1texinfo.texi(,2) @c Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $
2texinfo.texi(,3) @c Ordinarily Texinfo files have the extension .texi.  But texinfo.texi
3texinfo.texi(,4) @c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi.
4texinfo.texi(,5)
5texinfo.texi(,6) @c Everything between the start/end of header lines will be passed by
6texinfo.texi(,7) @c Emacs's {texinfo,makeinfo}-format region commands.  See the `start of
7texinfo.texi(,8) @c header' node for more info.
8texinfo.texi(,9) @c %**start of header
9texinfo.texi(,10)
10texinfo.texi(,11) @c makeinfo and texinfo.tex ignore all text before @setfilename.
11texinfo.texi(,12) @c
12texinfo.texi(,13) @c Ordinarily the setfilename argument ends with .info.  But
13texinfo.texi(,14) @c texinfo.info-13 is too long for 14-character filesystems.
14texinfo.texi(,15) @setfilename texinfo
15texinfo.texi(,16)
16texinfo.texi(,17) @c Automake automatically updates version.texi to @set VERSION and
17texinfo.texi(,18) @c @set UPDATED to appropriate values.
18version.texi(,1) @set UPDATED 28 March 2002
19version.texi(,2) @set UPDATED-MONTH March 2002
20version.texi(,3) @set EDITION 4.2
21version.texi(,4) @set VERSION 4.2
22texinfo.texi(,20) @settitle GNU Texinfo 4.2
23texinfo.texi(,21)
24texinfo.texi(,22) @c Define a new index for options.
25texinfo.texi(,23) @defcodeindex op
26texinfo.texi(,24) @c Put everything except function (command, in this case) names in one
27texinfo.texi(,25) @c index (arbitrarily chosen to be the concept index).
28texinfo.texi(,26) @syncodeindex op cp
29texinfo.texi(,27) @syncodeindex vr cp
30texinfo.texi(,28) @syncodeindex pg cp
31texinfo.texi(,29)
32texinfo.texi(,30) @footnotestyle separate
33texinfo.texi(,31) @paragraphindent 2
34texinfo.texi(,32) @c finalout
35texinfo.texi(,33)
36texinfo.texi(,34) @comment %**end of header
37texinfo.texi(,35)
38texinfo.texi(,36) @copying
39texinfo.texi(,37) This manual is for GNU Texinfo (version 4.2, 28 March 2002),
40texinfo.texi(,38) a documentation system that can produce both online information and a
41texinfo.texi(,39) printed manual from a single source.
42texinfo.texi(,40)
43texinfo.texi(,41) Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99, 2000, 01, 02
44texinfo.texi(,42) Free Software Foundation, Inc.
45texinfo.texi(,43)
46texinfo.texi(,44) @quotation
47texinfo.texi(,45) Permission is granted to copy, distribute and/or modify this document
48texinfo.texi(,46) under the terms of the GNU Free Documentation License, Version 1.1 or
49texinfo.texi(,47) any later version published by the Free Software Foundation; with no
50texinfo.texi(,48) Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
51texinfo.texi(,49) and with the Back-Cover Texts as in (a) below.  A copy of the license is
52texinfo.texi(,50) included in the section entitled ``GNU Free Documentation License.''
53texinfo.texi(,51)
54texinfo.texi(,52) (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
55texinfo.texi(,53) this GNU Manual, like GNU software.  Copies published by the Free
56texinfo.texi(,54) Software Foundation raise funds for GNU development.''
57texinfo.texi(,55) @end quotation
58texinfo.texi(,56) @end copying
59texinfo.texi(,57)
60texinfo.texi(,58) @dircategory Texinfo documentation system
61texinfo.texi(,59) @direntry
62texinfo.texi(,60) * Texinfo: (texinfo).           The GNU documentation format.
63texinfo.texi(,61) * install-info: (texinfo)Invoking install-info. Update info/dir entries.
64texinfo.texi(,62) * texi2dvi: (texinfo)Format with texi2dvi.      Print Texinfo documents.
65texinfo.texi(,63) * texindex: (texinfo)Format with tex/texindex.  Sort Texinfo index files.
66texinfo.texi(,64) * makeinfo: (texinfo)Invoking makeinfo.         Translate Texinfo source.
67texinfo.texi(,65) @end direntry
68texinfo.texi(,66)
69texinfo.texi(,67) @c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a
70texinfo.texi(,68) @c prefix arg).  This updates the node pointers, which texinfmt.el needs.
71texinfo.texi(,69)
72texinfo.texi(,70) @c Set smallbook if printing in smallbook format so the example of the
73texinfo.texi(,71) @c smallbook font is actually written using smallbook; in bigbook, a kludge
74texinfo.texi(,72) @c is used for TeX output.  Do this through the -t option to texi2dvi,
75texinfo.texi(,73) @c so this same source can be used for other paper sizes as well.
76texinfo.texi(,74) @c smallbook
77texinfo.texi(,75) @c set smallbook
78texinfo.texi(,76) @c @@clear smallbook
79texinfo.texi(,77)
80texinfo.texi(,78) @c If you like blank pages, add through texi2dvi -t.
81texinfo.texi(,79) @c setchapternewpage odd
82texinfo.texi(,80)
83texinfo.texi(,81) @c Currently undocumented command, 5 December 1993:
84texinfo.texi(,82) @c nwnode          (Same as node, but no warnings; for `makeinfo'.)
85texinfo.texi(,83)
86texinfo.texi(,84)
87texinfo.texi(,85) @shorttitlepage Texinfo
88texinfo.texi(,86)
89texinfo.texi(,87) @titlepage
90texinfo.texi(,88) @title Texinfo
91texinfo.texi(,89) @subtitle The GNU Documentation Format
92texinfo.texi(,90) @subtitle for Texinfo version 4.2, 28 March 2002
93texinfo.texi(,91)
94texinfo.texi(,92) @author Robert J. Chassell
95texinfo.texi(,93) @author Richard M. Stallman
96texinfo.texi(,94)
97texinfo.texi(,95) @c Include the Distribution inside the titlepage so
98texinfo.texi(,96) @c that headings are turned off.
99texinfo.texi(,97)
100texinfo.texi(,98) @page
101texinfo.texi(,99) @vskip 0pt plus 1filll
102texinfo.texi(,100) @insertcopying
103texinfo.texi(,101)
104texinfo.texi(,102) Published by the Free Software Foundation @*
105texinfo.texi(,103) 59 Temple Place Suite 330 @*
106texinfo.texi(,104) Boston, MA 02111-1307 @*
107texinfo.texi(,105) USA @*
108texinfo.texi(,106) ISBN 1-882114-67-1 @c for version 4.0, September 1999.
109texinfo.texi(,107) @c ISBN 1-882114-65-5 is for version 3.12, March 1998.
110texinfo.texi(,108) @c ISBN 1-882114-64-7 is for edition 2.24 of November 1996.
111texinfo.texi(,109) @c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995
112texinfo.texi(,110)
113texinfo.texi(,111) Cover art by Etienne Suvasa.
114texinfo.texi(,112) @end titlepage
115texinfo.texi(,113)
116texinfo.texi(,114)
117texinfo.texi(,115) @summarycontents
118texinfo.texi(,116) @contents
119texinfo.texi(,117)
120texinfo.texi(,118)
121texinfo.texi(,120) @node Top
122texinfo.texi(,121) @top Texinfo
123texinfo.texi(,122)
124texinfo.texi(,123) @insertcopying
125texinfo.texi(,124)
126texinfo.texi(,125) The first part of this master menu lists the major nodes in this Info
127texinfo.texi(,126) document, including the @@-command and concept indices.  The rest of
128texinfo.texi(,127) the menu lists all the lower level nodes in the document.
129texinfo.texi(,128)
130texinfo.texi(,130)
131texinfo.texi(,131) @menu
132texinfo.texi(,132) * Copying Conditions::          Your rights.
133texinfo.texi(,133) * Overview::                    Texinfo in brief.
134texinfo.texi(,134) * Texinfo Mode::                How to use Texinfo mode.
135texinfo.texi(,135) * Beginning a File::            What is at the beginning of a Texinfo file?
136texinfo.texi(,136) * Ending a File::               What is at the end of a Texinfo file?
137texinfo.texi(,137) * Structuring::                 How to create chapters, sections, subsections,
138texinfo.texi(,138)                                   appendices, and other parts.
139texinfo.texi(,139) * Nodes::                       How to write nodes.
140texinfo.texi(,140) * Menus::                       How to write menus.
141texinfo.texi(,141) * Cross References::            How to write cross references.
142texinfo.texi(,142) * Marking Text::                How to mark words and phrases as code,
143texinfo.texi(,143)                                   keyboard input, meta-syntactic
144texinfo.texi(,144)                                   variables, and the like.
145texinfo.texi(,145) * Quotations and Examples::     How to write quotations, examples, etc.
146texinfo.texi(,146) * Lists and Tables::            How to write lists and tables.
147texinfo.texi(,147) * Indices::                     How to create indices.
148texinfo.texi(,148) * Insertions::                  How to insert @@-signs, braces, etc.
149texinfo.texi(,149) * Breaks::                      How to force and prevent line and page breaks.
150texinfo.texi(,150) * Definition Commands::         How to describe functions and the like
151texinfo.texi(,151)                                   in a uniform manner.
152texinfo.texi(,152) * Conditionals::                How to specify text for either @TeX{} or Info.
153texinfo.texi(,153) * Internationalization::
154texinfo.texi(,154) * Defining New Texinfo Commands::
155texinfo.texi(,155) * Hardcopy::                    How to convert a Texinfo file to a file
156texinfo.texi(,156)                                   for printing and how to print that file.
157texinfo.texi(,157) * Creating and Installing Info Files::
158texinfo.texi(,158) * Command List::                All the Texinfo @@-commands.
159texinfo.texi(,159) * Tips::                        Hints on how to write a Texinfo document.
160texinfo.texi(,160) * Sample Texinfo Files::        Complete examples, including full texts.
161texinfo.texi(,161) * Include Files::               How to incorporate other Texinfo files.
162texinfo.texi(,162) * Headings::                    How to write page headings and footings.
163texinfo.texi(,163) * Catching Mistakes::           How to find formatting mistakes.
164texinfo.texi(,164) * Refilling Paragraphs::        All about paragraph refilling.
165texinfo.texi(,165) * Command Syntax::              A description of @@-Command syntax.
166texinfo.texi(,166) * Obtaining TeX::               How to Obtain @TeX{}.
167texinfo.texi(,167) * Copying This Manual::         The GNU Free Documentation License.
168texinfo.texi(,168) * Command and Variable Index::  A menu containing commands and variables.
169texinfo.texi(,169) * Concept Index::               A menu covering many topics.
170texinfo.texi(,170)
171texinfo.texi(,171) @detailmenu
172texinfo.texi(,172)  --- The Detailed Node Listing ---
173texinfo.texi(,173)
174texinfo.texi(,174) Overview of Texinfo
175texinfo.texi(,175)
176texinfo.texi(,176) * Reporting Bugs::              Submitting effective bug reports.
177texinfo.texi(,177) * Using Texinfo::               Create printed or online output.
178texinfo.texi(,178) * Info Files::                  What is an Info file?
179texinfo.texi(,179) * Printed Books::               Characteristics of a printed book or manual.
180texinfo.texi(,180) * Formatting Commands::         @@-commands are used for formatting.
181texinfo.texi(,181) * Conventions::                 General rules for writing a Texinfo file.
182texinfo.texi(,182) * Comments::                    Writing comments and ignored text in general.
183texinfo.texi(,183) * Minimum::                     What a Texinfo file must have.
184texinfo.texi(,184) * Six Parts::                   Usually, a Texinfo file has six parts.
185texinfo.texi(,185) * Short Sample::                A short sample Texinfo file.
186texinfo.texi(,186) * History::                     Acknowledgements, contributors and genesis.
187texinfo.texi(,187)
188texinfo.texi(,188) Using Texinfo Mode
189texinfo.texi(,189)
190texinfo.texi(,190) * Texinfo Mode Overview::       How Texinfo mode can help you.
191texinfo.texi(,191) * Emacs Editing::               Texinfo mode adds to GNU Emacs' general
192texinfo.texi(,192)                                   purpose editing features.
193texinfo.texi(,193) * Inserting::                   How to insert frequently used @@-commands.
194texinfo.texi(,194) * Showing the Structure::       How to show the structure of a file.
195texinfo.texi(,195) * Updating Nodes and Menus::    How to update or create new nodes and menus.
196texinfo.texi(,196) * Info Formatting::             How to format for Info.
197texinfo.texi(,197) * Printing::                    How to format and print part or all of a file.
198texinfo.texi(,198) * Texinfo Mode Summary::        Summary of all the Texinfo mode commands.
199texinfo.texi(,199)
200texinfo.texi(,200) Updating Nodes and Menus
201texinfo.texi(,201)
202texinfo.texi(,202) * Updating Commands::           Five major updating commands.
203texinfo.texi(,203) * Updating Requirements::       How to structure a Texinfo file for
204texinfo.texi(,204)                                   using the updating command.
205texinfo.texi(,205) * Other Updating Commands::     How to indent descriptions, insert
206texinfo.texi(,206)                                   missing nodes lines, and update
207texinfo.texi(,207)                                   nodes in sequence.
208texinfo.texi(,208)
209texinfo.texi(,209) Beginning a Texinfo File
210texinfo.texi(,210)
211texinfo.texi(,211) * Sample Beginning::            A sample beginning for a Texinfo file.
212texinfo.texi(,212) * Texinfo File Header::
213texinfo.texi(,213) * Document Permissions::
214texinfo.texi(,214) * Titlepage & Copyright Page::  Creating the title and copyright pages.
215texinfo.texi(,215) * The Top Node::                Creating the `Top' node and master menu.
216texinfo.texi(,216) * Global Document Commands::
217texinfo.texi(,217) * Software Copying Permissions::  Ensure that you and others continue to
218texinfo.texi(,218)                                     have the right to use and share software.
219texinfo.texi(,219)
220texinfo.texi(,220) Texinfo File Header
221texinfo.texi(,221)
222texinfo.texi(,222) * First Line::                  The first line of a Texinfo file.
223texinfo.texi(,223) * Start of Header::             Formatting a region requires this.
224texinfo.texi(,224) * setfilename::                 Tell Info the name of the Info file.
225texinfo.texi(,225) * settitle::                    Create a title for the printed work.
226texinfo.texi(,226) * End of Header::               Formatting a region requires this.
227texinfo.texi(,227)
228texinfo.texi(,228) Document Permissions
229texinfo.texi(,229)
230texinfo.texi(,230) * copying::                     Declare the document's copying permissions.
231texinfo.texi(,231) * insertcopying::               Where to insert the permissions.
232texinfo.texi(,232)
233texinfo.texi(,233) Title and Copyright Pages
234texinfo.texi(,234)
235texinfo.texi(,235) * titlepage::                   Create a title for the printed document.
236texinfo.texi(,236) * titlefont center sp::         The @code{@@titlefont}, @code{@@center},
237texinfo.texi(,237)                                   and @code{@@sp} commands.
238texinfo.texi(,238) * title subtitle author::       The @code{@@title}, @code{@@subtitle},
239texinfo.texi(,239)                                   and @code{@@author} commands.
240texinfo.texi(,240) * Copyright::                   How to write the copyright notice and
241texinfo.texi(,241)                                   include copying permissions.
242texinfo.texi(,242) * end titlepage::               Turn on page headings after the title and
243texinfo.texi(,243)                                   copyright pages.
244texinfo.texi(,244) * headings on off::             An option for turning headings on and off
245texinfo.texi(,245)                                   and double or single sided printing.
246texinfo.texi(,246)
247texinfo.texi(,247) The `Top' Node and Master Menu
248texinfo.texi(,248)
249texinfo.texi(,249) * Top Node Example::
250texinfo.texi(,250) * Master Menu Parts::
251texinfo.texi(,251)
252texinfo.texi(,252) Global Document Commands
253texinfo.texi(,253)
254texinfo.texi(,254) * documentdescription::         Document summary for the HTML output.
255texinfo.texi(,255) * setchapternewpage::           Start chapters on right-hand pages.
256texinfo.texi(,256) * paragraphindent::             Specify paragraph indentation.
257texinfo.texi(,257) * exampleindent::               Specify environment indentation.
258texinfo.texi(,258)
259texinfo.texi(,259) Ending a Texinfo File
260texinfo.texi(,260)
261texinfo.texi(,261) * Printing Indices & Menus::    How to print an index in hardcopy and
262texinfo.texi(,262)                                   generate index menus in Info.
263texinfo.texi(,263) * Contents::                    How to create a table of contents.
264texinfo.texi(,264) * File End::                    How to mark the end of a file.
265texinfo.texi(,265)
266texinfo.texi(,266) Chapter Structuring
267texinfo.texi(,267)
268texinfo.texi(,268) * Tree Structuring::            A manual is like an upside down tree @dots{}
269texinfo.texi(,269) * Structuring Command Types::   How to divide a manual into parts.
270texinfo.texi(,270) * makeinfo top::                The @code{@@top} command, part of the `Top' node.
271texinfo.texi(,271) * chapter::
272texinfo.texi(,272) * unnumbered & appendix::
273texinfo.texi(,273) * majorheading & chapheading::
274texinfo.texi(,274) * section::
275texinfo.texi(,275) * unnumberedsec appendixsec heading::
276texinfo.texi(,276) * subsection::
277texinfo.texi(,277) * unnumberedsubsec appendixsubsec subheading::
278texinfo.texi(,278) * subsubsection::               Commands for the lowest level sections.
279texinfo.texi(,279) * Raise/lower sections::        How to change commands' hierarchical level.
280texinfo.texi(,280)
281texinfo.texi(,281) Nodes
282texinfo.texi(,282)
283texinfo.texi(,283) * Two Paths::                   Different commands to structure
284texinfo.texi(,284)                                   Info output and printed output.
285texinfo.texi(,285) * Node Menu Illustration::      A diagram, and sample nodes and menus.
286texinfo.texi(,286) * node::                        Creating nodes, in detail.
287texinfo.texi(,287) * makeinfo Pointer Creation::   Letting makeinfo determine node pointers.
288texinfo.texi(,288) * anchor::                      Defining arbitrary cross-reference targets.
289texinfo.texi(,289)
290texinfo.texi(,290) The @code{@@node} Command
291texinfo.texi(,291)
292texinfo.texi(,292) * Node Names::                  How to choose node and pointer names.
293texinfo.texi(,293) * Writing a Node::              How to write an @code{@@node} line.
294texinfo.texi(,294) * Node Line Tips::              Keep names short.
295texinfo.texi(,295) * Node Line Requirements::      Keep names unique, without @@-commands.
296texinfo.texi(,296) * First Node::                  How to write a `Top' node.
297texinfo.texi(,297) * makeinfo top command::        How to use the @code{@@top} command.
298texinfo.texi(,298)
299texinfo.texi(,299) Menus
300texinfo.texi(,300)
301texinfo.texi(,301) * Menu Location::               Put a menu in a short node.
302texinfo.texi(,302) * Writing a Menu::              What is a menu?
303texinfo.texi(,303) * Menu Parts::                  A menu entry has three parts.
304texinfo.texi(,304) * Less Cluttered Menu Entry::   Two part menu entry.
305texinfo.texi(,305) * Menu Example::                Two and three part menu entries.
306texinfo.texi(,306) * Other Info Files::            How to refer to a different Info file.
307texinfo.texi(,307)
308texinfo.texi(,308) Cross References
309texinfo.texi(,309)
310texinfo.texi(,310) * References::                  What cross references are for.
311texinfo.texi(,311) * Cross Reference Commands::    A summary of the different commands.
312texinfo.texi(,312) * Cross Reference Parts::       A cross reference has several parts.
313texinfo.texi(,313) * xref::                        Begin a reference with `See' @dots{}
314texinfo.texi(,314) * Top Node Naming::             How to refer to the beginning of another file.
315texinfo.texi(,315) * ref::                         A reference for the last part of a sentence.
316texinfo.texi(,316) * pxref::                       How to write a parenthetical cross reference.
317texinfo.texi(,317) * inforef::                     How to refer to an Info-only file.
318texinfo.texi(,318) * uref::                        How to refer to a uniform resource locator.
319texinfo.texi(,319)
320texinfo.texi(,320) @code{@@xref}
321texinfo.texi(,321)
322texinfo.texi(,322) * Reference Syntax::            What a reference looks like and requires.
323texinfo.texi(,323) * One Argument::                @code{@@xref} with one argument.
324texinfo.texi(,324) * Two Arguments::               @code{@@xref} with two arguments.
325texinfo.texi(,325) * Three Arguments::             @code{@@xref} with three arguments.
326texinfo.texi(,326) * Four and Five Arguments::     @code{@@xref} with four and five arguments.
327texinfo.texi(,327)
328texinfo.texi(,328) Marking Words and Phrases
329texinfo.texi(,329)
330texinfo.texi(,330) * Indicating::                  How to indicate definitions, files, etc.
331texinfo.texi(,331) * Emphasis::                    How to emphasize text.
332texinfo.texi(,332)
333texinfo.texi(,333) Indicating Definitions, Commands, etc.
334texinfo.texi(,334)
335texinfo.texi(,335) * Useful Highlighting::         Highlighting provides useful information.
336texinfo.texi(,336) * code::                        Indicating program code.
337texinfo.texi(,337) * kbd::                         Showing keyboard input.
338texinfo.texi(,338) * key::                         Specifying keys.
339texinfo.texi(,339) * samp::                        A literal sequence of characters.
340texinfo.texi(,340) * verb::                        A verbatim sequence of characters.
341texinfo.texi(,341) * var::                         Indicating metasyntactic variables.
342texinfo.texi(,342) * env::                         Indicating environment variables.
343texinfo.texi(,343) * file::                        Indicating file names.
344texinfo.texi(,344) * command::                     Indicating command names.
345texinfo.texi(,345) * option::                      Indicating option names.
346texinfo.texi(,346) * dfn::                         Specifying definitions.
347texinfo.texi(,347) * cite::                        Referring to books not in the  Info system.
348texinfo.texi(,348) * acronym::                     Indicating acronyms.
349texinfo.texi(,349) * url::                         Indicating a World Wide Web reference.
350texinfo.texi(,350) * email::                       Indicating an electronic mail address.
351texinfo.texi(,351)
352texinfo.texi(,352) Emphasizing Text
353texinfo.texi(,353)
354texinfo.texi(,354) * emph & strong::               How to emphasize text in Texinfo.
355texinfo.texi(,355) * Smallcaps::                   How to use the small caps font.
356texinfo.texi(,356) * Fonts::                       Various font commands for printed output.
357texinfo.texi(,357)
358texinfo.texi(,358) Quotations and Examples
359texinfo.texi(,359)
360texinfo.texi(,360) * Block Enclosing Commands::    Different constructs for different purposes.
361texinfo.texi(,361) * quotation::                   Writing a quotation.
362texinfo.texi(,362) * example::                     Writing an example in a fixed-width font.
363texinfo.texi(,363) * verbatim::                    Writing a verbatim example.
364texinfo.texi(,364) * verbatiminclude::             Including a file verbatim.
365texinfo.texi(,365) * lisp::                        Illustrating Lisp code.
366texinfo.texi(,366) * small::                       Forms for @code{@@smallbook}.
367texinfo.texi(,367) * display::                     Writing an example in the current font.
368texinfo.texi(,368) * format::                      Writing an example without narrowed margins.
369texinfo.texi(,369) * exdent::                      Undo indentation on a line.
370texinfo.texi(,370) * flushleft & flushright::      Pushing text flush left or flush right.
371texinfo.texi(,371) * noindent::                    Preventing paragraph indentation.
372texinfo.texi(,372) * cartouche::                   Drawing rounded rectangles around examples.
373texinfo.texi(,373)
374texinfo.texi(,374) Lists and Tables
375texinfo.texi(,375)
376texinfo.texi(,376) * Introducing Lists::           Texinfo formats lists for you.
377texinfo.texi(,377) * itemize::                     How to construct a simple list.
378texinfo.texi(,378) * enumerate::                   How to construct a numbered list.
379texinfo.texi(,379) * Two-column Tables::           How to construct a two-column table.
380texinfo.texi(,380) * Multi-column Tables::         How to construct generalized tables.
381texinfo.texi(,381)
382texinfo.texi(,382) Making a Two-column Table
383texinfo.texi(,383)
384texinfo.texi(,384) * table::                       How to construct a two-column table.
385texinfo.texi(,385) * ftable vtable::               Automatic indexing for two-column tables.
386texinfo.texi(,386) * itemx::                       How to put more entries in the first column.
387texinfo.texi(,387)
388texinfo.texi(,388) Multi-column Tables
389texinfo.texi(,389)
390texinfo.texi(,390) * Multitable Column Widths::    Defining multitable column widths.
391texinfo.texi(,391) * Multitable Rows::             Defining multitable rows, with examples.
392texinfo.texi(,392)
393texinfo.texi(,393) Indices
394texinfo.texi(,394)
395texinfo.texi(,395) * Index Entries::               Choose different words for index entries.
396texinfo.texi(,396) * Predefined Indices::          Use different indices for different kinds
397texinfo.texi(,397)                                   of entry.
398texinfo.texi(,398) * Indexing Commands::           How to make an index entry.
399texinfo.texi(,399) * Combining Indices::           How to combine indices.
400texinfo.texi(,400) * New Indices::                 How to define your own indices.
401texinfo.texi(,401)
402texinfo.texi(,402) Combining Indices
403texinfo.texi(,403)
404texinfo.texi(,404) * syncodeindex::                How to merge two indices, using @code{@@code}
405texinfo.texi(,405)                                   font for the merged-from index.
406texinfo.texi(,406) * synindex::                    How to merge two indices, using the
407texinfo.texi(,407)                                   default font of the merged-to index.
408texinfo.texi(,408)
409texinfo.texi(,409) Special Insertions
410texinfo.texi(,410)
411texinfo.texi(,411) * Braces Atsigns::              How to insert braces, @samp{@@}.
412texinfo.texi(,412) * Inserting Space::             How to insert the right amount of space
413texinfo.texi(,413)                                   within a sentence.
414texinfo.texi(,414) * Inserting Accents::           How to insert accents and special characters.
415texinfo.texi(,415) * Dots Bullets::                How to insert dots and bullets.
416texinfo.texi(,416) * TeX and copyright::           How to insert the @TeX{} logo
417texinfo.texi(,417)                                   and the copyright symbol.
418texinfo.texi(,418) * pounds::                      How to insert the pounds currency symbol.
419texinfo.texi(,419) * minus::                       How to insert a minus sign.
420texinfo.texi(,420) * math::                        How to format a mathematical expression.
421texinfo.texi(,421) * Glyphs::                      How to indicate results of evaluation,
422texinfo.texi(,422)                                   expansion of macros, errors, etc.
423texinfo.texi(,423) * Footnotes::                   How to include footnotes.
424texinfo.texi(,424) * Images::                      How to include graphics.
425texinfo.texi(,425)
426texinfo.texi(,426) Inserting @@ and Braces
427texinfo.texi(,427)
428texinfo.texi(,428) * Inserting An Atsign::         How to insert @samp{@@}.
429texinfo.texi(,429) * Inserting Braces::            How to insert @samp{@{} and @samp{@}}.
430texinfo.texi(,430)
431texinfo.texi(,431) Inserting Space
432texinfo.texi(,432)
433texinfo.texi(,433) * Not Ending a Sentence::       Sometimes a . doesn't end a sentence.
434texinfo.texi(,434) * Ending a Sentence::           Sometimes it does.
435texinfo.texi(,435) * Multiple Spaces::             Inserting multiple spaces.
436texinfo.texi(,436) * dmn::                         How to format a dimension.
437texinfo.texi(,437)
438texinfo.texi(,438) Inserting Ellipsis and Bullets
439texinfo.texi(,439)
440texinfo.texi(,440) * dots::                        How to insert dots @dots{}
441texinfo.texi(,441) * bullet::                      How to insert a bullet.
442texinfo.texi(,442)
443texinfo.texi(,443) Inserting @TeX{} and the Copyright Symbol
444texinfo.texi(,444)
445texinfo.texi(,445) * tex::                         How to insert the @TeX{} logo.
446texinfo.texi(,446) * copyright symbol::            How to use @code{@@copyright}@{@}.
447texinfo.texi(,447)
448texinfo.texi(,448) Glyphs for Examples
449texinfo.texi(,449)
450texinfo.texi(,450) * Glyphs Summary::
451texinfo.texi(,451) * result::                      How to show the result of expression.
452texinfo.texi(,452) * expansion::                   How to indicate an expansion.
453texinfo.texi(,453) * Print Glyph::                 How to indicate printed output.
454texinfo.texi(,454) * Error Glyph::                 How to indicate an error message.
455texinfo.texi(,455) * Equivalence::                 How to indicate equivalence.
456texinfo.texi(,456) * Point Glyph::                 How to indicate the location of point.
457texinfo.texi(,457)
458texinfo.texi(,458) Glyphs Summary
459texinfo.texi(,459)
460texinfo.texi(,460) * result::
461texinfo.texi(,461) * expansion::
462texinfo.texi(,462) * Print Glyph::
463texinfo.texi(,463) * Error Glyph::
464texinfo.texi(,464) * Equivalence::
465texinfo.texi(,465) * Point Glyph::
466texinfo.texi(,466)
467texinfo.texi(,467) Footnotes
468texinfo.texi(,468)
469texinfo.texi(,469) * Footnote Commands::           How to write a footnote in Texinfo.
470texinfo.texi(,470) * Footnote Styles::             Controlling how footnotes appear in Info.
471texinfo.texi(,471)
472texinfo.texi(,472) Making and Preventing Breaks
473texinfo.texi(,473)
474texinfo.texi(,474) * Break Commands::              Cause and prevent splits.
475texinfo.texi(,475) * Line Breaks::                 How to force a single line to use two lines.
476texinfo.texi(,476) * - and hyphenation::           How to tell @TeX{} about hyphenation points.
477texinfo.texi(,477) * w::                           How to prevent unwanted line breaks.
478texinfo.texi(,478) * sp::                          How to insert blank lines.
479texinfo.texi(,479) * page::                        How to force the start of a new page.
480texinfo.texi(,480) * group::                       How to prevent unwanted page breaks.
481texinfo.texi(,481) * need::                        Another way to prevent unwanted page breaks.
482texinfo.texi(,482)
483texinfo.texi(,483) Definition Commands
484texinfo.texi(,484)
485texinfo.texi(,485) * Def Cmd Template::            How to structure a description using a
486texinfo.texi(,486)                                   definition command.
487texinfo.texi(,487) * Optional Arguments::          How to handle optional and repeated arguments.
488texinfo.texi(,488) * deffnx::                      How to group two or more `first' lines.
489texinfo.texi(,489) * Def Cmds in Detail::          All the definition commands.
490texinfo.texi(,490) * Def Cmd Conventions::         Conventions for writing definitions.
491texinfo.texi(,491) * Sample Function Definition::
492texinfo.texi(,492)
493texinfo.texi(,493) The Definition Commands
494texinfo.texi(,494)
495texinfo.texi(,495) * Functions Commands::          Commands for functions and similar entities.
496texinfo.texi(,496) * Variables Commands::          Commands for variables and similar entities.
497texinfo.texi(,497) * Typed Functions::             Commands for functions in typed languages.
498texinfo.texi(,498) * Typed Variables::             Commands for variables in typed languages.
499texinfo.texi(,499) * Abstract Objects::            Commands for object-oriented programming.
500texinfo.texi(,500) * Data Types::                  The definition command for data types.
501texinfo.texi(,501)
502texinfo.texi(,502) Conditionally Visible Text
503texinfo.texi(,503)
504texinfo.texi(,504) * Conditional Commands::        Specifying text for HTML, Info, or @TeX{}.
505texinfo.texi(,505) * Conditional Not Commands::    Specifying text for not HTML, Info, or @TeX{}.
506texinfo.texi(,506) * Raw Formatter Commands::      Using raw @TeX{} or HTML commands.
507texinfo.texi(,507) * set clear value::             Designating which text to format (for
508texinfo.texi(,508)                                   all output formats); and how to set a
509texinfo.texi(,509)                                   flag to a string that you can insert.
510texinfo.texi(,510)
511texinfo.texi(,511) @code{@@set}, @code{@@clear}, and @code{@@value}
512texinfo.texi(,512)
513texinfo.texi(,513) * set value::                   Expand a flag variable to a string.
514texinfo.texi(,514) * ifset ifclear::               Format a region if a flag is set.
515texinfo.texi(,515) * value Example::               An easy way to update edition information.
516texinfo.texi(,516)
517texinfo.texi(,517) Internationalization
518texinfo.texi(,518)
519texinfo.texi(,519) * documentlanguage::            Declaring the current language.
520texinfo.texi(,520) * documentencoding::            Declaring the input encoding.
521texinfo.texi(,521)
522texinfo.texi(,522) Defining New Texinfo Commands
523texinfo.texi(,523)
524texinfo.texi(,524) * Defining Macros::             Defining and undefining new commands.
525texinfo.texi(,525) * Invoking Macros::             Using a macro, once you've defined it.
526texinfo.texi(,526) * Macro Details::               Beyond basic macro usage.
527texinfo.texi(,527) * alias::                       Command aliases.
528texinfo.texi(,528) * definfoenclose::              Customized highlighting.
529texinfo.texi(,529)
530texinfo.texi(,530) Formatting and Printing Hardcopy
531texinfo.texi(,531)
532texinfo.texi(,532) * Use TeX::                     Use @TeX{} to format for hardcopy.
533texinfo.texi(,533) * Format with tex/texindex::    How to format with explicit shell commands.
534texinfo.texi(,534) * Format with texi2dvi::        A simpler way to format.
535texinfo.texi(,535) * Print with lpr::              How to print.
536texinfo.texi(,536) * Within Emacs::                How to format and print from an Emacs shell.
537texinfo.texi(,537) * Texinfo Mode Printing::       How to format and print in Texinfo mode.
538texinfo.texi(,538) * Compile-Command::             How to print using Emacs's compile command.
539texinfo.texi(,539) * Requirements Summary::        @TeX{} formatting requirements summary.
540texinfo.texi(,540) * Preparing for TeX::           What to do before you use @TeX{}.
541texinfo.texi(,541) * Overfull hboxes::             What are and what to do with overfull hboxes.
542texinfo.texi(,542) * smallbook::                   How to print small format books and manuals.
543texinfo.texi(,543) * A4 Paper::                    How to print on A4 or A5 paper.
544texinfo.texi(,544) * pagesizes::                   How to print with customized page sizes.
545texinfo.texi(,545) * Cropmarks and Magnification::  How to print marks to indicate the size
546texinfo.texi(,546)                                 of pages and how to print scaled up output.
547texinfo.texi(,547) * PDF Output::                  Portable Document Format output.
548texinfo.texi(,548)
549texinfo.texi(,549) Creating and Installing Info Files
550texinfo.texi(,550)
551texinfo.texi(,551) * Creating an Info File::
552texinfo.texi(,552) * Installing an Info File::
553texinfo.texi(,553)
554texinfo.texi(,554) Creating an Info File
555texinfo.texi(,555)
556texinfo.texi(,556) * makeinfo advantages::         @code{makeinfo} provides better error checking.
557texinfo.texi(,557) * Invoking makeinfo::           How to run @code{makeinfo} from a shell.
558texinfo.texi(,558) * makeinfo options::            Specify fill-column and other options.
559texinfo.texi(,559) * Pointer Validation::          How to check that pointers point somewhere.
560texinfo.texi(,560) * makeinfo in Emacs::           How to run @code{makeinfo} from Emacs.
561texinfo.texi(,561) * texinfo-format commands::     Two Info formatting commands written
562texinfo.texi(,562)                                   in Emacs Lisp are an alternative
563texinfo.texi(,563)                                   to @code{makeinfo}.
564texinfo.texi(,564) * Batch Formatting::            How to format for Info in Emacs Batch mode.
565texinfo.texi(,565) * Tag and Split Files::         How tagged and split files help Info
566texinfo.texi(,566)                                   to run better.
567texinfo.texi(,567) * makeinfo html::               Generating HTML output.
568texinfo.texi(,568)
569texinfo.texi(,569) Installing an Info File
570texinfo.texi(,570)
571texinfo.texi(,571) * Directory File::              The top level menu for all Info files.
572texinfo.texi(,572) * New Info File::               Listing a new Info file.
573texinfo.texi(,573) * Other Info Directories::      How to specify Info files that are
574texinfo.texi(,574)                                   located in other directories.
575texinfo.texi(,575) * Installing Dir Entries::      How to specify what menu entry to add
576texinfo.texi(,576)                                   to the Info directory.
577texinfo.texi(,577) * Invoking install-info::       @code{install-info} options.
578texinfo.texi(,578)
579texinfo.texi(,579) Sample Texinfo Files
580texinfo.texi(,580)
581texinfo.texi(,581) * Short Sample Texinfo File::
582texinfo.texi(,582) * GNU Sample Texts::
583texinfo.texi(,583)
584texinfo.texi(,584) Include Files
585texinfo.texi(,585)
586texinfo.texi(,586) * Using Include Files::         How to use the @code{@@include} command.
587texinfo.texi(,587) * texinfo-multiple-files-update::  How to create and update nodes and
588texinfo.texi(,588)                                   menus when using included files.
589texinfo.texi(,589) * Include File Requirements::   What @code{texinfo-multiple-files-update} expects.
590texinfo.texi(,590) * Sample Include File::         A sample outer file with included files
591texinfo.texi(,591)                                   within it; and a sample included file.
592texinfo.texi(,592) * Include Files Evolution::     How use of the @code{@@include} command
593texinfo.texi(,593)                                   has changed over time.
594texinfo.texi(,594)
595texinfo.texi(,595) Page Headings
596texinfo.texi(,596)
597texinfo.texi(,597) * Headings Introduced::         Conventions for using page headings.
598texinfo.texi(,598) * Heading Format::              Standard page heading formats.
599texinfo.texi(,599) * Heading Choice::              How to specify the type of page heading.
600texinfo.texi(,600) * Custom Headings::             How to create your own headings and footings.
601texinfo.texi(,601)
602texinfo.texi(,602) Formatting Mistakes
603texinfo.texi(,603)
604texinfo.texi(,604) * makeinfo Preferred::          @code{makeinfo} finds errors.
605texinfo.texi(,605) * Debugging with Info::         How to catch errors with Info formatting.
606texinfo.texi(,606) * Debugging with TeX::          How to catch errors with @TeX{} formatting.
607texinfo.texi(,607) * Using texinfo-show-structure::  How to use @code{texinfo-show-structure}.
608texinfo.texi(,608) * Using occur::                 How to list all lines containing a pattern.
609texinfo.texi(,609) * Running Info-Validate::       How to find badly referenced nodes.
610texinfo.texi(,610)
611texinfo.texi(,611) Finding Badly Referenced Nodes
612texinfo.texi(,612)
613texinfo.texi(,613) * Using Info-validate::         How to run @code{Info-validate}.
614texinfo.texi(,614) * Unsplit::                     How to create an unsplit file.
615texinfo.texi(,615) * Tagifying::                   How to tagify a file.
616texinfo.texi(,616) * Splitting::                   How to split a file manually.
617texinfo.texi(,617)
618texinfo.texi(,618) Copying This Manual
619texinfo.texi(,619)
620texinfo.texi(,620) * GNU Free Documentation License::  License for copying this manual.
621texinfo.texi(,621)
622texinfo.texi(,622) @end detailmenu
623texinfo.texi(,623) @end menu
624texinfo.texi(,624)
625texinfo.texi(,625) @c Reward readers for getting to the end of the menu :).
626texinfo.texi(,626) @c Contributed by Arnold Robbins.
627texinfo.texi(,627) @quotation
628texinfo.texi(,628) Documentation is like sex: when it is good, it is very, very good; and
629texinfo.texi(,629) when it is bad, it is better than nothing.
630texinfo.texi(,630) ---Dick Brandon
631texinfo.texi(,631) @end quotation
632texinfo.texi(,632)
633texinfo.texi(,633)
634texinfo.texi(,634) @node Copying Conditions
635texinfo.texi(,635) @unnumbered Texinfo Copying Conditions
636texinfo.texi(,636) @cindex Copying conditions
637texinfo.texi(,637) @cindex Conditions for copying Texinfo
638texinfo.texi(,638)
639texinfo.texi(,639) The programs currently being distributed that relate to Texinfo include
640texinfo.texi(,640) @code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}.
641texinfo.texi(,641) These programs are @dfn{free}; this means that everyone is free to use
642texinfo.texi(,642) them and free to redistribute them on a free basis.  The Texinfo-related
643texinfo.texi(,643) programs are not in the public domain; they are copyrighted and there
644texinfo.texi(,644) are restrictions on their distribution, but these restrictions are
645texinfo.texi(,645) designed to permit everything that a good cooperating citizen would want
646texinfo.texi(,646) to do.  What is not allowed is to try to prevent others from further
647texinfo.texi(,647) sharing any version of these programs that they might get from you.
648texinfo.texi(,648)
649texinfo.texi(,649) Specifically, we want to make sure that you have the right to give away
650texinfo.texi(,650) copies of the programs that relate to Texinfo, that you receive source
651texinfo.texi(,651) code or else can get it if you want it, that you can change these
652texinfo.texi(,652) programs or use pieces of them in new free programs, and that you know
653texinfo.texi(,653) you can do these things.
654texinfo.texi(,654)
655texinfo.texi(,655) To make sure that everyone has such rights, we have to forbid you to
656texinfo.texi(,656) deprive anyone else of these rights.  For example, if you distribute
657texinfo.texi(,657) copies of the Texinfo related programs, you must give the recipients all
658texinfo.texi(,658) the rights that you have.  You must make sure that they, too, receive or
659texinfo.texi(,659) can get the source code.  And you must tell them their rights.
660texinfo.texi(,660)
661texinfo.texi(,661) Also, for our own protection, we must make certain that everyone finds
662texinfo.texi(,662) out that there is no warranty for the programs that relate to Texinfo.
663texinfo.texi(,663) If these programs are modified by someone else and passed on, we want
664texinfo.texi(,664) their recipients to know that what they have is not what we distributed,
665texinfo.texi(,665) so that any problems introduced by others will not reflect on our
666texinfo.texi(,666) reputation.
667texinfo.texi(,667)
668texinfo.texi(,668) The precise conditions of the licenses for the programs currently being
669texinfo.texi(,669) distributed that relate to Texinfo are found in the General Public
670texinfo.texi(,670) Licenses that accompany them.  This manual specifically is covered by
671texinfo.texi(,671) the GNU Free Documentation License (@pxref{GNU Free Documentation
672texinfo.texi(,672) License}).
673texinfo.texi(,673)
674texinfo.texi(,674)
675texinfo.texi(,675) @node Overview
676texinfo.texi(,676) @chapter Overview of Texinfo
677texinfo.texi(,677) @cindex Overview of Texinfo
678texinfo.texi(,678) @cindex Texinfo overview
679texinfo.texi(,679)
680texinfo.texi(,680) @dfn{Texinfo}@footnote{The first syllable of ``Texinfo'' is pronounced
681texinfo.texi(,681) like ``speck'', not ``hex''.  This odd pronunciation is derived from,
682texinfo.texi(,682) but is not the same as, the pronunciation of @TeX{}.  In the word
683texinfo.texi(,683) @TeX{}, the @samp{X} is actually the Greek letter ``chi'' rather than
684texinfo.texi(,684) the English letter ``ex''.  Pronounce @TeX{} as if the @samp{X} were the
685texinfo.texi(,685) last sound in the name `Bach'; but pronounce Texinfo as if the @samp{x}
686texinfo.texi(,686) were a `k'.  Spell ``Texinfo'' with a capital ``T'' and the other
687texinfo.texi(,687) letters in lower case.}  is a documentation system that uses a single
688texinfo.texi(,688) source file to produce both online information and printed output.  This
689texinfo.texi(,689) means that instead of writing two different documents, one for the
690texinfo.texi(,690) online information and the other for a printed work, you need write only
691texinfo.texi(,691) one document.  Therefore, when the work is revised, you need revise only
692texinfo.texi(,692) that one document.
693texinfo.texi(,693)
694texinfo.texi(,694) @menu
695texinfo.texi(,695) * Reporting Bugs::              Submitting effective bug reports.
696texinfo.texi(,696) * Using Texinfo::               Create printed or online output.
697texinfo.texi(,697) * Info Files::                  What is an Info file?
698texinfo.texi(,698) * Printed Books::               Characteristics of a printed book or manual.
699texinfo.texi(,699) * Formatting Commands::         @@-commands are used for formatting.
700texinfo.texi(,700) * Conventions::                 General rules for writing a Texinfo file.
701texinfo.texi(,701) * Comments::                    Writing comments and ignored text in general.
702texinfo.texi(,702) * Minimum::                     What a Texinfo file must have.
703texinfo.texi(,703) * Six Parts::                   Usually, a Texinfo file has six parts.
704texinfo.texi(,704) * Short Sample::                A short sample Texinfo file.
705texinfo.texi(,705) * History::                     Acknowledgements, contributors and genesis.
706texinfo.texi(,706) @end menu
707texinfo.texi(,707)
708texinfo.texi(,708)
709texinfo.texi(,709) @node Reporting Bugs
710texinfo.texi(,710) @section Reporting Bugs
711texinfo.texi(,711)
712texinfo.texi(,712) @cindex Bugs, reporting
713texinfo.texi(,713) @cindex Suggestions for Texinfo, making
714texinfo.texi(,714) @cindex Reporting bugs
715texinfo.texi(,715) We welcome bug reports and suggestions for any aspect of the Texinfo system,
716texinfo.texi(,716) programs, documentation, installation, anything.  Please email them to
717texinfo.texi(,717) @email{bug-texinfo@@gnu.org}.  You can get the latest version of Texinfo
718texinfo.texi(,718) from @uref{ftp://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide.
719texinfo.texi(,719)
720texinfo.texi(,720) @cindex Checklist for bug reports
721texinfo.texi(,721) For bug reports, please include enough information for the maintainers
722texinfo.texi(,722) to reproduce the problem.  Generally speaking, that means:
723texinfo.texi(,723)
724texinfo.texi(,724) @itemize @bullet
725texinfo.texi(,725) @item the version number of Texinfo and the program(s) or manual(s) involved.
726texinfo.texi(,726) @item hardware and operating system names and versions.
727texinfo.texi(,727) @item the contents of any input files necessary to reproduce the bug.
728texinfo.texi(,728) @item a description of the problem and samples of any erroneous output.
729texinfo.texi(,729) @item any unusual options you gave to @command{configure}.
730texinfo.texi(,730) @item anything else that you think would be helpful.
731texinfo.texi(,731) @end itemize
732texinfo.texi(,732)
733texinfo.texi(,733) When in doubt whether something is needed or not, include it.  It's
734texinfo.texi(,734) better to include too much than to leave out something important.
735texinfo.texi(,735)
736texinfo.texi(,736) @cindex Patches, contributing
737texinfo.texi(,737) Patches are most welcome; if possible, please make them with
738texinfo.texi(,738) @samp{@w{diff -c}} (@pxref{Top,, Overview, diffutils, Comparing and
739texinfo.texi(,739) Merging Files}) and include @file{ChangeLog} entries (@pxref{Change
740texinfo.texi(,740) Log,,, emacs, The GNU Emacs Manual}).
741texinfo.texi(,741)
742texinfo.texi(,742) When sending patches, if possible please do not encode or split them in
743texinfo.texi(,743) any way; it's much easier to deal with one plain text message, however
744texinfo.texi(,744) large, than many small ones.  @uref{ftp://ftp.gnu.org/gnu/sharutils/,
745texinfo.texi(,745) GNU shar} is a convenient way of packaging multiple and/or binary files
746texinfo.texi(,746) for email.
747texinfo.texi(,747)
748texinfo.texi(,748)
749texinfo.texi(,749) @node Using Texinfo
750texinfo.texi(,750) @section Using Texinfo
751texinfo.texi(,751)
752texinfo.texi(,752) @cindex Using Texinfo in general
753texinfo.texi(,753) @cindex Texinfo, introduction to
754texinfo.texi(,754) @cindex Introduction to Texinfo
755texinfo.texi(,755)
756texinfo.texi(,756) Using Texinfo, you can create a printed document with the normal
757texinfo.texi(,757) features of a book, including chapters, sections, cross references, and
758texinfo.texi(,758) indices.  From the same Texinfo source file, you can create a
759texinfo.texi(,759) menu-driven, online Info file with nodes, menus, cross references, and
760texinfo.texi(,760) indices.  You can also create from that same source file an HTML output
761texinfo.texi(,761) file suitable for use with a web browser, or an XML file.  @cite{The GNU
762texinfo.texi(,762) Emacs Manual} is a good example of a Texinfo file, as is this manual.
763texinfo.texi(,763)
764texinfo.texi(,764) To make a printed document, you process a Texinfo source file with the
765texinfo.texi(,765) @TeX{} typesetting program (but the Texinfo language is very different
766texinfo.texi(,766) and much stricter than @TeX{}'s usual language, plain @TeX{}).  This
767texinfo.texi(,767) creates a DVI file that you can typeset and print as a book or report
768texinfo.texi(,768) (@pxref{Hardcopy}).
769texinfo.texi(,769)
770texinfo.texi(,770) @pindex makeinfo
771texinfo.texi(,771) To output an Info file, process your Texinfo source with the
772texinfo.texi(,772) @code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command.
773texinfo.texi(,773) You can install the result in your Info tree (@pxref{Installing an Info
774texinfo.texi(,774) File}).
775texinfo.texi(,775)
776texinfo.texi(,776) To output an HTML file, run @code{makeinfo --html} on your Texinfo
777texinfo.texi(,777) source.  You can (for example) install the result on your web site.
778texinfo.texi(,778)
779texinfo.texi(,779) @cindex Docbook, converting to Texinfo
780texinfo.texi(,780) @cindex Conversion, from Docbook to Texinfo
781texinfo.texi(,781) To output an XML file, run @code{makeinfo --xml} on your Texinfo source.
782texinfo.texi(,782) To output DocBook (a particular form of XML), run @code{makeinfo
783texinfo.texi(,783) --docbook}.  If you want to convert from Docbook @emph{to} Texinfo,
784texinfo.texi(,784) please see @uref{http://docbook2X.sourceforge.net/}.
785texinfo.texi(,785)
786texinfo.texi(,786) @cindex Output formats, supporting more
787texinfo.texi(,787) @cindex SGML-tools output format
788texinfo.texi(,788) If you are a programmer and would like to contribute to the GNU project
789texinfo.texi(,789) by implementing additional output formats for Texinfo, that would be
790texinfo.texi(,790) excellent.  But please do not write a separate translator texi2foo for
791texinfo.texi(,791) your favorite format foo!  That is the hard way to do the job, and makes
792texinfo.texi(,792) extra work in subsequent maintenance, since the Texinfo language is
793texinfo.texi(,793) continually being enhanced and updated.  Instead, the best approach is
794texinfo.texi(,794) modify @code{makeinfo} to generate the new format, as it does now for
795texinfo.texi(,795) Info, plain text, HTML, XML, and DocBook.
796texinfo.texi(,796)
797texinfo.texi(,797) @TeX{} works with virtually all printers; Info works with virtually all
798texinfo.texi(,798) computer terminals; the HTML output works with virtually all web
799texinfo.texi(,799) browsers.  Thus Texinfo can be used by almost any computer user.
800texinfo.texi(,800)
801texinfo.texi(,801) @cindex Source file
802texinfo.texi(,802) A Texinfo source file is a plain @sc{ascii} file containing text and
803texinfo.texi(,803) @dfn{@@-commands} (words preceded by an @samp{@@}) that tell the
804texinfo.texi(,804) typesetting and formatting programs what to do.  You may edit a Texinfo
805texinfo.texi(,805) file with any text editor; but it is especially convenient to use GNU
806texinfo.texi(,806) Emacs since that editor has a special mode, called Texinfo mode, that
807texinfo.texi(,807) provides various Texinfo-related features.  (@xref{Texinfo Mode}.)
808texinfo.texi(,808)
809texinfo.texi(,809) Before writing a Texinfo source file, you should learn about nodes,
810texinfo.texi(,810) menus, cross references, and the rest, for example by reading this
811texinfo.texi(,811) manual.
812texinfo.texi(,812)
813texinfo.texi(,813) You can use Texinfo to create both online help and printed manuals;
814texinfo.texi(,814) moreover, Texinfo is freely redistributable.  For these reasons, Texinfo
815texinfo.texi(,815) is the official documentation format of the GNU project.  More
816texinfo.texi(,816) information is available at the @uref{http://www.gnu.org/doc/, GNU
817texinfo.texi(,817) documentation web page}.
818texinfo.texi(,818)
819texinfo.texi(,819) @cindex Man page output, not supported
820texinfo.texi(,820) From time to time, proposals are made to generate traditional Unix man
821texinfo.texi(,821) pages from Texinfo source.  This is not likely to ever be supported,
822texinfo.texi(,822) because man pages have a very strict conventional format.  Merely
823texinfo.texi(,823) enhancing @command{makeinfo} to output troff format would be
824texinfo.texi(,824) insufficient.  Generating a good man page therefore requires a
825texinfo.texi(,825) completely different source than the typical Texinfo applications of
826texinfo.texi(,826) writing a good user tutorial or a good reference manual.  This makes
827texinfo.texi(,827) generating man pages incompatible with the Texinfo design goal of not
828texinfo.texi(,828) having to document the same information in different ways for different
829texinfo.texi(,829) output formats.  You might as well just write the man page directly.
830texinfo.texi(,830)
831texinfo.texi(,831) @pindex help2man
832texinfo.texi(,832) @cindex O'Dea, Brendan
833texinfo.texi(,833) Man pages still have their place, and if you wish to support them, the
834texinfo.texi(,834) program @command{help2man} may be useful; it generates a traditional man
835texinfo.texi(,835) page from the @samp{--help} output of a program.  In fact, this is
836texinfo.texi(,836) currently used to generate man pages for the Texinfo programs
837texinfo.texi(,837) themselves.  It is GNU software written by Brendan O'Dea, available from
838texinfo.texi(,838) @uref{ftp://ftp.gnu.org/gnu/help2man/}.
839texinfo.texi(,839)
840texinfo.texi(,840)
841texinfo.texi(,841) @node Info Files
842texinfo.texi(,842) @section Info files
843texinfo.texi(,843) @cindex Info files
844texinfo.texi(,844)
845texinfo.texi(,845) An Info file is a Texinfo file formatted so that the Info documentation
846texinfo.texi(,846) reading program can operate on it.  (@code{makeinfo}
847texinfo.texi(,847) and @code{texinfo-format-buffer} are two commands that convert a Texinfo file
848texinfo.texi(,848) into an Info file.)
849texinfo.texi(,849)
850texinfo.texi(,850) Info files are divided into pieces called @dfn{nodes}, each of which
851texinfo.texi(,851) contains the discussion of one topic.  Each node has a name, and
852texinfo.texi(,852) contains both text for the user to read and pointers to other nodes,
853texinfo.texi(,853) which are identified by their names.  The Info program displays one node
854texinfo.texi(,854) at a time, and provides commands with which the user can move to other
855texinfo.texi(,855) related nodes.
856texinfo.texi(,856)
857texinfo.texi(,858) @inforef{Top, info, info}, for more information about using Info.
858texinfo.texi(,860)
859texinfo.texi(,861) Each node of an Info file may have any number of child nodes that
860texinfo.texi(,862) describe subtopics of the node's topic.  The names of child
861texinfo.texi(,863) nodes are listed in a @dfn{menu} within the parent node; this
862texinfo.texi(,864) allows you to use certain Info commands to move to one of the child
863texinfo.texi(,865) nodes.  Generally, an Info file is organized like a book.  If a node
864texinfo.texi(,866) is at the logical level of a chapter, its child nodes are at the level
865texinfo.texi(,867) of sections; likewise, the child nodes of sections are at the level
866texinfo.texi(,868) of subsections.
867texinfo.texi(,869)
868texinfo.texi(,870) All the children of any one parent are linked together in a
869texinfo.texi(,871) bidirectional chain of `Next' and `Previous' pointers.  The `Next'
870texinfo.texi(,872) pointer provides a link to the next section, and the `Previous' pointer
871texinfo.texi(,873) provides a link to the previous section.  This means that all the nodes
872texinfo.texi(,874) that are at the level of sections within a chapter are linked together.
873texinfo.texi(,875) Normally the order in this chain is the same as the order of the
874texinfo.texi(,876) children in the parent's menu.  Each child node records the parent node
875texinfo.texi(,877) name as its `Up' pointer.  The last child has no `Next' pointer, and the
876texinfo.texi(,878) first child has the parent both as its `Previous' and as its `Up'
877texinfo.texi(,879) pointer.@footnote{In some documents, the first child has no `Previous'
878texinfo.texi(,880) pointer.  Occasionally, the last child has the node name of the next
879texinfo.texi(,881) following higher level node as its `Next' pointer.}
880texinfo.texi(,882)
881texinfo.texi(,883) The book-like structuring of an Info file into nodes that correspond
882texinfo.texi(,884) to chapters, sections, and the like is a matter of convention, not a
883texinfo.texi(,885) requirement.  The `Up', `Previous', and `Next' pointers of a node can
884texinfo.texi(,886) point to any other nodes, and a menu can contain any other nodes.
885texinfo.texi(,887) Thus, the node structure can be any directed graph.  But it is usually
886texinfo.texi(,888) more comprehensible to follow a structure that corresponds to the
887texinfo.texi(,889) structure of chapters and sections in a printed book or report.@refill
888texinfo.texi(,890)
889texinfo.texi(,891) In addition to menus and to `Next', `Previous', and `Up' pointers, Info
890texinfo.texi(,892) provides pointers of another kind, called references, that can be
891texinfo.texi(,893) sprinkled throughout the text.  This is usually the best way to
892texinfo.texi(,894) represent links that do not fit a hierarchical structure.@refill
893texinfo.texi(,895)
894texinfo.texi(,896) Usually, you will design a document so that its nodes match the
895texinfo.texi(,897) structure of chapters and sections in the printed output.  But
896texinfo.texi(,898) occasionally there are times when this is not right for the material
897texinfo.texi(,899) being discussed.  Therefore, Texinfo uses separate commands to specify
898texinfo.texi(,900) the node structure for the Info file and the section structure for the
899texinfo.texi(,901) printed output.@refill
900texinfo.texi(,902)
901texinfo.texi(,903) Generally, you enter an Info file through a node that by convention is
902texinfo.texi(,904) named `Top'.  This node normally contains just a brief summary of the
903texinfo.texi(,905) file's purpose, and a large menu through which the rest of the file is
904texinfo.texi(,906) reached.  From this node, you can either traverse the file
905texinfo.texi(,907) systematically by going from node to node, or you can go to a specific
906texinfo.texi(,908) node listed in the main menu, or you can search the index menus and then
907texinfo.texi(,909) go directly to the node that has the information you want.  Alternatively,
908texinfo.texi(,910) with the standalone Info program, you can specify specific menu items on
909texinfo.texi(,911) the command line (@pxref{Top,,, info, Info}).
910texinfo.texi(,912)
911texinfo.texi(,913) If you want to read through an Info file in sequence, as if it were a
912texinfo.texi(,914) printed manual, you can hit @key{SPC} repeatedly, or you get the whole
913texinfo.texi(,915) file with the advanced Info command @kbd{g *}.  (@inforef{Expert,
914texinfo.texi(,916) Advanced Info commands, info}.)@refill
915texinfo.texi(,917)
916texinfo.texi(,918) @c !!! dir file may be located in one of many places:
917texinfo.texi(,919) @c     /usr/local/emacs/info            mentioned in info.c DEFAULT_INFOPATH
918texinfo.texi(,920) @c     /usr/local/lib/emacs/info        mentioned in info.c DEFAULT_INFOPATH
919texinfo.texi(,921) @c     /usr/gnu/info                    mentioned in info.c DEFAULT_INFOPATH
920texinfo.texi(,922) @c     /usr/local/info
921texinfo.texi(,923) @c     /usr/local/lib/info
922texinfo.texi(,924) The @file{dir} file in the @file{info} directory serves as the
923texinfo.texi(,925) departure point for the whole Info system.  From it, you can reach the
924texinfo.texi(,926) `Top' nodes of each of the documents in a complete Info system.@refill
925texinfo.texi(,927)
926texinfo.texi(,928) @cindex URI syntax for Info
927texinfo.texi(,929) If you wish to refer to an Info file in a URI, you can use the
928texinfo.texi(,930) (unofficial) syntax exemplified in the following.  This works with
929texinfo.texi(,931) Emacs/W3, for example:
930texinfo.texi(,932) @example
931texinfo.texi(,933) info:///usr/info/emacs#Dissociated%20Press
932texinfo.texi(,934) info:emacs#Dissociated%20Press
933texinfo.texi(,935) info://localhost/usr/info/emacs#Dissociated%20Press
934texinfo.texi(,936) @end example
935texinfo.texi(,937)
936texinfo.texi(,938) The @command{info} program itself does not follow URI's of any kind.
937texinfo.texi(,939)
938texinfo.texi(,940)
939texinfo.texi(,941) @node Printed Books
940texinfo.texi(,942) @section Printed Books
941texinfo.texi(,943) @cindex Printed book and manual characteristics
942texinfo.texi(,944) @cindex Manual characteristics, printed
943texinfo.texi(,945) @cindex Book characteristics, printed
944texinfo.texi(,946) @cindex Texinfo printed book characteristics
945texinfo.texi(,947) @cindex Characteristics, printed books or manuals
946texinfo.texi(,948)
947texinfo.texi(,949) @cindex Knuth, Donald
948texinfo.texi(,950) A Texinfo file can be formatted and typeset as a printed book or manual.
949texinfo.texi(,951) To do this, you need @TeX{}, a powerful, sophisticated typesetting
950texinfo.texi(,952) program written by Donald Knuth.@footnote{You can also use the
951texinfo.texi(,953) @pindex texi2roff@r{, unsupported software}
952texinfo.texi(,954) @uref{ftp://tug.org/texi2roff.tar.gz, @code{texi2roff}} program if you
953texinfo.texi(,955) do not have @TeX{}; since Texinfo is designed for use with @TeX{},
954texinfo.texi(,956) @code{texi2roff} is not described here.  @code{texi2roff} is not part of
955texinfo.texi(,957) the standard GNU distribution and is not maintained or up-to-date with
956texinfo.texi(,958) all the Texinfo features described in this manual.}
957texinfo.texi(,959)
958texinfo.texi(,960) A Texinfo-based book is similar to any other typeset, printed work: it
959texinfo.texi(,961) can have a title page, copyright page, table of contents, and preface,
960texinfo.texi(,962) as well as chapters, numbered or unnumbered sections and subsections,
961texinfo.texi(,963) page headers, cross references, footnotes, and indices.@refill
962texinfo.texi(,964)
963texinfo.texi(,965) You can use Texinfo to write a book without ever having the intention
964texinfo.texi(,966) of converting it into online information.  You can use Texinfo for
965texinfo.texi(,967) writing a printed novel, and even to write a printed memo, although
966texinfo.texi(,968) this latter application is not recommended since electronic mail is so
967texinfo.texi(,969) much easier.@refill
968texinfo.texi(,970)
969texinfo.texi(,971) @TeX{} is a general purpose typesetting program.  Texinfo provides a
970texinfo.texi(,972) file @file{texinfo.tex} that contains information (definitions or
971texinfo.texi(,973) @dfn{macros}) that @TeX{} uses when it typesets a Texinfo file.
972texinfo.texi(,974) (@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands
973texinfo.texi(,975) to @TeX{} commands, which @TeX{} can then process to create the typeset
974texinfo.texi(,976) document.)  @file{texinfo.tex} contains the specifications for printing
975texinfo.texi(,977) a document.  You can get the latest version of @file{texinfo.tex} from
976texinfo.texi(,978) @uref{ftp://ftp.gnu.org/gnu/texinfo.tex}.
977texinfo.texi(,979)
978texinfo.texi(,980) In the United States, documents are most often printed on 8.5 inch by 11
979texinfo.texi(,981) inch pages (216@dmn{mm} by 280@dmn{mm}); this is the default size.  But
980texinfo.texi(,982) you can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by
981texinfo.texi(,983) 235@dmn{mm}, the @code{@@smallbook} size; or on A4 or A5 size paper
982texinfo.texi(,984) (@code{@@afourpaper}, @code{@@afivepaper}).  (@xref{smallbook, ,
983texinfo.texi(,985) Printing ``Small'' Books}.  Also, see @ref{A4 Paper, ,Printing on A4
984texinfo.texi(,986) Paper}.)
985texinfo.texi(,987)
986texinfo.texi(,988) By changing the parameters in @file{texinfo.tex}, you can change the
987texinfo.texi(,989) size of the printed document.  In addition, you can change the style in
988texinfo.texi(,990) which the printed document is formatted; for example, you can change the
989texinfo.texi(,991) sizes and fonts used, the amount of indentation for each paragraph, the
990texinfo.texi(,992) degree to which words are hyphenated, and the like.  By changing the
991texinfo.texi(,993) specifications, you can make a book look dignified, old and serious, or
992texinfo.texi(,994) light-hearted, young and cheery.
993texinfo.texi(,995)
994texinfo.texi(,996) @TeX{} is freely distributable.  It is written in a superset of Pascal
995texinfo.texi(,997) called WEB and can be compiled either in Pascal or (by using a
996texinfo.texi(,998) conversion program that comes with the @TeX{} distribution) in C.
997texinfo.texi(,999) (@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information
998texinfo.texi(,1000) about @TeX{}.)@refill
999texinfo.texi(,1001)
1000texinfo.texi(,1002) @TeX{} is very powerful and has a great many features.  Because a
1001texinfo.texi(,1003) Texinfo file must be able to present information both on a
1002texinfo.texi(,1004) character-only terminal in Info form and in a typeset book, the
1003texinfo.texi(,1005) formatting commands that Texinfo supports are necessarily limited.
1004texinfo.texi(,1006)
1005texinfo.texi(,1007) To get a copy of @TeX{}, see
1006texinfo.texi(,1008) @ref{Obtaining TeX, , How to Obtain @TeX{}}.
1007texinfo.texi(,1009)
1008texinfo.texi(,1010)
1009texinfo.texi(,1011) @node Formatting Commands
1010texinfo.texi(,1012) @section @@-commands
1011texinfo.texi(,1013) @cindex @@-commands
1012texinfo.texi(,1014) @cindex Formatting commands
1013texinfo.texi(,1015)
1014texinfo.texi(,1016) In a Texinfo file, the commands that tell @TeX{} how to typeset the
1015texinfo.texi(,1017) printed manual and tell @code{makeinfo} and
1016texinfo.texi(,1018) @code{texinfo-format-buffer} how to create an Info file are preceded
1017texinfo.texi(,1019) by @samp{@@}; they are called @dfn{@@-commands}.  For example,
1018texinfo.texi(,1020) @code{@@node} is the command to indicate a node and @code{@@chapter}
1019texinfo.texi(,1021) is the command to indicate the start of a chapter.@refill
1020texinfo.texi(,1022)
1021texinfo.texi(,1023) @quotation
1022texinfo.texi(,1024) @strong{Please note:} All the @@-commands, with the exception of the
1023texinfo.texi(,1025) @code{@@TeX@{@}} command, must be written entirely in lower case.
1024texinfo.texi(,1026) @end quotation
1025texinfo.texi(,1027)
1026texinfo.texi(,1028) The Texinfo @@-commands are a strictly limited set of constructs.  The
1027texinfo.texi(,1029) strict limits make it possible for Texinfo files to be understood both
1028texinfo.texi(,1030) by @TeX{} and by the code that converts them into Info files.  You can
1029texinfo.texi(,1031) display Info files on any terminal that displays alphabetic and
1030texinfo.texi(,1032) numeric characters.  Similarly, you can print the output generated by
1031texinfo.texi(,1033) @TeX{} on a wide variety of printers.@refill
1032texinfo.texi(,1034)
1033texinfo.texi(,1035) Depending on what they do or what arguments@footnote{The word
1034texinfo.texi(,1036) @dfn{argument} comes from the way it is used in mathematics and does not
1035texinfo.texi(,1037) refer to a dispute between two people; it refers to the information
1036texinfo.texi(,1038) presented to the command.  According to the @cite{Oxford English
1037texinfo.texi(,1039) Dictionary}, the word derives from the Latin for @dfn{to make clear,
1038texinfo.texi(,1040) prove}; thus it came to mean `the evidence offered as proof', which is
1039texinfo.texi(,1041) to say, `the information offered', which led to its mathematical
1040texinfo.texi(,1042) meaning.  In its other thread of derivation, the word came to mean `to
1041texinfo.texi(,1043) assert in a manner against which others may make counter assertions',
1042texinfo.texi(,1044) which led to the meaning of `argument' as a dispute.} they take, you
1043texinfo.texi(,1045) need to write @@-commands on lines of their own or as part of
1044texinfo.texi(,1046) sentences:
1045texinfo.texi(,1047)
1046texinfo.texi(,1048) @itemize @bullet
1047texinfo.texi(,1049) @item
1048texinfo.texi(,1050) Write a command such as @code{@@noindent} at the beginning of a line as
1049texinfo.texi(,1051) the only text on the line.  (@code{@@noindent} prevents the beginning of
1050texinfo.texi(,1052) the next line from being indented as the beginning of a
1051texinfo.texi(,1053) paragraph.)@refill
1052texinfo.texi(,1054)
1053texinfo.texi(,1055) @item
1054texinfo.texi(,1056) Write a command such as @code{@@chapter} at the beginning of a line
1055texinfo.texi(,1057) followed by the command's arguments, in this case the chapter title, on
1056texinfo.texi(,1058) the rest of the line.  (@code{@@chapter} creates chapter titles.)@refill
1057texinfo.texi(,1059)
1058texinfo.texi(,1060) @item
1059texinfo.texi(,1061) Write a command such as @code{@@dots@{@}} wherever you wish but usually
1060texinfo.texi(,1062) within a sentence. (@code{@@dots@{@}} creates dots @dots{})@refill
1061texinfo.texi(,1063)
1062texinfo.texi(,1064) @item
1063texinfo.texi(,1065) Write a command such as @code{@@code@{@var{sample-code}@}} wherever you
1064texinfo.texi(,1066) wish (but usually within a sentence) with its argument,
1065texinfo.texi(,1067) @var{sample-code} in this example, between the braces.  (@code{@@code}
1066texinfo.texi(,1068) marks text as being code.)@refill
1067texinfo.texi(,1069)
1068texinfo.texi(,1070) @item
1069texinfo.texi(,1071) Write a command such as @code{@@example} on a line of its own; write the
1070texinfo.texi(,1072) body-text on following lines; and write the matching @code{@@end}
1071texinfo.texi(,1073) command, @code{@@end example} in this case, at the on a line of its own
1072texinfo.texi(,1074) after the body-text. (@code{@@example} @dots{} @code{@@end example}
1073texinfo.texi(,1075) indents and typesets body-text as an example.)  It's usually ok to
1074texinfo.texi(,1076) indent environment commands like this, but in complicated and
1075texinfo.texi(,1077) hard-to-define circumstances the extra spaces cause extra space to
1076texinfo.texi(,1078) appear in the output, so beware.
1077texinfo.texi(,1079) @end itemize
1078texinfo.texi(,1080)
1079texinfo.texi(,1081) @noindent
1080texinfo.texi(,1082) @cindex Braces, when to use
1081texinfo.texi(,1083) As a general rule, a command requires braces if it mingles among other
1082texinfo.texi(,1084) text; but it does not need braces if it starts a line of its own.  The
1083texinfo.texi(,1085) non-alphabetic commands, such as @code{@@:}, are exceptions to the rule;
1084texinfo.texi(,1086) they do not need braces.@refill
1085texinfo.texi(,1087)
1086texinfo.texi(,1088) As you gain experience with Texinfo, you will rapidly learn how to
1087texinfo.texi(,1089) write the different commands: the different ways to write commands
1088texinfo.texi(,1090) make it easier to write and read Texinfo files than if all commands
1089texinfo.texi(,1091) followed exactly the same syntax.  (For details about @@-command
1090texinfo.texi(,1092) syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill
1091texinfo.texi(,1093)
1092texinfo.texi(,1094)
1093texinfo.texi(,1095) @node Conventions
1094texinfo.texi(,1096) @section General Syntactic Conventions
1095texinfo.texi(,1097) @cindex General syntactic conventions
1096texinfo.texi(,1098) @cindex Syntactic conventions
1097texinfo.texi(,1099) @cindex Conventions, syntactic
1098texinfo.texi(,1100)
1099texinfo.texi(,1101) This section describes the general conventions used in all Texinfo documents.
1100texinfo.texi(,1102)
1101texinfo.texi(,1103) @itemize @bullet
1102texinfo.texi(,1104) @item
1103texinfo.texi(,1105) All printable @sc{ascii} characters except @samp{@@}, @samp{@{} and
1104texinfo.texi(,1106) @samp{@}} can appear in a Texinfo file and stand for themselves.
1105texinfo.texi(,1107) @samp{@@} is the escape character which introduces commands, while
1106texinfo.texi(,1108) @samp{@{} and @samp{@}} are used to surround arguments to certain
1107texinfo.texi(,1109) commands.  To put one of these special characters into the document, put
1108texinfo.texi(,1110) an @samp{@@} character in front of it, like this: @samp{@@@@},
1109texinfo.texi(,1111) @samp{@@@{}, and @samp{@@@}}.
1110texinfo.texi(,1112)
1111texinfo.texi(,1113) @item
1112texinfo.texi(,1114) It is customary in @TeX{} to use doubled single-quote characters to
1113texinfo.texi(,1115) begin and end quotations: @w{@t{`@w{}`@dots{}'@w{}'}}.  This
1114texinfo.texi(,1116) convention should be followed in Texinfo files.  @TeX{} converts
1115texinfo.texi(,1117) two single quotes to left- and right-hand doubled
1116texinfo.texi(,1118) quotation marks,
1117texinfo.texi(,1119) @c this comes out as "like this" in Info, of course, which is just confusing.
1118texinfo.texi(,1123) and Info converts doubled single-quote characters to @sc{ascii}
1119texinfo.texi(,1124) double-quotes: @w{@t{`@w{}`@dots{}'@w{}'}} becomes @w{@t{"@dots{}"}}.
1120texinfo.texi(,1125)
1121texinfo.texi(,1126) @item
1122texinfo.texi(,1127) Use three hyphens in a row, @samp{---}, for a dash---like this.  In
1123texinfo.texi(,1128) @TeX{}, a single or double hyphen produces a printed dash that is
1124texinfo.texi(,1129) shorter than the usual typeset dash. Info reduces three hyphens to two
1125texinfo.texi(,1130) for display on the screen.
1126texinfo.texi(,1131)
1127texinfo.texi(,1132) @item
1128texinfo.texi(,1133) To prevent a paragraph from being indented in the printed manual, put
1129texinfo.texi(,1134) the command @code{@@noindent} on a line by itself before the
1130texinfo.texi(,1135) paragraph.
1131texinfo.texi(,1136)
1132texinfo.texi(,1137) @item
1133texinfo.texi(,1138) If you mark off a region of the Texinfo file with the @code{@@iftex}
1134texinfo.texi(,1139) and @w{@code{@@end iftex}} commands, that region will appear only in
1135texinfo.texi(,1140) the printed copy; in that region, you can use certain commands
1136texinfo.texi(,1141) borrowed from plain @TeX{} that you cannot use in Info.  Conversely,
1137texinfo.texi(,1142) text surrounded by @code{@@ifnottex} and @code{@@end ifnottex} will
1138texinfo.texi(,1143) appear in all output formats @emph{except} @TeX{}.
1139texinfo.texi(,1144)
1140texinfo.texi(,1145) Each of the other output formats (@code{html}, @code{info},
1141texinfo.texi(,1146) @code{plaintext}) have an analogous pair of commands.  @xref{Conditionals}.
1142texinfo.texi(,1147) @end itemize
1143texinfo.texi(,1148)
1144texinfo.texi(,1149) @cindex Tabs; don't use!
1145texinfo.texi(,1150) @quotation
1146texinfo.texi(,1151) @strong{Caution:} Do not use tab characters in a Texinfo file (except in
1147texinfo.texi(,1152) verbatim modes)!  @TeX{} uses variable-width fonts, which means that it
1148texinfo.texi(,1153) is impractical at best to define a tab to work in all circumstances.
1149texinfo.texi(,1154) Consequently, @TeX{} treats tabs like single spaces, and that is not
1150texinfo.texi(,1155) what they look like.  Furthermore, @code{makeinfo} does nothing special
1151texinfo.texi(,1156) with tabs, and thus a tab character in your input file may appear
1152texinfo.texi(,1157) differently in the output, for example, in indented text.
1153texinfo.texi(,1158)
1154texinfo.texi(,1159) @noindent
1155texinfo.texi(,1160) To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple
1156texinfo.texi(,1161) spaces when you press the @key{TAB} key.
1157texinfo.texi(,1162)
1158texinfo.texi(,1163) @noindent
1159texinfo.texi(,1164) Also, you can run @code{untabify} in Emacs to convert tabs in a region
1160texinfo.texi(,1165) to multiple spaces.
1161texinfo.texi(,1166) @end quotation
1162texinfo.texi(,1167)
1163texinfo.texi(,1168)
1164texinfo.texi(,1169) @node Comments
1165texinfo.texi(,1170) @section Comments
1166texinfo.texi(,1171)
1167texinfo.texi(,1172) @cindex Comments
1168texinfo.texi(,1173) @findex comment
1169texinfo.texi(,1174) @findex c @r{(comment)}
1170texinfo.texi(,1175)
1171texinfo.texi(,1176) You can write comments in a Texinfo file that will not appear in
1172texinfo.texi(,1177) either the Info file or the printed manual by using the
1173texinfo.texi(,1178) @code{@@comment} command (which may be abbreviated to @code{@@c}).
1174texinfo.texi(,1179) Such comments are for the person who revises the Texinfo file.  All the
1175texinfo.texi(,1180) text on a line that follows either @code{@@comment} or @code{@@c} is a
1176texinfo.texi(,1181) comment; the rest of the line does not appear in either the Info file
1177texinfo.texi(,1182) or the printed manual.
1178texinfo.texi(,1183)
1179texinfo.texi(,1184) Often, you can write the @code{@@comment} or @code{@@c} in the middle of
1180texinfo.texi(,1185) a line, and only the text that follows after the @code{@@comment} or
1181texinfo.texi(,1186) @code{@@c} command does not appear; but some commands, such as
1182texinfo.texi(,1187) @code{@@settitle} and @code{@@setfilename}, work on a whole line.  You
1183texinfo.texi(,1188) cannot use @code{@@comment} or @code{@@c} in a line beginning with such
1184texinfo.texi(,1189) a command.
1185texinfo.texi(,1190)
1186texinfo.texi(,1191) @cindex Ignored text
1187texinfo.texi(,1192) @cindex Unprocessed text
1188texinfo.texi(,1193) @findex ignore
1189texinfo.texi(,1194) You can write long stretches of text that will not appear in either
1190texinfo.texi(,1195) the Info file or the printed manual by using the @code{@@ignore} and
1191texinfo.texi(,1196) @code{@@end ignore} commands.  Write each of these commands on a line
1192texinfo.texi(,1197) of its own, starting each command at the beginning of the line.  Text
1193texinfo.texi(,1198) between these two commands does not appear in the processed output.
1194texinfo.texi(,1199) You can use @code{@@ignore} and @code{@@end ignore} for writing
1195texinfo.texi(,1200) comments.
1196texinfo.texi(,1201)
1197texinfo.texi(,1202) Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or
1198texinfo.texi(,1203) @code{@@ifclear} conditions is ignored in the sense that it will not
1199texinfo.texi(,1204) contribute to the formatted output.  However, @TeX{} and makeinfo must
1200texinfo.texi(,1205) still parse the ignored text, in order to understand when to @emph{stop}
1201texinfo.texi(,1206) ignoring text from the source file; that means that you may still get
1202texinfo.texi(,1207) error messages if you have invalid Texinfo commands within ignored text.
1203texinfo.texi(,1208)
1204texinfo.texi(,1209)
1205texinfo.texi(,1210) @node Minimum
1206texinfo.texi(,1211) @section What a Texinfo File Must Have
1207texinfo.texi(,1212) @cindex Minimal Texinfo file (requirements)
1208texinfo.texi(,1213) @cindex Must have in Texinfo file
1209texinfo.texi(,1214) @cindex Required in Texinfo file
1210texinfo.texi(,1215) @cindex Texinfo file minimum
1211texinfo.texi(,1216)
1212texinfo.texi(,1217) By convention, the namea of a Texinfo file ends with (in order of
1213texinfo.texi(,1218) preference) one of the extensions @file{.texinfo}, @file{.texi},
1214texinfo.texi(,1219) @file{.txi}, or @file{.tex}.  The longer extensions are preferred since
1215texinfo.texi(,1220) they describe more clearly to a human reader the nature of the file.
1216texinfo.texi(,1221) The shorter extensions are for operating systems that cannot handle long
1217texinfo.texi(,1222) file names.
1218texinfo.texi(,1223)
1219texinfo.texi(,1224) In order to be made into a printed manual and an Info file, a Texinfo
1220texinfo.texi(,1225) file @strong{must} begin with lines like this:
1221texinfo.texi(,1226)
1222texinfo.texi(,1227) @example
1223texinfo.texi(,1228) @group
1224texinfo.texi(,1229) \input texinfo
1225texinfo.texi(,1230) @@setfilename @var{info-file-name}
1226texinfo.texi(,1231) @@settitle @var{name-of-manual}
1227texinfo.texi(,1232) @end group
1228texinfo.texi(,1233) @end example
1229texinfo.texi(,1234)
1230texinfo.texi(,1235) @noindent
1231texinfo.texi(,1236) The contents of the file follow this beginning, and then you
1232texinfo.texi(,1237) @strong{must} end a Texinfo file with a line like this:
1233texinfo.texi(,1238)
1234texinfo.texi(,1239) @example
1235texinfo.texi(,1240) @@bye
1236texinfo.texi(,1241) @end example
1237texinfo.texi(,1242)
1238texinfo.texi(,1243) @findex \input @r{(raw @TeX{} startup)}
1239texinfo.texi(,1244) @noindent
1240texinfo.texi(,1245) Here's an explanation:
1241texinfo.texi(,1246)
1242texinfo.texi(,1247) @itemize @bullet
1243texinfo.texi(,1248) @item
1244texinfo.texi(,1249) The @samp{\input texinfo} line tells @TeX{} to use the
1245texinfo.texi(,1250) @file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo
1246texinfo.texi(,1251) @@-commands into @TeX{} typesetting commands.  (Note the use of the
1247texinfo.texi(,1252) backslash, @samp{\}; this is correct for @TeX{}.)
1248texinfo.texi(,1253)
1249texinfo.texi(,1254) @item
1250texinfo.texi(,1255) The @code{@@setfilename} line provides a name for the Info file and
1251texinfo.texi(,1256) tells @TeX{} to open auxiliary files.  @strong{All text before
1252texinfo.texi(,1257) @code{@@setfilename} is ignored!}
1253texinfo.texi(,1258)
1254texinfo.texi(,1259) @item
1255texinfo.texi(,1260) The @code{@@settitle} line specifies a title for the page headers (or
1256texinfo.texi(,1261) footers) of the printed manual, and the default document description for
1257texinfo.texi(,1262) the @samp{<head>} in HTML format.  Strictly speaking, @code{@@settitle}
1258texinfo.texi(,1263) is optional---if you don't mind your document being titled `Untitled'.
1259texinfo.texi(,1264)
1260texinfo.texi(,1265) @item
1261texinfo.texi(,1266) The @code{@@bye} line at the end of the file on a line of its own tells
1262texinfo.texi(,1267) the formatters that the file is ended and to stop formatting.
1263texinfo.texi(,1268)
1264texinfo.texi(,1269) @end itemize
1265texinfo.texi(,1270)
1266texinfo.texi(,1271) Typically, you will not use quite such a spare format, but will include
1267texinfo.texi(,1272) mode setting and start-of-header and end-of-header lines at the
1268texinfo.texi(,1273) beginning of a Texinfo file, like this:
1269texinfo.texi(,1274)
1270texinfo.texi(,1275) @example
1271texinfo.texi(,1276) @group
1272texinfo.texi(,1277) \input texinfo   @@c -*-texinfo-*-
1273texinfo.texi(,1278) @@c %**start of header
1274texinfo.texi(,1279) @@setfilename @var{info-file-name}
1275texinfo.texi(,1280) @@settitle @var{name-of-manual}
1276texinfo.texi(,1281) @@c %**end of header
1277texinfo.texi(,1282) @end group
1278texinfo.texi(,1283) @end example
1279texinfo.texi(,1284)
1280texinfo.texi(,1285) @noindent
1281texinfo.texi(,1286) In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into
1282texinfo.texi(,1287) Texinfo mode when you edit the file.
1283texinfo.texi(,1288)
1284texinfo.texi(,1289) The @code{@@c} lines which surround the @code{@@setfilename} and
1285texinfo.texi(,1290) @code{@@settitle} lines are optional, but you need them in order to
1286texinfo.texi(,1291) run @TeX{} or Info on just part of the file.  (@xref{Start of Header}.)
1287texinfo.texi(,1292)
1288texinfo.texi(,1293) Furthermore, you will usually provide a Texinfo file with a title page,
1289texinfo.texi(,1294) indices, and the like, all of which are explained in this manual.  But
1290texinfo.texi(,1295) the minimum, which can be useful for short documents, is just the three
1291texinfo.texi(,1296) lines at the beginning and the one line at the end.
1292texinfo.texi(,1297)
1293texinfo.texi(,1298)
1294texinfo.texi(,1299) @node Six Parts
1295texinfo.texi(,1300) @section Six Parts of a Texinfo File
1296texinfo.texi(,1301)
1297texinfo.texi(,1302) Generally, a Texinfo file contains more than the minimal beginning and
1298texinfo.texi(,1303) end described in the previous section---it usually contains the six
1299texinfo.texi(,1304) parts listed below.  These are described fully in the following sections.
1300texinfo.texi(,1305)
1301texinfo.texi(,1306) @table @r
1302texinfo.texi(,1307) @item 1. Header
1303texinfo.texi(,1308) The @dfn{Header} names the file, tells @TeX{} which definitions file to
1304texinfo.texi(,1309) use, and other such housekeeping tasks.
1305texinfo.texi(,1310)
1306texinfo.texi(,1311) @item 2. Summary and Copyright
1307texinfo.texi(,1312) The @dfn{Summary and Copyright} segment describes the document and
1308texinfo.texi(,1313) contains the copyright notice and copying permissions.  This is done
1309texinfo.texi(,1314) with the @code{@@copying} command.
1310texinfo.texi(,1315)
1311texinfo.texi(,1316) @item 3. Title and Copyright
1312texinfo.texi(,1317) The @dfn{Title and Copyright} segment contains the title and copyright
1313texinfo.texi(,1318) pages for the printed manual.  The segment must be enclosed between
1314texinfo.texi(,1319) @code{@@titlepage} and @code{@@end titlepage} commands.  The title and
1315texinfo.texi(,1320) copyright page appear only in the printed manual.
1316texinfo.texi(,1321)
1317texinfo.texi(,1322) @item 4. `Top' Node and Master Menu
1318texinfo.texi(,1323) The `Top' node starts off the online output; it does not appear in the
1319texinfo.texi(,1324) printed manual.  We recommend including the copying permissions here as
1320texinfo.texi(,1325) well as the segments above.  And it contains at least a top-level menu
1321texinfo.texi(,1326) listing the chapters, and possibly a @dfn{Master Menu} listing all the
1322texinfo.texi(,1327) nodes in the entire document.
1323texinfo.texi(,1328)
1324texinfo.texi(,1329) @item 5. Body
1325texinfo.texi(,1330) The @dfn{Body} of the document is typically structured like a
1326texinfo.texi(,1331) traditional book or encyclopedia, but it may be free form.
1327texinfo.texi(,1332)
1328texinfo.texi(,1333) @item 6. End
1329texinfo.texi(,1334) The @dfn{End} segment contains commands for printing indices and
1330texinfo.texi(,1335) generating the table of contents, and the @code{@@bye} command on a line
1331texinfo.texi(,1336) of its own.
1332texinfo.texi(,1337) @end table
1333texinfo.texi(,1338)
1334texinfo.texi(,1339)
1335texinfo.texi(,1340) @node Short Sample
1336texinfo.texi(,1341) @section A Short Sample Texinfo File
1337texinfo.texi(,1342) @cindex Sample Texinfo file, with comments
1338texinfo.texi(,1343)
1339texinfo.texi(,1344) Here is a very short but complete Texinfo file, in the six conventional
1340texinfo.texi(,1345) parts enumerated in the previous section, so you can see how Texinfo
1341texinfo.texi(,1346) source appears in practice.  The first three parts of the file, from
1342texinfo.texi(,1347) @samp{\input texinfo} through to @samp{@@end titlepage}, look more
1343texinfo.texi(,1348) intimidating than they are: most of the material is standard
1344texinfo.texi(,1349) boilerplate; when writing a manual, you simply change the names as
1345texinfo.texi(,1350) appropriate.
1346texinfo.texi(,1351)
1347texinfo.texi(,1352) @xref{Beginning a File}, for full documentation on the commands listed
1348texinfo.texi(,1353) here.  @xref{GNU Sample Texts}, for the full texts to be used in GNU manuals.
1349texinfo.texi(,1354)
1350texinfo.texi(,1355) In the following, the sample text is @emph{indented}; comments on it are
1351texinfo.texi(,1356) not.  The complete file, without interspersed comments, is shown in
1352texinfo.texi(,1357) @ref{Short Sample Texinfo File}.
1353texinfo.texi(,1358)
1354texinfo.texi(,1359) @subheading Part 1: Header
1355texinfo.texi(,1360)
1356texinfo.texi(,1361) @noindent
1357texinfo.texi(,1362) The header does not appear in either the Info file or the
1358texinfo.texi(,1363) printed output.  It sets various parameters, including the
1359texinfo.texi(,1364) name of the Info file and the title used in the header.
1360texinfo.texi(,1365)
1361texinfo.texi(,1366) @example
1362texinfo.texi(,1367) @group
1363texinfo.texi(,1368) \input texinfo   @@c -*-texinfo-*-
1364texinfo.texi(,1369) @@c %**start of header
1365texinfo.texi(,1370) @@setfilename sample.info
1366texinfo.texi(,1371) @@settitle Sample Manual 1.0
1367texinfo.texi(,1372) @@c %**end of header
1368texinfo.texi(,1373) @end group
1369texinfo.texi(,1374) @end example
1370texinfo.texi(,1375)
1371texinfo.texi(,1376) @subheading Part 2: Summary Description and Copyright
1372texinfo.texi(,1377)
1373texinfo.texi(,1378) @noindent
1374texinfo.texi(,1379) A real manual includes more text here, according to the license under
1375texinfo.texi(,1380) which it is distributed.  @xref{GNU Sample Texts}.
1376texinfo.texi(,1381)
1377texinfo.texi(,1382) @example
1378texinfo.texi(,1383) @group
1379texinfo.texi(,1384) @@copying
1380texinfo.texi(,1385) This is a short example of a complete Texinfo file, version 1.0.
1381texinfo.texi(,1386)
1382texinfo.texi(,1387) Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
1383texinfo.texi(,1388) @@end copying
1384texinfo.texi(,1389) @end group
1385texinfo.texi(,1390) @end example
1386texinfo.texi(,1391)
1387texinfo.texi(,1392) @subheading Part 3: Titlepage, Contents, Copyright
1388texinfo.texi(,1393)
1389texinfo.texi(,1394) @noindent
1390texinfo.texi(,1395) The titlepage segment does not appear in the online output, only in the
1391texinfo.texi(,1396) printed manual.  We use the @code{@@insertcopying} command to
1392texinfo.texi(,1397) include the permission text from the previous section, instead of
1393texinfo.texi(,1398) writing it out again; it is output on the back of the title page.  The
1394texinfo.texi(,1399) @code{@@contents} command generates a table of contents.
1395texinfo.texi(,1400)
1396texinfo.texi(,1401) @example
1397texinfo.texi(,1402) @group
1398texinfo.texi(,1403) @@titlepage
1399texinfo.texi(,1404) @@title Sample Title
1400texinfo.texi(,1405) @end group
1401texinfo.texi(,1406)
1402texinfo.texi(,1407) @group
1403texinfo.texi(,1408) @@c The following two commands start the copyright page.
1404texinfo.texi(,1409) @@page
1405texinfo.texi(,1410) @@vskip 0pt plus 1filll
1406texinfo.texi(,1411) @@insertcopying
1407texinfo.texi(,1412) @@end titlepage
1408texinfo.texi(,1413) @end group
1409texinfo.texi(,1414)
1410texinfo.texi(,1415) @@c Output the table of contents at the beginning.
1411texinfo.texi(,1416) @@contents
1412texinfo.texi(,1417) @end example
1413texinfo.texi(,1418)
1414texinfo.texi(,1419) @subheading Part 4: `Top' Node and Master Menu
1415texinfo.texi(,1420)
1416texinfo.texi(,1421) @noindent
1417texinfo.texi(,1422) The `Top' node contains the master menu for the Info file.  Since a
1418texinfo.texi(,1423) printed manual uses a table of contents rather than a menu, the master
1419texinfo.texi(,1424) menu appears only in online output.  We also include the copying text
1420texinfo.texi(,1425) again for the benefit of online readers.  And since the copying text
1421texinfo.texi(,1426) begins with a brief description of the manual, no other text is needed.
1422texinfo.texi(,1427)
1423texinfo.texi(,1428) @example
1424texinfo.texi(,1429) @group
1425texinfo.texi(,1430) @@ifnottex
1426texinfo.texi(,1431) @@node Top
1427texinfo.texi(,1432) @@end ifnottex
1428texinfo.texi(,1433) @end group
1429texinfo.texi(,1434) @end example
1430texinfo.texi(,1435)
1431texinfo.texi(,1436) @example
1432texinfo.texi(,1437) @group
1433texinfo.texi(,1438) @@insertcopying
1434texinfo.texi(,1439)
1435texinfo.texi(,1440) @@menu
1436texinfo.texi(,1441) * First Chapter::    The first chapter is the
1437texinfo.texi(,1442)                        only chapter in this sample.
1438texinfo.texi(,1443) * Index::            Complete index.
1439texinfo.texi(,1444) @@end menu
1440texinfo.texi(,1445) @end group
1441texinfo.texi(,1446) @end example
1442texinfo.texi(,1447)
1443texinfo.texi(,1448)
1444texinfo.texi(,1449) @subheading Part 5: The Body of the Document
1445texinfo.texi(,1450)
1446texinfo.texi(,1451) @noindent
1447texinfo.texi(,1452) The body segment contains all the text of the document, but not the
1448texinfo.texi(,1453) indices or table of contents.  This example illustrates a node and a
1449texinfo.texi(,1454) chapter containing an enumerated list.
1450texinfo.texi(,1455)
1451texinfo.texi(,1456) @example
1452texinfo.texi(,1457) @group
1453texinfo.texi(,1458) @@node First Chapter
1454texinfo.texi(,1459) @@chapter First Chapter
1455texinfo.texi(,1460)
1456texinfo.texi(,1461) @@cindex chapter, first
1457texinfo.texi(,1462) @end group
1458texinfo.texi(,1463)
1459texinfo.texi(,1464) @group
1460texinfo.texi(,1465) This is the first chapter.
1461texinfo.texi(,1466) @@cindex index entry, another
1462texinfo.texi(,1467) @end group
1463texinfo.texi(,1468)
1464texinfo.texi(,1469) @group
1465texinfo.texi(,1470) Here is a numbered list.
1466texinfo.texi(,1471)
1467texinfo.texi(,1472) @@enumerate
1468texinfo.texi(,1473) @@item
1469texinfo.texi(,1474) This is the first item.
1470texinfo.texi(,1475)
1471texinfo.texi(,1476) @@item
1472texinfo.texi(,1477) This is the second item.
1473texinfo.texi(,1478) @@end enumerate
1474texinfo.texi(,1479) @end group
1475texinfo.texi(,1480) @end example
1476texinfo.texi(,1481)
1477texinfo.texi(,1482)
1478texinfo.texi(,1483) @subheading Part 6: The End of the Document
1479texinfo.texi(,1484)
1480texinfo.texi(,1485) @noindent
1481texinfo.texi(,1486) The end segment contains commands for generating an index in a node and
1482texinfo.texi(,1487) unnumbered chapter of its own, and the @code{@@bye} command that marks
1483texinfo.texi(,1488) the end of the document.
1484texinfo.texi(,1489)
1485texinfo.texi(,1490) @example
1486texinfo.texi(,1491) @group
1487texinfo.texi(,1492) @@node Index
1488texinfo.texi(,1493) @@unnumbered Index
1489texinfo.texi(,1494) @end group
1490texinfo.texi(,1495)
1491texinfo.texi(,1496) @group
1492texinfo.texi(,1497) @@printindex cp
1493texinfo.texi(,1498)
1494texinfo.texi(,1499) @@bye
1495texinfo.texi(,1500) @end group
1496texinfo.texi(,1501) @end example
1497texinfo.texi(,1502)
1498texinfo.texi(,1503)
1499texinfo.texi(,1504) @subheading Some Results
1500texinfo.texi(,1505)
1501texinfo.texi(,1506) Here is what the contents of the first chapter of the sample look like:
1502texinfo.texi(,1507)
1503texinfo.texi(,1508) @sp 1
1504texinfo.texi(,1509) @need 700
1505texinfo.texi(,1510) @quotation
1506texinfo.texi(,1511) This is the first chapter.
1507texinfo.texi(,1512)
1508texinfo.texi(,1513) Here is a numbered list.
1509texinfo.texi(,1514)
1510texinfo.texi(,1515) @enumerate
1511texinfo.texi(,1516) @item
1512texinfo.texi(,1517) This is the first item.
1513texinfo.texi(,1518)
1514texinfo.texi(,1519) @item
1515texinfo.texi(,1520) This is the second item.
1516texinfo.texi(,1521) @end enumerate
1517texinfo.texi(,1522) @end quotation
1518texinfo.texi(,1523)
1519texinfo.texi(,1524)
1520texinfo.texi(,1525) @node History
1521texinfo.texi(,1526) @section History
1522texinfo.texi(,1527)
1523texinfo.texi(,1528) @cindex Stallman, Richard M.
1524texinfo.texi(,1529) @cindex Chassell, Robert J.
1525texinfo.texi(,1530) @cindex Fox, Brian
1526texinfo.texi(,1531) @cindex Berry, Karl
1527texinfo.texi(,1532) Richard M.@: Stallman invented the Texinfo format, wrote the initial
1528texinfo.texi(,1533) processors, and created Edition 1.0 of this manual.  @w{Robert J.@:}
1529texinfo.texi(,1534) Chassell greatly revised and extended the manual, starting with Edition
1530texinfo.texi(,1535) 1.1.  Brian Fox was responsible for the standalone Texinfo distribution
1531texinfo.texi(,1536) until version 3.8, and wrote the standalone @command{makeinfo} and
1532texinfo.texi(,1537) @command{info} programs.  Karl Berry has continued maintenance since
1533texinfo.texi(,1538) Texinfo 3.8 (manual edition 2.22).
1534texinfo.texi(,1539)
1535texinfo.texi(,1540) @cindex Pinard, Fran@,{c}ois
1536texinfo.texi(,1541) @cindex Zuhn, David D.
1537texinfo.texi(,1542) @cindex Weisshaus, Melissa
1538texinfo.texi(,1543) @cindex Zaretskii, Eli
1539texinfo.texi(,1544) @cindex Schwab, Andreas
1540texinfo.texi(,1545) @cindex Weinberg, Zack
1541texinfo.texi(,1546) Our thanks go out to all who helped improve this work, particularly the
1542texinfo.texi(,1547) indefatigable Eli Zaretskii and Andreas Schwab, who have provided
1543texinfo.texi(,1548) patches beyond counting.  Fran@,{c}ois Pinard and @w{David D.@: Zuhn},
1544texinfo.texi(,1549) tirelessly recorded and reported mistakes and obscurities.  Zack
1545texinfo.texi(,1550) Weinberg did the impossible by implementing the macro syntax in
1546texinfo.texi(,1551) @file{texinfo.tex}.  Special thanks go to Melissa Weisshaus for her
1547texinfo.texi(,1552) frequent reviews of nearly similar editions.  Dozens of others have
1548texinfo.texi(,1553) contributed patches and suggestions, they are gratefully acknowledged in
1549texinfo.texi(,1554) the @file{ChangeLog} file.  Our mistakes are our own.
1550texinfo.texi(,1555)
1551texinfo.texi(,1556) @cindex Scribe
1552texinfo.texi(,1557) @cindex Reid, Brian
1553texinfo.texi(,1558) @cindex History of Texinfo
1554texinfo.texi(,1559) @cindex Texinfo history
1555texinfo.texi(,1560) A bit of history: in the 1970's at CMU, Brian Reid developed a program
1556texinfo.texi(,1561) and format named Scribe to mark up documents for printing.  It used the
1557texinfo.texi(,1562) @code{@@} character to introduce commands, as Texinfo does.  Much more
1558texinfo.texi(,1563) consequentially, it strived to describe document contents rather than
1559texinfo.texi(,1564) formatting, an idea wholeheartedly adopted by Texinfo.
1560texinfo.texi(,1565)
1561texinfo.texi(,1566) @cindex Bolio
1562texinfo.texi(,1567) @cindex Bo@TeX{}
1563texinfo.texi(,1568) Meanwhile, people at MIT developed another, not too dissimilar format
1564texinfo.texi(,1569) called Bolio.  This then was converted to using @TeX{} as its typesetting
1565texinfo.texi(,1570) language: Bo@TeX{}.  The earliest Bo@TeX{} version seems to have been
1566texinfo.texi(,1571) 0.02 on October 31, 1984.
1567texinfo.texi(,1572)
1568texinfo.texi(,1573) Bo@TeX{} could only be used as a markup language for documents to be
1569texinfo.texi(,1574) printed, not for online documents.  Richard Stallman (RMS) worked on
1570texinfo.texi(,1575) both Bolio and Bo@TeX{}.  He also developed a nifty on-line help format
1571texinfo.texi(,1576) called Info, and then combined Bo@TeX{} and Info to create Texinfo, a
1572texinfo.texi(,1577) mark up language for text that is intended to be read both online and
1573texinfo.texi(,1578) as printed hard copy.
1574texinfo.texi(,1579)
1575texinfo.texi(,1580)
1576texinfo.texi(,1581) @node Texinfo Mode
1577texinfo.texi(,1582) @chapter Using Texinfo Mode
1578texinfo.texi(,1583) @cindex Texinfo mode
1579texinfo.texi(,1584) @cindex Mode, using Texinfo
1580texinfo.texi(,1585) @cindex GNU Emacs
1581texinfo.texi(,1586) @cindex Emacs
1582texinfo.texi(,1587)
1583texinfo.texi(,1588) You may edit a Texinfo file with any text editor you choose.  A Texinfo
1584texinfo.texi(,1589) file is no different from any other @sc{ascii} file.  However, GNU Emacs
1585texinfo.texi(,1590) comes with a special mode, called Texinfo mode, that provides Emacs
1586texinfo.texi(,1591) commands and tools to help ease your work.
1587texinfo.texi(,1592)
1588texinfo.texi(,1593) This chapter describes features of GNU Emacs' Texinfo mode but not any
1589texinfo.texi(,1594) features of the Texinfo formatting language.  So if you are reading this
1590texinfo.texi(,1595) manual straight through from the beginning, you may want to skim through
1591texinfo.texi(,1596) this chapter briefly and come back to it after reading succeeding
1592texinfo.texi(,1597) chapters which describe the Texinfo formatting language in detail.
1593texinfo.texi(,1598)
1594texinfo.texi(,1599) @menu
1595texinfo.texi(,1600) * Texinfo Mode Overview::       How Texinfo mode can help you.
1596texinfo.texi(,1601) * Emacs Editing::               Texinfo mode adds to GNU Emacs' general
1597texinfo.texi(,1602)                                   purpose editing features.
1598texinfo.texi(,1603) * Inserting::                   How to insert frequently used @@-commands.
1599texinfo.texi(,1604) * Showing the Structure::       How to show the structure of a file.
1600texinfo.texi(,1605) * Updating Nodes and Menus::    How to update or create new nodes and menus.
1601texinfo.texi(,1606) * Info Formatting::             How to format for Info.
1602texinfo.texi(,1607) * Printing::                    How to format and print part or all of a file.
1603texinfo.texi(,1608) * Texinfo Mode Summary::        Summary of all the Texinfo mode commands.
1604texinfo.texi(,1609) @end menu
1605texinfo.texi(,1610)
1606texinfo.texi(,1611) @node Texinfo Mode Overview, Emacs Editing, Texinfo Mode, Texinfo Mode
1607texinfo.texi(,1613) @heading Texinfo Mode Overview
1608texinfo.texi(,1615)
1609texinfo.texi(,1616) Texinfo mode provides special features for working with Texinfo
1610texinfo.texi(,1617) files.
1611texinfo.texi(,1618) You can:@refill
1612texinfo.texi(,1619)
1613texinfo.texi(,1620) @itemize @bullet
1614texinfo.texi(,1621) @item
1615texinfo.texi(,1622) Insert frequently used @@-commands. @refill
1616texinfo.texi(,1623)
1617texinfo.texi(,1624) @item
1618texinfo.texi(,1625) Automatically create @code{@@node} lines.
1619texinfo.texi(,1626)
1620texinfo.texi(,1627) @item
1621texinfo.texi(,1628) Show the structure of a Texinfo source file.@refill
1622texinfo.texi(,1629)
1623texinfo.texi(,1630) @item
1624texinfo.texi(,1631) Automatically create or update the `Next',
1625texinfo.texi(,1632) `Previous', and `Up' pointers of a node.
1626texinfo.texi(,1633)
1627texinfo.texi(,1634) @item
1628texinfo.texi(,1635) Automatically create or update menus.@refill
1629texinfo.texi(,1636)
1630texinfo.texi(,1637) @item
1631texinfo.texi(,1638) Automatically create a master menu.@refill
1632texinfo.texi(,1639)
1633texinfo.texi(,1640) @item
1634texinfo.texi(,1641) Format a part or all of a file for Info.@refill
1635texinfo.texi(,1642)
1636texinfo.texi(,1643) @item
1637texinfo.texi(,1644) Typeset and print part or all of a file.@refill
1638texinfo.texi(,1645) @end itemize
1639texinfo.texi(,1646)
1640texinfo.texi(,1647) Perhaps the two most helpful features are those for inserting frequently
1641texinfo.texi(,1648) used @@-commands and for creating node pointers and menus.@refill
1642texinfo.texi(,1649)
1643texinfo.texi(,1650) @node Emacs Editing, Inserting, Texinfo Mode Overview, Texinfo Mode
1644texinfo.texi(,1651) @section The Usual GNU Emacs Editing Commands
1645texinfo.texi(,1652)
1646texinfo.texi(,1653) In most cases, the usual Text mode commands work the same in Texinfo
1647texinfo.texi(,1654) mode as they do in Text mode.  Texinfo mode adds new editing commands
1648texinfo.texi(,1655) and tools to GNU Emacs' general purpose editing features.  The major
1649texinfo.texi(,1656) difference concerns filling.  In Texinfo mode, the paragraph
1650texinfo.texi(,1657) separation variable and syntax table are redefined so that Texinfo
1651texinfo.texi(,1658) commands that should be on lines of their own are not inadvertently
1652texinfo.texi(,1659) included in paragraphs.  Thus, the @kbd{M-q} (@code{fill-paragraph})
1653texinfo.texi(,1660) command will refill a paragraph but not mix an indexing command on a
1654texinfo.texi(,1661) line adjacent to it into the paragraph.@refill
1655texinfo.texi(,1662)
1656texinfo.texi(,1663) In addition, Texinfo mode sets the @code{page-delimiter} variable to
1657texinfo.texi(,1664) the value of @code{texinfo-chapter-level-regexp}; by default, this is
1658texinfo.texi(,1665) a regular expression matching the commands for chapters and their
1659texinfo.texi(,1666) equivalents, such as appendices.  With this value for the page
1660texinfo.texi(,1667) delimiter, you can jump from chapter title to chapter title with the
1661texinfo.texi(,1668) @kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [}
1662texinfo.texi(,1669) (@code{backward-page}) commands and narrow to a chapter with the
1663texinfo.texi(,1670) @kbd{C-x p} (@code{narrow-to-page}) command.  (@xref{Pages, , ,emacs,
1664texinfo.texi(,1671) The GNU Emacs Manual}, for details about the page commands.)@refill
1665texinfo.texi(,1672)
1666texinfo.texi(,1673) You may name a Texinfo file however you wish, but the convention is to
1667texinfo.texi(,1674) end a Texinfo file name with one of the extensions
1668texinfo.texi(,1675) @file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}.  A longer
1669texinfo.texi(,1676) extension is preferred, since it is explicit, but a shorter extension
1670texinfo.texi(,1677) may be necessary for operating systems that limit the length of file
1671texinfo.texi(,1678) names.  GNU Emacs automatically enters Texinfo mode when you visit a
1672texinfo.texi(,1679) file with a @file{.texinfo}, @file{.texi} or @file{.txi}
1673texinfo.texi(,1680) extension.  Also, Emacs switches to Texinfo mode
1674texinfo.texi(,1681) when you visit a
1675texinfo.texi(,1682) file that has @samp{-*-texinfo-*-} in its first line.  If ever you are
1676texinfo.texi(,1683) in another mode and wish to switch to Texinfo mode, type @code{M-x
1677texinfo.texi(,1684) texinfo-mode}.@refill
1678texinfo.texi(,1685)
1679texinfo.texi(,1686) Like all other Emacs features, you can customize or enhance Texinfo
1680texinfo.texi(,1687) mode as you wish.  In particular, the keybindings are very easy to
1681texinfo.texi(,1688) change.  The keybindings described here are the default or standard
1682texinfo.texi(,1689) ones.@refill
1683texinfo.texi(,1690)
1684texinfo.texi(,1691) @node Inserting, Showing the Structure, Emacs Editing, Texinfo Mode
1685texinfo.texi(,1692) @comment  node-name,  next,  previous,  up
1686texinfo.texi(,1693) @section Inserting Frequently Used Commands
1687texinfo.texi(,1694) @cindex Inserting frequently used commands
1688texinfo.texi(,1695) @cindex Frequently used commands, inserting
1689texinfo.texi(,1696) @cindex Commands, inserting them
1690texinfo.texi(,1697)
1691texinfo.texi(,1698) Texinfo mode provides commands to insert various frequently used
1692texinfo.texi(,1699) @@-commands into the buffer.  You can use these commands to save
1693texinfo.texi(,1700) keystrokes.@refill
1694texinfo.texi(,1701)
1695texinfo.texi(,1702) The insert commands are invoked by typing @kbd{C-c} twice and then the
1696texinfo.texi(,1703) first letter of the @@-command:@refill
1697texinfo.texi(,1704)
1698texinfo.texi(,1705) @table @kbd
1699texinfo.texi(,1706) @item  C-c C-c c
1700texinfo.texi(,1707) @itemx M-x texinfo-insert-@@code
1701texinfo.texi(,1708) @findex texinfo-insert-@@code
1702texinfo.texi(,1709) Insert @code{@@code@{@}} and put the
1703texinfo.texi(,1710) cursor between the braces.@refill
1704texinfo.texi(,1711)
1705texinfo.texi(,1712) @item  C-c C-c d
1706texinfo.texi(,1713) @itemx M-x texinfo-insert-@@dfn
1707texinfo.texi(,1714) @findex texinfo-insert-@@dfn
1708texinfo.texi(,1715) Insert @code{@@dfn@{@}} and put the
1709texinfo.texi(,1716) cursor between the braces.@refill
1710texinfo.texi(,1717)
1711texinfo.texi(,1718) @item  C-c C-c e
1712texinfo.texi(,1719) @itemx M-x texinfo-insert-@@end
1713texinfo.texi(,1720) @findex texinfo-insert-@@end
1714texinfo.texi(,1721) Insert @code{@@end} and attempt to insert the correct following word,
1715texinfo.texi(,1722) such as @samp{example} or @samp{table}.  (This command does not handle
1716texinfo.texi(,1723) nested lists correctly, but inserts the word appropriate to the
1717texinfo.texi(,1724) immediately preceding list.)@refill
1718texinfo.texi(,1725)
1719texinfo.texi(,1726) @item  C-c C-c i
1720texinfo.texi(,1727) @itemx M-x texinfo-insert-@@item
1721texinfo.texi(,1728) @findex texinfo-insert-@@item
1722texinfo.texi(,1729) Insert @code{@@item} and put the
1723texinfo.texi(,1730) cursor at the beginning of the next line.@refill
1724texinfo.texi(,1731)
1725texinfo.texi(,1732) @item  C-c C-c k
1726texinfo.texi(,1733) @itemx M-x texinfo-insert-@@kbd
1727texinfo.texi(,1734) @findex texinfo-insert-@@kbd
1728texinfo.texi(,1735) Insert @code{@@kbd@{@}} and put the
1729texinfo.texi(,1736) cursor between the braces.@refill
1730texinfo.texi(,1737)
1731texinfo.texi(,1738) @item  C-c C-c n
1732texinfo.texi(,1739) @itemx M-x texinfo-insert-@@node
1733texinfo.texi(,1740) @findex texinfo-insert-@@node
1734texinfo.texi(,1741) Insert @code{@@node} and a comment line
1735texinfo.texi(,1742) listing the sequence for the `Next',
1736texinfo.texi(,1743) `Previous', and `Up' nodes.
1737texinfo.texi(,1744) Leave point after the @code{@@node}.@refill
1738texinfo.texi(,1745)
1739texinfo.texi(,1746) @item  C-c C-c o
1740texinfo.texi(,1747) @itemx M-x texinfo-insert-@@noindent
1741texinfo.texi(,1748) @findex texinfo-insert-@@noindent
1742texinfo.texi(,1749) Insert @code{@@noindent} and put the
1743texinfo.texi(,1750) cursor at the beginning of the next line.@refill
1744texinfo.texi(,1751)
1745texinfo.texi(,1752) @item  C-c C-c s
1746texinfo.texi(,1753) @itemx M-x texinfo-insert-@@samp
1747texinfo.texi(,1754) @findex texinfo-insert-@@samp
1748texinfo.texi(,1755) Insert @code{@@samp@{@}} and put the
1749texinfo.texi(,1756) cursor between the braces.@refill
1750texinfo.texi(,1757)
1751texinfo.texi(,1758) @item  C-c C-c t
1752texinfo.texi(,1759) @itemx M-x texinfo-insert-@@table
1753texinfo.texi(,1760) @findex texinfo-insert-@@table
1754texinfo.texi(,1761) Insert @code{@@table} followed by a @key{SPC}
1755texinfo.texi(,1762) and leave the cursor after the @key{SPC}.@refill
1756texinfo.texi(,1763)
1757texinfo.texi(,1764) @item  C-c C-c v
1758texinfo.texi(,1765) @itemx M-x texinfo-insert-@@var
1759texinfo.texi(,1766) @findex texinfo-insert-@@var
1760texinfo.texi(,1767) Insert @code{@@var@{@}} and put the
1761texinfo.texi(,1768) cursor between the braces.@refill
1762texinfo.texi(,1769)
1763texinfo.texi(,1770) @item  C-c C-c x
1764texinfo.texi(,1771) @itemx M-x texinfo-insert-@@example
1765texinfo.texi(,1772) @findex texinfo-insert-@@example
1766texinfo.texi(,1773) Insert @code{@@example} and put the
1767texinfo.texi(,1774) cursor at the beginning of the next line.@refill
1768texinfo.texi(,1775)
1769texinfo.texi(,1776) @c M-@{  was the binding for texinfo-insert-braces;
1770texinfo.texi(,1777) @c in Emacs 19, backward-paragraph will take this binding.
1771texinfo.texi(,1778) @item C-c C-c @{
1772texinfo.texi(,1779) @itemx M-x texinfo-insert-braces
1773texinfo.texi(,1780) @findex texinfo-insert-braces
1774texinfo.texi(,1781) Insert @code{@{@}} and put the cursor between the braces.@refill
1775texinfo.texi(,1782)
1776texinfo.texi(,1783) @item C-c C-c @}
1777texinfo.texi(,1784) @itemx C-c C-c ]
1778texinfo.texi(,1785) @itemx M-x up-list
1779texinfo.texi(,1786) @findex up-list
1780texinfo.texi(,1787) Move from between a pair of braces forward past the closing brace.
1781texinfo.texi(,1788) Typing @kbd{C-c C-c ]} is easier than typing @kbd{C-c C-c @}}, which
1782texinfo.texi(,1789) is, however, more mnemonic; hence the two keybindings.  (Also, you can
1783texinfo.texi(,1790) move out from between braces by typing @kbd{C-f}.)@refill
1784texinfo.texi(,1791) @end table
1785texinfo.texi(,1792)
1786texinfo.texi(,1793) To put a command such as @w{@code{@@code@{@dots{}@}}} around an
1787texinfo.texi(,1794) @emph{existing} word, position the cursor in front of the word and type
1788texinfo.texi(,1795) @kbd{C-u 1 C-c C-c c}.  This makes it easy to edit existing plain text.
1789texinfo.texi(,1796) The value of the prefix argument tells Emacs how many words following
1790texinfo.texi(,1797) point to include between braces---@samp{1} for one word, @samp{2} for
1791texinfo.texi(,1798) two words, and so on.  Use a negative argument to enclose the previous
1792texinfo.texi(,1799) word or words.  If you do not specify a prefix argument, Emacs inserts
1793texinfo.texi(,1800) the @@-command string and positions the cursor between the braces.  This
1794texinfo.texi(,1801) feature works only for those @@-commands that operate on a word or words
1795texinfo.texi(,1802) within one line, such as @code{@@kbd} and @code{@@var}.@refill
1796texinfo.texi(,1803)
1797texinfo.texi(,1804) This set of insert commands was created after analyzing the frequency
1798texinfo.texi(,1805) with which different @@-commands are used in the @cite{GNU Emacs
1799texinfo.texi(,1806) Manual} and the @cite{GDB Manual}.  If you wish to add your own insert
1800texinfo.texi(,1807) commands, you can bind a keyboard macro to a key, use abbreviations,
1801texinfo.texi(,1808) or extend the code in @file{texinfo.el}.@refill
1802texinfo.texi(,1809)
1803texinfo.texi(,1810) @findex texinfo-start-menu-description
1804texinfo.texi(,1811) @cindex Menu description, start
1805texinfo.texi(,1812) @cindex Description for menu, start
1806texinfo.texi(,1813) @kbd{C-c C-c C-d} (@code{texinfo-start-menu-description}) is an insert
1807texinfo.texi(,1814) command that works differently from the other insert commands.  It
1808texinfo.texi(,1815) inserts a node's section or chapter title in the space for the
1809texinfo.texi(,1816) description in a menu entry line.  (A menu entry has three parts, the
1810texinfo.texi(,1817) entry name, the node name, and the description.  Only the node name is
1811texinfo.texi(,1818) required, but a description helps explain what the node is about.
1812texinfo.texi(,1819) @xref{Menu Parts, , The Parts of a Menu}.)@refill
1813texinfo.texi(,1820)
1814texinfo.texi(,1821) To use @code{texinfo-start-menu-description}, position point in a menu
1815texinfo.texi(,1822) entry line and type @kbd{C-c C-c C-d}.  The command looks for and copies
1816texinfo.texi(,1823) the title that goes with the node name, and inserts the title as a
1817texinfo.texi(,1824) description; it positions point at beginning of the inserted text so you
1818texinfo.texi(,1825) can edit it.  The function does not insert the title if the menu entry
1819texinfo.texi(,1826) line already contains a description.@refill
1820texinfo.texi(,1827)
1821texinfo.texi(,1828) This command is only an aid to writing descriptions; it does not do the
1822texinfo.texi(,1829) whole job.  You must edit the inserted text since a title tends to use
1823texinfo.texi(,1830) the same words as a node name but a useful description uses different
1824texinfo.texi(,1831) words.@refill
1825texinfo.texi(,1832)
1826texinfo.texi(,1833) @node Showing the Structure, Updating Nodes and Menus, Inserting, Texinfo Mode
1827texinfo.texi(,1834) @comment  node-name,  next,  previous,  up
1828texinfo.texi(,1835) @section Showing the Section Structure of a File
1829texinfo.texi(,1836) @cindex Showing the section structure of a file
1830texinfo.texi(,1837) @cindex Section structure of a file, showing it
1831texinfo.texi(,1838) @cindex Structure of a file, showing it
1832texinfo.texi(,1839) @cindex Outline of file structure, showing it
1833texinfo.texi(,1840) @cindex Contents-like outline of file structure
1834texinfo.texi(,1841) @cindex File section structure, showing it
1835texinfo.texi(,1842) @cindex Texinfo file section structure, showing it
1836texinfo.texi(,1843)
1837texinfo.texi(,1844) You can show the section structure of a Texinfo file by using the
1838texinfo.texi(,1845) @kbd{C-c C-s} command (@code{texinfo-show-structure}).  This command
1839texinfo.texi(,1846) shows the section structure of a Texinfo file by listing the lines
1840texinfo.texi(,1847) that begin with the @@-commands for @code{@@chapter},
1841texinfo.texi(,1848) @code{@@section}, and the like.  It constructs what amounts
1842texinfo.texi(,1849) to a table of contents.  These lines are displayed in another buffer
1843texinfo.texi(,1850) called the @samp{*Occur*} buffer.  In that buffer, you can position
1844texinfo.texi(,1851) the cursor over one of the lines and use the @kbd{C-c C-c} command
1845texinfo.texi(,1852) (@code{occur-mode-goto-occurrence}), to jump to the corresponding spot
1846texinfo.texi(,1853) in the Texinfo file.@refill
1847texinfo.texi(,1854)
1848texinfo.texi(,1855) @table @kbd
1849texinfo.texi(,1856) @item  C-c C-s
1850texinfo.texi(,1857) @itemx M-x texinfo-show-structure
1851texinfo.texi(,1858) @findex texinfo-show-structure
1852texinfo.texi(,1859) Show the @code{@@chapter}, @code{@@section}, and such lines of a
1853texinfo.texi(,1860) Texinfo file.@refill
1854texinfo.texi(,1861)
1855texinfo.texi(,1862) @item  C-c C-c
1856texinfo.texi(,1863) @itemx M-x occur-mode-goto-occurrence
1857texinfo.texi(,1864) @findex occur-mode-goto-occurrence
1858texinfo.texi(,1865) Go to the line in the Texinfo file corresponding to the line under the
1859texinfo.texi(,1866) cursor in the @file{*Occur*} buffer.@refill
1860texinfo.texi(,1867) @end table
1861texinfo.texi(,1868)
1862texinfo.texi(,1869) If you call @code{texinfo-show-structure} with a prefix argument by
1863texinfo.texi(,1870) typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the
1864texinfo.texi(,1871) @@-commands for @code{@@chapter}, @code{@@section}, and the like, but
1865texinfo.texi(,1872) also the @code{@@node} lines.  You can use @code{texinfo-show-structure}
1866texinfo.texi(,1873) with a prefix argument to check whether the `Next', `Previous', and `Up'
1867texinfo.texi(,1874) pointers of an @code{@@node} line are correct.
1868texinfo.texi(,1875)
1869texinfo.texi(,1876) Often, when you are working on a manual, you will be interested only
1870texinfo.texi(,1877) in the structure of the current chapter.  In this case, you can mark
1871texinfo.texi(,1878) off the region of the buffer that you are interested in by using the
1872texinfo.texi(,1879) @kbd{C-x n n} (@code{narrow-to-region}) command and
1873texinfo.texi(,1880) @code{texinfo-show-structure} will work on only that region.  To see
1874texinfo.texi(,1881) the whole buffer again, use @w{@kbd{C-x n w}} (@code{widen}).
1875texinfo.texi(,1882) (@xref{Narrowing, , , emacs, The GNU Emacs Manual}, for more
1876texinfo.texi(,1883) information about the narrowing commands.)@refill
1877texinfo.texi(,1884)
1878texinfo.texi(,1885) @vindex page-delimiter
1879texinfo.texi(,1886) @cindex Page delimiter in Texinfo mode
1880texinfo.texi(,1887) In addition to providing the @code{texinfo-show-structure} command,
1881texinfo.texi(,1888) Texinfo mode sets the value of the page delimiter variable to match
1882texinfo.texi(,1889) the chapter-level @@-commands.  This enables you to use the @kbd{C-x
1883texinfo.texi(,1890) ]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page})
1884texinfo.texi(,1891) commands to move forward and backward by chapter, and to use the
1885texinfo.texi(,1892) @kbd{C-x p} (@code{narrow-to-page}) command to narrow to a chapter.
1886texinfo.texi(,1893) @xref{Pages, , , emacs, The GNU Emacs Manual}, for more information
1887texinfo.texi(,1894) about the page commands.@refill
1888texinfo.texi(,1895)
1889texinfo.texi(,1896) @node Updating Nodes and Menus, Info Formatting, Showing the Structure, Texinfo Mode
1890texinfo.texi(,1897) @comment  node-name,  next,  previous,  up
1891texinfo.texi(,1898) @section Updating Nodes and Menus
1892texinfo.texi(,1899) @cindex Updating nodes and menus
1893texinfo.texi(,1900) @cindex Create nodes, menus automatically
1894texinfo.texi(,1901) @cindex Insert nodes, menus automatically
1895texinfo.texi(,1902) @cindex Automatically insert nodes, menus
1896texinfo.texi(,1903)
1897texinfo.texi(,1904) Texinfo mode provides commands for automatically creating or updating
1898texinfo.texi(,1905) menus and node pointers.  The commands are called ``update'' commands
1899texinfo.texi(,1906) because their most frequent use is for updating a Texinfo file after you
1900texinfo.texi(,1907) have worked on it; but you can use them to insert the `Next',
1901texinfo.texi(,1908) `Previous', and `Up' pointers into an @code{@@node} line that has none
1902texinfo.texi(,1909) and to create menus in a file that has none.
1903texinfo.texi(,1910)
1904texinfo.texi(,1911) If you do not use the updating commands, you need to write menus and
1905texinfo.texi(,1912) node pointers by hand, which is a tedious task.@refill
1906texinfo.texi(,1913)
1907texinfo.texi(,1914) @menu
1908texinfo.texi(,1915) * Updating Commands::           Five major updating commands.
1909texinfo.texi(,1916) * Updating Requirements::       How to structure a Texinfo file for
1910texinfo.texi(,1917)                                   using the updating command.
1911texinfo.texi(,1918) * Other Updating Commands::     How to indent descriptions, insert
1912texinfo.texi(,1919)                                   missing nodes lines, and update
1913texinfo.texi(,1920)                                   nodes in sequence.
1914texinfo.texi(,1921) @end menu
1915texinfo.texi(,1922)
1916texinfo.texi(,1923) @node Updating Commands, Updating Requirements, Updating Nodes and Menus, Updating Nodes and Menus
1917texinfo.texi(,1925) @subheading The Updating Commands
1918texinfo.texi(,1927)
1919texinfo.texi(,1928) You can use the updating commands to:@refill
1920texinfo.texi(,1929)
1921texinfo.texi(,1930) @itemize @bullet
1922texinfo.texi(,1931) @item
1923texinfo.texi(,1932) insert or update the `Next', `Previous', and `Up' pointers of a
1924texinfo.texi(,1933) node,@refill
1925texinfo.texi(,1934)
1926texinfo.texi(,1935) @item
1927texinfo.texi(,1936) insert or update the menu for a section, and@refill
1928texinfo.texi(,1937)
1929texinfo.texi(,1938) @item
1930texinfo.texi(,1939) create a master menu for a Texinfo source file.@refill
1931texinfo.texi(,1940) @end itemize
1932texinfo.texi(,1941)
1933texinfo.texi(,1942) You can also use the commands to update all the nodes and menus in a
1934texinfo.texi(,1943) region or in a whole Texinfo file.@refill
1935texinfo.texi(,1944)
1936texinfo.texi(,1945) The updating commands work only with conventional Texinfo files, which
1937texinfo.texi(,1946) are structured hierarchically like books.  In such files, a structuring
1938texinfo.texi(,1947) command line must follow closely after each @code{@@node} line, except
1939texinfo.texi(,1948) for the `Top' @code{@@node} line.  (A @dfn{structuring command line} is
1940texinfo.texi(,1949) a line beginning with @code{@@chapter}, @code{@@section}, or other
1941texinfo.texi(,1950) similar command.)
1942texinfo.texi(,1951)
1943texinfo.texi(,1952) You can write the structuring command line on the line that follows
1944texinfo.texi(,1953) immediately after an @code{@@node} line or else on the line that
1945texinfo.texi(,1954) follows after a single @code{@@comment} line or a single
1946texinfo.texi(,1955) @code{@@ifinfo} line.  You cannot interpose more than one line between
1947texinfo.texi(,1956) the @code{@@node} line and the structuring command line; and you may
1948texinfo.texi(,1957) interpose only an @code{@@comment} line or an @code{@@ifinfo} line.
1949texinfo.texi(,1958)
1950texinfo.texi(,1959) Commands which work on a whole buffer require that the `Top' node be
1951texinfo.texi(,1960) followed by a node with an @code{@@chapter} or equivalent-level command.
1952texinfo.texi(,1961) The menu updating commands will not create a main or master menu for a
1953texinfo.texi(,1962) Texinfo file that has only @code{@@chapter}-level nodes!  The menu
1954texinfo.texi(,1963) updating commands only create menus @emph{within} nodes for lower level
1955texinfo.texi(,1964) nodes.  To create a menu of chapters, you must provide a `Top'
1956texinfo.texi(,1965) node.
1957texinfo.texi(,1966)
1958texinfo.texi(,1967) The menu updating commands remove menu entries that refer to other Info
1959texinfo.texi(,1968) files since they do not refer to nodes within the current buffer.  This
1960texinfo.texi(,1969) is a deficiency.  Rather than use menu entries, you can use cross
1961texinfo.texi(,1970) references to refer to other Info files.  None of the updating commands
1962texinfo.texi(,1971) affect cross references.@refill
1963texinfo.texi(,1972)
1964texinfo.texi(,1973) Texinfo mode has five updating commands that are used most often: two
1965texinfo.texi(,1974) are for updating the node pointers or menu of a single node (or a
1966texinfo.texi(,1975) region); two are for updating every node pointer and menu in a file;
1967texinfo.texi(,1976) and one, the @code{texinfo-master-menu} command, is for creating a
1968texinfo.texi(,1977) master menu for a complete file, and optionally, for updating every
1969texinfo.texi(,1978) node and menu in the whole Texinfo file.@refill
1970texinfo.texi(,1979)
1971texinfo.texi(,1980) The @code{texinfo-master-menu} command is the primary command:@refill
1972texinfo.texi(,1981)
1973texinfo.texi(,1982) @table @kbd
1974texinfo.texi(,1983) @item C-c C-u m
1975texinfo.texi(,1984) @itemx M-x texinfo-master-menu
1976texinfo.texi(,1985) @findex texinfo-master-menu
1977texinfo.texi(,1986) Create or update a master menu that includes all the other menus
1978texinfo.texi(,1987) (incorporating the descriptions from pre-existing menus, if
1979texinfo.texi(,1988) any).@refill
1980texinfo.texi(,1989)
1981texinfo.texi(,1990) With an argument (prefix argument, @kbd{C-u,} if interactive), first create or
1982texinfo.texi(,1991) update all the nodes and all the regular menus in the buffer before
1983texinfo.texi(,1992) constructing the master menu.  (@xref{The Top Node, , The Top Node and
1984texinfo.texi(,1993) Master Menu}, for more about a master menu.)@refill
1985texinfo.texi(,1994)
1986texinfo.texi(,1995) For @code{texinfo-master-menu} to work, the Texinfo file must have a
1987texinfo.texi(,1996) `Top' node and at least one subsequent node.@refill
1988texinfo.texi(,1997)
1989texinfo.texi(,1998) After extensively editing a Texinfo file, you can type the following:
1990texinfo.texi(,1999)
1991texinfo.texi(,2000) @example
1992texinfo.texi(,2001) C-u M-x texinfo-master-menu
1993texinfo.texi(,2002) @exdent or
1994texinfo.texi(,2003) C-u C-c C-u m
1995texinfo.texi(,2004) @end example
1996texinfo.texi(,2005)
1997texinfo.texi(,2006) @noindent
1998texinfo.texi(,2007) This updates all the nodes and menus completely and all at once.@refill
1999texinfo.texi(,2008) @end table
2000texinfo.texi(,2009)
2001texinfo.texi(,2010) The other major updating commands do smaller jobs and are designed for
2002texinfo.texi(,2011) the person who updates nodes and menus as he or she writes a Texinfo
2003texinfo.texi(,2012) file.@refill
2004texinfo.texi(,2013)
2005texinfo.texi(,2014) @need 1000
2006texinfo.texi(,2015) The commands are:@refill
2007texinfo.texi(,2016)
2008texinfo.texi(,2017) @table @kbd
2009texinfo.texi(,2018) @item C-c C-u C-n
2010texinfo.texi(,2019) @itemx M-x texinfo-update-node
2011texinfo.texi(,2020) @findex texinfo-update-node
2012texinfo.texi(,2021) Insert the `Next', `Previous', and `Up' pointers for the node that point is
2013texinfo.texi(,2022) within (i.e., for the @code{@@node} line preceding point).  If the
2014texinfo.texi(,2023) @code{@@node} line has pre-existing `Next', `Previous', or `Up'
2015texinfo.texi(,2024) pointers in it, the old pointers are removed and new ones inserted.
2016texinfo.texi(,2025) With an argument (prefix argument, @kbd{C-u}, if interactive), this command
2017texinfo.texi(,2026) updates all @code{@@node} lines in the region (which is the text
2018texinfo.texi(,2027) between point and mark).@refill
2019texinfo.texi(,2028)
2020texinfo.texi(,2029) @item C-c C-u C-m
2021texinfo.texi(,2030) @itemx M-x texinfo-make-menu
2022texinfo.texi(,2031) @findex texinfo-make-menu
2023texinfo.texi(,2032) Create or update the menu in the node that point is within.
2024texinfo.texi(,2033) With an argument (@kbd{C-u} as prefix argument, if
2025texinfo.texi(,2034) interactive), the command makes or updates menus for the
2026texinfo.texi(,2035) nodes which are either within or a part of the
2027texinfo.texi(,2036) region.@refill
2028texinfo.texi(,2037)
2029texinfo.texi(,2038) Whenever @code{texinfo-make-menu} updates an existing menu, the
2030texinfo.texi(,2039) descriptions from that menu are incorporated into the new menu.  This
2031texinfo.texi(,2040) is done by copying descriptions from the existing menu to the entries
2032texinfo.texi(,2041) in the new menu that have the same node names.  If the node names are
2033texinfo.texi(,2042) different, the descriptions are not copied to the new menu.@refill
2034texinfo.texi(,2043)
2035texinfo.texi(,2044) @item C-c C-u C-e
2036texinfo.texi(,2045) @itemx M-x texinfo-every-node-update
2037texinfo.texi(,2046) @findex texinfo-every-node-update
2038texinfo.texi(,2047) Insert or update the `Next', `Previous', and `Up' pointers for every
2039texinfo.texi(,2048) node in the buffer.@refill
2040texinfo.texi(,2049)
2041texinfo.texi(,2050) @item C-c C-u C-a
2042texinfo.texi(,2051) @itemx M-x texinfo-all-menus-update
2043texinfo.texi(,2052) @findex texinfo-all-menus-update
2044texinfo.texi(,2053) Create or update all the menus in the buffer.  With an argument
2045texinfo.texi(,2054) (@kbd{C-u} as prefix argument, if interactive), first insert
2046texinfo.texi(,2055) or update all the node
2047texinfo.texi(,2056) pointers before working on the menus.@refill
2048texinfo.texi(,2057)
2049texinfo.texi(,2058) If a master menu exists, the @code{texinfo-all-menus-update} command
2050texinfo.texi(,2059) updates it; but the command does not create a new master menu if none
2051texinfo.texi(,2060) already exists.  (Use the @code{texinfo-master-menu} command for
2052texinfo.texi(,2061) that.)@refill
2053texinfo.texi(,2062)
2054texinfo.texi(,2063) When working on a document that does not merit a master menu, you can
2055texinfo.texi(,2064) type the following:
2056texinfo.texi(,2065)
2057texinfo.texi(,2066) @example
2058texinfo.texi(,2067) C-u C-c C-u C-a
2059texinfo.texi(,2068) @exdent or
2060texinfo.texi(,2069) C-u M-x texinfo-all-menus-update
2061texinfo.texi(,2070) @end example
2062texinfo.texi(,2071)
2063texinfo.texi(,2072) @noindent
2064texinfo.texi(,2073) This updates all the nodes and menus.@refill
2065texinfo.texi(,2074) @end table
2066texinfo.texi(,2075)
2067texinfo.texi(,2076) The @code{texinfo-column-for-description} variable specifies the
2068texinfo.texi(,2077) column to which menu descriptions are indented.  By default, the value
2069texinfo.texi(,2078) is 32 although it is often useful to reduce it to as low as 24.  You
2070texinfo.texi(,2079) can set the variable with the @kbd{M-x edit-options} command
2071texinfo.texi(,2080) (@pxref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs
2072texinfo.texi(,2081) Manual}) or with the @kbd{M-x set-variable} command (@pxref{Examining,
2073texinfo.texi(,2082) , Examining and Setting Variables, emacs, The GNU Emacs
2074texinfo.texi(,2083) Manual}).@refill
2075texinfo.texi(,2084)
2076texinfo.texi(,2085) Also, the @code{texinfo-indent-menu-description} command may be used to
2077texinfo.texi(,2086) indent existing menu descriptions to a specified column.  Finally, if
2078texinfo.texi(,2087) you wish, you can use the @code{texinfo-insert-node-lines} command to
2079texinfo.texi(,2088) insert missing @code{@@node} lines into a file.  (@xref{Other Updating
2080texinfo.texi(,2089) Commands}, for more information.)@refill
2081texinfo.texi(,2090)
2082texinfo.texi(,2091) @node Updating Requirements
2083texinfo.texi(,2092) @subsection Updating Requirements
2084texinfo.texi(,2093) @cindex Updating requirements
2085texinfo.texi(,2094) @cindex Requirements for updating commands
2086texinfo.texi(,2095)
2087texinfo.texi(,2096) To use the updating commands, you must organize the Texinfo file
2088texinfo.texi(,2097) hierarchically with chapters, sections, subsections, and the like.
2089texinfo.texi(,2098) When you construct the hierarchy of the manual, do not `jump down'
2090texinfo.texi(,2099) more than one level at a time: you can follow the `Top' node with a
2091texinfo.texi(,2100) chapter, but not with a section; you can follow a chapter with a
2092texinfo.texi(,2101) section, but not with a subsection.  However, you may `jump up' any
2093texinfo.texi(,2102) number of levels at one time---for example, from a subsection to a
2094texinfo.texi(,2103) chapter.@refill
2095texinfo.texi(,2104)
2096texinfo.texi(,2105) Each @code{@@node} line, with the exception of the line for the `Top'
2097texinfo.texi(,2106) node, must be followed by a line with a structuring command such as
2098texinfo.texi(,2107) @code{@@chapter}, @code{@@section}, or
2099texinfo.texi(,2108) @code{@@unnumberedsubsec}.@refill
2100texinfo.texi(,2109)
2101texinfo.texi(,2110) Each @code{@@node} line/structuring-command line combination
2102texinfo.texi(,2111) must look either like this:
2103texinfo.texi(,2112)
2104texinfo.texi(,2113) @example
2105texinfo.texi(,2114) @group
2106texinfo.texi(,2115) @@node     Comments,  Minimum, Conventions, Overview
2107texinfo.texi(,2116) @@comment  node-name, next,    previous,    up
2108texinfo.texi(,2117) @@section Comments
2109texinfo.texi(,2118) @end group
2110texinfo.texi(,2119) @end example
2111texinfo.texi(,2120)
2112texinfo.texi(,2121) or like this (without the @code{@@comment} line):
2113texinfo.texi(,2122)
2114texinfo.texi(,2123) @example
2115texinfo.texi(,2124) @group
2116texinfo.texi(,2125) @@node Comments, Minimum, Conventions, Overview
2117texinfo.texi(,2126) @@section Comments
2118texinfo.texi(,2127) @end group
2119texinfo.texi(,2128) @end example
2120texinfo.texi(,2129)
2121texinfo.texi(,2130) or like this (without the explicit node pointers):
2122texinfo.texi(,2131)
2123texinfo.texi(,2132) @example
2124texinfo.texi(,2133) @group
2125texinfo.texi(,2134) @@node Comments
2126texinfo.texi(,2135) @@section Comments
2127texinfo.texi(,2136) @end group
2128texinfo.texi(,2137) @end example
2129texinfo.texi(,2138)
2130texinfo.texi(,2139) @noindent
2131texinfo.texi(,2140) In this example, `Comments' is the name of both the node and the
2132texinfo.texi(,2141) section.  The next node is called `Minimum' and the previous node is
2133texinfo.texi(,2142) called `Conventions'.  The `Comments' section is within the `Overview'
2134texinfo.texi(,2143) node, which is specified by the `Up' pointer.  (Instead of an
2135texinfo.texi(,2144) @code{@@comment} line, you may also write an @code{@@ifinfo} line.)
2136texinfo.texi(,2145)
2137texinfo.texi(,2146) If a file has a `Top' node, it must be called @samp{top} or @samp{Top}
2138texinfo.texi(,2147) and be the first node in the file.
2139texinfo.texi(,2148)
2140texinfo.texi(,2149) The menu updating commands create a menu of sections within a chapter,
2141texinfo.texi(,2150) a menu of subsections within a section, and so on.  This means that
2142texinfo.texi(,2151) you must have a `Top' node if you want a menu of chapters.@refill
2143texinfo.texi(,2152)
2144texinfo.texi(,2153) Incidentally, the @code{makeinfo} command will create an Info file for a
2145texinfo.texi(,2154) hierarchically organized Texinfo file that lacks `Next', `Previous' and
2146texinfo.texi(,2155) `Up' pointers.  Thus, if you can be sure that your Texinfo file will be
2147texinfo.texi(,2156) formatted with @code{makeinfo}, you have no need for the update node
2148texinfo.texi(,2157) commands.  (@xref{Creating an Info File}, for more information about
2149texinfo.texi(,2158) @code{makeinfo}.)  However, both @code{makeinfo} and the
2150texinfo.texi(,2159) @code{texinfo-format-@dots{}} commands require that you insert menus in
2151texinfo.texi(,2160) the file.
2152texinfo.texi(,2161)
2153texinfo.texi(,2162)
2154texinfo.texi(,2163) @node Other Updating Commands
2155texinfo.texi(,2164) @subsection Other Updating Commands
2156texinfo.texi(,2165)
2157texinfo.texi(,2166) In addition to the five major updating commands, Texinfo mode
2158texinfo.texi(,2167) possesses several less frequently used updating commands:@refill
2159texinfo.texi(,2168)
2160texinfo.texi(,2169) @table @kbd
2161texinfo.texi(,2170) @item M-x texinfo-insert-node-lines
2162texinfo.texi(,2171) @findex texinfo-insert-node-lines
2163texinfo.texi(,2172) Insert @code{@@node} lines before the @code{@@chapter},
2164texinfo.texi(,2173) @code{@@section}, and other sectioning commands wherever they are
2165texinfo.texi(,2174) missing throughout a region in a Texinfo file.@refill
2166texinfo.texi(,2175)
2167texinfo.texi(,2176) With an argument (@kbd{C-u} as prefix argument, if interactive), the
2168texinfo.texi(,2177) @code{texinfo-insert-node-lines} command not only inserts
2169texinfo.texi(,2178) @code{@@node} lines but also inserts the chapter or section titles as
2170texinfo.texi(,2179) the names of the corresponding nodes.  In addition, it inserts the
2171texinfo.texi(,2180) titles as node names in pre-existing @code{@@node} lines that lack
2172texinfo.texi(,2181) names.  Since node names should be more concise than section or
2173texinfo.texi(,2182) chapter titles, you must manually edit node names so inserted.@refill
2174texinfo.texi(,2183)
2175texinfo.texi(,2184) For example, the following marks a whole buffer as a region and inserts
2176texinfo.texi(,2185) @code{@@node} lines and titles throughout:@refill
2177texinfo.texi(,2186)
2178texinfo.texi(,2187) @example
2179texinfo.texi(,2188) C-x h C-u M-x texinfo-insert-node-lines
2180texinfo.texi(,2189) @end example
2181texinfo.texi(,2190)
2182texinfo.texi(,2191) This command inserts titles as node names in @code{@@node} lines; the
2183texinfo.texi(,2192) @code{texinfo-start-menu-description} command (@pxref{Inserting,
2184texinfo.texi(,2193) Inserting Frequently Used Commands}) inserts titles as descriptions in
2185texinfo.texi(,2194) menu entries, a different action.  However, in both cases, you need to
2186texinfo.texi(,2195) edit the inserted text.
2187texinfo.texi(,2196)
2188texinfo.texi(,2197) @item M-x texinfo-multiple-files-update
2189texinfo.texi(,2198) @findex texinfo-multiple-files-update @r{(in brief)}
2190texinfo.texi(,2199) Update nodes and menus in a document built from several separate files.
2191texinfo.texi(,2200) With @kbd{C-u} as a prefix argument, create and insert a master menu in
2192texinfo.texi(,2201) the outer file.  With a numeric prefix argument, such as @kbd{C-u 2}, first
2193texinfo.texi(,2202) update all the menus and all the `Next', `Previous', and `Up' pointers
2194texinfo.texi(,2203) of all the included files before creating and inserting a master menu in
2195texinfo.texi(,2204) the outer file.  The @code{texinfo-multiple-files-update} command is
2196texinfo.texi(,2205) described in the appendix on @code{@@include} files.
2197texinfo.texi(,2207) @xref{texinfo-multiple-files-update}.@refill
2198texinfo.texi(,2213)
2199texinfo.texi(,2214) @item M-x texinfo-indent-menu-description
2200texinfo.texi(,2215) @findex texinfo-indent-menu-description
2201texinfo.texi(,2216) Indent every description in the menu following point to the specified
2202texinfo.texi(,2217) column.  You can use this command to give yourself more space for
2203texinfo.texi(,2218) descriptions.  With an argument (@kbd{C-u} as prefix argument, if
2204texinfo.texi(,2219) interactive), the @code{texinfo-indent-menu-description} command indents
2205texinfo.texi(,2220) every description in every menu in the region.  However, this command
2206texinfo.texi(,2221) does not indent the second and subsequent lines of a multi-line
2207texinfo.texi(,2222) description.@refill
2208texinfo.texi(,2223)
2209texinfo.texi(,2224) @item M-x texinfo-sequential-node-update
2210texinfo.texi(,2225) @findex texinfo-sequential-node-update
2211texinfo.texi(,2226) Insert the names of the nodes immediately following and preceding the
2212texinfo.texi(,2227) current node as the `Next' or `Previous' pointers regardless of those
2213texinfo.texi(,2228) nodes' hierarchical level.  This means that the `Next' node of a
2214texinfo.texi(,2229) subsection may well be the next chapter.  Sequentially ordered nodes are
2215texinfo.texi(,2230) useful for novels and other documents that you read through
2216texinfo.texi(,2231) sequentially.  (However, in Info, the @kbd{g *} command lets
2217texinfo.texi(,2232) you look through the file sequentially, so sequentially ordered nodes
2218texinfo.texi(,2233) are not strictly necessary.)  With an argument (prefix argument, if
2219texinfo.texi(,2234) interactive), the @code{texinfo-sequential-node-update} command
2220texinfo.texi(,2235) sequentially updates all the nodes in the region.@refill
2221texinfo.texi(,2236) @end table
2222texinfo.texi(,2237)
2223texinfo.texi(,2238) @node Info Formatting, Printing, Updating Nodes and Menus, Texinfo Mode
2224texinfo.texi(,2239) @comment  node-name,  next,  previous,  up
2225texinfo.texi(,2240) @section Formatting for Info
2226texinfo.texi(,2241) @cindex Formatting for Info
2227texinfo.texi(,2242) @cindex Running an Info formatter
2228texinfo.texi(,2243) @cindex Info formatting
2229texinfo.texi(,2244)
2230texinfo.texi(,2245) Texinfo mode provides several commands for formatting part or all of a
2231texinfo.texi(,2246) Texinfo file for Info.  Often, when you are writing a document, you
2232texinfo.texi(,2247) want to format only part of a file---that is, a region.@refill
2233texinfo.texi(,2248)
2234texinfo.texi(,2249) You can use either the @code{texinfo-format-region} or the
2235texinfo.texi(,2250) @code{makeinfo-region} command to format a region:@refill
2236texinfo.texi(,2251)
2237texinfo.texi(,2252) @table @kbd
2238texinfo.texi(,2253) @findex texinfo-format-region
2239texinfo.texi(,2254) @item  C-c C-e C-r
2240texinfo.texi(,2255) @itemx M-x texinfo-format-region
2241texinfo.texi(,2256) @itemx C-c C-m C-r
2242texinfo.texi(,2257) @itemx M-x makeinfo-region
2243texinfo.texi(,2258) Format the current region for Info.@refill
2244texinfo.texi(,2259) @end table
2245texinfo.texi(,2260)
2246texinfo.texi(,2261) You can use either the @code{texinfo-format-buffer} or the
2247texinfo.texi(,2262) @code{makeinfo-buffer} command to format a whole buffer:@refill
2248texinfo.texi(,2263)
2249texinfo.texi(,2264) @table @kbd
2250texinfo.texi(,2265) @findex texinfo-format-buffer
2251texinfo.texi(,2266) @item  C-c C-e C-b
2252texinfo.texi(,2267) @itemx M-x texinfo-format-buffer
2253texinfo.texi(,2268) @itemx C-c C-m C-b
2254texinfo.texi(,2269) @itemx M-x makeinfo-buffer
2255texinfo.texi(,2270) Format the current buffer for Info.@refill
2256texinfo.texi(,2271) @end table
2257texinfo.texi(,2272)
2258texinfo.texi(,2273) @need 1000
2259texinfo.texi(,2274) For example, after writing a Texinfo file, you can type the following:
2260texinfo.texi(,2275)
2261texinfo.texi(,2276) @example
2262texinfo.texi(,2277) C-u C-c C-u m
2263texinfo.texi(,2278) @exdent or
2264texinfo.texi(,2279) C-u M-x texinfo-master-menu
2265texinfo.texi(,2280) @end example
2266texinfo.texi(,2281)
2267texinfo.texi(,2282) @noindent
2268texinfo.texi(,2283) This updates all the nodes and menus.  Then type the following to create
2269texinfo.texi(,2284) an Info file:
2270texinfo.texi(,2285)
2271texinfo.texi(,2286) @example
2272texinfo.texi(,2287) C-c C-m C-b
2273texinfo.texi(,2288) @exdent or
2274texinfo.texi(,2289) M-x makeinfo-buffer
2275texinfo.texi(,2290) @end example
2276texinfo.texi(,2291)
2277texinfo.texi(,2292) For @TeX{} or the Info formatting commands to work, the file @emph{must}
2278texinfo.texi(,2293) include a line that has @code{@@setfilename} in its header.
2279texinfo.texi(,2294)
2280texinfo.texi(,2295) @xref{Creating an Info File}, for details about Info formatting.@refill
2281texinfo.texi(,2296)
2282texinfo.texi(,2297) @node Printing, Texinfo Mode Summary, Info Formatting, Texinfo Mode
2283texinfo.texi(,2298) @comment node-name,  next,  previous,  up
2284texinfo.texi(,2299) @section Formatting and Printing
2285texinfo.texi(,2300) @cindex Formatting for printing
2286texinfo.texi(,2301) @cindex Printing a region or buffer
2287texinfo.texi(,2302) @cindex Region formatting and printing
2288texinfo.texi(,2303) @cindex Buffer formatting and printing
2289texinfo.texi(,2304) @cindex Part of file formatting and printing
2290texinfo.texi(,2305)
2291texinfo.texi(,2306) Typesetting and printing a Texinfo file is a multi-step process in which
2292texinfo.texi(,2307) you first create a file for printing (called a DVI file), and then
2293texinfo.texi(,2308) print the file.  Optionally, you may also create indices.  To do this,
2294texinfo.texi(,2309) you must run the @code{texindex} command after first running the
2295texinfo.texi(,2310) @code{tex} typesetting command; and then you must run the @code{tex}
2296texinfo.texi(,2311) command again.  Or else run the @code{texi2dvi} command which
2297texinfo.texi(,2312) automatically creates indices as needed (@pxref{Format with texi2dvi}).
2298texinfo.texi(,2313)
2299texinfo.texi(,2314) Often, when you are writing a document, you want to typeset and print
2300texinfo.texi(,2315) only part of a file to see what it will look like.  You can use the
2301texinfo.texi(,2316) @code{texinfo-tex-region} and related commands for this purpose.  Use
2302texinfo.texi(,2317) the @code{texinfo-tex-buffer} command to format all of a
2303texinfo.texi(,2318) buffer.@refill
2304texinfo.texi(,2319)
2305texinfo.texi(,2320) @table @kbd
2306texinfo.texi(,2321) @item  C-c C-t C-b
2307texinfo.texi(,2322) @itemx M-x texinfo-tex-buffer
2308texinfo.texi(,2323) @findex texinfo-tex-buffer
2309texinfo.texi(,2324) Run @code{texi2dvi} on the buffer.  In addition to running @TeX{} on the
2310texinfo.texi(,2325) buffer, this command automatically creates or updates indices as
2311texinfo.texi(,2326) needed.@refill
2312texinfo.texi(,2327)
2313texinfo.texi(,2328) @item  C-c C-t C-r
2314texinfo.texi(,2329) @itemx M-x texinfo-tex-region
2315texinfo.texi(,2330) @findex texinfo-tex-region
2316texinfo.texi(,2331) Run @TeX{} on the region.@refill
2317texinfo.texi(,2332)
2318texinfo.texi(,2333) @item C-c C-t C-i
2319texinfo.texi(,2334) @itemx M-x texinfo-texindex
2320texinfo.texi(,2335) Run @code{texindex} to sort the indices of a Texinfo file formatted with
2321texinfo.texi(,2336) @code{texinfo-tex-region}.  The @code{texinfo-tex-region} command does
2322texinfo.texi(,2337) not run @code{texindex} automatically; it only runs the @code{tex}
2323texinfo.texi(,2338) typesetting command.  You must run the @code{texinfo-tex-region} command
2324texinfo.texi(,2339) a second time after sorting the raw index files with the @code{texindex}
2325texinfo.texi(,2340) command.  (Usually, you do not format an index when you format a region,
2326texinfo.texi(,2341) only when you format a buffer.  Now that the @code{texi2dvi} command
2327texinfo.texi(,2342) exists, there is little or no need for this command.)@refill
2328texinfo.texi(,2343)
2329texinfo.texi(,2344) @item C-c C-t C-p
2330texinfo.texi(,2345) @itemx M-x texinfo-tex-print
2331texinfo.texi(,2346) @findex texinfo-tex-print
2332texinfo.texi(,2347) Print the file (or the part of the file) previously formatted with
2333texinfo.texi(,2348) @code{texinfo-tex-buffer} or @code{texinfo-tex-region}.@refill
2334texinfo.texi(,2349) @end table
2335texinfo.texi(,2350)
2336texinfo.texi(,2351) For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the
2337texinfo.texi(,2352) file @emph{must} start with a @samp{\input texinfo} line and must
2338texinfo.texi(,2353) include an @code{@@settitle} line.  The file must end with @code{@@bye}
2339texinfo.texi(,2354) on a line by itself.  (When you use @code{texinfo-tex-region}, you must
2340texinfo.texi(,2355) surround the @code{@@settitle} line with start-of-header and
2341texinfo.texi(,2356) end-of-header lines.)@refill
2342texinfo.texi(,2357)
2343texinfo.texi(,2358) @xref{Hardcopy}, for a description of the other @TeX{} related
2344texinfo.texi(,2359) commands, such as @code{tex-show-print-queue}.@refill
2345texinfo.texi(,2360)
2346texinfo.texi(,2361) @node Texinfo Mode Summary,  , Printing, Texinfo Mode
2347texinfo.texi(,2362) @comment  node-name,  next,  previous,  up
2348texinfo.texi(,2363) @section Texinfo Mode Summary
2349texinfo.texi(,2364)
2350texinfo.texi(,2365) In Texinfo mode, each set of commands has default keybindings that
2351texinfo.texi(,2366) begin with the same keys.  All the commands that are custom-created
2352texinfo.texi(,2367) for Texinfo mode begin with @kbd{C-c}.  The keys are somewhat
2353texinfo.texi(,2368) mnemonic.@refill
2354texinfo.texi(,2369)
2355texinfo.texi(,2370) @subheading Insert Commands
2356texinfo.texi(,2371)
2357texinfo.texi(,2372) The insert commands are invoked by typing @kbd{C-c} twice and then the
2358texinfo.texi(,2373) first letter of the @@-command to be inserted.  (It might make more
2359texinfo.texi(,2374) sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but
2360texinfo.texi(,2375) @kbd{C-c C-c} is quick to type.)@refill
2361texinfo.texi(,2376)
2362texinfo.texi(,2377) @example
2363texinfo.texi(,2378) C-c C-c c       @r{Insert} @samp{@@code}.
2364texinfo.texi(,2379) C-c C-c d       @r{Insert} @samp{@@dfn}.
2365texinfo.texi(,2380) C-c C-c e       @r{Insert} @samp{@@end}.
2366texinfo.texi(,2381) C-c C-c i       @r{Insert} @samp{@@item}.
2367texinfo.texi(,2382) C-c C-c n       @r{Insert} @samp{@@node}.
2368texinfo.texi(,2383) C-c C-c s       @r{Insert} @samp{@@samp}.
2369texinfo.texi(,2384) C-c C-c v       @r{Insert} @samp{@@var}.
2370texinfo.texi(,2385) C-c C-c @{       @r{Insert braces.}
2371texinfo.texi(,2386) C-c C-c ]
2372texinfo.texi(,2387) C-c C-c @}       @r{Move out of enclosing braces.}
2373texinfo.texi(,2388)
2374texinfo.texi(,2389) @group
2375texinfo.texi(,2390) C-c C-c C-d     @r{Insert a node's section title}
2376texinfo.texi(,2391)                 @r{in the space for the description}
2377texinfo.texi(,2392)                 @r{in a menu entry line.}
2378texinfo.texi(,2393) @end group
2379texinfo.texi(,2394) @end example
2380texinfo.texi(,2395)
2381texinfo.texi(,2396) @subheading Show Structure
2382texinfo.texi(,2397)
2383texinfo.texi(,2398) The @code{texinfo-show-structure} command is often used within a
2384texinfo.texi(,2399) narrowed region.@refill
2385texinfo.texi(,2400)
2386texinfo.texi(,2401) @example
2387texinfo.texi(,2402) C-c C-s         @r{List all the headings.}
2388texinfo.texi(,2403) @end example
2389texinfo.texi(,2404)
2390texinfo.texi(,2405) @subheading The Master Update Command
2391texinfo.texi(,2406)
2392texinfo.texi(,2407) The @code{texinfo-master-menu} command creates a master menu; and can
2393texinfo.texi(,2408) be used to update every node and menu in a file as well.@refill
2394texinfo.texi(,2409)
2395texinfo.texi(,2410) @c Probably should use @tables in this section.
2396texinfo.texi(,2411) @example
2397texinfo.texi(,2412) @group
2398texinfo.texi(,2413) C-c C-u m
2399texinfo.texi(,2414) M-x texinfo-master-menu
2400texinfo.texi(,2415)                 @r{Create or update a master menu.}
2401texinfo.texi(,2416) @end group
2402texinfo.texi(,2417)
2403texinfo.texi(,2418) @group
2404texinfo.texi(,2419) C-u C-c C-u m   @r{With @kbd{C-u} as a prefix argument, first}
2405texinfo.texi(,2420)                 @r{create or update all nodes and regular}
2406texinfo.texi(,2421)                 @r{menus, and then create a master menu.}
2407texinfo.texi(,2422) @end group
2408texinfo.texi(,2423) @end example
2409texinfo.texi(,2424)
2410texinfo.texi(,2425) @subheading Update Pointers
2411texinfo.texi(,2426)
2412texinfo.texi(,2427) The update pointer commands are invoked by typing @kbd{C-c C-u} and
2413texinfo.texi(,2428) then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for
2414texinfo.texi(,2429) @code{texinfo-every-node-update}.@refill
2415texinfo.texi(,2430)
2416texinfo.texi(,2431) @example
2417texinfo.texi(,2432) C-c C-u C-n     @r{Update a node.}
2418texinfo.texi(,2433) C-c C-u C-e     @r{Update every node in the buffer.}
2419texinfo.texi(,2434) @end example
2420texinfo.texi(,2435)
2421texinfo.texi(,2436) @subheading Update Menus
2422texinfo.texi(,2437)
2423texinfo.texi(,2438) Invoke the  update menu commands by typing @kbd{C-c C-u}
2424texinfo.texi(,2439) and then either @kbd{C-m} for @code{texinfo-make-menu} or
2425texinfo.texi(,2440) @kbd{C-a} for @code{texinfo-all-menus-update}.  To update
2426texinfo.texi(,2441) both nodes and menus at the same time, precede @kbd{C-c C-u
2427texinfo.texi(,2442) C-a} with @kbd{C-u}.@refill
2428texinfo.texi(,2443)
2429texinfo.texi(,2444) @example
2430texinfo.texi(,2445) C-c C-u C-m     @r{Make or update a menu.}
2431texinfo.texi(,2446)
2432texinfo.texi(,2447) @group
2433texinfo.texi(,2448) C-c C-u C-a     @r{Make or update all}
2434texinfo.texi(,2449)                 @r{menus in a buffer.}
2435texinfo.texi(,2450) @end group
2436texinfo.texi(,2451)
2437texinfo.texi(,2452) @group
2438texinfo.texi(,2453) C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,}
2439texinfo.texi(,2454)                 @r{first create or update all nodes and}
2440texinfo.texi(,2455)                 @r{then create or update all menus.}
2441texinfo.texi(,2456) @end group
2442texinfo.texi(,2457) @end example
2443texinfo.texi(,2458)
2444texinfo.texi(,2459) @subheading Format for Info
2445texinfo.texi(,2460)
2446texinfo.texi(,2461) The Info formatting commands that are written in Emacs Lisp are
2447texinfo.texi(,2462) invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region
2448texinfo.texi(,2463) or @kbd{C-b} for the whole buffer.@refill
2449texinfo.texi(,2464)
2450texinfo.texi(,2465) The Info formatting commands that are written in C and based on the
2451texinfo.texi(,2466) @code{makeinfo} program are invoked by typing @kbd{C-c C-m} and then
2452texinfo.texi(,2467) either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer.@refill
2453texinfo.texi(,2468)
2454texinfo.texi(,2469) @need 800
2455texinfo.texi(,2470) @noindent
2456texinfo.texi(,2471) Use the @code{texinfo-format@dots{}} commands:
2457texinfo.texi(,2472)
2458texinfo.texi(,2473) @example
2459texinfo.texi(,2474) @group
2460texinfo.texi(,2475) C-c C-e C-r     @r{Format the region.}
2461texinfo.texi(,2476) C-c C-e C-b     @r{Format the buffer.}
2462texinfo.texi(,2477) @end group
2463texinfo.texi(,2478) @end example
2464texinfo.texi(,2479)
2465texinfo.texi(,2480) @need 750
2466texinfo.texi(,2481) @noindent
2467texinfo.texi(,2482) Use @code{makeinfo}:
2468texinfo.texi(,2483)
2469texinfo.texi(,2484) @example
2470texinfo.texi(,2485) C-c C-m C-r     @r{Format the region.}
2471texinfo.texi(,2486) C-c C-m C-b     @r{Format the buffer.}
2472texinfo.texi(,2487) C-c C-m C-l     @r{Recenter the @code{makeinfo} output buffer.}
2473texinfo.texi(,2488) C-c C-m C-k     @r{Kill the @code{makeinfo} formatting job.}
2474texinfo.texi(,2489) @end example
2475texinfo.texi(,2490)
2476texinfo.texi(,2491) @subheading Typeset and Print
2477texinfo.texi(,2492)
2478texinfo.texi(,2493) The @TeX{} typesetting and printing commands are invoked by typing
2479texinfo.texi(,2494) @kbd{C-c C-t} and then another control command: @kbd{C-r} for
2480texinfo.texi(,2495) @code{texinfo-tex-region}, @kbd{C-b} for @code{texinfo-tex-buffer},
2481texinfo.texi(,2496) and so on.@refill
2482texinfo.texi(,2497)
2483texinfo.texi(,2498) @example
2484texinfo.texi(,2499) C-c C-t C-r     @r{Run @TeX{} on the region.}
2485texinfo.texi(,2500) C-c C-t C-b     @r{Run} @code{texi2dvi} @r{on the buffer.}
2486texinfo.texi(,2501) C-c C-t C-i     @r{Run} @code{texindex}.
2487texinfo.texi(,2502) C-c C-t C-p     @r{Print the DVI file.}
2488texinfo.texi(,2503) C-c C-t C-q     @r{Show the print queue.}
2489texinfo.texi(,2504) C-c C-t C-d     @r{Delete a job from the print queue.}
2490texinfo.texi(,2505) C-c C-t C-k     @r{Kill the current @TeX{} formatting job.}
2491texinfo.texi(,2506) C-c C-t C-x     @r{Quit a currently stopped @TeX{} formatting job.}
2492texinfo.texi(,2507) C-c C-t C-l     @r{Recenter the output buffer.}
2493texinfo.texi(,2508) @end example
2494texinfo.texi(,2509)
2495texinfo.texi(,2510) @subheading Other Updating Commands
2496texinfo.texi(,2511)
2497texinfo.texi(,2512) The remaining updating commands do not have standard keybindings because
2498texinfo.texi(,2513) they are rarely used.
2499texinfo.texi(,2514)
2500texinfo.texi(,2515) @example
2501texinfo.texi(,2516) @group
2502texinfo.texi(,2517) M-x texinfo-insert-node-lines
2503texinfo.texi(,2518)                 @r{Insert missing @code{@@node} lines in region.}
2504texinfo.texi(,2519)                 @r{With @kbd{C-u} as a prefix argument,}
2505texinfo.texi(,2520)                 @r{use section titles as node names.}
2506texinfo.texi(,2521) @end group
2507texinfo.texi(,2522)
2508texinfo.texi(,2523) @group
2509texinfo.texi(,2524) M-x texinfo-multiple-files-update
2510texinfo.texi(,2525)                 @r{Update a multi-file document.}
2511texinfo.texi(,2526)                 @r{With @kbd{C-u 2} as a prefix argument,}
2512texinfo.texi(,2527)                 @r{create or update all nodes and menus}
2513texinfo.texi(,2528)                 @r{in all included files first.}
2514texinfo.texi(,2529) @end group
2515texinfo.texi(,2530)
2516texinfo.texi(,2531) @group
2517texinfo.texi(,2532) M-x texinfo-indent-menu-description
2518texinfo.texi(,2533)                 @r{Indent descriptions.}
2519texinfo.texi(,2534) @end group
2520texinfo.texi(,2535)
2521texinfo.texi(,2536) @group
2522texinfo.texi(,2537) M-x texinfo-sequential-node-update
2523texinfo.texi(,2538)                 @r{Insert node pointers in strict sequence.}
2524texinfo.texi(,2539) @end group
2525texinfo.texi(,2540) @end example
2526texinfo.texi(,2541)
2527texinfo.texi(,2542)
2528texinfo.texi(,2543) @node Beginning a File
2529texinfo.texi(,2544) @chapter Beginning a Texinfo File
2530texinfo.texi(,2545) @cindex Beginning a Texinfo file
2531texinfo.texi(,2546) @cindex Texinfo file beginning
2532texinfo.texi(,2547) @cindex File beginning
2533texinfo.texi(,2548)
2534texinfo.texi(,2549) Certain pieces of information must be provided at the beginning of a
2535texinfo.texi(,2550) Texinfo file, such as the name for the output file(s), the title of the
2536texinfo.texi(,2551) document, and the Top node.
2537texinfo.texi(,2552)
2538texinfo.texi(,2553) This chapter expands on the minimal complete Texinfo source file
2539texinfo.texi(,2554) previously given (@pxref{Six Parts}).
2540texinfo.texi(,2555)
2541texinfo.texi(,2556) @menu
2542texinfo.texi(,2557) * Sample Beginning::            A sample beginning for a Texinfo file.
2543texinfo.texi(,2558) * Texinfo File Header::         The first lines.
2544texinfo.texi(,2559) * Document Permissions::        Ensuring your manual is free.
2545texinfo.texi(,2560) * Titlepage & Copyright Page::  Creating the title and copyright pages.
2546texinfo.texi(,2561) * The Top Node::                Creating the `Top' node and master menu.
2547texinfo.texi(,2562) * Global Document Commands::    Affecting formatting throughout.
2548texinfo.texi(,2563) * Software Copying Permissions::  Ensure that you and others continue to
2549texinfo.texi(,2564)                                     have the right to use and share software.
2550texinfo.texi(,2565) @end menu
2551texinfo.texi(,2566)
2552texinfo.texi(,2567)
2553texinfo.texi(,2568) @node Sample Beginning
2554texinfo.texi(,2569) @section Sample Texinfo File Beginning
2555texinfo.texi(,2570)
2556texinfo.texi(,2571) @cindex Example beginning of Texinfo file
2557texinfo.texi(,2572)
2558texinfo.texi(,2573) The following sample shows what is needed.  The elements given here are
2559texinfo.texi(,2574) explained in more detail in the following sections.  Other commands are
2560texinfo.texi(,2575) often included at the beginning of Texinfo files, but the ones here are
2561texinfo.texi(,2576) the most critical.
2562texinfo.texi(,2577)
2563texinfo.texi(,2578) @xref{GNU Sample Texts}, for the full texts to be used in GNU manuals.
2564texinfo.texi(,2579)
2565texinfo.texi(,2580) @example
2566texinfo.texi(,2581) \input texinfo   @@c -*-texinfo-*-
2567texinfo.texi(,2582) @@c %**start of header
2568texinfo.texi(,2583) @@setfilename @var{infoname}.info
2569texinfo.texi(,2584) @@settitle @var{name-of-manual} @var{version}
2570texinfo.texi(,2585) @@c %**end of header
2571texinfo.texi(,2586)
2572texinfo.texi(,2587) @@copying
2573texinfo.texi(,2588) This manual is for @var{program}, version @var{version}.
2574texinfo.texi(,2589)
2575texinfo.texi(,2590) Copyright @@copyright@{@} @var{years} @var{copyright-owner}.
2576texinfo.texi(,2591)
2577texinfo.texi(,2592) @group
2578texinfo.texi(,2593) @@quotation
2579texinfo.texi(,2594) Permission is granted to @dots{}
2580texinfo.texi(,2595) @@end quotation
2581texinfo.texi(,2596) @@end copying
2582texinfo.texi(,2597) @end group
2583texinfo.texi(,2598)
2584texinfo.texi(,2599) @group
2585texinfo.texi(,2600) @@titlepage
2586texinfo.texi(,2601) @@title @var{name-of-manual-when-printed}
2587texinfo.texi(,2602) @@subtitle @var{subtitle-if-any}
2588texinfo.texi(,2603) @@subtitle @var{second-subtitle}
2589texinfo.texi(,2604) @@author @var{author}
2590texinfo.texi(,2605) @end group
2591texinfo.texi(,2606)
2592texinfo.texi(,2607) @group
2593texinfo.texi(,2608) @@c  The following two commands
2594texinfo.texi(,2609) @@c  start the copyright page.
2595texinfo.texi(,2610) @@page
2596texinfo.texi(,2611) @@vskip 0pt plus 1filll
2597texinfo.texi(,2612) @@insertcopying
2598texinfo.texi(,2613) @end group
2599texinfo.texi(,2614)
2600texinfo.texi(,2615) Published by @dots{}
2601texinfo.texi(,2616) @@end titlepage
2602texinfo.texi(,2617)
2603texinfo.texi(,2618) @@c So the toc is printed in the right place.
2604texinfo.texi(,2619) @@contents
2605texinfo.texi(,2620)
2606texinfo.texi(,2621) @@ifnottex
2607texinfo.texi(,2622) @@node Top
2608texinfo.texi(,2623) @@top @var{title}
2609texinfo.texi(,2624)
2610texinfo.texi(,2625) @@insertcopying
2611texinfo.texi(,2626) @@end ifnottex
2612texinfo.texi(,2627)
2613texinfo.texi(,2628) @group
2614texinfo.texi(,2629) @@menu
2615texinfo.texi(,2630) * First Chapter::    Getting started @dots{}
2616texinfo.texi(,2631) * Second Chapter::          @dots{}
2617texinfo.texi(,2632)   @dots{}
2618texinfo.texi(,2633) * Copying::          Your rights and freedoms.
2619texinfo.texi(,2634) @@end menu
2620texinfo.texi(,2635) @end group
2621texinfo.texi(,2636)
2622texinfo.texi(,2637) @group
2623texinfo.texi(,2638) @@node First Chapter
2624texinfo.texi(,2639) @@chapter First Chapter
2625texinfo.texi(,2640)
2626texinfo.texi(,2641) @@cindex first chapter
2627texinfo.texi(,2642) @@cindex chapter, first
2628texinfo.texi(,2643) @dots{}
2629texinfo.texi(,2644) @end group
2630texinfo.texi(,2645) @end example
2631texinfo.texi(,2646)
2632texinfo.texi(,2647)
2633texinfo.texi(,2648) @node Texinfo File Header
2634texinfo.texi(,2649) @section Texinfo File Header
2635texinfo.texi(,2650) @cindex Header for Texinfo files
2636texinfo.texi(,2651) @cindex Texinfo file header
2637texinfo.texi(,2652)
2638texinfo.texi(,2653) Texinfo files start with at least three lines that provide Info and
2639texinfo.texi(,2654) @TeX{} with necessary information.  These are the @code{\input texinfo}
2640texinfo.texi(,2655) line, the @code{@@settitle} line, and the @code{@@setfilename} line.
2641texinfo.texi(,2656)
2642texinfo.texi(,2657) Also, if you want to format just part of the Texinfo file, you must
2643texinfo.texi(,2658) write the @code{@@settitle} and @code{@@setfilename} lines between
2644texinfo.texi(,2659) start-of-header and end-of-header lines.  The start- and end-of-header
2645texinfo.texi(,2660) lines are optional, but they do no harm, so you might as well always
2646texinfo.texi(,2661) include them.
2647texinfo.texi(,2662)
2648texinfo.texi(,2663) Any command that affects document formatting as a whole makes sense to
2649texinfo.texi(,2664) include in the header.  @code{@@synindex} (@pxref{synindex}), for
2650texinfo.texi(,2665) instance, is another command often included in the header.  @xref{GNU
2651texinfo.texi(,2666) Sample Texts}, for complete sample texts.
2652texinfo.texi(,2667)
2653texinfo.texi(,2668) Thus, the beginning of a Texinfo file generally looks like this:
2654texinfo.texi(,2669)
2655texinfo.texi(,2670) @example
2656texinfo.texi(,2671) @group
2657texinfo.texi(,2672) \input texinfo   @@c -*-texinfo-*-
2658texinfo.texi(,2673) @@c %**start of header
2659texinfo.texi(,2674) @@setfilename sample.info
2660texinfo.texi(,2675) @@settitle Sample Manual 1.0
2661texinfo.texi(,2676) @@c %**end of header
2662texinfo.texi(,2677) @end group
2663texinfo.texi(,2678) @end example
2664texinfo.texi(,2679)
2665texinfo.texi(,2680) @menu
2666texinfo.texi(,2681) * First Line::                  The first line of a Texinfo file.
2667texinfo.texi(,2682) * Start of Header::             Formatting a region requires this.
2668texinfo.texi(,2683) * setfilename::                 Tell Info the name of the Info file.
2669texinfo.texi(,2684) * settitle::                    Create a title for the printed work.
2670texinfo.texi(,2685) * End of Header::               Formatting a region requires this.
2671texinfo.texi(,2686) @end menu
2672texinfo.texi(,2687)
2673texinfo.texi(,2688)
2674texinfo.texi(,2689) @node First Line
2675texinfo.texi(,2690) @subsection The First Line of a Texinfo File
2676texinfo.texi(,2691) @cindex First line of a Texinfo file
2677texinfo.texi(,2692) @cindex Beginning line of a Texinfo file
2678texinfo.texi(,2693) @cindex Header of a Texinfo file
2679texinfo.texi(,2694)
2680texinfo.texi(,2695) Every Texinfo file that is to be the top-level input to @TeX{} must begin
2681texinfo.texi(,2696) with a line that looks like this:
2682texinfo.texi(,2697)
2683texinfo.texi(,2698) @example
2684texinfo.texi(,2699) \input texinfo   @@c -*-texinfo-*-
2685texinfo.texi(,2700) @end example
2686texinfo.texi(,2701)
2687texinfo.texi(,2702) @noindent
2688texinfo.texi(,2703) This line serves two functions:
2689texinfo.texi(,2704)
2690texinfo.texi(,2705) @enumerate
2691texinfo.texi(,2706) @item
2692texinfo.texi(,2707) When the file is processed by @TeX{}, the @samp{\input texinfo} command
2693texinfo.texi(,2708) tells @TeX{} to load the macros needed for processing a Texinfo file.
2694texinfo.texi(,2709) These are in a file called @file{texinfo.tex}, which should have been
2695texinfo.texi(,2710) installed on your system along with either the @TeX{} or Texinfo
2696texinfo.texi(,2711) software.  @TeX{} uses the backslash, @samp{\}, to mark the beginning of
2697texinfo.texi(,2712) a command, exactly as Texinfo uses @samp{@@}.  The @file{texinfo.tex}
2698texinfo.texi(,2713) file causes the switch from @samp{\} to @samp{@@}; before the switch
2699texinfo.texi(,2714) occurs, @TeX{} requires @samp{\}, which is why it appears at the
2700texinfo.texi(,2715) beginning of the file.
2701texinfo.texi(,2716)
2702texinfo.texi(,2717) @item
2703texinfo.texi(,2718) When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode
2704texinfo.texi(,2719) specification tells Emacs to use Texinfo mode.
2705texinfo.texi(,2720) @end enumerate
2706texinfo.texi(,2721)
2707texinfo.texi(,2722)
2708texinfo.texi(,2723) @node Start of Header
2709texinfo.texi(,2724) @subsection Start of Header
2710texinfo.texi(,2725) @cindex Start of header line
2711texinfo.texi(,2726)
2712texinfo.texi(,2727) A start-of-header line is a Texinfo comment that looks like this:
2713texinfo.texi(,2728)
2714texinfo.texi(,2729) @example
2715texinfo.texi(,2730) @@c %**start of header
2716texinfo.texi(,2731) @end example
2717texinfo.texi(,2732)
2718texinfo.texi(,2733) Write the start-of-header line on the second line of a Texinfo file.
2719texinfo.texi(,2734) Follow the start-of-header line with @code{@@setfilename} and
2720texinfo.texi(,2735) @code{@@settitle} lines and, optionally, with other commands that
2721texinfo.texi(,2736) globally affect the document formatting, such as @code{@@synindex} or
2722texinfo.texi(,2737) @code{@@footnotestyle}; and then by an end-of-header line (@pxref{End of
2723texinfo.texi(,2738) Header}).
2724texinfo.texi(,2739)
2725texinfo.texi(,2740) The start- and end-of-header lines allow you to format only part of a
2726texinfo.texi(,2741) Texinfo file for Info or printing.  @xref{texinfo-format commands}.
2727texinfo.texi(,2742)
2728texinfo.texi(,2743) The odd string of characters, @samp{%**}, is to ensure that no other
2729texinfo.texi(,2744) comment is accidentally taken for a start-of-header line.  You can
2730texinfo.texi(,2745) change it if you wish by setting the @code{tex-start-of-header} and/or
2731texinfo.texi(,2746) @code{tex-end-of-header} Emacs variables.  @xref{Texinfo Mode Printing}.
2732texinfo.texi(,2747)
2733texinfo.texi(,2748)
2734texinfo.texi(,2749) @node setfilename
2735texinfo.texi(,2750) @subsection @code{@@setfilename}: Set the output file name
2736texinfo.texi(,2751) @findex setfilename
2737texinfo.texi(,2752) @cindex Texinfo requires @code{@@setfilename}
2738texinfo.texi(,2753)
2739texinfo.texi(,2754) In order to serve as the primary input file for either @code{makeinfo}
2740texinfo.texi(,2755) or @TeX{}, a Texinfo file must contain a line that looks like this:
2741texinfo.texi(,2756)
2742texinfo.texi(,2757) @example
2743texinfo.texi(,2758) @@setfilename @var{info-file-name}
2744texinfo.texi(,2759) @end example
2745texinfo.texi(,2760)
2746texinfo.texi(,2761) Write the @code{@@setfilename} command at the beginning of a line and
2747texinfo.texi(,2762) follow it on the same line by the Info file name.  Do not write anything
2748texinfo.texi(,2763) else on the line; anything on the line after the command is considered
2749texinfo.texi(,2764) part of the file name, including what would otherwise be a
2750texinfo.texi(,2765) comment.
2751texinfo.texi(,2766)
2752texinfo.texi(,2767) @cindex Ignored before @code{@@setfilename}
2753texinfo.texi(,2768) @cindex @samp{\input} source line ignored
2754texinfo.texi(,2769) The Info formatting commands ignore everything written before the
2755texinfo.texi(,2770) @code{@@setfilename} line, which is why the very first line of
2756texinfo.texi(,2771) the file (the @code{\input} line) does not show up in the output.
2757texinfo.texi(,2772)
2758texinfo.texi(,2773) The @code{@@setfilename} line specifies the name of the output file to
2759texinfo.texi(,2774) be generated.  This name must be different from the name of the Texinfo
2760texinfo.texi(,2775) file.  There are two conventions for choosing the name: you can either
2761texinfo.texi(,2776) remove the extension (such as @samp{.texi}) entirely from the input file
2762texinfo.texi(,2777) name, or, preferably, replace it with the @samp{.info} extension.
2763texinfo.texi(,2778)
2764texinfo.texi(,2779) @cindex Length of file names
2765texinfo.texi(,2780) @cindex File name collision
2766texinfo.texi(,2781) @cindex Info file name, choosing
2767texinfo.texi(,2782) Although an explicit @samp{.info} extension is preferable, some
2768texinfo.texi(,2783) operating systems cannot handle long file names.  You can run into a
2769texinfo.texi(,2784) problem even when the file name you specify is itself short enough.
2770texinfo.texi(,2785) This occurs because the Info formatters split a long Info file into
2771texinfo.texi(,2786) short indirect subfiles, and name them by appending @samp{-1},
2772texinfo.texi(,2787) @samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original
2773texinfo.texi(,2788) file name.  (@xref{Tag and Split Files}.)  The subfile name
2774texinfo.texi(,2789) @file{texinfo.info-10}, for example, is too long for old systems with a
2775texinfo.texi(,2790) 14-character limit on filenames; so the Info file name for this document
2776texinfo.texi(,2791) is @file{texinfo} rather than @file{texinfo.info}.  When @code{makeinfo}
2777texinfo.texi(,2792) is running on operating systems such as MS-DOS which impose severe
2778texinfo.texi(,2793) limits on file names, it may remove some characters from the original
2779texinfo.texi(,2794) file name to leave enough space for the subfile suffix, thus producing
2780texinfo.texi(,2795) files named @file{texin-10}, @file{gcc.i12}, etc.
2781texinfo.texi(,2796)
2782texinfo.texi(,2797) When producing HTML output, @code{makeinfo} will replace any extension
2783texinfo.texi(,2798) with @samp{html}, or add @samp{.html} if the given name has no
2784texinfo.texi(,2799) extension.
2785texinfo.texi(,2800)
2786texinfo.texi(,2801) @pindex texinfo.cnf
2787texinfo.texi(,2802) The @code{@@setfilename} line produces no output when you typeset a
2788texinfo.texi(,2803) manual with @TeX{}, but it is nevertheless essential: it opens the
2789texinfo.texi(,2804) index, cross-reference, and other auxiliary files used by Texinfo, and
2790texinfo.texi(,2805) also reads @file{texinfo.cnf} if that file is present on your system
2791texinfo.texi(,2806) (@pxref{Preparing for TeX,, Preparing for @TeX{}}).
2792texinfo.texi(,2807)
2793texinfo.texi(,2808)
2794texinfo.texi(,2809) @node settitle
2795texinfo.texi(,2810) @subsection @code{@@settitle}: Set the document title
2796texinfo.texi(,2811) @findex settitle
2797texinfo.texi(,2812)
2798texinfo.texi(,2813) In order to be made into a printed manual, a Texinfo file must contain
2799texinfo.texi(,2814) a line that looks like this:
2800texinfo.texi(,2815)
2801texinfo.texi(,2816) @example
2802texinfo.texi(,2817) @@settitle @var{title}
2803texinfo.texi(,2818) @end example
2804texinfo.texi(,2819)
2805texinfo.texi(,2820) Write the @code{@@settitle} command at the beginning of a line and
2806texinfo.texi(,2821) follow it on the same line by the title.  This tells @TeX{} the title to
2807texinfo.texi(,2822) use in a header or footer.  Do not write anything else on the line;
2808texinfo.texi(,2823) anything on the line after the command is considered part of the title,
2809texinfo.texi(,2824) including what would otherwise be a comment.
2810texinfo.texi(,2825)
2811texinfo.texi(,2826) The @code{@@settitle} command should precede everything that generates
2812texinfo.texi(,2827) actual output in @TeX{}.
2813texinfo.texi(,2828)
2814texinfo.texi(,2829) @cindex <title> HTML tag
2815texinfo.texi(,2830) In the HTML file produced by @command{makeinfo}, @var{title} also serves
2816texinfo.texi(,2831) as the document @samp{<title>} and the default document description in
2817texinfo.texi(,2832) the @samp{<head>} part; see @ref{documentdescription}, for how to change
2818texinfo.texi(,2833) that.
2819texinfo.texi(,2834)
2820texinfo.texi(,2835) The title in the @code{@@settitle} command does not affect the title as
2821texinfo.texi(,2836) it appears on the title page.  Thus, the two do not need not match
2822texinfo.texi(,2837) exactly.  A practice we recommend is to include the version or edition
2823texinfo.texi(,2838) number of the manual in the @code{@@settitle} title; on the title page,
2824texinfo.texi(,2839) the version number generally appears as a @code{@@subtitle} so it would
2825texinfo.texi(,2840) be omitted from the @code{@@title}.  (@xref{titlepage}.)
2826texinfo.texi(,2841)
2827texinfo.texi(,2842) Conventionally, when @TeX{} formats a Texinfo file for double-sided
2828texinfo.texi(,2843) output, the title is printed in the left-hand (even-numbered) page
2829texinfo.texi(,2844) headings and the current chapter title is printed in the right-hand
2830texinfo.texi(,2845) (odd-numbered) page headings.  (@TeX{} learns the title of each chapter
2831texinfo.texi(,2846) from each @code{@@chapter} command.)  By default, no page footer is
2832texinfo.texi(,2847) printed.
2833texinfo.texi(,2848)
2834texinfo.texi(,2849) Even if you are printing in a single-sided style, @TeX{} looks for an
2835texinfo.texi(,2850) @code{@@settitle} command line, in case you include the manual title
2836texinfo.texi(,2851) in the heading.
2837texinfo.texi(,2852)
2838texinfo.texi(,2853) @TeX{} prints page headings only for that text that comes after the
2839texinfo.texi(,2854) @code{@@end titlepage} command in the Texinfo file, or that comes
2840texinfo.texi(,2855) after an @code{@@headings} command that turns on headings.
2841texinfo.texi(,2856) (@xref{headings on off, , The @code{@@headings} Command}, for more
2842texinfo.texi(,2857) information.)
2843texinfo.texi(,2858)
2844texinfo.texi(,2859) You may, if you wish, create your own, customized headings and footings.
2845texinfo.texi(,2860) @xref{Headings}, for a detailed discussion of this.
2846texinfo.texi(,2861)
2847texinfo.texi(,2862)
2848texinfo.texi(,2863) @node End of Header
2849texinfo.texi(,2864) @subsection End of Header
2850texinfo.texi(,2865) @cindex End of header line
2851texinfo.texi(,2866)
2852texinfo.texi(,2867) Follow the header lines with an @w{end-of-header} line, which is a
2853texinfo.texi(,2868) Texinfo comment that looks like this:
2854texinfo.texi(,2869)
2855texinfo.texi(,2870) @example
2856texinfo.texi(,2871) @@c %**end of header
2857texinfo.texi(,2872) @end example
2858texinfo.texi(,2873)
2859texinfo.texi(,2874) @xref{Start of Header}.
2860texinfo.texi(,2875)
2861texinfo.texi(,2876)
2862texinfo.texi(,2877) @node Document Permissions
2863texinfo.texi(,2878) @section Document Permissions
2864texinfo.texi(,2879) @cindex Document Permissions
2865texinfo.texi(,2880) @cindex Copying Permissions
2866texinfo.texi(,2881)
2867texinfo.texi(,2882) The copyright notice and copying permissions for a document need to
2868texinfo.texi(,2883) appear in several places in the various Texinfo output formats.
2869texinfo.texi(,2884) Therefore, Texinfo provides a command (@code{@@copying}) to declare
2870texinfo.texi(,2885) this text once, and another command (@code{@@insertcopying}) to
2871texinfo.texi(,2886) insert the text at appropriate points.
2872texinfo.texi(,2887)
2873texinfo.texi(,2888) @menu
2874texinfo.texi(,2889) * copying::                 Declare the document's copying permissions.
2875texinfo.texi(,2890) * insertcopying::           Where to insert the permissions.
2876texinfo.texi(,2891) @end menu
2877texinfo.texi(,2892)
2878texinfo.texi(,2893)
2879texinfo.texi(,2894) @node copying
2880texinfo.texi(,2895) @subsection @code{@@copying}: Declare copying permissions
2881texinfo.texi(,2896) @findex copying
2882texinfo.texi(,2897)
2883texinfo.texi(,2898) The @code{@@copying} command should be given very early in the document;
2884texinfo.texi(,2899) right after the header material (@pxref{Texinfo File Header}) is the
2885texinfo.texi(,2900) recommended location.  It conventionally consists of a sentence or two
2886texinfo.texi(,2901) about what the program is, the legal copyright line, and the copying
2887texinfo.texi(,2902) permissions.  Here is a skeletal example:
2888texinfo.texi(,2903)
2889texinfo.texi(,2904) @example
2890texinfo.texi(,2905) @@copying
2891texinfo.texi(,2906) This manual is for @var{program} (version @var{version}),
2892texinfo.texi(,2907) which @dots{}
2893texinfo.texi(,2908)
2894texinfo.texi(,2909) Copyright @@copyright@{@} @var{years} @var{copyright-owner}.
2895texinfo.texi(,2910)
2896texinfo.texi(,2911) @@quotation
2897texinfo.texi(,2912) Permission is granted to @dots{}
2898texinfo.texi(,2913) @@end quotation
2899texinfo.texi(,2914) @@end copying
2900texinfo.texi(,2915) @end example
2901texinfo.texi(,2916)
2902texinfo.texi(,2917) The @code{@@quotation} has no legal significance; it's there to improve
2903texinfo.texi(,2918) readability in some contexts.
2904texinfo.texi(,2919)
2905texinfo.texi(,2920) @xref{GNU Sample Texts}, for the full text to be used in GNU manuals.
2906texinfo.texi(,2921) @xref{GNU Free Documentation License}, for the license itself under
2907texinfo.texi(,2922) which GNU and other free manuals are distributed.
2908texinfo.texi(,2923)
2909texinfo.texi(,2924) The text of @code{@@copying} is output as a comment at the beginning of
2910texinfo.texi(,2925) Info, HTML, and XML output files.  It is @emph{not} output implicitly in
2911texinfo.texi(,2926) plain text or @TeX{}; it's up to you to use @code{@@insertcopying} to
2912texinfo.texi(,2927) emit the copying information.  See the next section for details.
2913texinfo.texi(,2928)
2914texinfo.texi(,2929) @findex copyright
2915texinfo.texi(,2930) In output formats that support it (print and HTML), the
2916texinfo.texi(,2931) @code{@@copyright@{@}} command generates a @samp{c} inside a circle.  In
2917texinfo.texi(,2932) Info and plain text, it generates @samp{(C)}.  The copyright notice
2918texinfo.texi(,2933) itself has the following legally defined sequence:
2919texinfo.texi(,2934)
2920texinfo.texi(,2935) @example
2921texinfo.texi(,2936) Copyright @copyright{} @var{years} @var{copyright-owner}.
2922texinfo.texi(,2937) @end example
2923texinfo.texi(,2938)
2924texinfo.texi(,2939) @cindex Copyright word, always in English
2925texinfo.texi(,2940) The word `Copyright' must always be written in English, even if the
2926texinfo.texi(,2941) manual is otherwise in another language.  This is due to international
2927texinfo.texi(,2942) law.
2928texinfo.texi(,2943)
2929texinfo.texi(,2944) @cindex Years, in copyright line
2930texinfo.texi(,2945) The list of years should include all years in which a version was
2931texinfo.texi(,2946) completed (even if it was released in a subsequent year).  Ranges are
2932texinfo.texi(,2947) not allowed, each year must be written out individually, separated by
2933texinfo.texi(,2948) commas.
2934texinfo.texi(,2949)
2935texinfo.texi(,2950) @cindex Copyright owner for FSF works
2936texinfo.texi(,2951) The copyright owner (or owners) is whoever holds legal copyright on the
2937texinfo.texi(,2952) work.  In the case of works assigned to the FSF, the owner is `Free
2938texinfo.texi(,2953) Software Foundation, Inc.'.
2939texinfo.texi(,2954)
2940texinfo.texi(,2955) @xref{Copyright Notices,,,maintain,GNU Maintenance Instructions}, for
2941texinfo.texi(,2956) additional information.
2942texinfo.texi(,2957)
2943texinfo.texi(,2958)
2944texinfo.texi(,2959) @node insertcopying
2945texinfo.texi(,2960) @subsection @code{@@insertcopying}: Include permissions text
2946texinfo.texi(,2961) @findex insertcopying
2947texinfo.texi(,2962) @cindex Copying text, including
2948texinfo.texi(,2963) @cindex Permissions text, including
2949texinfo.texi(,2964) @cindex Including permissions text
2950texinfo.texi(,2965)
2951texinfo.texi(,2966) The @code{@@insertcopying} command is simply written on a line by
2952texinfo.texi(,2967) itself, like this:
2953texinfo.texi(,2968)
2954texinfo.texi(,2969) @example
2955texinfo.texi(,2970) @@insertcopying
2956texinfo.texi(,2971) @end example
2957texinfo.texi(,2972)
2958texinfo.texi(,2973) It inserts the text previously defined by @code{@@copying}.  Legally, it
2959texinfo.texi(,2974) must be used on the copyright page in the printed manual
2960texinfo.texi(,2975) (@pxref{Copyright}).
2961texinfo.texi(,2976)
2962texinfo.texi(,2977) Although it's not a legal requirement, we also strongly recommend using
2963texinfo.texi(,2978) @code{@@insertcopying} in the Top node of your manual (@pxref{The Top
2964texinfo.texi(,2979) Node}).  Here's why:
2965texinfo.texi(,2980)
2966texinfo.texi(,2981) The @code{@@copying} command itself causes the permissions text to
2967texinfo.texi(,2982) appear in an Info file @emph{before} the first node.  The text is also
2968texinfo.texi(,2983) copied into the beginning of each split Info output file, as is legally
2969texinfo.texi(,2984) necessary.  This location implies a human reading the manual using Info
2970texinfo.texi(,2985) does @emph{not} see this text (except when using the advanced Info
2971texinfo.texi(,2986) command @kbd{g *}).  Therefore, an explicit @code{@@insertcopying}
2972texinfo.texi(,2987) in the Top node makes it apparent to readers that the manual is free.
2973texinfo.texi(,2988)
2974texinfo.texi(,2989) Similarly, the @code{@@copying} text is automatically included at the
2975texinfo.texi(,2990) beginning of each HTML output file, as an HTML comment.  Again, this
2976texinfo.texi(,2991) text is not visible (unless the reader views the HTML source).  And
2977texinfo.texi(,2992) therefore again, the @code{@@insertcopying} in the Top node is valuable
2978texinfo.texi(,2993) because it makes the copying permissions visible and thus promotes
2979texinfo.texi(,2994) freedom.
2980texinfo.texi(,2995)
2981texinfo.texi(,2996) The permissions text defined by @code{@@copying} also appears
2982texinfo.texi(,2997) automatically at the beginning of the XML output file.
2983texinfo.texi(,2998)
2984texinfo.texi(,2999)
2985texinfo.texi(,3000) @node Titlepage & Copyright Page
2986texinfo.texi(,3001) @section Title and Copyright Pages
2987texinfo.texi(,3002)
2988texinfo.texi(,3003) In hard copy output, the manual's name and author are usually printed on
2989texinfo.texi(,3004) a title page.  Copyright information is usually printed on the back of
2990texinfo.texi(,3005) the title page.
2991texinfo.texi(,3006)
2992texinfo.texi(,3007) The title and copyright pages appear in the printed manual, but not in
2993texinfo.texi(,3008) the Info file.  Because of this, it is possible to use several slightly
2994texinfo.texi(,3009) obscure @TeX{} typesetting commands that cannot be used in an Info file.
2995texinfo.texi(,3010) In addition, this part of the beginning of a Texinfo file contains the
2996texinfo.texi(,3011) text of the copying permissions that appears in the printed manual.
2997texinfo.texi(,3012)
2998texinfo.texi(,3013) @cindex Title page, for plain text
2999texinfo.texi(,3014) @cindex Copyright page, for plain text
3000texinfo.texi(,3015) You may wish to include titlepage-like information for plain text
3001texinfo.texi(,3016) output.  Simply place any such leading material between
3002texinfo.texi(,3017) @code{@@ifplaintext} and @code{@@end ifplaintext}; @command{makeinfo}
3003texinfo.texi(,3018) includes this when writing plain text (@samp{--no-headers}), along with
3004texinfo.texi(,3019) an @code{@@insertcopying}.
3005texinfo.texi(,3020)
3006texinfo.texi(,3021) @menu
3007texinfo.texi(,3022) * titlepage::                   Create a title for the printed document.
3008texinfo.texi(,3023) * titlefont center sp::         The @code{@@titlefont}, @code{@@center},
3009texinfo.texi(,3024)                                   and @code{@@sp} commands.
3010texinfo.texi(,3025) * title subtitle author::       The @code{@@title}, @code{@@subtitle},
3011texinfo.texi(,3026)                                   and @code{@@author} commands.
3012texinfo.texi(,3027) * Copyright::                   How to write the copyright notice and
3013texinfo.texi(,3028)                                   include copying permissions.
3014texinfo.texi(,3029) * end titlepage::               Turn on page headings after the title and
3015texinfo.texi(,3030)                                   copyright pages.
3016texinfo.texi(,3031) * headings on off::             An option for turning headings on and off
3017texinfo.texi(,3032)                                   and double or single sided printing.
3018texinfo.texi(,3033) @end menu
3019texinfo.texi(,3034)
3020texinfo.texi(,3035)
3021texinfo.texi(,3036) @node titlepage
3022texinfo.texi(,3037) @subsection @code{@@titlepage}
3023texinfo.texi(,3038) @cindex Title page
3024texinfo.texi(,3039) @findex titlepage
3025texinfo.texi(,3040)
3026texinfo.texi(,3041) Start the material for the title page and following copyright page
3027texinfo.texi(,3042) with @code{@@titlepage} on a line by itself and end it with
3028texinfo.texi(,3043) @code{@@end titlepage} on a line by itself.
3029texinfo.texi(,3044)
3030texinfo.texi(,3045) The @code{@@end titlepage} command starts a new page and turns on page
3031texinfo.texi(,3046) numbering.  (@xref{Headings, , Page Headings}, for details about how to
3032texinfo.texi(,3047) generate page headings.)  All the material that you want to appear on
3033texinfo.texi(,3048) unnumbered pages should be put between the @code{@@titlepage} and
3034texinfo.texi(,3049) @code{@@end titlepage} commands.  You can force the table of contents to
3035texinfo.texi(,3050) appear there with the @code{@@setcontentsaftertitlepage} command
3036texinfo.texi(,3051) (@pxref{Contents}).
3037texinfo.texi(,3052)
3038texinfo.texi(,3053) @findex page@r{, within @code{@@titlepage}}
3039texinfo.texi(,3054) By using the @code{@@page} command you can force a page break within the
3040texinfo.texi(,3055) region delineated by the @code{@@titlepage} and @code{@@end titlepage}
3041texinfo.texi(,3056) commands and thereby create more than one unnumbered page.  This is how
3042texinfo.texi(,3057) the copyright page is produced.  (The @code{@@titlepage} command might
3043texinfo.texi(,3058) perhaps have been better named the @code{@@titleandadditionalpages}
3044texinfo.texi(,3059) command, but that would have been rather long!)
3045texinfo.texi(,3060)
3046texinfo.texi(,3061) When you write a manual about a computer program, you should write the
3047texinfo.texi(,3062) version of the program to which the manual applies on the title page.
3048texinfo.texi(,3063) If the manual changes more frequently than the program or is independent
3049texinfo.texi(,3064) of it, you should also include an edition number@footnote{We have found
3050texinfo.texi(,3065) that it is helpful to refer to versions of independent manuals as
3051texinfo.texi(,3066) `editions' and versions of programs as `versions'; otherwise, we find we
3052texinfo.texi(,3067) are liable to confuse each other in conversation by referring to both
3053texinfo.texi(,3068) the documentation and the software with the same words.} for the manual.
3054texinfo.texi(,3069) This helps readers keep track of which manual is for which version of
3055texinfo.texi(,3070) the program.  (The `Top' node should also contain this information; see
3056texinfo.texi(,3071) @ref{The Top Node}.)
3057texinfo.texi(,3072)
3058texinfo.texi(,3073) Texinfo provides two main methods for creating a title page.  One method
3059texinfo.texi(,3074) uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands
3060texinfo.texi(,3075) to generate a title page in which the words on the page are
3061texinfo.texi(,3076) centered.
3062texinfo.texi(,3077)
3063texinfo.texi(,3078) The second method uses the @code{@@title}, @code{@@subtitle}, and
3064texinfo.texi(,3079) @code{@@author} commands to create a title page with black rules under
3065texinfo.texi(,3080) the title and author lines and the subtitle text set flush to the
3066texinfo.texi(,3081) right hand side of the page.  With this method, you do not specify any
3067texinfo.texi(,3082) of the actual formatting of the title page.  You specify the text
3068texinfo.texi(,3083) you want, and Texinfo does the formatting.
3069texinfo.texi(,3084)
3070texinfo.texi(,3085) You may use either method, or you may combine them; see the examples in
3071texinfo.texi(,3086) the sections below.
3072texinfo.texi(,3087)
3073texinfo.texi(,3088) @findex shorttitlepage
3074texinfo.texi(,3089) @cindex Bastard title page
3075texinfo.texi(,3090) @cindex Title page, bastard
3076texinfo.texi(,3091) For extremely simple applications, and for the bastard title page in
3077texinfo.texi(,3092) traditional book front matter, Texinfo also provides a command
3078texinfo.texi(,3093) @code{@@shorttitlepage} which takes the rest of the line as the title.
3079texinfo.texi(,3094) The argument is typeset on a page by itself and followed by a blank
3080texinfo.texi(,3095) page.
3081texinfo.texi(,3096)
3082texinfo.texi(,3097)
3083texinfo.texi(,3098) @node titlefont center sp
3084texinfo.texi(,3099) @subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp}
3085texinfo.texi(,3100) @findex titlefont
3086texinfo.texi(,3101) @findex center
3087texinfo.texi(,3102) @findex sp @r{(titlepage line spacing)}
3088texinfo.texi(,3103)
3089texinfo.texi(,3104) You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center}
3090texinfo.texi(,3105) commands to create a title page for a printed document.  (This is the
3091texinfo.texi(,3106) first of the two methods for creating a title page in Texinfo.)
3092texinfo.texi(,3107)
3093texinfo.texi(,3108) Use the @code{@@titlefont} command to select a large font suitable for
3094texinfo.texi(,3109) the title itself.  You can use @code{@@titlefont} more than once if you
3095texinfo.texi(,3110) have an especially long title.
3096texinfo.texi(,3111)
3097texinfo.texi(,3112) @need 700
3098texinfo.texi(,3113) For example:
3099texinfo.texi(,3114)
3100texinfo.texi(,3115) @example
3101texinfo.texi(,3116) @@titlefont@{Texinfo@}
3102texinfo.texi(,3117) @end example
3103texinfo.texi(,3118)
3104texinfo.texi(,3119) Use the @code{@@center} command at the beginning of a line to center
3105texinfo.texi(,3120) the remaining text on that line.  Thus,
3106texinfo.texi(,3121)
3107texinfo.texi(,3122) @example
3108texinfo.texi(,3123) @@center @@titlefont@{Texinfo@}
3109texinfo.texi(,3124) @end example
3110texinfo.texi(,3125)
3111texinfo.texi(,3126) @noindent
3112texinfo.texi(,3127) centers the title, which in this example is ``Texinfo'' printed
3113texinfo.texi(,3128) in the title font.
3114texinfo.texi(,3129)
3115texinfo.texi(,3130) Use the @code{@@sp} command to insert vertical space.  For example:
3116texinfo.texi(,3131)
3117texinfo.texi(,3132) @example
3118texinfo.texi(,3133) @@sp 2
3119texinfo.texi(,3134) @end example
3120texinfo.texi(,3135)
3121texinfo.texi(,3136) @noindent
3122texinfo.texi(,3137) This inserts two blank lines on the printed page.  (@xref{sp, ,
3123texinfo.texi(,3138) @code{@@sp}}, for more information about the @code{@@sp}
3124texinfo.texi(,3139) command.)
3125texinfo.texi(,3140)
3126texinfo.texi(,3141) A template for this method looks like this:
3127texinfo.texi(,3142)
3128texinfo.texi(,3143) @example
3129texinfo.texi(,3144) @group
3130texinfo.texi(,3145) @@titlepage
3131texinfo.texi(,3146) @@sp 10
3132texinfo.texi(,3147) @@center @@titlefont@{@var{name-of-manual-when-printed}@}
3133texinfo.texi(,3148) @@sp 2
3134texinfo.texi(,3149) @@center @var{subtitle-if-any}
3135texinfo.texi(,3150) @@sp 2
3136texinfo.texi(,3151) @@center @var{author}
3137texinfo.texi(,3152) @dots{}
3138texinfo.texi(,3153) @@end titlepage
3139texinfo.texi(,3154) @end group
3140texinfo.texi(,3155) @end example
3141texinfo.texi(,3156)
3142texinfo.texi(,3157) The spacing of the example fits an 8.5 by 11 inch manual.
3143texinfo.texi(,3158)
3144texinfo.texi(,3159)
3145texinfo.texi(,3160) @node title subtitle author
3146texinfo.texi(,3161) @subsection @code{@@title}, @code{@@subtitle}, and @code{@@author}
3147texinfo.texi(,3162) @findex title
3148texinfo.texi(,3163) @findex subtitle
3149texinfo.texi(,3164) @findex author
3150texinfo.texi(,3165)
3151texinfo.texi(,3166) You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author}
3152texinfo.texi(,3167) commands to create a title page in which the vertical and horizontal
3153texinfo.texi(,3168) spacing is done for you automatically.  This contrasts with the method
3154texinfo.texi(,3169) described in the previous section, in which the @code{@@sp} command is
3155texinfo.texi(,3170) needed to adjust vertical spacing.
3156texinfo.texi(,3171)
3157texinfo.texi(,3172) Write the @code{@@title}, @code{@@subtitle}, or @code{@@author}
3158texinfo.texi(,3173) commands at the beginning of a line followed by the title, subtitle,
3159texinfo.texi(,3174) or author.
3160texinfo.texi(,3175)
3161texinfo.texi(,3176) The @code{@@title} command produces a line in which the title is set
3162texinfo.texi(,3177) flush to the left-hand side of the page in a larger than normal font.
3163texinfo.texi(,3178) The title is underlined with a black rule.  Only a single line is
3164texinfo.texi(,3179) allowed; the @code{@@*} command may not be used to break the title into
3165texinfo.texi(,3180) two lines.  To handle very long titles, you may find it profitable to
3166texinfo.texi(,3181) use both @code{@@title} and @code{@@titlefont}; see the final example in
3167texinfo.texi(,3182) this section.
3168texinfo.texi(,3183)
3169texinfo.texi(,3184) The @code{@@subtitle} command sets subtitles in a normal-sized font
3170texinfo.texi(,3185) flush to the right-hand side of the page.
3171texinfo.texi(,3186)
3172texinfo.texi(,3187) The @code{@@author} command sets the names of the author or authors in
3173texinfo.texi(,3188) a middle-sized font flush to the left-hand side of the page on a line
3174texinfo.texi(,3189) near the bottom of the title page.  The names are underlined with a
3175texinfo.texi(,3190) black rule that is thinner than the rule that underlines the title.
3176texinfo.texi(,3191) (The black rule only occurs if the @code{@@author} command line is
3177texinfo.texi(,3192) followed by an @code{@@page} command line.)
3178texinfo.texi(,3193)
3179texinfo.texi(,3194) There are two ways to use the @code{@@author} command: you can write
3180texinfo.texi(,3195) the name or names on the remaining part of the line that starts with
3181texinfo.texi(,3196) an @code{@@author} command:
3182texinfo.texi(,3197)
3183texinfo.texi(,3198) @example
3184texinfo.texi(,3199) @@author by Jane Smith and John Doe
3185texinfo.texi(,3200) @end example
3186texinfo.texi(,3201)
3187texinfo.texi(,3202) @noindent
3188texinfo.texi(,3203) or you can write the names one above each other by using two (or more)
3189texinfo.texi(,3204) @code{@@author} commands:
3190texinfo.texi(,3205)
3191texinfo.texi(,3206) @example
3192texinfo.texi(,3207) @group
3193texinfo.texi(,3208) @@author Jane Smith
3194texinfo.texi(,3209) @@author John Doe
3195texinfo.texi(,3210) @end group
3196texinfo.texi(,3211) @end example
3197texinfo.texi(,3212)
3198texinfo.texi(,3213) @noindent
3199texinfo.texi(,3214) (Only the bottom name is underlined with a black rule.)
3200texinfo.texi(,3215)
3201texinfo.texi(,3216) @need 950
3202texinfo.texi(,3217) A template for this method looks like this:
3203texinfo.texi(,3218)
3204texinfo.texi(,3219) @example
3205texinfo.texi(,3220) @group
3206texinfo.texi(,3221) @@titlepage
3207texinfo.texi(,3222) @@title @var{name-of-manual-when-printed}
3208texinfo.texi(,3223) @@subtitle @var{subtitle-if-any}
3209texinfo.texi(,3224) @@subtitle @var{second-subtitle}
3210texinfo.texi(,3225) @@author @var{author}
3211texinfo.texi(,3226) @@page
3212texinfo.texi(,3227) @dots{}
3213texinfo.texi(,3228) @@end titlepage
3214texinfo.texi(,3229) @end group
3215texinfo.texi(,3230) @end example
3216texinfo.texi(,3231)
3217texinfo.texi(,3232) You may also combine the @code{@@titlefont} method described in the
3218texinfo.texi(,3233) previous section and @code{@@title} method described in this one.  This
3219texinfo.texi(,3234) may be useful if you have a very long title.  Here is a real-life example:
3220texinfo.texi(,3235)
3221texinfo.texi(,3236) @example
3222texinfo.texi(,3237) @group
3223texinfo.texi(,3238) @@titlepage
3224texinfo.texi(,3239) @@titlefont@{GNU Software@}
3225texinfo.texi(,3240) @@sp 1
3226texinfo.texi(,3241) @@title for MS-Windows and MS-DOS
3227texinfo.texi(,3242) @@subtitle Edition @@value@{e@} for Release @@value@{cde@}
3228texinfo.texi(,3243) @@author by Daniel Hagerty, Melissa Weisshaus
3229texinfo.texi(,3244) @@author and Eli Zaretskii
3230texinfo.texi(,3245) @end group
3231texinfo.texi(,3246) @end example
3232texinfo.texi(,3247)
3233texinfo.texi(,3248) @noindent
3234texinfo.texi(,3249) (The use of @code{@@value} here is explained in @ref{value Example}.
3235texinfo.texi(,3250)
3236texinfo.texi(,3251)
3237texinfo.texi(,3252) @node Copyright
3238texinfo.texi(,3253) @subsection Copyright Page
3239texinfo.texi(,3254) @cindex Copyright page
3240texinfo.texi(,3255) @cindex Printed permissions
3241texinfo.texi(,3256) @cindex Permissions, printed
3242texinfo.texi(,3257)
3243texinfo.texi(,3258) By international treaty, the copyright notice for a book must be either
3244texinfo.texi(,3259) on the title page or on the back of the title page.  When the copyright
3245texinfo.texi(,3260) notice is on the back of the title page, that page is customarily not
3246texinfo.texi(,3261) numbered.  Therefore, in Texinfo, the information on the copyright page
3247texinfo.texi(,3262) should be within @code{@@titlepage} and @code{@@end titlepage}
3248texinfo.texi(,3263) commands.
3249texinfo.texi(,3264)
3250texinfo.texi(,3265) @findex vskip @r{@TeX{} vertical skip}
3251texinfo.texi(,3266) @findex filll @r{@TeX{} dimension}
3252texinfo.texi(,3267) Use the @code{@@page} command to cause a page break.  To push the
3253texinfo.texi(,3268) copyright notice and the other text on the copyright page towards the
3254texinfo.texi(,3269) bottom of the page, use the following incantantion after @code{@@page}:
3255texinfo.texi(,3270)
3256texinfo.texi(,3271) @example
3257texinfo.texi(,3272) @@vskip 0pt plus 1filll
3258texinfo.texi(,3273) @end example
3259texinfo.texi(,3274)
3260texinfo.texi(,3275) @noindent
3261texinfo.texi(,3276) This is a @TeX{} command that is not supported by the Info formatting
3262texinfo.texi(,3277) commands.  The @code{@@vskip} command inserts whitespace.  The @samp{0pt
3263texinfo.texi(,3278) plus 1filll} means to put in zero points of mandatory whitespace, and as
3264texinfo.texi(,3279) much optional whitespace as needed to push the following text to the
3265texinfo.texi(,3280) bottom of the page.  Note the use of three @samp{l}s in the word
3266texinfo.texi(,3281) @samp{filll}; this is correct.
3267texinfo.texi(,3282)
3268texinfo.texi(,3283) To insert the copyright text itself, write @code{@@insertcopying}
3269texinfo.texi(,3284) next (@pxref{Document Permissions}):
3270texinfo.texi(,3285)
3271texinfo.texi(,3286) @example
3272texinfo.texi(,3287) @@insertcopying
3273texinfo.texi(,3288) @end example
3274texinfo.texi(,3289)
3275texinfo.texi(,3290) Follow the copying text by the publisher, ISBN numbers, cover art
3276texinfo.texi(,3291) credits, and other such information.
3277texinfo.texi(,3292)
3278texinfo.texi(,3293) Here is an example putting all this together:
3279texinfo.texi(,3294)
3280texinfo.texi(,3295) @example
3281texinfo.texi(,3296) @@titlepage
3282texinfo.texi(,3297) @dots{}
3283texinfo.texi(,3298) @@page
3284texinfo.texi(,3299) @@vskip 0pt plus 1filll
3285texinfo.texi(,3300) @@insertcopying
3286texinfo.texi(,3301)
3287texinfo.texi(,3302) Published by @dots{}
3288texinfo.texi(,3303)
3289texinfo.texi(,3304) Cover art by @dots{}
3290texinfo.texi(,3305) @@end titlepage
3291texinfo.texi(,3306) @end example
3292texinfo.texi(,3307)
3293texinfo.texi(,3308)
3294texinfo.texi(,3309) @node end titlepage
3295texinfo.texi(,3310) @subsection Heading Generation
3296texinfo.texi(,3311) @findex end titlepage
3297texinfo.texi(,3312) @cindex Headings, page, begin to appear
3298texinfo.texi(,3313) @cindex Titlepage end starts headings
3299texinfo.texi(,3314) @cindex End titlepage starts headings
3300texinfo.texi(,3315)
3301texinfo.texi(,3316) The @code{@@end titlepage} command must be written on a line by itself.
3302texinfo.texi(,3317) It not only marks the end of the title and copyright pages, but also
3303texinfo.texi(,3318) causes @TeX{} to start generating page headings and page numbers.
3304texinfo.texi(,3319)
3305texinfo.texi(,3320) To repeat what is said elsewhere,  Texinfo has two standard page heading
3306texinfo.texi(,3321) formats, one for documents which are printed on one side of each sheet of paper
3307texinfo.texi(,3322) (single-sided printing), and the other for documents which are printed on both
3308texinfo.texi(,3323) sides of each sheet (double-sided printing).
3309texinfo.texi(,3324) You can specify these formats in different ways:
3310texinfo.texi(,3325)
3311texinfo.texi(,3326) @itemize @bullet
3312texinfo.texi(,3327) @item
3313texinfo.texi(,3328) The conventional way is to write an @code{@@setchapternewpage} command
3314texinfo.texi(,3329) before the title page commands, and then have the @code{@@end
3315texinfo.texi(,3330) titlepage} command start generating page headings in the manner desired.
3316texinfo.texi(,3331) (@xref{setchapternewpage}.)
3317texinfo.texi(,3332)
3318texinfo.texi(,3333) @item
3319texinfo.texi(,3334) Alternatively, you can use the @code{@@headings} command to prevent page
3320texinfo.texi(,3335) headings from being generated or to start them for either single or
3321texinfo.texi(,3336) double-sided printing.  (Write an @code{@@headings} command immediately
3322texinfo.texi(,3337) after the @code{@@end titlepage} command.  @xref{headings on off, , The
3323texinfo.texi(,3338) @code{@@headings} Command}, for more information.)@refill
3324texinfo.texi(,3339)
3325texinfo.texi(,3340) @item
3326texinfo.texi(,3341) Or, you may specify your own page heading and footing format.
3327texinfo.texi(,3342) @xref{Headings, , Page Headings}, for detailed
3328texinfo.texi(,3343) information about page headings and footings.
3329texinfo.texi(,3344) @end itemize
3330texinfo.texi(,3345)
3331texinfo.texi(,3346) Most documents are formatted with the standard single-sided or
3332texinfo.texi(,3347) double-sided format, using @code{@@setchapternewpage odd} for
3333texinfo.texi(,3348) double-sided printing and no @code{@@setchapternewpage} command for
3334texinfo.texi(,3349) single-sided printing.
3335texinfo.texi(,3350)
3336texinfo.texi(,3351)
3337texinfo.texi(,3352) @node headings on off
3338texinfo.texi(,3353) @subsection The @code{@@headings} Command
3339texinfo.texi(,3354) @findex headings
3340texinfo.texi(,3355)
3341texinfo.texi(,3356) The @code{@@headings} command is rarely used.  It specifies what kind of
3342texinfo.texi(,3357) page headings and footings to print on each page.  Usually, this is
3343texinfo.texi(,3358) controlled by the @code{@@setchapternewpage} command.  You need the
3344texinfo.texi(,3359) @code{@@headings} command only if the @code{@@setchapternewpage} command
3345texinfo.texi(,3360) does not do what you want, or if you want to turn off pre-defined page
3346texinfo.texi(,3361) headings prior to defining your own.  Write an @code{@@headings} command
3347texinfo.texi(,3362) immediately after the @code{@@end titlepage} command.@refill
3348texinfo.texi(,3363)
3349texinfo.texi(,3364) You can use @code{@@headings} as follows:@refill
3350texinfo.texi(,3365)
3351texinfo.texi(,3366) @table @code
3352texinfo.texi(,3367) @item @@headings off
3353texinfo.texi(,3368) Turn off printing of page headings.@refill
3354texinfo.texi(,3369)
3355texinfo.texi(,3370) @item @@headings single
3356texinfo.texi(,3371) Turn on page headings appropriate for single-sided printing.
3357texinfo.texi(,3372) @refill
3358texinfo.texi(,3373)
3359texinfo.texi(,3374) @item @@headings double
3360texinfo.texi(,3375) @itemx @@headings on
3361texinfo.texi(,3376) Turn on page headings appropriate for double-sided printing.  The two
3362texinfo.texi(,3377) commands, @code{@@headings on} and @code{@@headings double}, are
3363texinfo.texi(,3378) synonymous.@refill
3364texinfo.texi(,3379)
3365texinfo.texi(,3380) @item @@headings singleafter
3366texinfo.texi(,3381) @itemx @@headings doubleafter
3367texinfo.texi(,3382) Turn on @code{single} or @code{double} headings, respectively, after the
3368texinfo.texi(,3383) current page is output.
3369texinfo.texi(,3384)
3370texinfo.texi(,3385) @item @@headings on
3371texinfo.texi(,3386) Turn on page headings: @code{single} if @samp{@@setchapternewpage
3372texinfo.texi(,3387) on}, @code{double} otherwise.
3373texinfo.texi(,3388) @end table
3374texinfo.texi(,3389)
3375texinfo.texi(,3390) For example, suppose you write @code{@@setchapternewpage off} before the
3376texinfo.texi(,3391) @code{@@titlepage} command to tell @TeX{} to start a new chapter on the
3377texinfo.texi(,3392) same page as the end of the last chapter.  This command also causes
3378texinfo.texi(,3393) @TeX{} to typeset page headers for single-sided printing.  To cause
3379texinfo.texi(,3394) @TeX{} to typeset for double sided printing, write @code{@@headings
3380texinfo.texi(,3395) double} after the @code{@@end titlepage} command.
3381texinfo.texi(,3396)
3382texinfo.texi(,3397) You can stop @TeX{} from generating any page headings at all by
3383texinfo.texi(,3398) writing @code{@@headings off} on a line of its own immediately after the
3384texinfo.texi(,3399) line containing the @code{@@end titlepage} command, like this:@refill
3385texinfo.texi(,3400)
3386texinfo.texi(,3401) @example
3387texinfo.texi(,3402) @@end titlepage
3388texinfo.texi(,3403) @@headings off
3389texinfo.texi(,3404) @end example
3390texinfo.texi(,3405)
3391texinfo.texi(,3406) @noindent
3392texinfo.texi(,3407) The @code{@@headings off} command overrides the @code{@@end titlepage}
3393texinfo.texi(,3408) command, which would otherwise cause @TeX{} to print page
3394texinfo.texi(,3409) headings.@refill
3395texinfo.texi(,3410)
3396texinfo.texi(,3411) You can also specify your own style of page heading and footing.
3397texinfo.texi(,3412) @xref{Headings, , Page Headings}, for more information.@refill
3398texinfo.texi(,3413)
3399texinfo.texi(,3414)
3400texinfo.texi(,3415) @node The Top Node
3401texinfo.texi(,3416) @section The `Top' Node and Master Menu
3402texinfo.texi(,3417) @cindex Top node
3403texinfo.texi(,3418) @cindex Node, `Top'
3404texinfo.texi(,3419)
3405texinfo.texi(,3420) The `Top' node is the node in which a reader enters an Info manual.  As
3406texinfo.texi(,3421) such, it should begin with the @code{@@insertcopying} command
3407texinfo.texi(,3422) (@pxref{Document Permissions}) to provide a brief description of the
3408texinfo.texi(,3423) manual (including the version number) and copying permissions, and end
3409texinfo.texi(,3424) with a master menu for the whole manual.  Of course you should include
3410texinfo.texi(,3425) any other general information you feel a reader would find helpful.
3411texinfo.texi(,3426)
3412texinfo.texi(,3427) @findex top
3413texinfo.texi(,3428) It is also conventional to write an @code{@@top} sectioning command line
3414texinfo.texi(,3429) containing the title of the document immediately after the @code{@@node
3415texinfo.texi(,3430) Top} line (@pxref{makeinfo top command, , The @code{@@top} Sectioning
3416texinfo.texi(,3431) Command}).
3417texinfo.texi(,3432)
3418texinfo.texi(,3433) The contents of the `Top' node should appear only in the online output;
3419texinfo.texi(,3434) none of it should appear in printed output, so enclose it between
3420texinfo.texi(,3435) @code{@@ifnottex} and @code{@@end ifnottex} commands.  (@TeX{} does not
3421texinfo.texi(,3436) print either an @code{@@node} line or a menu; they appear only in Info;
3422texinfo.texi(,3437) strictly speaking, you are not required to enclose these parts between
3423texinfo.texi(,3438) @code{@@ifnottex} and @code{@@end ifnottext}, but it is simplest to do
3424texinfo.texi(,3439) so.  @xref{Conditionals, , Conditionally Visible Text}.)
3425texinfo.texi(,3440)
3426texinfo.texi(,3441) @menu
3427texinfo.texi(,3442) * Top Node Example::
3428texinfo.texi(,3443) * Master Menu Parts::
3429texinfo.texi(,3444) @end menu
3430texinfo.texi(,3445)
3431texinfo.texi(,3446)
3432texinfo.texi(,3447) @node Top Node Example
3433texinfo.texi(,3448) @subsection Top Node Example
3434texinfo.texi(,3449)
3435texinfo.texi(,3450) @cindex Top node example
3436texinfo.texi(,3451)
3437texinfo.texi(,3452) Here is an example of a Top node.
3438texinfo.texi(,3453)
3439texinfo.texi(,3454) @example
3440texinfo.texi(,3455) @group
3441texinfo.texi(,3456) @@ifnottex
3442texinfo.texi(,3457) @@node Top
3443texinfo.texi(,3458) @@top Sample Title
3444texinfo.texi(,3459)
3445texinfo.texi(,3460) @@insertcopying
3446texinfo.texi(,3461) @end group
3447texinfo.texi(,3462)
3448texinfo.texi(,3463) Additional general information.
3449texinfo.texi(,3464)
3450texinfo.texi(,3465) @group
3451texinfo.texi(,3466) @@menu
3452texinfo.texi(,3467) * First Chapter::
3453texinfo.texi(,3468) * Second Chapter::
3454texinfo.texi(,3469) @dots{}
3455texinfo.texi(,3470) * Index::
3456texinfo.texi(,3471) @end group
3457texinfo.texi(,3472) @@end menu
3458texinfo.texi(,3473) @end example
3459texinfo.texi(,3474)
3460texinfo.texi(,3475)
3461texinfo.texi(,3476) @node Master Menu Parts
3462texinfo.texi(,3477) @subsection Parts of a Master Menu
3463texinfo.texi(,3478) @cindex Master menu
3464texinfo.texi(,3479) @cindex Menu, master
3465texinfo.texi(,3480) @cindex Parts of a master menu
3466texinfo.texi(,3481)
3467texinfo.texi(,3482) A @dfn{master menu} is a detailed main menu listing all the nodes in a
3468texinfo.texi(,3483) file.
3469texinfo.texi(,3484)
3470texinfo.texi(,3485) A master menu is enclosed in @code{@@menu} and @code{@@end menu}
3471texinfo.texi(,3486) commands and does not appear in the printed document.
3472texinfo.texi(,3487)
3473texinfo.texi(,3488) Generally, a master menu is divided into parts.
3474texinfo.texi(,3489)
3475texinfo.texi(,3490) @itemize @bullet
3476texinfo.texi(,3491) @item
3477texinfo.texi(,3492) The first part contains the major nodes in the Texinfo file: the nodes
3478texinfo.texi(,3493) for the chapters, chapter-like sections, and the appendices.
3479texinfo.texi(,3494)
3480texinfo.texi(,3495) @item
3481texinfo.texi(,3496) The second part contains nodes for the indices.
3482texinfo.texi(,3497)
3483texinfo.texi(,3498) @item
3484texinfo.texi(,3499) The third and subsequent parts contain a listing of the other, lower
3485texinfo.texi(,3500) level nodes, often ordered by chapter.  This way, rather than go
3486texinfo.texi(,3501) through an intermediary menu, an inquirer can go directly to a
3487texinfo.texi(,3502) particular node when searching for specific information.  These menu
3488texinfo.texi(,3503) items are not required; add them if you think they are a
3489texinfo.texi(,3504) convenience.  If you do use them, put @code{@@detailmenu} before the
3490texinfo.texi(,3505) first one, and @code{@@end detailmenu} after the last; otherwise,
3491texinfo.texi(,3506) @code{makeinfo} will get confused.
3492texinfo.texi(,3507) @end itemize
3493texinfo.texi(,3508)
3494texinfo.texi(,3509) Each section in the menu can be introduced by a descriptive line.  So
3495texinfo.texi(,3510) long as the line does not begin with an asterisk, it will not be
3496texinfo.texi(,3511) treated as a menu entry.  (@xref{Writing a Menu}, for more
3497texinfo.texi(,3512) information.)
3498texinfo.texi(,3513)
3499texinfo.texi(,3514) For example, the master menu for this manual looks like the following
3500texinfo.texi(,3515) (but has many more entries):
3501texinfo.texi(,3516)
3502texinfo.texi(,3517) @example
3503texinfo.texi(,3518) @group
3504texinfo.texi(,3519) @@menu
3505texinfo.texi(,3520) * Copying Conditions::  Your rights.
3506texinfo.texi(,3521) * Overview::            Texinfo in brief.
3507texinfo.texi(,3522) @dots{}
3508texinfo.texi(,3523) @end group
3509texinfo.texi(,3524) @group
3510texinfo.texi(,3525) * Command and Variable Index::
3511texinfo.texi(,3526) * Concept Index::
3512texinfo.texi(,3527) @end group
3513texinfo.texi(,3528)
3514texinfo.texi(,3529) @group
3515texinfo.texi(,3530) @@detailmenu
3516texinfo.texi(,3531)  --- The Detailed Node Listing ---
3517texinfo.texi(,3532)
3518texinfo.texi(,3533) Overview of Texinfo
3519texinfo.texi(,3534)
3520texinfo.texi(,3535) * Reporting Bugs:: @dots{}
3521texinfo.texi(,3536) @dots{}
3522texinfo.texi(,3537) @end group
3523texinfo.texi(,3538)
3524texinfo.texi(,3539) @group
3525texinfo.texi(,3540) Beginning a Texinfo File
3526texinfo.texi(,3541)
3527texinfo.texi(,3542) * Sample Beginning:: @dots{}
3528texinfo.texi(,3543) @dots{}
3529texinfo.texi(,3544) @@end detailmenu
3530texinfo.texi(,3545) @@end menu
3531texinfo.texi(,3546) @end group
3532texinfo.texi(,3547) @end example
3533texinfo.texi(,3548)
3534texinfo.texi(,3549)
3535texinfo.texi(,3550) @node Global Document Commands
3536texinfo.texi(,3551) @section Global Document Commands
3537texinfo.texi(,3552) @cindex Global Document Commands
3538texinfo.texi(,3553)
3539texinfo.texi(,3554) Besides the basic commands mentioned in the previous sections, here are
3540texinfo.texi(,3555) additional commands which affect the document as a whole.  They are
3541texinfo.texi(,3556) generally all given before the Top node, if they are given at all.
3542texinfo.texi(,3557)
3543texinfo.texi(,3558) @menu
3544texinfo.texi(,3559) * documentdescription::         Document summary for the HTML output.
3545texinfo.texi(,3560) * setchapternewpage::           Start chapters on right-hand pages.
3546texinfo.texi(,3561) * paragraphindent::             Specify paragraph indentation.
3547texinfo.texi(,3562) * exampleindent::               Specify environment indentation.
3548texinfo.texi(,3563) @end menu
3549texinfo.texi(,3564)
3550texinfo.texi(,3565)
3551texinfo.texi(,3566) @node documentdescription
3552texinfo.texi(,3567) @subsection @code{@@documentdescription}: Summary text
3553texinfo.texi(,3568) @cindex Document description
3554texinfo.texi(,3569) @cindex Description of document
3555texinfo.texi(,3570) @cindex Summary of document
3556texinfo.texi(,3571) @cindex Abstract of document
3557texinfo.texi(,3572) @cindex <meta> HTML tag, and document description
3558texinfo.texi(,3573) @findex documentdescription
3559texinfo.texi(,3574)
3560texinfo.texi(,3575) When producing HTML output for a document, @command{makeinfo} writes a
3561texinfo.texi(,3576) @samp{<meta>} element in the @samp{<head>} to give some idea of the
3562texinfo.texi(,3577) content of the document.  By default, this @dfn{description} is the title
3563texinfo.texi(,3578) of the document, taken from the @code{@@settitle} command
3564texinfo.texi(,3579) (@pxref{settitle}).  To change this, use the @code{@@documentdescription}
3565texinfo.texi(,3580) environment, as in:
3566texinfo.texi(,3581)
3567texinfo.texi(,3582) @example
3568texinfo.texi(,3583) @@documentdescription
3569texinfo.texi(,3584) descriptive text.
3570texinfo.texi(,3585) @@end documentdescription
3571texinfo.texi(,3586) @end example
3572texinfo.texi(,3587)
3573texinfo.texi(,3588) @noindent
3574texinfo.texi(,3589) This will produce the following output in the @samp{<head>} of the HTML:
3575texinfo.texi(,3590)
3576texinfo.texi(,3591) @example
3577texinfo.texi(,3592) <meta name=description content="descriptive text.">
3578texinfo.texi(,3593) @end example
3579texinfo.texi(,3594)
3580texinfo.texi(,3595) @code{@@documentdescription} must be specified before the first node of
3581texinfo.texi(,3596) the document.
3582texinfo.texi(,3597)
3583texinfo.texi(,3598)
3584texinfo.texi(,3599) @node setchapternewpage
3585texinfo.texi(,3600) @subsection @code{@@setchapternewpage}:
3586texinfo.texi(,3601) @cindex Starting chapters
3587texinfo.texi(,3602) @cindex Pages, starting odd
3588texinfo.texi(,3603) @findex setchapternewpage
3589texinfo.texi(,3604)
3590texinfo.texi(,3605) In an officially bound book, text is usually printed on both sides of
3591texinfo.texi(,3606) the paper, chapters start on right-hand pages, and right-hand pages have
3592texinfo.texi(,3607) odd numbers.  But in short reports, text often is printed only on one
3593texinfo.texi(,3608) side of the paper.  Also in short reports, chapters sometimes do not
3594texinfo.texi(,3609) start on new pages, but are printed on the same page as the end of the
3595texinfo.texi(,3610) preceding chapter, after a small amount of vertical whitespace.
3596texinfo.texi(,3611)
3597texinfo.texi(,3612) You can use the @code{@@setchapternewpage} command with various
3598texinfo.texi(,3613) arguments to specify how @TeX{} should start chapters and whether it
3599texinfo.texi(,3614) should format headers for printing on one or both sides of the paper
3600texinfo.texi(,3615) (single-sided or double-sided printing).
3601texinfo.texi(,3616)
3602texinfo.texi(,3617) Write the @code{@@setchapternewpage} command at the beginning of a
3603texinfo.texi(,3618) line followed by its argument.
3604texinfo.texi(,3619)
3605texinfo.texi(,3620) For example, you would write the following to cause each chapter to
3606texinfo.texi(,3621) start on a fresh odd-numbered page:
3607texinfo.texi(,3622)
3608texinfo.texi(,3623) @example
3609texinfo.texi(,3624) @@setchapternewpage odd
3610texinfo.texi(,3625) @end example
3611texinfo.texi(,3626)
3612texinfo.texi(,3627) You can specify one of three alternatives with the
3613texinfo.texi(,3628) @code{@@setchapternewpage} command:
3614texinfo.texi(,3629)
3615texinfo.texi(,3630) @table @asis
3616texinfo.texi(,3631)
3617texinfo.texi(,3632) @item @code{@@setchapternewpage off}
3618texinfo.texi(,3633) Cause @TeX{} to typeset a new chapter on the same page as the last
3619texinfo.texi(,3634) chapter, after skipping some vertical whitespace.  Also, cause @TeX{} to
3620texinfo.texi(,3635) format page headers for single-sided printing.
3621texinfo.texi(,3636)
3622texinfo.texi(,3637) @item @code{@@setchapternewpage on}
3623texinfo.texi(,3638) Cause @TeX{} to start new chapters on new pages and to format page
3624texinfo.texi(,3639) headers for single-sided printing.  This is the form most often used for
3625texinfo.texi(,3640) short reports or personal printing. This is the default.
3626texinfo.texi(,3641)
3627texinfo.texi(,3642) @item @code{@@setchapternewpage odd}
3628texinfo.texi(,3643) Cause @TeX{} to start new chapters on new, odd-numbered pages
3629texinfo.texi(,3644) (right-handed pages) and to typeset for double-sided printing.  This is
3630texinfo.texi(,3645) the form most often used for books and manuals.
3631texinfo.texi(,3646) @end table
3632texinfo.texi(,3647)
3633texinfo.texi(,3648) Texinfo does not have an @code{@@setchapternewpage even} command,
3634texinfo.texi(,3649) because there is no printing tradition of starting chapters or books on
3635texinfo.texi(,3650) an even-numbered page.
3636texinfo.texi(,3651)
3637texinfo.texi(,3652) If you don't like the default headers that @code{@@setchapternewpage}
3638texinfo.texi(,3653) sets, you can explicit control them with the @code{@@headings} command.
3639texinfo.texi(,3654) @xref{headings on off, , The @code{@@headings} Command}.
3640texinfo.texi(,3655)
3641texinfo.texi(,3656) At the beginning of a manual or book, pages are not numbered---for
3642texinfo.texi(,3657) example, the title and copyright pages of a book are not numbered.  By
3643texinfo.texi(,3658) convention, table of contents and frontmatter pages are numbered with
3644texinfo.texi(,3659) roman numerals and not in sequence with the rest of the document.
3645texinfo.texi(,3660)
3646texinfo.texi(,3661) Since an Info file does not have pages, the @code{@@setchapternewpage}
3647texinfo.texi(,3662) command has no effect on it.
3648texinfo.texi(,3663)
3649texinfo.texi(,3664) We recommend not including any @code{@@setchapternewpage} command in
3650texinfo.texi(,3665) your manual sources at all, since the desired output is not intrinsic to
3651texinfo.texi(,3666) the document.  For a particular hard copy run, if you don't want the
3652texinfo.texi(,3667) default option (no blank pages, same headers on all pages) use the
3653texinfo.texi(,3668) @option{--texinfo} option to @command{texi2dvi} to specify the output
3654texinfo.texi(,3669) you want.
3655texinfo.texi(,3670)
3656texinfo.texi(,3671)
3657texinfo.texi(,3672) @node paragraphindent
3658texinfo.texi(,3673) @subsection Paragraph Indenting
3659texinfo.texi(,3674) @cindex Indenting paragraphs, control of
3660texinfo.texi(,3675) @cindex Paragraph indentation control
3661texinfo.texi(,3676) @findex paragraphindent
3662texinfo.texi(,3677)
3663texinfo.texi(,3678) The Texinfo processors may insert whitespace at the beginning of the
3664texinfo.texi(,3679) first line of each paragraph, thereby indenting that paragraph.  You can
3665texinfo.texi(,3680) use the @code{@@paragraphindent} command to specify this indentation.
3666texinfo.texi(,3681) Write an @code{@@paragraphindent} command at the beginning of a line
3667texinfo.texi(,3682) followed by either @samp{asis} or a number:
3668texinfo.texi(,3683)
3669texinfo.texi(,3684) @example
3670texinfo.texi(,3685) @@paragraphindent @var{indent}
3671texinfo.texi(,3686) @end example
3672texinfo.texi(,3687)
3673texinfo.texi(,3688) The indentation is according to the value of @var{indent}:
3674texinfo.texi(,3689)
3675texinfo.texi(,3690) @table @asis
3676texinfo.texi(,3691) @item @code{asis}
3677texinfo.texi(,3692) Do not change the existing indentation (not implemented in @TeX{}).
3678texinfo.texi(,3693)
3679texinfo.texi(,3694) @item @code{none}
3680texinfo.texi(,3695) @itemx 0
3681texinfo.texi(,3696) Omit all indentation.
3682texinfo.texi(,3697)
3683texinfo.texi(,3698) @item @var{n}
3684texinfo.texi(,3699) Indent by @var{n} space characters in Info output, by @var{n} ems in
3685texinfo.texi(,3700) @TeX{}.
3686texinfo.texi(,3701)
3687texinfo.texi(,3702) @end table
3688texinfo.texi(,3703)
3689texinfo.texi(,3704) The default value of @var{indent} is 3.  @code{@@paragraphindent} is
3690texinfo.texi(,3705) ignored for HTML output.
3691texinfo.texi(,3706)
3692texinfo.texi(,3707) It is best to write the @code{@@paragraphindent} command before the
3693texinfo.texi(,3708) end-of-header line at the beginning of a Texinfo file, so the region
3694texinfo.texi(,3709) formatting commands indent paragraphs as specified.  @xref{Start of
3695texinfo.texi(,3710) Header}.
3696texinfo.texi(,3711)
3697texinfo.texi(,3712) A peculiarity of the @code{texinfo-format-buffer} and
3698texinfo.texi(,3713) @code{texinfo-format-region} commands is that they do not indent (nor
3699texinfo.texi(,3714) fill) paragraphs that contain @code{@@w} or @code{@@*} commands.
3700texinfo.texi(,3715) @xref{Refilling Paragraphs}, for further information.
3701texinfo.texi(,3716)
3702texinfo.texi(,3717)
3703texinfo.texi(,3718) @node exampleindent
3704texinfo.texi(,3719) @subsection @code{@@exampleindent}: Environment Indenting
3705texinfo.texi(,3720) @cindex Indenting environments
3706texinfo.texi(,3721) @cindex Environment indentation
3707texinfo.texi(,3722) @cindex Example indentation
3708texinfo.texi(,3723) @findex exampleindent
3709texinfo.texi(,3724)
3710texinfo.texi(,3725) The Texinfo processors indent each line of @code{@@example} and similar
3711texinfo.texi(,3726) environments.  You can use the @code{@@exampleindent} command to specify
3712texinfo.texi(,3727) this indentation.  Write an @code{@@exampleindent} command at the
3713texinfo.texi(,3728) beginning of a line followed by either @samp{asis} or a number:
3714texinfo.texi(,3729)
3715texinfo.texi(,3730) @example
3716texinfo.texi(,3731) @@exampleindent @var{indent}
3717texinfo.texi(,3732) @end example
3718texinfo.texi(,3733)
3719texinfo.texi(,3734) The indentation is according to the value of @var{indent}:
3720texinfo.texi(,3735)
3721texinfo.texi(,3736) @table @asis
3722texinfo.texi(,3737) @item @code{asis}
3723texinfo.texi(,3738) Do not change the existing indentation (not implemented in @TeX{}).
3724texinfo.texi(,3739)
3725texinfo.texi(,3740) @item 0
3726texinfo.texi(,3741) Omit all indentation.
3727texinfo.texi(,3742)
3728texinfo.texi(,3743) @item @var{n}
3729texinfo.texi(,3744) Indent environments by @var{n} space characters in Info output, by
3730texinfo.texi(,3745) @var{n} ems in @TeX{}.
3731texinfo.texi(,3746)
3732texinfo.texi(,3747) @end table
3733texinfo.texi(,3748)
3734texinfo.texi(,3749) The default value of @var{indent} is 5.  @code{@@exampleindent} is
3735texinfo.texi(,3750) ignored for HTML output.
3736texinfo.texi(,3751)
3737texinfo.texi(,3752) It is best to write the @code{@@exampleindent} command before the
3738texinfo.texi(,3753) end-of-header line at the beginning of a Texinfo file, so the region
3739texinfo.texi(,3754) formatting commands indent paragraphs as specified.  @xref{Start of
3740texinfo.texi(,3755) Header}.
3741texinfo.texi(,3756)
3742texinfo.texi(,3757)
3743texinfo.texi(,3758) @node Software Copying Permissions
3744texinfo.texi(,3759) @section Software Copying Permissions
3745texinfo.texi(,3760) @cindex Software copying permissions
3746texinfo.texi(,3761) @cindex Copying software
3747texinfo.texi(,3762) @cindex Distribution
3748texinfo.texi(,3763) @cindex License agreement
3749texinfo.texi(,3764)
3750texinfo.texi(,3765) If the Texinfo file has a section containing the ``General Public
3751texinfo.texi(,3766) License'' and the distribution information and a warranty disclaimer for
3752texinfo.texi(,3767) the software that is documented, we recommend placing this right after
3753texinfo.texi(,3768) the `Top' node.  The General Public License is very important to Project
3754texinfo.texi(,3769) GNU software.  It ensures that you and others will continue to have a
3755texinfo.texi(,3770) right to use and share the software.
3756texinfo.texi(,3771)
3757texinfo.texi(,3772) The copying and distribution information and the disclaimer are followed
3758texinfo.texi(,3773) by an introduction or else by the first chapter of the manual.
3759texinfo.texi(,3774)
3760texinfo.texi(,3775) @cindex Introduction, as part of file
3761texinfo.texi(,3776) Although an introduction is not a required part of a Texinfo file, it
3762texinfo.texi(,3777) is very helpful.  Ideally, it should state clearly and concisely what
3763texinfo.texi(,3778) the file is about and who would be interested in reading it.  In
3764texinfo.texi(,3779) general, an introduction would follow the licensing and distribution
3765texinfo.texi(,3780) information, although sometimes people put it earlier in the document.
3766texinfo.texi(,3781)
3767texinfo.texi(,3782)
3768texinfo.texi(,3783) @node Ending a File
3769texinfo.texi(,3784) @chapter Ending a Texinfo File
3770texinfo.texi(,3785) @cindex Ending a Texinfo file
3771texinfo.texi(,3786) @cindex Texinfo file ending
3772texinfo.texi(,3787) @cindex File ending
3773texinfo.texi(,3788) @findex bye
3774texinfo.texi(,3789)
3775texinfo.texi(,3790) The end of a Texinfo file should include commands to create indices and
3776texinfo.texi(,3791) (perhaps) to generate both the full and summary tables of contents.
3777texinfo.texi(,3792) Finally, it must include the @code{@@bye} command that marks the last
3778texinfo.texi(,3793) line to be processed.
3779texinfo.texi(,3794)
3780texinfo.texi(,3795) @need 700
3781texinfo.texi(,3796) For example:
3782texinfo.texi(,3797)
3783texinfo.texi(,3798) @example
3784texinfo.texi(,3799) @@node Index
3785texinfo.texi(,3800) @@unnumbered Index
3786texinfo.texi(,3801)
3787texinfo.texi(,3802) @@printindex cp
3788texinfo.texi(,3803)
3789texinfo.texi(,3804) @@shortcontents
3790texinfo.texi(,3805) @@contents
3791texinfo.texi(,3806)
3792texinfo.texi(,3807) @@bye
3793texinfo.texi(,3808) @end example
3794texinfo.texi(,3809)
3795texinfo.texi(,3810) @menu
3796texinfo.texi(,3811) * Printing Indices & Menus::    How to print an index in hardcopy and
3797texinfo.texi(,3812)                                   generate index menus in Info.
3798texinfo.texi(,3813) * Contents::                    How to create a table of contents.
3799texinfo.texi(,3814) * File End::                    How to mark the end of a file.
3800texinfo.texi(,3815) @end menu
3801texinfo.texi(,3816)
3802texinfo.texi(,3817)
3803texinfo.texi(,3818) @node Printing Indices & Menus
3804texinfo.texi(,3819) @section Printing Indices and Menus
3805texinfo.texi(,3820) @findex printindex
3806texinfo.texi(,3821) @cindex Printing an index
3807texinfo.texi(,3822) @cindex Indices, printing and menus
3808texinfo.texi(,3823) @cindex Generating menus with indices
3809texinfo.texi(,3824) @cindex Menus generated with indices
3810texinfo.texi(,3825)
3811texinfo.texi(,3826) To print an index means to include it as part of a manual or Info file.
3812texinfo.texi(,3827) This does not happen automatically just because you use @code{@@cindex}
3813texinfo.texi(,3828) or other index-entry generating commands in the Texinfo file; those just
3814texinfo.texi(,3829) cause the raw data for the index to be accumulated.  To generate an
3815texinfo.texi(,3830) index, you must include the @code{@@printindex} command at the place in
3816texinfo.texi(,3831) the document where you want the index to appear.  Also, as part of the
3817texinfo.texi(,3832) process of creating a printed manual, you must run a program called
3818texinfo.texi(,3833) @code{texindex} (@pxref{Hardcopy}) to sort the raw data to produce a
3819texinfo.texi(,3834) sorted index file.  The sorted index file is what is actually used to
3820texinfo.texi(,3835) print the index.
3821texinfo.texi(,3836)
3822texinfo.texi(,3837) Texinfo offers six separate types of predefined index, each with a
3823texinfo.texi(,3838) two-letter abbreviation, as illustrated in the following table.
3824texinfo.texi(,3839) However, you may merge indices (@pxref{Combining Indices}) or define
3825texinfo.texi(,3840) your own indices (@pxref{New Indices}).
3826texinfo.texi(,3841)
3827texinfo.texi(,3842) Here are the predefined indices, their abbreviations, and the
3828texinfo.texi(,3843) corresponding index entry commands:
3829texinfo.texi(,3844)
3830texinfo.texi(,3845) @table @samp
3831texinfo.texi(,3846) @item cp
3832texinfo.texi(,3847) concept index (@code{@@cindex})
3833texinfo.texi(,3848) @item fn
3834texinfo.texi(,3849) function index (@code{@@findex})
3835texinfo.texi(,3850) @item vr
3836texinfo.texi(,3851) variable index (@code{@@index})
3837texinfo.texi(,3852) @item ky
3838texinfo.texi(,3853) key index (@code{@@kindex})
3839texinfo.texi(,3854) @item pg
3840texinfo.texi(,3855) program index (@code{@@pindex})
3841texinfo.texi(,3856) @item tp
3842texinfo.texi(,3857) data type index (@code{@@tindex})
3843texinfo.texi(,3858) @end table
3844texinfo.texi(,3859)
3845texinfo.texi(,3860) The @code{@@printindex} command takes a two-letter index abbreviation,
3846texinfo.texi(,3861) reads the corresponding sorted index file and formats it appropriately
3847texinfo.texi(,3862) into an index.
3848texinfo.texi(,3863)
3849texinfo.texi(,3864) The @code{@@printindex} command does not generate a chapter heading for
3850texinfo.texi(,3865) the index.  Consequently, you should precede the @code{@@printindex}
3851texinfo.texi(,3866) command with a suitable section or chapter command (usually
3852texinfo.texi(,3867) @code{@@appendix} or @code{@@unnumbered}) to supply the chapter heading
3853texinfo.texi(,3868) and put the index into the table of contents.  Precede the
3854texinfo.texi(,3869) @code{@@unnumbered} command with an @code{@@node} line.
3855texinfo.texi(,3870)
3856texinfo.texi(,3871) For example:
3857texinfo.texi(,3872)
3858texinfo.texi(,3873) @smallexample
3859texinfo.texi(,3874) @group
3860texinfo.texi(,3875) @@node Variable Index
3861texinfo.texi(,3876) @@unnumbered Variable Index
3862texinfo.texi(,3877)
3863texinfo.texi(,3878) @@printindex vr
3864texinfo.texi(,3879) @end group
3865texinfo.texi(,3880)
3866texinfo.texi(,3881) @group
3867texinfo.texi(,3882) @@node Concept Index
3868texinfo.texi(,3883) @@unnumbered Concept Index
3869texinfo.texi(,3884)
3870texinfo.texi(,3885) @@printindex cp
3871texinfo.texi(,3886) @end group
3872texinfo.texi(,3887) @end smallexample
3873texinfo.texi(,3888)
3874texinfo.texi(,3889) @noindent
3875texinfo.texi(,3890)
3876texinfo.texi(,3891) We recommend placing the concept index last, since that makes it easiest
3877texinfo.texi(,3892) to find.  We also recommend having a single index whenever possible,
3878texinfo.texi(,3893) since then readers have only one place to look (@pxref{Combining Indices}).
3879texinfo.texi(,3894)
3880texinfo.texi(,3895)
3881texinfo.texi(,3896) @node Contents
3882texinfo.texi(,3897) @section Generating a Table of Contents
3883texinfo.texi(,3898) @cindex Table of contents
3884texinfo.texi(,3899) @cindex Contents, Table of
3885texinfo.texi(,3900) @cindex Short table of contents
3886texinfo.texi(,3901) @findex contents
3887texinfo.texi(,3902) @findex summarycontents
3888texinfo.texi(,3903) @findex shortcontents
3889texinfo.texi(,3904)
3890texinfo.texi(,3905) The @code{@@chapter}, @code{@@section}, and other structuring commands
3891texinfo.texi(,3906) supply the information to make up a table of contents, but they do not
3892texinfo.texi(,3907) cause an actual table to appear in the manual.  To do this, you must use
3893texinfo.texi(,3908) the @code{@@contents} and/or @code{@@summarycontents} command(s).
3894texinfo.texi(,3909)
3895texinfo.texi(,3910) @table @code
3896texinfo.texi(,3911) @item @@contents
3897texinfo.texi(,3912) Generate a table of contents in a printed manual, including all
3898texinfo.texi(,3913) chapters, sections, subsections, etc., as well as appendices and
3899texinfo.texi(,3914) unnumbered chapters.  Headings generated by the @code{@@heading}
3900texinfo.texi(,3915) series of commands do not appear in the table of contents.
3901texinfo.texi(,3916)
3902texinfo.texi(,3917) @item @@shortcontents
3903texinfo.texi(,3918) @itemx @@summarycontents
3904texinfo.texi(,3919) (@code{@@summarycontents} is a synonym for @code{@@shortcontents}.)
3905texinfo.texi(,3920)
3906texinfo.texi(,3921) Generate a short or summary table of contents that lists only the
3907texinfo.texi(,3922) chapters, appendices, and unnumbered chapters.  Sections, subsections
3908texinfo.texi(,3923) and subsubsections are omitted.  Only a long manual needs a short table
3909texinfo.texi(,3924) of contents in addition to the full table of contents.
3910texinfo.texi(,3925)
3911texinfo.texi(,3926) @end table
3912texinfo.texi(,3927)
3913texinfo.texi(,3928) Both contents commands should be written on a line by themselves.
3914texinfo.texi(,3929) The contents commands automatically generate a chapter-like heading at
3915texinfo.texi(,3930) the top of the first table of contents page, so don't include any
3916texinfo.texi(,3931) sectioning command such as @code{@@unnumbered} before them.
3917texinfo.texi(,3932)
3918texinfo.texi(,3933) Since an Info file uses menus instead of tables of contents, the Info
3919texinfo.texi(,3934) formatting commands ignore the contents commands.  But the contents are
3920texinfo.texi(,3935) included in plain text output (generated by @code{makeinfo
3921texinfo.texi(,3936) --no-headers}), unless @code{makeinfo} is writing its output to standard
3922texinfo.texi(,3937) output.
3923texinfo.texi(,3938)
3924texinfo.texi(,3939) When @code{makeinfo} writes a short table of contents while producing
3925texinfo.texi(,3940) html output, the links in the short table of contents point to
3926texinfo.texi(,3941) corresponding entries in the full table of contents rather than the text
3927texinfo.texi(,3942) of the document. The links in the full table of contents point to the
3928texinfo.texi(,3943) main text of the document.
3929texinfo.texi(,3944)
3930texinfo.texi(,3945) The contents commands can be placed either at the very end of the file,
3931texinfo.texi(,3946) after any indices (see the previous section) and just before the
3932texinfo.texi(,3947) @code{@@bye} (see the next section), or near the beginning of the file,
3933texinfo.texi(,3948) after the @code{@@end titlepage} (@pxref{titlepage}).  The advantage to
3934texinfo.texi(,3949) the former is that then the contents output is always up to date,
3935texinfo.texi(,3950) because it reflects the processing just done.  The advantage to the
3936texinfo.texi(,3951) latter is that the contents are printed in the proper place, thus you do
3937texinfo.texi(,3952) not need to rearrange the DVI file with @command{dviselect} or shuffle
3938texinfo.texi(,3953) paper.
3939texinfo.texi(,3954)
3940texinfo.texi(,3955) @findex setcontentsaftertitlepage
3941texinfo.texi(,3956) @findex setshortcontentsaftertitlepage
3942texinfo.texi(,3957) @cindex Contents, after title page
3943texinfo.texi(,3958) @cindex Table of contents, after title page
3944texinfo.texi(,3959) As an author, you can put the contents commands wherever you prefer.
3945texinfo.texi(,3960) But if you are a user simply printing a manual, you may wish to print
3946texinfo.texi(,3961) the contents after the title page even if the author put the contents
3947texinfo.texi(,3962) commands at the end of the document (as is the case in most existing
3948texinfo.texi(,3963) Texinfo documents, at this writing).  You can do this by specifying
3949texinfo.texi(,3964) @code{@@setcontentsaftertitlepage} and/or
3950texinfo.texi(,3965) @code{@@setshortcontentsaftertitlepage}.  The first prints only the main
3951texinfo.texi(,3966) contents after the @code{@@end titlepage}; the second prints both the
3952texinfo.texi(,3967) short contents and the main contents.  In either case, any subsequent
3953texinfo.texi(,3968) @code{@@contents} or @code{@@shortcontents} is ignored (unless no
3954texinfo.texi(,3969) @code{@@end titlepage} is ever encountered).
3955texinfo.texi(,3970)
3956texinfo.texi(,3971) You need to include the @code{@@set@dots{}contentsaftertitlepage}
3957texinfo.texi(,3972) commands early in the document (just after @code{@@setfilename}, for
3958texinfo.texi(,3973) example).  We recommend using @command{texi2dvi} (@pxref{Format with
3959texinfo.texi(,3974) texi2dvi}) to specify this without altering the source file at all.  For
3960texinfo.texi(,3975) example:
3961texinfo.texi(,3976) @example
3962texinfo.texi(,3977) texi2dvi --texinfo=@@setcontentsaftertitlepage foo.texi
3963texinfo.texi(,3978) @end example
3964texinfo.texi(,3979)
3965texinfo.texi(,3980)
3966texinfo.texi(,3981) @node File End
3967texinfo.texi(,3982) @section @code{@@bye} File Ending
3968texinfo.texi(,3983) @findex bye
3969texinfo.texi(,3984)
3970texinfo.texi(,3985) An @code{@@bye} command terminates @TeX{} or Info formatting.  None of
3971texinfo.texi(,3986) the formatting commands reading anything following @code{@@bye}.  The
3972texinfo.texi(,3987) @code{@@bye} command should be on a line by itself.
3973texinfo.texi(,3988)
3974texinfo.texi(,3989) If you wish, you may follow the @code{@@bye} line with notes. These
3975texinfo.texi(,3990) notes will not be formatted and will not appear in either Info or a
3976texinfo.texi(,3991) printed manual; it is as if text after @code{@@bye} were within
3977texinfo.texi(,3992) @code{@@ignore} @dots{} @code{@@end ignore}.  Also, you may follow the
3978texinfo.texi(,3993) @code{@@bye} line with a local variables list for Emacs.
3979texinfo.texi(,3994) @xref{Compile-Command, , Using Local Variables and the Compile Command},
3980texinfo.texi(,3995) for more information.
3981texinfo.texi(,3996)
3982texinfo.texi(,3997)
3983texinfo.texi(,3998) @node Structuring
3984texinfo.texi(,3999) @chapter Chapter Structuring
3985texinfo.texi(,4000) @cindex Chapter structuring
3986texinfo.texi(,4001) @cindex Structuring of chapters
3987texinfo.texi(,4002)
3988texinfo.texi(,4003) The @dfn{chapter structuring} commands divide a document into a hierarchy of
3989texinfo.texi(,4004) chapters, sections, subsections, and subsubsections.  These commands
3990texinfo.texi(,4005) generate large headings; they also provide information for the table
3991texinfo.texi(,4006) of contents of a printed manual (@pxref{Contents, , Generating a Table
3992texinfo.texi(,4007) of Contents}).@refill
3993texinfo.texi(,4008)
3994texinfo.texi(,4009) The chapter structuring commands do not create an Info node structure,
3995texinfo.texi(,4010) so normally you should put an @code{@@node} command immediately before
3996texinfo.texi(,4011) each chapter structuring command (@pxref{Nodes}).  The only time you
3997texinfo.texi(,4012) are likely to use the chapter structuring commands without using the
3998texinfo.texi(,4013) node structuring commands is if you are writing a document that
3999texinfo.texi(,4014) contains no cross references and will never be transformed into Info
4000texinfo.texi(,4015) format.@refill
4001texinfo.texi(,4016)
4002texinfo.texi(,4017) It is unlikely that you will ever write a Texinfo file that is
4003texinfo.texi(,4018) intended only as an Info file and not as a printable document.  If you
4004texinfo.texi(,4019) do, you might still use chapter structuring commands to create a
4005texinfo.texi(,4020) heading at the top of each node---but you don't need to.@refill
4006texinfo.texi(,4021)
4007texinfo.texi(,4022) @menu
4008texinfo.texi(,4023) * Tree Structuring::            A manual is like an upside down tree @dots{}
4009texinfo.texi(,4024) * Structuring Command Types::   How to divide a manual into parts.
4010texinfo.texi(,4025) * makeinfo top::                The @code{@@top} command, part of the `Top' node.
4011texinfo.texi(,4026) * chapter::
4012texinfo.texi(,4027) * unnumbered & appendix::
4013texinfo.texi(,4028) * majorheading & chapheading::
4014texinfo.texi(,4029) * section::
4015texinfo.texi(,4030) * unnumberedsec appendixsec heading::
4016texinfo.texi(,4031) * subsection::
4017texinfo.texi(,4032) * unnumberedsubsec appendixsubsec subheading::
4018texinfo.texi(,4033) * subsubsection::               Commands for the lowest level sections.
4019texinfo.texi(,4034) * Raise/lower sections::        How to change commands' hierarchical level.
4020texinfo.texi(,4035) @end menu
4021texinfo.texi(,4036)
4022texinfo.texi(,4037)
4023texinfo.texi(,4038) @node Tree Structuring
4024texinfo.texi(,4039) @section Tree Structure of Sections
4025texinfo.texi(,4040) @cindex Tree structuring
4026texinfo.texi(,4041)
4027texinfo.texi(,4042) A Texinfo file is usually structured like a book with chapters,
4028texinfo.texi(,4043) sections, subsections, and the like.  This structure can be visualized
4029texinfo.texi(,4044) as a tree (or rather as an upside-down tree) with the root at the top
4030texinfo.texi(,4045) and the levels corresponding to chapters, sections, subsection, and
4031texinfo.texi(,4046) subsubsections.@refill
4032texinfo.texi(,4047)
4033texinfo.texi(,4048) Here is a diagram that shows a Texinfo file with three chapters,
4034texinfo.texi(,4049) each of which has two sections.@refill
4035texinfo.texi(,4050)
4036texinfo.texi(,4051) @example
4037texinfo.texi(,4052) @group
4038texinfo.texi(,4053)                           Top
4039texinfo.texi(,4054)                            |
4040texinfo.texi(,4055)          -------------------------------------
4041texinfo.texi(,4056)         |                  |                  |
4042texinfo.texi(,4057)      Chapter 1          Chapter 2          Chapter 3
4043texinfo.texi(,4058)         |                  |                  |
4044texinfo.texi(,4059)      --------           --------           --------
4045texinfo.texi(,4060)     |        |         |        |         |        |
4046texinfo.texi(,4061)  Section  Section   Section  Section   Section  Section
4047texinfo.texi(,4062)    1.1      1.2       2.1      2.2       3.1      3.2
4048texinfo.texi(,4063)
4049texinfo.texi(,4064) @end group
4050texinfo.texi(,4065) @end example
4051texinfo.texi(,4066)
4052texinfo.texi(,4067) In a Texinfo file that has this structure, the beginning of Chapter 2
4053texinfo.texi(,4068) looks like this:@refill
4054texinfo.texi(,4069)
4055texinfo.texi(,4070) @example
4056texinfo.texi(,4071) @group
4057texinfo.texi(,4072) @@node    Chapter 2,  Chapter 3, Chapter 1, top
4058texinfo.texi(,4073) @@chapter Chapter 2
4059texinfo.texi(,4074) @end group
4060texinfo.texi(,4075) @end example
4061texinfo.texi(,4076)
4062texinfo.texi(,4077) The chapter structuring commands are described in the sections that
4063texinfo.texi(,4078) follow; the @code{@@node} and @code{@@menu} commands are described in
4064texinfo.texi(,4079) following chapters. (@xref{Nodes}, and see @ref{Menus}.)@refill
4065texinfo.texi(,4080)
4066texinfo.texi(,4081)
4067texinfo.texi(,4082) @node Structuring Command Types
4068texinfo.texi(,4083) @section Structuring Command Types
4069texinfo.texi(,4084)
4070texinfo.texi(,4085) The chapter structuring commands fall into four groups or series, each
4071texinfo.texi(,4086) of which contains structuring commands corresponding to the
4072texinfo.texi(,4087) hierarchical levels of chapters, sections, subsections, and
4073texinfo.texi(,4088) subsubsections.@refill
4074texinfo.texi(,4089)
4075texinfo.texi(,4090) The four groups are the @code{@@chapter} series, the
4076texinfo.texi(,4091) @code{@@unnumbered} series, the @code{@@appendix} series, and the
4077texinfo.texi(,4092) @code{@@heading} series.@refill
4078texinfo.texi(,4093)
4079texinfo.texi(,4094) Each command produces titles that have a different appearance on the
4080texinfo.texi(,4095) printed page or Info file; only some of the commands produce
4081texinfo.texi(,4096) titles that are listed in the table of contents of a printed book or
4082texinfo.texi(,4097) manual.@refill
4083texinfo.texi(,4098)
4084texinfo.texi(,4099) @itemize @bullet
4085texinfo.texi(,4100) @item
4086texinfo.texi(,4101) The @code{@@chapter} and @code{@@appendix} series of commands produce
4087texinfo.texi(,4102) numbered or lettered entries both in the body of a printed work and in
4088texinfo.texi(,4103) its table of contents.@refill
4089texinfo.texi(,4104)
4090texinfo.texi(,4105) @item
4091texinfo.texi(,4106) The @code{@@unnumbered} series of commands produce unnumbered entries
4092texinfo.texi(,4107) both in the body of a printed work and in its table of contents.  The
4093texinfo.texi(,4108) @code{@@top} command, which has a special use, is a member of this
4094texinfo.texi(,4109) series (@pxref{makeinfo top, , @code{@@top}}).@refill
4095texinfo.texi(,4110)
4096texinfo.texi(,4111) @item
4097texinfo.texi(,4112) The @code{@@heading} series of commands produce unnumbered headings
4098texinfo.texi(,4113) that do not appear in a table of contents.  The heading commands never
4099texinfo.texi(,4114) start a new page.@refill
4100texinfo.texi(,4115)
4101texinfo.texi(,4116) @item
4102texinfo.texi(,4117) The @code{@@majorheading} command produces results similar to using
4103texinfo.texi(,4118) the @code{@@chapheading} command but generates a larger vertical
4104texinfo.texi(,4119) whitespace before the heading.@refill
4105texinfo.texi(,4120)
4106texinfo.texi(,4121) @item
4107texinfo.texi(,4122) When an @code{@@setchapternewpage} command says to do so, the
4108texinfo.texi(,4123) @code{@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands
4109texinfo.texi(,4124) start new pages in the printed manual; the @code{@@heading} commands
4110texinfo.texi(,4125) do not.@refill
4111texinfo.texi(,4126) @end itemize
4112texinfo.texi(,4127)
4113texinfo.texi(,4128) Here are the four groups of chapter structuring commands:
4114texinfo.texi(,4129)
4115texinfo.texi(,4130) @tex
4116texinfo.texi(,4131) {\globaldefs = 1 \smallfonts}
4117texinfo.texi(,4132) @end tex
4118texinfo.texi(,4133)
4119texinfo.texi(,4134) @multitable @columnfractions .19 .30 .29 .22
4120texinfo.texi(,4135) @item                        @tab                              @tab                       @tab No new page
4121texinfo.texi(,4136) @item @i{Numbered}           @tab @i{Unnumbered}               @tab @i{Lettered/numbered} @tab @i{Unnumbered}
4122texinfo.texi(,4137) @item In contents            @tab In contents                  @tab In contents           @tab Omitted from@*contents
4123texinfo.texi(,4138) @item                        @tab @code{@@top}                 @tab                       @tab @code{@@majorheading}
4124texinfo.texi(,4139) @item @code{@@chapter}       @tab @code{@@unnumbered}          @tab @code{@@appendix} @tab @code{@@chapheading}
4125texinfo.texi(,4140) @item @code{@@section}       @tab @code{@@unnumberedsec}       @tab @code{@@appendixsec} @tab @code{@@heading}
4126texinfo.texi(,4141) @item @code{@@subsection}    @tab @code{@@unnumberedsubsec}    @tab @code{@@appendixsubsec} @tab @code{@@subheading}
4127texinfo.texi(,4142) @item @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab @code{@@appendixsubsubsec} @tab @code{@@subsubheading}
4128texinfo.texi(,4143) @end multitable
4129texinfo.texi(,4144) @tex
4130texinfo.texi(,4145) {\globaldefs = 1 \textfonts}
4131texinfo.texi(,4146) @end tex
4132texinfo.texi(,4147)
4133texinfo.texi(,4148)
4134texinfo.texi(,4149) @node makeinfo top
4135texinfo.texi(,4150) @section @code{@@top}
4136texinfo.texi(,4151)
4137texinfo.texi(,4152) The @code{@@top} command is a special sectioning command that you use
4138texinfo.texi(,4153) only after an @samp{@@node Top} line at the beginning of a Texinfo file.
4139texinfo.texi(,4154) The @code{@@top} command tells the @code{makeinfo} formatter which node
4140texinfo.texi(,4155) is the `Top' node, so it can use it as the root of the node tree if your
4141texinfo.texi(,4156) manual uses implicit pointers.  It has the same typesetting effect as
4142texinfo.texi(,4157) @code{@@unnumbered} (@pxref{unnumbered & appendix, , @code{@@unnumbered}
4143texinfo.texi(,4158) and @code{@@appendix}}).  For detailed information, see @ref{makeinfo
4144texinfo.texi(,4159) top command, , The @code{@@top} Command}.
4145texinfo.texi(,4160)
4146texinfo.texi(,4161) The @code{@@top} node and its menu (if any) is conventionally wrapped in
4147texinfo.texi(,4162) an @code{@@ifnottex} conditional so that it will appear only in Info and
4148texinfo.texi(,4163) HTML output, not @TeX{}.
4149texinfo.texi(,4164)
4150texinfo.texi(,4165)
4151texinfo.texi(,4166) @node chapter, unnumbered & appendix, makeinfo top, Structuring
4152texinfo.texi(,4167) @comment  node-name,  next,  previous,  up
4153texinfo.texi(,4168) @section @code{@@chapter}
4154texinfo.texi(,4169) @findex chapter
4155texinfo.texi(,4170)
4156texinfo.texi(,4171) @code{@@chapter} identifies a chapter in the document.  Write the
4157texinfo.texi(,4172) command at the beginning of a line and follow it on the same line by
4158texinfo.texi(,4173) the title of the chapter.@refill
4159texinfo.texi(,4174)
4160texinfo.texi(,4175) For example, this chapter in this manual is entitled ``Chapter
4161texinfo.texi(,4176) Structuring''; the @code{@@chapter} line looks like this:@refill
4162texinfo.texi(,4177)
4163texinfo.texi(,4178) @example
4164texinfo.texi(,4179) @@chapter Chapter Structuring
4165texinfo.texi(,4180) @end example
4166texinfo.texi(,4181)
4167texinfo.texi(,4182) In @TeX{}, the @code{@@chapter} command creates a chapter in the
4168texinfo.texi(,4183) document, specifying the chapter title.  The chapter is numbered
4169texinfo.texi(,4184) automatically.@refill
4170texinfo.texi(,4185)
4171texinfo.texi(,4186) In Info, the @code{@@chapter} command causes the title to appear on a
4172texinfo.texi(,4187) line by itself, with a line of asterisks inserted underneath.  Thus,
4173texinfo.texi(,4188) in Info, the above example produces the following output:@refill
4174texinfo.texi(,4189)
4175texinfo.texi(,4190) @example
4176texinfo.texi(,4191) Chapter Structuring
4177texinfo.texi(,4192) *******************
4178texinfo.texi(,4193) @end example
4179texinfo.texi(,4194)
4180texinfo.texi(,4195) @findex centerchap
4181texinfo.texi(,4196) Texinfo also provides a command @code{@@centerchap}, which is analogous
4182texinfo.texi(,4197) to @code{@@unnumbered}, but centers its argument in the printed output.
4183texinfo.texi(,4198) This kind of stylistic choice is not usually offered by Texinfo.
4184texinfo.texi(,4199) @c but the Hacker's Dictionary wanted it ...
4185texinfo.texi(,4200)
4186texinfo.texi(,4201)
4187texinfo.texi(,4202) @node unnumbered & appendix
4188texinfo.texi(,4203) @section @code{@@unnumbered} and @code{@@appendix}
4189texinfo.texi(,4204) @findex unnumbered
4190texinfo.texi(,4205) @findex appendix
4191texinfo.texi(,4206)
4192texinfo.texi(,4207) Use the @code{@@unnumbered} command to create a chapter that appears
4193texinfo.texi(,4208) in a printed manual without chapter numbers of any kind.  Use the
4194texinfo.texi(,4209) @code{@@appendix} command to create an appendix in a printed manual
4195texinfo.texi(,4210) that is labelled by letter instead of by number.@refill
4196texinfo.texi(,4211)
4197texinfo.texi(,4212) For Info file output, the @code{@@unnumbered} and @code{@@appendix}
4198texinfo.texi(,4213) commands are equivalent to @code{@@chapter}: the title is printed on a
4199texinfo.texi(,4214) line by itself with a line of asterisks underneath.  (@xref{chapter, ,
4200texinfo.texi(,4215) @code{@@chapter}}.)@refill
4201texinfo.texi(,4216)
4202texinfo.texi(,4217) To create an appendix or an unnumbered chapter, write an
4203texinfo.texi(,4218) @code{@@appendix} or @code{@@unnumbered} command at the beginning of a
4204texinfo.texi(,4219) line and follow it on the same line by the title, as you would if you
4205texinfo.texi(,4220) were creating a chapter.@refill
4206texinfo.texi(,4221)
4207texinfo.texi(,4222)
4208texinfo.texi(,4223) @node majorheading & chapheading, section, unnumbered & appendix, Structuring
4209texinfo.texi(,4224) @section @code{@@majorheading}, @code{@@chapheading}
4210texinfo.texi(,4225) @findex majorheading
4211texinfo.texi(,4226) @findex chapheading
4212texinfo.texi(,4227)
4213texinfo.texi(,4228) The @code{@@majorheading} and @code{@@chapheading} commands put
4214texinfo.texi(,4229) chapter-like headings in the body of a document.@refill
4215texinfo.texi(,4230)
4216texinfo.texi(,4231) However, neither command causes @TeX{} to produce a numbered heading
4217texinfo.texi(,4232) or an entry in the table of contents; and neither command causes
4218texinfo.texi(,4233) @TeX{} to start a new page in a printed manual.@refill
4219texinfo.texi(,4234)
4220texinfo.texi(,4235) In @TeX{}, an @code{@@majorheading} command generates a larger vertical
4221texinfo.texi(,4236) whitespace before the heading than an @code{@@chapheading} command but
4222texinfo.texi(,4237) is otherwise the same.@refill
4223texinfo.texi(,4238)
4224texinfo.texi(,4239) In Info,
4225texinfo.texi(,4240) the @code{@@majorheading} and
4226texinfo.texi(,4241) @code{@@chapheading} commands are equivalent to
4227texinfo.texi(,4242) @code{@@chapter}: the title is printed on a line by itself with a line
4228texinfo.texi(,4243) of asterisks underneath.  (@xref{chapter, , @code{@@chapter}}.)@refill
4229texinfo.texi(,4244)
4230texinfo.texi(,4245) @node section, unnumberedsec appendixsec heading, majorheading & chapheading, Structuring
4231texinfo.texi(,4246) @comment  node-name,  next,  previous,  up
4232texinfo.texi(,4247) @section @code{@@section}
4233texinfo.texi(,4248) @findex section
4234texinfo.texi(,4249)
4235texinfo.texi(,4250) In a printed manual, an @code{@@section} command identifies a
4236texinfo.texi(,4251) numbered section within a chapter.  The section title appears in the
4237texinfo.texi(,4252) table of contents.  In Info, an @code{@@section} command provides a
4238texinfo.texi(,4253) title for a segment of text, underlined with @samp{=}.@refill
4239texinfo.texi(,4254)
4240texinfo.texi(,4255) This section is headed with an @code{@@section} command and looks like
4241texinfo.texi(,4256) this in the Texinfo file:@refill
4242texinfo.texi(,4257)
4243texinfo.texi(,4258) @example
4244texinfo.texi(,4259) @@section @@code@{@@@@section@}
4245texinfo.texi(,4260) @end example
4246texinfo.texi(,4261)
4247texinfo.texi(,4262) To create a section, write the @code{@@section} command at the
4248texinfo.texi(,4263) beginning of a line and follow it on the same line by the section
4249texinfo.texi(,4264) title.@refill
4250texinfo.texi(,4265)
4251texinfo.texi(,4266) Thus,
4252texinfo.texi(,4267)
4253texinfo.texi(,4268) @example
4254texinfo.texi(,4269) @@section This is a section
4255texinfo.texi(,4270) @end example
4256texinfo.texi(,4271)
4257texinfo.texi(,4272) @noindent
4258texinfo.texi(,4273) produces
4259texinfo.texi(,4274)
4260texinfo.texi(,4275) @example
4261texinfo.texi(,4276) @group
4262texinfo.texi(,4277) This is a section
4263texinfo.texi(,4278) =================
4264texinfo.texi(,4279) @end group
4265texinfo.texi(,4280) @end example
4266texinfo.texi(,4281)
4267texinfo.texi(,4282) @noindent
4268texinfo.texi(,4283) in Info.
4269texinfo.texi(,4284)
4270texinfo.texi(,4285) @node unnumberedsec appendixsec heading, subsection, section, Structuring
4271texinfo.texi(,4286) @comment  node-name,  next,  previous,  up
4272texinfo.texi(,4287) @section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
4273texinfo.texi(,4288) @findex unnumberedsec
4274texinfo.texi(,4289) @findex appendixsec
4275texinfo.texi(,4290) @findex heading
4276texinfo.texi(,4291)
4277texinfo.texi(,4292) The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading}
4278texinfo.texi(,4293) commands are, respectively, the unnumbered, appendix-like, and
4279texinfo.texi(,4294) heading-like equivalents of the @code{@@section} command.
4280texinfo.texi(,4295) (@xref{section, , @code{@@section}}.)@refill
4281texinfo.texi(,4296)
4282texinfo.texi(,4297) @table @code
4283texinfo.texi(,4298) @item @@unnumberedsec
4284texinfo.texi(,4299) The @code{@@unnumberedsec} command may be used within an
4285texinfo.texi(,4300) unnumbered chapter or within a regular chapter or appendix to
4286texinfo.texi(,4301) provide an unnumbered section.@refill
4287texinfo.texi(,4302)
4288texinfo.texi(,4303) @item @@appendixsec
4289texinfo.texi(,4304) @itemx @@appendixsection
4290texinfo.texi(,4305) @code{@@appendixsection} is a longer spelling of the
4291texinfo.texi(,4306) @code{@@appendixsec} command; the two are synonymous.@refill
4292texinfo.texi(,4307) @findex appendixsection
4293texinfo.texi(,4308)
4294texinfo.texi(,4309) Conventionally, the @code{@@appendixsec} or @code{@@appendixsection}
4295texinfo.texi(,4310) command is used only within appendices.@refill
4296texinfo.texi(,4311)
4297texinfo.texi(,4312) @item @@heading
4298texinfo.texi(,4313) You may use the @code{@@heading} command anywhere you wish for a
4299texinfo.texi(,4314) section-style heading that will not appear in the table of contents.@refill
4300texinfo.texi(,4315) @end table
4301texinfo.texi(,4316)
4302texinfo.texi(,4317) @node subsection, unnumberedsubsec appendixsubsec subheading, unnumberedsec appendixsec heading, Structuring
4303texinfo.texi(,4318) @comment  node-name,  next,  previous,  up
4304texinfo.texi(,4319) @section The @code{@@subsection} Command
4305texinfo.texi(,4320) @findex subsection
4306texinfo.texi(,4321)
4307texinfo.texi(,4322) Subsections are to sections as sections are to chapters.
4308texinfo.texi(,4323) (@xref{section, , @code{@@section}}.)  In Info, subsection titles are
4309texinfo.texi(,4324) underlined with @samp{-}.  For example,@refill
4310texinfo.texi(,4325)
4311texinfo.texi(,4326) @example
4312texinfo.texi(,4327) @@subsection This is a subsection
4313texinfo.texi(,4328) @end example
4314texinfo.texi(,4329)
4315texinfo.texi(,4330) @noindent
4316texinfo.texi(,4331) produces
4317texinfo.texi(,4332)
4318texinfo.texi(,4333) @example
4319texinfo.texi(,4334) @group
4320texinfo.texi(,4335) This is a subsection
4321texinfo.texi(,4336) --------------------
4322texinfo.texi(,4337) @end group
4323texinfo.texi(,4338) @end example
4324texinfo.texi(,4339)
4325texinfo.texi(,4340) In a printed manual, subsections are listed in the table of contents
4326texinfo.texi(,4341) and are numbered three levels deep.@refill
4327texinfo.texi(,4342)
4328texinfo.texi(,4343) @node unnumberedsubsec appendixsubsec subheading, subsubsection, subsection, Structuring
4329texinfo.texi(,4344) @comment  node-name,  next,  previous,  up
4330texinfo.texi(,4345) @section The @code{@@subsection}-like Commands
4331texinfo.texi(,4346) @cindex Subsection-like commands
4332texinfo.texi(,4347) @findex unnumberedsubsec
4333texinfo.texi(,4348) @findex appendixsubsec
4334texinfo.texi(,4349) @findex subheading
4335texinfo.texi(,4350)
4336texinfo.texi(,4351) The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and
4337texinfo.texi(,4352) @code{@@subheading} commands are, respectively, the unnumbered,
4338texinfo.texi(,4353) appendix-like, and heading-like equivalents of the @code{@@subsection}
4339texinfo.texi(,4354) command.  (@xref{subsection, , @code{@@subsection}}.)@refill
4340texinfo.texi(,4355)
4341texinfo.texi(,4356) In Info, the @code{@@subsection}-like commands generate a title
4342texinfo.texi(,4357) underlined with hyphens.  In a printed manual, an @code{@@subheading}
4343texinfo.texi(,4358) command produces a heading like that of a subsection except that it is
4344texinfo.texi(,4359) not numbered and does not appear in the table of contents.  Similarly,
4345texinfo.texi(,4360) an @code{@@unnumberedsubsec} command produces an unnumbered heading like
4346texinfo.texi(,4361) that of a subsection and an @code{@@appendixsubsec} command produces a
4347texinfo.texi(,4362) subsection-like heading labelled with a letter and numbers; both of
4348texinfo.texi(,4363) these commands produce headings that appear in the table of
4349texinfo.texi(,4364) contents.@refill
4350texinfo.texi(,4365)
4351texinfo.texi(,4366) @node subsubsection, Raise/lower sections, unnumberedsubsec appendixsubsec subheading, Structuring
4352texinfo.texi(,4367) @comment  node-name,  next,  previous,  up
4353texinfo.texi(,4368) @section The `subsub' Commands
4354texinfo.texi(,4369) @cindex Subsub commands
4355texinfo.texi(,4370) @findex subsubsection
4356texinfo.texi(,4371) @findex unnumberedsubsubsec
4357texinfo.texi(,4372) @findex appendixsubsubsec
4358texinfo.texi(,4373) @findex subsubheading
4359texinfo.texi(,4374)
4360texinfo.texi(,4375) The fourth and lowest level sectioning commands in Texinfo are the
4361texinfo.texi(,4376) `subsub' commands.  They are:@refill
4362texinfo.texi(,4377)
4363texinfo.texi(,4378) @table @code
4364texinfo.texi(,4379) @item @@subsubsection
4365texinfo.texi(,4380) Subsubsections are to subsections as subsections are to sections.
4366texinfo.texi(,4381) (@xref{subsection, , @code{@@subsection}}.)  In a printed manual,
4367texinfo.texi(,4382) subsubsection titles appear in the table of contents and are numbered
4368texinfo.texi(,4383) four levels deep.@refill
4369texinfo.texi(,4384)
4370texinfo.texi(,4385) @item @@unnumberedsubsubsec
4371texinfo.texi(,4386) Unnumbered subsubsection titles appear in the table of contents of a
4372texinfo.texi(,4387) printed manual, but lack numbers.  Otherwise, unnumbered
4373texinfo.texi(,4388) subsubsections are the same as subsubsections.  In Info, unnumbered
4374texinfo.texi(,4389) subsubsections look exactly like ordinary subsubsections.@refill
4375texinfo.texi(,4390)
4376texinfo.texi(,4391) @item @@appendixsubsubsec
4377texinfo.texi(,4392) Conventionally, appendix commands are used only for appendices and are
4378texinfo.texi(,4393) lettered and numbered appropriately in a printed manual.  They also
4379texinfo.texi(,4394) appear in the table of contents.  In Info, appendix subsubsections look
4380texinfo.texi(,4395) exactly like ordinary subsubsections.@refill
4381texinfo.texi(,4396)
4382texinfo.texi(,4397) @item @@subsubheading
4383texinfo.texi(,4398) The @code{@@subsubheading} command may be used anywhere that you need
4384texinfo.texi(,4399) a small heading that will not appear in the table of contents.  In
4385texinfo.texi(,4400) Info, subsubheadings look exactly like ordinary subsubsection
4386texinfo.texi(,4401) headings.@refill
4387texinfo.texi(,4402) @end table
4388texinfo.texi(,4403)
4389texinfo.texi(,4404) In Info,  `subsub' titles are underlined with periods.
4390texinfo.texi(,4405) For example,@refill
4391texinfo.texi(,4406)
4392texinfo.texi(,4407) @example
4393texinfo.texi(,4408) @@subsubsection This is a subsubsection
4394texinfo.texi(,4409) @end example
4395texinfo.texi(,4410)
4396texinfo.texi(,4411) @noindent
4397texinfo.texi(,4412) produces
4398texinfo.texi(,4413)
4399texinfo.texi(,4414) @example
4400texinfo.texi(,4415) @group
4401texinfo.texi(,4416) This is a subsubsection
4402texinfo.texi(,4417) .......................
4403texinfo.texi(,4418) @end group
4404texinfo.texi(,4419) @end example
4405texinfo.texi(,4420)
4406texinfo.texi(,4421) @node Raise/lower sections,  , subsubsection, Structuring
4407texinfo.texi(,4422) @comment  node-name,  next,  previous,  up
4408texinfo.texi(,4423) @section @code{@@raisesections} and @code{@@lowersections}
4409texinfo.texi(,4424) @findex raisesections
4410texinfo.texi(,4425) @findex lowersections
4411texinfo.texi(,4426) @cindex Raising and lowering sections
4412texinfo.texi(,4427) @cindex Sections, raising and lowering
4413texinfo.texi(,4428)
4414texinfo.texi(,4429) The @code{@@raisesections} and @code{@@lowersections} commands raise and
4415texinfo.texi(,4430) lower the hierarchical level of chapters, sections, subsections and the
4416texinfo.texi(,4431) like.  The @code{@@raisesections} command changes sections to chapters,
4417texinfo.texi(,4432) subsections to sections, and so on.  The @code{@@lowersections} command
4418texinfo.texi(,4433) changes chapters to sections, sections to subsections, and so on.
4419texinfo.texi(,4434)
4420texinfo.texi(,4435) @cindex Include files, and section levels
4421texinfo.texi(,4436) An @code{@@lowersections} command is useful if you wish to include text
4422texinfo.texi(,4437) that is written as an outer or standalone Texinfo file in another
4423texinfo.texi(,4438) Texinfo file as an inner, included file.  If you write the command at
4424texinfo.texi(,4439) the beginning of the file, all your @code{@@chapter} commands are
4425texinfo.texi(,4440) formatted as if they were @code{@@section} commands, all your
4426texinfo.texi(,4441) @code{@@section} command are formatted as if they were
4427texinfo.texi(,4442) @code{@@subsection} commands, and so on.
4428texinfo.texi(,4443)
4429texinfo.texi(,4444) @need 1000
4430texinfo.texi(,4445) @code{@@raisesections} raises a command one level in the chapter
4431texinfo.texi(,4446) structuring hierarchy:@refill
4432texinfo.texi(,4447)
4433texinfo.texi(,4448) @example
4434texinfo.texi(,4449) @group
4435texinfo.texi(,4450)   @r{Change}           @r{To}
4436texinfo.texi(,4451)
4437texinfo.texi(,4452) @@subsection     @@section,
4438texinfo.texi(,4453) @@section        @@chapter,
4439texinfo.texi(,4454) @@heading        @@chapheading,
4440texinfo.texi(,4455)           @r{etc.}
4441texinfo.texi(,4456) @end group
4442texinfo.texi(,4457) @end example
4443texinfo.texi(,4458)
4444texinfo.texi(,4459) @need 1000
4445texinfo.texi(,4460) @code{@@lowersections} lowers a command one level in the chapter
4446texinfo.texi(,4461) structuring hierarchy:@refill
4447texinfo.texi(,4462)
4448texinfo.texi(,4463) @example
4449texinfo.texi(,4464) @group
4450texinfo.texi(,4465)   @r{Change}           @r{To}
4451texinfo.texi(,4466)
4452texinfo.texi(,4467) @@chapter        @@section,
4453texinfo.texi(,4468) @@subsection     @@subsubsection,
4454texinfo.texi(,4469) @@heading        @@subheading,
4455texinfo.texi(,4470)           @r{etc.}
4456texinfo.texi(,4471) @end group
4457texinfo.texi(,4472) @end example
4458texinfo.texi(,4473)
4459texinfo.texi(,4474) An @code{@@raisesections} or @code{@@lowersections} command changes only
4460texinfo.texi(,4475) those structuring commands that follow the command in the Texinfo file.
4461texinfo.texi(,4476) Write an @code{@@raisesections} or @code{@@lowersections} command on a
4462texinfo.texi(,4477) line of its own.
4463texinfo.texi(,4478)
4464texinfo.texi(,4479) An @code{@@lowersections} command cancels an @code{@@raisesections}
4465texinfo.texi(,4480) command, and vice versa.  Typically, the commands are used like this:
4466texinfo.texi(,4481)
4467texinfo.texi(,4482) @example
4468texinfo.texi(,4483) @@lowersections
4469texinfo.texi(,4484) @@include somefile.texi
4470texinfo.texi(,4485) @@raisesections
4471texinfo.texi(,4486) @end example
4472texinfo.texi(,4487)
4473texinfo.texi(,4488) Without the @code{@@raisesections}, all the subsequent sections in your
4474texinfo.texi(,4489) document will be lowered.
4475texinfo.texi(,4490)
4476texinfo.texi(,4491) Repeated use of the commands continue to raise or lower the hierarchical
4477texinfo.texi(,4492) level a step at a time.
4478texinfo.texi(,4493)
4479texinfo.texi(,4494) An attempt to raise above `chapters' reproduces chapter commands; an
4480texinfo.texi(,4495) attempt to lower below `subsubsections' reproduces subsubsection
4481texinfo.texi(,4496) commands.
4482texinfo.texi(,4497)
4483texinfo.texi(,4498) @node Nodes
4484texinfo.texi(,4499) @chapter Nodes
4485texinfo.texi(,4500)
4486texinfo.texi(,4501) @dfn{Nodes} are the primary segments of a Texinfo file.  They do not
4487texinfo.texi(,4502) themselves impose a hierarchical or any other kind of structure on a file.
4488texinfo.texi(,4503) Nodes contain @dfn{node pointers} that name other nodes, and can contain
4489texinfo.texi(,4504) @dfn{menus} which are lists of nodes.  In Info, the movement commands
4490texinfo.texi(,4505) can carry you to a pointed-to node or to a node listed in a menu.  Node
4491texinfo.texi(,4506) pointers and menus provide structure for Info files just as chapters,
4492texinfo.texi(,4507) sections, subsections, and the like, provide structure for printed
4493texinfo.texi(,4508) books.@refill
4494texinfo.texi(,4509)
4495texinfo.texi(,4510) @menu
4496texinfo.texi(,4511) * Two Paths::                   Different commands to structure
4497texinfo.texi(,4512)                                   Info output and printed output.
4498texinfo.texi(,4513) * Node Menu Illustration::      A diagram, and sample nodes and menus.
4499texinfo.texi(,4514) * node::                        Creating nodes, in detail.
4500texinfo.texi(,4515) * makeinfo Pointer Creation::   Letting makeinfo determine node pointers.
4501texinfo.texi(,4516) * anchor::                      Defining arbitrary cross-reference targets.
4502texinfo.texi(,4517) @end menu
4503texinfo.texi(,4518)
4504texinfo.texi(,4519)
4505texinfo.texi(,4520) @node Two Paths
4506texinfo.texi(,4521) @section Two Paths
4507texinfo.texi(,4522)
4508texinfo.texi(,4523) The node and menu commands and the chapter structuring commands are
4509texinfo.texi(,4524) technically independent of each other:
4510texinfo.texi(,4525)
4511texinfo.texi(,4526) @itemize @bullet
4512texinfo.texi(,4527) @item
4513texinfo.texi(,4528) In Info, node and menu commands provide structure.  The chapter
4514texinfo.texi(,4529) structuring commands generate headings with different kinds of
4515texinfo.texi(,4530) underlining---asterisks for chapters, hyphens for sections, and so on;
4516texinfo.texi(,4531) they do nothing else.@refill
4517texinfo.texi(,4532)
4518texinfo.texi(,4533) @item
4519texinfo.texi(,4534) In @TeX{}, the chapter structuring commands generate chapter and section
4520texinfo.texi(,4535) numbers and tables of contents.  The node and menu commands provide
4521texinfo.texi(,4536) information for cross references; they do nothing else.@refill
4522texinfo.texi(,4537) @end itemize
4523texinfo.texi(,4538)
4524texinfo.texi(,4539) You can use node pointers and menus to structure an Info file any way
4525texinfo.texi(,4540) you want; and you can write a Texinfo file so that its Info output has a
4526texinfo.texi(,4541) different structure than its printed output.  However, virtually all
4527texinfo.texi(,4542) Texinfo files are written such that the structure for the Info output
4528texinfo.texi(,4543) corresponds to the structure for the printed output.  It is neither
4529texinfo.texi(,4544) convenient nor understandable to the reader to do otherwise.@refill
4530texinfo.texi(,4545)
4531texinfo.texi(,4546) Generally, printed output is structured in a tree-like hierarchy in
4532texinfo.texi(,4547) which the chapters are the major limbs from which the sections branch
4533texinfo.texi(,4548) out.  Similarly, node pointers and menus are organized to create a
4534texinfo.texi(,4549) matching structure in the Info output.@refill
4535texinfo.texi(,4550)
4536texinfo.texi(,4551)
4537texinfo.texi(,4552) @node Node Menu Illustration
4538texinfo.texi(,4553) @section Node and Menu Illustration
4539texinfo.texi(,4554)
4540texinfo.texi(,4555) Here is a copy of the diagram shown earlier that illustrates a Texinfo
4541texinfo.texi(,4556) file with three chapters, each of which contains two sections.@refill
4542texinfo.texi(,4557)
4543texinfo.texi(,4558) The ``root'' is at the top of the diagram and the ``leaves'' are at the
4544texinfo.texi(,4559) bottom.  This is how such a diagram is drawn conventionally; it
4545texinfo.texi(,4560) illustrates an upside-down tree.  For this reason, the root node is
4546texinfo.texi(,4561) called the `Top' node, and `Up' node pointers carry you closer to the
4547texinfo.texi(,4562) root.@refill
4548texinfo.texi(,4563)
4549texinfo.texi(,4564) @example
4550texinfo.texi(,4565) @group
4551texinfo.texi(,4566)                           Top
4552texinfo.texi(,4567)                            |
4553texinfo.texi(,4568)          -------------------------------------
4554texinfo.texi(,4569)         |                  |                  |
4555texinfo.texi(,4570)      Chapter 1          Chapter 2          Chapter 3
4556texinfo.texi(,4571)         |                  |                  |
4557texinfo.texi(,4572)      --------           --------           --------
4558texinfo.texi(,4573)     |        |         |        |         |        |
4559texinfo.texi(,4574)  Section  Section   Section  Section   Section  Section
4560texinfo.texi(,4575)    1.1      1.2       2.1      2.2       3.1      3.2
4561texinfo.texi(,4576) @end group
4562texinfo.texi(,4577) @end example
4563texinfo.texi(,4578)
4564texinfo.texi(,4579) The fully-written command to start Chapter 2 would be this:
4565texinfo.texi(,4580)
4566texinfo.texi(,4581) @example
4567texinfo.texi(,4582) @group
4568texinfo.texi(,4583) @@node     Chapter 2,  Chapter 3, Chapter 1, Top
4569texinfo.texi(,4584) @@comment  node-name,  next,      previous,  up
4570texinfo.texi(,4585) @end group
4571texinfo.texi(,4586) @end example
4572texinfo.texi(,4587)
4573texinfo.texi(,4588) @noindent
4574texinfo.texi(,4589) This @code{@@node} line says that the name of this node is ``Chapter
4575texinfo.texi(,4590) 2'', the name of the `Next' node is ``Chapter 3'', the name of the
4576texinfo.texi(,4591) `Previous' node is ``Chapter 1'', and the name of the `Up' node is
4577texinfo.texi(,4592) ``Top''.  You can omit writing out these node names if your document is
4578texinfo.texi(,4593) hierarchically organized (@pxref{makeinfo Pointer Creation}), but the
4579texinfo.texi(,4594) pointer relationships still obtain.
4580texinfo.texi(,4595)
4581texinfo.texi(,4596) @quotation
4582texinfo.texi(,4597) @strong{Please Note:} `Next' refers to the next node at the same
4583texinfo.texi(,4598) hierarchical level in the manual, not necessarily to the next node
4584texinfo.texi(,4599) within the Texinfo file.  In the Texinfo file, the subsequent node may
4585texinfo.texi(,4600) be at a lower level---a section-level node most often follows a
4586texinfo.texi(,4601) chapter-level node, for example.  `Next' and `Previous' refer to nodes
4587texinfo.texi(,4602) at the @emph{same} hierarchical level.  (The `Top' node contains the
4588texinfo.texi(,4603) exception to this rule.  Since the `Top' node is the only node at that
4589texinfo.texi(,4604) level, `Next' refers to the first following node, which is almost always
4590texinfo.texi(,4605) a chapter or chapter-level node.)@refill
4591texinfo.texi(,4606) @end quotation
4592texinfo.texi(,4607)
4593texinfo.texi(,4608) To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter
4594texinfo.texi(,4609) 2.  (@xref{Menus}.)  You would write the menu just
4595texinfo.texi(,4610) before the beginning of Section 2.1, like this:@refill
4596texinfo.texi(,4611)
4597texinfo.texi(,4612) @example
4598texinfo.texi(,4613) @group
4599texinfo.texi(,4614)     @@menu
4600texinfo.texi(,4615)     * Sect. 2.1::    Description of this section.
4601texinfo.texi(,4616)     * Sect. 2.2::
4602texinfo.texi(,4617)     @@end menu
4603texinfo.texi(,4618) @end group
4604texinfo.texi(,4619) @end example
4605texinfo.texi(,4620)
4606texinfo.texi(,4621) Write the node for Sect. 2.1 like this:@refill
4607texinfo.texi(,4622)
4608texinfo.texi(,4623) @example
4609texinfo.texi(,4624) @group
4610texinfo.texi(,4625)     @@node     Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
4611texinfo.texi(,4626)     @@comment  node-name, next,      previous,  up
4612texinfo.texi(,4627) @end group
4613texinfo.texi(,4628) @end example
4614texinfo.texi(,4629)
4615texinfo.texi(,4630) In Info format, the `Next' and `Previous' pointers of a node usually
4616texinfo.texi(,4631) lead to other nodes at the same level---from chapter to chapter or from
4617texinfo.texi(,4632) section to section (sometimes, as shown, the `Previous' pointer points
4618texinfo.texi(,4633) up); an `Up' pointer usually leads to a node at the level above (closer
4619texinfo.texi(,4634) to the `Top' node); and a `Menu' leads to nodes at a level below (closer
4620texinfo.texi(,4635) to `leaves').  (A cross reference can point to a node at any level;
4621texinfo.texi(,4636) see @ref{Cross References}.)@refill
4622texinfo.texi(,4637)
4623texinfo.texi(,4638) Usually, an @code{@@node} command and a chapter structuring command are
4624texinfo.texi(,4639) used in sequence, along with indexing commands.  (You may follow the
4625texinfo.texi(,4640) @code{@@node} line with a comment line that reminds you which pointer is
4626texinfo.texi(,4641) which.)@refill
4627texinfo.texi(,4642)
4628texinfo.texi(,4643) Here is the beginning of the chapter in this manual called ``Ending a
4629texinfo.texi(,4644) Texinfo File''.  This shows an @code{@@node} line followed by a comment
4630texinfo.texi(,4645) line, an @code{@@chapter} line, and then by indexing lines.@refill
4631texinfo.texi(,4646)
4632texinfo.texi(,4647) @example
4633texinfo.texi(,4648) @group
4634texinfo.texi(,4649) @@node    Ending a File, Structuring, Beginning a File, Top
4635texinfo.texi(,4650) @@comment node-name,     next,        previous,         up
4636texinfo.texi(,4651) @@chapter Ending a Texinfo File
4637texinfo.texi(,4652) @@cindex Ending a Texinfo file
4638texinfo.texi(,4653) @@cindex Texinfo file ending
4639texinfo.texi(,4654) @@cindex File ending
4640texinfo.texi(,4655) @end group
4641texinfo.texi(,4656) @end example
4642texinfo.texi(,4657)
4643texinfo.texi(,4658)
4644texinfo.texi(,4659) @node node
4645texinfo.texi(,4660) @section The @code{@@node} Command
4646texinfo.texi(,4661)
4647texinfo.texi(,4662) @cindex Node, defined
4648texinfo.texi(,4663) @findex node
4649texinfo.texi(,4664)
4650texinfo.texi(,4665) A @dfn{node} is a segment of text that begins at an @code{@@node}
4651texinfo.texi(,4666) command and continues until the next @code{@@node} command.  The
4652texinfo.texi(,4667) definition of node is different from that for chapter or section.  A
4653texinfo.texi(,4668) chapter may contain sections and a section may contain subsections;
4654texinfo.texi(,4669) but a node cannot contain subnodes; the text of a node continues only
4655texinfo.texi(,4670) until the next @code{@@node} command in the file.  A node usually
4656texinfo.texi(,4671) contains only one chapter structuring command, the one that follows
4657texinfo.texi(,4672) the @code{@@node} line.  On the other hand, in printed output nodes
4658texinfo.texi(,4673) are used only for cross references, so a chapter or section may
4659texinfo.texi(,4674) contain any number of nodes.  Indeed, a chapter usually contains
4660texinfo.texi(,4675) several nodes, one for each section, subsection, and
4661texinfo.texi(,4676) subsubsection.@refill
4662texinfo.texi(,4677)
4663texinfo.texi(,4678) To create a node, write an @code{@@node} command at the beginning of a
4664texinfo.texi(,4679) line, and follow it with up to four arguments, separated by commas, on
4665texinfo.texi(,4680) the rest of the same line.  The first argument is required; it is the
4666texinfo.texi(,4681) name of this node.  The subsequent arguments are the names of the
4667texinfo.texi(,4682) `Next', `Previous', and `Up' pointers, in that order, and may be omitted
4668texinfo.texi(,4683) if your Texinfo document is hierarchically organized (@pxref{makeinfo
4669texinfo.texi(,4684) Pointer Creation}).
4670texinfo.texi(,4685)
4671texinfo.texi(,4686) You may insert spaces before each name if you wish; the spaces are
4672texinfo.texi(,4687) ignored.  You must write the name of the node and the names of the
4673texinfo.texi(,4688) `Next', `Previous', and `Up' pointers all on the same line.  Otherwise,
4674texinfo.texi(,4689) the formatters fail.  (@inforef{Top, info, info}, for more information
4675texinfo.texi(,4690) about nodes in Info.)
4676texinfo.texi(,4691)
4677texinfo.texi(,4692) Usually, you write one of the chapter-structuring command lines
4678texinfo.texi(,4693) immediately after an @code{@@node} line---for example, an
4679texinfo.texi(,4694) @code{@@section} or @code{@@subsection} line.  (@xref{Structuring
4680texinfo.texi(,4695) Command Types}.)
4681texinfo.texi(,4696)
4682texinfo.texi(,4697) @quotation
4683texinfo.texi(,4698) @strong{Please note:} The GNU Emacs Texinfo mode updating commands work
4684texinfo.texi(,4699) only with Texinfo files in which @code{@@node} lines are followed by chapter
4685texinfo.texi(,4700) structuring lines.  @xref{Updating Requirements}.@refill
4686texinfo.texi(,4701) @end quotation
4687texinfo.texi(,4702)
4688texinfo.texi(,4703) @TeX{} uses @code{@@node} lines to identify the names to use for cross
4689texinfo.texi(,4704) references.  For this reason, you must write @code{@@node} lines in a
4690texinfo.texi(,4705) Texinfo file that you intend to format for printing, even if you do not
4691texinfo.texi(,4706) intend to format it for Info.  (Cross references, such as the one at the
4692texinfo.texi(,4707) end of this sentence, are made with @code{@@xref} and related commands;
4693texinfo.texi(,4708) see @ref{Cross References}.)@refill
4694texinfo.texi(,4709)
4695texinfo.texi(,4710) @menu
4696texinfo.texi(,4711) * Node Names::                  How to choose node and pointer names.
4697texinfo.texi(,4712) * Writing a Node::              How to write an @code{@@node} line.
4698texinfo.texi(,4713) * Node Line Tips::              Keep names short.
4699texinfo.texi(,4714) * Node Line Requirements::      Keep names unique, without @@-commands.
4700texinfo.texi(,4715) * First Node::                  How to write a `Top' node.
4701texinfo.texi(,4716) * makeinfo top command::        How to use the @code{@@top} command.
4702texinfo.texi(,4717) @end menu
4703texinfo.texi(,4718)
4704texinfo.texi(,4719)
4705texinfo.texi(,4720) @node Node Names
4706texinfo.texi(,4721) @subsection Choosing Node and Pointer Names
4707texinfo.texi(,4722)
4708texinfo.texi(,4723) @cindex Node names, choosing
4709texinfo.texi(,4724) The name of a node identifies the node.  The pointers enable
4710texinfo.texi(,4725) you to reach other nodes and consist of the names of those nodes.@refill
4711texinfo.texi(,4726)
4712texinfo.texi(,4727) Normally, a node's `Up' pointer contains the name of the node whose menu
4713texinfo.texi(,4728) mentions that node.  The node's `Next' pointer contains the name of the
4714texinfo.texi(,4729) node that follows that node in that menu and its `Previous' pointer
4715texinfo.texi(,4730) contains the name of the node that precedes it in that menu.  When a
4716texinfo.texi(,4731) node's `Previous' node is the same as its `Up' node, both node pointers
4717texinfo.texi(,4732) name the same node.@refill
4718texinfo.texi(,4733)
4719texinfo.texi(,4734) Usually, the first node of a Texinfo file is the `Top' node, and its
4720texinfo.texi(,4735) `Up' and `Previous' pointers point to the @file{dir} file, which
4721texinfo.texi(,4736) contains the main menu for all of Info.@refill
4722texinfo.texi(,4737)
4723texinfo.texi(,4738) The `Top' node itself contains the main or master menu for the manual.
4724texinfo.texi(,4739) Also, it is helpful to include a brief description of the manual in the
4725texinfo.texi(,4740) `Top' node.  @xref{First Node}, for information on how to write the
4726texinfo.texi(,4741) first node of a Texinfo file.@refill
4727texinfo.texi(,4742)
4728texinfo.texi(,4743) Even when you explicitly specify all pointers, that does not mean you
4729texinfo.texi(,4744) can write the nodes in the Texinfo source file in an arbitrary order!
4730texinfo.texi(,4745) Because @TeX{} processes the file sequentially, irrespective of node
4731texinfo.texi(,4746) pointers, you must write the nodes in the order you wish them to appear
4732texinfo.texi(,4747) in the printed output.
4733texinfo.texi(,4748)
4734texinfo.texi(,4749)
4735texinfo.texi(,4750) @node Writing a Node
4736texinfo.texi(,4751) @subsection How to Write an @code{@@node} Line
4737texinfo.texi(,4752) @cindex Writing an @code{@@node} line
4738texinfo.texi(,4753) @cindex @code{@@node} line writing
4739texinfo.texi(,4754) @cindex Node line writing
4740texinfo.texi(,4755)
4741texinfo.texi(,4756) The easiest way to write an @code{@@node} line is to write @code{@@node}
4742texinfo.texi(,4757) at the beginning of a line and then the name of the node, like
4743texinfo.texi(,4758) this:@refill
4744texinfo.texi(,4759)
4745texinfo.texi(,4760) @example
4746texinfo.texi(,4761) @@node @var{node-name}
4747texinfo.texi(,4762) @end example
4748texinfo.texi(,4763)
4749texinfo.texi(,4764) If you are using GNU Emacs, you can use the update node commands
4750texinfo.texi(,4765) provided by Texinfo mode to insert the names of the pointers; or you
4751texinfo.texi(,4766) can leave the pointers out of the Texinfo file and let @code{makeinfo}
4752texinfo.texi(,4767) insert node pointers into the Info file it creates.  (@xref{Texinfo
4753texinfo.texi(,4768) Mode}, and @ref{makeinfo Pointer Creation}.)@refill
4754texinfo.texi(,4769)
4755texinfo.texi(,4770) Alternatively, you can insert the `Next', `Previous', and `Up'
4756texinfo.texi(,4771) pointers yourself.  If you do this, you may find it helpful to use the
4757texinfo.texi(,4772) Texinfo mode keyboard command @kbd{C-c C-c n}.  This command inserts
4758texinfo.texi(,4773) @samp{@@node} and a comment line listing the names of the pointers in
4759texinfo.texi(,4774) their proper order.  The comment line helps you keep track of which
4760texinfo.texi(,4775) arguments are for which pointers.  This comment line is especially useful
4761texinfo.texi(,4776) if you are not familiar with Texinfo.@refill
4762texinfo.texi(,4777)
4763texinfo.texi(,4778) The template for a fully-written-out node line with `Next', `Previous',
4764texinfo.texi(,4779) and `Up' pointers looks like this:@refill
4765texinfo.texi(,4780)
4766texinfo.texi(,4781) @example
4767texinfo.texi(,4782) @@node @var{node-name}, @var{next}, @var{previous}, @var{up}
4768texinfo.texi(,4783) @end example
4769texinfo.texi(,4784)
4770texinfo.texi(,4785) If you wish, you can ignore @code{@@node} lines altogether in your first
4771texinfo.texi(,4786) draft and then use the @code{texinfo-insert-node-lines} command to
4772texinfo.texi(,4787) create @code{@@node} lines for you.  However, we do not recommend this
4773texinfo.texi(,4788) practice.  It is better to name the node itself at the same time that
4774texinfo.texi(,4789) you write a segment so you can easily make cross references.  A large
4775texinfo.texi(,4790) number of cross references are an especially important feature of a good
4776texinfo.texi(,4791) Info file.
4777texinfo.texi(,4792)
4778texinfo.texi(,4793) After you have inserted an @code{@@node} line, you should immediately
4779texinfo.texi(,4794) write an @@-command for the chapter or section and insert its name.
4780texinfo.texi(,4795) Next (and this is important!), put in several index entries.  Usually,
4781texinfo.texi(,4796) you will find at least two and often as many as four or five ways of
4782texinfo.texi(,4797) referring to the node in the index.  Use them all.  This will make it
4783texinfo.texi(,4798) much easier for people to find the node.
4784texinfo.texi(,4799)
4785texinfo.texi(,4800)
4786texinfo.texi(,4801) @node Node Line Tips
4787texinfo.texi(,4802) @subsection @code{@@node} Line Tips
4788texinfo.texi(,4803)
4789texinfo.texi(,4804) Here are three suggestions:
4790texinfo.texi(,4805)
4791texinfo.texi(,4806) @itemize @bullet
4792texinfo.texi(,4807) @item
4793texinfo.texi(,4808) Try to pick node names that are informative but short.@refill
4794texinfo.texi(,4809)
4795texinfo.texi(,4810) In the Info file, the file name, node name, and pointer names are all
4796texinfo.texi(,4811) inserted on one line, which may run into the right edge of the window.
4797texinfo.texi(,4812) (This does not cause a problem with Info, but is ugly.)@refill
4798texinfo.texi(,4813)
4799texinfo.texi(,4814) @item
4800texinfo.texi(,4815) Try to pick node names that differ from each other near the beginnings
4801texinfo.texi(,4816) of their names.  This way, it is easy to use automatic name completion in
4802texinfo.texi(,4817) Info.@refill
4803texinfo.texi(,4818)
4804texinfo.texi(,4819) @item
4805texinfo.texi(,4820) By convention, node names are capitalized just as they would be for
4806texinfo.texi(,4821) section or chapter titles---initial and significant words are
4807texinfo.texi(,4822) capitalized; others are not.@refill
4808texinfo.texi(,4823) @end itemize
4809texinfo.texi(,4824)
4810texinfo.texi(,4825)
4811texinfo.texi(,4826) @node Node Line Requirements, First Node, Node Line Tips, node
4812texinfo.texi(,4827) @subsection @code{@@node} Line Requirements
4813texinfo.texi(,4828)
4814texinfo.texi(,4829) @cindex Node line requirements
4815texinfo.texi(,4830) @cindex Restrictions on node names
4816texinfo.texi(,4831) Here are several requirements for @code{@@node} lines:
4817texinfo.texi(,4832)
4818texinfo.texi(,4833) @itemize @bullet
4819texinfo.texi(,4834) @cindex Unique nodename requirement
4820texinfo.texi(,4835) @cindex Node name must be unique
4821texinfo.texi(,4836) @item
4822texinfo.texi(,4837) All the node names for a single Info file must be unique.@refill
4823texinfo.texi(,4838)
4824texinfo.texi(,4839) Duplicates confuse the Info movement commands.  This means, for
4825texinfo.texi(,4840) example, that if you end every chapter with a summary, you must name
4826texinfo.texi(,4841) each summary node differently.  You cannot just call each one
4827texinfo.texi(,4842) ``Summary''.  You may, however, duplicate the titles of chapters, sections,
4828texinfo.texi(,4843) and the like.  Thus you can end each chapter in a book with a section
4829texinfo.texi(,4844) called ``Summary'', so long as the node names for those sections are all
4830texinfo.texi(,4845) different.@refill
4831texinfo.texi(,4846)
4832texinfo.texi(,4847) @item
4833texinfo.texi(,4848) A pointer name must be the name of a node.@refill
4834texinfo.texi(,4849)
4835texinfo.texi(,4850) The node to which a pointer points may come before or after the
4836texinfo.texi(,4851) node containing the pointer.
4837texinfo.texi(,4852)
4838texinfo.texi(,4853) @cindex @@-commands in nodename
4839texinfo.texi(,4854) @cindex Node name, should not contain @@-commands
4840texinfo.texi(,4855) @item
4841texinfo.texi(,4856) @w{@@-commands} used in node names generally confuse Info, so you
4842texinfo.texi(,4857) should avoid them.  This includes punctuation characters that are
4843texinfo.texi(,4858) escaped with a @samp{@@}, such as @code{@@} and @code{@{}.  For a few
4844texinfo.texi(,4859) rare cases when this is useful, Texinfo has limited support for using
4845texinfo.texi(,4860) @w{@@-commands} in node names; see @ref{Pointer Validation}.
4846texinfo.texi(,4861)
4847texinfo.texi(,4862) @need 750
4848texinfo.texi(,4863) Thus, the beginning of the section called @code{@@chapter} looks like
4849texinfo.texi(,4864) this:@refill
4850texinfo.texi(,4865)
4851texinfo.texi(,4866) @smallexample
4852texinfo.texi(,4867) @group
4853texinfo.texi(,4868) @@node  chapter, unnumbered & appendix, makeinfo top, Structuring
4854texinfo.texi(,4869) @@comment  node-name,  next,  previous,  up
4855texinfo.texi(,4870) @@section @@code@{@@@@chapter@}
4856texinfo.texi(,4871) @@findex chapter
4857texinfo.texi(,4872) @end group
4858texinfo.texi(,4873) @end smallexample
4859texinfo.texi(,4874)
4860texinfo.texi(,4875) @item
4861texinfo.texi(,4876) @cindex Parentheses in nodename
4862texinfo.texi(,4877) You cannot use parentheses in node names, because a node name such as
4863texinfo.texi(,4878) @samp{(foo)bar} is interpreted by the Info readers as a node
4864texinfo.texi(,4879) @samp{bar} in an Info file @file{foo}.
4865texinfo.texi(,4880)
4866texinfo.texi(,4881) @item
4867texinfo.texi(,4882) @cindex Apostrophe in nodename
4868texinfo.texi(,4883) @cindex Colon in nodename
4869texinfo.texi(,4884) @cindex Comma in nodename
4870texinfo.texi(,4885) @cindex Period in nodename
4871texinfo.texi(,4886) @cindex Characters, invalid in node name
4872texinfo.texi(,4887) @cindex Invalid characters in node names
4873texinfo.texi(,4888) Unfortunately, you cannot use periods, commas, colons or apostrophes
4874texinfo.texi(,4889) within a node name; these confuse @TeX{} or the Info formatters.
4875texinfo.texi(,4890)
4876texinfo.texi(,4891) @need 700
4877texinfo.texi(,4892) For example, the following is a section title:
4878texinfo.texi(,4893)
4879texinfo.texi(,4894) @smallexample
4880texinfo.texi(,4895) @@code@{@@@@unnumberedsec@}, @@code@{@@@@appendixsec@}, @@code@{@@@@heading@}
4881texinfo.texi(,4896) @end smallexample
4882texinfo.texi(,4897)
4883texinfo.texi(,4898) @noindent
4884texinfo.texi(,4899) The corresponding node name is:
4885texinfo.texi(,4900)
4886texinfo.texi(,4901) @smallexample
4887texinfo.texi(,4902) unnumberedsec appendixsec heading
4888texinfo.texi(,4903) @end smallexample
4889texinfo.texi(,4904)
4890texinfo.texi(,4905) @cindex Case in node name
4891texinfo.texi(,4906) @item
4892texinfo.texi(,4907) Case is significant.
4893texinfo.texi(,4908) @end itemize
4894texinfo.texi(,4909)
4895texinfo.texi(,4910)
4896texinfo.texi(,4911) @node First Node
4897texinfo.texi(,4912) @subsection The First Node
4898texinfo.texi(,4913) @cindex Top node is first
4899texinfo.texi(,4914) @cindex First node
4900texinfo.texi(,4915)
4901texinfo.texi(,4916) The first node of a Texinfo file is the @dfn{Top} node, except in an
4902texinfo.texi(,4917) included file (@pxref{Include Files}).  The Top node should contain a
4903texinfo.texi(,4918) short summary, copying permissions, and a master menu.  @xref{The Top
4904texinfo.texi(,4919) Node}, for more information on the Top node contents and examples.
4905texinfo.texi(,4920)
4906texinfo.texi(,4921) Here is a description of the node pointers to be used in the Top node:
4907texinfo.texi(,4922)
4908texinfo.texi(,4923) @itemize @bullet
4909texinfo.texi(,4924)
4910texinfo.texi(,4925) @item
4911texinfo.texi(,4926) @cindex Up node of Top node
4912texinfo.texi(,4927) @cindex (dir) as Up node of Top node
4913texinfo.texi(,4928) The Top node (which must be named @samp{top} or @samp{Top}) should have
4914texinfo.texi(,4929) as its `Up' node the name of a node in another file, where there is a
4915texinfo.texi(,4930) menu that leads to this file.  Specify the file name in parentheses.
4916texinfo.texi(,4931)
4917texinfo.texi(,4932) Usually, all Info files are installed in the same Info directory tree;
4918texinfo.texi(,4933) in this case, use @samp{(dir)} as the parent of the Top node; this is
4919texinfo.texi(,4934) short for @samp{(dir)top}, and specifies the Top node in the @file{dir}
4920texinfo.texi(,4935) file, which contains the main menu for the Info system as a whole.
4921texinfo.texi(,4936)
4922texinfo.texi(,4937) @item
4923texinfo.texi(,4938) @cindex Previous node of Top node
4924texinfo.texi(,4939) On the other hand, do not define the `Previous' node of the Top node to
4925texinfo.texi(,4940) be @samp{(dir)}, as it causes confusing behavior for users: if you are
4926texinfo.texi(,4941) in the Top node and hits @key{DEL} to go backwards, you wind up in the
4927texinfo.texi(,4942) middle of the some other entry in the @file{dir} file, which has nothing
4928texinfo.texi(,4943) to do with what you were reading.
4929texinfo.texi(,4944)
4930texinfo.texi(,4945) @item
4931texinfo.texi(,4946) @cindex Next node of Top node
4932texinfo.texi(,4947) The `Next' node of the Top node should be the first chapter in your
4933texinfo.texi(,4948) document.
4934texinfo.texi(,4949)
4935texinfo.texi(,4950) @end itemize
4936texinfo.texi(,4951)
4937texinfo.texi(,4952) @xref{Installing an Info File}, for more information about installing
4938texinfo.texi(,4953) an Info file in the @file{info} directory.
4939texinfo.texi(,4954)
4940texinfo.texi(,4955) For concreteness, here is an example with explicit pointers (which you
4941texinfo.texi(,4956) can maintain automatically with the texinfo mode commands):
4942texinfo.texi(,4957)
4943texinfo.texi(,4958) Or you can leave the pointers off entirely and let the tools implicitly
4944texinfo.texi(,4959) define them.  This is recommended.  Thus:
4945texinfo.texi(,4960)
4946texinfo.texi(,4961) @example
4947texinfo.texi(,4962) @@node Top
4948texinfo.texi(,4963) @end example
4949texinfo.texi(,4964)
4950texinfo.texi(,4965)
4951texinfo.texi(,4966) @node makeinfo top command
4952texinfo.texi(,4967) @subsection The @code{@@top} Sectioning Command
4953texinfo.texi(,4968) @findex top @r{(@@-command)}
4954texinfo.texi(,4969)
4955texinfo.texi(,4970) A special sectioning command, @code{@@top} should be used with the
4956texinfo.texi(,4971) @code{@@node Top} line.  The @code{@@top} sectioning command tells
4957texinfo.texi(,4972) @code{makeinfo} that it marks the `Top' node in the file.  It provides
4958texinfo.texi(,4973) the information that @code{makeinfo} needs to insert node pointers
4959texinfo.texi(,4974) automatically.  Write the @code{@@top} command at the beginning of the
4960texinfo.texi(,4975) line immediately following the @code{@@node Top} line.  Write the title
4961texinfo.texi(,4976) on the remaining part of the same line as the @code{@@top} command.
4962texinfo.texi(,4977)
4963texinfo.texi(,4978) In Info, the @code{@@top} sectioning command causes the title to appear
4964texinfo.texi(,4979) on a line by itself, with a line of asterisks inserted underneath, as
4965texinfo.texi(,4980) other sectioning commands do.
4966texinfo.texi(,4981)
4967texinfo.texi(,4982) In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
4968texinfo.texi(,4983) sectioning command is merely a synonym for @code{@@unnumbered}.
4969texinfo.texi(,4984) Neither of these formatters require an @code{@@top} command, and do
4970texinfo.texi(,4985) nothing special with it.  You can use @code{@@chapter} or
4971texinfo.texi(,4986) @code{@@unnumbered} after the @code{@@node Top} line when you use
4972texinfo.texi(,4987) these formatters.  Also, you can use @code{@@chapter} or
4973texinfo.texi(,4988) @code{@@unnumbered} when you use the Texinfo updating commands to
4974texinfo.texi(,4989) create or update pointers and menus.
4975texinfo.texi(,4990)
4976texinfo.texi(,4991) Thus, in practice, a Top node starts like this:
4977texinfo.texi(,4992)
4978texinfo.texi(,4993) @example
4979texinfo.texi(,4994) @@node Top
4980texinfo.texi(,4995) @@top Your Manual Title
4981texinfo.texi(,4996) @end example
4982texinfo.texi(,4997)
4983texinfo.texi(,4998)
4984texinfo.texi(,4999) @node makeinfo Pointer Creation
4985texinfo.texi(,5000) @section Creating Pointers with @code{makeinfo}
4986texinfo.texi(,5001) @cindex Creating pointers with @code{makeinfo}
4987texinfo.texi(,5002) @cindex Pointer creation with @code{makeinfo}
4988texinfo.texi(,5003) @cindex Automatic pointer creation with @code{makeinfo}
4989texinfo.texi(,5004)
4990texinfo.texi(,5005) The @code{makeinfo} program has a feature for automatically defining
4991texinfo.texi(,5006) node pointers for a hierarchically organized file.
4992texinfo.texi(,5007)
4993texinfo.texi(,5008) When you take advantage of this feature, you do not need to write the
4994texinfo.texi(,5009) `Next', `Previous', and `Up' pointers after the name of a node.
4995texinfo.texi(,5010) However, you must write a sectioning command, such as @code{@@chapter}
4996texinfo.texi(,5011) or @code{@@section}, on the line immediately following each truncated
4997texinfo.texi(,5012) @code{@@node} line (except that comment lines may intervene).
4998texinfo.texi(,5013)
4999texinfo.texi(,5014) In addition, you must follow the `Top' @code{@@node} line with a line
5000texinfo.texi(,5015) beginning with @code{@@top} to mark the `Top' node in the
5001texinfo.texi(,5016) file.  @xref{makeinfo top, , @code{@@top}}.
5002texinfo.texi(,5017)
5003texinfo.texi(,5018) Finally, you must write the name of each node (except for the `Top'
5004texinfo.texi(,5019) node) in a menu that is one or more hierarchical levels above the
5005texinfo.texi(,5020) node's hierarchical level.
5006texinfo.texi(,5021)
5007texinfo.texi(,5022) This node pointer insertion feature in @code{makeinfo} relieves you from
5008texinfo.texi(,5023) the need to update menus and pointers manually or with Texinfo mode
5009texinfo.texi(,5024) commands.  (@xref{Updating Nodes and Menus}.)
5010texinfo.texi(,5025)
5011texinfo.texi(,5026) In most cases, you will want to take advantage of this feature and not
5012texinfo.texi(,5027) redundantly specify node pointers.  However, Texinfo documents are not
5013texinfo.texi(,5028) required to be organized hierarchically or in fact contain sectioning
5014texinfo.texi(,5029) commands at all.  For example, if you never intend the document to be
5015texinfo.texi(,5030) printed.  In those cases, you will need to explicitly specify the pointers.
5016texinfo.texi(,5031)
5017texinfo.texi(,5032)
5018texinfo.texi(,5033) @node anchor
5019texinfo.texi(,5034) @section @code{@@anchor}: Defining Arbitrary Cross-reference Targets
5020texinfo.texi(,5035)
5021texinfo.texi(,5036) @findex anchor
5022texinfo.texi(,5037) @cindex Anchors
5023texinfo.texi(,5038) @cindex Cross-reference targets, arbitrary
5024texinfo.texi(,5039) @cindex Targets for cross-references, arbitrary
5025texinfo.texi(,5040)
5026texinfo.texi(,5041) An @dfn{anchor} is a position in your document, labeled so that
5027texinfo.texi(,5042) cross-references can refer to it, just as they can to nodes.  You create
5028texinfo.texi(,5043) an anchor with the @code{@@anchor} command, and give the label as a
5029texinfo.texi(,5044) normal brace-delimited argument.  For example:
5030texinfo.texi(,5045)
5031texinfo.texi(,5046) @example
5032texinfo.texi(,5047) This marks the @@anchor@{x-spot@}spot.
5033texinfo.texi(,5048) @dots{}
5034texinfo.texi(,5049) @@xref@{x-spot,,the spot@}.
5035texinfo.texi(,5050) @end example
5036texinfo.texi(,5051)
5037texinfo.texi(,5052) @noindent produces:
5038texinfo.texi(,5053)
5039texinfo.texi(,5054) @example
5040texinfo.texi(,5055) This marks the spot.
5041texinfo.texi(,5056) @dots{}
5042texinfo.texi(,5057) See [the spot], page 1.
5043texinfo.texi(,5058) @end example
5044texinfo.texi(,5059)
5045texinfo.texi(,5060) As you can see, the @code{@@anchor} command itself produces no output.
5046texinfo.texi(,5061) This example defines an anchor `x-spot' just before the word `spot'.
5047texinfo.texi(,5062) You can refer to it later with an @code{@@xref} or other cross-reference
5048texinfo.texi(,5063) command, as shown.  @xref{Cross References}, for details on the
5049texinfo.texi(,5064) cross-reference commands.
5050texinfo.texi(,5065)
5051texinfo.texi(,5066) It is best to put @code{@@anchor} commands just before the position you
5052texinfo.texi(,5067) wish to refer to; that way, the reader's eye is led on to the correct
5053texinfo.texi(,5068) text when they jump to the anchor.  You can put the @code{@@anchor}
5054texinfo.texi(,5069) command on a line by itself if that helps readability of the source.
5055texinfo.texi(,5070) Spaces are always ignored after @code{@@anchor}.
5056texinfo.texi(,5071)
5057texinfo.texi(,5072) Anchor names and node names may not conflict.  Anchors and nodes are
5058texinfo.texi(,5073) given similar treatment in some ways; for example, the @code{goto-node}
5059texinfo.texi(,5074) command in standalone Info takes either an anchor name or a node name as
5060texinfo.texi(,5075) an argument.  (@xref{goto-node,,,info-stnd,GNU Info}.)
5061texinfo.texi(,5076)
5062texinfo.texi(,5077)
5063texinfo.texi(,5078) @node Menus
5064texinfo.texi(,5079) @chapter Menus
5065texinfo.texi(,5080) @cindex Menus
5066texinfo.texi(,5081) @findex menu
5067texinfo.texi(,5082)
5068texinfo.texi(,5083) @dfn{Menus} contain pointers to subordinate nodes.@footnote{Menus can
5069texinfo.texi(,5084) carry you to any node, regardless of the hierarchical structure; even to
5070texinfo.texi(,5085) nodes in a different Info file.  However, the GNU Emacs Texinfo mode
5071texinfo.texi(,5086) updating commands work only to create menus of subordinate nodes.
5072texinfo.texi(,5087) Conventionally, cross references are used to refer to other nodes.} In
5073texinfo.texi(,5088) Info, you use menus to go to such nodes.  Menus have no effect in
5074texinfo.texi(,5089) printed manuals and do not appear in them.
5075texinfo.texi(,5090)
5076texinfo.texi(,5091) By convention, a menu is put at the end of a node since a reader who
5077texinfo.texi(,5092) uses the menu may not see text that follows it.  Furthermore, a node
5078texinfo.texi(,5093) that has a menu should not contain much text. If you have a lot of text
5079texinfo.texi(,5094) and a menu, move most of the text into a new subnode---all but a few
5080texinfo.texi(,5095) lines.  Otherwise, a reader with a terminal that displays only a few
5081texinfo.texi(,5096) lines may miss the menu and its associated text.  As a practical matter,
5082texinfo.texi(,5097) you should locate a menu within 20 lines of the beginning of the
5083texinfo.texi(,5098) node.
5084texinfo.texi(,5099)
5085texinfo.texi(,5100) @menu
5086texinfo.texi(,5101) * Menu Location::               Put a menu in a short node.
5087texinfo.texi(,5102) * Writing a Menu::              What is a menu?
5088texinfo.texi(,5103) * Menu Parts::                  A menu entry has three parts.
5089texinfo.texi(,5104) * Less Cluttered Menu Entry::   Two part menu entry.
5090texinfo.texi(,5105) * Menu Example::                Two and three part menu entries.
5091texinfo.texi(,5106) * Other Info Files::            How to refer to a different Info file.
5092texinfo.texi(,5107) @end menu
5093texinfo.texi(,5108)
5094texinfo.texi(,5109)
5095texinfo.texi(,5110) @node Menu Location, Writing a Menu, Menus, Menus
5096texinfo.texi(,5112) @heading Menus Need Short Nodes
5097texinfo.texi(,5114) @cindex Menu location
5098texinfo.texi(,5115) @cindex Location of menus
5099texinfo.texi(,5116) @cindex Nodes for menus are short
5100texinfo.texi(,5117) @cindex Short nodes for menus
5101texinfo.texi(,5118)
5102texinfo.texi(,5119) The short text before a menu may look awkward in a printed manual.  To
5103texinfo.texi(,5120) avoid this, you can write a menu near the beginning of its node and
5104texinfo.texi(,5121) follow the menu by an @code{@@node} line, and then an @code{@@heading}
5105texinfo.texi(,5122) line located within @code{@@ifinfo} and @code{@@end ifinfo}.  This way,
5106texinfo.texi(,5123) the menu, @code{@@node} line, and title appear only in the Info file,
5107texinfo.texi(,5124) not the printed document.
5108texinfo.texi(,5125)
5109texinfo.texi(,5126) For example, the preceding two paragraphs follow an Info-only menu,
5110texinfo.texi(,5127) @code{@@node} line, and heading, and look like this:
5111texinfo.texi(,5128)
5112texinfo.texi(,5129) @example
5113texinfo.texi(,5130) @group
5114texinfo.texi(,5131) @@menu
5115texinfo.texi(,5132) * Menu Location::             Put a menu in a short node.
5116texinfo.texi(,5133) * Writing a Menu::            What is a menu?
5117texinfo.texi(,5134) * Menu Parts::                A menu entry has three parts.
5118texinfo.texi(,5135) * Less Cluttered Menu Entry:: Two part menu entry.
5119texinfo.texi(,5136) * Menu Example::              Two and three part entries.
5120texinfo.texi(,5137) * Other Info Files::          How to refer to a different
5121texinfo.texi(,5138)                                 Info file.
5122texinfo.texi(,5139) @@end menu
5123texinfo.texi(,5140)
5124texinfo.texi(,5141) @@node Menu Location, Writing a Menu, , Menus
5125texinfo.texi(,5142) @@ifinfo
5126texinfo.texi(,5143) @@heading Menus Need Short Nodes
5127texinfo.texi(,5144) @@end ifinfo
5128texinfo.texi(,5145) @end group
5129texinfo.texi(,5146) @end example
5130texinfo.texi(,5147)
5131texinfo.texi(,5148) The Texinfo file for this document contains a number of
5132texinfo.texi(,5149) examples of this procedure; one is at the beginning of this chapter.
5133texinfo.texi(,5150)
5134texinfo.texi(,5151)
5135texinfo.texi(,5152) @node Writing a Menu, Menu Parts, Menu Location, Menus
5136texinfo.texi(,5153) @section Writing a Menu
5137texinfo.texi(,5154) @cindex Writing a menu
5138texinfo.texi(,5155) @cindex Menu writing
5139texinfo.texi(,5156)
5140texinfo.texi(,5157) A menu consists of an @code{@@menu} command on a line by
5141texinfo.texi(,5158) itself followed by menu entry lines or menu comment lines
5142texinfo.texi(,5159) and then by an @code{@@end menu} command on a line by
5143texinfo.texi(,5160) itself.@refill
5144texinfo.texi(,5161)
5145texinfo.texi(,5162) A menu looks like this:@refill
5146texinfo.texi(,5163)
5147texinfo.texi(,5164) @example
5148texinfo.texi(,5165) @group
5149texinfo.texi(,5166) @@menu
5150texinfo.texi(,5167) Larger Units of Text
5151texinfo.texi(,5168)
5152texinfo.texi(,5169) * Files::                       All about handling files.
5153texinfo.texi(,5170) * Multiples: Buffers.           Multiple buffers; editing
5154texinfo.texi(,5171)                                   several files at once.
5155texinfo.texi(,5172) @@end menu
5156texinfo.texi(,5173) @end group
5157texinfo.texi(,5174) @end example
5158texinfo.texi(,5175)
5159texinfo.texi(,5176) In a menu, every line that begins with an @w{@samp{* }} is a @dfn{menu
5160texinfo.texi(,5177) entry}.  (Note the space after the asterisk.)  A line that does not
5161texinfo.texi(,5178) start with an @w{@samp{* }} may also appear in a menu.  Such a line is
5162texinfo.texi(,5179) not a menu entry but is a menu comment line that appears in the Info
5163texinfo.texi(,5180) file.  In the example above, the line @samp{Larger Units of Text} is a
5164texinfo.texi(,5181) menu comment line; the two lines starting with @w{@samp{* }} are menu
5165texinfo.texi(,5182) @cindex Spaces, in menus
5166texinfo.texi(,5183) entries.  Space characters in a menu are preserved as-is; this allows
5167texinfo.texi(,5184) you to format the menu as you wish.
5168texinfo.texi(,5185)
5169texinfo.texi(,5186)
5170texinfo.texi(,5187) @node Menu Parts, Less Cluttered Menu Entry, Writing a Menu, Menus
5171texinfo.texi(,5188) @section The Parts of a Menu
5172texinfo.texi(,5189) @cindex Parts of a menu
5173texinfo.texi(,5190) @cindex Menu parts
5174texinfo.texi(,5191) @cindex @code{@@menu} parts
5175texinfo.texi(,5192)
5176texinfo.texi(,5193) A menu entry has three parts, only the second of which is required:
5177texinfo.texi(,5194)
5178texinfo.texi(,5195) @enumerate
5179texinfo.texi(,5196) @item
5180texinfo.texi(,5197) The menu entry name (optional).
5181texinfo.texi(,5198)
5182texinfo.texi(,5199) @item
5183texinfo.texi(,5200) The name of the node (required).
5184texinfo.texi(,5201)
5185texinfo.texi(,5202) @item
5186texinfo.texi(,5203) A description of the item (optional).
5187texinfo.texi(,5204) @end enumerate
5188texinfo.texi(,5205)
5189texinfo.texi(,5206) The template for a menu entry looks like this:@refill
5190texinfo.texi(,5207)
5191texinfo.texi(,5208) @example
5192texinfo.texi(,5209) * @var{menu-entry-name}: @var{node-name}.   @var{description}
5193texinfo.texi(,5210) @end example
5194texinfo.texi(,5211)
5195texinfo.texi(,5212) Follow the menu entry name with a single colon and follow the node name
5196texinfo.texi(,5213) with tab, comma, period, or newline.@refill
5197texinfo.texi(,5214)
5198texinfo.texi(,5215) In Info, a user selects a node with the @kbd{m} (@code{Info-menu})
5199texinfo.texi(,5216) command.  The menu entry name is what the user types after the @kbd{m}
5200texinfo.texi(,5217) command.@refill
5201texinfo.texi(,5218)
5202texinfo.texi(,5219) The third part of a menu entry is a descriptive phrase or sentence.
5203texinfo.texi(,5220) Menu entry names and node names are often short; the description
5204texinfo.texi(,5221) explains to the reader what the node is about.  A useful description
5205texinfo.texi(,5222) complements the node name rather than repeats it.  The description,
5206texinfo.texi(,5223) which is optional, can spread over two or more lines; if it does, some
5207texinfo.texi(,5224) authors prefer to indent the second line while others prefer to align it
5208texinfo.texi(,5225) with the first (and all others).  It's up to you.
5209texinfo.texi(,5226)
5210texinfo.texi(,5227)
5211texinfo.texi(,5228) @node Less Cluttered Menu Entry, Menu Example, Menu Parts, Menus
5212texinfo.texi(,5229) @comment  node-name,  next,  previous,  up
5213texinfo.texi(,5230) @section Less Cluttered Menu Entry
5214texinfo.texi(,5231) @cindex Two part menu entry
5215texinfo.texi(,5232) @cindex Double-colon menu entries
5216texinfo.texi(,5233) @cindex Menu entries with two colons
5217texinfo.texi(,5234) @cindex Less cluttered menu entry
5218texinfo.texi(,5235) @cindex Uncluttered menu entry
5219texinfo.texi(,5236)
5220texinfo.texi(,5237) When the menu entry name and node name are the same, you can write
5221texinfo.texi(,5238) the name immediately after the asterisk and space at the beginning of
5222texinfo.texi(,5239) the line and follow the name with two colons.@refill
5223texinfo.texi(,5240)
5224texinfo.texi(,5241) @need 800
5225texinfo.texi(,5242) For example, write
5226texinfo.texi(,5243)
5227texinfo.texi(,5244) @example
5228texinfo.texi(,5245) * Name::                                    @var{description}
5229texinfo.texi(,5246) @end example
5230texinfo.texi(,5247)
5231texinfo.texi(,5248) @need 800
5232texinfo.texi(,5249) @noindent
5233texinfo.texi(,5250) instead of
5234texinfo.texi(,5251)
5235texinfo.texi(,5252) @example
5236texinfo.texi(,5253) * Name: Name.                               @var{description}
5237texinfo.texi(,5254) @end example
5238texinfo.texi(,5255)
5239texinfo.texi(,5256) You should use the node name for the menu entry name whenever possible,
5240texinfo.texi(,5257) since it reduces visual clutter in the menu.@refill
5241texinfo.texi(,5258)
5242texinfo.texi(,5259) @node Menu Example, Other Info Files, Less Cluttered Menu Entry, Menus
5243texinfo.texi(,5260) @comment  node-name,  next,  previous,  up
5244texinfo.texi(,5261) @section A Menu Example
5245texinfo.texi(,5262) @cindex Menu example
5246texinfo.texi(,5263) @cindex Example menu
5247texinfo.texi(,5264)
5248texinfo.texi(,5265) A menu looks like this in Texinfo:@refill
5249texinfo.texi(,5266)
5250texinfo.texi(,5267) @example
5251texinfo.texi(,5268) @group
5252texinfo.texi(,5269) @@menu
5253texinfo.texi(,5270) * menu entry name: Node name.   A short description.
5254texinfo.texi(,5271) * Node name::                   This form is preferred.
5255texinfo.texi(,5272) @@end menu
5256texinfo.texi(,5273) @end group
5257texinfo.texi(,5274) @end example
5258texinfo.texi(,5275)
5259texinfo.texi(,5276) @need 800
5260texinfo.texi(,5277) @noindent
5261texinfo.texi(,5278) This produces:
5262texinfo.texi(,5279)
5263texinfo.texi(,5280) @example
5264texinfo.texi(,5281) @group
5265texinfo.texi(,5282) * menu:
5266texinfo.texi(,5283)
5267texinfo.texi(,5284) * menu entry name: Node name.   A short description.
5268texinfo.texi(,5285) * Node name::                   This form is preferred.
5269texinfo.texi(,5286) @end group
5270texinfo.texi(,5287) @end example
5271texinfo.texi(,5288)
5272texinfo.texi(,5289) @need 700
5273texinfo.texi(,5290) Here is an example as you might see it in a Texinfo file:@refill
5274texinfo.texi(,5291)
5275texinfo.texi(,5292) @example
5276texinfo.texi(,5293) @group
5277texinfo.texi(,5294) @@menu
5278texinfo.texi(,5295) Larger Units of Text
5279texinfo.texi(,5296)
5280texinfo.texi(,5297) * Files::                       All about handling files.
5281texinfo.texi(,5298) * Multiples: Buffers.           Multiple buffers; editing
5282texinfo.texi(,5299)                                   several files at once.
5283texinfo.texi(,5300) @@end menu
5284texinfo.texi(,5301) @end group
5285texinfo.texi(,5302) @end example
5286texinfo.texi(,5303)
5287texinfo.texi(,5304) @need 800
5288texinfo.texi(,5305) @noindent
5289texinfo.texi(,5306) This produces:
5290texinfo.texi(,5307)
5291texinfo.texi(,5308) @example
5292texinfo.texi(,5309) @group
5293texinfo.texi(,5310) * menu:
5294texinfo.texi(,5311) Larger Units of Text
5295texinfo.texi(,5312)
5296texinfo.texi(,5313) * Files::                       All about handling files.
5297texinfo.texi(,5314) * Multiples: Buffers.           Multiple buffers; editing
5298texinfo.texi(,5315)                                   several files at once.
5299texinfo.texi(,5316) @end group
5300texinfo.texi(,5317) @end example
5301texinfo.texi(,5318)
5302texinfo.texi(,5319) In this example, the menu has two entries.  @samp{Files} is both a menu
5303texinfo.texi(,5320) entry name and the name of the node referred to by that name.
5304texinfo.texi(,5321) @samp{Multiples} is the menu entry name; it refers to the node named
5305texinfo.texi(,5322) @samp{Buffers}. The line @samp{Larger Units of Text} is a comment; it
5306texinfo.texi(,5323) appears in the menu, but is not an entry.@refill
5307texinfo.texi(,5324)
5308texinfo.texi(,5325) Since no file name is specified with either @samp{Files} or
5309texinfo.texi(,5326) @samp{Buffers}, they must be the names of nodes in the same Info file
5310texinfo.texi(,5327) (@pxref{Other Info Files, , Referring to Other Info Files}).@refill
5311texinfo.texi(,5328)
5312texinfo.texi(,5329) @node Other Info Files,  , Menu Example, Menus
5313texinfo.texi(,5330) @comment  node-name,  next,  previous,  up
5314texinfo.texi(,5331) @section Referring to Other Info Files
5315texinfo.texi(,5332) @cindex Referring to other Info files
5316texinfo.texi(,5333) @cindex Nodes in other Info files
5317texinfo.texi(,5334) @cindex Other Info files' nodes
5318texinfo.texi(,5335) @cindex Going to other Info files' nodes
5319texinfo.texi(,5336) @cindex Info; other files' nodes
5320texinfo.texi(,5337)
5321texinfo.texi(,5338) You can create a menu entry that enables a reader in Info to go to a
5322texinfo.texi(,5339) node in another Info file by writing the file name in parentheses just
5323texinfo.texi(,5340) before the node name.  In this case, you should use the three-part menu
5324texinfo.texi(,5341) entry format, which saves the reader from having to type the file
5325texinfo.texi(,5342) name.@refill
5326texinfo.texi(,5343)
5327texinfo.texi(,5344) @need 800
5328texinfo.texi(,5345) The format looks like this:@refill
5329texinfo.texi(,5346)
5330texinfo.texi(,5347) @example
5331texinfo.texi(,5348) @group
5332texinfo.texi(,5349) @@menu
5333texinfo.texi(,5350) * @var{first-entry-name}:(@var{filename})@var{nodename}.     @var{description}
5334texinfo.texi(,5351) * @var{second-entry-name}:(@var{filename})@var{second-node}. @var{description}
5335texinfo.texi(,5352) @@end menu
5336texinfo.texi(,5353) @end group
5337texinfo.texi(,5354) @end example
5338texinfo.texi(,5355)
5339texinfo.texi(,5356) For example, to refer directly to the @samp{Outlining} and
5340texinfo.texi(,5357) @samp{Rebinding} nodes in the @cite{Emacs Manual}, you would write a
5341texinfo.texi(,5358) menu like this:@refill
5342texinfo.texi(,5359)
5343texinfo.texi(,5360) @example
5344texinfo.texi(,5361) @group
5345texinfo.texi(,5362) @@menu
5346texinfo.texi(,5363) * Outlining: (emacs)Outline Mode. The major mode for
5347texinfo.texi(,5364)                                   editing outlines.
5348texinfo.texi(,5365) * Rebinding: (emacs)Rebinding.    How to redefine the
5349texinfo.texi(,5366)                                   meaning of a key.
5350texinfo.texi(,5367) @@end menu
5351texinfo.texi(,5368) @end group
5352texinfo.texi(,5369) @end example
5353texinfo.texi(,5370)
5354texinfo.texi(,5371) If you do not list the node name, but only name the file, then Info
5355texinfo.texi(,5372) presumes that you are referring to the `Top' node.@refill
5356texinfo.texi(,5373)
5357texinfo.texi(,5374) The @file{dir} file that contains the main menu for Info has menu
5358texinfo.texi(,5375) entries that list only file names.  These take you directly to the `Top'
5359texinfo.texi(,5376) nodes of each Info document.  (@xref{Installing an Info File}.)
5360texinfo.texi(,5377)
5361texinfo.texi(,5378) @need 700
5362texinfo.texi(,5379) For example:
5363texinfo.texi(,5380)
5364texinfo.texi(,5381) @example
5365texinfo.texi(,5382) @group
5366texinfo.texi(,5383) * Info: (info).         Documentation browsing system.
5367texinfo.texi(,5384) * Emacs: (emacs).       The extensible, self-documenting
5368texinfo.texi(,5385)                         text editor.
5369texinfo.texi(,5386) @end group
5370texinfo.texi(,5387) @end example
5371texinfo.texi(,5388)
5372texinfo.texi(,5389) @noindent
5373texinfo.texi(,5390) (The @file{dir} top level directory for the Info system is an Info file,
5374texinfo.texi(,5391) not a Texinfo file, but a menu entry looks the same in both types of
5375texinfo.texi(,5392) file.)@refill
5376texinfo.texi(,5393)
5377texinfo.texi(,5394) The GNU Emacs Texinfo mode menu updating commands only work with nodes
5378texinfo.texi(,5395) within the current buffer, so you cannot use them to create menus that
5379texinfo.texi(,5396) refer to other files.  You must write such menus by hand.
5380texinfo.texi(,5397)
5381texinfo.texi(,5398)
5382texinfo.texi(,5399) @node Cross References
5383texinfo.texi(,5400) @chapter Cross References
5384texinfo.texi(,5401) @cindex Making cross references
5385texinfo.texi(,5402) @cindex Cross references
5386texinfo.texi(,5403) @cindex References
5387texinfo.texi(,5404)
5388texinfo.texi(,5405) @dfn{Cross references} are used to refer the reader to other parts of the
5389texinfo.texi(,5406) same or different Texinfo files.  In Texinfo, nodes and anchors are the
5390texinfo.texi(,5407) places to which cross references can refer.
5391texinfo.texi(,5408)
5392texinfo.texi(,5409) @menu
5393texinfo.texi(,5410) * References::                  What cross references are for.
5394texinfo.texi(,5411) * Cross Reference Commands::    A summary of the different commands.
5395texinfo.texi(,5412) * Cross Reference Parts::       A cross reference has several parts.
5396texinfo.texi(,5413) * xref::                        Begin a reference with `See' @dots{}
5397texinfo.texi(,5414) * Top Node Naming::             How to refer to the beginning of another file.
5398texinfo.texi(,5415) * ref::                         A reference for the last part of a sentence.
5399texinfo.texi(,5416) * pxref::                       How to write a parenthetical cross reference.
5400texinfo.texi(,5417) * inforef::                     How to refer to an Info-only file.
5401texinfo.texi(,5418) * uref::                        How to refer to a uniform resource locator.
5402texinfo.texi(,5419) @end menu
5403texinfo.texi(,5420)
5404texinfo.texi(,5421) @node References, Cross Reference Commands, Cross References, Cross References
5405texinfo.texi(,5423) @heading What References Are For
5406texinfo.texi(,5425)
5407texinfo.texi(,5426) Often, but not always, a printed document should be designed so that
5408texinfo.texi(,5427) it can be read sequentially.  People tire of flipping back and forth
5409texinfo.texi(,5428) to find information that should be presented to them as they need
5410texinfo.texi(,5429) it.@refill
5411texinfo.texi(,5430)
5412texinfo.texi(,5431) However, in any document, some information will be too detailed for
5413texinfo.texi(,5432) the current context, or incidental to it; use cross references to
5414texinfo.texi(,5433) provide access to such information.  Also, an online help system or a
5415texinfo.texi(,5434) reference manual is not like a novel; few read such documents in
5416texinfo.texi(,5435) sequence from beginning to end.  Instead, people look up what they
5417texinfo.texi(,5436) need.  For this reason, such creations should contain many cross
5418texinfo.texi(,5437) references to help readers find other information that they may not
5419texinfo.texi(,5438) have read.@refill
5420texinfo.texi(,5439)
5421texinfo.texi(,5440) In a printed manual, a cross reference results in a page reference,
5422texinfo.texi(,5441) unless it is to another manual altogether, in which case the cross
5423texinfo.texi(,5442) reference names that manual.@refill
5424texinfo.texi(,5443)
5425texinfo.texi(,5444) In Info, a cross reference results in an entry that you can follow using
5426texinfo.texi(,5445) the Info @samp{f} command.  (@inforef{Help-Adv, Some advanced Info
5427texinfo.texi(,5446) commands, info}.)@refill
5428texinfo.texi(,5447)
5429texinfo.texi(,5448) The various cross reference commands use nodes (or anchors,
5430texinfo.texi(,5449) @pxref{anchor,,@code{@@anchor}}) to define cross reference locations.
5431texinfo.texi(,5450) This is evident in Info, in which a cross reference takes you to the
5432texinfo.texi(,5451) specified location.  @TeX{} also uses nodes to define cross reference
5433texinfo.texi(,5452) locations, but the action is less obvious.  When @TeX{} generates a DVI
5434texinfo.texi(,5453) file, it records each node's page number and uses the page numbers in making
5435texinfo.texi(,5454) references.  Thus, if you are writing a manual that will only be
5436texinfo.texi(,5455) printed, and will not be used online, you must nonetheless write
5437texinfo.texi(,5456) @code{@@node} lines to name the places to which you make cross
5438texinfo.texi(,5457) references.@refill
5439texinfo.texi(,5458)
5440texinfo.texi(,5459) @need 800
5441texinfo.texi(,5460) @node Cross Reference Commands, Cross Reference Parts, References, Cross References
5442texinfo.texi(,5461) @comment  node-name,  next,  previous,  up
5443texinfo.texi(,5462) @section Different Cross Reference Commands
5444texinfo.texi(,5463) @cindex Different cross reference commands
5445texinfo.texi(,5464)
5446texinfo.texi(,5465) There are four different cross reference commands:@refill
5447texinfo.texi(,5466)
5448texinfo.texi(,5467) @table @code
5449texinfo.texi(,5468) @item @@xref
5450texinfo.texi(,5469) Used to start a sentence in the printed manual saying @w{`See @dots{}'}
5451texinfo.texi(,5470) or an Info cross-reference saying @samp{*Note @var{name}: @var{node}.}.
5452texinfo.texi(,5471)
5453texinfo.texi(,5472) @item @@ref
5454texinfo.texi(,5473) Used within or, more often, at the end of a sentence; same as
5455texinfo.texi(,5474) @code{@@xref} for Info; produces just the reference in the printed
5456texinfo.texi(,5475) manual without a preceding `See'.@refill
5457texinfo.texi(,5476)
5458texinfo.texi(,5477) @item @@pxref
5459texinfo.texi(,5478) Used within parentheses to make a reference that suits both an Info
5460texinfo.texi(,5479) file and a printed book.  Starts with a lower case `see' within the
5461texinfo.texi(,5480) printed manual. (@samp{p} is for `parenthesis'.)@refill
5462texinfo.texi(,5481)
5463texinfo.texi(,5482) @item @@inforef
5464texinfo.texi(,5483) Used to make a reference to an Info file for which there is no printed
5465texinfo.texi(,5484) manual.@refill
5466texinfo.texi(,5485) @end table
5467texinfo.texi(,5486)
5468texinfo.texi(,5487) @noindent
5469texinfo.texi(,5488) (The @code{@@cite} command is used to make references to books and
5470texinfo.texi(,5489) manuals for which there is no corresponding Info file and, therefore,
5471texinfo.texi(,5490) no node to which to point.   @xref{cite, , @code{@@cite}}.)@refill
5472texinfo.texi(,5491)
5473texinfo.texi(,5492) @node Cross Reference Parts, xref, Cross Reference Commands, Cross References
5474texinfo.texi(,5493) @comment  node-name,  next,  previous,  up
5475texinfo.texi(,5494) @section Parts of a Cross Reference
5476texinfo.texi(,5495) @cindex Cross reference parts
5477texinfo.texi(,5496) @cindex Parts of a cross reference
5478texinfo.texi(,5497)
5479texinfo.texi(,5498) A cross reference command requires only one argument, which is the
5480texinfo.texi(,5499) name of the node to which it refers.  But a cross reference command
5481texinfo.texi(,5500) may contain up to four additional arguments.  By using these
5482texinfo.texi(,5501) arguments, you can provide a cross reference name for Info, a topic
5483texinfo.texi(,5502) description or section title for the printed output, the name of a
5484texinfo.texi(,5503) different Info file, and the name of a different printed
5485texinfo.texi(,5504) manual.@refill
5486texinfo.texi(,5505)
5487texinfo.texi(,5506) Here is a simple cross reference example:@refill
5488texinfo.texi(,5507)
5489texinfo.texi(,5508) @example
5490texinfo.texi(,5509) @@xref@{Node name@}.
5491texinfo.texi(,5510) @end example
5492texinfo.texi(,5511)
5493texinfo.texi(,5512) @noindent
5494texinfo.texi(,5513) which produces
5495texinfo.texi(,5514)
5496texinfo.texi(,5515) @example
5497texinfo.texi(,5516) *Note Node name::.
5498texinfo.texi(,5517) @end example
5499texinfo.texi(,5518)
5500texinfo.texi(,5519) @noindent
5501texinfo.texi(,5520) and
5502texinfo.texi(,5521)
5503texinfo.texi(,5522) @quotation
5504texinfo.texi(,5523) See Section @var{nnn} [Node name], page @var{ppp}.
5505texinfo.texi(,5524) @end quotation
5506texinfo.texi(,5525)
5507texinfo.texi(,5526) @need 700
5508texinfo.texi(,5527) Here is an example of a full five-part cross reference:@refill
5509texinfo.texi(,5528)
5510texinfo.texi(,5529) @example
5511texinfo.texi(,5530) @group
5512texinfo.texi(,5531) @@xref@{Node name, Cross Reference Name, Particular Topic,
5513texinfo.texi(,5532) info-file-name, A Printed Manual@}, for details.
5514texinfo.texi(,5533) @end group
5515texinfo.texi(,5534) @end example
5516texinfo.texi(,5535)
5517texinfo.texi(,5536) @noindent
5518texinfo.texi(,5537) which produces
5519texinfo.texi(,5538)
5520texinfo.texi(,5539) @example
5521texinfo.texi(,5540) *Note Cross Reference Name: (info-file-name)Node name,
5522texinfo.texi(,5541) for details.
5523texinfo.texi(,5542) @end example
5524texinfo.texi(,5543)
5525texinfo.texi(,5544) @noindent
5526texinfo.texi(,5545) in Info and
5527texinfo.texi(,5546)
5528texinfo.texi(,5547) @quotation
5529texinfo.texi(,5548) See section ``Particular Topic'' in @i{A Printed Manual}, for details.
5530texinfo.texi(,5549) @end quotation
5531texinfo.texi(,5550)
5532texinfo.texi(,5551) @noindent
5533texinfo.texi(,5552) in a printed book.
5534texinfo.texi(,5553)
5535texinfo.texi(,5554) The five possible arguments for a cross reference are:@refill
5536texinfo.texi(,5555)
5537texinfo.texi(,5556) @enumerate
5538texinfo.texi(,5557) @item
5539texinfo.texi(,5558) The node or anchor name (required).  This is the location to which the
5540texinfo.texi(,5559) cross reference takes you.  In a printed document, the location of the
5541texinfo.texi(,5560) node provides the page reference only for references within the same
5542texinfo.texi(,5561) document.@refill
5543texinfo.texi(,5562)
5544texinfo.texi(,5563) @item
5545texinfo.texi(,5564) The cross reference name for the Info reference, if it is to be different
5546texinfo.texi(,5565) from the node name.  If you include this argument, it becomes
5547texinfo.texi(,5566) the first part of the cross reference.  It is usually omitted.@refill
5548texinfo.texi(,5567)
5549texinfo.texi(,5568) @item
5550texinfo.texi(,5569) A topic description or section name.  Often, this is the title of the
5551texinfo.texi(,5570) section.  This is used as the name of the reference in the printed
5552texinfo.texi(,5571) manual.  If omitted, the node name is used.@refill
5553texinfo.texi(,5572)
5554texinfo.texi(,5573) @item
5555texinfo.texi(,5574) The name of the Info file in which the reference is located, if it is
5556texinfo.texi(,5575) different from the current file.  You need not include any @samp{.info}
5557texinfo.texi(,5576) suffix on the file name, since Info readers try appending it
5558texinfo.texi(,5577) automatically.
5559texinfo.texi(,5578)
5560texinfo.texi(,5579) @item
5561texinfo.texi(,5580) The name of a printed manual from a different Texinfo file.@refill
5562texinfo.texi(,5581) @end enumerate
5563texinfo.texi(,5582)
5564texinfo.texi(,5583) The template for a full five argument cross reference looks like
5565texinfo.texi(,5584) this:@refill
5566texinfo.texi(,5585)
5567texinfo.texi(,5586) @example
5568texinfo.texi(,5587) @group
5569texinfo.texi(,5588) @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic},
5570texinfo.texi(,5589) @var{info-file-name}, @var{printed-manual-title}@}.
5571texinfo.texi(,5590) @end group
5572texinfo.texi(,5591) @end example
5573texinfo.texi(,5592)
5574texinfo.texi(,5593) Cross references with one, two, three, four, and five arguments are
5575texinfo.texi(,5594) described separately following the description of @code{@@xref}.@refill
5576texinfo.texi(,5595)
5577texinfo.texi(,5596) Write a node name in a cross reference in exactly the same way as in
5578texinfo.texi(,5597) the @code{@@node} line, including the same capitalization; otherwise, the
5579texinfo.texi(,5598) formatters may not find the reference.@refill
5580texinfo.texi(,5599)
5581texinfo.texi(,5600) You can write cross reference commands within a paragraph, but note
5582texinfo.texi(,5601) how Info and @TeX{} format the output of each of the various commands:
5583texinfo.texi(,5602) write @code{@@xref} at the beginning of a sentence; write
5584texinfo.texi(,5603) @code{@@pxref} only within parentheses, and so on.@refill
5585texinfo.texi(,5604)
5586texinfo.texi(,5605) @node xref, Top Node Naming, Cross Reference Parts, Cross References
5587texinfo.texi(,5606) @comment  node-name,  next,  previous,  up
5588texinfo.texi(,5607) @section @code{@@xref}
5589texinfo.texi(,5608) @findex xref
5590texinfo.texi(,5609) @cindex Cross references using @code{@@xref}
5591texinfo.texi(,5610) @cindex References using @code{@@xref}
5592texinfo.texi(,5611)
5593texinfo.texi(,5612) The @code{@@xref} command generates a cross reference for the
5594texinfo.texi(,5613) beginning of a sentence.  The Info formatting commands convert it into
5595texinfo.texi(,5614) an Info cross reference, which the Info @samp{f} command can use to
5596texinfo.texi(,5615) bring you directly to another node.  The @TeX{} typesetting commands
5597texinfo.texi(,5616) convert it into a page reference, or a reference to another book or
5598texinfo.texi(,5617) manual.@refill
5599texinfo.texi(,5618)
5600texinfo.texi(,5619) @menu
5601texinfo.texi(,5620) * Reference Syntax::            What a reference looks like and requires.
5602texinfo.texi(,5621) * One Argument::                @code{@@xref} with one argument.
5603texinfo.texi(,5622) * Two Arguments::               @code{@@xref} with two arguments.
5604texinfo.texi(,5623) * Three Arguments::             @code{@@xref} with three arguments.
5605texinfo.texi(,5624) * Four and Five Arguments::     @code{@@xref} with four and five arguments.
5606texinfo.texi(,5625) @end menu
5607texinfo.texi(,5626)
5608texinfo.texi(,5627) @node Reference Syntax, One Argument, xref, xref
5609texinfo.texi(,5629) @subheading What a Reference Looks Like and Requires
5610texinfo.texi(,5631)
5611texinfo.texi(,5632) Most often, an Info cross reference looks like this:@refill
5612texinfo.texi(,5633)
5613texinfo.texi(,5634) @example
5614texinfo.texi(,5635) *Note @var{node-name}::.
5615texinfo.texi(,5636) @end example
5616texinfo.texi(,5637)
5617texinfo.texi(,5638) @noindent
5618texinfo.texi(,5639) or like this
5619texinfo.texi(,5640)
5620texinfo.texi(,5641) @example
5621texinfo.texi(,5642) *Note @var{cross-reference-name}: @var{node-name}.
5622texinfo.texi(,5643) @end example
5623texinfo.texi(,5644)
5624texinfo.texi(,5645) @noindent
5625texinfo.texi(,5646) In @TeX{}, a cross reference looks like this:
5626texinfo.texi(,5647)
5627texinfo.texi(,5648) @quotation
5628texinfo.texi(,5649) See Section @var{section-number} [@var{node-name}], page @var{page}.
5629texinfo.texi(,5650) @end quotation
5630texinfo.texi(,5651)
5631texinfo.texi(,5652) @noindent
5632texinfo.texi(,5653) or like this
5633texinfo.texi(,5654)
5634texinfo.texi(,5655) @quotation
5635texinfo.texi(,5656) See Section @var{section-number} [@var{title-or-topic}], page @var{page}.
5636texinfo.texi(,5657) @end quotation
5637texinfo.texi(,5658)
5638texinfo.texi(,5659) The @code{@@xref} command does not generate a period or comma to end
5639texinfo.texi(,5660) the cross reference in either the Info file or the printed output.
5640texinfo.texi(,5661) You must write that period or comma yourself; otherwise, Info will not
5641texinfo.texi(,5662) recognize the end of the reference.  (The @code{@@pxref} command works
5642texinfo.texi(,5663) differently.  @xref{pxref, , @code{@@pxref}}.)@refill
5643texinfo.texi(,5664)
5644texinfo.texi(,5665) @quotation
5645texinfo.texi(,5666) @strong{Please note:} A period or comma @strong{must} follow the closing
5646texinfo.texi(,5667) brace of an @code{@@xref}.  It is required to terminate the cross
5647texinfo.texi(,5668) reference.  This period or comma will appear in the output, both in
5648texinfo.texi(,5669) the Info file and in the printed manual.@refill
5649texinfo.texi(,5670) @end quotation
5650texinfo.texi(,5671)
5651texinfo.texi(,5672) @code{@@xref} must refer to an Info node by name.  Use @code{@@node}
5652texinfo.texi(,5673) to define the node (@pxref{Writing a Node}).@refill
5653texinfo.texi(,5674)
5654texinfo.texi(,5675) @code{@@xref} is followed by several arguments inside braces, separated by
5655texinfo.texi(,5676) commas.  Whitespace before and after these commas is ignored.@refill
5656texinfo.texi(,5677)
5657texinfo.texi(,5678) A cross reference requires only the name of a node; but it may contain
5658texinfo.texi(,5679) up to four additional arguments.  Each of these variations produces a
5659texinfo.texi(,5680) cross reference that looks somewhat different.@refill
5660texinfo.texi(,5681)
5661texinfo.texi(,5682) @quotation
5662texinfo.texi(,5683) @strong{Please note:} Commas separate arguments in a cross reference;
5663texinfo.texi(,5684) avoid including them in the title or other part lest the formatters
5664texinfo.texi(,5685) mistake them for separators.@refill
5665texinfo.texi(,5686) @end quotation
5666texinfo.texi(,5687)
5667texinfo.texi(,5688) @node One Argument, Two Arguments, Reference Syntax, xref
5668texinfo.texi(,5689) @subsection @code{@@xref} with One Argument
5669texinfo.texi(,5690)
5670texinfo.texi(,5691) The simplest form of @code{@@xref} takes one argument, the name of
5671texinfo.texi(,5692) another node in the same Info file.    The Info formatters produce
5672texinfo.texi(,5693) output that the Info readers can use to jump to the reference; @TeX{}
5673texinfo.texi(,5694) produces output that specifies the page and section number for you.@refill
5674texinfo.texi(,5695)
5675texinfo.texi(,5696) @need 700
5676texinfo.texi(,5697) @noindent
5677texinfo.texi(,5698) For example,
5678texinfo.texi(,5699)
5679texinfo.texi(,5700) @example
5680texinfo.texi(,5701) @@xref@{Tropical Storms@}.
5681texinfo.texi(,5702) @end example
5682texinfo.texi(,5703)
5683texinfo.texi(,5704) @noindent
5684texinfo.texi(,5705) produces
5685texinfo.texi(,5706)
5686texinfo.texi(,5707) @example
5687texinfo.texi(,5708) *Note Tropical Storms::.
5688texinfo.texi(,5709) @end example
5689texinfo.texi(,5710)
5690texinfo.texi(,5711) @noindent
5691texinfo.texi(,5712) and
5692texinfo.texi(,5713)
5693texinfo.texi(,5714) @quotation
5694texinfo.texi(,5715) See Section 3.1 [Tropical Storms], page 24.
5695texinfo.texi(,5716) @end quotation
5696texinfo.texi(,5717)
5697texinfo.texi(,5718) @noindent
5698texinfo.texi(,5719) (Note that in the preceding example the closing brace is followed by a
5699texinfo.texi(,5720) period.)@refill
5700texinfo.texi(,5721)
5701texinfo.texi(,5722) You can write a clause after the cross reference, like this:@refill
5702texinfo.texi(,5723)
5703texinfo.texi(,5724) @example
5704texinfo.texi(,5725) @@xref@{Tropical Storms@}, for more info.
5705texinfo.texi(,5726) @end example
5706texinfo.texi(,5727)
5707texinfo.texi(,5728) @noindent
5708texinfo.texi(,5729) which produces
5709texinfo.texi(,5730)
5710texinfo.texi(,5731) @example
5711texinfo.texi(,5732) *Note Tropical Storms::, for more info.
5712texinfo.texi(,5733) @end example
5713texinfo.texi(,5734)
5714texinfo.texi(,5735) @noindent
5715texinfo.texi(,5736) and
5716texinfo.texi(,5737)
5717texinfo.texi(,5738) @quotation
5718texinfo.texi(,5739) See Section 3.1 [Tropical Storms], page 24, for more info.
5719texinfo.texi(,5740) @end quotation
5720texinfo.texi(,5741)
5721texinfo.texi(,5742) @noindent
5722texinfo.texi(,5743) (Note that in the preceding example the closing brace is followed by a
5723texinfo.texi(,5744) comma, and then by the clause, which is followed by a period.)@refill
5724texinfo.texi(,5745)
5725texinfo.texi(,5746) @node Two Arguments, Three Arguments, One Argument, xref
5726texinfo.texi(,5747) @subsection @code{@@xref} with Two Arguments
5727texinfo.texi(,5748)
5728texinfo.texi(,5749) With two arguments, the second is used as the name of the Info cross
5729texinfo.texi(,5750) reference, while the first is still the name of the node to which the
5730texinfo.texi(,5751) cross reference points.@refill
5731texinfo.texi(,5752)
5732texinfo.texi(,5753) @need 750
5733texinfo.texi(,5754) @noindent
5734texinfo.texi(,5755) The template is like this:
5735texinfo.texi(,5756)
5736texinfo.texi(,5757) @example
5737texinfo.texi(,5758) @@xref@{@var{node-name}, @var{cross-reference-name}@}.
5738texinfo.texi(,5759) @end example
5739texinfo.texi(,5760)
5740texinfo.texi(,5761) @need 700
5741texinfo.texi(,5762) @noindent
5742texinfo.texi(,5763) For example,
5743texinfo.texi(,5764)
5744texinfo.texi(,5765) @example
5745texinfo.texi(,5766) @@xref@{Electrical Effects, Lightning@}.
5746texinfo.texi(,5767) @end example
5747texinfo.texi(,5768)
5748texinfo.texi(,5769) @noindent
5749texinfo.texi(,5770) produces:
5750texinfo.texi(,5771)
5751texinfo.texi(,5772) @example
5752texinfo.texi(,5773) *Note Lightning: Electrical Effects.
5753texinfo.texi(,5774) @end example
5754texinfo.texi(,5775)
5755texinfo.texi(,5776) @noindent
5756texinfo.texi(,5777) and
5757texinfo.texi(,5778)
5758texinfo.texi(,5779) @quotation
5759texinfo.texi(,5780) See Section 5.2 [Electrical Effects], page 57.
5760texinfo.texi(,5781) @end quotation
5761texinfo.texi(,5782)
5762texinfo.texi(,5783) @noindent
5763texinfo.texi(,5784) (Note that in the preceding example the closing brace is followed by a
5764texinfo.texi(,5785) period; and that the node name is printed, not the cross reference name.)
5765texinfo.texi(,5786)
5766texinfo.texi(,5787) You can write a clause after the cross reference, like this:@refill
5767texinfo.texi(,5788)
5768texinfo.texi(,5789) @example
5769texinfo.texi(,5790) @@xref@{Electrical Effects, Lightning@}, for more info.
5770texinfo.texi(,5791) @end example
5771texinfo.texi(,5792)
5772texinfo.texi(,5793) @noindent
5773texinfo.texi(,5794) which produces
5774texinfo.texi(,5795) @example
5775texinfo.texi(,5796) *Note Lightning: Electrical Effects, for more info.
5776texinfo.texi(,5797) @end example
5777texinfo.texi(,5798)
5778texinfo.texi(,5799) @noindent
5779texinfo.texi(,5800) and
5780texinfo.texi(,5801)
5781texinfo.texi(,5802) @quotation
5782texinfo.texi(,5803) See Section 5.2 [Electrical Effects], page 57, for more info.
5783texinfo.texi(,5804) @end quotation
5784texinfo.texi(,5805)
5785texinfo.texi(,5806) @noindent
5786texinfo.texi(,5807) (Note that in the preceding example the closing brace is followed by a
5787texinfo.texi(,5808) comma, and then by the clause, which is followed by a period.)@refill
5788texinfo.texi(,5809)
5789texinfo.texi(,5810) @node Three Arguments, Four and Five Arguments, Two Arguments, xref
5790texinfo.texi(,5811) @subsection @code{@@xref} with Three Arguments
5791texinfo.texi(,5812)
5792texinfo.texi(,5813) A third argument replaces the node name in the @TeX{} output.  The third
5793texinfo.texi(,5814) argument should be the name of the section in the printed output, or
5794texinfo.texi(,5815) else state the topic discussed by that section.  Often, you will want to
5795texinfo.texi(,5816) use initial upper case letters so it will be easier to read when the
5796texinfo.texi(,5817) reference is printed.  Use a third argument when the node name is
5797texinfo.texi(,5818) unsuitable because of syntax or meaning.@refill
5798texinfo.texi(,5819)
5799texinfo.texi(,5820) Remember to avoid placing a comma within the title or topic section of
5800texinfo.texi(,5821) a cross reference, or within any other section.  The formatters divide
5801texinfo.texi(,5822) cross references into arguments according to the commas; a comma
5802texinfo.texi(,5823) within a title or other section will divide it into two arguments.  In
5803texinfo.texi(,5824) a reference, you need to write a title such as ``Clouds, Mist, and
5804texinfo.texi(,5825) Fog'' without the commas.@refill
5805texinfo.texi(,5826)
5806texinfo.texi(,5827) Also, remember to write a comma or period after the closing brace of an
5807texinfo.texi(,5828) @code{@@xref} to terminate the cross reference.  In the following
5808texinfo.texi(,5829) examples, a clause follows a terminating comma.@refill
5809texinfo.texi(,5830)
5810texinfo.texi(,5831)
5811texinfo.texi(,5832) @need 750
5812texinfo.texi(,5833) @noindent
5813texinfo.texi(,5834) The template is like this:
5814texinfo.texi(,5835)
5815texinfo.texi(,5836) @example
5816texinfo.texi(,5837) @group
5817texinfo.texi(,5838) @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}@}.
5818texinfo.texi(,5839) @end group
5819texinfo.texi(,5840) @end example
5820texinfo.texi(,5841)
5821texinfo.texi(,5842) @need 700
5822texinfo.texi(,5843) @noindent
5823texinfo.texi(,5844) For example,
5824texinfo.texi(,5845)
5825texinfo.texi(,5846) @example
5826texinfo.texi(,5847) @group
5827texinfo.texi(,5848) @@xref@{Electrical Effects, Lightning, Thunder and Lightning@},
5828texinfo.texi(,5849) for details.
5829texinfo.texi(,5850) @end group
5830texinfo.texi(,5851) @end example
5831texinfo.texi(,5852)
5832texinfo.texi(,5853) @noindent
5833texinfo.texi(,5854) produces
5834texinfo.texi(,5855)
5835texinfo.texi(,5856) @example
5836texinfo.texi(,5857) *Note Lightning: Electrical Effects, for details.
5837texinfo.texi(,5858) @end example
5838texinfo.texi(,5859)
5839texinfo.texi(,5860) @noindent
5840texinfo.texi(,5861) and
5841texinfo.texi(,5862)
5842texinfo.texi(,5863) @quotation
5843texinfo.texi(,5864) See Section 5.2 [Thunder and Lightning], page 57, for details.
5844texinfo.texi(,5865) @end quotation
5845texinfo.texi(,5866)
5846texinfo.texi(,5867) If a third argument is given and the second one is empty, then the
5847texinfo.texi(,5868) third argument serves both.  (Note how two commas, side by side, mark
5848texinfo.texi(,5869) the empty second argument.)@refill
5849texinfo.texi(,5870)
5850texinfo.texi(,5871) @example
5851texinfo.texi(,5872) @group
5852texinfo.texi(,5873) @@xref@{Electrical Effects, , Thunder and Lightning@},
5853texinfo.texi(,5874) for details.
5854texinfo.texi(,5875) @end group
5855texinfo.texi(,5876) @end example
5856texinfo.texi(,5877)
5857texinfo.texi(,5878) @noindent
5858texinfo.texi(,5879) produces
5859texinfo.texi(,5880)
5860texinfo.texi(,5881) @example
5861texinfo.texi(,5882) *Note Thunder and Lightning: Electrical Effects, for details.
5862texinfo.texi(,5883) @end example
5863texinfo.texi(,5884)
5864texinfo.texi(,5885) @noindent
5865texinfo.texi(,5886) and
5866texinfo.texi(,5887)
5867texinfo.texi(,5888) @quotation
5868texinfo.texi(,5889) See Section 5.2 [Thunder and Lightning], page 57, for details.
5869texinfo.texi(,5890) @end quotation
5870texinfo.texi(,5891)
5871texinfo.texi(,5892) As a practical matter, it is often best to write cross references with
5872texinfo.texi(,5893) just the first argument if the node name and the section title are the
5873texinfo.texi(,5894) same, and with the first and third arguments if the node name and title
5874texinfo.texi(,5895) are different.@refill
5875texinfo.texi(,5896)
5876texinfo.texi(,5897) Here are several examples from @cite{The GNU Awk User's Guide}:@refill
5877texinfo.texi(,5898)
5878texinfo.texi(,5899) @smallexample
5879texinfo.texi(,5900) @@xref@{Sample Program@}.
5880texinfo.texi(,5901) @@xref@{Glossary@}.
5881texinfo.texi(,5902) @@xref@{Case-sensitivity, ,Case-sensitivity in Matching@}.
5882texinfo.texi(,5903) @@xref@{Close Output, , Closing Output Files and Pipes@},
5883texinfo.texi(,5904)    for more information.
5884texinfo.texi(,5905) @@xref@{Regexp, , Regular Expressions as Patterns@}.
5885texinfo.texi(,5906) @end smallexample
5886texinfo.texi(,5907)
5887texinfo.texi(,5908) @node Four and Five Arguments,  , Three Arguments, xref
5888texinfo.texi(,5909) @subsection @code{@@xref} with Four and Five Arguments
5889texinfo.texi(,5910)
5890texinfo.texi(,5911) In a cross reference, a fourth argument specifies the name of another
5891texinfo.texi(,5912) Info file, different from the file in which the reference appears, and
5892texinfo.texi(,5913) a fifth argument specifies its title as a printed manual.@refill
5893texinfo.texi(,5914)
5894texinfo.texi(,5915) Remember that a comma or period must follow the closing brace of an
5895texinfo.texi(,5916) @code{@@xref} command to terminate the cross reference.  In the
5896texinfo.texi(,5917) following examples, a clause follows a terminating comma.@refill
5897texinfo.texi(,5918)
5898texinfo.texi(,5919) @need 800
5899texinfo.texi(,5920) @noindent
5900texinfo.texi(,5921) The template is:
5901texinfo.texi(,5922)
5902texinfo.texi(,5923) @example
5903texinfo.texi(,5924) @group
5904texinfo.texi(,5925) @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic},
5905texinfo.texi(,5926) @var{info-file-name}, @var{printed-manual-title}@}.
5906texinfo.texi(,5927) @end group
5907texinfo.texi(,5928) @end example
5908texinfo.texi(,5929)
5909texinfo.texi(,5930) @need 700
5910texinfo.texi(,5931) @noindent
5911texinfo.texi(,5932) For example,
5912texinfo.texi(,5933)
5913texinfo.texi(,5934) @example
5914texinfo.texi(,5935) @@xref@{Electrical Effects, Lightning, Thunder and Lightning,
5915texinfo.texi(,5936) weather, An Introduction to Meteorology@}, for details.
5916texinfo.texi(,5937) @end example
5917texinfo.texi(,5938)
5918texinfo.texi(,5939) @noindent
5919texinfo.texi(,5940) produces
5920texinfo.texi(,5941)
5921texinfo.texi(,5942) @example
5922texinfo.texi(,5943) *Note Lightning: (weather)Electrical Effects, for details.
5923texinfo.texi(,5944) @end example
5924texinfo.texi(,5945)
5925texinfo.texi(,5946) @noindent
5926texinfo.texi(,5947) The name of the Info file is enclosed in parentheses and precedes
5927texinfo.texi(,5948) the name of the node.
5928texinfo.texi(,5949)
5929texinfo.texi(,5950) @noindent
5930texinfo.texi(,5951) In a printed manual, the reference looks like this:@refill
5931texinfo.texi(,5952)
5932texinfo.texi(,5953) @quotation
5933texinfo.texi(,5954) See section ``Thunder and Lightning'' in @i{An Introduction to
5934texinfo.texi(,5955) Meteorology}, for details.
5935texinfo.texi(,5956) @end quotation
5936texinfo.texi(,5957)
5937texinfo.texi(,5958) @noindent
5938texinfo.texi(,5959) The title of the printed manual is typeset in italics; and the
5939texinfo.texi(,5960) reference lacks a page number since @TeX{} cannot know to which page a
5940texinfo.texi(,5961) reference refers when that reference is to another manual.@refill
5941texinfo.texi(,5962)
5942texinfo.texi(,5963) Often, you will leave out the second argument when you use the long
5943texinfo.texi(,5964) version of @code{@@xref}.  In this case, the third argument, the topic
5944texinfo.texi(,5965) description, will be used as the cross reference name in Info.@refill
5945texinfo.texi(,5966)
5946texinfo.texi(,5967) @noindent
5947texinfo.texi(,5968) The template looks like this:
5948texinfo.texi(,5969)
5949texinfo.texi(,5970) @example
5950texinfo.texi(,5971) @@xref@{@var{node-name}, , @var{title-or-topic}, @var{info-file-name},
5951texinfo.texi(,5972) @var{printed-manual-title}@}, for details.
5952texinfo.texi(,5973) @end example
5953texinfo.texi(,5974)
5954texinfo.texi(,5975) @noindent
5955texinfo.texi(,5976) which produces
5956texinfo.texi(,5977)
5957texinfo.texi(,5978) @example
5958texinfo.texi(,5979) *Note @var{title-or-topic}: (@var{info-file-name})@var{node-name}, for details.
5959texinfo.texi(,5980) @end example
5960texinfo.texi(,5981)
5961texinfo.texi(,5982) @noindent
5962texinfo.texi(,5983) and
5963texinfo.texi(,5984)
5964texinfo.texi(,5985) @quotation
5965texinfo.texi(,5986) See section @var{title-or-topic} in @var{printed-manual-title}, for details.
5966texinfo.texi(,5987) @end quotation
5967texinfo.texi(,5988)
5968texinfo.texi(,5989) @need 700
5969texinfo.texi(,5990) @noindent
5970texinfo.texi(,5991) For example,
5971texinfo.texi(,5992)
5972texinfo.texi(,5993) @example
5973texinfo.texi(,5994) @@xref@{Electrical Effects, , Thunder and Lightning,
5974texinfo.texi(,5995) weather, An Introduction to Meteorology@}, for details.
5975texinfo.texi(,5996) @end example
5976texinfo.texi(,5997)
5977texinfo.texi(,5998) @noindent
5978texinfo.texi(,5999) produces
5979texinfo.texi(,6000)
5980texinfo.texi(,6001) @example
5981texinfo.texi(,6002) @group
5982texinfo.texi(,6003) *Note Thunder and Lightning: (weather)Electrical Effects,
5983texinfo.texi(,6004) for details.
5984texinfo.texi(,6005) @end group
5985texinfo.texi(,6006) @end example
5986texinfo.texi(,6007)
5987texinfo.texi(,6008) @noindent
5988texinfo.texi(,6009) and
5989texinfo.texi(,6010)
5990texinfo.texi(,6011) @quotation
5991texinfo.texi(,6012) See section ``Thunder and Lightning'' in @i{An Introduction to
5992texinfo.texi(,6013) Meteorology}, for details.
5993texinfo.texi(,6014) @end quotation
5994texinfo.texi(,6015)
5995texinfo.texi(,6016) On rare occasions, you may want to refer to another Info file that
5996texinfo.texi(,6017) is within a single printed manual---when multiple Texinfo files are
5997texinfo.texi(,6018) incorporated into the same @TeX{} run but make separate Info files.
5998texinfo.texi(,6019) In this case, you need to specify only the fourth argument, and not
5999texinfo.texi(,6020) the fifth.@refill
6000texinfo.texi(,6021)
6001texinfo.texi(,6022) @node Top Node Naming, ref, xref, Cross References
6002texinfo.texi(,6023) @section Naming a `Top' Node
6003texinfo.texi(,6024) @cindex Naming a `Top' Node in references
6004texinfo.texi(,6025) @cindex @samp{@r{Top}} node naming for references
6005texinfo.texi(,6026)
6006texinfo.texi(,6027) In a cross reference, you must always name a node.  This means that in
6007texinfo.texi(,6028) order to refer to a whole manual, you must identify the `Top' node by
6008texinfo.texi(,6029) writing it as the first argument to the @code{@@xref} command.  (This
6009texinfo.texi(,6030) is different from the way you write a menu entry; see @ref{Other Info
6010texinfo.texi(,6031) Files, , Referring to Other Info Files}.)  At the same time, to
6011texinfo.texi(,6032) provide a meaningful section topic or title in the printed cross
6012texinfo.texi(,6033) reference (instead of the word `Top'), you must write an appropriate
6013texinfo.texi(,6034) entry for the third argument to the @code{@@xref} command.
6014texinfo.texi(,6035) @refill
6015texinfo.texi(,6036)
6016texinfo.texi(,6037) @noindent
6017texinfo.texi(,6038) Thus, to make a cross reference to @cite{The GNU Make Manual},
6018texinfo.texi(,6039) write:@refill
6019texinfo.texi(,6040)
6020texinfo.texi(,6041) @example
6021texinfo.texi(,6042) @@xref@{Top, , Overview, make, The GNU Make Manual@}.
6022texinfo.texi(,6043) @end example
6023texinfo.texi(,6044)
6024texinfo.texi(,6045) @noindent
6025texinfo.texi(,6046) which produces
6026texinfo.texi(,6047)
6027texinfo.texi(,6048) @example
6028texinfo.texi(,6049) *Note Overview: (make)Top.
6029texinfo.texi(,6050) @end example
6030texinfo.texi(,6051)
6031texinfo.texi(,6052) @noindent
6032texinfo.texi(,6053) and
6033texinfo.texi(,6054)
6034texinfo.texi(,6055) @quotation
6035texinfo.texi(,6056) See section ``Overview'' in @i{The GNU Make Manual}.
6036texinfo.texi(,6057) @end quotation
6037texinfo.texi(,6058)
6038texinfo.texi(,6059) @noindent
6039texinfo.texi(,6060) In this example, @samp{Top} is the name of the first node, and
6040texinfo.texi(,6061) @samp{Overview} is the name of the first section of the manual.@refill
6041texinfo.texi(,6062) @node ref, pxref, Top Node Naming, Cross References
6042texinfo.texi(,6063) @comment  node-name,  next,  previous,  up
6043texinfo.texi(,6064) @section @code{@@ref}
6044texinfo.texi(,6065) @cindex Cross references using @code{@@ref}
6045texinfo.texi(,6066) @cindex References using @code{@@ref}
6046texinfo.texi(,6067) @findex ref
6047texinfo.texi(,6068)
6048texinfo.texi(,6069) @code{@@ref} is nearly the same as @code{@@xref} except that it does
6049texinfo.texi(,6070) not generate a `See' in the printed output, just the reference itself.
6050texinfo.texi(,6071) This makes it useful as the last part of a sentence.@refill
6051texinfo.texi(,6072)
6052texinfo.texi(,6073) @need 700
6053texinfo.texi(,6074) @noindent
6054texinfo.texi(,6075) For example,
6055texinfo.texi(,6076)
6056texinfo.texi(,6077) @cindex Hurricanes
6057texinfo.texi(,6078) @example
6058texinfo.texi(,6079) For more information, see @@ref@{Hurricanes@}.
6059texinfo.texi(,6080) @end example
6060texinfo.texi(,6081)
6061texinfo.texi(,6082) @noindent
6062texinfo.texi(,6083) produces
6063texinfo.texi(,6084)
6064texinfo.texi(,6085) @example
6065texinfo.texi(,6086) For more information, see *Note Hurricanes::.
6066texinfo.texi(,6087) @end example
6067texinfo.texi(,6088)
6068texinfo.texi(,6089) @noindent
6069texinfo.texi(,6090) and
6070texinfo.texi(,6091)
6071texinfo.texi(,6092) @quotation
6072texinfo.texi(,6093) For more information, see Section 8.2 [Hurricanes], page 123.
6073texinfo.texi(,6094) @end quotation
6074texinfo.texi(,6095)
6075texinfo.texi(,6096) The @code{@@ref} command sometimes leads writers to express themselves
6076texinfo.texi(,6097) in a manner that is suitable for a printed manual but looks awkward
6077texinfo.texi(,6098) in the Info format.  Bear in mind that your audience will be using
6078texinfo.texi(,6099) both the printed and the Info format.@refill
6079texinfo.texi(,6100)
6080texinfo.texi(,6101) @need 800
6081texinfo.texi(,6102) @noindent
6082texinfo.texi(,6103) For example,
6083texinfo.texi(,6104)
6084texinfo.texi(,6105) @cindex Sea surges
6085texinfo.texi(,6106) @example
6086texinfo.texi(,6107) @group
6087texinfo.texi(,6108) Sea surges are described in @@ref@{Hurricanes@}.
6088texinfo.texi(,6109) @end group
6089texinfo.texi(,6110) @end example
6090texinfo.texi(,6111)
6091texinfo.texi(,6112) @need 800
6092texinfo.texi(,6113) @noindent
6093texinfo.texi(,6114) produces
6094texinfo.texi(,6115)
6095texinfo.texi(,6116) @quotation
6096texinfo.texi(,6117) Sea surges are described in Section 6.7 [Hurricanes], page 72.
6097texinfo.texi(,6118) @end quotation
6098texinfo.texi(,6119)
6099texinfo.texi(,6120) @need 800
6100texinfo.texi(,6121) @noindent
6101texinfo.texi(,6122) in a printed document, and the following in Info:
6102texinfo.texi(,6123)
6103texinfo.texi(,6124) @example
6104texinfo.texi(,6125) Sea surges are described in *Note Hurricanes::.
6105texinfo.texi(,6126) @end example
6106texinfo.texi(,6127)
6107texinfo.texi(,6128) @quotation
6108texinfo.texi(,6129) @strong{Caution:} You @emph{must} write a period, comma, or right
6109texinfo.texi(,6130) parenthesis immediately after an @code{@@ref} command with two or more
6110texinfo.texi(,6131) arguments.  Otherwise, Info will not find the end of the cross reference
6111texinfo.texi(,6132) entry and its attempt to follow the cross reference will fail.  As a
6112texinfo.texi(,6133) general rule, you should write a period or comma after every
6113texinfo.texi(,6134) @code{@@ref} command.  This looks best in both the printed and the Info
6114texinfo.texi(,6135) output.@refill
6115texinfo.texi(,6136) @end quotation
6116texinfo.texi(,6137)
6117texinfo.texi(,6138) @node pxref, inforef, ref, Cross References
6118texinfo.texi(,6139) @comment  node-name,  next,  previous,  up
6119texinfo.texi(,6140) @section @code{@@pxref}
6120texinfo.texi(,6141) @cindex Cross references using @code{@@pxref}
6121texinfo.texi(,6142) @cindex References using @code{@@pxref}
6122texinfo.texi(,6143) @findex pxref
6123texinfo.texi(,6144)
6124texinfo.texi(,6145) The parenthetical reference command, @code{@@pxref}, is nearly the
6125texinfo.texi(,6146) same as @code{@@xref}, but you use it @emph{only} inside parentheses
6126texinfo.texi(,6147) and you do @emph{not} type a comma or period after the command's
6127texinfo.texi(,6148) closing brace.  The command differs from @code{@@xref} in two
6128texinfo.texi(,6149) ways:@refill
6129texinfo.texi(,6150)
6130texinfo.texi(,6151) @enumerate
6131texinfo.texi(,6152) @item
6132texinfo.texi(,6153) @TeX{} typesets the reference for the printed manual with a lower case
6133texinfo.texi(,6154) `see' rather than an upper case `See'.@refill
6134texinfo.texi(,6155)
6135texinfo.texi(,6156) @item
6136texinfo.texi(,6157) The Info formatting commands automatically end the reference with a
6137texinfo.texi(,6158) closing colon or period.@refill
6138texinfo.texi(,6159) @end enumerate
6139texinfo.texi(,6160)
6140texinfo.texi(,6161) Because one type of formatting automatically inserts closing
6141texinfo.texi(,6162) punctuation and the other does not, you should use @code{@@pxref}
6142texinfo.texi(,6163) @emph{only} inside parentheses as part of another sentence.  Also, you
6143texinfo.texi(,6164) yourself should not insert punctuation after the reference, as you do
6144texinfo.texi(,6165) with @code{@@xref}.@refill
6145texinfo.texi(,6166)
6146texinfo.texi(,6167) @code{@@pxref} is designed so that the output looks right and works
6147texinfo.texi(,6168) right between parentheses both in printed output and in an Info file.
6148texinfo.texi(,6169) In a printed manual, a closing comma or period should not follow a
6149texinfo.texi(,6170) cross reference within parentheses; such punctuation is wrong.  But in
6150texinfo.texi(,6171) an Info file, suitable closing punctuation must follow the cross
6151texinfo.texi(,6172) reference so Info can recognize its end.  @code{@@pxref} spares you
6152texinfo.texi(,6173) the need to use complicated methods to put a terminator into one form
6153texinfo.texi(,6174) of the output and not the other.@refill
6154texinfo.texi(,6175)
6155texinfo.texi(,6176) @noindent
6156texinfo.texi(,6177) With one argument, a parenthetical cross reference looks like
6157texinfo.texi(,6178) this:@refill
6158texinfo.texi(,6179)
6159texinfo.texi(,6180) @cindex Flooding
6160texinfo.texi(,6181) @example
6161texinfo.texi(,6182) @dots{} storms cause flooding (@@pxref@{Hurricanes@}) @dots{}
6162texinfo.texi(,6183) @end example
6163texinfo.texi(,6184)
6164texinfo.texi(,6185) @need 800
6165texinfo.texi(,6186) @noindent
6166texinfo.texi(,6187) which produces
6167texinfo.texi(,6188)
6168texinfo.texi(,6189) @example
6169texinfo.texi(,6190) @group
6170texinfo.texi(,6191) @dots{} storms cause flooding (*Note Hurricanes::) @dots{}
6171texinfo.texi(,6192) @end group
6172texinfo.texi(,6193) @end example
6173texinfo.texi(,6194)
6174texinfo.texi(,6195) @noindent
6175texinfo.texi(,6196) and
6176texinfo.texi(,6197)
6177texinfo.texi(,6198) @quotation
6178texinfo.texi(,6199) @dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{}
6179texinfo.texi(,6200) @end quotation
6180texinfo.texi(,6201)
6181texinfo.texi(,6202) With two arguments, a parenthetical cross reference has this
6182texinfo.texi(,6203) template:@refill
6183texinfo.texi(,6204)
6184texinfo.texi(,6205) @example
6185texinfo.texi(,6206) @dots{} (@@pxref@{@var{node-name}, @var{cross-reference-name}@}) @dots{}
6186texinfo.texi(,6207) @end example
6187texinfo.texi(,6208)
6188texinfo.texi(,6209) @noindent
6189texinfo.texi(,6210) which produces
6190texinfo.texi(,6211)
6191texinfo.texi(,6212) @example
6192texinfo.texi(,6213) @dots{} (*Note @var{cross-reference-name}: @var{node-name}.) @dots{}
6193texinfo.texi(,6214) @end example
6194texinfo.texi(,6215)
6195texinfo.texi(,6216) @noindent
6196texinfo.texi(,6217) and
6197texinfo.texi(,6218)
6198texinfo.texi(,6219) @need 1500
6199texinfo.texi(,6220) @quotation
6200texinfo.texi(,6221) @dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{}
6201texinfo.texi(,6222) @end quotation
6202texinfo.texi(,6223)
6203texinfo.texi(,6224) @code{@@pxref} can be used with up to five arguments just like
6204texinfo.texi(,6225) @code{@@xref} (@pxref{xref, , @code{@@xref}}).@refill
6205texinfo.texi(,6226)
6206texinfo.texi(,6227) @quotation
6207texinfo.texi(,6228) @strong{Please note:} Use @code{@@pxref} only as a parenthetical
6208texinfo.texi(,6229) reference.  Do not try to use @code{@@pxref} as a clause in a sentence.
6209texinfo.texi(,6230) It will look bad in either the Info file, the printed output, or
6210texinfo.texi(,6231) both.@refill
6211texinfo.texi(,6232)
6212texinfo.texi(,6233) Also, parenthetical cross references look best at the ends of sentences.
6213texinfo.texi(,6234) Although you may write them in the middle of a sentence, that location
6214texinfo.texi(,6235) breaks up the flow of text.@refill
6215texinfo.texi(,6236) @end quotation
6216texinfo.texi(,6237)
6217texinfo.texi(,6238) @node inforef, uref, pxref, Cross References
6218texinfo.texi(,6239) @section @code{@@inforef}
6219texinfo.texi(,6240) @cindex Cross references using @code{@@inforef}
6220texinfo.texi(,6241) @cindex References using @code{@@inforef}
6221texinfo.texi(,6242) @findex inforef
6222texinfo.texi(,6243)
6223texinfo.texi(,6244) @code{@@inforef} is used for cross references to Info files for which
6224texinfo.texi(,6245) there are no printed manuals.  Even in a printed manual,
6225texinfo.texi(,6246) @code{@@inforef} generates a reference directing the user to look in
6226texinfo.texi(,6247) an Info file.@refill
6227texinfo.texi(,6248)
6228texinfo.texi(,6249) The command takes either two or three arguments, in the following
6229texinfo.texi(,6250) order:@refill
6230texinfo.texi(,6251)
6231texinfo.texi(,6252) @enumerate
6232texinfo.texi(,6253) @item
6233texinfo.texi(,6254) The node name.
6234texinfo.texi(,6255)
6235texinfo.texi(,6256) @item
6236texinfo.texi(,6257) The cross reference name (optional).
6237texinfo.texi(,6258)
6238texinfo.texi(,6259) @item
6239texinfo.texi(,6260) The Info file name.
6240texinfo.texi(,6261) @end enumerate
6241texinfo.texi(,6262)
6242texinfo.texi(,6263) @noindent
6243texinfo.texi(,6264) Separate the arguments with commas, as with @code{@@xref}.  Also, you
6244texinfo.texi(,6265) must terminate the reference with a comma or period after the
6245texinfo.texi(,6266) @samp{@}}, as you do with @code{@@xref}.@refill
6246texinfo.texi(,6267)
6247texinfo.texi(,6268) @noindent
6248texinfo.texi(,6269) The template is:
6249texinfo.texi(,6270)
6250texinfo.texi(,6271) @example
6251texinfo.texi(,6272) @@inforef@{@var{node-name}, @var{cross-reference-name}, @var{info-file-name}@},
6252texinfo.texi(,6273) @end example
6253texinfo.texi(,6274)
6254texinfo.texi(,6275) @need 800
6255texinfo.texi(,6276) @noindent
6256texinfo.texi(,6277) Thus,
6257texinfo.texi(,6278)
6258texinfo.texi(,6279) @example
6259texinfo.texi(,6280) @group
6260texinfo.texi(,6281) @@inforef@{Expert, Advanced Info commands, info@},
6261texinfo.texi(,6282) for more information.
6262texinfo.texi(,6283) @end group
6263texinfo.texi(,6284) @end example
6264texinfo.texi(,6285)
6265texinfo.texi(,6286) @need 800
6266texinfo.texi(,6287) @noindent
6267texinfo.texi(,6288) produces
6268texinfo.texi(,6289)
6269texinfo.texi(,6290) @example
6270texinfo.texi(,6291) @group
6271texinfo.texi(,6292) *Note Advanced Info commands: (info)Expert,
6272texinfo.texi(,6293) for more information.
6273texinfo.texi(,6294) @end group
6274texinfo.texi(,6295) @end example
6275texinfo.texi(,6296)
6276texinfo.texi(,6297) @need 800
6277texinfo.texi(,6298) @noindent
6278texinfo.texi(,6299) and
6279texinfo.texi(,6300)
6280texinfo.texi(,6301) @quotation
6281texinfo.texi(,6302) See Info file @file{info}, node @samp{Expert}, for more information.
6282texinfo.texi(,6303) @end quotation
6283texinfo.texi(,6304)
6284texinfo.texi(,6305) @need 800
6285texinfo.texi(,6306) @noindent
6286texinfo.texi(,6307) Similarly,
6287texinfo.texi(,6308)
6288texinfo.texi(,6309) @example
6289texinfo.texi(,6310) @group
6290texinfo.texi(,6311) @@inforef@{Expert, , info@}, for more information.
6291texinfo.texi(,6312) @end group
6292texinfo.texi(,6313) @end example
6293texinfo.texi(,6314)
6294texinfo.texi(,6315) @need 800
6295texinfo.texi(,6316) @noindent
6296texinfo.texi(,6317) produces
6297texinfo.texi(,6318)
6298texinfo.texi(,6319) @example
6299texinfo.texi(,6320) *Note (info)Expert::, for more information.
6300texinfo.texi(,6321) @end example
6301texinfo.texi(,6322)
6302texinfo.texi(,6323) @need 800
6303texinfo.texi(,6324) @noindent
6304texinfo.texi(,6325) and
6305texinfo.texi(,6326)
6306texinfo.texi(,6327) @quotation
6307texinfo.texi(,6328) See Info file @file{info}, node @samp{Expert}, for more information.
6308texinfo.texi(,6329) @end quotation
6309texinfo.texi(,6330)
6310texinfo.texi(,6331) The converse of @code{@@inforef} is @code{@@cite}, which is used to
6311texinfo.texi(,6332) refer to printed works for which no Info form exists.  @xref{cite, ,
6312texinfo.texi(,6333) @code{@@cite}}.@refill
6313texinfo.texi(,6334)
6314texinfo.texi(,6335)
6315texinfo.texi(,6336) @node uref
6316texinfo.texi(,6337) @section @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}}
6317texinfo.texi(,6338) @findex uref
6318texinfo.texi(,6339) @cindex Uniform resource locator, referring to
6319texinfo.texi(,6340) @cindex URL, referring to
6320texinfo.texi(,6341)
6321texinfo.texi(,6342) @cindex @code{href}, producing HTML
6322texinfo.texi(,6343) @code{@@uref} produces a reference to a uniform resource locator (url).
6323texinfo.texi(,6344) It takes one mandatory argument, the url, and two optional arguments
6324texinfo.texi(,6345) which control the text that is displayed.  In HTML output, @code{@@uref}
6325texinfo.texi(,6346) produces a link you can follow.
6326texinfo.texi(,6347)
6327texinfo.texi(,6348) The second argument, if specified, is the text to display (the default
6328texinfo.texi(,6349) is the url itself); in Info and DVI output, but not in HTML output, the
6329texinfo.texi(,6350) url is also output.
6330texinfo.texi(,6351)
6331texinfo.texi(,6352) @cindex Man page, reference to
6332texinfo.texi(,6353) The third argument, on the other hand, if specified is also the text to
6333texinfo.texi(,6354) display, but the url is @emph{not} output in any format.  This is useful
6334texinfo.texi(,6355) when the text is already sufficiently referential, as in a man page.  If
6335texinfo.texi(,6356) the third argument is given, the second argument is ignored.
6336texinfo.texi(,6357)
6337texinfo.texi(,6358) The simple one argument form, where the url is both the target and the
6338texinfo.texi(,6359) text of the link:
6339texinfo.texi(,6360)
6340texinfo.texi(,6361) @example
6341texinfo.texi(,6362) The official GNU ftp site is @@uref@{ftp://ftp.gnu.org/gnu@}.
6342texinfo.texi(,6363) @end example
6343texinfo.texi(,6364)
6344texinfo.texi(,6365) @noindent produces:
6345texinfo.texi(,6366) @display
6346texinfo.texi(,6367) The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}.
6347texinfo.texi(,6368) @end display
6348texinfo.texi(,6369)
6349texinfo.texi(,6370)
6350texinfo.texi(,6371) An example of the two-argument form:
6351texinfo.texi(,6372) @example
6352texinfo.texi(,6373) The official @@uref@{ftp://ftp.gnu.org/gnu, GNU ftp site@}
6353texinfo.texi(,6374) holds programs and texts.
6354texinfo.texi(,6375) @end example
6355texinfo.texi(,6376)
6356texinfo.texi(,6377) @noindent produces:
6357texinfo.texi(,6378) @display
6358texinfo.texi(,6379) The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site}
6359texinfo.texi(,6380) holds programs and texts.
6360texinfo.texi(,6381) @end display
6361texinfo.texi(,6382)
6362texinfo.texi(,6383) @noindent that is, the Info output is this:
6363texinfo.texi(,6384) @example
6364texinfo.texi(,6385) The official GNU ftp site (ftp://ftp.gnu.org/gnu)
6365texinfo.texi(,6386) holds programs and texts.
6366texinfo.texi(,6387) @end example
6367texinfo.texi(,6388)
6368texinfo.texi(,6389) @noindent and the HTML output is this:
6369texinfo.texi(,6390) @example
6370texinfo.texi(,6391) The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a>
6371texinfo.texi(,6392) holds programs and texts.
6372texinfo.texi(,6393) @end example
6373texinfo.texi(,6394)
6374texinfo.texi(,6395)
6375texinfo.texi(,6396) An example of the three-argument form:
6376texinfo.texi(,6397) @example
6377texinfo.texi(,6398) The @@uref@{/man.cgi/1/ls,,ls(1)@} program @dots{}
6378texinfo.texi(,6399) @end example
6379texinfo.texi(,6400)
6380texinfo.texi(,6401) @noindent produces:
6381texinfo.texi(,6402) @display
6382texinfo.texi(,6403) The @uref{/man.cgi/1/ls,,ls(1)} program @dots{}
6383texinfo.texi(,6404) @end display
6384texinfo.texi(,6405)
6385texinfo.texi(,6406) @noindent but with HTML:
6386texinfo.texi(,6407) @example
6387texinfo.texi(,6408) The <a href="/man.cgi/1/ls">ls(1)</a> program @dots{}
6388texinfo.texi(,6409) @end example
6389texinfo.texi(,6410)
6390texinfo.texi(,6411) To merely indicate a url without creating a link people can follow, use
6391texinfo.texi(,6412) @code{@@url} (@pxref{url, @code{@@url}}).
6392texinfo.texi(,6413)
6393texinfo.texi(,6414) Some people prefer to display url's in the unambiguous format:
6394texinfo.texi(,6415)
6395texinfo.texi(,6416) @display
6396texinfo.texi(,6417) <URL:http://@var{host}/@var{path}>
6397texinfo.texi(,6418) @end display
6398texinfo.texi(,6419)
6399texinfo.texi(,6420) @noindent
6400texinfo.texi(,6421) @cindex <URL convention, not used
6401texinfo.texi(,6422) You can use this form in the input file if you wish.  We feel it's not
6402texinfo.texi(,6423) necessary to clutter up the output with the extra @samp{<URL:} and
6403texinfo.texi(,6424) @samp{>}, since any software that tries to detect url's in text already
6404texinfo.texi(,6425) has to detect them without the @samp{<URL:} to be useful.
6405texinfo.texi(,6426)
6406texinfo.texi(,6427)
6407texinfo.texi(,6428) @node Marking Text
6408texinfo.texi(,6429) @chapter Marking Words and Phrases
6409texinfo.texi(,6430) @cindex Paragraph, marking text within
6410texinfo.texi(,6431) @cindex Marking words and phrases
6411texinfo.texi(,6432) @cindex Words and phrases, marking them
6412texinfo.texi(,6433) @cindex Marking text within a paragraph
6413texinfo.texi(,6434) @cindex Text, marking up
6414texinfo.texi(,6435)
6415texinfo.texi(,6436) In Texinfo, you can mark words and phrases in a variety of ways.
6416texinfo.texi(,6437) The Texinfo formatters use this information to determine how to
6417texinfo.texi(,6438) highlight the text.
6418texinfo.texi(,6439) You can specify, for example, whether a word or phrase is a
6419texinfo.texi(,6440) defining occurrence, a metasyntactic variable, or a symbol used in a
6420texinfo.texi(,6441) program.  Also, you can emphasize text, in several different ways.
6421texinfo.texi(,6442)
6422texinfo.texi(,6443) @menu
6423texinfo.texi(,6444) * Indicating::                  How to indicate definitions, files, etc.
6424texinfo.texi(,6445) * Emphasis::                    How to emphasize text.
6425texinfo.texi(,6446) @end menu
6426texinfo.texi(,6447)
6427texinfo.texi(,6448)
6428texinfo.texi(,6449) @node Indicating, Emphasis, Marking Text, Marking Text
6429texinfo.texi(,6450) @section Indicating Definitions, Commands, etc.
6430texinfo.texi(,6451) @cindex Highlighting text
6431texinfo.texi(,6452) @cindex Indicating commands, definitions, etc.
6432texinfo.texi(,6453)
6433texinfo.texi(,6454) Texinfo has commands for indicating just what kind of object a piece of
6434texinfo.texi(,6455) text refers to.  For example, metasyntactic variables are marked by
6435texinfo.texi(,6456) @code{@@var}, and code by @code{@@code}.  Since the pieces of text are
6436texinfo.texi(,6457) labelled by commands that tell what kind of object they are, it is easy
6437texinfo.texi(,6458) to change the way the Texinfo formatters prepare such text.  (Texinfo is
6438texinfo.texi(,6459) an @emph{intentional} formatting language rather than a @emph{typesetting}
6439texinfo.texi(,6460) formatting language.)@refill
6440texinfo.texi(,6461)
6441texinfo.texi(,6462) For example, in a printed manual,
6442texinfo.texi(,6463) code is usually illustrated in a typewriter font;
6443texinfo.texi(,6464) @code{@@code} tells @TeX{} to typeset this text in this font.  But it
6444texinfo.texi(,6465) would be easy to change the way @TeX{} highlights code to use another
6445texinfo.texi(,6466) font, and this change would not affect how keystroke examples are
6446texinfo.texi(,6467) highlighted.  If straight typesetting commands were used in the body
6447texinfo.texi(,6468) of the file and you wanted to make a change, you would need to check
6448texinfo.texi(,6469) every single occurrence to make sure that you were changing code and
6449texinfo.texi(,6470) not something else that should not be changed.@refill
6450texinfo.texi(,6471)
6451texinfo.texi(,6472) @menu
6452texinfo.texi(,6473) * Useful Highlighting::         Highlighting provides useful information.
6453texinfo.texi(,6474) * code::                        Indicating program code.
6454texinfo.texi(,6475) * kbd::                         Showing keyboard input.
6455texinfo.texi(,6476) * key::                         Specifying keys.
6456texinfo.texi(,6477) * samp::                        A literal sequence of characters.
6457texinfo.texi(,6478) * verb::                        A verbatim sequence of characters.
6458texinfo.texi(,6479) * var::                         Indicating metasyntactic variables.
6459texinfo.texi(,6480) * env::                         Indicating environment variables.
6460texinfo.texi(,6481) * file::                        Indicating file names.
6461texinfo.texi(,6482) * command::                     Indicating command names.
6462texinfo.texi(,6483) * option::                      Indicating option names.
6463texinfo.texi(,6484) * dfn::                         Specifying definitions.
6464texinfo.texi(,6485) * cite::                        Referring to books not in the  Info system.
6465texinfo.texi(,6486) * acronym::                     Indicating acronyms.
6466texinfo.texi(,6487) * url::                         Indicating a World Wide Web reference.
6467texinfo.texi(,6488) * email::                       Indicating an electronic mail address.
6468texinfo.texi(,6489) @end menu
6469texinfo.texi(,6490)
6470texinfo.texi(,6491)
6471texinfo.texi(,6492) @node Useful Highlighting, code, Indicating, Indicating
6472texinfo.texi(,6494) @subheading Highlighting Commands are Useful
6473texinfo.texi(,6496)
6474texinfo.texi(,6497) The highlighting commands can be used to extract useful information
6475texinfo.texi(,6498) from the file, such as lists of functions or file names.  It is
6476texinfo.texi(,6499) possible, for example, to write a program in Emacs Lisp (or a keyboard
6477texinfo.texi(,6500) macro) to insert an index entry after every paragraph that contains
6478texinfo.texi(,6501) words or phrases marked by a specified command.  You could do this to
6479texinfo.texi(,6502) construct an index of functions if you had not already made the
6480texinfo.texi(,6503) entries.@refill
6481texinfo.texi(,6504)
6482texinfo.texi(,6505) The commands serve a variety of purposes:@refill
6483texinfo.texi(,6506)
6484texinfo.texi(,6507) @table @code
6485texinfo.texi(,6508) @item @@code@{@var{sample-code}@}
6486texinfo.texi(,6509) Indicate text that is a literal example of a piece of a program.@refill
6487texinfo.texi(,6510)
6488texinfo.texi(,6511) @item @@kbd@{@var{keyboard-characters}@}
6489texinfo.texi(,6512) Indicate keyboard input.@refill
6490texinfo.texi(,6513)
6491texinfo.texi(,6514) @item @@key@{@var{key-name}@}
6492texinfo.texi(,6515) Indicate the conventional name for a key on a keyboard.@refill
6493texinfo.texi(,6516)
6494texinfo.texi(,6517) @item @@samp@{@var{text}@}
6495texinfo.texi(,6518) Indicate text that is a literal example of a sequence of characters.@refill
6496texinfo.texi(,6519)
6497texinfo.texi(,6520) @item @@var@{@var{metasyntactic-variable}@}
6498texinfo.texi(,6521) Indicate a metasyntactic variable.@refill
6499texinfo.texi(,6522)
6500texinfo.texi(,6523) @item @@env@{@var{environment-variable}@}
6501texinfo.texi(,6524) Indicate an environment variable.@refill
6502texinfo.texi(,6525)
6503texinfo.texi(,6526) @item @@file@{@var{file-name}@}
6504texinfo.texi(,6527) Indicate the name of a file.@refill
6505texinfo.texi(,6528)
6506texinfo.texi(,6529) @item @@command@{@var{command-name}@}
6507texinfo.texi(,6530) Indicate the name of a command.@refill
6508texinfo.texi(,6531)
6509texinfo.texi(,6532) @item @@option@{@var{option}@}
6510texinfo.texi(,6533) Indicate a command-line option.@refill
6511texinfo.texi(,6534)
6512texinfo.texi(,6535) @item @@dfn@{@var{term}@}
6513texinfo.texi(,6536) Indicate the introductory or defining use of a term.@refill
6514texinfo.texi(,6537)
6515texinfo.texi(,6538) @item @@cite@{@var{reference}@}
6516texinfo.texi(,6539) Indicate the name of a book.@refill
6517texinfo.texi(,6540)
6518texinfo.texi(,6541) @item @@acronym@{@var{acronym}@}
6519texinfo.texi(,6542) Indicate an acronym.@refill
6520texinfo.texi(,6543)
6521texinfo.texi(,6544) @item @@url@{@var{uniform-resource-locator}@}
6522texinfo.texi(,6545) Indicate a uniform resource locator for the World Wide Web.
6523texinfo.texi(,6546)
6524texinfo.texi(,6547) @item @@email@{@var{email-address}[, @var{displayed-text}]@}
6525texinfo.texi(,6548) Indicate an electronic mail address.
6526texinfo.texi(,6549)
6527texinfo.texi(,6554) @end table
6528texinfo.texi(,6555)
6529texinfo.texi(,6556)
6530texinfo.texi(,6557) @node code
6531texinfo.texi(,6558) @subsection @code{@@code}@{@var{sample-code}@}
6532texinfo.texi(,6559) @findex code
6533texinfo.texi(,6560)
6534texinfo.texi(,6561) @cindex Syntactic tokens, indicating
6535texinfo.texi(,6562) Use the @code{@@code} command to indicate text that is a piece of a
6536texinfo.texi(,6563) program and which consists of entire syntactic tokens.  Enclose the
6537texinfo.texi(,6564) text in braces.
6538texinfo.texi(,6565)
6539texinfo.texi(,6566) @cindex Expressions in a program, indicating
6540texinfo.texi(,6567) @cindex Keywords, indicating
6541texinfo.texi(,6568) @cindex Reserved words, indicating
6542texinfo.texi(,6569) Thus, you should use @code{@@code} for an expression in a program, for
6543texinfo.texi(,6570) the name of a variable or function used in a program, or for a
6544texinfo.texi(,6571) keyword in a programming language.
6545texinfo.texi(,6572)
6546texinfo.texi(,6573) Use @code{@@code} for command names in languages that resemble
6547texinfo.texi(,6574) programming languages, such as Texinfo.  For example, @code{@@code} and
6548texinfo.texi(,6575) @code{@@samp} are produced by writing @samp{@@code@{@@@@code@}} and
6549texinfo.texi(,6576) @samp{@@code@{@@@@samp@}} in the Texinfo source, respectively.
6550texinfo.texi(,6577)
6551texinfo.texi(,6578) @cindex Case, not altering in @code{@@code}
6552texinfo.texi(,6579) It is incorrect to alter the case of a word inside an @code{@@code}
6553texinfo.texi(,6580) command when it appears at the beginning of a sentence.  Most computer
6554texinfo.texi(,6581) languages are case sensitive.  In C, for example, @code{Printf} is
6555texinfo.texi(,6582) different from the identifier @code{printf}, and most likely is a
6556texinfo.texi(,6583) misspelling of it.  Even in languages which are not case sensitive, it
6557texinfo.texi(,6584) is confusing to a human reader to see identifiers spelled in different
6558texinfo.texi(,6585) ways.  Pick one spelling and always use that.  If you do not want to
6559texinfo.texi(,6586) start a sentence with a command name written all in lower case, you
6560texinfo.texi(,6587) should rearrange the sentence.
6561texinfo.texi(,6588)
6562texinfo.texi(,6589) In the printed manual, @code{@@code} causes @TeX{} to typeset the
6563texinfo.texi(,6590) argument in a typewriter face.  In the Info file, it causes the Info
6564texinfo.texi(,6591) formatting commands to use single quotation marks around the text.
6565texinfo.texi(,6592)
6566texinfo.texi(,6593) @need 700
6567texinfo.texi(,6594) For example,
6568texinfo.texi(,6595)
6569texinfo.texi(,6596) @example
6570texinfo.texi(,6597) The function returns @@code@{nil@}.
6571texinfo.texi(,6598) @end example
6572texinfo.texi(,6599)
6573texinfo.texi(,6600) @noindent
6574texinfo.texi(,6601) produces this in the printed manual:
6575texinfo.texi(,6602)
6576texinfo.texi(,6603) @quotation
6577texinfo.texi(,6604) The function returns @code{nil}.
6578texinfo.texi(,6605) @end quotation
6579texinfo.texi(,6606)
6580texinfo.texi(,6614)
6581texinfo.texi(,6615) Here are some cases for which it is preferable not to use @code{@@code}:
6582texinfo.texi(,6616)
6583texinfo.texi(,6617) @itemize @bullet
6584texinfo.texi(,6618) @item
6585texinfo.texi(,6619) For shell command names such as @command{ls} (use @code{@@command}).
6586texinfo.texi(,6620)
6587texinfo.texi(,6621) @item
6588texinfo.texi(,6622) For shell options such as @samp{-c} when such options stand alone (use
6589texinfo.texi(,6623) @code{@@option}).
6590texinfo.texi(,6624)
6591texinfo.texi(,6625) @item
6592texinfo.texi(,6626) Also, an entire shell command often looks better if written using
6593texinfo.texi(,6627) @code{@@samp} rather than @code{@@code}.  In this case, the rule is to
6594texinfo.texi(,6628) choose the more pleasing format.
6595texinfo.texi(,6629)
6596texinfo.texi(,6630) @item
6597texinfo.texi(,6631) For environment variable such as @env{TEXINPUTS} (use @code{@@env}).
6598texinfo.texi(,6632)
6599texinfo.texi(,6633) @item
6600texinfo.texi(,6634) For a string of characters shorter than a syntactic token.  For example,
6601texinfo.texi(,6635) if you are writing about @samp{goto-ch}, which is just a part of the
6602texinfo.texi(,6636) name for the @code{goto-char} Emacs Lisp function, you should use
6603texinfo.texi(,6637) @code{@@samp}.
6604texinfo.texi(,6638)
6605texinfo.texi(,6639) @item
6606texinfo.texi(,6640) In general, when writing about the characters used in a token; for
6607texinfo.texi(,6641) example, do not use @code{@@code} when you are explaining what letters
6608texinfo.texi(,6642) or printable symbols can be used in the names of functions.  (Use
6609texinfo.texi(,6643) @code{@@samp}.)  Also, you should not use @code{@@code} to mark text
6610texinfo.texi(,6644) that is considered input to programs unless the input is written in a
6611texinfo.texi(,6645) language that is like a programming language.  For example, you should
6612texinfo.texi(,6646) not use @code{@@code} for the keystroke commands of GNU Emacs (use
6613texinfo.texi(,6647) @code{@@kbd} instead) although you may use @code{@@code} for the names
6614texinfo.texi(,6648) of the Emacs Lisp functions that the keystroke commands invoke.
6615texinfo.texi(,6649)
6616texinfo.texi(,6650) @end itemize
6617texinfo.texi(,6651)
6618texinfo.texi(,6652) Since @code{@@command}, @code{@@option}, and @code{@@env} were
6619texinfo.texi(,6653) introduced relatively recently, it is acceptable to use @code{@@code} or
6620texinfo.texi(,6654) @code{@@samp} for command names, options, and environment variables.
6621texinfo.texi(,6655) The new commands allow you to express the markup more precisely, but
6622texinfo.texi(,6656) there is no real harm in using the older commands, and of course the
6623texinfo.texi(,6657) long-standing manuals do so.
6624texinfo.texi(,6658)
6625texinfo.texi(,6659)
6626texinfo.texi(,6660) @node kbd
6627texinfo.texi(,6661) @subsection @code{@@kbd}@{@var{keyboard-characters}@}
6628texinfo.texi(,6662) @findex kbd
6629texinfo.texi(,6663) @cindex Keyboard input
6630texinfo.texi(,6664)
6631texinfo.texi(,6665) Use the @code{@@kbd} command for characters of input to be typed by
6632texinfo.texi(,6666) users.  For example, to refer to the characters @kbd{M-a},
6633texinfo.texi(,6667) write@refill
6634texinfo.texi(,6668)
6635texinfo.texi(,6669) @example
6636texinfo.texi(,6670) @@kbd@{M-a@}
6637texinfo.texi(,6671) @end example
6638texinfo.texi(,6672)
6639texinfo.texi(,6673) @noindent
6640texinfo.texi(,6674) and to refer to the characters @kbd{M-x shell}, write@refill
6641texinfo.texi(,6675)
6642texinfo.texi(,6676) @example
6643texinfo.texi(,6677) @@kbd@{M-x shell@}
6644texinfo.texi(,6678) @end example
6645texinfo.texi(,6679)
6646texinfo.texi(,6680) @cindex user input
6647texinfo.texi(,6681) @cindex slanted typewriter font, for @code{@@kbd}
6648texinfo.texi(,6682) The @code{@@kbd} command has the same effect as @code{@@code} in Info,
6649texinfo.texi(,6683) but by default produces a different font (slanted typewriter instead of
6650texinfo.texi(,6684) normal typewriter) in the printed manual, so users can distinguish the
6651texinfo.texi(,6685) characters they are supposed to type from those the computer outputs.
6652texinfo.texi(,6686)
6653texinfo.texi(,6687) @findex kbdinputstyle
6654texinfo.texi(,6688) Since the usage of @code{@@kbd} varies from manual to manual, you can
6655texinfo.texi(,6689) control the font switching with the @code{@@kbdinputstyle} command.
6656texinfo.texi(,6690) This command has no effect on Info output.  Write this command at the
6657texinfo.texi(,6691) beginning of a line with a single word as an argument, one of the
6658texinfo.texi(,6692) following:
6659texinfo.texi(,6693) @vindex distinct@r{, arg to @@kbdinputstyle}
6660texinfo.texi(,6694) @vindex example@r{, arg to @@kbdinputstyle}
6661texinfo.texi(,6695) @vindex code@r{, arg to @@kbdinputstyle}
6662texinfo.texi(,6696) @table @samp
6663texinfo.texi(,6697) @item code
6664texinfo.texi(,6698) Always use the same font for @code{@@kbd} as @code{@@code}.
6665texinfo.texi(,6699) @item example
6666texinfo.texi(,6700) Use the distinguishing font for @code{@@kbd} only in @code{@@example}
6667texinfo.texi(,6701) and similar environments.
6668texinfo.texi(,6702) @item distinct
6669texinfo.texi(,6703) (the default) Always use the distinguishing font for @code{@@kbd}.
6670texinfo.texi(,6704) @end table
6671texinfo.texi(,6705)
6672texinfo.texi(,6706) You can embed another @@-command inside the braces of an @code{@@kbd}
6673texinfo.texi(,6707) command.  Here, for example, is the way to describe a command that
6674texinfo.texi(,6708) would be described more verbosely as ``press an @samp{r} and then
6675texinfo.texi(,6709) press the @key{RET} key'':@refill
6676texinfo.texi(,6710)
6677texinfo.texi(,6711) @example
6678texinfo.texi(,6712) @@kbd@{r @@key@{RET@}@}
6679texinfo.texi(,6713) @end example
6680texinfo.texi(,6714)
6681texinfo.texi(,6715) @noindent
6682texinfo.texi(,6716) This produces: @kbd{r @key{RET}}
6683texinfo.texi(,6717)
6684texinfo.texi(,6718) You also use the @code{@@kbd} command if you are spelling out the letters
6685texinfo.texi(,6719) you type; for example:@refill
6686texinfo.texi(,6720)
6687texinfo.texi(,6721) @example
6688texinfo.texi(,6722) To give the @@code@{logout@} command,
6689texinfo.texi(,6723) type the characters @@kbd@{l o g o u t @@key@{RET@}@}.
6690texinfo.texi(,6724) @end example
6691texinfo.texi(,6725)
6692texinfo.texi(,6726) @noindent
6693texinfo.texi(,6727) This produces:
6694texinfo.texi(,6728)
6695texinfo.texi(,6729) @quotation
6696texinfo.texi(,6730) To give the @code{logout} command,
6697texinfo.texi(,6731) type the characters @kbd{l o g o u t @key{RET}}.
6698texinfo.texi(,6732) @end quotation
6699texinfo.texi(,6733)
6700texinfo.texi(,6734) (Also, this example shows that you can add spaces for clarity.  If you
6701texinfo.texi(,6735) really want to mention a space character as one of the characters of
6702texinfo.texi(,6736) input, write @kbd{@@key@{SPC@}} for it.)@refill
6703texinfo.texi(,6737)
6704texinfo.texi(,6738)
6705texinfo.texi(,6739) @node key, samp, kbd, Indicating
6706texinfo.texi(,6740) @comment  node-name,  next,  previous,  up
6707texinfo.texi(,6741) @subsection @code{@@key}@{@var{key-name}@}
6708texinfo.texi(,6742) @findex key
6709texinfo.texi(,6743)
6710texinfo.texi(,6744) Use the @code{@@key} command for the conventional name for a key on a
6711texinfo.texi(,6745) keyboard, as in:@refill
6712texinfo.texi(,6746)
6713texinfo.texi(,6747) @example
6714texinfo.texi(,6748) @@key@{RET@}
6715texinfo.texi(,6749) @end example
6716texinfo.texi(,6750)
6717texinfo.texi(,6751) You can use the @code{@@key} command within the argument of an
6718texinfo.texi(,6752) @code{@@kbd} command when the sequence of characters to be typed
6719texinfo.texi(,6753) includes one or more keys that are described by name.@refill
6720texinfo.texi(,6754)
6721texinfo.texi(,6755) @need 700
6722texinfo.texi(,6756) For example, to produce @kbd{C-x @key{ESC}} you would type:@refill
6723texinfo.texi(,6757)
6724texinfo.texi(,6758) @example
6725texinfo.texi(,6759) @@kbd@{C-x @@key@{ESC@}@}
6726texinfo.texi(,6760) @end example
6727texinfo.texi(,6761)
6728texinfo.texi(,6762) Here is a list of the recommended names for keys:
6729texinfo.texi(,6763) @cindex Recommended names for keys
6730texinfo.texi(,6764) @cindex Keys, recommended names
6731texinfo.texi(,6765) @cindex Names recommended for keys
6732texinfo.texi(,6766) @cindex Abbreviations for keys
6733texinfo.texi(,6767)
6734texinfo.texi(,6768) @quotation
6735texinfo.texi(,6769) @table @t
6736texinfo.texi(,6770) @item SPC
6737texinfo.texi(,6771) Space
6738texinfo.texi(,6772) @item RET
6739texinfo.texi(,6773) Return
6740texinfo.texi(,6774) @item LFD
6741texinfo.texi(,6775) Linefeed (however, since most keyboards nowadays do not have a Linefeed key,
6742texinfo.texi(,6776) it might be better to call this character @kbd{C-j}.
6743texinfo.texi(,6777) @item TAB
6744texinfo.texi(,6778) Tab
6745texinfo.texi(,6779) @item BS
6746texinfo.texi(,6780) Backspace
6747texinfo.texi(,6781) @item ESC
6748texinfo.texi(,6782) Escape
6749texinfo.texi(,6783) @item DEL
6750texinfo.texi(,6784) Delete
6751texinfo.texi(,6785) @item SHIFT
6752texinfo.texi(,6786) Shift
6753texinfo.texi(,6787) @item CTRL
6754texinfo.texi(,6788) Control
6755texinfo.texi(,6789) @item META
6756texinfo.texi(,6790) Meta
6757texinfo.texi(,6791) @end table
6758texinfo.texi(,6792) @end quotation
6759texinfo.texi(,6793)
6760texinfo.texi(,6794) @cindex META key
6761texinfo.texi(,6795) There are subtleties to handling words like `meta' or `ctrl' that are
6762texinfo.texi(,6796) names of modifier keys.  When mentioning a character in which the
6763texinfo.texi(,6797) modifier key is used, such as @kbd{Meta-a}, use the @code{@@kbd} command
6764texinfo.texi(,6798) alone; do not use the @code{@@key} command; but when you are referring
6765texinfo.texi(,6799) to the modifier key in isolation, use the @code{@@key} command.  For
6766texinfo.texi(,6800) example, write @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and
6767texinfo.texi(,6801) @samp{@@key@{META@}} to produce @key{META}.
6768texinfo.texi(,6802)
6769texinfo.texi(,6803) @c I don't think this is a good explanation.
6770texinfo.texi(,6804) @c I think it will puzzle readers more than it clarifies matters.  -- rms.
6771texinfo.texi(,6805) @c In other words, use @code{@@kbd} for what you do, and use @code{@@key}
6772texinfo.texi(,6806) @c for what you talk about: ``Press @code{@@kbd@{M-a@}} to move point to
6773texinfo.texi(,6807) @c the beginning of the sentence.  The @code{@@key@{META@}} key is often in
6774texinfo.texi(,6808) @c the lower left of the keyboard.''@refill
6775texinfo.texi(,6809)
6776texinfo.texi(,6810) @node samp
6777texinfo.texi(,6811) @subsection @code{@@samp}@{@var{text}@}
6778texinfo.texi(,6812) @findex samp
6779texinfo.texi(,6813)
6780texinfo.texi(,6814) Use the @code{@@samp} command to indicate text that is a literal example
6781texinfo.texi(,6815) or `sample' of a sequence of characters in a file, string, pattern, etc.
6782texinfo.texi(,6816) Enclose the text in braces.  The argument appears within single
6783texinfo.texi(,6817) quotation marks in both the Info file and the printed manual; in
6784texinfo.texi(,6818) addition, it is printed in a fixed-width font.@refill
6785texinfo.texi(,6819)
6786texinfo.texi(,6820) @example
6787texinfo.texi(,6821) To match @@samp@{foo@} at the end of the line,
6788texinfo.texi(,6822) use the regexp @@samp@{foo$@}.
6789texinfo.texi(,6823) @end example
6790texinfo.texi(,6824)
6791texinfo.texi(,6825) @noindent
6792texinfo.texi(,6826) produces
6793texinfo.texi(,6827)
6794texinfo.texi(,6828) @quotation
6795texinfo.texi(,6829) To match @samp{foo} at the end of the line, use the regexp
6796texinfo.texi(,6830) @samp{foo$}.@refill
6797texinfo.texi(,6831) @end quotation
6798texinfo.texi(,6832)
6799texinfo.texi(,6833) Any time you are referring to single characters, you should use
6800texinfo.texi(,6834) @code{@@samp} unless @code{@@kbd} or @code{@@key} is more appropriate.
6801texinfo.texi(,6835) Also, you may use @code{@@samp} for entire statements in C and for entire
6802texinfo.texi(,6836) shell commands---in this case, @code{@@samp} often looks better than
6803texinfo.texi(,6837) @code{@@code}.  Basically, @code{@@samp} is a catchall for whatever is
6804texinfo.texi(,6838) not covered by @code{@@code}, @code{@@kbd}, or @code{@@key}.@refill
6805texinfo.texi(,6839)
6806texinfo.texi(,6840) Only include punctuation marks within braces if they are part of the
6807texinfo.texi(,6841) string you are specifying.  Write punctuation marks outside the braces
6808texinfo.texi(,6842) if those punctuation marks are part of the English text that surrounds
6809texinfo.texi(,6843) the string.  In the following sentence, for example, the commas and
6810texinfo.texi(,6844) period are outside of the braces:@refill
6811texinfo.texi(,6845)
6812texinfo.texi(,6846) @example
6813texinfo.texi(,6847) @group
6814texinfo.texi(,6848) In English, the vowels are @@samp@{a@}, @@samp@{e@},
6815texinfo.texi(,6849) @@samp@{i@}, @@samp@{o@}, @@samp@{u@}, and sometimes
6816texinfo.texi(,6850) @@samp@{y@}.
6817texinfo.texi(,6851) @end group
6818texinfo.texi(,6852) @end example
6819texinfo.texi(,6853)
6820texinfo.texi(,6854) @noindent
6821texinfo.texi(,6855) This produces:
6822texinfo.texi(,6856)
6823texinfo.texi(,6857) @quotation
6824texinfo.texi(,6858) In English, the vowels are @samp{a}, @samp{e},
6825texinfo.texi(,6859) @samp{i}, @samp{o}, @samp{u},  and sometimes
6826texinfo.texi(,6860) @samp{y}.
6827texinfo.texi(,6861) @end quotation
6828texinfo.texi(,6862)
6829texinfo.texi(,6863)
6830texinfo.texi(,6864) @node verb
6831texinfo.texi(,6865) @subsection @code{@@verb}@{<char>@var{text}<char>@}
6832texinfo.texi(,6866) @findex verb
6833texinfo.texi(,6867) @cindex Verbatim in-line text
6834texinfo.texi(,6868)
6835texinfo.texi(,6869) @cindex Delimiter character, for verbatim
6836texinfo.texi(,6870) Use the @code{@@verb} command to print a verbatim sequence of
6837texinfo.texi(,6871) characters.
6838texinfo.texi(,6872)
6839texinfo.texi(,6873) Like La@TeX{}'s @code{\verb} command, the verbatim text can be quoted using
6840texinfo.texi(,6874) any unique delimiter character.  Enclose the verbatim text, including the
6841texinfo.texi(,6875) delimiters, in braces.  Text is printed in a fixed-width font:
6842texinfo.texi(,6876)
6843texinfo.texi(,6877) @example
6844texinfo.texi(,6878) How many @@verb@{|@@|@}-escapes does one need to print this
6845texinfo.texi(,6879) @@verb@{.@@a @@b @@c.@} string or @@verb@{+@@'e@?`@!`@{@}\+@} this?
6846texinfo.texi(,6880) @end example
6847texinfo.texi(,6881)
6848texinfo.texi(,6882) @noindent
6849texinfo.texi(,6883) produces
6850texinfo.texi(,6884)
6851texinfo.texi(,6885) @example
6852texinfo.texi(,6886) How many @verb{|@ |}-escapes does one need to print this
6853texinfo.texi(,6887) @verb{.@a @b @c.} string or these @verb{+@'e?`{}!`\+} this?
6854texinfo.texi(,6888) @end example
6855texinfo.texi(,6889)
6856texinfo.texi(,6890) This is in contrast to @code{@@samp} (see the previous
6857texinfo.texi(,6891) section), whose argument is normal Texinfo text, where the characters
6858texinfo.texi(,6892) @code{@@@{@}} are special; with @code{@@verb}, nothing is special except
6859texinfo.texi(,6893) the delimiter character you choose.
6860texinfo.texi(,6894)
6861texinfo.texi(,6895)
6862texinfo.texi(,6896) @node var
6863texinfo.texi(,6897) @subsection @code{@@var}@{@var{metasyntactic-variable}@}
6864texinfo.texi(,6898) @findex var
6865texinfo.texi(,6899)
6866texinfo.texi(,6900) Use the @code{@@var} command to indicate metasyntactic variables.  A
6867texinfo.texi(,6901) @dfn{metasyntactic variable} is something that stands for another piece of
6868texinfo.texi(,6902) text.  For example, you should use a metasyntactic variable in the
6869texinfo.texi(,6903) documentation of a function to describe the arguments that are passed
6870texinfo.texi(,6904) to that function.@refill
6871texinfo.texi(,6905)
6872texinfo.texi(,6906) Do not use @code{@@var} for the names of particular variables in
6873texinfo.texi(,6907) programming languages.  These are specific names from a program, so
6874texinfo.texi(,6908) @code{@@code} is correct for them (@pxref{code}).  For example, the
6875texinfo.texi(,6909) Emacs Lisp variable @code{texinfo-tex-command} is not a metasyntactic
6876texinfo.texi(,6910) variable; it is properly formatted using @code{@@code}.
6877texinfo.texi(,6911)
6878texinfo.texi(,6912) Do not use @code{@@var} for environment variables either; @code{@@env}
6879texinfo.texi(,6913) is correct for them (see the next section).
6880texinfo.texi(,6914)
6881texinfo.texi(,6915) The effect of @code{@@var} in the Info file is to change the case of the
6882texinfo.texi(,6916) argument to all upper case.  In the printed manual and HTML output, the
6883texinfo.texi(,6917) argument is printed in slanted type.
6884texinfo.texi(,6918)
6885texinfo.texi(,6919) @need 700
6886texinfo.texi(,6920) For example,
6887texinfo.texi(,6921)
6888texinfo.texi(,6922) @example
6889texinfo.texi(,6923) To delete file @@var@{filename@},
6890texinfo.texi(,6924) type @@samp@{rm @@var@{filename@}@}.
6891texinfo.texi(,6925) @end example
6892texinfo.texi(,6926)
6893texinfo.texi(,6927) @noindent
6894texinfo.texi(,6928) produces
6895texinfo.texi(,6929)
6896texinfo.texi(,6930) @quotation
6897texinfo.texi(,6931) To delete file @var{filename}, type @samp{rm @var{filename}}.
6898texinfo.texi(,6932) @end quotation
6899texinfo.texi(,6933)
6900texinfo.texi(,6934) @noindent
6901texinfo.texi(,6935) (Note that @code{@@var} may appear inside @code{@@code},
6902texinfo.texi(,6936) @code{@@samp}, @code{@@file}, etc.)@refill
6903texinfo.texi(,6937)
6904texinfo.texi(,6938) Write a metasyntactic variable all in lower case without spaces, and
6905texinfo.texi(,6939) use hyphens to make it more readable.  Thus, the Texinfo source for
6906texinfo.texi(,6940) the illustration of how to begin a Texinfo manual looks like
6907texinfo.texi(,6941) this:@refill
6908texinfo.texi(,6942)
6909texinfo.texi(,6943) @example
6910texinfo.texi(,6944) @group
6911texinfo.texi(,6945) \input texinfo
6912texinfo.texi(,6946) @@@@setfilename @@var@{info-file-name@}
6913texinfo.texi(,6947) @@@@settitle @@var@{name-of-manual@}
6914texinfo.texi(,6948) @end group
6915texinfo.texi(,6949) @end example
6916texinfo.texi(,6950)
6917texinfo.texi(,6951) @noindent
6918texinfo.texi(,6952) This produces:
6919texinfo.texi(,6953)
6920texinfo.texi(,6954) @example
6921texinfo.texi(,6955) @group
6922texinfo.texi(,6956) \input texinfo
6923texinfo.texi(,6957) @@setfilename @var{info-file-name}
6924texinfo.texi(,6958) @@settitle @var{name-of-manual}
6925texinfo.texi(,6959) @end group
6926texinfo.texi(,6960) @end example
6927texinfo.texi(,6961)
6928texinfo.texi(,6962) In some documentation styles, metasyntactic variables are shown with
6929texinfo.texi(,6963) angle brackets, for example:@refill
6930texinfo.texi(,6964)
6931texinfo.texi(,6965) @example
6932texinfo.texi(,6966) @dots{}, type rm <filename>
6933texinfo.texi(,6967) @end example
6934texinfo.texi(,6968)
6935texinfo.texi(,6969) @noindent
6936texinfo.texi(,6970) However, that is not the style that Texinfo uses.  (You can, of
6937texinfo.texi(,6971) course, modify the sources to @file{texinfo.tex} and the Info formatting commands
6938texinfo.texi(,6972) to output the @code{<@dots{}>} format if you wish.)@refill
6939texinfo.texi(,6973)
6940texinfo.texi(,6974)
6941texinfo.texi(,6975) @node env
6942texinfo.texi(,6976) @subsection @code{@@env}@{@var{environment-variable}@}
6943texinfo.texi(,6977) @findex env
6944texinfo.texi(,6978)
6945texinfo.texi(,6979) Use the @code{@@env} command to indicate environment variables, as used
6946texinfo.texi(,6980) by many operating systems, including GNU.  Do not use it for
6947texinfo.texi(,6981) metasyntactic variables; use @code{@@var} instead (see the previous
6948texinfo.texi(,6982) section).
6949texinfo.texi(,6983)
6950texinfo.texi(,6984) @code{@@env} is equivalent to @code{@@code} in its effects.
6951texinfo.texi(,6985) For example:
6952texinfo.texi(,6986)
6953texinfo.texi(,6987) @example
6954texinfo.texi(,6988) The @@env@{PATH@} environment variable @dots{}
6955texinfo.texi(,6989) @end example
6956texinfo.texi(,6990) @noindent produces
6957texinfo.texi(,6991) @quotation
6958texinfo.texi(,6992) The @env{PATH} environment variable @dots{}
6959texinfo.texi(,6993) @end quotation
6960texinfo.texi(,6994)
6961texinfo.texi(,6995)
6962texinfo.texi(,6996) @node file
6963texinfo.texi(,6997) @subsection @code{@@file}@{@var{file-name}@}
6964texinfo.texi(,6998) @findex file
6965texinfo.texi(,6999)
6966texinfo.texi(,7000) Use the @code{@@file} command to indicate text that is the name of a
6967texinfo.texi(,7001) file, buffer, or directory, or is the name of a node in Info.  You can
6968texinfo.texi(,7002) also use the command for file name suffixes.  Do not use @code{@@file}
6969texinfo.texi(,7003) for symbols in a programming language; use @code{@@code}.
6970texinfo.texi(,7004)
6971texinfo.texi(,7005) Currently, @code{@@file} is equivalent to @code{@@samp} in its effects.
6972texinfo.texi(,7006) For example,@refill
6973texinfo.texi(,7007)
6974texinfo.texi(,7008) @example
6975texinfo.texi(,7009) The @@file@{.el@} files are in
6976texinfo.texi(,7010) the @@file@{/usr/local/emacs/lisp@} directory.
6977texinfo.texi(,7011) @end example
6978texinfo.texi(,7012)
6979texinfo.texi(,7013) @noindent
6980texinfo.texi(,7014) produces
6981texinfo.texi(,7015)
6982texinfo.texi(,7016) @quotation
6983texinfo.texi(,7017) The @file{.el} files are in
6984texinfo.texi(,7018) the @file{/usr/local/emacs/lisp} directory.
6985texinfo.texi(,7019) @end quotation
6986texinfo.texi(,7020)
6987texinfo.texi(,7021)
6988texinfo.texi(,7022) @node command
6989texinfo.texi(,7023) @subsection @code{@@command}@{@var{command-name}@}
6990texinfo.texi(,7024) @findex command
6991texinfo.texi(,7025) @cindex Command names, indicating
6992texinfo.texi(,7026) @cindex Program names, indicating
6993texinfo.texi(,7027)
6994texinfo.texi(,7028) Use the @code{@@command} command to indicate command names, such as
6995texinfo.texi(,7029) @command{ls} or @command{cc}.
6996texinfo.texi(,7030)
6997texinfo.texi(,7031) @code{@@command} is equivalent to @code{@@code} in its effects.
6998texinfo.texi(,7032) For example:
6999texinfo.texi(,7033)
7000texinfo.texi(,7034) @example
7001texinfo.texi(,7035) The command @@command@{ls@} lists directory contents.
7002texinfo.texi(,7036) @end example
7003texinfo.texi(,7037) @noindent produces
7004texinfo.texi(,7038) @quotation
7005texinfo.texi(,7039) The command @command{ls} lists directory contents.
7006texinfo.texi(,7040) @end quotation
7007texinfo.texi(,7041)
7008texinfo.texi(,7042) You should write the name of a program in the ordinary text font, rather
7009texinfo.texi(,7043) than using @code{@@command}, if you regard it as a new English word,
7010texinfo.texi(,7044) such as `Emacs' or `Bison'.
7011texinfo.texi(,7045)
7012texinfo.texi(,7046) When writing an entire shell command invocation, as in @samp{ls -l},
7013texinfo.texi(,7047) you should use either @code{@@samp} or @code{@@code} at your discretion.
7014texinfo.texi(,7048)
7015texinfo.texi(,7049)
7016texinfo.texi(,7050) @node option
7017texinfo.texi(,7051) @subsection @code{@@option}@{@var{option-name}@}
7018texinfo.texi(,7052) @findex option
7019texinfo.texi(,7053)
7020texinfo.texi(,7054) Use the @code{@@option} command to indicate a command-line option; for
7021texinfo.texi(,7055) example, @option{-l} or @option{--version} or
7022texinfo.texi(,7056) @option{--output=@var{filename}}.
7023texinfo.texi(,7057)
7024texinfo.texi(,7058) @code{@@option} is equivalent to @code{@@samp} in its effects.
7025texinfo.texi(,7059) For example:
7026texinfo.texi(,7060)
7027texinfo.texi(,7061) @example
7028texinfo.texi(,7062) The option @@option@{-l@} produces a long listing.
7029texinfo.texi(,7063) @end example
7030texinfo.texi(,7064) @noindent produces
7031texinfo.texi(,7065) @quotation
7032texinfo.texi(,7066) The option @option{-l} produces a long listing.
7033texinfo.texi(,7067) @end quotation
7034texinfo.texi(,7068)
7035texinfo.texi(,7069) In tables, putting options inside @code{@@code} produces a
7036texinfo.texi(,7070) more pleasing effect.
7037texinfo.texi(,7071)
7038texinfo.texi(,7072) @node dfn
7039texinfo.texi(,7073) @comment  node-name,  next,  previous,  up
7040texinfo.texi(,7074) @subsection @code{@@dfn}@{@var{term}@}
7041texinfo.texi(,7075) @findex dfn
7042texinfo.texi(,7076)
7043texinfo.texi(,7077) Use the @code{@@dfn} command to identify the introductory or defining
7044texinfo.texi(,7078) use of a technical term.  Use the command only in passages whose
7045texinfo.texi(,7079) purpose is to introduce a term which will be used again or which the
7046texinfo.texi(,7080) reader ought to know.  Mere passing mention of a term for the first
7047texinfo.texi(,7081) time does not deserve @code{@@dfn}.  The command generates italics in
7048texinfo.texi(,7082) the printed manual, and double quotation marks in the Info file.  For
7049texinfo.texi(,7083) example:@refill
7050texinfo.texi(,7084)
7051texinfo.texi(,7085) @example
7052texinfo.texi(,7086) Getting rid of a file is called @@dfn@{deleting@} it.
7053texinfo.texi(,7087) @end example
7054texinfo.texi(,7088)
7055texinfo.texi(,7089) @noindent
7056texinfo.texi(,7090) produces
7057texinfo.texi(,7091)
7058texinfo.texi(,7092) @quotation
7059texinfo.texi(,7093) Getting rid of a file is called @dfn{deleting} it.
7060texinfo.texi(,7094) @end quotation
7061texinfo.texi(,7095)
7062texinfo.texi(,7096) As a general rule, a sentence containing the defining occurrence of a
7063texinfo.texi(,7097) term should be a definition of the term.  The sentence does not need
7064texinfo.texi(,7098) to say explicitly that it is a definition, but it should contain the
7065texinfo.texi(,7099) information of a definition---it should make the meaning clear.
7066texinfo.texi(,7100)
7067texinfo.texi(,7101) @node cite
7068texinfo.texi(,7102) @subsection @code{@@cite}@{@var{reference}@}
7069texinfo.texi(,7103) @findex cite
7070texinfo.texi(,7104)
7071texinfo.texi(,7105) Use the @code{@@cite} command for the name of a book that lacks a
7072texinfo.texi(,7106) companion Info file.  The command produces italics in the printed
7073texinfo.texi(,7107) manual, and quotation marks in the Info file.
7074texinfo.texi(,7108)
7075texinfo.texi(,7109) If a book is written in Texinfo, it is better to use a cross reference
7076texinfo.texi(,7110) command since a reader can easily follow such a reference in Info.
7077texinfo.texi(,7111) @xref{xref, , @code{@@xref}}.
7078texinfo.texi(,7112)
7079texinfo.texi(,7113)
7080texinfo.texi(,7162)
7081texinfo.texi(,7163)
7082texinfo.texi(,7164) @node acronym
7083texinfo.texi(,7165) @subsection @code{@@acronym}@{@var{acronym}@}
7084texinfo.texi(,7166) @findex acronym
7085texinfo.texi(,7167)
7086texinfo.texi(,7168) @cindex NASA, as acronym
7087texinfo.texi(,7169) @cindex F.B.I., as acronym
7088texinfo.texi(,7170) @cindex Abbreviations, tagging
7089texinfo.texi(,7171) @cindex Acronyms, tagging
7090texinfo.texi(,7172) Use the @code{@@acronym} command for abbreviations written in all
7091texinfo.texi(,7173) capital letters, such as `@acronym{NASA}'.  The abbreviation is given as
7092texinfo.texi(,7174) the single argument in braces, as in @samp{@@acronym@{NASA@}}.  As
7093texinfo.texi(,7175) a matter of style, or for particular abbreviations, you may prefer to
7094texinfo.texi(,7176) use periods, as in @samp{@@acronym@{F.B.I.@}}.
7095texinfo.texi(,7177)
7096texinfo.texi(,7178) In @TeX{} and HTML, the argument is printed in a slightly smaller font
7097texinfo.texi(,7179) size.  In Info or plain text output, this command changes nothing.
7098texinfo.texi(,7180)
7099texinfo.texi(,7181)
7100texinfo.texi(,7182) @node url
7101texinfo.texi(,7183) @subsection @code{@@url}@{@var{uniform-resource-locator}@}
7102texinfo.texi(,7184) @findex url
7103texinfo.texi(,7185) @cindex Uniform resource locator, indicating
7104texinfo.texi(,7186) @cindex URL, indicating
7105texinfo.texi(,7187)
7106texinfo.texi(,7188) Use the @code{@@url} command to indicate a uniform resource locator on
7107texinfo.texi(,7189) the World Wide Web.  This is analogous to @code{@@file}, @code{@@var},
7108texinfo.texi(,7190) etc., and is purely for markup purposes.  It does not produce a link you
7109texinfo.texi(,7191) can follow in HTML output (use the @code{@@uref} command for that,
7110texinfo.texi(,7192) @pxref{uref,, @code{@@uref}}).  It is useful for url's which do
7111texinfo.texi(,7193) not actually exist.  For example:
7112texinfo.texi(,7194)
7113texinfo.texi(,7195) @c Two lines because one is too long for smallbook format.
7114texinfo.texi(,7196) @example
7115texinfo.texi(,7197) For example, the url might be @@url@{http://example.org/path@}.
7116texinfo.texi(,7198) @end example
7117texinfo.texi(,7199)
7118texinfo.texi(,7200) @noindent which produces:
7119texinfo.texi(,7201)
7120texinfo.texi(,7202) @display
7121texinfo.texi(,7203) For example, the url might be @url{http://example.org/path}.
7122texinfo.texi(,7204) @end display
7123texinfo.texi(,7205)
7124texinfo.texi(,7206)
7125texinfo.texi(,7207) @node email
7126texinfo.texi(,7208) @subsection @code{@@email}@{@var{email-address}[, @var{displayed-text}]@}
7127texinfo.texi(,7209) @findex email
7128texinfo.texi(,7210)
7129texinfo.texi(,7211) Use the @code{@@email} command to indicate an electronic mail address.
7130texinfo.texi(,7212) It takes one mandatory argument, the address, and one optional argument, the
7131texinfo.texi(,7213) text to display (the default is the address itself).
7132texinfo.texi(,7214)
7133texinfo.texi(,7215) @cindex mailto link
7134texinfo.texi(,7216) In Info and @TeX{}, the address is shown in angle brackets, preceded by
7135texinfo.texi(,7217) the text to display if any.  In HTML output, @code{@@email} produces a
7136texinfo.texi(,7218) @samp{mailto} link that usually brings up a mail composition window.
7137texinfo.texi(,7219) For example:
7138texinfo.texi(,7220)
7139texinfo.texi(,7221) @example
7140texinfo.texi(,7222) Send bug reports to @@email@{bug-texinfo@@@@gnu.org@},
7141texinfo.texi(,7223) suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}.
7142texinfo.texi(,7224) @end example
7143texinfo.texi(,7225) @noindent produces
7144texinfo.texi(,7226) @display
7145texinfo.texi(,7227) Send bug reports to @email{bug-texinfo@@gnu.org},
7146texinfo.texi(,7228) suggestions to the @email{bug-texinfo@@gnu.org, same place}.
7147texinfo.texi(,7229) @end display
7148texinfo.texi(,7230)
7149texinfo.texi(,7231)
7150texinfo.texi(,7232) @node Emphasis
7151texinfo.texi(,7233) @comment node-name,  next,  previous,  up
7152texinfo.texi(,7234) @section Emphasizing Text
7153texinfo.texi(,7235) @cindex Emphasizing text
7154texinfo.texi(,7236)
7155texinfo.texi(,7237) Usually, Texinfo changes the font to mark words in the text according to
7156texinfo.texi(,7238) what category the words belong to; an example is the @code{@@code} command.
7157texinfo.texi(,7239) Most often, this is the best way to mark words.
7158texinfo.texi(,7240) However, sometimes you will want to emphasize text without indicating a
7159texinfo.texi(,7241) category.  Texinfo has two commands to do this.  Also, Texinfo has
7160texinfo.texi(,7242) several commands that specify the font in which @TeX{} will typeset
7161texinfo.texi(,7243) text.  These commands have no effect on Info and only one of them,
7162texinfo.texi(,7244) the @code{@@r} command, has any regular use.@refill
7163texinfo.texi(,7245)
7164texinfo.texi(,7246) @menu
7165texinfo.texi(,7247) * emph & strong::               How to emphasize text in Texinfo.
7166texinfo.texi(,7248) * Smallcaps::                   How to use the small caps font.
7167texinfo.texi(,7249) * Fonts::                       Various font commands for printed output.
7168texinfo.texi(,7250) @end menu
7169texinfo.texi(,7251)
7170texinfo.texi(,7252) @node emph & strong
7171texinfo.texi(,7253) @subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@}
7172texinfo.texi(,7254) @cindex Emphasizing text, font for
7173texinfo.texi(,7255) @findex emph
7174texinfo.texi(,7256) @findex strong
7175texinfo.texi(,7257)
7176texinfo.texi(,7258) The @code{@@emph} and @code{@@strong} commands are for emphasis;
7177texinfo.texi(,7259) @code{@@strong} is stronger.  In printed output, @code{@@emph} produces
7178texinfo.texi(,7260) @emph{italics} and @code{@@strong} produces @strong{bold}.
7179texinfo.texi(,7261)
7180texinfo.texi(,7262) @need 800
7181texinfo.texi(,7263) For example,
7182texinfo.texi(,7264)
7183texinfo.texi(,7265) @example
7184texinfo.texi(,7266) @group
7185texinfo.texi(,7267) @@quotation
7186texinfo.texi(,7268) @@strong@{Caution:@} @@samp@{rm * .[^.]*@} removes @@emph@{all@}
7187texinfo.texi(,7269) files in the directory.
7188texinfo.texi(,7270) @@end quotation
7189texinfo.texi(,7271) @end group
7190texinfo.texi(,7272) @end example
7191texinfo.texi(,7273)
7192texinfo.texi(,7287) @noindent
7193texinfo.texi(,7288) produces:
7194texinfo.texi(,7290)
7195texinfo.texi(,7291) @example
7196texinfo.texi(,7292)      *Caution*: `rm * .[^.]*' removes _all_
7197texinfo.texi(,7293)      files in the directory.
7198texinfo.texi(,7294) @end example
7199texinfo.texi(,7295)
7200texinfo.texi(,7296) The @code{@@strong} command is seldom used except to mark what is, in
7201texinfo.texi(,7297) effect, a typographical element, such as the word `Caution' in the
7202texinfo.texi(,7298) preceding example.
7203texinfo.texi(,7299)
7204texinfo.texi(,7300) In the Info output, @code{@@emph} surrounds the text with underscores
7205texinfo.texi(,7301) (@samp{_}), and @code{@@strong} puts asterisks around the text.
7206texinfo.texi(,7302)
7207texinfo.texi(,7303) @quotation
7208texinfo.texi(,7304) @strong{Caution:} Do not use @code{@@strong} with the word @samp{Note};
7209texinfo.texi(,7305) Info will mistake the combination for a cross reference.  Use a phrase
7210texinfo.texi(,7306) such as @strong{Please note} or @strong{Caution} instead.
7211texinfo.texi(,7307) @end quotation
7212texinfo.texi(,7308)
7213texinfo.texi(,7309)
7214texinfo.texi(,7310) @node Smallcaps
7215texinfo.texi(,7311) @subsection @code{@@sc}@{@var{text}@}: The Small Caps Font
7216texinfo.texi(,7312) @cindex Small caps font
7217texinfo.texi(,7313) @findex sc @r{(small caps font)}
7218texinfo.texi(,7314)
7219texinfo.texi(,7315) Use the @samp{@@sc} command to set text in the printed and the HTML
7220texinfo.texi(,7316) output in @sc{a small caps font} and set text in the Info file in upper
7221texinfo.texi(,7317) case letters.  Write the text you want to be in small caps (where
7222texinfo.texi(,7318) possible) between braces in lower case, like this:
7223texinfo.texi(,7319)
7224texinfo.texi(,7320) @example
7225texinfo.texi(,7321) The @@sc@{acm@} and @@sc@{ieee@} are technical societies.
7226texinfo.texi(,7322) @end example
7227texinfo.texi(,7323)
7228texinfo.texi(,7324) @noindent
7229texinfo.texi(,7325) This produces:
7230texinfo.texi(,7326)
7231texinfo.texi(,7327) @display
7232texinfo.texi(,7328) The @sc{acm} and @sc{ieee} are technical societies.
7233texinfo.texi(,7329) @end display
7234texinfo.texi(,7330)
7235texinfo.texi(,7331) @TeX{} typesets the small caps font in a manner that prevents the
7236texinfo.texi(,7332) letters from `jumping out at you on the page'.  This makes small caps
7237texinfo.texi(,7333) text easier to read than text in all upper case---but it's usually
7238texinfo.texi(,7334) better to use regular mixed case anyway.  The Info formatting commands
7239texinfo.texi(,7335) set all small caps text in upper case.  In HTML, the text is upper-cased
7240texinfo.texi(,7336) and a smaller font is used to render it.
7241texinfo.texi(,7337)
7242texinfo.texi(,7338) If the text between the braces of an @code{@@sc} command is uppercase,
7243texinfo.texi(,7339) @TeX{} typesets in FULL-SIZE CAPITALS.  Use full-size capitals
7244texinfo.texi(,7340) sparingly, if ever, and since it's redundant to mark all-uppercase text
7245texinfo.texi(,7341) with @code{@@sc}, @command{makeinfo} warns about such usage.
7246texinfo.texi(,7342)
7247texinfo.texi(,7343) You may also use the small caps font for a jargon word such as
7248texinfo.texi(,7344) @sc{ato} (a @sc{nasa} word meaning `abort to orbit').
7249texinfo.texi(,7345)
7250texinfo.texi(,7346) There are subtleties to using the small caps font with a jargon word
7251texinfo.texi(,7347) such as @sc{cdr}, a word used in Lisp programming.  In this case, you
7252texinfo.texi(,7348) should use the small caps font when the word refers to the second and
7253texinfo.texi(,7349) subsequent elements of a list (the @sc{cdr} of the list), but you
7254texinfo.texi(,7350) should use @samp{@@code} when the word refers to the Lisp function of
7255texinfo.texi(,7351) the same spelling.
7256texinfo.texi(,7352)
7257texinfo.texi(,7353)
7258texinfo.texi(,7354) @node Fonts
7259texinfo.texi(,7355) @subsection Fonts for Printing, Not Info
7260texinfo.texi(,7356) @cindex Fonts for printing, not for Info
7261texinfo.texi(,7357) @findex i @r{(italic font)}
7262texinfo.texi(,7358) @findex b @r{(bold font)}
7263texinfo.texi(,7359) @findex t @r{(typewriter font)}
7264texinfo.texi(,7360) @findex r @r{(Roman font)}
7265texinfo.texi(,7361)
7266texinfo.texi(,7362) Texinfo provides four font commands that specify font changes in the
7267texinfo.texi(,7363) printed manual but have no effect in the Info file.  @code{@@i}
7268texinfo.texi(,7364) requests @i{italic} font (in some versions of @TeX{}, a slanted font
7269texinfo.texi(,7365) is used), @code{@@b} requests @b{bold} face, @code{@@t} requests the
7270texinfo.texi(,7366) @t{fixed-width}, typewriter-style font used by @code{@@code}, and @code{@@r} requests a
7271texinfo.texi(,7367) @r{roman} font, which is the usual font in which text is printed.  All
7272texinfo.texi(,7368) four commands apply to an argument that follows, surrounded by
7273texinfo.texi(,7369) braces.@refill
7274texinfo.texi(,7370)
7275texinfo.texi(,7371) Only the @code{@@r} command has much use: in example programs, you
7276texinfo.texi(,7372) can use the @code{@@r} command to convert code comments from the
7277texinfo.texi(,7373) fixed-width font to a roman font.  This looks better in printed
7278texinfo.texi(,7374) output.@refill
7279texinfo.texi(,7375)
7280texinfo.texi(,7376) @need 700
7281texinfo.texi(,7377) For example,
7282texinfo.texi(,7378)
7283texinfo.texi(,7379) @example
7284texinfo.texi(,7380) @group
7285texinfo.texi(,7381) @@lisp
7286texinfo.texi(,7382) (+ 2 2)    ; @@r@{Add two plus two.@}
7287texinfo.texi(,7383) @@end lisp
7288texinfo.texi(,7384) @end group
7289texinfo.texi(,7385) @end example
7290texinfo.texi(,7386)
7291texinfo.texi(,7387) @noindent
7292texinfo.texi(,7388) produces
7293texinfo.texi(,7389)
7294texinfo.texi(,7390) @lisp
7295texinfo.texi(,7391) (+ 2 2)    ; @r{Add two plus two.}
7296texinfo.texi(,7392) @end lisp
7297texinfo.texi(,7393)
7298texinfo.texi(,7394) If possible, you should avoid using the other three font commands.  If
7299texinfo.texi(,7395) you need to use one, it probably indicates a gap in the Texinfo
7300texinfo.texi(,7396) language.
7301texinfo.texi(,7397)
7302texinfo.texi(,7398)
7303texinfo.texi(,7399) @node Quotations and Examples
7304texinfo.texi(,7400) @chapter Quotations and Examples
7305texinfo.texi(,7401)
7306texinfo.texi(,7402) Quotations and examples are blocks of text consisting of one or more
7307texinfo.texi(,7403) whole paragraphs that are set off from the bulk of the text and
7308texinfo.texi(,7404) treated differently.  They are usually indented.@refill
7309texinfo.texi(,7405)
7310texinfo.texi(,7406) In Texinfo, you always begin a quotation or example by writing an
7311texinfo.texi(,7407) @@-command at the beginning of a line by itself, and end it by writing
7312texinfo.texi(,7408) an @code{@@end} command that is also at the beginning of a line by
7313texinfo.texi(,7409) itself.  For instance, you begin an example by writing @code{@@example}
7314texinfo.texi(,7410) by itself at the beginning of a line and end the example by writing
7315texinfo.texi(,7411) @code{@@end example} on a line by itself, at the beginning of that
7316texinfo.texi(,7412) line.
7317texinfo.texi(,7413) @findex end
7318texinfo.texi(,7414)
7319texinfo.texi(,7415) @menu
7320texinfo.texi(,7416) * Block Enclosing Commands::    Different constructs for different purposes.
7321texinfo.texi(,7417) * quotation::                   Writing a quotation.
7322texinfo.texi(,7418) * example::                     Writing an example in a fixed-width font.
7323texinfo.texi(,7419) * verbatim::                    Writing a verbatim example.
7324texinfo.texi(,7420) * verbatiminclude::             Including a file verbatim.
7325texinfo.texi(,7421) * lisp::                        Illustrating Lisp code.
7326texinfo.texi(,7422) * small::                       Forms for @code{@@smallbook}.
7327texinfo.texi(,7423) * display::                     Writing an example in the current font.
7328texinfo.texi(,7424) * format::                      Writing an example without narrowed margins.
7329texinfo.texi(,7425) * exdent::                      Undo indentation on a line.
7330texinfo.texi(,7426) * flushleft & flushright::      Pushing text flush left or flush right.
7331texinfo.texi(,7427) * noindent::                    Preventing paragraph indentation.
7332texinfo.texi(,7428) * cartouche::                   Drawing rounded rectangles around examples.
7333texinfo.texi(,7429) @end menu
7334texinfo.texi(,7430)
7335texinfo.texi(,7431)
7336texinfo.texi(,7432) @node Block Enclosing Commands
7337texinfo.texi(,7433) @section Block Enclosing Commands
7338texinfo.texi(,7434)
7339texinfo.texi(,7435) Here are commands for quotations and examples, explained further in the
7340texinfo.texi(,7436) following sections:
7341texinfo.texi(,7437)
7342texinfo.texi(,7438) @table @code
7343texinfo.texi(,7439) @item @@quotation
7344texinfo.texi(,7440) Indicate text that is quoted. The text is filled, indented, and
7345texinfo.texi(,7441) printed in a roman font by default.
7346texinfo.texi(,7442)
7347texinfo.texi(,7443) @item @@example
7348texinfo.texi(,7444) Illustrate code, commands, and the like. The text is printed
7349texinfo.texi(,7445) in a fixed-width font, and indented but not filled.
7350texinfo.texi(,7446)
7351texinfo.texi(,7447) @item @@verbatim
7352texinfo.texi(,7448) Mark a piece of text that is to be printed verbatim; no character
7353texinfo.texi(,7449) substitutions are made and all commands are ignored, until the next
7354texinfo.texi(,7450) @code{@@end verbatim}.  The text is printed in a fixed-width font,
7355texinfo.texi(,7451) and not indented or filled.  Extra spaces and blank lines are
7356texinfo.texi(,7452) significant, and tabs are expanded.
7357texinfo.texi(,7453)
7358texinfo.texi(,7454) @item @@smallexample
7359texinfo.texi(,7455) Same as @code{@@example}, except that in @TeX{} this command typesets
7360texinfo.texi(,7456) text in a smaller font.
7361texinfo.texi(,7457)
7362texinfo.texi(,7458) @item @@lisp
7363texinfo.texi(,7459) Like @code{@@example}, but specifically for illustrating Lisp code. The
7364texinfo.texi(,7460) text is printed in a fixed-width font, and indented but not filled.
7365texinfo.texi(,7461)
7366texinfo.texi(,7462) @item @@smalllisp
7367texinfo.texi(,7463) Is to @code{@@lisp} as @code{@@smallexample} is to @code{@@example}.
7368texinfo.texi(,7464)
7369texinfo.texi(,7465) @item @@display
7370texinfo.texi(,7466) Display illustrative text.  The text is indented but not filled, and
7371texinfo.texi(,7467) no font is selected (so, by default, the font is roman).@refill
7372texinfo.texi(,7468)
7373texinfo.texi(,7469) @item @@smalldisplay
7374texinfo.texi(,7470) Is to @code{@@display} as @code{@@smallexample} is to @code{@@example}.
7375texinfo.texi(,7471)
7376texinfo.texi(,7472) @item @@format
7377texinfo.texi(,7473) Like @code{@@display} (the text is not filled and no font is selected),
7378texinfo.texi(,7474) but the text is not indented.
7379texinfo.texi(,7475)
7380texinfo.texi(,7476) @item @@smallformat
7381texinfo.texi(,7477) Is to @code{@@format} as @code{@@smallexample} is to @code{@@example}.
7382texinfo.texi(,7478) @end table
7383texinfo.texi(,7479)
7384texinfo.texi(,7480) The @code{@@exdent} command is used within the above constructs to
7385texinfo.texi(,7481) undo the indentation of a line.
7386texinfo.texi(,7482)
7387texinfo.texi(,7483) The @code{@@flushleft} and @code{@@flushright} commands are used to line
7388texinfo.texi(,7484) up the left or right margins of unfilled text.@refill
7389texinfo.texi(,7485)
7390texinfo.texi(,7486) The @code{@@noindent} command may be used after one of the above
7391texinfo.texi(,7487) constructs to prevent the following text from being indented as a new
7392texinfo.texi(,7488) paragraph.
7393texinfo.texi(,7489)
7394texinfo.texi(,7490) You can use the @code{@@cartouche} command within one of the above
7395texinfo.texi(,7491) constructs to highlight the example or quotation by drawing a box with
7396texinfo.texi(,7492) rounded corners around it.  @xref{cartouche, , Drawing Cartouches Around
7397texinfo.texi(,7493) Examples}.
7398texinfo.texi(,7494)
7399texinfo.texi(,7495)
7400texinfo.texi(,7496) @node quotation
7401texinfo.texi(,7497) @section @code{@@quotation}
7402texinfo.texi(,7498) @cindex Quotations
7403texinfo.texi(,7499) @findex quotation
7404texinfo.texi(,7500)
7405texinfo.texi(,7501) The text of a quotation is processed normally except that:
7406texinfo.texi(,7502)
7407texinfo.texi(,7503) @itemize @bullet
7408texinfo.texi(,7504) @item
7409texinfo.texi(,7505) the margins are closer to the center of the page, so the whole of the
7410texinfo.texi(,7506) quotation is indented;@refill
7411texinfo.texi(,7507)
7412texinfo.texi(,7508) @item
7413texinfo.texi(,7509) the first lines of paragraphs are indented no more than other
7414texinfo.texi(,7510) lines;@refill
7415texinfo.texi(,7511)
7416texinfo.texi(,7512) @item
7417texinfo.texi(,7513) in the printed output, interparagraph spacing is reduced.@refill
7418texinfo.texi(,7514) @end itemize
7419texinfo.texi(,7515)
7420texinfo.texi(,7516) @quotation
7421texinfo.texi(,7517) This is an example of text written between an @code{@@quotation}
7422texinfo.texi(,7518) command and an @code{@@end quotation} command.  An @code{@@quotation}
7423texinfo.texi(,7519) command is most often used to indicate text that is excerpted from
7424texinfo.texi(,7520) another (real or hypothetical) printed work.@refill
7425texinfo.texi(,7521) @end quotation
7426texinfo.texi(,7522)
7427texinfo.texi(,7523) Write an @code{@@quotation} command as text on a line by itself.  This
7428texinfo.texi(,7524) line will disappear from the output.  Mark the end of the quotation
7429texinfo.texi(,7525) with a line beginning with and containing only @code{@@end quotation}.
7430texinfo.texi(,7526) The @code{@@end quotation} line will likewise disappear from the
7431texinfo.texi(,7527) output.  Thus, the following,@refill
7432texinfo.texi(,7528)
7433texinfo.texi(,7529) @example
7434texinfo.texi(,7530) @@quotation
7435texinfo.texi(,7531) This is
7436texinfo.texi(,7532) a foo.
7437texinfo.texi(,7533) @@end quotation
7438texinfo.texi(,7534) @end example
7439texinfo.texi(,7535)
7440texinfo.texi(,7536) @noindent
7441texinfo.texi(,7537) produces
7442texinfo.texi(,7538)
7443texinfo.texi(,7539) @quotation
7444texinfo.texi(,7540) This is a foo.
7445texinfo.texi(,7541) @end quotation
7446texinfo.texi(,7542)
7447texinfo.texi(,7543)
7448texinfo.texi(,7544) @node example
7449texinfo.texi(,7545) @section @code{@@example}: Example Text
7450texinfo.texi(,7546) @cindex Examples, formatting them
7451texinfo.texi(,7547) @cindex Formatting examples
7452texinfo.texi(,7548) @findex example
7453texinfo.texi(,7549)
7454texinfo.texi(,7550) The @code{@@example} command is used to indicate an example that is
7455texinfo.texi(,7551) not part of the running text, such as computer input or output.
7456texinfo.texi(,7552)
7457texinfo.texi(,7553) @example
7458texinfo.texi(,7554) @group
7459texinfo.texi(,7555) This is an example of text written between an
7460texinfo.texi(,7556) @code{@@example} command
7461texinfo.texi(,7557) and an @code{@@end example} command.
7462texinfo.texi(,7558) The text is indented but not filled.
7463texinfo.texi(,7559) @end group
7464texinfo.texi(,7560)
7465texinfo.texi(,7561) @group
7466texinfo.texi(,7562) In the printed manual, the text is typeset in a
7467texinfo.texi(,7563) fixed-width font, and extra spaces and blank lines are
7468texinfo.texi(,7564) significant.  In the Info file, an analogous result is
7469texinfo.texi(,7565) obtained by indenting each line with five spaces.
7470texinfo.texi(,7566) @end group
7471texinfo.texi(,7567) @end example
7472texinfo.texi(,7568)
7473texinfo.texi(,7569) Write an @code{@@example} command at the beginning of a line by itself.
7474texinfo.texi(,7570) Mark the end of the example
7475texinfo.texi(,7571) with an @code{@@end example} command, also written at the beginning of a
7476texinfo.texi(,7572) line by itself.@refill
7477texinfo.texi(,7573)
7478texinfo.texi(,7574) @need 700
7479texinfo.texi(,7575) For example,
7480texinfo.texi(,7576)
7481texinfo.texi(,7577) @example
7482texinfo.texi(,7578) @@example
7483texinfo.texi(,7579) mv foo bar
7484texinfo.texi(,7580) @@end example
7485texinfo.texi(,7581) @end example
7486texinfo.texi(,7582)
7487texinfo.texi(,7583) @noindent
7488texinfo.texi(,7584) produces
7489texinfo.texi(,7585)
7490texinfo.texi(,7586) @example
7491texinfo.texi(,7587) mv foo bar
7492texinfo.texi(,7588) @end example
7493texinfo.texi(,7589)
7494texinfo.texi(,7590) The lines containing @code{@@example} and @code{@@end example}
7495texinfo.texi(,7591) will disappear from the output.
7496texinfo.texi(,7592) To make the output look good,
7497texinfo.texi(,7593) you should put a blank line before the
7498texinfo.texi(,7594) @code{@@example} and another blank line after the @code{@@end example}.
7499texinfo.texi(,7595) Note that blank lines inside the beginning
7500texinfo.texi(,7596) @code{@@example} and the ending @code{@@end example} will appear in
7501texinfo.texi(,7597) the output.@refill
7502texinfo.texi(,7598)
7503texinfo.texi(,7599) @quotation
7504texinfo.texi(,7600) @strong{Caution:} Do not use tabs in the lines of an example or anywhere
7505texinfo.texi(,7601) else in Texinfo (except in verbatim environments)!  The @TeX{}
7506texinfo.texi(,7602) implementation of Texinfo treats tabs as single spaces, and that is not
7507texinfo.texi(,7603) what they look like.  (If necessary, in Emacs, you can use @kbd{M-x
7508texinfo.texi(,7604) untabify} to convert tabs in a region to multiple spaces.)@refill
7509texinfo.texi(,7605) @end quotation
7510texinfo.texi(,7606)
7511texinfo.texi(,7607) Examples are often, logically speaking, ``in the middle'' of a
7512texinfo.texi(,7608) paragraph, and the text that continues after an example should not be
7513texinfo.texi(,7609) indented.  The @code{@@noindent} command prevents a piece of text from
7514texinfo.texi(,7610) being indented as if it were a new paragraph.
7515texinfo.texi(,7612) (@xref{noindent}.)
7516texinfo.texi(,7614)
7517texinfo.texi(,7615) (The @code{@@code} command is used for examples of code that are
7518texinfo.texi(,7616) embedded within sentences, not set off from preceding and following
7519texinfo.texi(,7617) text.  @xref{code, , @code{@@code}}.)
7520texinfo.texi(,7618)
7521texinfo.texi(,7619)
7522texinfo.texi(,7620) @node verbatim
7523texinfo.texi(,7621) @section @code{@@verbatim}: Literal Text
7524texinfo.texi(,7622) @findex verbatim
7525texinfo.texi(,7623) @cindex Verbatim environment
7526texinfo.texi(,7624)
7527texinfo.texi(,7625) Use the @code{@@verbatim} environment for printing of text that may
7528texinfo.texi(,7626) contain special characters or commands that should not be interpreted,
7529texinfo.texi(,7627) such as computer input or output (@code{@@example} interprets its text
7530texinfo.texi(,7628) as regular Texinfo commands).  This is especially useful for including
7531texinfo.texi(,7629) automatically generated output in a Texinfo manual.  Here is an example;
7532texinfo.texi(,7630) the output you see is just the same as the input, with a line
7533texinfo.texi(,7631) @code{@@verbatim} before and a line @code{@@end verbatim} after.
7534texinfo.texi(,7632)
7535texinfo.texi(,7633) @verbatim
7536texinfo.texi(,7634) This is an example of text written in a @verbatim
7537texinfo.texi(,7635) block.  No character substitutions are made.  All commands
7538texinfo.texi(,7636) are ignored, until `<at>end verbatim'.
7539texinfo.texi(,7637)
7540texinfo.texi(,7638) In the printed manual, the text is typeset in a
7541texinfo.texi(,7639) fixed-width font, and not indented or filled.  All
7542texinfo.texi(,7640) spaces and blank lines are significant, including tabs.
7543texinfo.texi(,7641) @end verbatim
7544texinfo.texi(,7642)
7545texinfo.texi(,7643) Write a @code{@@verbatim} command at the beginning of a line by itself.
7546texinfo.texi(,7644) This line will disappear from the output.  Mark the end of the verbatim
7547texinfo.texi(,7645) block with a @code{@@end verbatim} command, also written at the
7548texinfo.texi(,7646) beginning of a line by itself.  The @code{@@end verbatim} will also
7549texinfo.texi(,7647) disappear from the output.
7550texinfo.texi(,7648)
7551texinfo.texi(,7649) For example:
7552texinfo.texi(,7650) @c oops, got to trick this a bit: can't use @end verbatim inside @verbatim
7553texinfo.texi(,7651)
7554texinfo.texi(,7652) @example
7555texinfo.texi(,7653) @exdent @@verbatim
7556texinfo.texi(,7654) @exdent @{
7557texinfo.texi(,7655) @exdent <tab>@@command with strange characters: @@'e
7558texinfo.texi(,7656) @exdent expand<tab>me
7559texinfo.texi(,7657) @exdent @}
7560texinfo.texi(,7658) @exdent @@end verbatim
7561texinfo.texi(,7659) @end example
7562texinfo.texi(,7660)
7563texinfo.texi(,7661) @noindent
7564texinfo.texi(,7662) produces
7565texinfo.texi(,7663)
7566texinfo.texi(,7664) @verbatim
7567texinfo.texi(,7665) {
7568texinfo.texi(,7666) 	@command with strange characters: @'e
7569texinfo.texi(,7667) expand	me
7570texinfo.texi(,7668) }
7571texinfo.texi(,7669) @end verbatim
7572texinfo.texi(,7670)
7573texinfo.texi(,7671) Since the lines containing @code{@@verbatim} and @code{@@end verbatim}
7574texinfo.texi(,7672) produce no output, tyically you should put a blank line before the
7575texinfo.texi(,7673) @code{@@verbatim} and another blank line after the @code{@@end
7576texinfo.texi(,7674) verbatim}.  Blank lines between the beginning @code{@@verbatim} and the
7577texinfo.texi(,7675) ending @code{@@end verbatim} will appear in the output.
7578texinfo.texi(,7676)
7579texinfo.texi(,7677)
7580texinfo.texi(,7678) @node verbatiminclude
7581texinfo.texi(,7679) @section @code{@@verbatiminclude} @var{file}: Include a File Verbatim
7582texinfo.texi(,7680) @cindex Verbatim, include file
7583texinfo.texi(,7681) @cindex Including a file verbatim
7584texinfo.texi(,7682) @findex verbatiminclude
7585texinfo.texi(,7683)
7586texinfo.texi(,7684) You can include the exact contents of a file in the document with the
7587texinfo.texi(,7685) @code{@@verbatiminclude} command:
7588texinfo.texi(,7686)
7589texinfo.texi(,7687) @example
7590texinfo.texi(,7688) @@verbatiminclude @var{filename}
7591texinfo.texi(,7689) @end example
7592texinfo.texi(,7690)
7593texinfo.texi(,7691) The contents of @var{filename} is printed in a verbatim environment
7594texinfo.texi(,7692) (@pxref{verbatim,,@code{@@verbatim}}).  Generally, the file is printed
7595texinfo.texi(,7693) exactly as it is, with all special characters and white space retained.
7596texinfo.texi(,7694)
7597texinfo.texi(,7695)
7598texinfo.texi(,7696) @node lisp
7599texinfo.texi(,7697) @section @code{@@lisp}: Marking a Lisp Example
7600texinfo.texi(,7698) @findex lisp
7601texinfo.texi(,7699) @cindex Lisp example
7602texinfo.texi(,7700)
7603texinfo.texi(,7701) The @code{@@lisp} command is used for Lisp code.  It is synonymous
7604texinfo.texi(,7702) with the @code{@@example} command.
7605texinfo.texi(,7703)
7606texinfo.texi(,7704) @lisp
7607texinfo.texi(,7705) This is an example of text written between an
7608texinfo.texi(,7706) @code{@@lisp} command and an @code{@@end lisp} command.
7609texinfo.texi(,7707) @end lisp
7610texinfo.texi(,7708)
7611texinfo.texi(,7709) Use @code{@@lisp} instead of @code{@@example} to preserve information
7612texinfo.texi(,7710) regarding the nature of the example.  This is useful, for example, if
7613texinfo.texi(,7711) you write a function that evaluates only and all the Lisp code in a
7614texinfo.texi(,7712) Texinfo file.  Then you can use the Texinfo file as a Lisp
7615texinfo.texi(,7713) library.@footnote{It would be straightforward to extend Texinfo to work
7616texinfo.texi(,7714) in a similar fashion for C, Fortran, or other languages.}
7617texinfo.texi(,7715)
7618texinfo.texi(,7716) Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by
7619texinfo.texi(,7717) itself.@refill
7620texinfo.texi(,7718)
7621texinfo.texi(,7719)
7622texinfo.texi(,7720) @node small
7623texinfo.texi(,7721) @section @code{@@small@dots{}} Block Commands
7624texinfo.texi(,7722) @cindex Small examples
7625texinfo.texi(,7723) @cindex Examples in smaller fonts
7626texinfo.texi(,7724) @cindex Lisp examples in smaller fonts
7627texinfo.texi(,7725) @findex smalldisplay
7628texinfo.texi(,7726) @findex smallexample
7629texinfo.texi(,7727) @findex smallformat
7630texinfo.texi(,7728) @findex smalllisp
7631texinfo.texi(,7729)
7632texinfo.texi(,7730) In addition to the regular @code{@@example} and @code{@@lisp} commands,
7633texinfo.texi(,7731) Texinfo has ``small'' example-style commands.  These are
7634texinfo.texi(,7732) @code{@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat}, and
7635texinfo.texi(,7733) @code{@@smalllisp}.
7636texinfo.texi(,7734)
7637texinfo.texi(,7735) In @TeX{}, the @code{@@small@dots{}} commands typeset text in a smaller
7638texinfo.texi(,7736) font than the non-small example commands.  Consequently, many examples
7639texinfo.texi(,7737) containing long lines fit on a page without needing to be shortened.
7640texinfo.texi(,7738)
7641texinfo.texi(,7739) In Info, the @code{@@small@dots{}} commands are equivalent to their
7642texinfo.texi(,7740) non-small companion commands.
7643texinfo.texi(,7741)
7644texinfo.texi(,7742) Mark the end of an @code{@@small@dots{}} block with a corresponding
7645texinfo.texi(,7743) @code{@@end small@dots{}}.  For example, pair @code{@@smallexample} with
7646texinfo.texi(,7744) @code{@@end smallexample}.
7647texinfo.texi(,7745)
7648texinfo.texi(,7776) @smallexample
7649texinfo.texi(,7777) This is an example of text written between @code{@@smallexample} and
7650texinfo.texi(,7778) @code{@@end smallexample}.  In Info this text appears in its normal size;
7651texinfo.texi(,7779) but in a 7 by 9.25 inch manual, this text appears in a smaller font.
7652texinfo.texi(,7780) @end smallexample
7653texinfo.texi(,7782)
7654texinfo.texi(,7783) The @code{@@small@dots{}} commands make it easier to prepare manuals
7655texinfo.texi(,7784) without forcing you to edit examples by hand to fit them onto narrower
7656texinfo.texi(,7785) pages.
7657texinfo.texi(,7786)
7658texinfo.texi(,7787) As a general rule, a printed document looks better if you use only one
7659texinfo.texi(,7788) of (for example) @code{@@example} or in @code{@@smallexample}
7660texinfo.texi(,7789) consistently within a chapter.  Only occasionally should you mix the two
7661texinfo.texi(,7790) formats.
7662texinfo.texi(,7791)
7663texinfo.texi(,7792) @xref{smallbook, , Printing ``Small'' Books}, for more information
7664texinfo.texi(,7793) about the @code{@@smallbook} command.
7665texinfo.texi(,7794)
7666texinfo.texi(,7795)
7667texinfo.texi(,7796) @node display
7668texinfo.texi(,7797) @section @code{@@display} and @code{@@smalldisplay}
7669texinfo.texi(,7798) @cindex Display formatting
7670texinfo.texi(,7799) @findex display
7671texinfo.texi(,7800)
7672texinfo.texi(,7801) The @code{@@display} command begins a kind of example.  It is like the
7673texinfo.texi(,7802) @code{@@example} command
7674texinfo.texi(,7803) except that, in
7675texinfo.texi(,7804) a printed manual, @code{@@display} does not select the fixed-width
7676texinfo.texi(,7805) font.  In fact, it does not specify the font at all, so that the text
7677texinfo.texi(,7806) appears in the same font it would have appeared in without the
7678texinfo.texi(,7807) @code{@@display} command.@refill
7679texinfo.texi(,7808)
7680texinfo.texi(,7809) @display
7681texinfo.texi(,7810) This is an example of text written between an @code{@@display} command
7682texinfo.texi(,7811) and an @code{@@end display} command.  The @code{@@display} command
7683texinfo.texi(,7812) indents the text, but does not fill it.
7684texinfo.texi(,7813) @end display
7685texinfo.texi(,7814)
7686texinfo.texi(,7815) @findex smalldisplay
7687texinfo.texi(,7816) Texinfo also provides a command @code{@@smalldisplay}, which is like
7688texinfo.texi(,7817) @code{@@display} but uses a smaller font in @code{@@smallbook} format.
7689texinfo.texi(,7818) @xref{small}.
7690texinfo.texi(,7819)
7691texinfo.texi(,7820)
7692texinfo.texi(,7821) @node format
7693texinfo.texi(,7822) @section @code{@@format} and @code{@@smallformat}
7694texinfo.texi(,7823) @findex format
7695texinfo.texi(,7824)
7696texinfo.texi(,7825) The @code{@@format} command is similar to @code{@@example} except
7697texinfo.texi(,7826) that, in the printed manual, @code{@@format} does not select the
7698texinfo.texi(,7827) fixed-width font and does not narrow the margins.@refill
7699texinfo.texi(,7828)
7700texinfo.texi(,7829) @format
7701texinfo.texi(,7830) This is an example of text written between an @code{@@format} command
7702texinfo.texi(,7831) and an @code{@@end format} command.  As you can see
7703texinfo.texi(,7832) from this example,
7704texinfo.texi(,7833) the @code{@@format} command does not fill the text.
7705texinfo.texi(,7834) @end format
7706texinfo.texi(,7835)
7707texinfo.texi(,7836) @findex smallformat
7708texinfo.texi(,7837) Texinfo also provides a command @code{@@smallformat}, which is like
7709texinfo.texi(,7838) @code{@@format} but uses a smaller font in @code{@@smallbook} format.
7710texinfo.texi(,7839) @xref{small}.
7711texinfo.texi(,7840)
7712texinfo.texi(,7841)
7713texinfo.texi(,7842)
7714texinfo.texi(,7843) @node exdent
7715texinfo.texi(,7844) @section @code{@@exdent}: Undoing a Line's Indentation
7716texinfo.texi(,7845) @cindex Indentation undoing
7717texinfo.texi(,7846) @findex exdent
7718texinfo.texi(,7847)
7719texinfo.texi(,7848) The @code{@@exdent} command removes any indentation a line might have.
7720texinfo.texi(,7849) The command is written at the beginning of a line and applies only to
7721texinfo.texi(,7850) the text that follows the command that is on the same line.  Do not use
7722texinfo.texi(,7851) braces around the text.  In a printed manual, the text on an
7723texinfo.texi(,7852) @code{@@exdent} line is printed in the roman font.@refill
7724texinfo.texi(,7853)
7725texinfo.texi(,7854) @code{@@exdent} is usually used within examples.  Thus,@refill
7726texinfo.texi(,7855)
7727texinfo.texi(,7856) @example
7728texinfo.texi(,7857) @group
7729texinfo.texi(,7858) @@example
7730texinfo.texi(,7859) This line follows an @@@@example command.
7731texinfo.texi(,7860) @@exdent This line is exdented.
7732texinfo.texi(,7861) This line follows the exdented line.
7733texinfo.texi(,7862) The @@@@end example comes on the next line.
7734texinfo.texi(,7863) @@end group
7735texinfo.texi(,7864) @end group
7736texinfo.texi(,7865) @end example
7737texinfo.texi(,7866)
7738texinfo.texi(,7867) @noindent
7739texinfo.texi(,7868) produces
7740texinfo.texi(,7869)
7741texinfo.texi(,7870) @example
7742texinfo.texi(,7871) @group
7743texinfo.texi(,7872) This line follows an @@example command.
7744texinfo.texi(,7873) @exdent This line is exdented.
7745texinfo.texi(,7874) This line follows the exdented line.
7746texinfo.texi(,7875) The @@end example comes on the next line.
7747texinfo.texi(,7876) @end group
7748texinfo.texi(,7877) @end example
7749texinfo.texi(,7878)
7750texinfo.texi(,7879) In practice, the @code{@@exdent} command is rarely used.
7751texinfo.texi(,7880) Usually, you un-indent text by ending the example and
7752texinfo.texi(,7881) returning the page to its normal width.@refill
7753texinfo.texi(,7882)
7754texinfo.texi(,7883)
7755texinfo.texi(,7884) @node flushleft & flushright
7756texinfo.texi(,7885) @section @code{@@flushleft} and @code{@@flushright}
7757texinfo.texi(,7886) @findex flushleft
7758texinfo.texi(,7887) @findex flushright
7759texinfo.texi(,7888) @cindex ragged right
7760texinfo.texi(,7889) @cindex ragged left
7761texinfo.texi(,7890)
7762texinfo.texi(,7891) The @code{@@flushleft} and @code{@@flushright} commands line up the
7763texinfo.texi(,7892) ends of lines on the left and right margins of a page,
7764texinfo.texi(,7893) but do not fill the text.  The commands are written on lines of their
7765texinfo.texi(,7894) own, without braces.  The @code{@@flushleft} and @code{@@flushright}
7766texinfo.texi(,7895) commands are ended by @code{@@end flushleft} and @code{@@end
7767texinfo.texi(,7896) flushright} commands on lines of their own.@refill
7768texinfo.texi(,7897)
7769texinfo.texi(,7898) @need 1500
7770texinfo.texi(,7899) For example,
7771texinfo.texi(,7900)
7772texinfo.texi(,7901) @example
7773texinfo.texi(,7902) @group
7774texinfo.texi(,7903) @@flushleft
7775texinfo.texi(,7904) This text is
7776texinfo.texi(,7905) written flushleft.
7777texinfo.texi(,7906) @@end flushleft
7778texinfo.texi(,7907) @end group
7779texinfo.texi(,7908) @end example
7780texinfo.texi(,7909)
7781texinfo.texi(,7910) @noindent
7782texinfo.texi(,7911) produces
7783texinfo.texi(,7912)
7784texinfo.texi(,7913) @quotation
7785texinfo.texi(,7914) @flushleft
7786texinfo.texi(,7915) This text is
7787texinfo.texi(,7916) written flushleft.
7788texinfo.texi(,7917) @end flushleft
7789texinfo.texi(,7918) @end quotation
7790texinfo.texi(,7919)
7791texinfo.texi(,7920)
7792texinfo.texi(,7921) @code{@@flushright} produces the type of indentation often used in the
7793texinfo.texi(,7922) return address of letters.  For example,
7794texinfo.texi(,7923)
7795texinfo.texi(,7924) @example
7796texinfo.texi(,7925) @group
7797texinfo.texi(,7926) @@flushright
7798texinfo.texi(,7927) Here is an example of text written
7799texinfo.texi(,7928) flushright.  The @@code@{@@flushright@} command
7800texinfo.texi(,7929) right justifies every line but leaves the
7801texinfo.texi(,7930) left end ragged.
7802texinfo.texi(,7931) @@end flushright
7803texinfo.texi(,7932) @end group
7804texinfo.texi(,7933) @end example
7805texinfo.texi(,7934)
7806texinfo.texi(,7935) @noindent
7807texinfo.texi(,7936) produces
7808texinfo.texi(,7937)
7809texinfo.texi(,7938) @flushright
7810texinfo.texi(,7939) Here is an example of text written
7811texinfo.texi(,7940) flushright.  The @code{@@flushright} command
7812texinfo.texi(,7941) right justifies every line but leaves the
7813texinfo.texi(,7942) left end ragged.
7814texinfo.texi(,7943) @end flushright
7815texinfo.texi(,7944)
7816texinfo.texi(,7945)
7817texinfo.texi(,7946) @node noindent
7818texinfo.texi(,7947) @section @code{@@noindent}: Omitting Indentation
7819texinfo.texi(,7948) @findex noindent
7820texinfo.texi(,7949)
7821texinfo.texi(,7950) An example or other inclusion can break a paragraph into segments.
7822texinfo.texi(,7951) Ordinarily, the formatters indent text that follows an example as a new
7823texinfo.texi(,7952) paragraph.  However, you can prevent this by writing @code{@@noindent}
7824texinfo.texi(,7953) at the beginning of a line by itself preceding the continuation
7825texinfo.texi(,7954) text.@refill
7826texinfo.texi(,7955)
7827texinfo.texi(,7956) @need 1500
7828texinfo.texi(,7957) For example:
7829texinfo.texi(,7958)
7830texinfo.texi(,7959) @example
7831texinfo.texi(,7960) @group
7832texinfo.texi(,7961) @@example
7833texinfo.texi(,7962) This is an example
7834texinfo.texi(,7963) @@end example
7835texinfo.texi(,7964)
7836texinfo.texi(,7965) @@noindent
7837texinfo.texi(,7966) This line is not indented.  As you can see, the
7838texinfo.texi(,7967) beginning of the line is fully flush left with the line
7839texinfo.texi(,7968) that follows after it.  (This whole example is between
7840texinfo.texi(,7969) @@code@{@@@@display@} and @@code@{@@@@end display@}.)
7841texinfo.texi(,7970) @end group
7842texinfo.texi(,7971) @end example
7843texinfo.texi(,7972)
7844texinfo.texi(,7973) @noindent
7845texinfo.texi(,7974) produces
7846texinfo.texi(,7975)
7847texinfo.texi(,7976) @display
7848texinfo.texi(,7977) @example
7849texinfo.texi(,7978) This is an example
7850texinfo.texi(,7979) @end example
7851texinfo.texi(,7980) @tex
7852texinfo.texi(,7981) % Remove extra vskip; this is a kludge to counter the effect of display
7853texinfo.texi(,7982) \vskip-3.5\baselineskip
7854texinfo.texi(,7983) @end tex
7855texinfo.texi(,7984)
7856texinfo.texi(,7985) @noindent
7857texinfo.texi(,7986) This line is not indented.  As you can see, the
7858texinfo.texi(,7987) beginning of the line is fully flush left with the line
7859texinfo.texi(,7988) that follows after it.  (This whole example is between
7860texinfo.texi(,7989) @code{@@display} and @code{@@end display}.)
7861texinfo.texi(,7990) @end display
7862texinfo.texi(,7991)
7863texinfo.texi(,7992) To adjust the number of blank lines properly in the Info file output,
7864texinfo.texi(,7993) remember that the line containing @code{@@noindent} does not generate a
7865texinfo.texi(,7994) blank line, and neither does the @code{@@end example} line.@refill
7866texinfo.texi(,7995)
7867texinfo.texi(,7996) In the Texinfo source file for this manual, each line that says
7868texinfo.texi(,7997) `produces' is preceded by a line containing @code{@@noindent}.@refill
7869texinfo.texi(,7998)
7870texinfo.texi(,7999) Do not put braces after an @code{@@noindent} command; they are not
7871texinfo.texi(,8000) necessary, since @code{@@noindent} is a command used outside of
7872texinfo.texi(,8001) paragraphs (@pxref{Command Syntax}).@refill
7873texinfo.texi(,8002)
7874texinfo.texi(,8003)
7875texinfo.texi(,8004) @node cartouche
7876texinfo.texi(,8005) @section @code{@@cartouche}: Rounded Rectangles Around Examples
7877texinfo.texi(,8006) @findex cartouche
7878texinfo.texi(,8007) @cindex Box with rounded corners
7879texinfo.texi(,8008) @cindex Rounded rectangles, around examples
7880texinfo.texi(,8009)
7881texinfo.texi(,8010) In a printed manual, the @code{@@cartouche} command draws a box with
7882texinfo.texi(,8011) rounded corners around its contents.  You can use this command to
7883texinfo.texi(,8012) further highlight an example or quotation.  For instance, you could
7884texinfo.texi(,8013) write a manual in which one type of example is surrounded by a cartouche
7885texinfo.texi(,8014) for emphasis.
7886texinfo.texi(,8015)
7887texinfo.texi(,8016) @code{@@cartouche} affects only the printed manual; it has no effect in
7888texinfo.texi(,8017) other output files.
7889texinfo.texi(,8018)
7890texinfo.texi(,8019) @need 1500
7891texinfo.texi(,8020) For example,
7892texinfo.texi(,8021)
7893texinfo.texi(,8022) @example
7894texinfo.texi(,8023) @group
7895texinfo.texi(,8024) @@example
7896texinfo.texi(,8025) @@cartouche
7897texinfo.texi(,8026) % pwd
7898texinfo.texi(,8027) /usr/local/share/emacs
7899texinfo.texi(,8028) @@end cartouche
7900texinfo.texi(,8029) @@end example
7901texinfo.texi(,8030) @end group
7902texinfo.texi(,8031) @end example
7903texinfo.texi(,8032)
7904texinfo.texi(,8033) @noindent
7905texinfo.texi(,8034) surrounds the two-line example with a box with rounded corners, in the
7906texinfo.texi(,8035) printed manual.
7907texinfo.texi(,8036)
7908texinfo.texi(,8049)
7909texinfo.texi(,8050)
7910texinfo.texi(,8051) @node Lists and Tables
7911texinfo.texi(,8052) @chapter Lists and Tables
7912texinfo.texi(,8053) @cindex Making lists and tables
7913texinfo.texi(,8054) @cindex Lists and tables, making
7914texinfo.texi(,8055) @cindex Tables and lists, making
7915texinfo.texi(,8056)
7916texinfo.texi(,8057) Texinfo has several ways of making lists and tables.  Lists can be
7917texinfo.texi(,8058) bulleted or numbered; two-column tables can highlight the items in
7918texinfo.texi(,8059) the first column; multi-column tables are also supported.
7919texinfo.texi(,8060)
7920texinfo.texi(,8061) @menu
7921texinfo.texi(,8062) * Introducing Lists::           Texinfo formats lists for you.
7922texinfo.texi(,8063) * itemize::                     How to construct a simple list.
7923texinfo.texi(,8064) * enumerate::                   How to construct a numbered list.
7924texinfo.texi(,8065) * Two-column Tables::           How to construct a two-column table.
7925texinfo.texi(,8066) * Multi-column Tables::         How to construct generalized tables.
7926texinfo.texi(,8067) @end menu
7927texinfo.texi(,8068)
7928texinfo.texi(,8069) @node Introducing Lists, itemize, Lists and Tables, Lists and Tables
7929texinfo.texi(,8071) @heading Introducing Lists
7930texinfo.texi(,8073)
7931texinfo.texi(,8074) Texinfo automatically indents the text in lists or tables, and numbers
7932texinfo.texi(,8075) an enumerated list.  This last feature is useful if you modify the
7933texinfo.texi(,8076) list, since you do not need to renumber it yourself.@refill
7934texinfo.texi(,8077)
7935texinfo.texi(,8078) Numbered lists and tables begin with the appropriate @@-command at the
7936texinfo.texi(,8079) beginning of a line, and end with the corresponding @code{@@end}
7937texinfo.texi(,8080) command on a line by itself.  The table and itemized-list commands
7938texinfo.texi(,8081) also require that you write formatting information on the same line as
7939texinfo.texi(,8082) the beginning @@-command.@refill
7940texinfo.texi(,8083)
7941texinfo.texi(,8084) Begin an enumerated list, for example, with an @code{@@enumerate}
7942texinfo.texi(,8085) command and end the list with an @code{@@end enumerate} command.
7943texinfo.texi(,8086) Begin an itemized list with an @code{@@itemize} command, followed on
7944texinfo.texi(,8087) the same line by a formatting command such as @code{@@bullet}, and end
7945texinfo.texi(,8088) the list with an @code{@@end itemize} command.@refill
7946texinfo.texi(,8089) @findex end
7947texinfo.texi(,8090)
7948texinfo.texi(,8091) Precede each element of a list with an @code{@@item} or @code{@@itemx}
7949texinfo.texi(,8092) command.@refill
7950texinfo.texi(,8093)
7951texinfo.texi(,8094) @sp 1
7952texinfo.texi(,8095) @noindent
7953texinfo.texi(,8096) Here is an itemized list of the different kinds of table and lists:@refill
7954texinfo.texi(,8097)
7955texinfo.texi(,8098) @itemize @bullet
7956texinfo.texi(,8099) @item
7957texinfo.texi(,8100) Itemized lists with and without bullets.
7958texinfo.texi(,8101)
7959texinfo.texi(,8102) @item
7960texinfo.texi(,8103) Enumerated lists, using numbers or letters.
7961texinfo.texi(,8104)
7962texinfo.texi(,8105) @item
7963texinfo.texi(,8106) Two-column tables with highlighting.
7964texinfo.texi(,8107) @end itemize
7965texinfo.texi(,8108)
7966texinfo.texi(,8109) @sp 1
7967texinfo.texi(,8110) @noindent
7968texinfo.texi(,8111) Here is an enumerated list with the same items:@refill
7969texinfo.texi(,8112)
7970texinfo.texi(,8113) @enumerate
7971texinfo.texi(,8114) @item
7972texinfo.texi(,8115) Itemized lists with and without bullets.
7973texinfo.texi(,8116)
7974texinfo.texi(,8117) @item
7975texinfo.texi(,8118) Enumerated lists, using numbers or letters.
7976texinfo.texi(,8119)
7977texinfo.texi(,8120) @item
7978texinfo.texi(,8121) Two-column tables with highlighting.
7979texinfo.texi(,8122) @end enumerate
7980texinfo.texi(,8123)
7981texinfo.texi(,8124) @sp 1
7982texinfo.texi(,8125) @noindent
7983texinfo.texi(,8126) And here is a two-column table with the same items and their
7984texinfo.texi(,8127) @w{@@-commands}:@refill
7985texinfo.texi(,8128)
7986texinfo.texi(,8129) @table @code
7987texinfo.texi(,8130) @item @@itemize
7988texinfo.texi(,8131) Itemized lists with and without bullets.
7989texinfo.texi(,8132)
7990texinfo.texi(,8133) @item @@enumerate
7991texinfo.texi(,8134) Enumerated lists, using numbers or letters.
7992texinfo.texi(,8135)
7993texinfo.texi(,8136) @item @@table
7994texinfo.texi(,8137) @itemx @@ftable
7995texinfo.texi(,8138) @itemx @@vtable
7996texinfo.texi(,8139) Two-column tables, optionally with indexing.
7997texinfo.texi(,8140) @end table
7998texinfo.texi(,8141)
7999texinfo.texi(,8142)
8000texinfo.texi(,8143) @node itemize
8001texinfo.texi(,8144) @section @code{@@itemize}: Making an Itemized List
8002texinfo.texi(,8145) @cindex Itemization
8003texinfo.texi(,8146) @findex itemize
8004texinfo.texi(,8147)
8005texinfo.texi(,8148) The @code{@@itemize} command produces sequences of indented
8006texinfo.texi(,8149) paragraphs, with a bullet or other mark inside the left margin
8007texinfo.texi(,8150) at the beginning of each paragraph for which such a mark is desired.@refill
8008texinfo.texi(,8151)
8009texinfo.texi(,8152) @cindex @code{@@w}, for blank items
8010texinfo.texi(,8153) Begin an itemized list by writing @code{@@itemize} at the beginning of
8011texinfo.texi(,8154) a line.  Follow the command, on the same line, with a character or a
8012texinfo.texi(,8155) Texinfo command that generates a mark.  Usually, you will write
8013texinfo.texi(,8156) @code{@@bullet} after @code{@@itemize}, but you can use
8014texinfo.texi(,8157) @code{@@minus}, or any command or character that results in a single
8015texinfo.texi(,8158) character in the Info file.  If you don't want any mark at all, use
8016texinfo.texi(,8159) @code{@@w}.  (When you write the mark command such as
8017texinfo.texi(,8160) @code{@@bullet} after an @code{@@itemize} command, you may omit the
8018texinfo.texi(,8161) @samp{@{@}}.)  If you don't specify a mark command, the default is
8019texinfo.texi(,8162) @code{@@bullet}.
8020texinfo.texi(,8163)
8021texinfo.texi(,8164) Write the text of the indented paragraphs themselves after the
8022texinfo.texi(,8165) @code{@@itemize}, up to another line that says @code{@@end
8023texinfo.texi(,8166) itemize}.@refill
8024texinfo.texi(,8167)
8025texinfo.texi(,8168) @findex item
8026texinfo.texi(,8169) Before each paragraph for which a mark in the margin is desired, write a
8027texinfo.texi(,8170) line that says just @code{@@item}.  It is ok to have text following the
8028texinfo.texi(,8171) @code{@@item}.
8029texinfo.texi(,8172)
8030texinfo.texi(,8173) Usually, you should put a blank line before an @code{@@item}.  This
8031texinfo.texi(,8174) puts a blank line in the Info file. (@TeX{} inserts the proper
8032texinfo.texi(,8175) interline whitespace in either case.)  Except when the entries are
8033texinfo.texi(,8176) very brief, these blank lines make the list look better.@refill
8034texinfo.texi(,8177)
8035texinfo.texi(,8178) Here is an example of the use of @code{@@itemize}, followed by the
8036texinfo.texi(,8179) output it produces.  @code{@@bullet} produces an @samp{*} in Info and a
8037texinfo.texi(,8180) round dot in @TeX{}.
8038texinfo.texi(,8181)
8039texinfo.texi(,8182) @example
8040texinfo.texi(,8183) @group
8041texinfo.texi(,8184) @@itemize @@bullet
8042texinfo.texi(,8185) @@item
8043texinfo.texi(,8186) Some text for foo.
8044texinfo.texi(,8187)
8045texinfo.texi(,8188) @@item
8046texinfo.texi(,8189) Some text
8047texinfo.texi(,8190) for bar.
8048texinfo.texi(,8191) @@end itemize
8049texinfo.texi(,8192) @end group
8050texinfo.texi(,8193) @end example
8051texinfo.texi(,8194)
8052texinfo.texi(,8195) @noindent
8053texinfo.texi(,8196) This produces:
8054texinfo.texi(,8197)
8055texinfo.texi(,8198) @quotation
8056texinfo.texi(,8199) @itemize @bullet
8057texinfo.texi(,8200) @item
8058texinfo.texi(,8201) Some text for foo.
8059texinfo.texi(,8202)
8060texinfo.texi(,8203) @item
8061texinfo.texi(,8204) Some text
8062texinfo.texi(,8205) for bar.
8063texinfo.texi(,8206) @end itemize
8064texinfo.texi(,8207) @end quotation
8065texinfo.texi(,8208)
8066texinfo.texi(,8209) Itemized lists may be embedded within other itemized lists.  Here is a
8067texinfo.texi(,8210) list marked with dashes embedded in a list marked with bullets:@refill
8068texinfo.texi(,8211)
8069texinfo.texi(,8212) @example
8070texinfo.texi(,8213) @group
8071texinfo.texi(,8214) @@itemize @@bullet
8072texinfo.texi(,8215) @@item
8073texinfo.texi(,8216) First item.
8074texinfo.texi(,8217)
8075texinfo.texi(,8218) @@itemize @@minus
8076texinfo.texi(,8219) @@item
8077texinfo.texi(,8220) Inner item.
8078texinfo.texi(,8221)
8079texinfo.texi(,8222) @@item
8080texinfo.texi(,8223) Second inner item.
8081texinfo.texi(,8224) @@end itemize
8082texinfo.texi(,8225)
8083texinfo.texi(,8226) @@item
8084texinfo.texi(,8227) Second outer item.
8085texinfo.texi(,8228) @@end itemize
8086texinfo.texi(,8229) @end group
8087texinfo.texi(,8230) @end example
8088texinfo.texi(,8231)
8089texinfo.texi(,8232) @noindent
8090texinfo.texi(,8233) This produces:
8091texinfo.texi(,8234)
8092texinfo.texi(,8235) @quotation
8093texinfo.texi(,8236) @itemize @bullet
8094texinfo.texi(,8237) @item
8095texinfo.texi(,8238) First item.
8096texinfo.texi(,8239)
8097texinfo.texi(,8240) @itemize @minus
8098texinfo.texi(,8241) @item
8099texinfo.texi(,8242) Inner item.
8100texinfo.texi(,8243)
8101texinfo.texi(,8244) @item
8102texinfo.texi(,8245) Second inner item.
8103texinfo.texi(,8246) @end itemize
8104texinfo.texi(,8247)
8105texinfo.texi(,8248) @item
8106texinfo.texi(,8249) Second outer item.
8107texinfo.texi(,8250) @end itemize
8108texinfo.texi(,8251) @end quotation
8109texinfo.texi(,8252)
8110texinfo.texi(,8253)
8111texinfo.texi(,8254) @node enumerate
8112texinfo.texi(,8255) @section @code{@@enumerate}: Making a Numbered or Lettered List
8113texinfo.texi(,8256) @cindex Enumeration
8114texinfo.texi(,8257) @findex enumerate
8115texinfo.texi(,8258)
8116texinfo.texi(,8259) @code{@@enumerate} is like @code{@@itemize} (@pxref{itemize,,
8117texinfo.texi(,8260) @code{@@itemize}}), except that the labels on the items are
8118texinfo.texi(,8261) successive integers or letters instead of bullets.
8119texinfo.texi(,8262)
8120texinfo.texi(,8263) Write the @code{@@enumerate} command at the beginning of a line.  The
8121texinfo.texi(,8264) command does not require an argument, but accepts either a number or a
8122texinfo.texi(,8265) letter as an option.  Without an argument, @code{@@enumerate} starts the
8123texinfo.texi(,8266) list with the number @samp{1}.  With a numeric argument, such as
8124texinfo.texi(,8267) @samp{3}, the command starts the list with that number.  With an upper
8125texinfo.texi(,8268) or lower case letter, such as @samp{a} or @samp{A}, the command starts
8126texinfo.texi(,8269) the list with that letter.
8127texinfo.texi(,8270)
8128texinfo.texi(,8271) Write the text of the enumerated list in the same way you write an
8129texinfo.texi(,8272) itemized list: put @code{@@item} on a line of its own before the start
8130texinfo.texi(,8273) of each paragraph that you want enumerated.  Do not write any other text
8131texinfo.texi(,8274) on the line beginning with @code{@@item}.
8132texinfo.texi(,8275)
8133texinfo.texi(,8276) You should put a blank line between entries in the list.
8134texinfo.texi(,8277) This generally makes it easier to read the Info file.
8135texinfo.texi(,8278)
8136texinfo.texi(,8279) @need 1500
8137texinfo.texi(,8280) Here is an example of @code{@@enumerate} without an argument:
8138texinfo.texi(,8281)
8139texinfo.texi(,8282) @example
8140texinfo.texi(,8283) @group
8141texinfo.texi(,8284) @@enumerate
8142texinfo.texi(,8285) @@item
8143texinfo.texi(,8286) Underlying causes.
8144texinfo.texi(,8287)
8145texinfo.texi(,8288) @@item
8146texinfo.texi(,8289) Proximate causes.
8147texinfo.texi(,8290) @@end enumerate
8148texinfo.texi(,8291) @end group
8149texinfo.texi(,8292) @end example
8150texinfo.texi(,8293)
8151texinfo.texi(,8294) @noindent
8152texinfo.texi(,8295) This produces:
8153texinfo.texi(,8296)
8154texinfo.texi(,8297) @enumerate
8155texinfo.texi(,8298) @item
8156texinfo.texi(,8299) Underlying causes.
8157texinfo.texi(,8300)
8158texinfo.texi(,8301) @item
8159texinfo.texi(,8302) Proximate causes.
8160texinfo.texi(,8303) @end enumerate
8161texinfo.texi(,8304) @sp 1
8162texinfo.texi(,8305) Here is an example with an argument of @kbd{3}:@refill
8163texinfo.texi(,8306) @sp 1
8164texinfo.texi(,8307) @example
8165texinfo.texi(,8308) @group
8166texinfo.texi(,8309) @@enumerate 3
8167texinfo.texi(,8310) @@item
8168texinfo.texi(,8311) Predisposing causes.
8169texinfo.texi(,8312)
8170texinfo.texi(,8313) @@item
8171texinfo.texi(,8314) Precipitating causes.
8172texinfo.texi(,8315)
8173texinfo.texi(,8316) @@item
8174texinfo.texi(,8317) Perpetuating causes.
8175texinfo.texi(,8318) @@end enumerate
8176texinfo.texi(,8319) @end group
8177texinfo.texi(,8320) @end example
8178texinfo.texi(,8321)
8179texinfo.texi(,8322) @noindent
8180texinfo.texi(,8323) This produces:
8181texinfo.texi(,8324)
8182texinfo.texi(,8325) @enumerate 3
8183texinfo.texi(,8326) @item
8184texinfo.texi(,8327) Predisposing causes.
8185texinfo.texi(,8328)
8186texinfo.texi(,8329) @item
8187texinfo.texi(,8330) Precipitating causes.
8188texinfo.texi(,8331)
8189texinfo.texi(,8332) @item
8190texinfo.texi(,8333) Perpetuating causes.
8191texinfo.texi(,8334) @end enumerate
8192texinfo.texi(,8335) @sp 1
8193texinfo.texi(,8336) Here is a brief summary of the alternatives.  The summary is constructed
8194texinfo.texi(,8337) using @code{@@enumerate} with an argument of @kbd{a}.@refill
8195texinfo.texi(,8338) @sp 1
8196texinfo.texi(,8339) @enumerate a
8197texinfo.texi(,8340) @item
8198texinfo.texi(,8341) @code{@@enumerate}
8199texinfo.texi(,8342)
8200texinfo.texi(,8343) Without an argument, produce a numbered list, starting with the number
8201texinfo.texi(,8344) 1.@refill
8202texinfo.texi(,8345)
8203texinfo.texi(,8346) @item
8204texinfo.texi(,8347) @code{@@enumerate @var{positive-integer}}
8205texinfo.texi(,8348)
8206texinfo.texi(,8349) With a (positive) numeric argument, start a numbered list with that
8207texinfo.texi(,8350) number.  You can use this to continue a list that you interrupted with
8208texinfo.texi(,8351) other text.@refill
8209texinfo.texi(,8352)
8210texinfo.texi(,8353) @item
8211texinfo.texi(,8354) @code{@@enumerate @var{upper-case-letter}}
8212texinfo.texi(,8355)
8213texinfo.texi(,8356) With an upper case letter as argument, start a list
8214texinfo.texi(,8357) in which each item is marked
8215texinfo.texi(,8358) by a letter, beginning with that upper case letter.@refill
8216texinfo.texi(,8359)
8217texinfo.texi(,8360) @item
8218texinfo.texi(,8361) @code{@@enumerate @var{lower-case-letter}}
8219texinfo.texi(,8362)
8220texinfo.texi(,8363) With a lower case letter as argument, start a list
8221texinfo.texi(,8364) in which each item is marked by
8222texinfo.texi(,8365) a letter, beginning with that lower case letter.@refill
8223texinfo.texi(,8366) @end enumerate
8224texinfo.texi(,8367)
8225texinfo.texi(,8368) You can also nest enumerated lists, as in an outline.@refill
8226texinfo.texi(,8369)
8227texinfo.texi(,8370) @node Two-column Tables, Multi-column Tables, enumerate, Lists and Tables
8228texinfo.texi(,8371) @section Making a Two-column Table
8229texinfo.texi(,8372) @cindex Tables, making two-column
8230texinfo.texi(,8373) @findex table
8231texinfo.texi(,8374)
8232texinfo.texi(,8375) @code{@@table} is similar to @code{@@itemize} (@pxref{itemize,,
8233texinfo.texi(,8376) @code{@@itemize}}), but allows you to specify a name or heading line for
8234texinfo.texi(,8377) each item.  The @code{@@table} command is used to produce two-column
8235texinfo.texi(,8378) tables, and is especially useful for glossaries, explanatory
8236texinfo.texi(,8379) exhibits, and command-line option summaries.
8237texinfo.texi(,8380)
8238texinfo.texi(,8381) @menu
8239texinfo.texi(,8382) * table::                       How to construct a two-column table.
8240texinfo.texi(,8383) * ftable vtable::               Automatic indexing for two-column tables.
8241texinfo.texi(,8384) * itemx::                       How to put more entries in the first column.
8242texinfo.texi(,8385) @end menu
8243texinfo.texi(,8386)
8244texinfo.texi(,8387) @node table, ftable vtable, Two-column Tables, Two-column Tables
8245texinfo.texi(,8389) @subheading Using the @code{@@table} Command
8246texinfo.texi(,8390)
8247texinfo.texi(,8391) Use the @code{@@table} command to produce two-column tables.@refill
8248texinfo.texi(,8393)
8249texinfo.texi(,8394) Write the @code{@@table} command at the beginning of a line and follow
8250texinfo.texi(,8395) it on the same line with an argument that is a Texinfo ``indicating''
8251texinfo.texi(,8396) command such as @code{@@code}, @code{@@samp}, @code{@@var}, or
8252texinfo.texi(,8397) @code{@@kbd} (@pxref{Indicating}).  Although these commands are usually
8253texinfo.texi(,8398) followed by arguments in braces, in this case you use the command name
8254texinfo.texi(,8399) without an argument because @code{@@item} will supply the argument.
8255texinfo.texi(,8400) This command will be applied to the text that goes into the first column
8256texinfo.texi(,8401) of each item and determines how it will be highlighted.  For example,
8257texinfo.texi(,8402) @code{@@code} will cause the text in the first column to be highlighted
8258texinfo.texi(,8403) with an @code{@@code} command.  (We recommend @code{@@code} for
8259texinfo.texi(,8404) @code{@@table}'s of command-line options.)
8260texinfo.texi(,8405)
8261texinfo.texi(,8406) @findex asis
8262texinfo.texi(,8407) You may also choose to use the @code{@@asis} command as an argument to
8263texinfo.texi(,8408) @code{@@table}.  @code{@@asis} is a command that does nothing; if you
8264texinfo.texi(,8409) use this command after @code{@@table}, @TeX{} and the Info formatting
8265texinfo.texi(,8410) commands output the first column entries without added highlighting
8266texinfo.texi(,8411) (``as is'').@refill
8267texinfo.texi(,8412)
8268texinfo.texi(,8413) (The @code{@@table} command may work with other commands besides those
8269texinfo.texi(,8414) listed here.  However, you can only use commands that normally take
8270texinfo.texi(,8415) arguments in braces.)@refill
8271texinfo.texi(,8416)
8272texinfo.texi(,8417) @findex item
8273texinfo.texi(,8418) Begin each table entry with an @code{@@item} command at the beginning
8274texinfo.texi(,8419) of a line.  Write the first column text on the same line as the
8275texinfo.texi(,8420) @code{@@item} command.  Write the second column text on the line
8276texinfo.texi(,8421) following the @code{@@item} line and on subsequent lines.  (You do not
8277texinfo.texi(,8422) need to type anything for an empty second column entry.)  You may
8278texinfo.texi(,8423) write as many lines of supporting text as you wish, even several
8279texinfo.texi(,8424) paragraphs.  But only text on the same line as the @code{@@item} will
8280texinfo.texi(,8425) be placed in the first column, including any footnote.
8281texinfo.texi(,8426)
8282texinfo.texi(,8427) Normally, you should put a blank line before an @code{@@item} line.
8283texinfo.texi(,8428) This puts a blank like in the Info file.  Except when the entries are
8284texinfo.texi(,8429) very brief, a blank line looks better.@refill
8285texinfo.texi(,8430)
8286texinfo.texi(,8431) @need 1500
8287texinfo.texi(,8432) The following table, for example, highlights the text in the first
8288texinfo.texi(,8433) column with an @code{@@samp} command:@refill
8289texinfo.texi(,8434)
8290texinfo.texi(,8435) @example
8291texinfo.texi(,8436) @group
8292texinfo.texi(,8437) @@table @@samp
8293texinfo.texi(,8438) @@item foo
8294texinfo.texi(,8439) This is the text for
8295texinfo.texi(,8440) @@samp@{foo@}.
8296texinfo.texi(,8441)
8297texinfo.texi(,8442) @@item bar
8298texinfo.texi(,8443) Text for @@samp@{bar@}.
8299texinfo.texi(,8444) @@end table
8300texinfo.texi(,8445) @end group
8301texinfo.texi(,8446) @end example
8302texinfo.texi(,8447)
8303texinfo.texi(,8448) @noindent
8304texinfo.texi(,8449) This produces:
8305texinfo.texi(,8450)
8306texinfo.texi(,8451) @table @samp
8307texinfo.texi(,8452) @item foo
8308texinfo.texi(,8453) This is the text for
8309texinfo.texi(,8454) @samp{foo}.
8310texinfo.texi(,8455) @item bar
8311texinfo.texi(,8456) Text for @samp{bar}.
8312texinfo.texi(,8457) @end table
8313texinfo.texi(,8458)
8314texinfo.texi(,8459) If you want to list two or more named items with a single block of
8315texinfo.texi(,8460) text, use the @code{@@itemx} command.  (@xref{itemx, ,
8316texinfo.texi(,8461) @code{@@itemx}}.)@refill
8317texinfo.texi(,8462)
8318texinfo.texi(,8463)
8319texinfo.texi(,8464) @node ftable vtable
8320texinfo.texi(,8465) @subsection @code{@@ftable} and @code{@@vtable}
8321texinfo.texi(,8466) @cindex Tables with indexes
8322texinfo.texi(,8467) @cindex Indexing table entries automatically
8323texinfo.texi(,8468) @findex ftable
8324texinfo.texi(,8469) @findex vtable
8325texinfo.texi(,8470)
8326texinfo.texi(,8471) The @code{@@ftable} and @code{@@vtable} commands are the same as the
8327texinfo.texi(,8472) @code{@@table} command except that @code{@@ftable} automatically enters
8328texinfo.texi(,8473) each of the items in the first column of the table into the index of
8329texinfo.texi(,8474) functions and @code{@@vtable} automatically enters each of the items in
8330texinfo.texi(,8475) the first column of the table into the index of variables.  This
8331texinfo.texi(,8476) simplifies the task of creating indices.  Only the items on the same
8332texinfo.texi(,8477) line as the @code{@@item} commands are indexed, and they are indexed in
8333texinfo.texi(,8478) exactly the form that they appear on that line.  @xref{Indices},
8334texinfo.texi(,8479) for more information about indices.@refill
8335texinfo.texi(,8480)
8336texinfo.texi(,8481) Begin a two-column table using @code{@@ftable} or @code{@@vtable} by
8337texinfo.texi(,8482) writing the @@-command at the beginning of a line, followed on the same
8338texinfo.texi(,8483) line by an argument that is a Texinfo command such as @code{@@code},
8339texinfo.texi(,8484) exactly as you would for an @code{@@table} command; and end the table
8340texinfo.texi(,8485) with an @code{@@end ftable} or @code{@@end vtable} command on a line by
8341texinfo.texi(,8486) itself.
8342texinfo.texi(,8487)
8343texinfo.texi(,8488) See the example for @code{@@table} in the previous section.
8344texinfo.texi(,8489)
8345texinfo.texi(,8490) @node itemx
8346texinfo.texi(,8491) @subsection @code{@@itemx}
8347texinfo.texi(,8492) @cindex Two named items for @code{@@table}
8348texinfo.texi(,8493) @findex itemx
8349texinfo.texi(,8494)
8350texinfo.texi(,8495) Use the @code{@@itemx} command inside a table when you have two or more
8351texinfo.texi(,8496) first column entries for the same item, each of which should appear on a
8352texinfo.texi(,8497) line of its own.  Use @code{@@itemx} for all but the first entry;
8353texinfo.texi(,8498) @code{@@itemx} should always follow an @code{@@item} command.  The
8354texinfo.texi(,8499) @code{@@itemx} command works exactly like @code{@@item} except that it
8355texinfo.texi(,8500) does not generate extra vertical space above the first column text.
8356texinfo.texi(,8501)
8357texinfo.texi(,8502) For example,
8358texinfo.texi(,8503)
8359texinfo.texi(,8504) @example
8360texinfo.texi(,8505) @group
8361texinfo.texi(,8506) @@table @@code
8362texinfo.texi(,8507) @@item upcase
8363texinfo.texi(,8508) @@itemx downcase
8364texinfo.texi(,8509) These two functions accept a character or a string as
8365texinfo.texi(,8510) argument, and return the corresponding upper case (lower
8366texinfo.texi(,8511) case) character or string.
8367texinfo.texi(,8512) @@end table
8368texinfo.texi(,8513) @end group
8369texinfo.texi(,8514) @end example
8370texinfo.texi(,8515)
8371texinfo.texi(,8516) @noindent
8372texinfo.texi(,8517) This produces:
8373texinfo.texi(,8518)
8374texinfo.texi(,8519) @table @code
8375texinfo.texi(,8520) @item upcase
8376texinfo.texi(,8521) @itemx downcase
8377texinfo.texi(,8522) These two functions accept a character or a string as
8378texinfo.texi(,8523) argument, and return the corresponding upper case (lower
8379texinfo.texi(,8524) case) character or string.@refill
8380texinfo.texi(,8525) @end table
8381texinfo.texi(,8526)
8382texinfo.texi(,8527) @noindent
8383texinfo.texi(,8528) (Note also that this example illustrates multi-line supporting text in
8384texinfo.texi(,8529) a two-column table.)@refill
8385texinfo.texi(,8530)
8386texinfo.texi(,8531)
8387texinfo.texi(,8532) @node Multi-column Tables,  , Two-column Tables, Lists and Tables
8388texinfo.texi(,8533) @section Multi-column Tables
8389texinfo.texi(,8534) @cindex Tables, making multi-column
8390texinfo.texi(,8535) @findex multitable
8391texinfo.texi(,8536)
8392texinfo.texi(,8537) @code{@@multitable} allows you to construct tables with any number of
8393texinfo.texi(,8538) columns, with each column having any width you like.
8394texinfo.texi(,8539)
8395texinfo.texi(,8540) You define the column widths on the @code{@@multitable} line itself, and
8396texinfo.texi(,8541) write each row of the actual table following an @code{@@item} command,
8397texinfo.texi(,8542) with columns separated by an @code{@@tab} command.  Finally, @code{@@end
8398texinfo.texi(,8543) multitable} completes the table.  Details in the sections below.
8399texinfo.texi(,8544)
8400texinfo.texi(,8545) @menu
8401texinfo.texi(,8546) * Multitable Column Widths::    Defining multitable column widths.
8402texinfo.texi(,8547) * Multitable Rows::             Defining multitable rows, with examples.
8403texinfo.texi(,8548) @end menu
8404texinfo.texi(,8549)
8405texinfo.texi(,8550) @node Multitable Column Widths
8406texinfo.texi(,8551) @subsection Multitable Column Widths
8407texinfo.texi(,8552) @cindex Multitable column widths
8408texinfo.texi(,8553) @cindex Column widths, defining for multitables
8409texinfo.texi(,8554) @cindex Widths, defining multitable column
8410texinfo.texi(,8555)
8411texinfo.texi(,8556) You can define the column widths for a multitable in two ways: as
8412texinfo.texi(,8557) fractions of the line length; or with a prototype row.  Mixing the two
8413texinfo.texi(,8558) methods is not supported.  In either case, the widths are defined
8414texinfo.texi(,8559) entirely on the same line as the @code{@@multitable} command.
8415texinfo.texi(,8560)
8416texinfo.texi(,8561) @enumerate
8417texinfo.texi(,8562) @item
8418texinfo.texi(,8563) @findex columnfractions
8419texinfo.texi(,8564) @cindex Line length, column widths as fraction of
8420texinfo.texi(,8565) To specify column widths as fractions of the line length, write
8421texinfo.texi(,8566) @code{@@columnfractions} and the decimal numbers (presumably less than
8422texinfo.texi(,8567) 1) after the @code{@@multitable} command, as in:
8423texinfo.texi(,8568)
8424texinfo.texi(,8569) @example
8425texinfo.texi(,8570) @@multitable @@columnfractions .33 .33 .33
8426texinfo.texi(,8571) @end example
8427texinfo.texi(,8572)
8428texinfo.texi(,8573) @noindent The fractions need not add up exactly to 1.0, as these do
8429texinfo.texi(,8574) not.  This allows you to produce tables that do not need the full line
8430texinfo.texi(,8575) length.  You can use a leading zero if you wish.
8431texinfo.texi(,8576)
8432texinfo.texi(,8577) @item
8433texinfo.texi(,8578) @cindex Prototype row, column widths defined by
8434texinfo.texi(,8579) To specify a prototype row, write the longest entry for each column
8435texinfo.texi(,8580) enclosed in braces after the @code{@@multitable} command.  For example:
8436texinfo.texi(,8581)
8437texinfo.texi(,8582) @example
8438texinfo.texi(,8583) @@multitable @{some text for column one@} @{for column two@}
8439texinfo.texi(,8584) @end example
8440texinfo.texi(,8585)
8441texinfo.texi(,8586) @noindent
8442texinfo.texi(,8587) The first column will then have the width of the typeset `some text for
8443texinfo.texi(,8588) column one', and the second column the width of `for column two'.
8444texinfo.texi(,8589)
8445texinfo.texi(,8590) The prototype entries need not appear in the table itself.
8446texinfo.texi(,8591)
8447texinfo.texi(,8592) Although we used simple text in this example, the prototype entries can
8448texinfo.texi(,8593) contain Texinfo commands; markup commands such as @code{@@code} are
8449texinfo.texi(,8594) particularly likely to be useful.
8450texinfo.texi(,8595)
8451texinfo.texi(,8596) @end enumerate
8452texinfo.texi(,8597)
8453texinfo.texi(,8598)
8454texinfo.texi(,8599) @node Multitable Rows,  , Multitable Column Widths, Multi-column Tables
8455texinfo.texi(,8600) @subsection Multitable Rows
8456texinfo.texi(,8601) @cindex Multitable rows
8457texinfo.texi(,8602) @cindex Rows, of a multitable
8458texinfo.texi(,8603)
8459texinfo.texi(,8604) @findex item
8460texinfo.texi(,8605) @findex tab
8461texinfo.texi(,8606) After the @code{@@multitable} command defining the column widths (see
8462texinfo.texi(,8607) the previous section), you begin each row in the body of a multitable
8463texinfo.texi(,8608) with @code{@@item}, and separate the column entries with @code{@@tab}.
8464texinfo.texi(,8609) Line breaks are not special within the table body, and you may break
8465texinfo.texi(,8610) input lines in your source file as necessary.
8466texinfo.texi(,8611)
8467texinfo.texi(,8612) Here is a complete example of a multi-column table (the text is from
8468texinfo.texi(,8613) @cite{The GNU Emacs Manual}, @pxref{Split Window,, Splitting Windows,
8469texinfo.texi(,8614) emacs, The GNU Emacs Manual}):
8470texinfo.texi(,8615)
8471texinfo.texi(,8616) @example
8472texinfo.texi(,8617) @@multitable @@columnfractions .15 .45 .4
8473texinfo.texi(,8618) @@item Key @@tab Command @@tab Description
8474texinfo.texi(,8619) @@item C-x 2
8475texinfo.texi(,8620) @@tab @@code@{split-window-vertically@}
8476texinfo.texi(,8621) @@tab Split the selected window into two windows,
8477texinfo.texi(,8622) with one above the other.
8478texinfo.texi(,8623) @@item C-x 3
8479texinfo.texi(,8624) @@tab @@code@{split-window-horizontally@}
8480texinfo.texi(,8625) @@tab Split the selected window into two windows
8481texinfo.texi(,8626) positioned side by side.
8482texinfo.texi(,8627) @@item C-Mouse-2
8483texinfo.texi(,8628) @@tab
8484texinfo.texi(,8629) @@tab In the mode line or scroll bar of a window,
8485texinfo.texi(,8630) split that window.
8486texinfo.texi(,8631) @@end multitable
8487texinfo.texi(,8632) @end example
8488texinfo.texi(,8633)
8489texinfo.texi(,8634) @noindent produces:
8490texinfo.texi(,8635)
8491texinfo.texi(,8636) @multitable @columnfractions .15 .45 .4
8492texinfo.texi(,8637) @item Key @tab Command @tab Description
8493texinfo.texi(,8638) @item C-x 2
8494texinfo.texi(,8639) @tab @code{split-window-vertically}
8495texinfo.texi(,8640) @tab Split the selected window into two windows,
8496texinfo.texi(,8641) with one above the other.
8497texinfo.texi(,8642) @item C-x 3
8498texinfo.texi(,8643) @tab @code{split-window-horizontally}
8499texinfo.texi(,8644) @tab Split the selected window into two windows
8500texinfo.texi(,8645) positioned side by side.
8501texinfo.texi(,8646) @item C-Mouse-2
8502texinfo.texi(,8647) @tab
8503texinfo.texi(,8648) @tab In the mode line or scroll bar of a window,
8504texinfo.texi(,8649) split that window.
8505texinfo.texi(,8650) @end multitable
8506texinfo.texi(,8651)
8507texinfo.texi(,8652)
8508texinfo.texi(,8653) @node Indices, Insertions, Lists and Tables, Top
8509texinfo.texi(,8654) @comment node-name,  next,  previous,  up
8510texinfo.texi(,8655) @chapter Indices
8511texinfo.texi(,8656) @cindex Indices
8512texinfo.texi(,8657)
8513texinfo.texi(,8658) Using Texinfo, you can generate indices without having to sort and
8514texinfo.texi(,8659) collate entries manually.  In an index, the entries are listed in
8515texinfo.texi(,8660) alphabetical order, together with information on how to find the
8516texinfo.texi(,8661) discussion of each entry.  In a printed manual, this information
8517texinfo.texi(,8662) consists of page numbers.  In an Info file, this information is a menu
8518texinfo.texi(,8663) entry leading to the first node referenced.@refill
8519texinfo.texi(,8664)
8520texinfo.texi(,8665) Texinfo provides several predefined kinds of index: an index
8521texinfo.texi(,8666) for functions, an index for variables, an index for concepts, and so
8522texinfo.texi(,8667) on.  You can combine indices or use them for other than their
8523texinfo.texi(,8668) canonical purpose.  If you wish, you can define your own indices.@refill
8524texinfo.texi(,8669)
8525texinfo.texi(,8670) @menu
8526texinfo.texi(,8671) * Index Entries::               Choose different words for index entries.
8527texinfo.texi(,8672) * Predefined Indices::          Use different indices for different kinds
8528texinfo.texi(,8673)                                   of entry.
8529texinfo.texi(,8674) * Indexing Commands::           How to make an index entry.
8530texinfo.texi(,8675) * Combining Indices::           How to combine indices.
8531texinfo.texi(,8676) * New Indices::                 How to define your own indices.
8532texinfo.texi(,8677) @end menu
8533texinfo.texi(,8678)
8534texinfo.texi(,8679) @node Index Entries, Predefined Indices, Indices, Indices
8535texinfo.texi(,8680) @comment  node-name,  next,  previous,  up
8536texinfo.texi(,8681) @section Making Index Entries
8537texinfo.texi(,8682) @cindex Index entries, making
8538texinfo.texi(,8683) @cindex Entries, making index
8539texinfo.texi(,8684)
8540texinfo.texi(,8685) When you are making index entries, it is good practice to think of the
8541texinfo.texi(,8686) different ways people may look for something.  Different people
8542texinfo.texi(,8687) @emph{do not} think of the same words when they look something up.  A
8543texinfo.texi(,8688) helpful index will have items indexed under all the different words
8544texinfo.texi(,8689) that people may use.  For example, one reader may think it obvious that
8545texinfo.texi(,8690) the two-letter names for indices should be listed under ``Indices,
8546texinfo.texi(,8691) two-letter names'', since the word ``Index'' is the general concept.
8547texinfo.texi(,8692) But another reader may remember the specific concept of two-letter
8548texinfo.texi(,8693) names and search for the entry listed as ``Two letter names for
8549texinfo.texi(,8694) indices''.  A good index will have both entries and will help both
8550texinfo.texi(,8695) readers.@refill
8551texinfo.texi(,8696)
8552texinfo.texi(,8697) Like typesetting, the construction of an index is a highly skilled,
8553texinfo.texi(,8698) professional art, the subtleties of which are not appreciated until you
8554texinfo.texi(,8699) need to do it yourself.@refill
8555texinfo.texi(,8700)
8556texinfo.texi(,8701) @xref{Printing Indices & Menus}, for information about printing an index
8557texinfo.texi(,8702) at the end of a book or creating an index menu in an Info file.@refill
8558texinfo.texi(,8703)
8559texinfo.texi(,8704) @node Predefined Indices, Indexing Commands, Index Entries, Indices
8560texinfo.texi(,8705) @comment  node-name,  next,  previous,  up
8561texinfo.texi(,8706) @section Predefined Indices
8562texinfo.texi(,8707)
8563texinfo.texi(,8708) Texinfo provides six predefined indices:@refill
8564texinfo.texi(,8709)
8565texinfo.texi(,8710) @itemize @bullet
8566texinfo.texi(,8711) @item
8567texinfo.texi(,8712) A @dfn{concept index} listing concepts that are discussed.@refill
8568texinfo.texi(,8713)
8569texinfo.texi(,8714) @item
8570texinfo.texi(,8715) A @dfn{function index} listing functions (such as entry points of
8571texinfo.texi(,8716) libraries).@refill
8572texinfo.texi(,8717)
8573texinfo.texi(,8718) @item
8574texinfo.texi(,8719) A @dfn{variables index} listing variables (such as global variables
8575texinfo.texi(,8720) of libraries).@refill
8576texinfo.texi(,8721)
8577texinfo.texi(,8722) @item
8578texinfo.texi(,8723) A @dfn{keystroke index} listing keyboard commands.@refill
8579texinfo.texi(,8724)
8580texinfo.texi(,8725) @item
8581texinfo.texi(,8726) A @dfn{program index} listing names of programs.@refill
8582texinfo.texi(,8727)
8583texinfo.texi(,8728) @item
8584texinfo.texi(,8729) A @dfn{data type index} listing data types (such as structures defined in
8585texinfo.texi(,8730) header files).@refill
8586texinfo.texi(,8731) @end itemize
8587texinfo.texi(,8732)
8588texinfo.texi(,8733) @noindent
8589texinfo.texi(,8734) Not every manual needs all of these, and most manuals use two or three
8590texinfo.texi(,8735) of them.  This manual has two indices: a
8591texinfo.texi(,8736) concept index and an @@-command index (that is actually the function
8592texinfo.texi(,8737) index but is called a command index in the chapter heading).  Two or
8593texinfo.texi(,8738) more indices can be combined into one using the @code{@@synindex} or
8594texinfo.texi(,8739) @code{@@syncodeindex} commands.  @xref{Combining Indices}.@refill
8595texinfo.texi(,8740)
8596texinfo.texi(,8741) @node Indexing Commands, Combining Indices, Predefined Indices, Indices
8597texinfo.texi(,8742) @comment  node-name,  next,  previous,  up
8598texinfo.texi(,8743) @section Defining the Entries of an Index
8599texinfo.texi(,8744) @cindex Defining indexing entries
8600texinfo.texi(,8745) @cindex Index entries
8601texinfo.texi(,8746) @cindex Entries for an index
8602texinfo.texi(,8747) @cindex Specifying index entries
8603texinfo.texi(,8748) @cindex Creating index entries
8604texinfo.texi(,8749)
8605texinfo.texi(,8750) The data to make an index come from many individual indexing commands
8606texinfo.texi(,8751) scattered throughout the Texinfo source file.  Each command says to add
8607texinfo.texi(,8752) one entry to a particular index; after formatting, the index will give
8608texinfo.texi(,8753) the current page number or node name as the reference.@refill
8609texinfo.texi(,8754)
8610texinfo.texi(,8755) An index entry consists of an indexing command at the beginning of a
8611texinfo.texi(,8756) line followed, on the rest of the line, by the entry.@refill
8612texinfo.texi(,8757)
8613texinfo.texi(,8758) For example, this section begins with the following five entries for
8614texinfo.texi(,8759) the concept index:@refill
8615texinfo.texi(,8760)
8616texinfo.texi(,8761) @example
8617texinfo.texi(,8762) @@cindex Defining indexing entries
8618texinfo.texi(,8763) @@cindex Index entries
8619texinfo.texi(,8764) @@cindex Entries for an index
8620texinfo.texi(,8765) @@cindex Specifying index entries
8621texinfo.texi(,8766) @@cindex Creating index entries
8622texinfo.texi(,8767) @end example
8623texinfo.texi(,8768)
8624texinfo.texi(,8769) Each predefined index has its own indexing command---@code{@@cindex}
8625texinfo.texi(,8770) for the concept index, @code{@@findex} for the function index, and so
8626texinfo.texi(,8771) on.@refill
8627texinfo.texi(,8772)
8628texinfo.texi(,8773) @cindex Writing index entries
8629texinfo.texi(,8774) @cindex Index entry writing
8630texinfo.texi(,8775) Concept index entries consist of text.  The best way to write an index
8631texinfo.texi(,8776) is to choose entries that are terse yet clear.  If you can do this,
8632texinfo.texi(,8777) the index often looks better if the entries are not capitalized, but
8633texinfo.texi(,8778) written just as they would appear in the middle of a sentence.
8634texinfo.texi(,8779) (Capitalize proper names and acronyms that always call for upper case
8635texinfo.texi(,8780) letters.)  This is the case convention we use in most GNU manuals'
8636texinfo.texi(,8781) indices.
8637texinfo.texi(,8782)
8638texinfo.texi(,8783) If you don't see how to make an entry terse yet clear, make it longer
8639texinfo.texi(,8784) and clear---not terse and confusing.  If many of the entries are several
8640texinfo.texi(,8785) words long, the index may look better if you use a different convention:
8641texinfo.texi(,8786) to capitalize the first word of each entry.  But do not capitalize a
8642texinfo.texi(,8787) case-sensitive name such as a C or Lisp function name or a shell
8643texinfo.texi(,8788) command; that would be a spelling error.
8644texinfo.texi(,8789)
8645texinfo.texi(,8790) Whichever case convention you use, please use it consistently!
8646texinfo.texi(,8791)
8647texinfo.texi(,8792) Entries in indices other than the concept index are symbol names in
8648texinfo.texi(,8793) programming languages, or program names; these names are usually
8649texinfo.texi(,8794) case-sensitive, so use upper and lower case as required for them.
8650texinfo.texi(,8795)
8651texinfo.texi(,8796) By default, entries for a concept index are printed in a small roman
8652texinfo.texi(,8797) font and entries for the other indices are printed in a small
8653texinfo.texi(,8798) @code{@@code} font.  You may change the way part of an entry is
8654texinfo.texi(,8799) printed with the usual Texinfo commands, such as @code{@@file} for
8655texinfo.texi(,8800) file names and @code{@@emph} for emphasis (@pxref{Marking
8656texinfo.texi(,8801) Text}).@refill
8657texinfo.texi(,8802) @cindex Index font types
8658texinfo.texi(,8803)
8659texinfo.texi(,8804) @cindex Predefined indexing commands
8660texinfo.texi(,8805) @cindex Indexing commands, predefined
8661texinfo.texi(,8806) The six indexing commands for predefined indices are:
8662texinfo.texi(,8807)
8663texinfo.texi(,8808) @table @code
8664texinfo.texi(,8809) @item @@cindex @var{concept}
8665texinfo.texi(,8810) @findex cindex
8666texinfo.texi(,8811) Make an entry in the concept index for @var{concept}.@refill
8667texinfo.texi(,8812)
8668texinfo.texi(,8813) @item @@findex @var{function}
8669texinfo.texi(,8814) @findex findex
8670texinfo.texi(,8815) Make an entry in the function index for @var{function}.@refill
8671texinfo.texi(,8816)
8672texinfo.texi(,8817) @item @@vindex @var{variable}
8673texinfo.texi(,8818) @findex vindex
8674texinfo.texi(,8819) Make an entry in the variable index for @var{variable}.@refill
8675texinfo.texi(,8820)
8676texinfo.texi(,8821) @item @@kindex @var{keystroke}
8677texinfo.texi(,8822) @findex kindex
8678texinfo.texi(,8823) Make an entry in the key index for @var{keystroke}.@refill
8679texinfo.texi(,8824)
8680texinfo.texi(,8825) @item @@pindex @var{program}
8681texinfo.texi(,8826) @findex pindex
8682texinfo.texi(,8827) Make an entry in the program index for @var{program}.@refill
8683texinfo.texi(,8828)
8684texinfo.texi(,8829) @item @@tindex @var{data type}
8685texinfo.texi(,8830) @findex tindex
8686texinfo.texi(,8831) Make an entry in the data type index for @var{data type}.@refill
8687texinfo.texi(,8832) @end table
8688texinfo.texi(,8833)
8689texinfo.texi(,8834) @quotation
8690texinfo.texi(,8835) @strong{Caution:} Do not use a colon in an index entry.  In Info, a
8691texinfo.texi(,8836) colon separates the menu entry name from the node name, so a colon in
8692texinfo.texi(,8837) the entry itself confuses Info.  @xref{Menu Parts, , The Parts of a
8693texinfo.texi(,8838) Menu}, for more information about the structure of a menu entry.
8694texinfo.texi(,8839) @end quotation
8695texinfo.texi(,8840)
8696texinfo.texi(,8841) You are not actually required to use the predefined indices for their
8697texinfo.texi(,8842) canonical purposes.  For example, suppose you wish to index some C
8698texinfo.texi(,8843) preprocessor macros.  You could put them in the function index along
8699texinfo.texi(,8844) with actual functions, just by writing @code{@@findex} commands for
8700texinfo.texi(,8845) them; then, when you print the ``Function Index'' as an unnumbered
8701texinfo.texi(,8846) chapter, you could give it the title `Function and Macro Index' and
8702texinfo.texi(,8847) all will be consistent for the reader.  Or you could put the macros in
8703texinfo.texi(,8848) with the data types by writing @code{@@tindex} commands for them, and
8704texinfo.texi(,8849) give that index a suitable title so the reader will understand.
8705texinfo.texi(,8850) (@xref{Printing Indices & Menus}.)@refill
8706texinfo.texi(,8851)
8707texinfo.texi(,8852) @node Combining Indices, New Indices, Indexing Commands, Indices
8708texinfo.texi(,8853) @comment node-name,  next,  previous,  up
8709texinfo.texi(,8854) @section Combining Indices
8710texinfo.texi(,8855) @cindex Combining indices
8711texinfo.texi(,8856) @cindex Indices, combining them
8712texinfo.texi(,8857)
8713texinfo.texi(,8858) Sometimes you will want to combine two disparate indices such as functions
8714texinfo.texi(,8859) and concepts, perhaps because you have few enough of one of them that
8715texinfo.texi(,8860) a separate index for them would look silly.@refill
8716texinfo.texi(,8861)
8717texinfo.texi(,8862) You could put functions into the concept index by writing
8718texinfo.texi(,8863) @code{@@cindex} commands for them instead of @code{@@findex} commands,
8719texinfo.texi(,8864) and produce a consistent manual by printing the concept index with the
8720texinfo.texi(,8865) title `Function and Concept Index' and not printing the `Function
8721texinfo.texi(,8866) Index' at all; but this is not a robust procedure.  It works only if
8722texinfo.texi(,8867) your document is never included as part of another
8723texinfo.texi(,8868) document that is designed to have a separate function index; if your
8724texinfo.texi(,8869) document were to be included with such a document, the functions from
8725texinfo.texi(,8870) your document and those from the other would not end up together.
8726texinfo.texi(,8871) Also, to make your function names appear in the right font in the
8727texinfo.texi(,8872) concept index, you would need to enclose every one of them between
8728texinfo.texi(,8873) the braces of @code{@@code}.@refill
8729texinfo.texi(,8874)
8730texinfo.texi(,8875) @menu
8731texinfo.texi(,8876) * syncodeindex::                How to merge two indices, using @code{@@code}
8732texinfo.texi(,8877)                                   font for the merged-from index.
8733texinfo.texi(,8878) * synindex::                    How to merge two indices, using the
8734texinfo.texi(,8879)                                   default font of the merged-to index.
8735texinfo.texi(,8880) @end menu
8736texinfo.texi(,8881)
8737texinfo.texi(,8882) @node syncodeindex
8738texinfo.texi(,8883) @subsection @code{@@syncodeindex}
8739texinfo.texi(,8884) @findex syncodeindex
8740texinfo.texi(,8885)
8741texinfo.texi(,8886) When you want to combine functions and concepts into one index, you
8742texinfo.texi(,8887) should index the functions with @code{@@findex} and index the concepts
8743texinfo.texi(,8888) with @code{@@cindex}, and use the @code{@@syncodeindex} command to
8744texinfo.texi(,8889) redirect the function index entries into the concept index.@refill
8745texinfo.texi(,8890) @findex syncodeindex
8746texinfo.texi(,8891)
8747texinfo.texi(,8892) The @code{@@syncodeindex} command takes two arguments; they are the name
8748texinfo.texi(,8893) of the index to redirect, and the name of the index to redirect it to.
8749texinfo.texi(,8894) The template looks like this:@refill
8750texinfo.texi(,8895)
8751texinfo.texi(,8896) @example
8752texinfo.texi(,8897) @@syncodeindex @var{from} @var{to}
8753texinfo.texi(,8898) @end example
8754texinfo.texi(,8899)
8755texinfo.texi(,8900) @cindex Predefined names for indices
8756texinfo.texi(,8901) @cindex Two letter names for indices
8757texinfo.texi(,8902) @cindex Indices, two letter names
8758texinfo.texi(,8903) @cindex Names for indices
8759texinfo.texi(,8904) For this purpose, the indices are given two-letter names:@refill
8760texinfo.texi(,8905)
8761texinfo.texi(,8906) @table @samp
8762texinfo.texi(,8907) @item cp
8763texinfo.texi(,8908) concept index
8764texinfo.texi(,8909) @item fn
8765texinfo.texi(,8910) function index
8766texinfo.texi(,8911) @item vr
8767texinfo.texi(,8912) variable index
8768texinfo.texi(,8913) @item ky
8769texinfo.texi(,8914) key index
8770texinfo.texi(,8915) @item pg
8771texinfo.texi(,8916) program index
8772texinfo.texi(,8917) @item tp
8773texinfo.texi(,8918) data type index
8774texinfo.texi(,8919) @end table
8775texinfo.texi(,8920)
8776texinfo.texi(,8921) Write an @code{@@syncodeindex} command before or shortly after the
8777texinfo.texi(,8922) end-of-header line at the beginning of a Texinfo file.  For example,
8778texinfo.texi(,8923) to merge a function index with a concept index, write the
8779texinfo.texi(,8924) following:@refill
8780texinfo.texi(,8925)
8781texinfo.texi(,8926) @example
8782texinfo.texi(,8927) @@syncodeindex fn cp
8783texinfo.texi(,8928) @end example
8784texinfo.texi(,8929)
8785texinfo.texi(,8930) @noindent
8786texinfo.texi(,8931) This will cause all entries designated for the function index to merge
8787texinfo.texi(,8932) in with the concept index instead.@refill
8788texinfo.texi(,8933)
8789texinfo.texi(,8934) To merge both a variables index and a function index into a concept
8790texinfo.texi(,8935) index, write the following:@refill
8791texinfo.texi(,8936)
8792texinfo.texi(,8937) @example
8793texinfo.texi(,8938) @group
8794texinfo.texi(,8939) @@syncodeindex vr cp
8795texinfo.texi(,8940) @@syncodeindex fn cp
8796texinfo.texi(,8941) @end group
8797texinfo.texi(,8942) @end example
8798texinfo.texi(,8943)
8799texinfo.texi(,8944) @cindex Fonts for indices
8800texinfo.texi(,8945) The @code{@@syncodeindex} command puts all the entries from the `from'
8801texinfo.texi(,8946) index (the redirected index) into the @code{@@code} font, overriding
8802texinfo.texi(,8947) whatever default font is used by the index to which the entries are
8803texinfo.texi(,8948) now directed.  This way, if you direct function names from a function
8804texinfo.texi(,8949) index into a concept index, all the function names are printed in the
8805texinfo.texi(,8950) @code{@@code} font as you would expect.@refill
8806texinfo.texi(,8951)
8807texinfo.texi(,8952) @node synindex,  , syncodeindex, Combining Indices
8808texinfo.texi(,8953) @subsection @code{@@synindex}
8809texinfo.texi(,8954) @findex synindex
8810texinfo.texi(,8955)
8811texinfo.texi(,8956) The @code{@@synindex} command is nearly the same as the
8812texinfo.texi(,8957) @code{@@syncodeindex} command, except that it does not put the
8813texinfo.texi(,8958) `from' index  entries into the @code{@@code} font; rather it puts
8814texinfo.texi(,8959) them in the roman font.  Thus, you use @code{@@synindex} when you
8815texinfo.texi(,8960) merge a concept index into a function index.@refill
8816texinfo.texi(,8961)
8817texinfo.texi(,8962) @xref{Printing Indices & Menus}, for information about printing an index
8818texinfo.texi(,8963) at the end of a book or creating an index menu in an Info file.@refill
8819texinfo.texi(,8964)
8820texinfo.texi(,8965) @node New Indices,  , Combining Indices, Indices
8821texinfo.texi(,8966) @section Defining New Indices
8822texinfo.texi(,8967) @cindex Defining new indices
8823texinfo.texi(,8968) @cindex Indices, defining new
8824texinfo.texi(,8969) @cindex New index defining
8825texinfo.texi(,8970) @findex defindex
8826texinfo.texi(,8971) @findex defcodeindex
8827texinfo.texi(,8972)
8828texinfo.texi(,8973) In addition to the predefined indices, you may use the
8829texinfo.texi(,8974) @code{@@defindex} and @code{@@defcodeindex} commands to define new
8830texinfo.texi(,8975) indices.  These commands create new indexing @@-commands with which
8831texinfo.texi(,8976) you mark index entries.  The @code{@@defindex }command is used like
8832texinfo.texi(,8977) this:@refill
8833texinfo.texi(,8978)
8834texinfo.texi(,8979) @example
8835texinfo.texi(,8980) @@defindex @var{name}
8836texinfo.texi(,8981) @end example
8837texinfo.texi(,8982)
8838texinfo.texi(,8983) The name of an index should be a two letter word, such as @samp{au}.
8839texinfo.texi(,8984) For example:@refill
8840texinfo.texi(,8985)
8841texinfo.texi(,8986) @example
8842texinfo.texi(,8987) @@defindex au
8843texinfo.texi(,8988) @end example
8844texinfo.texi(,8989)
8845texinfo.texi(,8990) This defines a new index, called the @samp{au} index.  At the same
8846texinfo.texi(,8991) time, it creates a new indexing command, @code{@@auindex}, that you
8847texinfo.texi(,8992) can use to make index entries.  Use the new indexing command just as
8848texinfo.texi(,8993) you would use a predefined indexing command.@refill
8849texinfo.texi(,8994)
8850texinfo.texi(,8995) For example, here is a section heading followed by a concept index
8851texinfo.texi(,8996) entry and two @samp{au} index entries.@refill
8852texinfo.texi(,8997)
8853texinfo.texi(,8998) @example
8854texinfo.texi(,8999) @@section Cognitive Semantics
8855texinfo.texi(,9000) @@cindex kinesthetic image schemas
8856texinfo.texi(,9001) @@auindex Johnson, Mark
8857texinfo.texi(,9002) @@auindex Lakoff, George
8858texinfo.texi(,9003) @end example
8859texinfo.texi(,9004)
8860texinfo.texi(,9005) @noindent
8861texinfo.texi(,9006) (Evidently, @samp{au} serves here as an abbreviation for ``author''.)
8862texinfo.texi(,9007) Texinfo constructs the new indexing command by concatenating the name
8863texinfo.texi(,9008) of the index with @samp{index}; thus, defining an @samp{au} index
8864texinfo.texi(,9009) leads to the automatic creation of an @code{@@auindex} command.@refill
8865texinfo.texi(,9010)
8866texinfo.texi(,9011) Use the @code{@@printindex} command to print the index, as you do with
8867texinfo.texi(,9012) the predefined indices.  For example:@refill
8868texinfo.texi(,9013)
8869texinfo.texi(,9014) @example
8870texinfo.texi(,9015) @group
8871texinfo.texi(,9016) @@node Author Index, Subject Index, , Top
8872texinfo.texi(,9017) @@unnumbered Author Index
8873texinfo.texi(,9018)
8874texinfo.texi(,9019) @@printindex au
8875texinfo.texi(,9020) @end group
8876texinfo.texi(,9021) @end example
8877texinfo.texi(,9022)
8878texinfo.texi(,9023) The @code{@@defcodeindex} is like the @code{@@defindex} command, except
8879texinfo.texi(,9024) that, in the printed output, it prints entries in an @code{@@code} font
8880texinfo.texi(,9025) instead of a roman font.  Thus, it parallels the @code{@@findex} command
8881texinfo.texi(,9026) rather than the @code{@@cindex} command.@refill
8882texinfo.texi(,9027)
8883texinfo.texi(,9028) You should define new indices within or right after the end-of-header
8884texinfo.texi(,9029) line of a Texinfo file, before any @code{@@synindex} or
8885texinfo.texi(,9030) @code{@@syncodeindex} commands (@pxref{Texinfo File Header}).
8886texinfo.texi(,9031)
8887texinfo.texi(,9032)
8888texinfo.texi(,9033) @node Insertions
8889texinfo.texi(,9034) @chapter Special Insertions
8890texinfo.texi(,9035) @cindex Inserting special characters and symbols
8891texinfo.texi(,9036) @cindex Special insertions
8892texinfo.texi(,9037)
8893texinfo.texi(,9038) Texinfo provides several commands for inserting characters that have
8894texinfo.texi(,9039) special meaning in Texinfo, such as braces, and for other graphic
8895texinfo.texi(,9040) elements that do not correspond to simple characters you can type.
8896texinfo.texi(,9041)
8897texinfo.texi(,9059)
8898texinfo.texi(,9060) @menu
8899texinfo.texi(,9061) * Braces Atsigns::              How to insert braces, @samp{@@}.
8900texinfo.texi(,9062) * Inserting Space::             How to insert the right amount of space
8901texinfo.texi(,9063)                                   within a sentence.
8902texinfo.texi(,9064) * Inserting Accents::           How to insert accents and special characters.
8903texinfo.texi(,9065) * Dots Bullets::                How to insert dots and bullets.
8904texinfo.texi(,9066) * TeX and copyright::           How to insert the @TeX{} logo
8905texinfo.texi(,9067)                                   and the copyright symbol.
8906texinfo.texi(,9068) * pounds::                      How to insert the pounds currency symbol.
8907texinfo.texi(,9069) * minus::                       How to insert a minus sign.
8908texinfo.texi(,9070) * math::                        How to format a mathematical expression.
8909texinfo.texi(,9071) * Glyphs::                      How to indicate results of evaluation,
8910texinfo.texi(,9072)                                   expansion of macros, errors, etc.
8911texinfo.texi(,9073) * Footnotes::                   How to include footnotes.
8912texinfo.texi(,9074) * Images::                      How to include graphics.
8913texinfo.texi(,9075) @end menu
8914texinfo.texi(,9076)
8915texinfo.texi(,9077)
8916texinfo.texi(,9078) @node Braces Atsigns, Inserting Space, Insertions, Insertions
8917texinfo.texi(,9079) @section Inserting @@ and Braces
8918texinfo.texi(,9080) @cindex Inserting @@, braces
8919texinfo.texi(,9081) @cindex Braces, inserting
8920texinfo.texi(,9082) @cindex Special characters, commands to insert
8921texinfo.texi(,9083) @cindex Commands to insert special characters
8922texinfo.texi(,9084)
8923texinfo.texi(,9085) @samp{@@} and curly braces are special characters in Texinfo.  To insert
8924texinfo.texi(,9086) these characters so they appear in text, you must put an @samp{@@} in
8925texinfo.texi(,9087) front of these characters to prevent Texinfo from misinterpreting
8926texinfo.texi(,9088) them.
8927texinfo.texi(,9089)
8928texinfo.texi(,9090) Do not put braces after any of these commands; they are not
8929texinfo.texi(,9091) necessary.
8930texinfo.texi(,9092)
8931texinfo.texi(,9093) @menu
8932texinfo.texi(,9094) * Inserting An Atsign::         How to insert @samp{@@}.
8933texinfo.texi(,9095) * Inserting Braces::            How to insert @samp{@{} and @samp{@}}.
8934texinfo.texi(,9096) @end menu
8935texinfo.texi(,9097)
8936texinfo.texi(,9098) @node Inserting An Atsign, Inserting Braces, Braces Atsigns, Braces Atsigns
8937texinfo.texi(,9099) @subsection Inserting @samp{@@} with @@@@
8938texinfo.texi(,9100) @findex @@ @r{(literal @samp{@@})}
8939texinfo.texi(,9101)
8940texinfo.texi(,9102) @code{@@@@} stands for a single @samp{@@} in either printed or Info
8941texinfo.texi(,9103) output.
8942texinfo.texi(,9104)
8943texinfo.texi(,9105) Do not put braces after an @code{@@@@} command.
8944texinfo.texi(,9106)
8945texinfo.texi(,9107)
8946texinfo.texi(,9108) @node Inserting Braces
8947texinfo.texi(,9109) @subsection Inserting @samp{@{} and @samp{@}}with @@@{ and @@@}
8948texinfo.texi(,9110) @findex @{ @r{(literal @samp{@{})}
8949texinfo.texi(,9111) @findex @} @r{(literal @samp{@}})}
8950texinfo.texi(,9112)
8951texinfo.texi(,9113) @code{@@@{} stands for a single @samp{@{} in either printed or Info
8952texinfo.texi(,9114) output.
8953texinfo.texi(,9115)
8954texinfo.texi(,9116) @code{@@@}} stands for a single @samp{@}} in either printed or Info
8955texinfo.texi(,9117) output.
8956texinfo.texi(,9118)
8957texinfo.texi(,9119) Do not put braces after either an @code{@@@{} or an @code{@@@}}
8958texinfo.texi(,9120) command.
8959texinfo.texi(,9121)
8960texinfo.texi(,9122)
8961texinfo.texi(,9123) @node Inserting Space
8962texinfo.texi(,9124) @section Inserting Space
8963texinfo.texi(,9125)
8964texinfo.texi(,9126) @cindex Inserting space
8965texinfo.texi(,9127) @cindex Spacing, inserting
8966texinfo.texi(,9128) The following sections describe commands that control spacing of various
8967texinfo.texi(,9129) kinds within and after sentences.
8968texinfo.texi(,9130)
8969texinfo.texi(,9131) @menu
8970texinfo.texi(,9132) * Not Ending a Sentence::       Sometimes a . doesn't end a sentence.
8971texinfo.texi(,9133) * Ending a Sentence::           Sometimes it does.
8972texinfo.texi(,9134) * Multiple Spaces::             Inserting multiple spaces.
8973texinfo.texi(,9135) * dmn::                         How to format a dimension.
8974texinfo.texi(,9136) @end menu
8975texinfo.texi(,9137)
8976texinfo.texi(,9138)
8977texinfo.texi(,9139) @node Not Ending a Sentence
8978texinfo.texi(,9140) @subsection Not Ending a Sentence
8979texinfo.texi(,9141)
8980texinfo.texi(,9142) @cindex Not ending a sentence
8981texinfo.texi(,9143) @cindex Sentence non-ending punctuation
8982texinfo.texi(,9144) @cindex Periods, inserting
8983texinfo.texi(,9145) Depending on whether a period or exclamation point or question mark is
8984texinfo.texi(,9146) inside or at the end of a sentence, less or more space is inserted after
8985texinfo.texi(,9147) a period in a typeset manual.  Since it is not always possible
8986texinfo.texi(,9148) to determine when a period ends a sentence and when it is used
8987texinfo.texi(,9149) in an abbreviation, special commands are needed in some circumstances.
8988texinfo.texi(,9150) Usually, Texinfo can guess how to handle periods, so you do not need to
8989texinfo.texi(,9151) use the special commands; you just enter a period as you would if you
8990texinfo.texi(,9152) were using a typewriter, which means you put two spaces after the
8991texinfo.texi(,9153) period, question mark, or exclamation mark that ends a sentence.
8992texinfo.texi(,9154)
8993texinfo.texi(,9155) @findex <colon> @r{(suppress widening)}
8994texinfo.texi(,9156) Use the @code{@@:}@: command after a period, question mark,
8995texinfo.texi(,9157) exclamation mark, or colon that should not be followed by extra space.
8996texinfo.texi(,9158) For example, use @code{@@:}@: after periods that end abbreviations
8997texinfo.texi(,9159) which are not at the ends of sentences.
8998texinfo.texi(,9160)
8999texinfo.texi(,9161) For example,
9000texinfo.texi(,9162)
9001texinfo.texi(,9163) @example
9002texinfo.texi(,9164) The s.o.p.@@: has three parts @dots{}
9003texinfo.texi(,9165) The s.o.p. has three parts @dots{}
9004texinfo.texi(,9166) @end example
9005texinfo.texi(,9167)
9006texinfo.texi(,9168) @noindent
9007texinfo.texi(,9170) produces
9008texinfo.texi(,9177)
9009texinfo.texi(,9178) @quotation
9010texinfo.texi(,9179) The s.o.p.@: has three parts @dots{}@*
9011texinfo.texi(,9180) The s.o.p. has three parts @dots{}
9012texinfo.texi(,9181) @end quotation
9013texinfo.texi(,9182)
9014texinfo.texi(,9183) @noindent
9015texinfo.texi(,9184) (Incidentally, @samp{s.o.p.} is an abbreviation for ``Standard Operating
9016texinfo.texi(,9185) Procedure''.)
9017texinfo.texi(,9186)
9018texinfo.texi(,9187) @code{@@:} has no effect on the Info output.  Do not put braces after
9019texinfo.texi(,9188) @code{@@:}.
9020texinfo.texi(,9189)
9021texinfo.texi(,9190)
9022texinfo.texi(,9191) @node Ending a Sentence, Multiple Spaces, Not Ending a Sentence, Inserting Space
9023texinfo.texi(,9192) @subsection Ending a Sentence
9024texinfo.texi(,9193)
9025texinfo.texi(,9194) @cindex Ending a Sentence
9026texinfo.texi(,9195) @cindex Sentence ending punctuation
9027texinfo.texi(,9196)
9028texinfo.texi(,9197) @findex .  @r{(end of sentence)}
9029texinfo.texi(,9198) @findex ! @r{(end of sentence)}
9030texinfo.texi(,9199) @findex ? @r{(end of sentence)}
9031texinfo.texi(,9200) Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an
9032texinfo.texi(,9201) exclamation point, and @code{@@?}@: instead of a question mark at the end
9033texinfo.texi(,9202) of a sentence that ends with a single capital letter.  Otherwise, @TeX{}
9034texinfo.texi(,9203) will think the letter is an abbreviation and will not insert the correct
9035texinfo.texi(,9204) end-of-sentence spacing.  Here is an example:
9036texinfo.texi(,9205)
9037texinfo.texi(,9206) @example
9038texinfo.texi(,9207) Give it to M.I.B. and to M.E.W@@.  Also, give it to R.J.C@@.
9039texinfo.texi(,9208) Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.
9040texinfo.texi(,9209) @end example
9041texinfo.texi(,9210)
9042texinfo.texi(,9211) @noindent
9043texinfo.texi(,9213) produces
9044texinfo.texi(,9220)
9045texinfo.texi(,9221) @quotation
9046texinfo.texi(,9222) Give it to M.I.B. and to M.E.W@.  Also, give it to R.J.C@.@*
9047texinfo.texi(,9223) Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.
9048texinfo.texi(,9224) @end quotation
9049texinfo.texi(,9225)
9050texinfo.texi(,9226) In the Info file output, @code{@@.}@: is equivalent to a simple
9051texinfo.texi(,9227) @samp{.}; likewise for @code{@@!}@: and @code{@@?}@:.
9052texinfo.texi(,9228)
9053texinfo.texi(,9229) The meanings of @code{@@:} and @code{@@.}@: in Texinfo are designed to
9054texinfo.texi(,9230) work well with the Emacs sentence motion commands (@pxref{Sentences,,,
9055texinfo.texi(,9231) emacs, The GNU Emacs Manual}).
9056texinfo.texi(,9232)
9057texinfo.texi(,9233) Do not put braces after any of these commands.
9058texinfo.texi(,9234)
9059texinfo.texi(,9235)
9060texinfo.texi(,9236) @node Multiple Spaces, dmn, Ending a Sentence, Inserting Space
9061texinfo.texi(,9237) @subsection Multiple Spaces
9062texinfo.texi(,9238)
9063texinfo.texi(,9239) @cindex Multiple spaces
9064texinfo.texi(,9240) @cindex Whitespace, inserting
9065texinfo.texi(,9241) @cindex Space, inserting horizontal
9066texinfo.texi(,9242) @findex (space)
9067texinfo.texi(,9243) @findex (tab)
9068texinfo.texi(,9244) @findex (newline)
9069texinfo.texi(,9245)
9070texinfo.texi(,9246) Ordinarily, @TeX{} collapses multiple whitespace characters (space, tab,
9071texinfo.texi(,9247) and newline) into a single space.  Info output, on the other hand,
9072texinfo.texi(,9248) preserves whitespace as you type it, except for changing a newline into
9073texinfo.texi(,9249) a space; this is why it is important to put two spaces at the end of
9074texinfo.texi(,9250) sentences in Texinfo documents.
9075texinfo.texi(,9251)
9076texinfo.texi(,9252) Occasionally, you may want to actually insert several consecutive
9077texinfo.texi(,9253) spaces, either for purposes of example (what your program does with
9078texinfo.texi(,9254) multiple spaces as input), or merely for purposes of appearance in
9079texinfo.texi(,9255) headings or lists.  Texinfo supports three commands:
9080texinfo.texi(,9256) @code{@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all of
9081texinfo.texi(,9257) which insert a single space into the output.  (Here,
9082texinfo.texi(,9258) @code{@@@kbd{SPACE}} represents an @samp{@@} character followed by a
9083texinfo.texi(,9259) space, i.e., @samp{@@ }, and @kbd{TAB} and @kbd{NL} represent the tab
9084texinfo.texi(,9260) character and end-of-line, i.e., when @samp{@@} is the last character on
9085texinfo.texi(,9261) a line.)
9086texinfo.texi(,9262)
9087texinfo.texi(,9263) For example,
9088texinfo.texi(,9264) @example
9089texinfo.texi(,9265) Spacey@@ @@ @@ @@
9090texinfo.texi(,9266) example.
9091texinfo.texi(,9267) @end example
9092texinfo.texi(,9268)
9093texinfo.texi(,9269) @noindent produces
9094texinfo.texi(,9270)
9095texinfo.texi(,9271) @example
9096texinfo.texi(,9272) Spacey@ @ @ @
9097texinfo.texi(,9273) example.
9098texinfo.texi(,9274) @end example
9099texinfo.texi(,9275)
9100texinfo.texi(,9276) Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by
9101texinfo.texi(,9277) @code{@@multitable} (@pxref{Multi-column Tables}).
9102texinfo.texi(,9278)
9103texinfo.texi(,9279) Do not follow any of these commands with braces.
9104texinfo.texi(,9280)
9105texinfo.texi(,9281) To produce a non-breakable space, see @ref{w, non-breakable space}.
9106texinfo.texi(,9282)
9107texinfo.texi(,9283)
9108texinfo.texi(,9284) @node dmn
9109texinfo.texi(,9285) @subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension
9110texinfo.texi(,9286) @cindex Thin space between number, dimension
9111texinfo.texi(,9287) @cindex Dimension formatting
9112texinfo.texi(,9288) @cindex Format a dimension
9113texinfo.texi(,9289) @findex dmn
9114texinfo.texi(,9290)
9115texinfo.texi(,9291) At times, you may want to write @samp{12@dmn{pt}} or
9116texinfo.texi(,9292) @samp{8.5@dmn{in}} with little or no space between the number and the
9117texinfo.texi(,9293) abbreviation for the dimension.  You can use the @code{@@dmn} command
9118texinfo.texi(,9294) to do this.  On seeing the command, @TeX{} inserts just enough space
9119texinfo.texi(,9295) for proper typesetting; the Info formatting commands insert no space
9120texinfo.texi(,9296) at all, since the Info file does not require it.
9121texinfo.texi(,9297)
9122texinfo.texi(,9298) To use the @code{@@dmn} command, write the number and then follow it
9123texinfo.texi(,9299) immediately, with no intervening space, by @code{@@dmn}, and then by
9124texinfo.texi(,9300) the dimension within braces.  For example,
9125texinfo.texi(,9301)
9126texinfo.texi(,9302) @example
9127texinfo.texi(,9303) A4 paper is 8.27@@dmn@{in@} wide.
9128texinfo.texi(,9304) @end example
9129texinfo.texi(,9305)
9130texinfo.texi(,9306) @noindent
9131texinfo.texi(,9307) produces
9132texinfo.texi(,9308)
9133texinfo.texi(,9309) @quotation
9134texinfo.texi(,9310) A4 paper is 8.27@dmn{in} wide.
9135texinfo.texi(,9311) @end quotation
9136texinfo.texi(,9312)
9137texinfo.texi(,9313) Not everyone uses this style.  Some people prefer @w{@samp{8.27 in.@@:}}
9138texinfo.texi(,9314) or @w{@samp{8.27 inches}} to @samp{8.27@@dmn@{in@}} in the Texinfo file.
9139texinfo.texi(,9315) In these cases, however, the formatters may insert a line break between
9140texinfo.texi(,9316) the number and the dimension, so use @code{@@w} (@pxref{w}).  Also, if
9141texinfo.texi(,9317) you write a period after an abbreviation within a sentence, you should
9142texinfo.texi(,9318) write @samp{@@:} after the period to prevent @TeX{} from inserting extra
9143texinfo.texi(,9319) whitespace, as shown here.  @xref{Not Ending a Sentence}.
9144texinfo.texi(,9320)
9145texinfo.texi(,9321)
9146texinfo.texi(,9322) @node Inserting Accents
9147texinfo.texi(,9323) @section Inserting Accents
9148texinfo.texi(,9324)
9149texinfo.texi(,9325) @cindex Inserting accents
9150texinfo.texi(,9326) @cindex Accents, inserting
9151texinfo.texi(,9327) @cindex Floating accents, inserting
9152texinfo.texi(,9328)
9153texinfo.texi(,9329) Here is a table with the commands Texinfo provides for inserting
9154texinfo.texi(,9330) floating accents.  The commands with non-alphabetic names do not take
9155texinfo.texi(,9331) braces around their argument (which is taken to be the next character).
9156texinfo.texi(,9332) (Exception: @code{@@,} @emph{does} take braces around its argument.)
9157texinfo.texi(,9333) This is so as to make the source as convenient to type and read as
9158texinfo.texi(,9334) possible, since accented characters are very common in some languages.
9159texinfo.texi(,9335)
9160texinfo.texi(,9336) @findex " @r{(umlaut accent)}
9161texinfo.texi(,9337) @cindex Umlaut accent
9162texinfo.texi(,9338) @findex ' @r{(umlaut accent)}
9163texinfo.texi(,9339) @cindex Acute accent
9164texinfo.texi(,9340) @findex = @r{(macron accent)}
9165texinfo.texi(,9341) @cindex Macron accent
9166texinfo.texi(,9342) @findex ^ @r{(circumflex accent)}
9167texinfo.texi(,9343) @cindex Circumflex accent
9168texinfo.texi(,9344) @findex ` @r{(grave accent)}
9169texinfo.texi(,9345) @cindex Grave accent
9170texinfo.texi(,9346) @findex ~ @r{(tilde accent)}
9171texinfo.texi(,9347) @cindex Tilde accent
9172texinfo.texi(,9348) @findex , @r{(cedilla accent)}
9173texinfo.texi(,9349) @cindex Cedilla accent
9174texinfo.texi(,9350) @findex dotaccent
9175texinfo.texi(,9351) @cindex Dot accent
9176texinfo.texi(,9352) @findex H @r{(Hungarian umlaut accent)}
9177texinfo.texi(,9353) @cindex Hungarian umlaut accent
9178texinfo.texi(,9354) @findex ringaccent
9179texinfo.texi(,9355) @cindex Ring accent
9180texinfo.texi(,9356) @findex tieaccent
9181texinfo.texi(,9357) @cindex Tie-after accent
9182texinfo.texi(,9358) @findex u @r{(breve accent)}
9183texinfo.texi(,9359) @cindex Breve accent
9184texinfo.texi(,9360) @findex ubaraccent
9185texinfo.texi(,9361) @cindex Underbar accent
9186texinfo.texi(,9362) @findex udotaccent
9187texinfo.texi(,9363) @cindex Underdot accent
9188texinfo.texi(,9364) @findex v @r{(check accent)}
9189texinfo.texi(,9365) @cindex Check accent
9190texinfo.texi(,9366) @multitable {@@questiondown@{@}} {Output} {macron/overbar accent}
9191texinfo.texi(,9367) @item Command               @tab Output         @tab What
9192texinfo.texi(,9368) @item @t{@@"o}              @tab @"o            @tab umlaut accent
9193texinfo.texi(,9369) @item @t{@@'o}              @tab @'o            @tab acute accent
9194texinfo.texi(,9370) @item @t{@@,@{c@}}          @tab @,{c}          @tab cedilla accent
9195texinfo.texi(,9371) @item @t{@@=o}              @tab @=o            @tab macron/overbar accent
9196texinfo.texi(,9372) @item @t{@@^o}              @tab @^o            @tab circumflex accent
9197texinfo.texi(,9373) @item @t{@@`o}              @tab @`o            @tab grave accent
9198texinfo.texi(,9374) @item @t{@@~o}              @tab @~o            @tab tilde accent
9199texinfo.texi(,9375) @item @t{@@dotaccent@{o@}}  @tab @dotaccent{o}  @tab overdot accent
9200texinfo.texi(,9376) @item @t{@@H@{o@}}          @tab @H{o}          @tab long Hungarian umlaut
9201texinfo.texi(,9377) @item @t{@@ringaccent@{o@}} @tab @ringaccent{o} @tab ring accent
9202texinfo.texi(,9378) @item @t{@@tieaccent@{oo@}} @tab @tieaccent{oo} @tab tie-after accent
9203texinfo.texi(,9379) @item @t{@@u@{o@}}          @tab @u{o}          @tab breve accent
9204texinfo.texi(,9380) @item @t{@@ubaraccent@{o@}} @tab @ubaraccent{o} @tab underbar accent
9205texinfo.texi(,9381) @item @t{@@udotaccent@{o@}} @tab @udotaccent{o} @tab underdot accent
9206texinfo.texi(,9382) @item @t{@@v@{o@}}          @tab @v{o}          @tab hacek or check accent
9207texinfo.texi(,9383) @end multitable
9208texinfo.texi(,9384)
9209texinfo.texi(,9385) This table lists the Texinfo commands for inserting other characters
9210texinfo.texi(,9386) commonly used in languages other than English.
9211texinfo.texi(,9387)
9212texinfo.texi(,9388) @findex questiondown
9213texinfo.texi(,9389) @cindex @questiondown{}
9214texinfo.texi(,9390) @findex exclamdown
9215texinfo.texi(,9391) @cindex @exclamdown{}
9216texinfo.texi(,9392) @findex aa
9217texinfo.texi(,9393) @cindex @aa{}
9218texinfo.texi(,9394) @findex AA
9219texinfo.texi(,9395) @cindex @AA{}
9220texinfo.texi(,9396) @findex ae
9221texinfo.texi(,9397) @cindex @ae{}
9222texinfo.texi(,9398) @findex AE
9223texinfo.texi(,9399) @cindex @AE{}
9224texinfo.texi(,9400) @findex dotless
9225texinfo.texi(,9401) @cindex @dotless{i}
9226texinfo.texi(,9402) @cindex @dotless{j}
9227texinfo.texi(,9403) @cindex Dotless i, j
9228texinfo.texi(,9404) @findex l
9229texinfo.texi(,9405) @cindex @l{}
9230texinfo.texi(,9406) @findex L
9231texinfo.texi(,9407) @cindex @L{}
9232texinfo.texi(,9408) @findex o
9233texinfo.texi(,9409) @cindex @o{}
9234texinfo.texi(,9410) @findex O
9235texinfo.texi(,9411) @cindex @O{}
9236texinfo.texi(,9412) @findex oe
9237texinfo.texi(,9413) @cindex @oe{}
9238texinfo.texi(,9414) @findex OE
9239texinfo.texi(,9415) @cindex @OE{}
9240texinfo.texi(,9416) @findex ss
9241texinfo.texi(,9417) @cindex @ss{}
9242texinfo.texi(,9418) @cindex Es-zet
9243texinfo.texi(,9419) @cindex Sharp S
9244texinfo.texi(,9420) @cindex German S
9245texinfo.texi(,9421) @multitable {x@@questiondown@{@}} {oe,OE} {es-zet or sharp S}
9246texinfo.texi(,9422) @item @t{@@exclamdown@{@}}   @tab @exclamdown{}   @tab upside-down !
9247texinfo.texi(,9423) @item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ?
9248texinfo.texi(,9424) @item @t{@@aa@{@},@@AA@{@}}  @tab @aa{},@AA{}     @tab a,A with circle
9249texinfo.texi(,9425) @item @t{@@ae@{@},@@AE@{@}}  @tab @ae{},@AE{}     @tab ae,AE ligatures
9250texinfo.texi(,9426) @item @t{@@dotless@{i@}}     @tab @dotless{i}     @tab dotless i
9251texinfo.texi(,9427) @item @t{@@dotless@{j@}}     @tab @dotless{j}     @tab dotless j
9252texinfo.texi(,9428) @item @t{@@l@{@},@@L@{@}}    @tab @l{},@L{}       @tab suppressed-L,l
9253texinfo.texi(,9429) @item @t{@@o@{@},@@O@{@}}    @tab @o{},@O{}       @tab O,o with slash
9254texinfo.texi(,9430) @item @t{@@oe@{@},@@OE@{@}}  @tab @oe{},@OE{}     @tab oe,OE ligatures
9255texinfo.texi(,9431) @item @t{@@ss@{@}}           @tab @ss{}           @tab es-zet or sharp S
9256texinfo.texi(,9432) @end multitable
9257texinfo.texi(,9433)
9258texinfo.texi(,9434)
9259texinfo.texi(,9435) @node Dots Bullets
9260texinfo.texi(,9436) @section Inserting Ellipsis and Bullets
9261texinfo.texi(,9437) @cindex Dots, inserting
9262texinfo.texi(,9438) @cindex Bullets, inserting
9263texinfo.texi(,9439) @cindex Ellipsis, inserting
9264texinfo.texi(,9440) @cindex Inserting ellipsis
9265texinfo.texi(,9441) @cindex Inserting dots
9266texinfo.texi(,9442) @cindex Special typesetting commands
9267texinfo.texi(,9443) @cindex Typesetting commands for dots, etc.
9268texinfo.texi(,9444)
9269texinfo.texi(,9445) An @dfn{ellipsis} (a line of dots) is not typeset as a string of
9270texinfo.texi(,9446) periods, so a special command is used for ellipsis in Texinfo.  The
9271texinfo.texi(,9447) @code{@@bullet} command is special, too.  Each of these commands is
9272texinfo.texi(,9448) followed by a pair of braces, @samp{@{@}}, without any whitespace
9273texinfo.texi(,9449) between the name of the command and the braces.  (You need to use braces
9274texinfo.texi(,9450) with these commands because you can use them next to other text; without
9275texinfo.texi(,9451) the braces, the formatters would be confused.  @xref{Command Syntax, ,
9276texinfo.texi(,9452) @@-Command Syntax}, for further information.)@refill
9277texinfo.texi(,9453)
9278texinfo.texi(,9454) @menu
9279texinfo.texi(,9455) * dots::                        How to insert dots @dots{}
9280texinfo.texi(,9456) * bullet::                      How to insert a bullet.
9281texinfo.texi(,9457) @end menu
9282texinfo.texi(,9458)
9283texinfo.texi(,9459)
9284texinfo.texi(,9460) @node dots
9285texinfo.texi(,9461) @subsection @code{@@dots}@{@} (@dots{}) and @code{@@enddots}@{@} (@enddots{})
9286texinfo.texi(,9462) @findex dots
9287texinfo.texi(,9463) @findex enddots
9288texinfo.texi(,9464) @cindex Inserting dots
9289texinfo.texi(,9465) @cindex Dots, inserting
9290texinfo.texi(,9466)
9291texinfo.texi(,9467) Use the @code{@@dots@{@}} command to generate an ellipsis, which is
9292texinfo.texi(,9468) three dots in a row, appropriately spaced, like this: `@dots{}'.  Do
9293texinfo.texi(,9469) not simply write three periods in the input file; that would work for
9294texinfo.texi(,9470) the Info file output, but would produce the wrong amount of space
9295texinfo.texi(,9471) between the periods in the printed manual.
9296texinfo.texi(,9472)
9297texinfo.texi(,9473) Similarly, the @code{@@enddots@{@}} command generates an
9298texinfo.texi(,9474) end-of-sentence ellipsis (four dots) @enddots{}
9299texinfo.texi(,9475)
9300texinfo.texi(,9483)
9301texinfo.texi(,9484)
9302texinfo.texi(,9485) @node bullet
9303texinfo.texi(,9486) @subsection @code{@@bullet}@{@} (@bullet{})
9304texinfo.texi(,9487) @findex bullet
9305texinfo.texi(,9488)
9306texinfo.texi(,9489) Use the @code{@@bullet@{@}} command to generate a large round dot, or
9307texinfo.texi(,9490) the closest possible thing to one.  In Info, an asterisk is used.@refill
9308texinfo.texi(,9491)
9309texinfo.texi(,9492) Here is a bullet: @bullet{}
9310texinfo.texi(,9493)
9311texinfo.texi(,9494) When you use @code{@@bullet} in @code{@@itemize}, you do not need to
9312texinfo.texi(,9495) type the braces, because @code{@@itemize} supplies them.
9313texinfo.texi(,9496) (@xref{itemize, , @code{@@itemize}}.)@refill
9314texinfo.texi(,9497)
9315texinfo.texi(,9498)
9316texinfo.texi(,9499) @node TeX and copyright, pounds, Dots Bullets, Insertions
9317texinfo.texi(,9500) @section Inserting @TeX{} and the Copyright Symbol
9318texinfo.texi(,9501)
9319texinfo.texi(,9502) The logo `@TeX{}' is typeset in a special fashion and it needs an
9320texinfo.texi(,9503) @@-command.  The copyright symbol, `@copyright{}', is also special.
9321texinfo.texi(,9504) Each of these commands is followed by a pair of braces, @samp{@{@}},
9322texinfo.texi(,9505) without any whitespace between the name of the command and the
9323texinfo.texi(,9506) braces.@refill
9324texinfo.texi(,9507)
9325texinfo.texi(,9508) @menu
9326texinfo.texi(,9509) * tex::                         How to insert the @TeX{} logo.
9327texinfo.texi(,9510) * copyright symbol::            How to use @code{@@copyright}@{@}.
9328texinfo.texi(,9511) @end menu
9329texinfo.texi(,9512)
9330texinfo.texi(,9513)
9331texinfo.texi(,9514) @node tex
9332texinfo.texi(,9515) @subsection @code{@@TeX}@{@} (@TeX{})
9333texinfo.texi(,9516) @findex tex (command)
9334texinfo.texi(,9517)
9335texinfo.texi(,9518) Use the @code{@@TeX@{@}} command to generate `@TeX{}'.  In a printed
9336texinfo.texi(,9519) manual, this is a special logo that is different from three ordinary
9337texinfo.texi(,9520) letters.  In Info, it just looks like @samp{TeX}.  The
9338texinfo.texi(,9521) @code{@@TeX@{@}} command is unique among Texinfo commands in that the
9339texinfo.texi(,9522) @samp{T} and the @samp{X} are in upper case.@refill
9340texinfo.texi(,9523)
9341texinfo.texi(,9524)
9342texinfo.texi(,9525) @node copyright symbol
9343texinfo.texi(,9526) @subsection @code{@@copyright}@{@} (@copyright{})
9344texinfo.texi(,9527) @findex copyright
9345texinfo.texi(,9528)
9346texinfo.texi(,9529) Use the @code{@@copyright@{@}} command to generate `@copyright{}'.  In
9347texinfo.texi(,9530) a printed manual, this is a @samp{c} inside a circle, and in Info,
9348texinfo.texi(,9531) this is @samp{(C)}.@refill
9349texinfo.texi(,9532)
9350texinfo.texi(,9533)
9351texinfo.texi(,9534) @node pounds, minus, TeX and copyright, Insertions
9352texinfo.texi(,9535) @section @code{@@pounds}@{@} (@pounds{}): Pounds Sterling
9353texinfo.texi(,9536) @findex pounds
9354texinfo.texi(,9537)
9355texinfo.texi(,9538) Use the @code{@@pounds@{@}} command to generate `@pounds{}'.  In a
9356texinfo.texi(,9539) printed manual, this is the symbol for the currency pounds sterling.
9357texinfo.texi(,9540) In Info, it is a @samp{#}.  Other currency symbols are unfortunately not
9358texinfo.texi(,9541) available.
9359texinfo.texi(,9542)
9360texinfo.texi(,9543)
9361texinfo.texi(,9544) @node minus, math, pounds, Insertions
9362texinfo.texi(,9545) @section @code{@@minus}@{@} (@minus{}): Inserting a Minus Sign
9363texinfo.texi(,9546) @findex minus
9364texinfo.texi(,9547)
9365texinfo.texi(,9548) @cindex em-dash
9366texinfo.texi(,9549) @cindex hyphen
9367texinfo.texi(,9550) Use the @code{@@minus@{@}} command to generate a minus sign.  In a
9368texinfo.texi(,9551) fixed-width font, this is a single hyphen, but in a proportional font,
9369texinfo.texi(,9552) the symbol is the customary length for a minus sign---a little longer
9370texinfo.texi(,9553) than a hyphen, shorter than an em-dash:
9371texinfo.texi(,9554)
9372texinfo.texi(,9555) @display
9373texinfo.texi(,9556) @samp{@minus{}} is a minus sign generated with @samp{@@minus@{@}},
9374texinfo.texi(,9557)
9375texinfo.texi(,9558) `-' is a hyphen generated with the character @samp{-},
9376texinfo.texi(,9559)
9377texinfo.texi(,9560) `---' is an em-dash for text.
9378texinfo.texi(,9561) @end display
9379texinfo.texi(,9562)
9380texinfo.texi(,9563) @noindent
9381texinfo.texi(,9564) In the fixed-width font used by Info, @code{@@minus@{@}} is the same
9382texinfo.texi(,9565) as a hyphen.
9383texinfo.texi(,9566)
9384texinfo.texi(,9567) You should not use @code{@@minus@{@}} inside @code{@@code} or
9385texinfo.texi(,9568) @code{@@example} because the width distinction is not made in the
9386texinfo.texi(,9569) fixed-width font they use.
9387texinfo.texi(,9570)
9388texinfo.texi(,9571) When you use @code{@@minus} to specify the mark beginning each entry in
9389texinfo.texi(,9572) an itemized list, you do not need to type the braces
9390texinfo.texi(,9573) (@pxref{itemize, , @code{@@itemize}}.)
9391texinfo.texi(,9574)
9392texinfo.texi(,9575)
9393texinfo.texi(,9576) @node math
9394texinfo.texi(,9577) @section @code{@@math}: Inserting Mathematical Expressions
9395texinfo.texi(,9578) @findex math
9396texinfo.texi(,9579) @cindex Mathematical expressions
9397texinfo.texi(,9580) @cindex Formulas, mathematical
9398texinfo.texi(,9581)
9399texinfo.texi(,9582) You can write a short mathematical expression with the @code{@@math}
9400texinfo.texi(,9583) command.  Write the mathematical expression between braces, like this:
9401texinfo.texi(,9584)
9402texinfo.texi(,9585) @example
9403texinfo.texi(,9586) @@math@{(a + b)(a + b) = a^2 + 2ab + b^2@}
9404texinfo.texi(,9587) @end example
9405texinfo.texi(,9588)
9406texinfo.texi(,9599) @noindent This produces the following in Info:
9407texinfo.texi(,9601)
9408texinfo.texi(,9602) @example
9409texinfo.texi(,9603) (a + b)(a + b) = a^2 + 2ab + b^2
9410texinfo.texi(,9604) @end example
9411texinfo.texi(,9605)
9412texinfo.texi(,9606) Thus, the @code{@@math} command has no effect on the Info output.
9413texinfo.texi(,9607)
9414texinfo.texi(,9608) @code{@@math} implies @code{@@tex}.  This not only makes it possible to
9415texinfo.texi(,9609) write superscripts and subscripts (as in the above example), but also
9416texinfo.texi(,9610) allows you to use any of the plain @TeX{} math control sequences.  It's
9417texinfo.texi(,9611) conventional to use @samp{\} instead of @samp{@@} for these commands.
9418texinfo.texi(,9612) As in:
9419texinfo.texi(,9613) @example
9420texinfo.texi(,9614) @@math@{\sin 2\pi \equiv \cos 3\pi@}
9421texinfo.texi(,9615) @end example
9422texinfo.texi(,9616)
9423texinfo.texi(,9625) @noindent which looks like the input in Info and HTML:
9424texinfo.texi(,9626) @example
9425texinfo.texi(,9627) \sin 2\pi \equiv \cos 3\pi
9426texinfo.texi(,9628) @end example
9427texinfo.texi(,9629)
9428texinfo.texi(,9630) @findex \ @r{(literal \ in @code{@@math})}
9429texinfo.texi(,9631) Since @samp{\} is an escape character inside @code{@@math}, you can use
9430texinfo.texi(,9632) @code{@@\} to get a literal backslash (@code{\\} will work in @TeX{},
9431texinfo.texi(,9633) but you'll get the literal @samp{\\} in Info).  @code{@@\} is not
9432texinfo.texi(,9634) defined outside of @code{@@math}, since a @samp{\} ordinarily produces a
9433texinfo.texi(,9635) literal @samp{\}.
9434texinfo.texi(,9636)
9435texinfo.texi(,9637)
9436texinfo.texi(,9638) @cindex Displayed equations
9437texinfo.texi(,9639) @cindex Equations, displayed
9438texinfo.texi(,9640) For displayed equations, you must at present use @TeX{} directly
9439texinfo.texi(,9641) (@pxref{Raw Formatter Commands}).
9440texinfo.texi(,9642)
9441texinfo.texi(,9643)
9442texinfo.texi(,9644) @node Glyphs
9443texinfo.texi(,9645) @section Glyphs for Examples
9444texinfo.texi(,9646) @cindex Glyphs
9445texinfo.texi(,9647) @cindex Examples, glyphs for
9446texinfo.texi(,9648)
9447texinfo.texi(,9649) In Texinfo, code is often illustrated in examples that are delimited
9448texinfo.texi(,9650) by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and
9449texinfo.texi(,9651) @code{@@end lisp}.  In such examples, you can indicate the results of
9450texinfo.texi(,9652) evaluation or an expansion using @samp{@result{}} or
9451texinfo.texi(,9653) @samp{@expansion{}}.  Likewise, there are commands to insert glyphs
9452texinfo.texi(,9654) to indicate
9453texinfo.texi(,9655) printed output, error messages, equivalence of expressions, and the
9454texinfo.texi(,9656) location of point.@refill
9455texinfo.texi(,9657)
9456texinfo.texi(,9658) The glyph-insertion commands do not need to be used within an example, but
9457texinfo.texi(,9659) most often they are.  Every  glyph-insertion command is followed by a pair of
9458texinfo.texi(,9660) left- and right-hand braces.@refill
9459texinfo.texi(,9661)
9460texinfo.texi(,9662) @menu
9461texinfo.texi(,9663) * Glyphs Summary::
9462texinfo.texi(,9664) * result::                      How to show the result of expression.
9463texinfo.texi(,9665) * expansion::                   How to indicate an expansion.
9464texinfo.texi(,9666) * Print Glyph::                 How to indicate printed output.
9465texinfo.texi(,9667) * Error Glyph::                 How to indicate an error message.
9466texinfo.texi(,9668) * Equivalence::                 How to indicate equivalence.
9467texinfo.texi(,9669) * Point Glyph::                 How to indicate the location of point.
9468texinfo.texi(,9670) @end menu
9469texinfo.texi(,9671)
9470texinfo.texi(,9672)
9471texinfo.texi(,9673) @node Glyphs Summary
9472texinfo.texi(,9674) @subsection Glyphs Summary
9473texinfo.texi(,9675)
9474texinfo.texi(,9676) Here are the different glyph commands:@refill
9475texinfo.texi(,9677)
9476texinfo.texi(,9678) @table @asis
9477texinfo.texi(,9679) @item @result{}
9478texinfo.texi(,9680) @code{@@result@{@}} points to the result of an expression.@refill
9479texinfo.texi(,9681)
9480texinfo.texi(,9682) @item @expansion{}
9481texinfo.texi(,9683) @code{@@expansion@{@}} shows the results of a macro expansion.@refill
9482texinfo.texi(,9684)
9483texinfo.texi(,9685) @item @print{}
9484texinfo.texi(,9686) @code{@@print@{@}} indicates printed output.@refill
9485texinfo.texi(,9687)
9486texinfo.texi(,9688) @item @error{}
9487texinfo.texi(,9689) @code{@@error@{@}} indicates that the following text is an error
9488texinfo.texi(,9690) message.@refill
9489texinfo.texi(,9691)
9490texinfo.texi(,9692) @item @equiv{}
9491texinfo.texi(,9693) @code{@@equiv@{@}} indicates the exact equivalence of two forms.@refill
9492texinfo.texi(,9694)
9493texinfo.texi(,9695) @item @point{}
9494texinfo.texi(,9696) @code{@@point@{@}} shows the location of point.@refill
9495texinfo.texi(,9697) @end table
9496texinfo.texi(,9698)
9497texinfo.texi(,9699) @menu
9498texinfo.texi(,9700) * result::
9499texinfo.texi(,9701) * expansion::
9500texinfo.texi(,9702) * Print Glyph::
9501texinfo.texi(,9703) * Error Glyph::
9502texinfo.texi(,9704) * Equivalence::
9503texinfo.texi(,9705) * Point Glyph::
9504texinfo.texi(,9706) @end menu
9505texinfo.texi(,9707)
9506texinfo.texi(,9708)
9507texinfo.texi(,9709) @node result
9508texinfo.texi(,9710) @subsection @code{@@result@{@}} (@result{}): Indicating Evaluation
9509texinfo.texi(,9711) @cindex Result of an expression
9510texinfo.texi(,9712) @cindex Indicating evaluation
9511texinfo.texi(,9713) @cindex Evaluation glyph
9512texinfo.texi(,9714) @cindex Value of an expression, indicating
9513texinfo.texi(,9715) @findex result
9514texinfo.texi(,9716)
9515texinfo.texi(,9717) Use the @code{@@result@{@}} command to indicate the result of
9516texinfo.texi(,9718) evaluating an expression.@refill
9517texinfo.texi(,9719)
9518texinfo.texi(,9725) The @code{@@result@{@}} command is displayed as @samp{@result{}} in Info
9519texinfo.texi(,9726) and as a double stemmed arrow in the printed output.@refill
9520texinfo.texi(,9728)
9521texinfo.texi(,9729) Thus, the following,
9522texinfo.texi(,9730)
9523texinfo.texi(,9731) @lisp
9524texinfo.texi(,9732) (cdr '(1 2 3))
9525texinfo.texi(,9733)      @result{} (2 3)
9526texinfo.texi(,9734) @end lisp
9527texinfo.texi(,9735)
9528texinfo.texi(,9736) @noindent
9529texinfo.texi(,9737) may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''.
9530texinfo.texi(,9738)
9531texinfo.texi(,9739)
9532texinfo.texi(,9740) @node expansion, Print Glyph, result, Glyphs
9533texinfo.texi(,9741) @subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion
9534texinfo.texi(,9742) @cindex Expansion, indicating it
9535texinfo.texi(,9743) @findex expansion
9536texinfo.texi(,9744)
9537texinfo.texi(,9745) When an expression is a macro call, it expands into a new expression.
9538texinfo.texi(,9746) You can indicate the result of the expansion with the
9539texinfo.texi(,9747) @code{@@expansion@{@}} command.@refill
9540texinfo.texi(,9748)
9541texinfo.texi(,9754) The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}}
9542texinfo.texi(,9755) in Info and as a long arrow with a flat base in the printed output.@refill
9543texinfo.texi(,9757)
9544texinfo.texi(,9758) @need 700
9545texinfo.texi(,9759) For example, the following
9546texinfo.texi(,9760)
9547texinfo.texi(,9761) @example
9548texinfo.texi(,9762) @group
9549texinfo.texi(,9763) @@lisp
9550texinfo.texi(,9764) (third '(a b c))
9551texinfo.texi(,9765)      @@expansion@{@} (car (cdr (cdr '(a b c))))
9552texinfo.texi(,9766)      @@result@{@} c
9553texinfo.texi(,9767) @@end lisp
9554texinfo.texi(,9768) @end group
9555texinfo.texi(,9769) @end example
9556texinfo.texi(,9770)
9557texinfo.texi(,9771) @noindent
9558texinfo.texi(,9772) produces
9559texinfo.texi(,9773)
9560texinfo.texi(,9774) @lisp
9561texinfo.texi(,9775) @group
9562texinfo.texi(,9776) (third '(a b c))
9563texinfo.texi(,9777)      @expansion{} (car (cdr (cdr '(a b c))))
9564texinfo.texi(,9778)      @result{} c
9565texinfo.texi(,9779) @end group
9566texinfo.texi(,9780) @end lisp
9567texinfo.texi(,9781)
9568texinfo.texi(,9782) @noindent
9569texinfo.texi(,9783) which may be read as:
9570texinfo.texi(,9784)
9571texinfo.texi(,9785) @quotation
9572texinfo.texi(,9786) @code{(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))};
9573texinfo.texi(,9787) the result of evaluating the expression is @code{c}.
9574texinfo.texi(,9788) @end quotation
9575texinfo.texi(,9789)
9576texinfo.texi(,9790) @noindent
9577texinfo.texi(,9791) Often, as in this case, an example looks better if the
9578texinfo.texi(,9792) @code{@@expansion@{@}} and @code{@@result@{@}} commands are indented
9579texinfo.texi(,9793) five spaces.@refill
9580texinfo.texi(,9794)
9581texinfo.texi(,9795)
9582texinfo.texi(,9796) @node Print Glyph, Error Glyph, expansion, Glyphs
9583texinfo.texi(,9797) @subsection @code{@@print@{@}} (@print{}): Indicating Printed Output
9584texinfo.texi(,9798) @cindex Printed output, indicating it
9585texinfo.texi(,9799) @findex print
9586texinfo.texi(,9800)
9587texinfo.texi(,9801) Sometimes an expression will print output during its execution.  You
9588texinfo.texi(,9802) can indicate the printed output with the @code{@@print@{@}} command.@refill
9589texinfo.texi(,9803)
9590texinfo.texi(,9809) The @code{@@print@{@}} command is displayed as @samp{@print{}} in Info
9591texinfo.texi(,9810) and similarly, as a horizontal dash butting against a vertical bar, in
9592texinfo.texi(,9811) the printed output.@refill
9593texinfo.texi(,9813)
9594texinfo.texi(,9814) In the following example, the printed text is indicated with
9595texinfo.texi(,9815) @samp{@print{}}, and the value of the expression follows on the
9596texinfo.texi(,9816) last line.@refill
9597texinfo.texi(,9817)
9598texinfo.texi(,9818) @lisp
9599texinfo.texi(,9819) @group
9600texinfo.texi(,9820) (progn (print 'foo) (print 'bar))
9601texinfo.texi(,9821)      @print{} foo
9602texinfo.texi(,9822)      @print{} bar
9603texinfo.texi(,9823)      @result{} bar
9604texinfo.texi(,9824) @end group
9605texinfo.texi(,9825) @end lisp
9606texinfo.texi(,9826)
9607texinfo.texi(,9827) @noindent
9608texinfo.texi(,9828) In a Texinfo source file, this example is written as follows:
9609texinfo.texi(,9829)
9610texinfo.texi(,9830) @lisp
9611texinfo.texi(,9831) @group
9612texinfo.texi(,9832) @@lisp
9613texinfo.texi(,9833) (progn (print 'foo) (print 'bar))
9614texinfo.texi(,9834)      @@print@{@} foo
9615texinfo.texi(,9835)      @@print@{@} bar
9616texinfo.texi(,9836)      @@result@{@} bar
9617texinfo.texi(,9837) @@end lisp
9618texinfo.texi(,9838) @end group
9619texinfo.texi(,9839) @end lisp
9620texinfo.texi(,9840)
9621texinfo.texi(,9841)
9622texinfo.texi(,9842) @node Error Glyph, Equivalence, Print Glyph, Glyphs
9623texinfo.texi(,9843) @subsection @code{@@error@{@}} (@error{}): Indicating an Error Message
9624texinfo.texi(,9844) @cindex Error message, indicating it
9625texinfo.texi(,9845) @findex error
9626texinfo.texi(,9846)
9627texinfo.texi(,9847) A piece of code may cause an error when you evaluate it.  You can
9628texinfo.texi(,9848) designate the error message with the @code{@@error@{@}} command.@refill
9629texinfo.texi(,9849)
9630texinfo.texi(,9855) The @code{@@error@{@}} command is displayed as @samp{@error{}} in Info
9631texinfo.texi(,9856) and as the word `error' in a box in the printed output.@refill
9632texinfo.texi(,9858)
9633texinfo.texi(,9859) @need 700
9634texinfo.texi(,9860) Thus,
9635texinfo.texi(,9861)
9636texinfo.texi(,9862) @example
9637texinfo.texi(,9863) @@lisp
9638texinfo.texi(,9864) (+ 23 'x)
9639texinfo.texi(,9865) @@error@{@} Wrong type argument: integer-or-marker-p, x
9640texinfo.texi(,9866) @@end lisp
9641texinfo.texi(,9867) @end example
9642texinfo.texi(,9868)
9643texinfo.texi(,9869) @noindent
9644texinfo.texi(,9870) produces
9645texinfo.texi(,9871)
9646texinfo.texi(,9872) @lisp
9647texinfo.texi(,9873) (+ 23 'x)
9648texinfo.texi(,9874) @error{} Wrong type argument: integer-or-marker-p, x
9649texinfo.texi(,9875) @end lisp
9650texinfo.texi(,9876)
9651texinfo.texi(,9877) @noindent
9652texinfo.texi(,9878) This indicates that the following error message is printed
9653texinfo.texi(,9879) when you evaluate the expression:
9654texinfo.texi(,9880)
9655texinfo.texi(,9881) @lisp
9656texinfo.texi(,9882) Wrong type argument: integer-or-marker-p, x
9657texinfo.texi(,9883) @end lisp
9658texinfo.texi(,9884)
9659texinfo.texi(,9885) @samp{@error{}} itself is not part of the error message.
9660texinfo.texi(,9886)
9661texinfo.texi(,9887)
9662texinfo.texi(,9888) @node Equivalence, Point Glyph, Error Glyph, Glyphs
9663texinfo.texi(,9889) @subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence
9664texinfo.texi(,9890) @cindex Equivalence, indicating it
9665texinfo.texi(,9891) @findex equiv
9666texinfo.texi(,9892)
9667texinfo.texi(,9893) Sometimes two expressions produce identical results.  You can indicate the
9668texinfo.texi(,9894) exact equivalence of two forms with the @code{@@equiv@{@}} command.@refill
9669texinfo.texi(,9895)
9670texinfo.texi(,9901) The @code{@@equiv@{@}} command is displayed as @samp{@equiv{}} in Info
9671texinfo.texi(,9902) and as a three parallel horizontal lines in the printed output.@refill
9672texinfo.texi(,9904)
9673texinfo.texi(,9905) Thus,
9674texinfo.texi(,9906)
9675texinfo.texi(,9907) @example
9676texinfo.texi(,9908) @@lisp
9677texinfo.texi(,9909) (make-sparse-keymap) @@equiv@{@} (list 'keymap)
9678texinfo.texi(,9910) @@end lisp
9679texinfo.texi(,9911) @end example
9680texinfo.texi(,9912)
9681texinfo.texi(,9913) @noindent
9682texinfo.texi(,9914) produces
9683texinfo.texi(,9915)
9684texinfo.texi(,9916) @lisp
9685texinfo.texi(,9917) (make-sparse-keymap) @equiv{} (list 'keymap)
9686texinfo.texi(,9918) @end lisp
9687texinfo.texi(,9919)
9688texinfo.texi(,9920) @noindent
9689texinfo.texi(,9921) This indicates that evaluating @code{(make-sparse-keymap)} produces
9690texinfo.texi(,9922) identical results to evaluating @code{(list 'keymap)}.
9691texinfo.texi(,9923)
9692texinfo.texi(,9924)
9693texinfo.texi(,9925) @node Point Glyph
9694texinfo.texi(,9926) @subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer
9695texinfo.texi(,9927) @cindex Point, indicating in a buffer
9696texinfo.texi(,9928) @findex point
9697texinfo.texi(,9929)
9698texinfo.texi(,9930) Sometimes you need to show an example of text in an Emacs buffer.  In
9699texinfo.texi(,9931) such examples, the convention is to include the entire contents of the
9700texinfo.texi(,9932) buffer in question between two lines of dashes containing the buffer
9701texinfo.texi(,9933) name.@refill
9702texinfo.texi(,9934)
9703texinfo.texi(,9935) You can use the @samp{@@point@{@}} command to show the location of point
9704texinfo.texi(,9936) in the text in the buffer.  (The symbol for point, of course, is not
9705texinfo.texi(,9937) part of the text in the buffer; it indicates the place @emph{between}
9706texinfo.texi(,9938) two characters where point is located.)@refill
9707texinfo.texi(,9939)
9708texinfo.texi(,9945) The @code{@@point@{@}} command is displayed as @samp{@point{}} in Info
9709texinfo.texi(,9946) and as a small five pointed star in the printed output.@refill
9710texinfo.texi(,9948)
9711texinfo.texi(,9949) The following example shows the contents of buffer @file{foo} before
9712texinfo.texi(,9950) and after evaluating a Lisp command to insert the word @code{changed}.@refill
9713texinfo.texi(,9951)
9714texinfo.texi(,9952) @example
9715texinfo.texi(,9953) @group
9716texinfo.texi(,9954) ---------- Buffer: foo ----------
9717texinfo.texi(,9955) This is the @point{}contents of foo.
9718texinfo.texi(,9956) ---------- Buffer: foo ----------
9719texinfo.texi(,9957)
9720texinfo.texi(,9958) @end group
9721texinfo.texi(,9959) @end example
9722texinfo.texi(,9960)
9723texinfo.texi(,9961) @example
9724texinfo.texi(,9962) @group
9725texinfo.texi(,9963) (insert "changed ")
9726texinfo.texi(,9964)      @result{} nil
9727texinfo.texi(,9965) ---------- Buffer: foo ----------
9728texinfo.texi(,9966) This is the changed @point{}contents of foo.
9729texinfo.texi(,9967) ---------- Buffer: foo ----------
9730texinfo.texi(,9968)
9731texinfo.texi(,9969) @end group
9732texinfo.texi(,9970) @end example
9733texinfo.texi(,9971)
9734texinfo.texi(,9972) In a Texinfo source file, the example is written like this:@refill
9735texinfo.texi(,9973)
9736texinfo.texi(,9974) @example
9737texinfo.texi(,9975) @@example
9738texinfo.texi(,9976) ---------- Buffer: foo ----------
9739texinfo.texi(,9977) This is the @@point@{@}contents of foo.
9740texinfo.texi(,9978) ---------- Buffer: foo ----------
9741texinfo.texi(,9979)
9742texinfo.texi(,9980) (insert "changed ")
9743texinfo.texi(,9981)      @@result@{@} nil
9744texinfo.texi(,9982) ---------- Buffer: foo ----------
9745texinfo.texi(,9983) This is the changed @@point@{@}contents of foo.
9746texinfo.texi(,9984) ---------- Buffer: foo ----------
9747texinfo.texi(,9985) @@end example
9748texinfo.texi(,9986) @end example
9749texinfo.texi(,9987)
9750texinfo.texi(,9988)
9751texinfo.texi(,9989) @node Footnotes
9752texinfo.texi(,9990) @section Footnotes
9753texinfo.texi(,9991) @cindex Footnotes
9754texinfo.texi(,9992) @findex footnote
9755texinfo.texi(,9993)
9756texinfo.texi(,9994) A @dfn{footnote} is for a reference that documents or elucidates the
9757texinfo.texi(,9995) primary text.@footnote{A footnote should complement or expand upon
9758texinfo.texi(,9996) the primary text, but a reader should not need to read a footnote to
9759texinfo.texi(,9997) understand the primary text.  For a thorough discussion of footnotes,
9760texinfo.texi(,9998) see @cite{The Chicago Manual of Style}, which is published by the
9761texinfo.texi(,9999) University of Chicago Press.}
9762texinfo.texi(,10000)
9763texinfo.texi(,10001) @menu
9764texinfo.texi(,10002) * Footnote Commands::           How to write a footnote in Texinfo.
9765texinfo.texi(,10003) * Footnote Styles::             Controlling how footnotes appear in Info.
9766texinfo.texi(,10004) @end menu
9767texinfo.texi(,10005)
9768texinfo.texi(,10006)
9769texinfo.texi(,10007) @node Footnote Commands
9770texinfo.texi(,10008) @subsection Footnote Commands
9771texinfo.texi(,10009)
9772texinfo.texi(,10010) In Texinfo, footnotes are created with the @code{@@footnote} command.
9773texinfo.texi(,10011) This command is followed immediately by a left brace, then by the text
9774texinfo.texi(,10012) of the footnote, and then by a terminating right brace.  Footnotes may
9775texinfo.texi(,10013) be of any length (they will be broken across pages if necessary), but
9776texinfo.texi(,10014) are usually short.  The template is:
9777texinfo.texi(,10015)
9778texinfo.texi(,10016) @example
9779texinfo.texi(,10017) ordinary text@@footnote@{@var{text of footnote}@}
9780texinfo.texi(,10018) @end example
9781texinfo.texi(,10019)
9782texinfo.texi(,10020) As shown here, the @code{@@footnote} command should come right after the
9783texinfo.texi(,10021) text being footnoted, with no intervening space; otherwise, the footnote
9784texinfo.texi(,10022) marker might end up starting a line.
9785texinfo.texi(,10023)
9786texinfo.texi(,10024) For example, this clause is followed by a sample footnote@footnote{Here
9787texinfo.texi(,10025) is the sample footnote.}; in the Texinfo source, it looks like
9788texinfo.texi(,10026) this:
9789texinfo.texi(,10027)
9790texinfo.texi(,10028) @example
9791texinfo.texi(,10029) @dots{}a sample footnote@@footnote@{Here is the sample
9792texinfo.texi(,10030) footnote.@}; in the Texinfo source@dots{}
9793texinfo.texi(,10031) @end example
9794texinfo.texi(,10032)
9795texinfo.texi(,10033) As you can see, the source includes two punctuation marks next to each
9796texinfo.texi(,10034) other; in this case, @samp{.@};} is the sequence.  This is normal (the
9797texinfo.texi(,10035) first ends the footnote and the second belongs to the sentence being
9798texinfo.texi(,10036) footnoted), so don't worry that it looks odd.
9799texinfo.texi(,10037)
9800texinfo.texi(,10038) In a printed manual or book, the reference mark for a footnote is a
9801texinfo.texi(,10039) small, superscripted number; the text of the footnote appears at the
9802texinfo.texi(,10040) bottom of the page, below a horizontal line.
9803texinfo.texi(,10041)
9804texinfo.texi(,10042) In Info, the reference mark for a footnote is a pair of parentheses
9805texinfo.texi(,10043) with the footnote number between them, like this: @samp{(1)}.  The
9806texinfo.texi(,10044) reference mark is followed by a cross-reference link to the footnote's
9807texinfo.texi(,10045) text.
9808texinfo.texi(,10046)
9809texinfo.texi(,10047) In the HTML output, footnote references are marked with a small,
9810texinfo.texi(,10048) superscripted number which is rendered as a hypertext link to the
9811texinfo.texi(,10049) footnote text.
9812texinfo.texi(,10050)
9813texinfo.texi(,10051) By the way, footnotes in the argument of an @code{@@item} command for a
9814texinfo.texi(,10052) @code{@@table} must be on the same line as the @code{@@item}
9815texinfo.texi(,10053) (as usual).  @xref{Two-column Tables}.
9816texinfo.texi(,10054)
9817texinfo.texi(,10055)
9818texinfo.texi(,10056) @node Footnote Styles
9819texinfo.texi(,10057) @subsection Footnote Styles
9820texinfo.texi(,10058)
9821texinfo.texi(,10059) Info has two footnote styles, which determine where the text of the
9822texinfo.texi(,10060) footnote is located:@refill
9823texinfo.texi(,10061)
9824texinfo.texi(,10062) @itemize @bullet
9825texinfo.texi(,10063) @cindex @samp{@r{End}} node footnote style
9826texinfo.texi(,10064) @item
9827texinfo.texi(,10065) In the `End' node style, all the footnotes for a single node
9828texinfo.texi(,10066) are placed at the end of that node.  The footnotes are separated from
9829texinfo.texi(,10067) the rest of the node by a line of dashes with the word
9830texinfo.texi(,10068) @samp{Footnotes} within it.  Each footnote begins with an
9831texinfo.texi(,10069) @samp{(@var{n})} reference mark.@refill
9832texinfo.texi(,10070)
9833texinfo.texi(,10071) @need 700
9834texinfo.texi(,10072) @noindent
9835texinfo.texi(,10073) Here is an example of a single footnote in the end of node style:@refill
9836texinfo.texi(,10074)
9837texinfo.texi(,10075) @example
9838texinfo.texi(,10076) @group
9839texinfo.texi(,10077)  --------- Footnotes ---------
9840texinfo.texi(,10078)
9841texinfo.texi(,10079) (1)  Here is a sample footnote.
9842texinfo.texi(,10080) @end group
9843texinfo.texi(,10081) @end example
9844texinfo.texi(,10082)
9845texinfo.texi(,10083) @cindex @samp{@r{Separate}} footnote style
9846texinfo.texi(,10084) @item
9847texinfo.texi(,10085) In the `Separate' node style, all the footnotes for a single
9848texinfo.texi(,10086) node are placed in an automatically constructed node of
9849texinfo.texi(,10087) their own.  In this style, a ``footnote reference'' follows
9850texinfo.texi(,10088) each @samp{(@var{n})} reference mark in the body of the
9851texinfo.texi(,10089) node.  The footnote reference is actually a cross reference
9852texinfo.texi(,10090) which you use to reach the footnote node.@refill
9853texinfo.texi(,10091)
9854texinfo.texi(,10092) The name of the node with the footnotes is constructed
9855texinfo.texi(,10093) by appending @w{@samp{-Footnotes}} to the name of the node
9856texinfo.texi(,10094) that contains the footnotes. (Consequently, the footnotes'
9857texinfo.texi(,10095) node for the @file{Footnotes} node is
9858texinfo.texi(,10096) @w{@file{Footnotes-Footnotes}}!)  The footnotes' node has an
9859texinfo.texi(,10097) `Up' node pointer that leads back to its parent node.@refill
9860texinfo.texi(,10098)
9861texinfo.texi(,10099) @noindent
9862texinfo.texi(,10100) Here is how the first footnote in this manual looks after being
9863texinfo.texi(,10101) formatted for Info in the separate node style:@refill
9864texinfo.texi(,10102)
9865texinfo.texi(,10103) @smallexample
9866texinfo.texi(,10104) @group
9867texinfo.texi(,10105) File: texinfo.info  Node: Overview-Footnotes, Up: Overview
9868texinfo.texi(,10106)
9869texinfo.texi(,10107) (1) The first syllable of "Texinfo" is pronounced like "speck", not
9870texinfo.texi(,10108) "hex". @dots{}
9871texinfo.texi(,10109) @end group
9872texinfo.texi(,10110) @end smallexample
9873texinfo.texi(,10111) @end itemize
9874texinfo.texi(,10112)
9875texinfo.texi(,10113) A Texinfo file may be formatted into an Info file with either footnote
9876texinfo.texi(,10114) style.@refill
9877texinfo.texi(,10115)
9878texinfo.texi(,10116) @findex footnotestyle
9879texinfo.texi(,10117) Use the @code{@@footnotestyle} command to specify an Info file's
9880texinfo.texi(,10118) footnote style.  Write this command at the beginning of a line followed
9881texinfo.texi(,10119) by an argument, either @samp{end} for the end node style or
9882texinfo.texi(,10120) @samp{separate} for the separate node style.
9883texinfo.texi(,10121)
9884texinfo.texi(,10122) @need 700
9885texinfo.texi(,10123) For example,
9886texinfo.texi(,10124)
9887texinfo.texi(,10125) @example
9888texinfo.texi(,10126) @@footnotestyle end
9889texinfo.texi(,10127) @end example
9890texinfo.texi(,10128) @noindent
9891texinfo.texi(,10129) or
9892texinfo.texi(,10130) @example
9893texinfo.texi(,10131) @@footnotestyle separate
9894texinfo.texi(,10132) @end example
9895texinfo.texi(,10133)
9896texinfo.texi(,10134) Write an @code{@@footnotestyle} command before or shortly after the
9897texinfo.texi(,10135) end-of-header line at the beginning of a Texinfo file.  (If you
9898texinfo.texi(,10136) include the @code{@@footnotestyle} command between the start-of-header
9899texinfo.texi(,10137) and end-of-header lines, the region formatting commands will format
9900texinfo.texi(,10138) footnotes as specified.)@refill
9901texinfo.texi(,10139)
9902texinfo.texi(,10140) If you do not specify a footnote style, the formatting commands use
9903texinfo.texi(,10141) their default style.  Currently, @code{texinfo-format-buffer} and
9904texinfo.texi(,10142) @code{texinfo-format-region} use the `separate' style and
9905texinfo.texi(,10143) @code{makeinfo} uses the `end' style.@refill
9906texinfo.texi(,10144)
9907texinfo.texi(,10145) @c !!! note: makeinfo's --footnote-style option overrides footnotestyle
9908texinfo.texi(,10181) This chapter contains two footnotes.@refill
9909texinfo.texi(,10183)
9910texinfo.texi(,10184)
9911texinfo.texi(,10185) @c this should be described with figures when we have them
9912texinfo.texi(,10186) @c perhaps in the quotation/example chapter.
9913texinfo.texi(,10187) @node Images
9914texinfo.texi(,10188) @section Inserting Images
9915texinfo.texi(,10189)
9916texinfo.texi(,10190) @cindex Images, inserting
9917texinfo.texi(,10191) @cindex Pictures, inserting
9918texinfo.texi(,10192) @findex image
9919texinfo.texi(,10193)
9920texinfo.texi(,10194) You can insert an image given in an external file with the
9921texinfo.texi(,10195) @code{@@image} command:
9922texinfo.texi(,10196)
9923texinfo.texi(,10197) @example
9924texinfo.texi(,10198) @@image@{@var{filename}, @r{[}@var{width}@r{]}, @r{[}@var{height}@r{]}, @r{[}@var{alttext}@r{]}, @r{[}@var{extension}@r{]}@}
9925texinfo.texi(,10199) @end example
9926texinfo.texi(,10200)
9927texinfo.texi(,10201) @cindex Formats for images
9928texinfo.texi(,10202) @cindex Image formats
9929texinfo.texi(,10203) The @var{filename} argument is mandatory, and must not have an
9930texinfo.texi(,10204) extension, because the different processors support different formats:
9931texinfo.texi(,10205) @itemize @bullet
9932texinfo.texi(,10206) @item
9933texinfo.texi(,10207) @TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript
9934texinfo.texi(,10208) format).
9935texinfo.texi(,10209) @item
9936texinfo.texi(,10210) @pindex pdftex@r{, and images}
9937texinfo.texi(,10211) PDF@TeX{} reads @file{@var{filename}.pdf} (Adobe's Portable Document Format).
9938texinfo.texi(,10212) @item
9939texinfo.texi(,10213) @code{makeinfo} uses @file{@var{filename}.txt} verbatim for
9940texinfo.texi(,10214) Info output (more or less as if it was an @code{@@example}).
9941texinfo.texi(,10215) @item
9942texinfo.texi(,10216) @code{makeinfo}
9943texinfo.texi(,10217) uses the optional fifth argument to @code{@@image} for the extension if
9944texinfo.texi(,10218) you supply it.  For example:
9945texinfo.texi(,10219)
9946texinfo.texi(,10220) @pindex XPM image format
9947texinfo.texi(,10221) @example
9948texinfo.texi(,10222) @@image@{foo,,,,xpm@}
9949texinfo.texi(,10223) @end example
9950texinfo.texi(,10224)
9951texinfo.texi(,10225) @noindent
9952texinfo.texi(,10226) will cause @samp{makeinfo --html} to try @file{foo.xpm}.
9953texinfo.texi(,10227)
9954texinfo.texi(,10228) @cindex GIF, unsupported due to patents
9955texinfo.texi(,10229) @cindex PNG image format
9956texinfo.texi(,10230) @cindex JPG image format
9957texinfo.texi(,10231) If you do not supply the optional fifth argument, @samp{makeinfo
9958texinfo.texi(,10232) ---html} first tries @file{@var{filename}.png}; if that does not exist,
9959texinfo.texi(,10233) it tries @file{@var{filename}.jpg}.  If that does not exist either, it
9960texinfo.texi(,10234) complains.  (We cannot support GIF format directly due to software
9961texinfo.texi(,10235) patents.)
9962texinfo.texi(,10236) @end itemize
9963texinfo.texi(,10237)
9964texinfo.texi(,10238) @cindex Width of images
9965texinfo.texi(,10239) @cindex Height of images
9966texinfo.texi(,10240) @cindex Aspect ratio of images
9967texinfo.texi(,10241) @cindex Distorting images
9968texinfo.texi(,10242) The optional @var{width} and @var{height} arguments specify the size to
9969texinfo.texi(,10243) scale the image to (they are ignored for Info output).  If neither is
9970texinfo.texi(,10244) specified, the image is presented in its natural size (given in the
9971texinfo.texi(,10245) file); if only one is specified, the other is scaled proportionately;
9972texinfo.texi(,10246) and if both are specified, both are respected, thus possibly distorting
9973texinfo.texi(,10247) the original image by changing its aspect ratio.
9974texinfo.texi(,10248)
9975texinfo.texi(,10249) @cindex Dimensions and image sizes
9976texinfo.texi(,10250) The @var{width} and @var{height} may be specified using any valid @TeX{}
9977texinfo.texi(,10251) dimension, namely:
9978texinfo.texi(,10252)
9979texinfo.texi(,10253) @table @asis
9980texinfo.texi(,10254) @item pt
9981texinfo.texi(,10255) @cindex Points (dimension)
9982texinfo.texi(,10256) point (72.27pt = 1in)
9983texinfo.texi(,10257) @item pc
9984texinfo.texi(,10258) @cindex Picas
9985texinfo.texi(,10259) pica (1pc = 12pt)
9986texinfo.texi(,10260) @item bp
9987texinfo.texi(,10261) @cindex Big points
9988texinfo.texi(,10262) big point (72bp = 1in)
9989texinfo.texi(,10263) @item in
9990texinfo.texi(,10264) @cindex Inches
9991texinfo.texi(,10265) inch
9992texinfo.texi(,10266) @item cm
9993texinfo.texi(,10267) @cindex Centimeters
9994texinfo.texi(,10268) centimeter (2.54cm = 1in)
9995texinfo.texi(,10269) @item mm
9996texinfo.texi(,10270) @cindex Millimeters
9997texinfo.texi(,10271) millimeter (10mm = 1cm)
9998texinfo.texi(,10272) @item dd
9999texinfo.texi(,10273) @cindex Did@^ot points
10000texinfo.texi(,10274) did@^ot point (1157dd = 1238pt)
10001texinfo.texi(,10275) @item cc
10002texinfo.texi(,10276) @cindex Ciceros
10003texinfo.texi(,10277) cicero (1cc = 12dd)
10004texinfo.texi(,10278) @item sp
10005texinfo.texi(,10279) @cindex Scaled points
10006texinfo.texi(,10280) scaled point (65536sp = 1pt)
10007texinfo.texi(,10281) @end table
10008texinfo.texi(,10282)
10009texinfo.texi(,10283) @pindex ridt.eps
10010texinfo.texi(,10284) For example, the following will scale a file @file{ridt.eps} to one
10011texinfo.texi(,10285) inch vertically, with the width scaled proportionately:
10012texinfo.texi(,10286)
10013texinfo.texi(,10287) @example
10014texinfo.texi(,10288) @@image@{ridt,,1in@}
10015texinfo.texi(,10289) @end example
10016texinfo.texi(,10290)
10017texinfo.texi(,10291) @pindex epsf.tex
10018texinfo.texi(,10292) For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be
10019texinfo.texi(,10293) installed somewhere that @TeX{} can find it.  (The standard location is
10020texinfo.texi(,10294) @file{@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a
10021texinfo.texi(,10295) root of your @TeX{} directory tree.)  This file is included in the
10022texinfo.texi(,10296) Texinfo distribution and is also available from
10023texinfo.texi(,10297) @uref{ftp://tug.org/tex/epsf.tex}, among other places.
10024texinfo.texi(,10298)
10025texinfo.texi(,10299) @code{@@image} can be used within a line as well as for displayed
10026texinfo.texi(,10300) figures.  Therefore, if you intend it to be displayed, be sure to leave
10027texinfo.texi(,10301) a blank line before the command, or the output will run into the
10028texinfo.texi(,10302) preceding text.
10029texinfo.texi(,10303)
10030texinfo.texi(,10304) @cindex alt attribute for images
10031texinfo.texi(,10305) @cindex alternate text for images
10032texinfo.texi(,10306) When producing html, @code{makeinfo} sets the @dfn{alt attribute} for
10033texinfo.texi(,10307) inline images to the optional fourth argument to @code{@@image}, if
10034texinfo.texi(,10308) supplied.  If not supplied, @code{makeinfo} uses the full file name of
10035texinfo.texi(,10309) the image being displayed.
10036texinfo.texi(,10310)
10037texinfo.texi(,10311)
10038texinfo.texi(,10312) @node Breaks
10039texinfo.texi(,10313) @chapter Making and Preventing Breaks
10040texinfo.texi(,10314) @cindex Making line and page breaks
10041texinfo.texi(,10315) @cindex Preventing line and page breaks
10042texinfo.texi(,10316)
10043texinfo.texi(,10317) @cindex Line breaks
10044texinfo.texi(,10318) Usually, a Texinfo file is processed both by @TeX{} and by one of the
10045texinfo.texi(,10319) Info formatting commands.  Line, paragraph, or page breaks sometimes
10046texinfo.texi(,10320) occur in the `wrong' place in one or other form of output.  You must
10047texinfo.texi(,10321) ensure that text looks right both in the printed manual and in the
10048texinfo.texi(,10322) Info file.
10049texinfo.texi(,10323)
10050texinfo.texi(,10324) @cindex White space, excessive
10051texinfo.texi(,10325) @cindex Page breaks
10052texinfo.texi(,10326) For example, in a printed manual, page breaks may occur awkwardly in
10053texinfo.texi(,10327) the middle of an example; to prevent this, you can hold text together
10054texinfo.texi(,10328) using a grouping command that keeps the text from being split across
10055texinfo.texi(,10329) two pages.  Conversely, you may want to force a page break where none
10056texinfo.texi(,10330) would occur normally.  Fortunately, problems like these do not often
10057texinfo.texi(,10331) arise.  When they do, use the break, break prevention, or pagination
10058texinfo.texi(,10332) commands.
10059texinfo.texi(,10333)
10060texinfo.texi(,10334) @menu
10061texinfo.texi(,10335) * Break Commands::              Cause and prevent splits.
10062texinfo.texi(,10336) * Line Breaks::                 How to force a single line to use two lines.
10063texinfo.texi(,10337) * - and hyphenation::           How to tell @TeX{} about hyphenation points.
10064texinfo.texi(,10338) * w::                           How to prevent unwanted line breaks.
10065texinfo.texi(,10339) * sp::                          How to insert blank lines.
10066texinfo.texi(,10340) * page::                        How to force the start of a new page.
10067texinfo.texi(,10341) * group::                       How to prevent unwanted page breaks.
10068texinfo.texi(,10342) * need::                        Another way to prevent unwanted page breaks.
10069texinfo.texi(,10343) @end menu
10070texinfo.texi(,10344)
10071texinfo.texi(,10345)
10072texinfo.texi(,10346) @node Break Commands, Line Breaks, Breaks, Breaks
10073texinfo.texi(,10348) @heading Break Commands
10074texinfo.texi(,10350)
10075texinfo.texi(,10351) The break commands create or allow line and paragraph breaks:@refill
10076texinfo.texi(,10352)
10077texinfo.texi(,10353) @table @code
10078texinfo.texi(,10354) @item @@*
10079texinfo.texi(,10355) Force a line break.
10080texinfo.texi(,10356)
10081texinfo.texi(,10357) @item @@sp @var{n}
10082texinfo.texi(,10358) Skip @var{n} blank lines.@refill
10083texinfo.texi(,10359)
10084texinfo.texi(,10360) @item @@-
10085texinfo.texi(,10361) Insert a discretionary hyphen.
10086texinfo.texi(,10362)
10087texinfo.texi(,10363) @item @@hyphenation@{@var{hy-phen-a-ted words}@}
10088texinfo.texi(,10364) Define hyphen points in @var{hy-phen-a-ted words}.
10089texinfo.texi(,10365) @end table
10090texinfo.texi(,10366)
10091texinfo.texi(,10367) The line-break-prevention command holds text together all on one
10092texinfo.texi(,10368) line:@refill
10093texinfo.texi(,10369)
10094texinfo.texi(,10370) @table @code
10095texinfo.texi(,10371) @item @@w@{@var{text}@}
10096texinfo.texi(,10372) Prevent @var{text} from being split and hyphenated across two lines.@refill
10097texinfo.texi(,10373) @end table
10098texinfo.texi(,10377)
10099texinfo.texi(,10378) The pagination commands apply only to printed output, since Info
10100texinfo.texi(,10379) files do not have pages.@refill
10101texinfo.texi(,10380)
10102texinfo.texi(,10381) @table @code
10103texinfo.texi(,10382) @item @@page
10104texinfo.texi(,10383) Start a new page in the printed manual.@refill
10105texinfo.texi(,10384)
10106texinfo.texi(,10385) @item @@group
10107texinfo.texi(,10386) Hold text together that must appear on one printed page.@refill
10108texinfo.texi(,10387)
10109texinfo.texi(,10388) @item @@need @var{mils}
10110texinfo.texi(,10389) Start a new printed page if not enough space on this one.@refill
10111texinfo.texi(,10390) @end table
10112texinfo.texi(,10391)
10113texinfo.texi(,10392) @node Line Breaks
10114texinfo.texi(,10393) @section @code{@@*}: Generate Line Breaks
10115texinfo.texi(,10394) @findex * @r{(force line break)}
10116texinfo.texi(,10395) @cindex Line breaks
10117texinfo.texi(,10396) @cindex Breaks in a line
10118texinfo.texi(,10397)
10119texinfo.texi(,10398) The @code{@@*} command forces a line break in both the printed manual and
10120texinfo.texi(,10399) in Info.@refill
10121texinfo.texi(,10400)
10122texinfo.texi(,10401) @need 700
10123texinfo.texi(,10402) For example,
10124texinfo.texi(,10403)
10125texinfo.texi(,10404) @example
10126texinfo.texi(,10405) This line @@* is broken @@*in two places.
10127texinfo.texi(,10406) @end example
10128texinfo.texi(,10407)
10129texinfo.texi(,10408) @noindent
10130texinfo.texi(,10409) produces
10131texinfo.texi(,10410)
10132texinfo.texi(,10411) @example
10133texinfo.texi(,10412) @group
10134texinfo.texi(,10413) This line
10135texinfo.texi(,10414)  is broken
10136texinfo.texi(,10415) in two places.
10137texinfo.texi(,10416) @end group
10138texinfo.texi(,10417) @end example
10139texinfo.texi(,10418)
10140texinfo.texi(,10419) @noindent
10141texinfo.texi(,10420) (Note that the space after the first @code{@@*} command is faithfully
10142texinfo.texi(,10421) carried down to the next line.)@refill
10143texinfo.texi(,10422)
10144texinfo.texi(,10423) @need 800
10145texinfo.texi(,10424) The @code{@@*} command is often used in a file's copyright page:@refill
10146texinfo.texi(,10425)
10147texinfo.texi(,10426) @example
10148texinfo.texi(,10427) @group
10149texinfo.texi(,10428) This is edition 2.0 of the Texinfo documentation,@@*
10150texinfo.texi(,10429) and is for @dots{}
10151texinfo.texi(,10430) @end group
10152texinfo.texi(,10431) @end example
10153texinfo.texi(,10432)
10154texinfo.texi(,10433) @noindent
10155texinfo.texi(,10434) In this case, the @code{@@*} command keeps @TeX{} from stretching the
10156texinfo.texi(,10435) line across the whole page in an ugly manner.@refill
10157texinfo.texi(,10436)
10158texinfo.texi(,10437) @quotation
10159texinfo.texi(,10438) @strong{Please note:} Do not write braces after an @code{@@*} command;
10160texinfo.texi(,10439) they are not needed.@refill
10161texinfo.texi(,10440)
10162texinfo.texi(,10441) Do not write an @code{@@refill} command at the end of a paragraph
10163texinfo.texi(,10442) containing an @code{@@*} command; it will cause the paragraph to be
10164texinfo.texi(,10443) refilled after the line break occurs, negating the effect of the line
10165texinfo.texi(,10444) break.@refill
10166texinfo.texi(,10445) @end quotation
10167texinfo.texi(,10446)
10168texinfo.texi(,10447)
10169texinfo.texi(,10448) @node - and hyphenation
10170texinfo.texi(,10449) @section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} hyphenate
10171texinfo.texi(,10450)
10172texinfo.texi(,10451) @findex - @r{(discretionary hyphen)}
10173texinfo.texi(,10452) @findex hyphenation
10174texinfo.texi(,10453) @cindex Hyphenation, helping @TeX{} do
10175texinfo.texi(,10454) @cindex Fine-tuning, and hyphenation
10176texinfo.texi(,10455)
10177texinfo.texi(,10456) Although @TeX{}'s hyphenation algorithm is generally pretty good, it
10178texinfo.texi(,10457) does miss useful hyphenation points from time to time.  (Or, far more
10179texinfo.texi(,10458) rarely, insert an incorrect hyphenation.)  So, for documents with an
10180texinfo.texi(,10459) unusual vocabulary or when fine-tuning for a printed edition, you may
10181texinfo.texi(,10460) wish to help @TeX{} out.  Texinfo supports two commands for this:
10182texinfo.texi(,10461)
10183texinfo.texi(,10462) @table @code
10184texinfo.texi(,10463) @item @@-
10185texinfo.texi(,10464) Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does
10186texinfo.texi(,10465) not have to) hyphenate.  This is especially useful when you notice an
10187texinfo.texi(,10466) overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull
10188texinfo.texi(,10467) hboxes}).  @TeX{} will not insert any hyphenation points itself into a
10189texinfo.texi(,10468) word containing @code{@@-}.
10190texinfo.texi(,10469)
10191texinfo.texi(,10470) @item @@hyphenation@{@var{hy-phen-a-ted words}@}
10192texinfo.texi(,10471) Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}.  As shown, you
10193texinfo.texi(,10472) put a @samp{-} at each hyphenation point.  For example:
10194texinfo.texi(,10473) @example
10195texinfo.texi(,10474) @@hyphenation@{man-u-script man-u-scripts@}
10196texinfo.texi(,10475) @end example
10197texinfo.texi(,10476) @noindent @TeX{} only uses the specified hyphenation points when the
10198texinfo.texi(,10477) words match exactly, so give all necessary variants.
10199texinfo.texi(,10478) @end table
10200texinfo.texi(,10479)
10201texinfo.texi(,10480) Info output is not hyphenated, so these commands have no effect there.
10202texinfo.texi(,10481)
10203texinfo.texi(,10482) @node w
10204texinfo.texi(,10483) @section @code{@@w}@{@var{text}@}: Prevent Line Breaks
10205texinfo.texi(,10484) @findex w @r{(prevent line break)}
10206texinfo.texi(,10485) @cindex Line breaks, preventing
10207texinfo.texi(,10486) @cindex Hyphenation, preventing
10208texinfo.texi(,10487)
10209texinfo.texi(,10488) @code{@@w@{@var{text}@}} outputs @var{text} and prohibits line breaks
10210texinfo.texi(,10489) within @var{text}.@refill
10211texinfo.texi(,10490)
10212texinfo.texi(,10491) You can use the @code{@@w} command to prevent @TeX{} from automatically
10213texinfo.texi(,10492) hyphenating a long name or phrase that happens to fall near the end of a
10214texinfo.texi(,10493) line.  For example:
10215texinfo.texi(,10494)
10216texinfo.texi(,10495) @example
10217texinfo.texi(,10496) You can copy GNU software from @@w@{@@samp@{ftp.gnu.org@}@}.
10218texinfo.texi(,10497) @end example
10219texinfo.texi(,10498)
10220texinfo.texi(,10499) @noindent
10221texinfo.texi(,10500) produces
10222texinfo.texi(,10501)
10223texinfo.texi(,10502) @quotation
10224texinfo.texi(,10503) You can copy GNU software from @w{@samp{ftp.gnu.org}}.
10225texinfo.texi(,10504) @end quotation
10226texinfo.texi(,10505)
10227texinfo.texi(,10506) @cindex Non-breakable space
10228texinfo.texi(,10507) @cindex Unbreakable space
10229texinfo.texi(,10508) @cindex Tied space
10230texinfo.texi(,10509) You can also use @code{@@w} to produce a non-breakable space:
10231texinfo.texi(,10510)
10232texinfo.texi(,10511) @example
10233texinfo.texi(,10512) None of the formatters will break at this@@w@{ @}space.
10234texinfo.texi(,10513) @end example
10235texinfo.texi(,10514)
10236texinfo.texi(,10515)
10237texinfo.texi(,10516) @node sp
10238texinfo.texi(,10517) @section @code{@@sp} @var{n}: Insert Blank Lines
10239texinfo.texi(,10518) @findex sp @r{(line spacing)}
10240texinfo.texi(,10519) @cindex Space, inserting vertical
10241texinfo.texi(,10520) @cindex Blank lines
10242texinfo.texi(,10521) @cindex Line spacing
10243texinfo.texi(,10522)
10244texinfo.texi(,10523) A line beginning with and containing only @code{@@sp @var{n}}
10245texinfo.texi(,10524) generates @var{n} blank lines of space in both the printed manual and
10246texinfo.texi(,10525) the Info file.  @code{@@sp} also forces a paragraph break.  For
10247texinfo.texi(,10526) example,
10248texinfo.texi(,10527)
10249texinfo.texi(,10528) @example
10250texinfo.texi(,10529) @@sp 2
10251texinfo.texi(,10530) @end example
10252texinfo.texi(,10531)
10253texinfo.texi(,10532) @noindent
10254texinfo.texi(,10533) generates two blank lines.
10255texinfo.texi(,10534)
10256texinfo.texi(,10535) The @code{@@sp} command is most often used in the title page.@refill
10257texinfo.texi(,10536)
10258texinfo.texi(,10576)
10259texinfo.texi(,10577)
10260texinfo.texi(,10578) @node page
10261texinfo.texi(,10579) @section @code{@@page}: Start a New Page
10262texinfo.texi(,10580) @cindex Page breaks
10263texinfo.texi(,10581) @findex page
10264texinfo.texi(,10582)
10265texinfo.texi(,10583) A line containing only @code{@@page} starts a new page in a printed
10266texinfo.texi(,10584) manual.  The command has no effect on Info files since they are not
10267texinfo.texi(,10585) paginated.  An @code{@@page} command is often used in the @code{@@titlepage}
10268texinfo.texi(,10586) section of a Texinfo file to start the copyright page.
10269texinfo.texi(,10587)
10270texinfo.texi(,10588)
10271texinfo.texi(,10589) @node group, need, page, Breaks
10272texinfo.texi(,10590) @comment  node-name,  next,  previous,  up
10273texinfo.texi(,10591) @section @code{@@group}: Prevent Page Breaks
10274texinfo.texi(,10592) @cindex Group (hold text together vertically)
10275texinfo.texi(,10593) @cindex Holding text together vertically
10276texinfo.texi(,10594) @cindex Vertically holding text together
10277texinfo.texi(,10595) @findex group
10278texinfo.texi(,10596)
10279texinfo.texi(,10597) The @code{@@group} command (on a line by itself) is used inside an
10280texinfo.texi(,10598) @code{@@example} or similar construct to begin an unsplittable vertical
10281texinfo.texi(,10599) group, which will appear entirely on one page in the printed output.
10282texinfo.texi(,10600) The group is terminated by a line containing only @code{@@end group}.
10283texinfo.texi(,10601) These two lines produce no output of their own, and in the Info file
10284texinfo.texi(,10602) output they have no effect at all.@refill
10285texinfo.texi(,10603)
10286texinfo.texi(,10604) @c Once said that these environments
10287texinfo.texi(,10605) @c turn off vertical spacing between ``paragraphs''.
10288texinfo.texi(,10606) @c Also, quotation used to work, but doesn't in texinfo-2.72
10289texinfo.texi(,10607) Although @code{@@group} would make sense conceptually in a wide
10290texinfo.texi(,10608) variety of contexts, its current implementation works reliably only
10291texinfo.texi(,10609) within @code{@@example} and variants, and within @code{@@display},
10292texinfo.texi(,10610) @code{@@format}, @code{@@flushleft} and @code{@@flushright}.
10293texinfo.texi(,10611) @xref{Quotations and Examples}.  (What all these commands have in
10294texinfo.texi(,10612) common is that each line of input produces a line of output.)  In
10295texinfo.texi(,10613) other contexts, @code{@@group} can cause anomalous vertical
10296texinfo.texi(,10614) spacing.@refill
10297texinfo.texi(,10615)
10298texinfo.texi(,10616) @need 750
10299texinfo.texi(,10617) This formatting requirement means that you should write:
10300texinfo.texi(,10618)
10301texinfo.texi(,10619) @example
10302texinfo.texi(,10620) @group
10303texinfo.texi(,10621) @@example
10304texinfo.texi(,10622) @@group
10305texinfo.texi(,10623) @dots{}
10306texinfo.texi(,10624) @@end group
10307texinfo.texi(,10625) @@end example
10308texinfo.texi(,10626) @end group
10309texinfo.texi(,10627) @end example
10310texinfo.texi(,10628)
10311texinfo.texi(,10629) @noindent
10312texinfo.texi(,10630) with the @code{@@group} and @code{@@end group} commands inside the
10313texinfo.texi(,10631) @code{@@example} and @code{@@end example} commands.
10314texinfo.texi(,10632)
10315texinfo.texi(,10633) The @code{@@group} command is most often used to hold an example
10316texinfo.texi(,10634) together on one page.  In this Texinfo manual, more than 100 examples
10317texinfo.texi(,10635) contain text that is enclosed between @code{@@group} and @code{@@end
10318texinfo.texi(,10636) group}.
10319texinfo.texi(,10637)
10320texinfo.texi(,10638) If you forget to end a group, you may get strange and unfathomable
10321texinfo.texi(,10639) error messages when you run @TeX{}.  This is because @TeX{} keeps
10322texinfo.texi(,10640) trying to put the rest of the Texinfo file onto the one page and does
10323texinfo.texi(,10641) not start to generate error messages until it has processed
10324texinfo.texi(,10642) considerable text.  It is a good rule of thumb to look for a missing
10325texinfo.texi(,10643) @code{@@end group} if you get incomprehensible error messages in
10326texinfo.texi(,10644) @TeX{}.@refill
10327texinfo.texi(,10645)
10328texinfo.texi(,10646) @node need,  , group, Breaks
10329texinfo.texi(,10647) @comment  node-name,  next,  previous,  up
10330texinfo.texi(,10648) @section @code{@@need @var{mils}}: Prevent Page Breaks
10331texinfo.texi(,10649) @cindex Need space at page bottom
10332texinfo.texi(,10650) @findex need
10333texinfo.texi(,10651)
10334texinfo.texi(,10652) A line containing only @code{@@need @var{n}} starts
10335texinfo.texi(,10653) a new page in a printed manual if fewer than @var{n} mils (thousandths
10336texinfo.texi(,10654) of an inch) remain on the current page.  Do not use
10337texinfo.texi(,10655) braces around the argument @var{n}.  The @code{@@need} command has no
10338texinfo.texi(,10656) effect on Info files since they are not paginated.@refill
10339texinfo.texi(,10657)
10340texinfo.texi(,10658) @need 800
10341texinfo.texi(,10659) This paragraph is preceded by an @code{@@need} command that tells
10342texinfo.texi(,10660) @TeX{} to start a new page if fewer than 800 mils (eight-tenths
10343texinfo.texi(,10661) inch) remain on the page.  It looks like this:@refill
10344texinfo.texi(,10662)
10345texinfo.texi(,10663) @example
10346texinfo.texi(,10664) @group
10347texinfo.texi(,10665) @@need 800
10348texinfo.texi(,10666) This paragraph is preceded by @dots{}
10349texinfo.texi(,10667) @end group
10350texinfo.texi(,10668) @end example
10351texinfo.texi(,10669)
10352texinfo.texi(,10670) The @code{@@need} command is useful for preventing orphans (single
10353texinfo.texi(,10671) lines at the bottoms of printed pages).@refill
10354texinfo.texi(,10672)
10355texinfo.texi(,10673)
10356texinfo.texi(,10674) @node Definition Commands
10357texinfo.texi(,10675) @chapter Definition Commands
10358texinfo.texi(,10676) @cindex Definition commands
10359texinfo.texi(,10677)
10360texinfo.texi(,10678) The @code{@@deffn} command and the other @dfn{definition commands}
10361texinfo.texi(,10679) enable you to describe functions, variables, macros, commands, user
10362texinfo.texi(,10680) options, special forms and other such artifacts in a uniform
10363texinfo.texi(,10681) format.@refill
10364texinfo.texi(,10682)
10365texinfo.texi(,10683) In the Info file, a definition causes the entity
10366texinfo.texi(,10684) category---`Function', `Variable', or whatever---to appear at the
10367texinfo.texi(,10685) beginning of the first line of the definition, followed by the
10368texinfo.texi(,10686) entity's name and arguments.  In the printed manual, the command
10369texinfo.texi(,10687) causes @TeX{} to print the entity's name and its arguments on the left
10370texinfo.texi(,10688) margin and print the category next to the right margin.  In both
10371texinfo.texi(,10689) output formats, the body of the definition is indented.  Also, the
10372texinfo.texi(,10690) name of the entity is entered into the appropriate index:
10373texinfo.texi(,10691) @code{@@deffn} enters the name into the index of functions,
10374texinfo.texi(,10692) @code{@@defvr} enters it into the index of variables, and so
10375texinfo.texi(,10693) on.@refill
10376texinfo.texi(,10694)
10377texinfo.texi(,10695) A manual need not and should not contain more than one definition for
10378texinfo.texi(,10696) a given name.  An appendix containing a summary should use
10379texinfo.texi(,10697) @code{@@table} rather than the definition commands.@refill
10380texinfo.texi(,10698)
10381texinfo.texi(,10699) @menu
10382texinfo.texi(,10700) * Def Cmd Template::            How to structure a description using a
10383texinfo.texi(,10701)                                   definition command.
10384texinfo.texi(,10702) * Optional Arguments::          How to handle optional and repeated arguments.
10385texinfo.texi(,10703) * deffnx::                      How to group two or more `first' lines.
10386texinfo.texi(,10704) * Def Cmds in Detail::          All the definition commands.
10387texinfo.texi(,10705) * Def Cmd Conventions::         Conventions for writing definitions.
10388texinfo.texi(,10706) * Sample Function Definition::
10389texinfo.texi(,10707) @end menu
10390texinfo.texi(,10708)
10391texinfo.texi(,10709) @node Def Cmd Template, Optional Arguments, Definition Commands, Definition Commands
10392texinfo.texi(,10710) @section The Template for a Definition
10393texinfo.texi(,10711) @cindex Definition template
10394texinfo.texi(,10712) @cindex Template for a definition
10395texinfo.texi(,10713)
10396texinfo.texi(,10714) The @code{@@deffn} command is used for definitions of entities that
10397texinfo.texi(,10715) resemble functions.  To write a definition using the @code{@@deffn}
10398texinfo.texi(,10716) command, write the @code{@@deffn} command at the beginning of a line
10399texinfo.texi(,10717) and follow it on the same line by the category of the entity, the name
10400texinfo.texi(,10718) of the entity itself, and its arguments (if any).  Then write the body
10401texinfo.texi(,10719) of the definition on succeeding lines.  (You may embed examples in the
10402texinfo.texi(,10720) body.)  Finally, end the definition with an @code{@@end deffn} command
10403texinfo.texi(,10721) written on a line of its own.  (The other definition commands follow
10404texinfo.texi(,10722) the same format.)@refill
10405texinfo.texi(,10723)
10406texinfo.texi(,10724) The template for a definition looks like this:
10407texinfo.texi(,10725)
10408texinfo.texi(,10726) @example
10409texinfo.texi(,10727) @group
10410texinfo.texi(,10728) @@deffn @var{category} @var{name} @var{arguments}@dots{}
10411texinfo.texi(,10729) @var{body-of-definition}
10412texinfo.texi(,10730) @@end deffn
10413texinfo.texi(,10731) @end group
10414texinfo.texi(,10732) @end example
10415texinfo.texi(,10733)
10416texinfo.texi(,10734) @need 700
10417texinfo.texi(,10735) @noindent
10418texinfo.texi(,10736) For example,
10419texinfo.texi(,10737)
10420texinfo.texi(,10738) @example
10421texinfo.texi(,10739) @group
10422texinfo.texi(,10740) @@deffn Command forward-word count
10423texinfo.texi(,10741) This command moves point forward @@var@{count@} words
10424texinfo.texi(,10742) (or backward if @@var@{count@} is negative). @dots{}
10425texinfo.texi(,10743) @@end deffn
10426texinfo.texi(,10744) @end group
10427texinfo.texi(,10745) @end example
10428texinfo.texi(,10746)
10429texinfo.texi(,10747) @noindent
10430texinfo.texi(,10748) produces
10431texinfo.texi(,10749)
10432texinfo.texi(,10750) @quotation
10433texinfo.texi(,10751) @deffn Command forward-word count
10434texinfo.texi(,10752) This function moves point forward @var{count} words
10435texinfo.texi(,10753) (or backward if @var{count} is negative). @dots{}
10436texinfo.texi(,10754) @end deffn
10437texinfo.texi(,10755) @end quotation
10438texinfo.texi(,10756)
10439texinfo.texi(,10757) Capitalize the category name like a title.  If the name of the
10440texinfo.texi(,10758) category contains spaces, as in the phrase `Interactive Command',
10441texinfo.texi(,10759) write braces around it.  For example:@refill
10442texinfo.texi(,10760)
10443texinfo.texi(,10761) @example
10444texinfo.texi(,10762) @group
10445texinfo.texi(,10763) @@deffn @{Interactive Command@} isearch-forward
10446texinfo.texi(,10764) @dots{}
10447texinfo.texi(,10765) @@end deffn
10448texinfo.texi(,10766) @end group
10449texinfo.texi(,10767) @end example
10450texinfo.texi(,10768)
10451texinfo.texi(,10769) @noindent
10452texinfo.texi(,10770) Otherwise, the second word will be mistaken for the name of the
10453texinfo.texi(,10771) entity.@refill
10454texinfo.texi(,10772)
10455texinfo.texi(,10773) Some of the definition commands are more general than others.  The
10456texinfo.texi(,10774) @code{@@deffn} command, for example, is the general definition command
10457texinfo.texi(,10775) for functions and the like---for entities that may take arguments.  When
10458texinfo.texi(,10776) you use this command, you specify the category to which the entity
10459texinfo.texi(,10777) belongs.  The @code{@@deffn} command possesses three predefined,
10460texinfo.texi(,10778) specialized variations, @code{@@defun}, @code{@@defmac}, and
10461texinfo.texi(,10779) @code{@@defspec}, that specify the category for you: ``Function'',
10462texinfo.texi(,10780) ``Macro'', and ``Special Form'' respectively.  (In Lisp, a special form
10463texinfo.texi(,10781) is an entity much like a function.)  The @code{@@defvr} command also is
10464texinfo.texi(,10782) accompanied by several predefined, specialized variations for describing
10465texinfo.texi(,10783) particular kinds of variables.@refill
10466texinfo.texi(,10784)
10467texinfo.texi(,10785) The template for a specialized definition, such as @code{@@defun}, is
10468texinfo.texi(,10786) similar to the template for a generalized definition, except that you
10469texinfo.texi(,10787) do not need to specify the category:@refill
10470texinfo.texi(,10788)
10471texinfo.texi(,10789) @example
10472texinfo.texi(,10790) @group
10473texinfo.texi(,10791) @@defun @var{name} @var{arguments}@dots{}
10474texinfo.texi(,10792) @var{body-of-definition}
10475texinfo.texi(,10793) @@end defun
10476texinfo.texi(,10794) @end group
10477texinfo.texi(,10795) @end example
10478texinfo.texi(,10796)
10479texinfo.texi(,10797) @noindent
10480texinfo.texi(,10798) Thus,
10481texinfo.texi(,10799)
10482texinfo.texi(,10800) @example
10483texinfo.texi(,10801) @group
10484texinfo.texi(,10802) @@defun buffer-end flag
10485texinfo.texi(,10803) This function returns @@code@{(point-min)@} if @@var@{flag@}
10486texinfo.texi(,10804) is less than 1, @@code@{(point-max)@} otherwise.
10487texinfo.texi(,10805) @dots{}
10488texinfo.texi(,10806) @@end defun
10489texinfo.texi(,10807) @end group
10490texinfo.texi(,10808) @end example
10491texinfo.texi(,10809)
10492texinfo.texi(,10810) @noindent
10493texinfo.texi(,10811) produces
10494texinfo.texi(,10812)
10495texinfo.texi(,10813) @quotation
10496texinfo.texi(,10814) @defun buffer-end flag
10497texinfo.texi(,10815) This function returns @code{(point-min)} if @var{flag} is less than 1,
10498texinfo.texi(,10816) @code{(point-max)} otherwise.  @dots{}
10499texinfo.texi(,10817) @end defun
10500texinfo.texi(,10818) @end quotation
10501texinfo.texi(,10819)
10502texinfo.texi(,10820) @noindent
10503texinfo.texi(,10821) @xref{Sample Function Definition, Sample Function Definition, A Sample
10504texinfo.texi(,10822) Function Definition}, for a more detailed example of a function
10505texinfo.texi(,10823) definition, including the use of @code{@@example} inside the
10506texinfo.texi(,10824) definition.@refill
10507texinfo.texi(,10825)
10508texinfo.texi(,10826) The other specialized commands work like @code{@@defun}.@refill
10509texinfo.texi(,10827)
10510texinfo.texi(,10828) @cindex Macros in definition commands
10511texinfo.texi(,10829) Note that, due to implementation difficulties, macros are not expanded
10512texinfo.texi(,10830) in @code{@@deffn} and all the other definition commands.
10513texinfo.texi(,10831)
10514texinfo.texi(,10832) @node Optional Arguments, deffnx, Def Cmd Template, Definition Commands
10515texinfo.texi(,10833) @section Optional and Repeated Arguments
10516texinfo.texi(,10834) @cindex Optional and repeated arguments
10517texinfo.texi(,10835) @cindex Repeated and optional arguments
10518texinfo.texi(,10836) @cindex Arguments, repeated and optional
10519texinfo.texi(,10837) @cindex Syntax, optional & repeated arguments
10520texinfo.texi(,10838) @cindex Meta-syntactic chars for arguments
10521texinfo.texi(,10839)
10522texinfo.texi(,10840) Some entities take optional or repeated arguments, which may be
10523texinfo.texi(,10841) specified by a distinctive glyph that uses square brackets and
10524texinfo.texi(,10842) ellipses.  For @w{example}, a special form often breaks its argument list
10525texinfo.texi(,10843) into separate arguments in more complicated ways than a
10526texinfo.texi(,10844) straightforward function.@refill
10527texinfo.texi(,10845)
10528texinfo.texi(,10858) @c The following looks better in Info (no `r', `samp' and `code'):
10529texinfo.texi(,10860) An argument enclosed within square brackets is optional.
10530texinfo.texi(,10861) Thus, [@var{optional-arg}] means that @var{optional-arg} is optional.
10531texinfo.texi(,10862) An argument followed by an ellipsis is optional
10532texinfo.texi(,10863) and may be repeated more than once.
10533texinfo.texi(,10864) @c This is consistent with Emacs Lisp Reference manual
10534texinfo.texi(,10865) Thus, @var{repeated-args}@dots{} stands for zero or more arguments.
10535texinfo.texi(,10866) Parentheses are used when several arguments are grouped
10536texinfo.texi(,10867) into additional levels of list structure in Lisp.
10537texinfo.texi(,10869)
10538texinfo.texi(,10870) Here is the @code{@@defspec} line of an example of an imaginary
10539texinfo.texi(,10871) special form:@refill
10540texinfo.texi(,10872)
10541texinfo.texi(,10873) @quotation
10542texinfo.texi(,10874) @defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{}
10543texinfo.texi(,10875) @end defspec
10544texinfo.texi(,10876) @tex
10545texinfo.texi(,10877) \vskip \parskip
10546texinfo.texi(,10878) @end tex
10547texinfo.texi(,10879) @end quotation
10548texinfo.texi(,10880)
10549texinfo.texi(,10881) @noindent
10550texinfo.texi(,10882) In this example, the arguments @var{from} and @var{to} are optional,
10551texinfo.texi(,10883) but must both be present or both absent.  If they are present,
10552texinfo.texi(,10884) @var{inc} may optionally be specified as well.  These arguments are
10553texinfo.texi(,10885) grouped with the argument @var{var} into a list, to distinguish them
10554texinfo.texi(,10886) from @var{body}, which includes all remaining elements of the
10555texinfo.texi(,10887) form.@refill
10556texinfo.texi(,10888)
10557texinfo.texi(,10889) In a Texinfo source file, this @code{@@defspec} line is written like
10558texinfo.texi(,10890) this (except it would not be split over two lines, as it is in this
10559texinfo.texi(,10891) example).@refill
10560texinfo.texi(,10892)
10561texinfo.texi(,10893) @example
10562texinfo.texi(,10894) @group
10563texinfo.texi(,10895) @@defspec foobar (@@var@{var@} [@@var@{from@} @@var@{to@}
10564texinfo.texi(,10896)      [@@var@{inc@}]]) @@var@{body@}@@dots@{@}
10565texinfo.texi(,10897) @end group
10566texinfo.texi(,10898) @end example
10567texinfo.texi(,10899)
10568texinfo.texi(,10900) @noindent
10569texinfo.texi(,10901) The function is listed in the Command and Variable Index under
10570texinfo.texi(,10902) @samp{foobar}.@refill
10571texinfo.texi(,10903)
10572texinfo.texi(,10904) @node deffnx, Def Cmds in Detail, Optional Arguments, Definition Commands
10573texinfo.texi(,10905) @section Two or More `First' Lines
10574texinfo.texi(,10906) @cindex Two `First' Lines for @code{@@deffn}
10575texinfo.texi(,10907) @cindex Grouping two definitions together
10576texinfo.texi(,10908) @cindex Definitions grouped together
10577texinfo.texi(,10909) @findex deffnx
10578texinfo.texi(,10910)
10579texinfo.texi(,10911) To create two or more `first' or header lines for a definition, follow
10580texinfo.texi(,10912) the first @code{@@deffn} line by a line beginning with @code{@@deffnx}.
10581texinfo.texi(,10913) The @code{@@deffnx} command works exactly like @code{@@deffn}
10582texinfo.texi(,10914) except that it does not generate extra vertical white space between it
10583texinfo.texi(,10915) and the preceding line.@refill
10584texinfo.texi(,10916)
10585texinfo.texi(,10917) @need 1000
10586texinfo.texi(,10918) For example,
10587texinfo.texi(,10919)
10588texinfo.texi(,10920) @example
10589texinfo.texi(,10921) @group
10590texinfo.texi(,10922) @@deffn @{Interactive Command@} isearch-forward
10591texinfo.texi(,10923) @@deffnx @{Interactive Command@} isearch-backward
10592texinfo.texi(,10924) These two search commands are similar except @dots{}
10593texinfo.texi(,10925) @@end deffn
10594texinfo.texi(,10926) @end group
10595texinfo.texi(,10927) @end example
10596texinfo.texi(,10928)
10597texinfo.texi(,10929) @noindent
10598texinfo.texi(,10930) produces
10599texinfo.texi(,10931)
10600texinfo.texi(,10932) @deffn {Interactive Command} isearch-forward
10601texinfo.texi(,10933) @deffnx {Interactive Command} isearch-backward
10602texinfo.texi(,10934) These two search commands are similar except @dots{}
10603texinfo.texi(,10935) @end deffn
10604texinfo.texi(,10936)
10605texinfo.texi(,10937) Each definition command has an `x' form: @code{@@defunx},
10606texinfo.texi(,10938) @code{@@defvrx}, @code{@@deftypefunx}, etc.
10607texinfo.texi(,10939)
10608texinfo.texi(,10940) The `x' forms work just like @code{@@itemx}; see @ref{itemx, , @code{@@itemx}}.
10609texinfo.texi(,10941)
10610texinfo.texi(,10942) @node Def Cmds in Detail, Def Cmd Conventions, deffnx, Definition Commands
10611texinfo.texi(,10943) @section The Definition Commands
10612texinfo.texi(,10944)
10613texinfo.texi(,10945) Texinfo provides more than a dozen definition commands, all of which
10614texinfo.texi(,10946) are described in this section.@refill
10615texinfo.texi(,10947)
10616texinfo.texi(,10948) The definition commands automatically enter the name of the entity in
10617texinfo.texi(,10949) the appropriate index: for example, @code{@@deffn}, @code{@@defun},
10618texinfo.texi(,10950) and @code{@@defmac} enter function names in the index of functions;
10619texinfo.texi(,10951) @code{@@defvr} and @code{@@defvar} enter variable names in the index
10620texinfo.texi(,10952) of variables.@refill
10621texinfo.texi(,10953)
10622texinfo.texi(,10954) Although the examples that follow mostly illustrate Lisp, the commands
10623texinfo.texi(,10955) can be used for other programming languages.@refill
10624texinfo.texi(,10956)
10625texinfo.texi(,10957) @menu
10626texinfo.texi(,10958) * Functions Commands::          Commands for functions and similar entities.
10627texinfo.texi(,10959) * Variables Commands::          Commands for variables and similar entities.
10628texinfo.texi(,10960) * Typed Functions::             Commands for functions in typed languages.
10629texinfo.texi(,10961) * Typed Variables::             Commands for variables in typed languages.
10630texinfo.texi(,10962) * Abstract Objects::            Commands for object-oriented programming.
10631texinfo.texi(,10963) * Data Types::                  The definition command for data types.
10632texinfo.texi(,10964) @end menu
10633texinfo.texi(,10965)
10634texinfo.texi(,10966) @node Functions Commands, Variables Commands, Def Cmds in Detail, Def Cmds in Detail
10635texinfo.texi(,10967) @subsection Functions and Similar Entities
10636texinfo.texi(,10968)
10637texinfo.texi(,10969) This section describes the commands for describing functions and similar
10638texinfo.texi(,10970) entities:@refill
10639texinfo.texi(,10971)
10640texinfo.texi(,10972) @table @code
10641texinfo.texi(,10973) @findex deffn
10642texinfo.texi(,10974) @item @@deffn @var{category} @var{name} @var{arguments}@dots{}
10643texinfo.texi(,10975) The @code{@@deffn} command is the general definition command for
10644texinfo.texi(,10976) functions, interactive commands, and similar entities that may take
10645texinfo.texi(,10977) arguments.  You must choose a term to describe the category of entity
10646texinfo.texi(,10978) being defined; for example, ``Function'' could be used if the entity is
10647texinfo.texi(,10979) a function.  The @code{@@deffn} command is written at the beginning of a
10648texinfo.texi(,10980) line and is followed on the same line by the category of entity being
10649texinfo.texi(,10981) described, the name of this particular entity, and its arguments, if
10650texinfo.texi(,10982) any.  Terminate the definition with @code{@@end deffn} on a line of its
10651texinfo.texi(,10983) own.@refill
10652texinfo.texi(,10984)
10653texinfo.texi(,10985) @need 750
10654texinfo.texi(,10986) For example, here is a definition:
10655texinfo.texi(,10987)
10656texinfo.texi(,10988) @example
10657texinfo.texi(,10989) @group
10658texinfo.texi(,10990) @@deffn Command forward-char nchars
10659texinfo.texi(,10991) Move point forward @@var@{nchars@} characters.
10660texinfo.texi(,10992) @@end deffn
10661texinfo.texi(,10993) @end group
10662texinfo.texi(,10994) @end example
10663texinfo.texi(,10995)
10664texinfo.texi(,10996) @noindent
10665texinfo.texi(,10997) This shows a rather terse definition for a ``command'' named
10666texinfo.texi(,10998) @code{forward-char} with one argument, @var{nchars}.
10667texinfo.texi(,10999)
10668texinfo.texi(,11000) @code{@@deffn} prints argument names such as @var{nchars} in italics or
10669texinfo.texi(,11001) upper case, as if @code{@@var} had been used, because we think of these
10670texinfo.texi(,11002) names as metasyntactic variables---they stand for the actual argument
10671texinfo.texi(,11003) values.  Within the text of the description, write an argument name
10672texinfo.texi(,11004) explicitly with @code{@@var} to refer to the value of the argument.  In
10673texinfo.texi(,11005) the example above, we used @samp{@@var@{nchars@}} in this way.
10674texinfo.texi(,11006)
10675texinfo.texi(,11007) The template for @code{@@deffn} is:
10676texinfo.texi(,11008)
10677texinfo.texi(,11009) @example
10678texinfo.texi(,11010) @group
10679texinfo.texi(,11011) @@deffn @var{category} @var{name} @var{arguments}@dots{}
10680texinfo.texi(,11012) @var{body-of-definition}
10681texinfo.texi(,11013) @@end deffn
10682texinfo.texi(,11014) @end group
10683texinfo.texi(,11015) @end example
10684texinfo.texi(,11016)
10685texinfo.texi(,11017) @findex defun
10686texinfo.texi(,11018) @item @@defun @var{name} @var{arguments}@dots{}
10687texinfo.texi(,11019) The @code{@@defun} command is the definition command for functions.
10688texinfo.texi(,11020) @code{@@defun} is equivalent to @samp{@@deffn Function
10689texinfo.texi(,11021) @dots{}}.@refill
10690texinfo.texi(,11022)
10691texinfo.texi(,11023) @need 800
10692texinfo.texi(,11024) @noindent
10693texinfo.texi(,11025) For example,
10694texinfo.texi(,11026)
10695texinfo.texi(,11027) @example
10696texinfo.texi(,11028) @group
10697texinfo.texi(,11029) @@defun set symbol new-value
10698texinfo.texi(,11030) Change the value of the symbol @@var@{symbol@}
10699texinfo.texi(,11031) to @@var@{new-value@}.
10700texinfo.texi(,11032) @@end defun
10701texinfo.texi(,11033) @end group
10702texinfo.texi(,11034) @end example
10703texinfo.texi(,11035)
10704texinfo.texi(,11036) @noindent
10705texinfo.texi(,11037) shows a rather terse definition for a function @code{set} whose
10706texinfo.texi(,11038) arguments are @var{symbol} and @var{new-value}.  The argument names on
10707texinfo.texi(,11039) the @code{@@defun} line automatically appear in italics or upper case as
10708texinfo.texi(,11040) if they were enclosed in @code{@@var}.  Terminate the definition with
10709texinfo.texi(,11041) @code{@@end defun} on a line of its own.@refill
10710texinfo.texi(,11042)
10711texinfo.texi(,11043) The template is:
10712texinfo.texi(,11044)
10713texinfo.texi(,11045) @example
10714texinfo.texi(,11046) @group
10715texinfo.texi(,11047) @@defun @var{function-name} @var{arguments}@dots{}
10716texinfo.texi(,11048) @var{body-of-definition}
10717texinfo.texi(,11049) @@end defun
10718texinfo.texi(,11050) @end group
10719texinfo.texi(,11051) @end example
10720texinfo.texi(,11052)
10721texinfo.texi(,11053) @code{@@defun} creates an entry in the index of functions.
10722texinfo.texi(,11054)
10723texinfo.texi(,11055) @findex defmac
10724texinfo.texi(,11056) @item @@defmac @var{name} @var{arguments}@dots{}
10725texinfo.texi(,11057) The @code{@@defmac} command is the definition command for macros.
10726texinfo.texi(,11058) @code{@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and
10727texinfo.texi(,11059) works like @code{@@defun}.@refill
10728texinfo.texi(,11060)
10729texinfo.texi(,11061) @findex defspec
10730texinfo.texi(,11062) @item @@defspec @var{name} @var{arguments}@dots{}
10731texinfo.texi(,11063) The @code{@@defspec} command is the definition command for special
10732texinfo.texi(,11064) forms.  (In Lisp, a special form is an entity much like a function,
10733texinfo.texi(,11065) @pxref{Special Forms,,, elisp, GNU Emacs Lisp Reference Manual}.)
10734texinfo.texi(,11066) @code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@}
10735texinfo.texi(,11067) @dots{}} and works like @code{@@defun}.@refill
10736texinfo.texi(,11068) @end table
10737texinfo.texi(,11069)
10738texinfo.texi(,11070) @node Variables Commands, Typed Functions, Functions Commands, Def Cmds in Detail
10739texinfo.texi(,11071) @subsection Variables and Similar Entities
10740texinfo.texi(,11072)
10741texinfo.texi(,11073) Here are the commands for defining variables and similar
10742texinfo.texi(,11074) entities:@refill
10743texinfo.texi(,11075)
10744texinfo.texi(,11076) @table @code
10745texinfo.texi(,11077) @findex defvr
10746texinfo.texi(,11078) @item @@defvr @var{category} @var{name}
10747texinfo.texi(,11079) The @code{@@defvr} command is a general definition command for
10748texinfo.texi(,11080) something like a variable---an entity that records a value.  You must
10749texinfo.texi(,11081) choose a term to describe the category of entity being defined; for
10750texinfo.texi(,11082) example, ``Variable'' could be used if the entity is a variable.
10751texinfo.texi(,11083) Write the @code{@@defvr} command at the beginning of a line and
10752texinfo.texi(,11084) follow it on the same line by the category of the entity and the
10753texinfo.texi(,11085) name of the entity.
10754texinfo.texi(,11086)
10755texinfo.texi(,11087) Capitalize the category name like a title.  If the name of the category
10756texinfo.texi(,11088) contains spaces, as in the name ``User Option'', enclose it in braces.
10757texinfo.texi(,11089) Otherwise, the second word will be mistaken for the name of the entity.
10758texinfo.texi(,11090) For example,
10759texinfo.texi(,11091)
10760texinfo.texi(,11092) @example
10761texinfo.texi(,11093) @group
10762texinfo.texi(,11094) @@defvr @{User Option@} fill-column
10763texinfo.texi(,11095) This buffer-local variable specifies
10764texinfo.texi(,11096) the maximum width of filled lines.
10765texinfo.texi(,11097) @dots{}
10766texinfo.texi(,11098) @@end defvr
10767texinfo.texi(,11099) @end group
10768texinfo.texi(,11100) @end example
10769texinfo.texi(,11101)
10770texinfo.texi(,11102) Terminate the definition with @code{@@end defvr} on a line of its
10771texinfo.texi(,11103) own.@refill
10772texinfo.texi(,11104)
10773texinfo.texi(,11105) The template is:
10774texinfo.texi(,11106)
10775texinfo.texi(,11107) @example
10776texinfo.texi(,11108) @group
10777texinfo.texi(,11109) @@defvr @var{category} @var{name}
10778texinfo.texi(,11110) @var{body-of-definition}
10779texinfo.texi(,11111) @@end defvr
10780texinfo.texi(,11112) @end group
10781texinfo.texi(,11113) @end example
10782texinfo.texi(,11114)
10783texinfo.texi(,11115) @code{@@defvr} creates an entry in the index of variables for @var{name}.
10784texinfo.texi(,11116)
10785texinfo.texi(,11117) @findex defvar
10786texinfo.texi(,11118) @item @@defvar @var{name}
10787texinfo.texi(,11119) The @code{@@defvar} command is the definition command for variables.
10788texinfo.texi(,11120) @code{@@defvar} is equivalent to @samp{@@defvr Variable
10789texinfo.texi(,11121) @dots{}}.@refill
10790texinfo.texi(,11122)
10791texinfo.texi(,11123) @need 750
10792texinfo.texi(,11124) For example:
10793texinfo.texi(,11125)
10794texinfo.texi(,11126) @example
10795texinfo.texi(,11127) @group
10796texinfo.texi(,11128) @@defvar kill-ring
10797texinfo.texi(,11129) @dots{}
10798texinfo.texi(,11130) @@end defvar
10799texinfo.texi(,11131) @end group
10800texinfo.texi(,11132) @end example
10801texinfo.texi(,11133)
10802texinfo.texi(,11134) The template is:
10803texinfo.texi(,11135)
10804texinfo.texi(,11136) @example
10805texinfo.texi(,11137) @group
10806texinfo.texi(,11138) @@defvar @var{name}
10807texinfo.texi(,11139) @var{body-of-definition}
10808texinfo.texi(,11140) @@end defvar
10809texinfo.texi(,11141) @end group
10810texinfo.texi(,11142) @end example
10811texinfo.texi(,11143)
10812texinfo.texi(,11144) @code{@@defvar} creates an entry in the index of variables for
10813texinfo.texi(,11145) @var{name}.@refill
10814texinfo.texi(,11146)
10815texinfo.texi(,11147) @findex defopt
10816texinfo.texi(,11148) @item @@defopt @var{name}
10817texinfo.texi(,11149) @cindex User options, marking
10818texinfo.texi(,11150) The @code{@@defopt} command is the definition command for @dfn{user
10819texinfo.texi(,11151) options}, i.e., variables intended for users to change according to
10820texinfo.texi(,11152) taste; Emacs has many such (@pxref{Variables,,, emacs, The GNU Emacs
10821texinfo.texi(,11153) Manual}).  @code{@@defopt} is equivalent to @samp{@@defvr @{User
10822texinfo.texi(,11154) Option@} @dots{}} and works like @code{@@defvar}.@refill
10823texinfo.texi(,11155) @end table
10824texinfo.texi(,11156)
10825texinfo.texi(,11157)
10826texinfo.texi(,11158) @node Typed Functions, Typed Variables, Variables Commands, Def Cmds in Detail
10827texinfo.texi(,11159) @subsection Functions in Typed Languages
10828texinfo.texi(,11160)
10829texinfo.texi(,11161) The @code{@@deftypefn} command and its variations are for describing
10830texinfo.texi(,11162) functions in languages in which you must declare types of variables and
10831texinfo.texi(,11163) functions, such as C and C++.
10832texinfo.texi(,11164)
10833texinfo.texi(,11165) @table @code
10834texinfo.texi(,11166) @findex deftypefn
10835texinfo.texi(,11167) @item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{}
10836texinfo.texi(,11168) The @code{@@deftypefn} command is the general definition command for
10837texinfo.texi(,11169) functions and similar entities that may take arguments and that are
10838texinfo.texi(,11170) typed.  The @code{@@deftypefn} command is written at the beginning of
10839texinfo.texi(,11171) a line and is followed on the same line by the category of entity
10840texinfo.texi(,11172) being described, the type of the returned value, the name of this
10841texinfo.texi(,11173) particular entity, and its arguments, if any.@refill
10842texinfo.texi(,11174)
10843texinfo.texi(,11175) @need 800
10844texinfo.texi(,11176) @noindent
10845texinfo.texi(,11177) For example,
10846texinfo.texi(,11178)
10847texinfo.texi(,11179) @example
10848texinfo.texi(,11180) @group
10849texinfo.texi(,11181) @@deftypefn @{Library Function@} int foobar
10850texinfo.texi(,11182)    (int @@var@{foo@}, float @@var@{bar@})
10851texinfo.texi(,11183) @dots{}
10852texinfo.texi(,11184) @@end deftypefn
10853texinfo.texi(,11185) @end group
10854texinfo.texi(,11186) @end example
10855texinfo.texi(,11187)
10856texinfo.texi(,11188) @need 1000
10857texinfo.texi(,11189) @noindent
10858texinfo.texi(,11190) (where the text before the ``@dots{}'', shown above as two lines, would
10859texinfo.texi(,11191) actually be a single line in a real Texinfo file) produces the following
10860texinfo.texi(,11192) in Info:
10861texinfo.texi(,11193)
10862texinfo.texi(,11194) @smallexample
10863texinfo.texi(,11195) @group
10864texinfo.texi(,11196) -- Library Function: int foobar (int FOO, float BAR)
10865texinfo.texi(,11197) @dots{}
10866texinfo.texi(,11198) @end group
10867texinfo.texi(,11199) @end smallexample
10868texinfo.texi(,11210)
10869texinfo.texi(,11211) This means that @code{foobar} is a ``library function'' that returns an
10870texinfo.texi(,11212) @code{int}, and its arguments are @var{foo} (an @code{int}) and
10871texinfo.texi(,11213) @var{bar} (a @code{float}).@refill
10872texinfo.texi(,11214)
10873texinfo.texi(,11215) The argument names that you write in @code{@@deftypefn} are not subject
10874texinfo.texi(,11216) to an implicit @code{@@var}---since the actual names of the arguments in
10875texinfo.texi(,11217) @code{@@deftypefn} are typically scattered among data type names and
10876texinfo.texi(,11218) keywords, Texinfo cannot find them without help.  Instead, you must write
10877texinfo.texi(,11219) @code{@@var} explicitly around the argument names.  In the example
10878texinfo.texi(,11220) above, the argument names are @samp{foo} and @samp{bar}.@refill
10879texinfo.texi(,11221)
10880texinfo.texi(,11222) The template for @code{@@deftypefn} is:@refill
10881texinfo.texi(,11223)
10882texinfo.texi(,11224) @example
10883texinfo.texi(,11225) @group
10884texinfo.texi(,11226) @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{}
10885texinfo.texi(,11227) @var{body-of-description}
10886texinfo.texi(,11228) @@end deftypefn
10887texinfo.texi(,11229) @end group
10888texinfo.texi(,11230) @end example
10889texinfo.texi(,11231)
10890texinfo.texi(,11232) @noindent
10891texinfo.texi(,11233) Note that if the @var{category} or @var{data type} is more than one
10892texinfo.texi(,11234) word then it must be enclosed in braces to make it a single argument.@refill
10893texinfo.texi(,11235)
10894texinfo.texi(,11236) If you are describing a procedure in a language that has packages,
10895texinfo.texi(,11237) such as Ada, you might consider using @code{@@deftypefn} in a manner
10896texinfo.texi(,11238) somewhat contrary to the convention described in the preceding
10897texinfo.texi(,11239) paragraphs.@refill
10898texinfo.texi(,11240)
10899texinfo.texi(,11241) @need 800
10900texinfo.texi(,11242) @noindent
10901texinfo.texi(,11243) For example:
10902texinfo.texi(,11244)
10903texinfo.texi(,11245) @example
10904texinfo.texi(,11246) @group
10905texinfo.texi(,11247) @@deftypefn stacks private push
10906texinfo.texi(,11248)         (@@var@{s@}:in out stack;
10907texinfo.texi(,11249)         @@var@{n@}:in integer)
10908texinfo.texi(,11250) @dots{}
10909texinfo.texi(,11251) @@end deftypefn
10910texinfo.texi(,11252) @end group
10911texinfo.texi(,11253) @end example
10912texinfo.texi(,11254)
10913texinfo.texi(,11255) @noindent
10914texinfo.texi(,11256) (The @code{@@deftypefn} arguments are shown split into three lines, but
10915texinfo.texi(,11257) would be a single line in a real Texinfo file.)
10916texinfo.texi(,11258)
10917texinfo.texi(,11259) In this instance, the procedure is classified as belonging to the
10918texinfo.texi(,11260) package @code{stacks} rather than classified as a `procedure' and its
10919texinfo.texi(,11261) data type is described as @code{private}.  (The name of the procedure
10920texinfo.texi(,11262) is @code{push}, and its arguments are @var{s} and @var{n}.)@refill
10921texinfo.texi(,11263)
10922texinfo.texi(,11264) @code{@@deftypefn} creates an entry in the index of functions for
10923texinfo.texi(,11265) @var{name}.@refill
10924texinfo.texi(,11266)
10925texinfo.texi(,11267) @item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{}
10926texinfo.texi(,11268) @findex deftypefun
10927texinfo.texi(,11269) The @code{@@deftypefun} command is the specialized definition command
10928texinfo.texi(,11270) for functions in typed languages.  The command is equivalent to
10929texinfo.texi(,11271) @samp{@@deftypefn Function @dots{}}.@refill
10930texinfo.texi(,11272)
10931texinfo.texi(,11273) @need 800
10932texinfo.texi(,11274) @noindent
10933texinfo.texi(,11275) Thus,
10934texinfo.texi(,11276)
10935texinfo.texi(,11277) @smallexample
10936texinfo.texi(,11278) @group
10937texinfo.texi(,11279) @@deftypefun int foobar (int @@var@{foo@}, float @@var@{bar@})
10938texinfo.texi(,11280) @dots{}
10939texinfo.texi(,11281) @@end deftypefun
10940texinfo.texi(,11282) @end group
10941texinfo.texi(,11283) @end smallexample
10942texinfo.texi(,11284)
10943texinfo.texi(,11285) @noindent
10944texinfo.texi(,11286) produces the following in Info:
10945texinfo.texi(,11287)
10946texinfo.texi(,11288) @example
10947texinfo.texi(,11289) @group
10948texinfo.texi(,11290) -- Function: int foobar (int FOO, float BAR)
10949texinfo.texi(,11291) @dots{}
10950texinfo.texi(,11292) @end group
10951texinfo.texi(,11293) @end example
10952texinfo.texi(,11306)
10953texinfo.texi(,11307) @need 800
10954texinfo.texi(,11308) The template is:
10955texinfo.texi(,11309)
10956texinfo.texi(,11310) @example
10957texinfo.texi(,11311) @group
10958texinfo.texi(,11312) @@deftypefun @var{type} @var{name} @var{arguments}@dots{}
10959texinfo.texi(,11313) @var{body-of-description}
10960texinfo.texi(,11314) @@end deftypefun
10961texinfo.texi(,11315) @end group
10962texinfo.texi(,11316) @end example
10963texinfo.texi(,11317)
10964texinfo.texi(,11318) @code{@@deftypefun} creates an entry in the index of functions for
10965texinfo.texi(,11319) @var{name}.@refill
10966texinfo.texi(,11320)
10967texinfo.texi(,11321) @end table
10968texinfo.texi(,11322)
10969texinfo.texi(,11323)
10970texinfo.texi(,11324) @node Typed Variables, Abstract Objects, Typed Functions, Def Cmds in Detail
10971texinfo.texi(,11325) @subsection Variables in Typed Languages
10972texinfo.texi(,11326)
10973texinfo.texi(,11327) Variables in typed languages are handled in a manner similar to
10974texinfo.texi(,11328) functions in typed languages.  @xref{Typed Functions}.  The general
10975texinfo.texi(,11329) definition command @code{@@deftypevr} corresponds to
10976texinfo.texi(,11330) @code{@@deftypefn} and the specialized definition command
10977texinfo.texi(,11331) @code{@@deftypevar} corresponds to @code{@@deftypefun}.@refill
10978texinfo.texi(,11332)
10979texinfo.texi(,11333) @table @code
10980texinfo.texi(,11334) @findex deftypevr
10981texinfo.texi(,11335) @item @@deftypevr @var{category} @var{data-type} @var{name}
10982texinfo.texi(,11336) The @code{@@deftypevr} command is the general definition command for
10983texinfo.texi(,11337) something like a variable in a typed language---an entity that records
10984texinfo.texi(,11338) a value.  You must choose a term to describe the category of the
10985texinfo.texi(,11339) entity being defined; for example, ``Variable'' could be used if the
10986texinfo.texi(,11340) entity is a variable.@refill
10987texinfo.texi(,11341)
10988texinfo.texi(,11342) The @code{@@deftypevr} command is written at the beginning of a line
10989texinfo.texi(,11343) and is followed on the same line by the category of the entity
10990texinfo.texi(,11344) being described, the data type, and the name of this particular
10991texinfo.texi(,11345) entity.@refill
10992texinfo.texi(,11346)
10993texinfo.texi(,11347) @need 800
10994texinfo.texi(,11348) @noindent
10995texinfo.texi(,11349) For example:
10996texinfo.texi(,11350)
10997texinfo.texi(,11351) @example
10998texinfo.texi(,11352) @group
10999texinfo.texi(,11353) @@deftypevr @{Global Flag@} int enable
11000texinfo.texi(,11354) @dots{}
11001texinfo.texi(,11355) @@end deftypevr
11002texinfo.texi(,11356) @end group
11003texinfo.texi(,11357) @end example
11004texinfo.texi(,11358)
11005texinfo.texi(,11359) @noindent
11006texinfo.texi(,11360) produces the following in Info:
11007texinfo.texi(,11361)
11008texinfo.texi(,11362) @example
11009texinfo.texi(,11363) @group
11010texinfo.texi(,11364) -- Global Flag: int enable
11011texinfo.texi(,11365) @dots{}
11012texinfo.texi(,11366) @end group
11013texinfo.texi(,11367) @end example
11014texinfo.texi(,11379)
11015texinfo.texi(,11380) @need 800
11016texinfo.texi(,11381) The template is:
11017texinfo.texi(,11382)
11018texinfo.texi(,11383) @example
11019texinfo.texi(,11384) @@deftypevr @var{category} @var{data-type} @var{name}
11020texinfo.texi(,11385) @var{body-of-description}
11021texinfo.texi(,11386) @@end deftypevr
11022texinfo.texi(,11387) @end example
11023texinfo.texi(,11388)
11024texinfo.texi(,11389) @code{@@deftypevr} creates an entry in the index of variables for
11025texinfo.texi(,11390) @var{name}.@refill
11026texinfo.texi(,11391)
11027texinfo.texi(,11392) @findex deftypevar
11028texinfo.texi(,11393) @item @@deftypevar @var{data-type} @var{name}
11029texinfo.texi(,11394) The @code{@@deftypevar} command is the specialized definition command
11030texinfo.texi(,11395) for variables in typed languages.  @code{@@deftypevar} is equivalent
11031texinfo.texi(,11396) to @samp{@@deftypevr Variable @dots{}}.@refill
11032texinfo.texi(,11397)
11033texinfo.texi(,11398) @need 800
11034texinfo.texi(,11399) @noindent
11035texinfo.texi(,11400) For example:
11036texinfo.texi(,11401)
11037texinfo.texi(,11402) @example
11038texinfo.texi(,11403) @group
11039texinfo.texi(,11404) @@deftypevar int fubar
11040texinfo.texi(,11405) @dots{}
11041texinfo.texi(,11406) @@end deftypevar
11042texinfo.texi(,11407) @end group
11043texinfo.texi(,11408) @end example
11044texinfo.texi(,11409)
11045texinfo.texi(,11410) @noindent
11046texinfo.texi(,11411) produces the following in Info:
11047texinfo.texi(,11412)
11048texinfo.texi(,11413) @example
11049texinfo.texi(,11414) @group
11050texinfo.texi(,11415) -- Variable: int fubar
11051texinfo.texi(,11416) @dots{}
11052texinfo.texi(,11417) @end group
11053texinfo.texi(,11418) @end example
11054texinfo.texi(,11431)
11055texinfo.texi(,11432) @need 800
11056texinfo.texi(,11433) @noindent
11057texinfo.texi(,11434) The template is:
11058texinfo.texi(,11435)
11059texinfo.texi(,11436) @example
11060texinfo.texi(,11437) @group
11061texinfo.texi(,11438) @@deftypevar @var{data-type} @var{name}
11062texinfo.texi(,11439) @var{body-of-description}
11063texinfo.texi(,11440) @@end deftypevar
11064texinfo.texi(,11441) @end group
11065texinfo.texi(,11442) @end example
11066texinfo.texi(,11443)
11067texinfo.texi(,11444) @code{@@deftypevar} creates an entry in the index of variables for
11068texinfo.texi(,11445) @var{name}.@refill
11069texinfo.texi(,11446) @end table
11070texinfo.texi(,11447)
11071texinfo.texi(,11448) @node Abstract Objects
11072texinfo.texi(,11449) @subsection Object-Oriented Programming
11073texinfo.texi(,11450)
11074texinfo.texi(,11451) Here are the commands for formatting descriptions about abstract
11075texinfo.texi(,11452) objects, such as are used in object-oriented programming.  A class is
11076texinfo.texi(,11453) a defined type of abstract object.  An instance of a class is a
11077texinfo.texi(,11454) particular object that has the type of the class.  An instance
11078texinfo.texi(,11455) variable is a variable that belongs to the class but for which each
11079texinfo.texi(,11456) instance has its own value.@refill
11080texinfo.texi(,11457)
11081texinfo.texi(,11458) In a definition, if the name of a class is truly a name defined in the
11082texinfo.texi(,11459) programming system for a class, then you should write an @code{@@code}
11083texinfo.texi(,11460) around it.  Otherwise, it is printed in the usual text font.@refill
11084texinfo.texi(,11461)
11085texinfo.texi(,11462) @table @code
11086texinfo.texi(,11463) @findex defcv
11087texinfo.texi(,11464) @item @@defcv @var{category} @var{class} @var{name}
11088texinfo.texi(,11465) The @code{@@defcv} command is the general definition command for
11089texinfo.texi(,11466) variables associated with classes in object-oriented programming.  The
11090texinfo.texi(,11467) @code{@@defcv} command is followed by three arguments: the category of
11091texinfo.texi(,11468) thing being defined, the class to which it belongs, and its
11092texinfo.texi(,11469) name.  Thus,@refill
11093texinfo.texi(,11470)
11094texinfo.texi(,11471) @example
11095texinfo.texi(,11472) @group
11096texinfo.texi(,11473) @@defcv @{Class Option@} Window border-pattern
11097texinfo.texi(,11474) @dots{}
11098texinfo.texi(,11475) @@end defcv
11099texinfo.texi(,11476) @end group
11100texinfo.texi(,11477) @end example
11101texinfo.texi(,11478)
11102texinfo.texi(,11479) @noindent
11103texinfo.texi(,11480) illustrates how you would write the first line of a definition of the
11104texinfo.texi(,11481) @code{border-pattern} class option of the class @code{Window}.@refill
11105texinfo.texi(,11482)
11106texinfo.texi(,11483) The template is:
11107texinfo.texi(,11484) @example
11108texinfo.texi(,11485) @group
11109texinfo.texi(,11486) @@defcv @var{category} @var{class} @var{name}
11110texinfo.texi(,11487) @dots{}
11111texinfo.texi(,11488) @@end defcv
11112texinfo.texi(,11489) @end group
11113texinfo.texi(,11490) @end example
11114texinfo.texi(,11491)
11115texinfo.texi(,11492) @code{@@defcv} creates an entry in the index of variables.
11116texinfo.texi(,11493)
11117texinfo.texi(,11494) @findex defivar
11118texinfo.texi(,11495) @item @@defivar @var{class} @var{name}
11119texinfo.texi(,11496) The @code{@@defivar} command is the definition command for instance
11120texinfo.texi(,11497) variables in object-oriented programming.  @code{@@defivar} is
11121texinfo.texi(,11498) equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}@refill
11122texinfo.texi(,11499)
11123texinfo.texi(,11500) The template is:
11124texinfo.texi(,11501) @example
11125texinfo.texi(,11502) @group
11126texinfo.texi(,11503) @@defivar @var{class} @var{instance-variable-name}
11127texinfo.texi(,11504) @var{body-of-definition}
11128texinfo.texi(,11505) @@end defivar
11129texinfo.texi(,11506) @end group
11130texinfo.texi(,11507) @end example
11131texinfo.texi(,11508)
11132texinfo.texi(,11509) @code{@@defivar} creates an entry in the index of variables.
11133texinfo.texi(,11510)
11134texinfo.texi(,11511) @findex deftypeivar
11135texinfo.texi(,11512) @item @@deftypeivar @var{class} @var{data-type} @var{name}
11136texinfo.texi(,11513) The @code{@@deftypeivar} command is the definition command for typed
11137texinfo.texi(,11514) instance variables in object-oriented programming.  It is similar to
11138texinfo.texi(,11515) @code{@@defivar} with the addition of the @var{data-type} parameter to
11139texinfo.texi(,11516) specify the type of the instance variable.  @code{@@deftypeivar} creates an
11140texinfo.texi(,11517) entry in the index of variables.
11141texinfo.texi(,11518)
11142texinfo.texi(,11519) @findex defop
11143texinfo.texi(,11520) @item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
11144texinfo.texi(,11521) The @code{@@defop} command is the general definition command for
11145texinfo.texi(,11522) entities that may resemble methods in object-oriented programming.
11146texinfo.texi(,11523) These entities take arguments, as functions do, but are associated with
11147texinfo.texi(,11524) particular classes of objects.@refill
11148texinfo.texi(,11525)
11149texinfo.texi(,11526) For example, some systems have constructs called @dfn{wrappers} that
11150texinfo.texi(,11527) are associated with classes as methods are, but that act more like
11151texinfo.texi(,11528) macros than like functions.  You could use @code{@@defop Wrapper} to
11152texinfo.texi(,11529) describe one of these.@refill
11153texinfo.texi(,11530)
11154texinfo.texi(,11531) Sometimes it is useful to distinguish methods and @dfn{operations}.
11155texinfo.texi(,11532) You can think of an operation as the specification for a method.
11156texinfo.texi(,11533) Thus, a window system might specify that all window classes have a
11157texinfo.texi(,11534) method named @code{expose}; we would say that this window system
11158texinfo.texi(,11535) defines an @code{expose} operation on windows in general.  Typically,
11159texinfo.texi(,11536) the operation has a name and also specifies the pattern of arguments;
11160texinfo.texi(,11537) all methods that implement the operation must accept the same
11161texinfo.texi(,11538) arguments, since applications that use the operation do so without
11162texinfo.texi(,11539) knowing which method will implement it.@refill
11163texinfo.texi(,11540)
11164texinfo.texi(,11541) Often it makes more sense to document operations than methods.  For
11165texinfo.texi(,11542) example, window application developers need to know about the
11166texinfo.texi(,11543) @code{expose} operation, but need not be concerned with whether a
11167texinfo.texi(,11544) given class of windows has its own method to implement this operation.
11168texinfo.texi(,11545) To describe this operation, you would write:@refill
11169texinfo.texi(,11546)
11170texinfo.texi(,11547) @example
11171texinfo.texi(,11548) @@defop Operation windows expose
11172texinfo.texi(,11549) @end example
11173texinfo.texi(,11550)
11174texinfo.texi(,11551) The @code{@@defop} command is written at the beginning of a line and
11175texinfo.texi(,11552) is followed on the same line by the overall name of the category of
11176texinfo.texi(,11553) operation, the name of the class of the operation, the name of the
11177texinfo.texi(,11554) operation, and its arguments, if any.@refill
11178texinfo.texi(,11555)
11179texinfo.texi(,11556) The template is:
11180texinfo.texi(,11557) @example
11181texinfo.texi(,11558) @group
11182texinfo.texi(,11559) @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
11183texinfo.texi(,11560) @var{body-of-definition}
11184texinfo.texi(,11561) @@end defop
11185texinfo.texi(,11562) @end group
11186texinfo.texi(,11563) @end example
11187texinfo.texi(,11564)
11188texinfo.texi(,11565) @code{@@defop} creates an entry, such as `@code{expose} on
11189texinfo.texi(,11566) @code{windows}', in the index of functions.@refill
11190texinfo.texi(,11567)
11191texinfo.texi(,11568) @findex deftypeop
11192texinfo.texi(,11569) @item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
11193texinfo.texi(,11570) The @code{@@deftypeop} command is the definition command for typed
11194texinfo.texi(,11571) operations in object-oriented programming.  It is similar to
11195texinfo.texi(,11572) @code{@@defop} with the addition of the @var{data-type} parameter to
11196texinfo.texi(,11573) specify the return type of the method.  @code{@@deftypeop} creates an
11197texinfo.texi(,11574) entry in the index of functions.
11198texinfo.texi(,11575)
11199texinfo.texi(,11576) @item @@defmethod @var{class} @var{name} @var{arguments}@dots{}
11200texinfo.texi(,11577) @findex defmethod
11201texinfo.texi(,11578) The @code{@@defmethod} command is the definition command for methods
11202texinfo.texi(,11579) in object-oriented programming.  A method is a kind of function that
11203texinfo.texi(,11580) implements an operation for a particular class of objects and its
11204texinfo.texi(,11581) subclasses.
11205texinfo.texi(,11588)
11206texinfo.texi(,11589) @code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}.
11207texinfo.texi(,11590) The command is written at the beginning of a line and is followed by
11208texinfo.texi(,11591) the name of the class of the method, the name of the method, and its
11209texinfo.texi(,11592) arguments, if any.@refill
11210texinfo.texi(,11593)
11211texinfo.texi(,11594) @noindent
11212texinfo.texi(,11595) For example:
11213texinfo.texi(,11596) @example
11214texinfo.texi(,11597) @group
11215texinfo.texi(,11598) @@defmethod @code{bar-class} bar-method argument
11216texinfo.texi(,11599) @dots{}
11217texinfo.texi(,11600) @@end defmethod
11218texinfo.texi(,11601) @end group
11219texinfo.texi(,11602) @end example
11220texinfo.texi(,11603)
11221texinfo.texi(,11604) @noindent
11222texinfo.texi(,11605) illustrates the definition for a method called @code{bar-method} of
11223texinfo.texi(,11606) the class @code{bar-class}.  The method takes an argument.@refill
11224texinfo.texi(,11607)
11225texinfo.texi(,11608) The template is:
11226texinfo.texi(,11609)
11227texinfo.texi(,11610) @example
11228texinfo.texi(,11611) @group
11229texinfo.texi(,11612) @@defmethod @var{class} @var{method-name} @var{arguments}@dots{}
11230texinfo.texi(,11613) @var{body-of-definition}
11231texinfo.texi(,11614) @@end defmethod
11232texinfo.texi(,11615) @end group
11233texinfo.texi(,11616) @end example
11234texinfo.texi(,11617)
11235texinfo.texi(,11618) @code{@@defmethod} creates an entry, such as `@code{bar-method} on
11236texinfo.texi(,11619) @code{bar-class}', in the index of functions.@refill
11237texinfo.texi(,11620)
11238texinfo.texi(,11621)
11239texinfo.texi(,11622) @item @@deftypemethod @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
11240texinfo.texi(,11623) @findex defmethod
11241texinfo.texi(,11624) The @code{@@deftypemethod} command is the definition command for methods
11242texinfo.texi(,11625) in object-oriented typed languages, such as C++ and Java.  It is similar
11243texinfo.texi(,11626) to the @code{@@defmethod} command with the addition of the
11244texinfo.texi(,11627) @var{data-type} parameter to specify the return type of the method.
11245texinfo.texi(,11628)
11246texinfo.texi(,11629) @end table
11247texinfo.texi(,11630)
11248texinfo.texi(,11631)
11249texinfo.texi(,11632) @node Data Types
11250texinfo.texi(,11633) @subsection Data Types
11251texinfo.texi(,11634)
11252texinfo.texi(,11635) Here is the command for data types:@refill
11253texinfo.texi(,11636)
11254texinfo.texi(,11637) @table @code
11255texinfo.texi(,11638) @findex deftp
11256texinfo.texi(,11639) @item @@deftp @var{category} @var{name} @var{attributes}@dots{}
11257texinfo.texi(,11640) The @code{@@deftp} command is the generic definition command for data
11258texinfo.texi(,11641) types.  The command is written at the beginning of a line and is
11259texinfo.texi(,11642) followed on the same line by the category, by the name of the type
11260texinfo.texi(,11643) (which is a word like @code{int} or @code{float}), and then by names of
11261texinfo.texi(,11644) attributes of objects of that type.  Thus, you could use this command
11262texinfo.texi(,11645) for describing @code{int} or @code{float}, in which case you could use
11263texinfo.texi(,11646) @code{data type} as the category.  (A data type is a category of
11264texinfo.texi(,11647) certain objects for purposes of deciding which operations can be
11265texinfo.texi(,11648) performed on them.)@refill
11266texinfo.texi(,11649)
11267texinfo.texi(,11650) In Lisp, for example,  @dfn{pair} names a particular data
11268texinfo.texi(,11651) type, and an object of that type has two slots called the
11269texinfo.texi(,11652) @sc{car} and the @sc{cdr}.  Here is how you would write the first line
11270texinfo.texi(,11653) of a definition of @code{pair}.@refill
11271texinfo.texi(,11654)
11272texinfo.texi(,11655) @example
11273texinfo.texi(,11656) @group
11274texinfo.texi(,11657) @@deftp @{Data type@} pair car cdr
11275texinfo.texi(,11658) @dots{}
11276texinfo.texi(,11659) @@end deftp
11277texinfo.texi(,11660) @end group
11278texinfo.texi(,11661) @end example
11279texinfo.texi(,11662)
11280texinfo.texi(,11663) @need 950
11281texinfo.texi(,11664) The template is:
11282texinfo.texi(,11665)
11283texinfo.texi(,11666) @example
11284texinfo.texi(,11667) @group
11285texinfo.texi(,11668) @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
11286texinfo.texi(,11669) @var{body-of-definition}
11287texinfo.texi(,11670) @@end deftp
11288texinfo.texi(,11671) @end group
11289texinfo.texi(,11672) @end example
11290texinfo.texi(,11673)
11291texinfo.texi(,11674) @code{@@deftp} creates an entry in the index of data types.
11292texinfo.texi(,11675) @end table
11293texinfo.texi(,11676)
11294texinfo.texi(,11677) @node Def Cmd Conventions, Sample Function Definition, Def Cmds in Detail, Definition Commands
11295texinfo.texi(,11678) @section Conventions for Writing Definitions
11296texinfo.texi(,11679) @cindex Definition conventions
11297texinfo.texi(,11680) @cindex Conventions for writing definitions
11298texinfo.texi(,11681)
11299texinfo.texi(,11682) When you write a definition using @code{@@deffn}, @code{@@defun}, or
11300texinfo.texi(,11683) one of the other definition commands, please take care to use
11301texinfo.texi(,11684) arguments that indicate the meaning, as with the @var{count} argument
11302texinfo.texi(,11685) to the @code{forward-word} function.  Also, if the name of an argument
11303texinfo.texi(,11686) contains the name of a type, such as @var{integer}, take care that the
11304texinfo.texi(,11687) argument actually is of that type.@refill
11305texinfo.texi(,11688)
11306texinfo.texi(,11689) @node Sample Function Definition,  , Def Cmd Conventions, Definition Commands
11307texinfo.texi(,11690) @section A Sample Function Definition
11308texinfo.texi(,11691) @cindex Function definitions
11309texinfo.texi(,11692) @cindex Command definitions
11310texinfo.texi(,11693) @cindex Macro definitions
11311texinfo.texi(,11694) @cindex Sample function definition
11312texinfo.texi(,11695)
11313texinfo.texi(,11696) A function definition uses the @code{@@defun} and @code{@@end defun}
11314texinfo.texi(,11697) commands.  The name of the function follows immediately after the
11315texinfo.texi(,11698) @code{@@defun} command and it is followed, on the same line, by the
11316texinfo.texi(,11699) parameter list.@refill
11317texinfo.texi(,11700)
11318texinfo.texi(,11701) Here is a definition from @ref{Calling Functions,,, elisp, The GNU Emacs
11319texinfo.texi(,11702) Lisp Reference Manual}.
11320texinfo.texi(,11703)
11321texinfo.texi(,11704) @quotation
11322texinfo.texi(,11705) @defun apply function &rest arguments
11323texinfo.texi(,11706) @code{apply} calls @var{function} with @var{arguments}, just
11324texinfo.texi(,11707) like @code{funcall} but with one difference: the last of
11325texinfo.texi(,11708) @var{arguments} is a list of arguments to give to
11326texinfo.texi(,11709) @var{function}, rather than a single argument.  We also say
11327texinfo.texi(,11710) that this list is @dfn{appended} to the other arguments.
11328texinfo.texi(,11711)
11329texinfo.texi(,11712) @code{apply} returns the result of calling @var{function}.
11330texinfo.texi(,11713) As with @code{funcall}, @var{function} must either be a Lisp
11331texinfo.texi(,11714) function or a primitive function; special forms and macros
11332texinfo.texi(,11715) do not make sense in @code{apply}.
11333texinfo.texi(,11716)
11334texinfo.texi(,11717) @example
11335texinfo.texi(,11718) (setq f 'list)
11336texinfo.texi(,11719)      @result{} list
11337texinfo.texi(,11720) (apply f 'x 'y 'z)
11338texinfo.texi(,11721) @error{} Wrong type argument: listp, z
11339texinfo.texi(,11722) (apply '+ 1 2 '(3 4))
11340texinfo.texi(,11723)      @result{} 10
11341texinfo.texi(,11724) (apply '+ '(1 2 3 4))
11342texinfo.texi(,11725)      @result{} 10
11343texinfo.texi(,11726)
11344texinfo.texi(,11727) (apply 'append '((a b c) nil (x y z) nil))
11345texinfo.texi(,11728)      @result{} (a b c x y z)
11346texinfo.texi(,11729) @end example
11347texinfo.texi(,11730)
11348texinfo.texi(,11731) An interesting example of using @code{apply} is found in the description
11349texinfo.texi(,11732) of @code{mapcar}.@refill
11350texinfo.texi(,11733) @end defun
11351texinfo.texi(,11734) @end quotation
11352texinfo.texi(,11735)
11353texinfo.texi(,11736) @need 1200
11354texinfo.texi(,11737) In the Texinfo source file, this example looks like this:
11355texinfo.texi(,11738)
11356texinfo.texi(,11739) @example
11357texinfo.texi(,11740) @group
11358texinfo.texi(,11741) @@defun apply function &rest arguments
11359texinfo.texi(,11742) @@code@{apply@} calls @@var@{function@} with
11360texinfo.texi(,11743) @@var@{arguments@}, just like @@code@{funcall@} but with one
11361texinfo.texi(,11744) difference: the last of @@var@{arguments@} is a list of
11362texinfo.texi(,11745) arguments to give to @@var@{function@}, rather than a single
11363texinfo.texi(,11746) argument.  We also say that this list is @@dfn@{appended@}
11364texinfo.texi(,11747) to the other arguments.
11365texinfo.texi(,11748) @end group
11366texinfo.texi(,11749)
11367texinfo.texi(,11750) @group
11368texinfo.texi(,11751) @@code@{apply@} returns the result of calling
11369texinfo.texi(,11752) @@var@{function@}.  As with @@code@{funcall@},
11370texinfo.texi(,11753) @@var@{function@} must either be a Lisp function or a
11371texinfo.texi(,11754) primitive function; special forms and macros do not make
11372texinfo.texi(,11755) sense in @@code@{apply@}.
11373texinfo.texi(,11756) @end group
11374texinfo.texi(,11757)
11375texinfo.texi(,11758) @group
11376texinfo.texi(,11759) @@example
11377texinfo.texi(,11760) (setq f 'list)
11378texinfo.texi(,11761)      @@result@{@} list
11379texinfo.texi(,11762) (apply f 'x 'y 'z)
11380texinfo.texi(,11763) @@error@{@} Wrong type argument: listp, z
11381texinfo.texi(,11764) (apply '+ 1 2 '(3 4))
11382texinfo.texi(,11765)      @@result@{@} 10
11383texinfo.texi(,11766) (apply '+ '(1 2 3 4))
11384texinfo.texi(,11767)      @@result@{@} 10
11385texinfo.texi(,11768)
11386texinfo.texi(,11769) (apply 'append '((a b c) nil (x y z) nil))
11387texinfo.texi(,11770)      @@result@{@} (a b c x y z)
11388texinfo.texi(,11771) @@end example
11389texinfo.texi(,11772) @end group
11390texinfo.texi(,11773)
11391texinfo.texi(,11774) @group
11392texinfo.texi(,11775) An interesting example of using @@code@{apply@} is found
11393texinfo.texi(,11776) in the description of @@code@{mapcar@}.
11394texinfo.texi(,11777) @@end defun
11395texinfo.texi(,11778) @end group
11396texinfo.texi(,11779) @end example
11397texinfo.texi(,11780)
11398texinfo.texi(,11781) @noindent
11399texinfo.texi(,11782) In this manual, this function is listed in the Command and Variable
11400texinfo.texi(,11783) Index under @code{apply}.@refill
11401texinfo.texi(,11784)
11402texinfo.texi(,11785) Ordinary variables and user options are described using a format like
11403texinfo.texi(,11786) that for functions except that variables do not take arguments.
11404texinfo.texi(,11787)
11405texinfo.texi(,11788)
11406texinfo.texi(,11789) @node Conditionals
11407texinfo.texi(,11790) @chapter Conditionally Visible Text
11408texinfo.texi(,11791) @cindex Conditionally visible text
11409texinfo.texi(,11792) @cindex Text, conditionally visible
11410texinfo.texi(,11793) @cindex Visibility of conditional text
11411texinfo.texi(,11794) @cindex If text conditionally visible
11412texinfo.texi(,11795)
11413texinfo.texi(,11796) Sometimes it is good to use different text for different output formats.
11414texinfo.texi(,11797) For example, you can use the @dfn{conditional commands} to specify
11415texinfo.texi(,11798) different text for the printed manual and the Info output.
11416texinfo.texi(,11799)
11417texinfo.texi(,11800) Conditional commands may not be nested.
11418texinfo.texi(,11801)
11419texinfo.texi(,11802) The conditional commands comprise the following categories.
11420texinfo.texi(,11803)
11421texinfo.texi(,11804) @itemize @bullet
11422texinfo.texi(,11805) @item Commands for HTML, Info, or @TeX{}.
11423texinfo.texi(,11806) @item Commands for not HTML, Info, or @TeX{}.
11424texinfo.texi(,11807) @item Raw @TeX{} or HTML commands.
11425texinfo.texi(,11808) @item
11426texinfo.texi(,11809) Substituting text for all formats, and testing if a flag is set or clear.
11427texinfo.texi(,11810) @end itemize
11428texinfo.texi(,11811)
11429texinfo.texi(,11812) @menu
11430texinfo.texi(,11813) * Conditional Commands::        Specifying text for HTML, Info, or @TeX{}.
11431texinfo.texi(,11814) * Conditional Not Commands::    Specifying text for not HTML, Info, or @TeX{}.
11432texinfo.texi(,11815) * Raw Formatter Commands::      Using raw @TeX{} or HTML commands.
11433texinfo.texi(,11816) * set clear value::             Designating which text to format (for
11434texinfo.texi(,11817)                                   all output formats); and how to set a
11435texinfo.texi(,11818)                                   flag to a string that you can insert.
11436texinfo.texi(,11819) @end menu
11437texinfo.texi(,11820)
11438texinfo.texi(,11821)
11439texinfo.texi(,11822) @node Conditional Commands
11440texinfo.texi(,11823) @section Conditional Commands
11441texinfo.texi(,11824)
11442texinfo.texi(,11825) Texinfo has a pair of commands for each output format, to allow
11443texinfo.texi(,11826) conditional inclusion of text for a particular output format.
11444texinfo.texi(,11827)
11445texinfo.texi(,11828) @findex ifinfo
11446texinfo.texi(,11829) @code{@@ifinfo} begins segments of text that should be ignored by @TeX{}
11447texinfo.texi(,11830) when it typesets the printed manual.  The segment of text appears only
11448texinfo.texi(,11831) in the Info file and (for historical compatibility) the plain text
11449texinfo.texi(,11832) output.  The @code{@@ifinfo} command should appear on a line by itself;
11450texinfo.texi(,11833) end the Info-only text with a line containing @code{@@end ifinfo} by
11451texinfo.texi(,11834) itself.
11452texinfo.texi(,11835)
11453texinfo.texi(,11836) @findex iftex
11454texinfo.texi(,11837) @findex ifhtml
11455texinfo.texi(,11838) @findex ifplaintext
11456texinfo.texi(,11839) The @code{@@iftex} and @code{@@end iftex} commands are analogous to the
11457texinfo.texi(,11840) @code{@@ifinfo} and @code{@@end ifinfo} commands; they specify text that
11458texinfo.texi(,11841) will appear in the printed manual but not in the Info file.  Likewise
11459texinfo.texi(,11842) for @code{@@ifhtml} and @code{@@end ifhtml}, which specify text to
11460texinfo.texi(,11843) appear only in HTML output.  And for @code{@@ifplaintext} and
11461texinfo.texi(,11844) @code{@@end ifplaintext}, which specify text to appear only in plain
11462texinfo.texi(,11845) text output.
11463texinfo.texi(,11846)
11464texinfo.texi(,11847) For example,
11465texinfo.texi(,11848)
11466texinfo.texi(,11849) @example
11467texinfo.texi(,11850) @@iftex
11468texinfo.texi(,11851) This text will appear only in the printed manual.
11469texinfo.texi(,11852) @@end iftex
11470texinfo.texi(,11853) @@ifinfo
11471texinfo.texi(,11854) However, this text will appear only in Info (or plain text).
11472texinfo.texi(,11855) @@end ifinfo
11473texinfo.texi(,11856) @@ifhtml
11474texinfo.texi(,11857) And this text will only appear in HTML.
11475texinfo.texi(,11858) @@end ifhtml
11476texinfo.texi(,11859) @@ifplaintext
11477texinfo.texi(,11860) Whereas this text will only appear in plain text.
11478texinfo.texi(,11861) @@end ifplaintext
11479texinfo.texi(,11862) @end example
11480texinfo.texi(,11863)
11481texinfo.texi(,11864) @noindent
11482texinfo.texi(,11865) The preceding example produces the following line:
11483texinfo.texi(,11870) However, this text will appear only in Info (or plain text).
11484texinfo.texi(,11878)
11485texinfo.texi(,11879) @noindent
11486texinfo.texi(,11880) Notice that you only see one of the input lines, depending on which
11487texinfo.texi(,11881) version of the manual you are reading.
11488texinfo.texi(,11882)
11489texinfo.texi(,11883)
11490texinfo.texi(,11884) @node Conditional Not Commands
11491texinfo.texi(,11885) @section Conditional Not Commands
11492texinfo.texi(,11886) @findex ifnothtml
11493texinfo.texi(,11887) @findex ifnotinfo
11494texinfo.texi(,11888) @findex ifnotplaintext
11495texinfo.texi(,11889) @findex ifnottex
11496texinfo.texi(,11890)
11497texinfo.texi(,11891) You can specify text to be included in any output format @emph{other}
11498texinfo.texi(,11892) than some given one with the @code{@@ifnot@dots{}} commands:
11499texinfo.texi(,11893) @example
11500texinfo.texi(,11894) @@ifnothtml @dots{} @@end ifnothtml
11501texinfo.texi(,11895) @@ifnotinfo @dots{} @@end ifnotinfo
11502texinfo.texi(,11896) @@ifnotplaintext @dots{} @@end ifnotplaintext
11503texinfo.texi(,11897) @@ifnottex @dots{} @@end ifnottex
11504texinfo.texi(,11898) @end example
11505texinfo.texi(,11899) @noindent
11506texinfo.texi(,11900) (The @code{@@ifnot@dots{}} command and the @code{@@end} command must
11507texinfo.texi(,11901) appear on lines by themselves in your actual source file.)
11508texinfo.texi(,11902)
11509texinfo.texi(,11903) If the output file is @emph{not} being made for the given format, the
11510texinfo.texi(,11904) region is included.  Otherwise, it is ignored.
11511texinfo.texi(,11905)
11512texinfo.texi(,11906) With one exception (for historical compatibility): @code{@@ifnotinfo}
11513texinfo.texi(,11907) text is omitted for both Info and plain text output, not just Info.  To
11514texinfo.texi(,11908) specify text which appears only in Info and not in plain text, use
11515texinfo.texi(,11909) @code{@@ifnotplaintext}, like this:
11516texinfo.texi(,11910) @example
11517texinfo.texi(,11913) This will be in Info, but not plain text.
11518texinfo.texi(,11916) @end example
11519texinfo.texi(,11917)
11520texinfo.texi(,11918) The regions delimited by these commands are ordinary Texinfo source as
11521texinfo.texi(,11919) with @code{@@iftex}, not raw formatter source as with @code{@@tex}
11522texinfo.texi(,11920) (@pxref{Raw Formatter Commands}).
11523texinfo.texi(,11921)
11524texinfo.texi(,11922)
11525texinfo.texi(,11923) @node Raw Formatter Commands
11526texinfo.texi(,11924) @section Raw Formatter Commands
11527texinfo.texi(,11925) @cindex @TeX{} commands, using ordinary
11528texinfo.texi(,11926) @cindex HTML commands, using ordinary
11529texinfo.texi(,11927) @cindex Raw formatter commands
11530texinfo.texi(,11928) @cindex Ordinary @TeX{} commands, using
11531texinfo.texi(,11929) @cindex Ordinary HTML commands, using
11532texinfo.texi(,11930) @cindex Commands using raw @TeX{}
11533texinfo.texi(,11931) @cindex Commands using raw HTML
11534texinfo.texi(,11932) @cindex plain @TeX{}
11535texinfo.texi(,11933)
11536texinfo.texi(,11934) Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, you
11537texinfo.texi(,11935) can embed some raw @TeX{} commands.  Info will ignore these commands
11538texinfo.texi(,11936) since they are only in that part of the file which is seen by @TeX{}.
11539texinfo.texi(,11937) You can write the @TeX{} commands as you would write them in a normal
11540texinfo.texi(,11938) @TeX{} file, except that you must replace the @samp{\} used by @TeX{}
11541texinfo.texi(,11939) with an @samp{@@}.  For example, in the @code{@@titlepage} section of a
11542texinfo.texi(,11940) Texinfo file, you can use the @TeX{} command @code{@@vskip} to format
11543texinfo.texi(,11941) the copyright page.  (The @code{@@titlepage} command causes Info to
11544texinfo.texi(,11942) ignore the region automatically, as it does with the @code{@@iftex}
11545texinfo.texi(,11943) command.)
11546texinfo.texi(,11944)
11547texinfo.texi(,11945) However, many features of plain @TeX{} will not work, as they are
11548texinfo.texi(,11946) overridden by Texinfo features.
11549texinfo.texi(,11947)
11550texinfo.texi(,11948) @findex tex
11551texinfo.texi(,11949) You can enter plain @TeX{} completely, and use @samp{\} in the @TeX{}
11552texinfo.texi(,11950) commands, by delineating a region with the @code{@@tex} and @code{@@end
11553texinfo.texi(,11951) tex} commands.  (The @code{@@tex} command also causes Info to ignore the
11554texinfo.texi(,11952) region, like the @code{@@iftex} command.)  The sole exception is that the
11555texinfo.texi(,11953) @code{@@} character still introduces a command, so that @code{@@end tex}
11556texinfo.texi(,11954) can be recognized properly.
11557texinfo.texi(,11955)
11558texinfo.texi(,11956) @cindex Mathematical expressions
11559texinfo.texi(,11957) For example, here is a mathematical expression written in
11560texinfo.texi(,11958) plain @TeX{}:
11561texinfo.texi(,11959)
11562texinfo.texi(,11960) @example
11563texinfo.texi(,11961) @@tex
11564texinfo.texi(,11962) $$ \chi^2 = \sum_@{i=1@}^N
11565texinfo.texi(,11963)           \left (y_i - (a + b x_i)
11566texinfo.texi(,11964)           \over \sigma_i\right)^2 $$
11567texinfo.texi(,11965) @@end tex
11568texinfo.texi(,11966) @end example
11569texinfo.texi(,11967)
11570texinfo.texi(,11968) @noindent
11571texinfo.texi(,11969) The output of this example will appear only in a printed manual.  If
11572texinfo.texi(,11970) you are reading this in Info, you will not see the equation that appears
11573texinfo.texi(,11971) in the printed manual.
11574texinfo.texi(,11976)
11575texinfo.texi(,11977) @tex
11576texinfo.texi(,11978) $$ \chi^2 = \sum_{i=1}^N
11577texinfo.texi(,11979)           \left(y_i - (a + b x_i)
11578texinfo.texi(,11980)           \over \sigma_i\right)^2 $$
11579texinfo.texi(,11981) @end tex
11580texinfo.texi(,11982)
11581texinfo.texi(,11983) @findex ifhtml
11582texinfo.texi(,11984) @findex html
11583texinfo.texi(,11985) Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to delimit
11584texinfo.texi(,11986) a region to be included in HTML output only, and @code{@@html @dots{}
11585texinfo.texi(,11987) @@end html} for a region of raw HTML (again, except that @code{@@} is
11586texinfo.texi(,11988) still the escape character, so the @code{@@end} command can be
11587texinfo.texi(,11989) recognized.)
11588texinfo.texi(,11990)
11589texinfo.texi(,11991)
11590texinfo.texi(,11992) @node set clear value
11591texinfo.texi(,11993) @section @code{@@set}, @code{@@clear}, and @code{@@value}
11592texinfo.texi(,11994)
11593texinfo.texi(,11995) You can direct the Texinfo formatting commands to format or ignore parts
11594texinfo.texi(,11996) of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset},
11595texinfo.texi(,11997) and @code{@@ifclear} commands.@refill
11596texinfo.texi(,11998)
11597texinfo.texi(,11999) Brief descriptions:
11598texinfo.texi(,12000)
11599texinfo.texi(,12001) @table @code
11600texinfo.texi(,12002) @item @@set @var{flag} [@var{value}]
11601texinfo.texi(,12003) Set the variable @var{flag}, to the optional @var{value} if specifed.
11602texinfo.texi(,12004)
11603texinfo.texi(,12005) @item @@clear @var{flag}
11604texinfo.texi(,12006) Undefine the variable @var{flag}, whether or not it was previously defined.
11605texinfo.texi(,12007)
11606texinfo.texi(,12008) @item @@ifset @var{flag}
11607texinfo.texi(,12009) If @var{flag} is set, text through the next @code{@@end ifset} command
11608texinfo.texi(,12010) is formatted.  If @var{flag} is clear, text through the following
11609texinfo.texi(,12011) @code{@@end ifset} command is ignored.
11610texinfo.texi(,12012)
11611texinfo.texi(,12013) @item @@ifclear @var{flag}
11612texinfo.texi(,12014) If @var{flag} is set, text through the next @code{@@end ifclear} command
11613texinfo.texi(,12015) is ignored.  If @var{flag} is clear, text through the following
11614texinfo.texi(,12016) @code{@@end ifclear} command is formatted.
11615texinfo.texi(,12017) @end table
11616texinfo.texi(,12018)
11617texinfo.texi(,12019) @menu
11618texinfo.texi(,12020) * set value::                   Expand a flag variable to a string.
11619texinfo.texi(,12021) * ifset ifclear::               Format a region if a flag is set.
11620texinfo.texi(,12022) * value Example::               An easy way to update edition information.
11621texinfo.texi(,12023) @end menu
11622texinfo.texi(,12024)
11623texinfo.texi(,12025)
11624texinfo.texi(,12026) @node set value
11625texinfo.texi(,12027) @subsection @code{@@set} and @code{@@value}
11626texinfo.texi(,12028) @findex value
11627texinfo.texi(,12029)
11628texinfo.texi(,12030) You use the @code{@@set} command to specify a value for a flag, which is
11629texinfo.texi(,12031) later expanded by the @code{@@value} command.
11630texinfo.texi(,12032)
11631texinfo.texi(,12033) A @dfn{flag} is an identifier.  In general, it is best to use only
11632texinfo.texi(,12034) letters and numerals in a flag name, not @samp{-} or @samp{_}---they
11633texinfo.texi(,12035) will work in some contexts, but not all, due to limitations in @TeX{}.
11634texinfo.texi(,12036)
11635texinfo.texi(,12037) The value is the remainder of the input line, and can contain anything.
11636texinfo.texi(,12038)
11637texinfo.texi(,12039) Write the @code{@@set} command like this:
11638texinfo.texi(,12040)
11639texinfo.texi(,12041) @example
11640texinfo.texi(,12042) @@set foo This is a string.
11641texinfo.texi(,12043) @end example
11642texinfo.texi(,12044)
11643texinfo.texi(,12045) @noindent
11644texinfo.texi(,12046) This sets the value of the flag @code{foo} to ``This is a string.''.
11645texinfo.texi(,12047)
11646texinfo.texi(,12048) The Texinfo formatters then replace an @code{@@value@{@var{flag}@}}
11647texinfo.texi(,12049) command with the string to which @var{flag} is set.  Thus, when
11648texinfo.texi(,12050) @code{foo} is set as shown above, the Texinfo formatters convert this:
11649texinfo.texi(,12051)
11650texinfo.texi(,12052) @example
11651texinfo.texi(,12053) @group
11652texinfo.texi(,12054) @@value@{foo@}
11653texinfo.texi(,12055) @exdent @r{to this:}
11654texinfo.texi(,12056) This is a string.
11655texinfo.texi(,12057) @end group
11656texinfo.texi(,12058) @end example
11657texinfo.texi(,12059)
11658texinfo.texi(,12060) You can write an @code{@@value} command within a paragraph; but you
11659texinfo.texi(,12061) must write an @code{@@set} command on a line of its own.
11660texinfo.texi(,12062)
11661texinfo.texi(,12063) If you write the @code{@@set} command like this:
11662texinfo.texi(,12064)
11663texinfo.texi(,12065) @example
11664texinfo.texi(,12066) @@set foo
11665texinfo.texi(,12067) @end example
11666texinfo.texi(,12068)
11667texinfo.texi(,12069) @noindent
11668texinfo.texi(,12070) without specifying a string, the value of @code{foo} is the empty string.
11669texinfo.texi(,12071)
11670texinfo.texi(,12072) If you clear a previously set flag with @code{@@clear @var{flag}}, a
11671texinfo.texi(,12073) subsequent @code{@@value@{flag@}} command will report an error.
11672texinfo.texi(,12074)
11673texinfo.texi(,12075) For example, if you set @code{foo} as follows:@refill
11674texinfo.texi(,12076)
11675texinfo.texi(,12077) @example
11676texinfo.texi(,12078) @@set how-much very, very, very
11677texinfo.texi(,12079) @end example
11678texinfo.texi(,12080)
11679texinfo.texi(,12081) @noindent
11680texinfo.texi(,12082) then the formatters transform
11681texinfo.texi(,12083)
11682texinfo.texi(,12084) @example
11683texinfo.texi(,12085) @group
11684texinfo.texi(,12086) It is a @@value@{how-much@} wet day.
11685texinfo.texi(,12087) @exdent @r{into}
11686texinfo.texi(,12088) It is a very, very, very wet day.
11687texinfo.texi(,12089) @end group
11688texinfo.texi(,12090) @end example
11689texinfo.texi(,12091)
11690texinfo.texi(,12092) If you write
11691texinfo.texi(,12093)
11692texinfo.texi(,12094) @example
11693texinfo.texi(,12095) @@clear how-much
11694texinfo.texi(,12096) @end example
11695texinfo.texi(,12097)
11696texinfo.texi(,12098) @noindent
11697texinfo.texi(,12099) then the formatters transform
11698texinfo.texi(,12100)
11699texinfo.texi(,12101) @example
11700texinfo.texi(,12102) @group
11701texinfo.texi(,12103) It is a @@value@{how-much@} wet day.
11702texinfo.texi(,12104) @exdent @r{into}
11703texinfo.texi(,12105) It is a @{No value for "how-much"@} wet day.
11704texinfo.texi(,12106) @end group
11705texinfo.texi(,12107) @end example
11706texinfo.texi(,12108)
11707texinfo.texi(,12109)
11708texinfo.texi(,12110) @node ifset ifclear
11709texinfo.texi(,12111) @subsection @code{@@ifset} and @code{@@ifclear}
11710texinfo.texi(,12112)
11711texinfo.texi(,12113) @findex ifset
11712texinfo.texi(,12114) When a @var{flag} is set, the Texinfo formatting commands format text
11713texinfo.texi(,12115) between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end
11714texinfo.texi(,12116) ifset} commands.  When the @var{flag} is cleared, the Texinfo formatting
11715texinfo.texi(,12117) commands do @emph{not} format the text.  @code{@@ifclear} operates
11716texinfo.texi(,12118) analogously.
11717texinfo.texi(,12119)
11718texinfo.texi(,12120) Write the conditionally formatted text between @code{@@ifset @var{flag}}
11719texinfo.texi(,12121) and @code{@@end ifset} commands, like this:
11720texinfo.texi(,12122)
11721texinfo.texi(,12123) @example
11722texinfo.texi(,12124) @group
11723texinfo.texi(,12125) @@ifset @var{flag}
11724texinfo.texi(,12126) @var{conditional-text}
11725texinfo.texi(,12127) @@end ifset
11726texinfo.texi(,12128) @end group
11727texinfo.texi(,12129) @end example
11728texinfo.texi(,12130)
11729texinfo.texi(,12131) For example, you can create one document that has two variants, such as
11730texinfo.texi(,12132) a manual for a `large' and `small' model:
11731texinfo.texi(,12133)
11732texinfo.texi(,12134) @cindex shrubbery
11733texinfo.texi(,12135) @example
11734texinfo.texi(,12136) You can use this machine to dig up shrubs
11735texinfo.texi(,12137) without hurting them.
11736texinfo.texi(,12138)
11737texinfo.texi(,12139) @@set large
11738texinfo.texi(,12140)
11739texinfo.texi(,12141) @@ifset large
11740texinfo.texi(,12142) It can also dig up fully grown trees.
11741texinfo.texi(,12143) @@end ifset
11742texinfo.texi(,12144)
11743texinfo.texi(,12145) Remember to replant promptly @dots{}
11744texinfo.texi(,12146) @end example
11745texinfo.texi(,12147)
11746texinfo.texi(,12148) @noindent
11747texinfo.texi(,12149) In the example, the formatting commands will format the text between
11748texinfo.texi(,12150) @code{@@ifset large} and @code{@@end ifset} because the @code{large}
11749texinfo.texi(,12151) flag is set.
11750texinfo.texi(,12152)
11751texinfo.texi(,12153) When @var{flag} is cleared, the Texinfo formatting commands do
11752texinfo.texi(,12154) @emph{not} format the text between @code{@@ifset @var{flag}} and
11753texinfo.texi(,12155) @code{@@end ifset}; that text is ignored and does not appear in either
11754texinfo.texi(,12156) printed or Info output.
11755texinfo.texi(,12157)
11756texinfo.texi(,12158) For example, if you clear the flag of the preceding example by writing
11757texinfo.texi(,12159) an @code{@@clear large} command after the @code{@@set large} command
11758texinfo.texi(,12160) (but before the conditional text), then the Texinfo formatting commands
11759texinfo.texi(,12161) ignore the text between the @code{@@ifset large} and @code{@@end ifset}
11760texinfo.texi(,12162) commands.  In the formatted output, that text does not appear; in both
11761texinfo.texi(,12163) printed and Info output, you see only the lines that say, ``You can use
11762texinfo.texi(,12164) this machine to dig up shrubs without hurting them.  Remember to replant
11763texinfo.texi(,12165) promptly @dots{}''.
11764texinfo.texi(,12166)
11765texinfo.texi(,12167) @findex ifclear
11766texinfo.texi(,12168) If a flag is cleared with an @code{@@clear @var{flag}} command, then
11767texinfo.texi(,12169) the formatting commands format text between subsequent pairs of
11768texinfo.texi(,12170) @code{@@ifclear} and @code{@@end ifclear} commands.  But if the flag
11769texinfo.texi(,12171) is set with @code{@@set @var{flag}}, then the formatting commands do
11770texinfo.texi(,12172) @emph{not} format text between an @code{@@ifclear} and an @code{@@end
11771texinfo.texi(,12173) ifclear} command; rather, they ignore that text.  An @code{@@ifclear}
11772texinfo.texi(,12174) command looks like this:
11773texinfo.texi(,12175)
11774texinfo.texi(,12176) @example
11775texinfo.texi(,12177) @@ifclear @var{flag}
11776texinfo.texi(,12178) @end example
11777texinfo.texi(,12179)
11778texinfo.texi(,12180)
11779texinfo.texi(,12181) @node value Example
11780texinfo.texi(,12182) @subsection @code{@@value} Example
11781texinfo.texi(,12183)
11782texinfo.texi(,12184) You can use the @code{@@value} command to minimize the number of places
11783texinfo.texi(,12185) you need to change when you record an update to a manual.  @xref{GNU
11784texinfo.texi(,12186) Sample Texts}, for an example of this same principle can work with
11785texinfo.texi(,12187) Automake distributions, and full texts.
11786texinfo.texi(,12188)
11787texinfo.texi(,12189) Here is an example adapted from @ref{Top,, Overview, make, The GNU Make
11788texinfo.texi(,12190) Manual}):
11789texinfo.texi(,12191)
11790texinfo.texi(,12192) @enumerate
11791texinfo.texi(,12193) @item
11792texinfo.texi(,12194) Set the flags:
11793texinfo.texi(,12195)
11794texinfo.texi(,12196) @example
11795texinfo.texi(,12197) @group
11796texinfo.texi(,12198) @@set EDITION 0.35 Beta
11797texinfo.texi(,12199) @@set VERSION 3.63 Beta
11798texinfo.texi(,12200) @@set UPDATED 14 August 1992
11799texinfo.texi(,12201) @@set UPDATE-MONTH August 1992
11800texinfo.texi(,12202) @end group
11801texinfo.texi(,12203) @end example
11802texinfo.texi(,12204)
11803texinfo.texi(,12205) @item
11804texinfo.texi(,12206) Write text for the @code{@@copying} section (@pxref{copying}):
11805texinfo.texi(,12207)
11806texinfo.texi(,12208) @example
11807texinfo.texi(,12209) @group
11808texinfo.texi(,12210) @@copying
11809texinfo.texi(,12211) This is Edition @@value@{EDITION@},
11810texinfo.texi(,12212) last updated @@value@{UPDATED@},
11811texinfo.texi(,12213) of @@cite@{The GNU Make Manual@},
11812texinfo.texi(,12214) for @@code@{make@}, version @@value@{VERSION@}.
11813texinfo.texi(,12215)
11814texinfo.texi(,12216) Copyright @dots{}
11815texinfo.texi(,12217)
11816texinfo.texi(,12218) Permission is granted @dots{}
11817texinfo.texi(,12219) @@end copying
11818texinfo.texi(,12220) @end group
11819texinfo.texi(,12221) @end example
11820texinfo.texi(,12222)
11821texinfo.texi(,12223) @item
11822texinfo.texi(,12224) Write text for the title page, for people reading the printed manual:
11823texinfo.texi(,12225)
11824texinfo.texi(,12226) @example
11825texinfo.texi(,12227) @group
11826texinfo.texi(,12228) @@titlepage
11827texinfo.texi(,12229) @@title GNU Make
11828texinfo.texi(,12230) @@subtitle A Program for Directing Recompilation
11829texinfo.texi(,12231) @@subtitle Edition @@value@{EDITION@}, @dots{}
11830texinfo.texi(,12232) @@subtitle @@value@{UPDATE-MONTH@}
11831texinfo.texi(,12233) @@page
11832texinfo.texi(,12234) @@insertcopying
11833texinfo.texi(,12235) @dots{}
11834texinfo.texi(,12236) @@end titlepage
11835texinfo.texi(,12237) @end group
11836texinfo.texi(,12238) @end example
11837texinfo.texi(,12239)
11838texinfo.texi(,12240) @noindent
11839texinfo.texi(,12241) (On a printed cover, a date listing the month and the year looks less
11840texinfo.texi(,12242) fussy than a date listing the day as well as the month and year.)
11841texinfo.texi(,12243)
11842texinfo.texi(,12244) @item
11843texinfo.texi(,12245) Write text for the Top node, for people reading the Info file:
11844texinfo.texi(,12246)
11845texinfo.texi(,12247) @example
11846texinfo.texi(,12248) @group
11847texinfo.texi(,12249) @@ifnottex
11848texinfo.texi(,12250) @@node Top
11849texinfo.texi(,12251) @@top Make
11850texinfo.texi(,12252)
11851texinfo.texi(,12253) @@insertcopying
11852texinfo.texi(,12254) @dots{}
11853texinfo.texi(,12255) @@end ifnottex
11854texinfo.texi(,12256) @end group
11855texinfo.texi(,12257) @end example
11856texinfo.texi(,12258)
11857texinfo.texi(,12259) After you format the manual, the @code{@@value} constructs have been
11858texinfo.texi(,12260) expanded, so the output contains text like this:
11859texinfo.texi(,12261)
11860texinfo.texi(,12262) @example
11861texinfo.texi(,12263) @group
11862texinfo.texi(,12264) This is Edition 0.35 Beta, last updated 14 August 1992,
11863texinfo.texi(,12265) of `The GNU Make Manual', for `make', Version 3.63 Beta.
11864texinfo.texi(,12266) @end group
11865texinfo.texi(,12267) @end example
11866texinfo.texi(,12268) @end enumerate
11867texinfo.texi(,12269)
11868texinfo.texi(,12270) When you update the manual, you change only the values of the flags; you
11869texinfo.texi(,12271) do not need to edit the three sections.
11870texinfo.texi(,12272)
11871texinfo.texi(,12273)
11872texinfo.texi(,12274) @node Internationalization
11873texinfo.texi(,12275) @chapter Internationalization
11874texinfo.texi(,12276)
11875texinfo.texi(,12277) @cindex Internationalization
11876texinfo.texi(,12278) Texinfo has some support for writing in languages other than English,
11877texinfo.texi(,12279) although this area still needs considerable work.
11878texinfo.texi(,12280)
11879texinfo.texi(,12281) For a list of the various accented and special characters Texinfo
11880texinfo.texi(,12282) supports, see @ref{Inserting Accents}.
11881texinfo.texi(,12283)
11882texinfo.texi(,12284) @menu
11883texinfo.texi(,12285) * documentlanguage::            Declaring the current language.
11884texinfo.texi(,12286) * documentencoding::            Declaring the input encoding.
11885texinfo.texi(,12287) @end menu
11886texinfo.texi(,12288)
11887texinfo.texi(,12289)
11888texinfo.texi(,12290) @node documentlanguage
11889texinfo.texi(,12291) @section @code{@@documentlanguage @var{cc}}: Set the Document Language
11890texinfo.texi(,12292)
11891texinfo.texi(,12293) @findex documentlanguage
11892texinfo.texi(,12294) @cindex Language, declaring
11893texinfo.texi(,12295) @cindex Document language, declaring
11894texinfo.texi(,12296)
11895texinfo.texi(,12297) The @code{@@documentlanguage} command declares the current document
11896texinfo.texi(,12298) language.  Write it on a line by itself, with a two-letter ISO-639
11897texinfo.texi(,12299) language code following (list is included below).  If you have a
11898texinfo.texi(,12300) multilingual document, the intent is to be able to use this command
11899texinfo.texi(,12301) multiple times, to declare each language change.  If the command is not
11900texinfo.texi(,12302) used at all, the default is @code{en} for English.
11901texinfo.texi(,12303)
11902texinfo.texi(,12304) @cindex @file{txi-@var{cc}.tex}
11903texinfo.texi(,12305) At present, this command is ignored in Info and HTML output.  For
11904texinfo.texi(,12306) @TeX{}, it causes the file @file{txi-@var{cc}.tex} to be read (if it
11905texinfo.texi(,12307) exists).  Such a file appropriately redefines the various English words
11906texinfo.texi(,12308) used in @TeX{} output, such as `Chapter', `See', and so on.
11907texinfo.texi(,12309)
11908texinfo.texi(,12310) @cindex Hyphenation patterns, language-dependent
11909texinfo.texi(,12311) It would be good if this command also changed @TeX{}'s ideas of the
11910texinfo.texi(,12312) current hyphenation patterns (via the @TeX{} primitive
11911texinfo.texi(,12313) @code{\language}), but this is unfortunately not currently implemented.
11912texinfo.texi(,12314)
11913texinfo.texi(,12315) @cindex ISO 639 codes
11914texinfo.texi(,12316) @cindex Language codes
11915texinfo.texi(,12317) Hereare the valid language codes, from ISO-639.
11916texinfo.texi(,12318)
11917texinfo.texi(,12319) @multitable @columnfractions .07 .26 .07 .26 .07 .26
11918texinfo.texi(,12320) @item
11919texinfo.texi(,12321) @code{aa} @tab Afar @tab
11920texinfo.texi(,12322) @code{ab} @tab Abkhazian @tab
11921texinfo.texi(,12323) @code{af} @tab Afrikaans
11922texinfo.texi(,12324) @item
11923texinfo.texi(,12325) @code{am} @tab Amharic @tab
11924texinfo.texi(,12326) @code{ar} @tab Arabic @tab
11925texinfo.texi(,12327) @code{as} @tab Assamese
11926texinfo.texi(,12328) @item
11927texinfo.texi(,12329) @code{ay} @tab Aymara @tab
11928texinfo.texi(,12330) @code{az} @tab Azerbaijani @tab
11929texinfo.texi(,12331) @code{ba} @tab Bashkir
11930texinfo.texi(,12332) @item
11931texinfo.texi(,12333) @code{be} @tab Byelorussian @tab
11932texinfo.texi(,12334) @code{bg} @tab Bulgarian @tab
11933texinfo.texi(,12335) @code{bh} @tab Bihari
11934texinfo.texi(,12336) @item
11935texinfo.texi(,12337) @code{bi} @tab Bislama @tab
11936texinfo.texi(,12338) @code{bn} @tab Bengali; Bangla @tab
11937texinfo.texi(,12339) @code{bo} @tab Tibetan
11938texinfo.texi(,12340) @item
11939texinfo.texi(,12341) @code{br} @tab Breton @tab
11940texinfo.texi(,12342) @code{ca} @tab Catalan @tab
11941texinfo.texi(,12343) @code{co} @tab Corsican
11942texinfo.texi(,12344) @item
11943texinfo.texi(,12345) @code{cs} @tab Czech @tab
11944texinfo.texi(,12346) @code{cy} @tab Welsh @tab
11945texinfo.texi(,12347) @code{da} @tab Danish
11946texinfo.texi(,12348) @item
11947texinfo.texi(,12349) @code{de} @tab German @tab
11948texinfo.texi(,12350) @code{dz} @tab Bhutani @tab
11949texinfo.texi(,12351) @code{el} @tab Greek
11950texinfo.texi(,12352) @item
11951texinfo.texi(,12353) @code{en} @tab English @tab
11952texinfo.texi(,12354) @code{eo} @tab Esperanto @tab
11953texinfo.texi(,12355) @code{es} @tab Spanish
11954texinfo.texi(,12356) @item
11955texinfo.texi(,12357) @code{et} @tab Estonian @tab
11956texinfo.texi(,12358) @code{eu} @tab Basque @tab
11957texinfo.texi(,12359) @code{fa} @tab Persian
11958texinfo.texi(,12360) @item
11959texinfo.texi(,12361) @code{fi} @tab Finnish @tab
11960texinfo.texi(,12362) @code{fj} @tab Fiji @tab
11961texinfo.texi(,12363) @code{fo} @tab Faroese
11962texinfo.texi(,12364) @item
11963texinfo.texi(,12365) @code{fr} @tab French @tab
11964texinfo.texi(,12366) @code{fy} @tab Frisian @tab
11965texinfo.texi(,12367) @code{ga} @tab Irish
11966texinfo.texi(,12368) @item
11967texinfo.texi(,12369) @code{gd} @tab Scots Gaelic @tab
11968texinfo.texi(,12370) @code{gl} @tab Galician @tab
11969texinfo.texi(,12371) @code{gn} @tab Guarani
11970texinfo.texi(,12372) @item
11971texinfo.texi(,12373) @code{gu} @tab Gujarati @tab
11972texinfo.texi(,12374) @code{ha} @tab Hausa @tab
11973texinfo.texi(,12375) @code{he} @tab Hebrew
11974texinfo.texi(,12376) @item
11975texinfo.texi(,12377) @code{hi} @tab Hindi @tab
11976texinfo.texi(,12378) @code{hr} @tab Croatian @tab
11977texinfo.texi(,12379) @code{hu} @tab Hungarian
11978texinfo.texi(,12380) @item
11979texinfo.texi(,12381) @code{hy} @tab Armenian @tab
11980texinfo.texi(,12382) @code{ia} @tab Interlingua @tab
11981texinfo.texi(,12383) @code{id} @tab Indonesian
11982texinfo.texi(,12384) @item
11983texinfo.texi(,12385) @code{ie} @tab Interlingue @tab
11984texinfo.texi(,12386) @code{ik} @tab Inupiak @tab
11985texinfo.texi(,12387) @code{is} @tab Icelandic
11986texinfo.texi(,12388) @item
11987texinfo.texi(,12389) @code{it} @tab Italian @tab
11988texinfo.texi(,12390) @code{iu} @tab Inuktitut @tab
11989texinfo.texi(,12391) @code{ja} @tab Japanese
11990texinfo.texi(,12392) @item
11991texinfo.texi(,12393) @code{jw} @tab Javanese @tab
11992texinfo.texi(,12394) @code{ka} @tab Georgian @tab
11993texinfo.texi(,12395) @code{kk} @tab Kazakh
11994texinfo.texi(,12396) @item
11995texinfo.texi(,12397) @code{kl} @tab Greenlandic @tab
11996texinfo.texi(,12398) @code{km} @tab Cambodian @tab
11997texinfo.texi(,12399) @code{kn} @tab Kannada
11998texinfo.texi(,12400) @item
11999texinfo.texi(,12401) @code{ks} @tab Kashmiri @tab
12000texinfo.texi(,12402) @code{ko} @tab Korean @tab
12001texinfo.texi(,12403) @code{ku} @tab Kurdish
12002texinfo.texi(,12404) @item
12003texinfo.texi(,12405) @code{ky} @tab Kirghiz @tab
12004texinfo.texi(,12406) @code{la} @tab Latin @tab
12005texinfo.texi(,12407) @code{ln} @tab Lingala
12006texinfo.texi(,12408) @item
12007texinfo.texi(,12409) @code{lt} @tab Lithuanian @tab
12008texinfo.texi(,12410) @code{lo} @tab Laothian @tab
12009texinfo.texi(,12411) @code{lv} @tab Latvian, Lettish
12010texinfo.texi(,12412) @item
12011texinfo.texi(,12413) @code{mg} @tab Malagasy @tab
12012texinfo.texi(,12414) @code{mi} @tab Maori @tab
12013texinfo.texi(,12415) @code{mk} @tab Macedonian
12014texinfo.texi(,12416) @item
12015texinfo.texi(,12417) @code{ml} @tab Malayalam @tab
12016texinfo.texi(,12418) @code{mn} @tab Mongolian @tab
12017texinfo.texi(,12419) @code{mo} @tab Moldavian
12018texinfo.texi(,12420) @item
12019texinfo.texi(,12421) @code{mr} @tab Marathi @tab
12020texinfo.texi(,12422) @code{ms} @tab Malay @tab
12021texinfo.texi(,12423) @code{mt} @tab Maltese
12022texinfo.texi(,12424) @item
12023texinfo.texi(,12425) @code{my} @tab Burmese @tab
12024texinfo.texi(,12426) @code{na} @tab Nauru @tab
12025texinfo.texi(,12427) @code{ne} @tab Nepali
12026texinfo.texi(,12428) @item
12027texinfo.texi(,12429) @code{nl} @tab Dutch @tab
12028texinfo.texi(,12430) @code{no} @tab Norwegian @tab
12029texinfo.texi(,12431) @code{oc} @tab Occitan
12030texinfo.texi(,12432) @item
12031texinfo.texi(,12433) @code{om} @tab (Afan) Oromo @tab
12032texinfo.texi(,12434) @code{or} @tab Oriya @tab
12033texinfo.texi(,12435) @code{pa} @tab Punjabi
12034texinfo.texi(,12436) @item
12035texinfo.texi(,12437) @code{pl} @tab Polish @tab
12036texinfo.texi(,12438) @code{ps} @tab Pashto, Pushto @tab
12037texinfo.texi(,12439) @code{pt} @tab Portuguese
12038texinfo.texi(,12440) @item
12039texinfo.texi(,12441) @code{qu} @tab Quechua @tab
12040texinfo.texi(,12442) @code{rm} @tab Rhaeto-Romance @tab
12041texinfo.texi(,12443) @code{rn} @tab Kirundi
12042texinfo.texi(,12444) @item
12043texinfo.texi(,12445) @code{ro} @tab Romanian @tab
12044texinfo.texi(,12446) @code{ru} @tab Russian @tab
12045texinfo.texi(,12447) @code{rw} @tab Kinyarwanda
12046texinfo.texi(,12448) @item
12047texinfo.texi(,12449) @code{sa} @tab Sanskrit @tab
12048texinfo.texi(,12450) @code{sd} @tab Sindhi @tab
12049texinfo.texi(,12451) @code{sg} @tab Sangro
12050texinfo.texi(,12452) @item
12051texinfo.texi(,12453) @code{sh} @tab Serbo-Croatian @tab
12052texinfo.texi(,12454) @code{si} @tab Sinhalese @tab
12053texinfo.texi(,12455) @code{sk} @tab Slovak
12054texinfo.texi(,12456) @item
12055texinfo.texi(,12457) @code{sl} @tab Slovenian @tab
12056texinfo.texi(,12458) @code{sm} @tab Samoan @tab
12057texinfo.texi(,12459) @code{sn} @tab Shona
12058texinfo.texi(,12460) @item
12059texinfo.texi(,12461) @code{so} @tab Somali @tab
12060texinfo.texi(,12462) @code{sq} @tab Albanian @tab
12061texinfo.texi(,12463) @code{sr} @tab Serbian
12062texinfo.texi(,12464) @item
12063texinfo.texi(,12465) @code{ss} @tab Siswati @tab
12064texinfo.texi(,12466) @code{st} @tab Sesotho @tab
12065texinfo.texi(,12467) @code{su} @tab Sundanese
12066texinfo.texi(,12468) @item
12067texinfo.texi(,12469) @code{sv} @tab Swedish @tab
12068texinfo.texi(,12470) @code{sw} @tab Swahili @tab
12069texinfo.texi(,12471) @code{ta} @tab Tamil
12070texinfo.texi(,12472) @item
12071texinfo.texi(,12473) @code{te} @tab Telugu @tab
12072texinfo.texi(,12474) @code{tg} @tab Tajik @tab
12073texinfo.texi(,12475) @code{th} @tab Thai
12074texinfo.texi(,12476) @item
12075texinfo.texi(,12477) @code{ti} @tab Tigrinya @tab
12076texinfo.texi(,12478) @code{tk} @tab Turkmen @tab
12077texinfo.texi(,12479) @code{tl} @tab Tagalog
12078texinfo.texi(,12480) @item
12079texinfo.texi(,12481) @code{tn} @tab Setswana @tab
12080texinfo.texi(,12482) @code{to} @tab Tonga @tab
12081texinfo.texi(,12483) @code{tr} @tab Turkish
12082texinfo.texi(,12484) @item
12083texinfo.texi(,12485) @code{ts} @tab Tsonga @tab
12084texinfo.texi(,12486) @code{tt} @tab Tatar @tab
12085texinfo.texi(,12487) @code{tw} @tab Twi
12086texinfo.texi(,12488) @item
12087texinfo.texi(,12489) @code{ug} @tab Uighur @tab
12088texinfo.texi(,12490) @code{uk} @tab Ukrainian @tab
12089texinfo.texi(,12491) @code{ur} @tab Urdu
12090texinfo.texi(,12492) @item
12091texinfo.texi(,12493) @code{uz} @tab Uzbek @tab
12092texinfo.texi(,12494) @code{vi} @tab Vietnamese @tab
12093texinfo.texi(,12495) @code{vo} @tab Volapuk
12094texinfo.texi(,12496) @item
12095texinfo.texi(,12497) @code{wo} @tab Wolof @tab
12096texinfo.texi(,12498) @code{xh} @tab Xhosa @tab
12097texinfo.texi(,12499) @code{yi} @tab Yiddish
12098texinfo.texi(,12500) @item
12099texinfo.texi(,12501) @code{yo} @tab Yoruba @tab
12100texinfo.texi(,12502) @code{za} @tab Zhuang @tab
12101texinfo.texi(,12503) @code{zh} @tab Chinese
12102texinfo.texi(,12504) @item
12103texinfo.texi(,12505) @code{zu} @tab Zulu
12104texinfo.texi(,12506) @end multitable
12105texinfo.texi(,12507)
12106texinfo.texi(,12508)
12107texinfo.texi(,12509) @node documentencoding
12108texinfo.texi(,12510) @section @code{@@documentencoding @var{enc}}: Set Input Encoding
12109texinfo.texi(,12511)
12110texinfo.texi(,12512) @findex documentencoding
12111texinfo.texi(,12513) @cindex Encoding, declaring
12112texinfo.texi(,12514) @cindex Input encoding, declaring
12113texinfo.texi(,12515) @cindex Document input encoding
12114texinfo.texi(,12516)
12115texinfo.texi(,12517) The @code{@@documentencoding} command declares the input document
12116texinfo.texi(,12518) encoding.  Write it on a line by itself, with a valid encoding
12117texinfo.texi(,12519) specification following, such as @samp{ISO-8859-1}.
12118texinfo.texi(,12520)
12119texinfo.texi(,12521) @cindex http-equiv, and charset
12120texinfo.texi(,12522) @cindex meta HTML tag, and charset
12121texinfo.texi(,12523) At present, this is used only in HTML output from @code{makeinfo}.  If a
12122texinfo.texi(,12524) document encoding @var{enc} is specified, it is used in a
12123texinfo.texi(,12525) @samp{<meta>} tag included in the @samp{<head>} of the output:
12124texinfo.texi(,12526)
12125texinfo.texi(,12527) @example
12126texinfo.texi(,12528) <meta http-equiv="Content-Type" content="text/html;
12127texinfo.texi(,12529)       charset=@var{enc}">
12128texinfo.texi(,12530) @end example
12129texinfo.texi(,12531)
12130texinfo.texi(,12532)
12131texinfo.texi(,12533) @node Defining New Texinfo Commands
12132texinfo.texi(,12534) @chapter Defining New Texinfo Commands
12133texinfo.texi(,12535) @cindex Macros
12134texinfo.texi(,12536) @cindex Defining new Texinfo commands
12135texinfo.texi(,12537) @cindex New Texinfo commands, defining
12136texinfo.texi(,12538) @cindex Texinfo commands, defining new
12137texinfo.texi(,12539) @cindex User-defined Texinfo commands
12138texinfo.texi(,12540)
12139texinfo.texi(,12541) Texinfo provides several ways to define new commands:
12140texinfo.texi(,12542)
12141texinfo.texi(,12543) @itemize @bullet
12142texinfo.texi(,12544) @item
12143texinfo.texi(,12545) A Texinfo @dfn{macro} allows you to define a new Texinfo command as any
12144texinfo.texi(,12546) sequence of text and/or existing commands (including other macros).  The
12145texinfo.texi(,12547) macro can have any number of @dfn{parameters}---text you supply each
12146texinfo.texi(,12548) time you use the macro.
12147texinfo.texi(,12549)
12148texinfo.texi(,12550) Incidentally, these macros have nothing to do with the @code{@@defmac}
12149texinfo.texi(,12551) command, which is for documenting macros in the subject of the manual
12150texinfo.texi(,12552) (@pxref{Def Cmd Template}).
12151texinfo.texi(,12553)
12152texinfo.texi(,12554) @item
12153texinfo.texi(,12555) @samp{@@alias} is a convenient way to define a new name for an existing
12154texinfo.texi(,12556) command.
12155texinfo.texi(,12557)
12156texinfo.texi(,12558) @item
12157texinfo.texi(,12559) @samp{@@definfoenclose} allows you to define new commands with
12158texinfo.texi(,12560) customized output in the Info file.
12159texinfo.texi(,12561)
12160texinfo.texi(,12562) @end itemize
12161texinfo.texi(,12563)
12162texinfo.texi(,12564) @menu
12163texinfo.texi(,12565) * Defining Macros::             Defining and undefining new commands.
12164texinfo.texi(,12566) * Invoking Macros::             Using a macro, once you've defined it.
12165texinfo.texi(,12567) * Macro Details::               Beyond basic macro usage.
12166texinfo.texi(,12568) * alias::                       Command aliases.
12167texinfo.texi(,12569) * definfoenclose::              Customized highlighting.
12168texinfo.texi(,12570) @end menu
12169texinfo.texi(,12571)
12170texinfo.texi(,12572)
12171texinfo.texi(,12573) @node Defining Macros
12172texinfo.texi(,12574) @section Defining Macros
12173texinfo.texi(,12575) @cindex Defining macros
12174texinfo.texi(,12576) @cindex Macro definitions
12175texinfo.texi(,12577)
12176texinfo.texi(,12578) @findex macro
12177texinfo.texi(,12579) You use the Texinfo @code{@@macro} command to define a macro, like this:
12178texinfo.texi(,12580)
12179texinfo.texi(,12581) @example
12180texinfo.texi(,12582) @@macro @var{macroname}@{@var{param1}, @var{param2}, @dots{}@}
12181texinfo.texi(,12583) @var{text} @dots{} \@var{param1}\ @dots{}
12182texinfo.texi(,12584) @@end macro
12183texinfo.texi(,12585) @end example
12184texinfo.texi(,12586)
12185texinfo.texi(,12587) The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to
12186texinfo.texi(,12588) arguments supplied when the macro is subsequently used in the document
12187texinfo.texi(,12589) (described in the next section).
12188texinfo.texi(,12590)
12189texinfo.texi(,12591) For a macro to work with @TeX{}, @var{macroname} must consist entirely
12190texinfo.texi(,12592) of letters: no digits, hyphens, underscores, or other special characters.
12191texinfo.texi(,12593)
12192texinfo.texi(,12594) If a macro needs no parameters, you can define it either with an empty
12193texinfo.texi(,12595) list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro
12194texinfo.texi(,12596) foo}).
12195texinfo.texi(,12597)
12196texinfo.texi(,12598) @cindex Body of a macro
12197texinfo.texi(,12599) @cindex Mutually recursive macros
12198texinfo.texi(,12600) @cindex Recursion, mutual
12199texinfo.texi(,12601) The definition or @dfn{body} of the macro can contain most Texinfo
12200texinfo.texi(,12602) commands, including previously-defined macros.  Not-yet-defined macro
12201texinfo.texi(,12603) invocations are not allowed; thus, it is not possible to have mutually
12202texinfo.texi(,12604) recursive Texinfo macros.  Also, a macro definition that defines another
12203texinfo.texi(,12605) macro does not work in @TeX{} due to limitations in the design of
12204texinfo.texi(,12606) @code{@@macro}.
12205texinfo.texi(,12607)
12206texinfo.texi(,12608) @cindex Parameters to macros
12207texinfo.texi(,12609) In the macro body, instances of a parameter name surrounded by
12208texinfo.texi(,12610) backslashes, as in @samp{\@var{param1}\} in the example above, are
12209texinfo.texi(,12611) replaced by the corresponding argument from the macro invocation.  You
12210texinfo.texi(,12612) can use parameter names any number of times in the body, including zero.
12211texinfo.texi(,12613)
12212texinfo.texi(,12614) @cindex Backslash in macros
12213texinfo.texi(,12615) To get a single @samp{\} in the macro expansion, use @samp{\\}.  Any
12214texinfo.texi(,12616) other use of @samp{\} in the body yields a warning.
12215texinfo.texi(,12617)
12216texinfo.texi(,12618) @cindex Spaces in macros
12217texinfo.texi(,12619) @cindex Whitespace in macros
12218texinfo.texi(,12620) The newlines after the @code{@@macro} line and before the @code{@@end
12219texinfo.texi(,12621) macro} line are ignored, that is, not included in the macro body.  All
12220texinfo.texi(,12622) other whitespace is treated according to the usual Texinfo rules.
12221texinfo.texi(,12623)
12222texinfo.texi(,12624) @cindex Recursive macro invocations
12223texinfo.texi(,12625) @findex rmacro
12224texinfo.texi(,12626) To allow a macro to be used recursively, that is, in an argument to a
12225texinfo.texi(,12627) call to itself, you must define it with @samp{@@rmacro}, like this:
12226texinfo.texi(,12628)
12227texinfo.texi(,12629) @example
12228texinfo.texi(,12630) @@rmacro rmac @{arg@}
12229texinfo.texi(,12631) a\arg\b
12230texinfo.texi(,12632) @@end rmacro
12231texinfo.texi(,12633) @dots{}
12232texinfo.texi(,12634) @@rmac@{1@@rmac@{text@}2@}
12233texinfo.texi(,12635) @end example
12234texinfo.texi(,12636)
12235texinfo.texi(,12637) This produces the output `a1atextb2b'.  With @samp{@@macro} instead of
12236texinfo.texi(,12638) @samp{@@rmacro}, an error message is given.
12237texinfo.texi(,12639)
12238texinfo.texi(,12640) @findex unmacro
12239texinfo.texi(,12641) @cindex Macros, undefining
12240texinfo.texi(,12642) @cindex Undefining macros
12241texinfo.texi(,12643) You can undefine a macro @var{foo} with @code{@@unmacro @var{foo}}.
12242texinfo.texi(,12644) It is not an error to undefine a macro that is already undefined.
12243texinfo.texi(,12645) For example:
12244texinfo.texi(,12646)
12245texinfo.texi(,12647) @example
12246texinfo.texi(,12648) @@unmacro foo
12247texinfo.texi(,12649) @end example
12248texinfo.texi(,12650)
12249texinfo.texi(,12651)
12250texinfo.texi(,12652) @node Invoking Macros
12251texinfo.texi(,12653) @section Invoking Macros
12252texinfo.texi(,12654) @cindex Invoking macros
12253texinfo.texi(,12655) @cindex Expanding macros
12254texinfo.texi(,12656) @cindex Running macros
12255texinfo.texi(,12657) @cindex Macro invocation
12256texinfo.texi(,12658)
12257texinfo.texi(,12659) After a macro is defined (see the previous section), you can use
12258texinfo.texi(,12660) (@dfn{invoke}) it in your document like this:
12259texinfo.texi(,12661)
12260texinfo.texi(,12662) @example
12261texinfo.texi(,12663) @@@var{macroname} @{@var{arg1}, @var{arg2}, @dots{}@}
12262texinfo.texi(,12664) @end example
12263texinfo.texi(,12665)
12264texinfo.texi(,12666) @noindent and the result will be just as if you typed the body of
12265texinfo.texi(,12667) @var{macroname} at that spot.  For example:
12266texinfo.texi(,12668)
12267texinfo.texi(,12669) @example
12268texinfo.texi(,12670) @@macro foo @{p, q@}
12269texinfo.texi(,12671) Together: \p\ & \q\.
12270texinfo.texi(,12672) @@end macro
12271texinfo.texi(,12673) @@foo@{a, b@}
12272texinfo.texi(,12674) @end example
12273texinfo.texi(,12675)
12274texinfo.texi(,12676) @noindent produces:
12275texinfo.texi(,12677)
12276texinfo.texi(,12678) @display
12277texinfo.texi(,12679) Together: a & b.
12278texinfo.texi(,12680) @end display
12279texinfo.texi(,12681)
12280texinfo.texi(,12682) @cindex Backslash, and macros
12281texinfo.texi(,12683) Thus, the arguments and parameters are separated by commas and delimited
12282texinfo.texi(,12684) by braces; any whitespace after (but not before) a comma is ignored.
12283texinfo.texi(,12685) The braces are required in the invocation (but not the definition), even
12284texinfo.texi(,12686) when the macro takes no arguments, consistent with all other Texinfo
12285texinfo.texi(,12687) commands.  For example:
12286texinfo.texi(,12688)
12287texinfo.texi(,12689) @example
12288texinfo.texi(,12690) @@macro argless @{@}
12289texinfo.texi(,12691) No arguments here.
12290texinfo.texi(,12692) @@end macro
12291texinfo.texi(,12693) @@argless@{@}
12292texinfo.texi(,12694) @end example
12293texinfo.texi(,12695)
12294texinfo.texi(,12696) @noindent produces:
12295texinfo.texi(,12697)
12296texinfo.texi(,12698) @display
12297texinfo.texi(,12699) No arguments here.
12298texinfo.texi(,12700) @end display
12299texinfo.texi(,12701)
12300texinfo.texi(,12702) @cindex Comma, in macro arguments
12301texinfo.texi(,12703) @cindex Braces, in macro arguments
12302texinfo.texi(,12704) To insert a comma, brace, or backslash in an argument, prepend a
12303texinfo.texi(,12705) backslash, as in
12304texinfo.texi(,12706)
12305texinfo.texi(,12707) @example
12306texinfo.texi(,12708) @@@var{macname} @{\\\@{\@}\,@}
12307texinfo.texi(,12709) @end example
12308texinfo.texi(,12710)
12309texinfo.texi(,12711) @noindent
12310texinfo.texi(,12712) which will pass the (almost certainly error-producing) argument
12311texinfo.texi(,12713) @samp{\@{@},} to @var{macname}.  However, commas in parameters, even
12312texinfo.texi(,12714) if escaped by a backslash, might cause trouble in @TeX{}.
12313texinfo.texi(,12715)
12314texinfo.texi(,12716) If the macro is defined to take a single argument, and is invoked
12315texinfo.texi(,12717) without any braces, the entire rest of the line after the macro name is
12316texinfo.texi(,12718) supplied as the argument.  For example:
12317texinfo.texi(,12719)
12318texinfo.texi(,12720) @example
12319texinfo.texi(,12721) @@macro bar @{p@}
12320texinfo.texi(,12722) Twice: \p\ & \p\.
12321texinfo.texi(,12723) @@end macro
12322texinfo.texi(,12724) @@bar aah
12323texinfo.texi(,12725) @end example
12324texinfo.texi(,12726)
12325texinfo.texi(,12727) @noindent produces:
12326texinfo.texi(,12728)
12327texinfo.texi(,12729) @c Sorry for cheating, but let's not require macros to process the manual.
12328texinfo.texi(,12730) @display
12329texinfo.texi(,12731) Twice: aah & aah.
12330texinfo.texi(,12732) @end display
12331texinfo.texi(,12733)
12332texinfo.texi(,12734) If the macro is defined to take a single argument, and is invoked with
12333texinfo.texi(,12735) braces, the braced text is passed as the argument, regardless of
12334texinfo.texi(,12736) commas.  For example:
12335texinfo.texi(,12737)
12336texinfo.texi(,12738) @example
12337texinfo.texi(,12739) @@macro bar @{p@}
12338texinfo.texi(,12740) Twice: \p\ & \p\.
12339texinfo.texi(,12741) @@end macro
12340texinfo.texi(,12742) @@bar@{a,b@}
12341texinfo.texi(,12743) @end example
12342texinfo.texi(,12744)
12343texinfo.texi(,12745) @noindent produces:
12344texinfo.texi(,12746)
12345texinfo.texi(,12747) @display
12346texinfo.texi(,12748) Twice: a,b & a,b.
12347texinfo.texi(,12749) @end display
12348texinfo.texi(,12750)
12349texinfo.texi(,12751)
12350texinfo.texi(,12752) @node Macro Details
12351texinfo.texi(,12753) @section Macro Details
12352texinfo.texi(,12754) @cindex Macro details
12353texinfo.texi(,12755) @cindex Details of macro usage
12354texinfo.texi(,12756)
12355texinfo.texi(,12757) Due to unavoidable disparities in the @TeX{} and @command{makeinfo}
12356texinfo.texi(,12758) implementations, Texinfo macros have the following limitations.
12357texinfo.texi(,12759)
12358texinfo.texi(,12760) @itemize @bullet
12359texinfo.texi(,12761) @item
12360texinfo.texi(,12762) All macros are expanded inside at least one @TeX{} group.  This means
12361texinfo.texi(,12763) that @code{@@set} and other such commands will have no effect inside a
12362texinfo.texi(,12764) macro.
12363texinfo.texi(,12765)
12364texinfo.texi(,12766) @item
12365texinfo.texi(,12767) Macros containing a command which must be on a line by itself, such as a
12366texinfo.texi(,12768) conditional, cannot be invoked in the middle of a line.
12367texinfo.texi(,12769)
12368texinfo.texi(,12770) @item
12369texinfo.texi(,12771) Commas in macro arguments, even if escaped by a backslash, don't
12370texinfo.texi(,12772) always work.
12371texinfo.texi(,12773)
12372texinfo.texi(,12774) @item
12373texinfo.texi(,12775) The @TeX{} implementation cannot construct macros that define macros in
12374texinfo.texi(,12776) the natural way.  To do this, you must use conditionals and raw @TeX{}.
12375texinfo.texi(,12777) For example:
12376texinfo.texi(,12778)
12377texinfo.texi(,12779) @example
12378texinfo.texi(,12780) @@ifnottex
12379texinfo.texi(,12781) @@macro ctor @{name, arg@}
12380texinfo.texi(,12782) @@macro \name\
12381texinfo.texi(,12783) something involving \arg\ somehow
12382texinfo.texi(,12784) @@end macro
12383texinfo.texi(,12785) @@end macro
12384texinfo.texi(,12786) @@end ifnottex
12385texinfo.texi(,12787) @@tex
12386texinfo.texi(,12788) \gdef\ctor#1@{\ctorx#1,@}
12387texinfo.texi(,12789) \gdef\ctorx#1,#2,@{\def#1@{something involving #2 somehow@}@}
12388texinfo.texi(,12790) @@end tex
12389texinfo.texi(,12791) @end example
12390texinfo.texi(,12792)
12391texinfo.texi(,12793) @item
12392texinfo.texi(,12794) It is best to avoid comments inside macro definitions.
12393texinfo.texi(,12795)
12394texinfo.texi(,12796) @end itemize
12395texinfo.texi(,12797)
12396texinfo.texi(,12798) If some macro feature causes errors when producing the printed version
12397texinfo.texi(,12799) of a manual, try expanding the macros with @command{makeinfo} by
12398texinfo.texi(,12800) invoking @command{texi2dvi} with the @samp{-e} option; see @ref{Format
12399texinfo.texi(,12801) with texi2dvi}.
12400texinfo.texi(,12802)
12401texinfo.texi(,12803) @node alias
12402texinfo.texi(,12804) @section @samp{@@alias @var{new}=@var{existing}}
12403texinfo.texi(,12805) @cindex Aliases, command
12404texinfo.texi(,12806) @cindex Command aliases
12405texinfo.texi(,12807) @findex alias
12406texinfo.texi(,12808)
12407texinfo.texi(,12809) The @samp{@@alias} command defines a new command to be just like an
12408texinfo.texi(,12810) existing one.  This is useful for defining additional markup names, thus
12409texinfo.texi(,12811) preserving semantic information in the input even though the output
12410texinfo.texi(,12812) result may be the same.
12411texinfo.texi(,12813)
12412texinfo.texi(,12814) Write the @samp{@@alias} command on a line by itself, followed by the
12413texinfo.texi(,12815) new command name, an equals sign, and the existing command name.
12414texinfo.texi(,12816) Whitespace around the equals sign is ignored.  Thus:
12415texinfo.texi(,12817) @example
12416texinfo.texi(,12818) @@alias @var{new} = @var{existing}
12417texinfo.texi(,12819) @end example
12418texinfo.texi(,12820)
12419texinfo.texi(,12821) For example, if your document contains citations for both books and
12420texinfo.texi(,12822) some other media (movies, for example), you might like to define a
12421texinfo.texi(,12823) macro @code{@@moviecite@{@}} that does the same thing as an ordinary
12422texinfo.texi(,12824) @code{@@cite@{@}} but conveys the extra semantic information as well.
12423texinfo.texi(,12825) You'd do this as follows:
12424texinfo.texi(,12826)
12425texinfo.texi(,12827) @example
12426texinfo.texi(,12828) @@alias moviecite = cite
12427texinfo.texi(,12829) @end example
12428texinfo.texi(,12830)
12429texinfo.texi(,12831) Macros do not always have the same effect due to vagaries of argument
12430texinfo.texi(,12832) parsing.  Also, aliases are much simpler to define than macros.  So the
12431texinfo.texi(,12833) command is not redundant.  (It was also heavily used in the Jargon File!)
12432texinfo.texi(,12834)
12433texinfo.texi(,12835) Aliases must not be recursive, directly or indirectly.
12434texinfo.texi(,12836)
12435texinfo.texi(,12837) @node definfoenclose
12436texinfo.texi(,12838) @section @samp{definfoenclose}: Customized Highlighting
12437texinfo.texi(,12839) @cindex Highlighting, customized
12438texinfo.texi(,12840) @cindex Customized highlighting
12439texinfo.texi(,12841) @findex definfoenclose
12440texinfo.texi(,12842)
12441texinfo.texi(,12843) A @code{@@definfoenclose} command may be used to define a highlighting
12442texinfo.texi(,12844) command for Info, but not for @TeX{}.  A command defined using
12443texinfo.texi(,12845) @code{@@definfoenclose} marks text by enclosing it in strings that
12444texinfo.texi(,12846) precede and follow the text.  You can use this to get closer control of
12445texinfo.texi(,12847) your Info output.
12446texinfo.texi(,12848)
12447texinfo.texi(,12849) Presumably, if you define a command with @code{@@definfoenclose} for Info,
12448texinfo.texi(,12850) you will create a corresponding command for @TeX{}, either in
12449texinfo.texi(,12851) @file{texinfo.tex}, @file{texinfo.cnf}, or within an @samp{@@iftex} in
12450texinfo.texi(,12852) your document.
12451texinfo.texi(,12853)
12452texinfo.texi(,12854) Write a @code{@@definfoenclose} command on a line and follow it with
12453texinfo.texi(,12855) three arguments separated by commas.  The first argument to
12454texinfo.texi(,12856) @code{@@definfoenclose} is the @@-command name (without the @code{@@});
12455texinfo.texi(,12857) the second argument is the Info start delimiter string; and the third
12456texinfo.texi(,12858) argument is the Info end delimiter string.  The latter two arguments
12457texinfo.texi(,12859) enclose the highlighted text in the Info file.  A delimiter string may
12458texinfo.texi(,12860) contain spaces.  Neither the start nor end delimiter is required.  If
12459texinfo.texi(,12861) you do not want a start delimiter but do want an end delimiter, you must
12460texinfo.texi(,12862) follow the command name with two commas in a row; otherwise, the Info
12461texinfo.texi(,12863) formatting commands will naturally misinterpret the end delimiter string
12462texinfo.texi(,12864) you intended as the start delimiter string.
12463texinfo.texi(,12865)
12464texinfo.texi(,12866) If you do a @code{@@definfoenclose} on the name of a pre-defined macro
12465texinfo.texi(,12867) (such as @code{@@emph}, @code{@@strong}, @code{@@t}, or @code{@@i}), the
12466texinfo.texi(,12868) enclosure definition will override the built-in definition.
12467texinfo.texi(,12869)
12468texinfo.texi(,12870) An enclosure command defined this way takes one argument in braces; this
12469texinfo.texi(,12871) is intended for new markup commands (@pxref{Marking Text}).
12470texinfo.texi(,12872)
12471texinfo.texi(,12873) @findex phoo
12472texinfo.texi(,12874) For example, you can write:
12473texinfo.texi(,12875)
12474texinfo.texi(,12876) @example
12475texinfo.texi(,12877) @@definfoenclose phoo,//,\\
12476texinfo.texi(,12878) @end example
12477texinfo.texi(,12879)
12478texinfo.texi(,12880) @noindent
12479texinfo.texi(,12881) near the beginning of a Texinfo file to define @code{@@phoo} as an Info
12480texinfo.texi(,12882) formatting command that inserts `//' before and `\\' after the argument
12481texinfo.texi(,12883) to @code{@@phoo}.  You can then write @code{@@phoo@{bar@}} wherever you
12482texinfo.texi(,12884) want `//bar\\' highlighted in Info.
12483texinfo.texi(,12885)
12484texinfo.texi(,12886) Also, for @TeX{} formatting, you could write
12485texinfo.texi(,12887)
12486texinfo.texi(,12888) @example
12487texinfo.texi(,12889) @@iftex
12488texinfo.texi(,12890) @@global@@let@@phoo=@@i
12489texinfo.texi(,12891) @@end iftex
12490texinfo.texi(,12892) @end example
12491texinfo.texi(,12893)
12492texinfo.texi(,12894) @noindent
12493texinfo.texi(,12895) to define @code{@@phoo} as a command that causes @TeX{} to typeset the
12494texinfo.texi(,12896) argument to @code{@@phoo} in italics.
12495texinfo.texi(,12897)
12496texinfo.texi(,12898) Each definition applies to its own formatter: one for @TeX{}, the other
12497texinfo.texi(,12899) for @code{texinfo-format-buffer} or @code{texinfo-format-region}.  The
12498texinfo.texi(,12900) @code{@@definfoenclose} command need not be within @samp{@@ifinfo}, but
12499texinfo.texi(,12901) the raw @TeX{} commands do need to be in @samp{@@iftex}.
12500texinfo.texi(,12902)
12501texinfo.texi(,12903) @findex headword
12502texinfo.texi(,12904) Here is another example: write
12503texinfo.texi(,12905)
12504texinfo.texi(,12906) @example
12505texinfo.texi(,12907) @@definfoenclose headword, , :
12506texinfo.texi(,12908) @end example
12507texinfo.texi(,12909)
12508texinfo.texi(,12910) @noindent
12509texinfo.texi(,12911) near the beginning of the file, to define @code{@@headword} as an Info
12510texinfo.texi(,12912) formatting command that inserts nothing before and a colon after the
12511texinfo.texi(,12913) argument to @code{@@headword}.
12512texinfo.texi(,12914)
12513texinfo.texi(,12915) @samp{@@definfoenclose} definitions must not be recursive, directly or
12514texinfo.texi(,12916) indirectly.
12515texinfo.texi(,12917)
12516texinfo.texi(,12918)
12517texinfo.texi(,12919) @node Hardcopy
12518texinfo.texi(,12920) @chapter Formatting and Printing Hardcopy
12519texinfo.texi(,12921) @cindex Format and print hardcopy
12520texinfo.texi(,12922) @cindex Printing hardcopy
12521texinfo.texi(,12923) @cindex Hardcopy, printing it
12522texinfo.texi(,12924) @cindex Making a printed manual
12523texinfo.texi(,12925) @cindex Sorting indices
12524texinfo.texi(,12926) @cindex Indices, sorting
12525texinfo.texi(,12927) @cindex @TeX{} index sorting
12526texinfo.texi(,12928) @pindex texindex
12527texinfo.texi(,12929)
12528texinfo.texi(,12930) There are three major shell commands for making a printed manual from a
12529texinfo.texi(,12931) Texinfo file: one for converting the Texinfo file into a file that will be
12530texinfo.texi(,12932) printed, a second for sorting indices, and a third for printing the
12531texinfo.texi(,12933) formatted document.  When you use the shell commands, you can either
12532texinfo.texi(,12934) work directly in the operating system shell or work within a shell
12533texinfo.texi(,12935) inside GNU Emacs.
12534texinfo.texi(,12936)
12535texinfo.texi(,12937) If you are using GNU Emacs, you can use commands provided by Texinfo
12536texinfo.texi(,12938) mode instead of shell commands.  In addition to the three commands to
12537texinfo.texi(,12939) format a file, sort the indices, and print the result, Texinfo mode
12538texinfo.texi(,12940) offers key bindings for commands to recenter the output buffer, show the
12539texinfo.texi(,12941) print queue, and delete a job from the print queue.
12540texinfo.texi(,12942)
12541texinfo.texi(,12943) @menu
12542texinfo.texi(,12944) * Use TeX::                     Use @TeX{} to format for hardcopy.
12543texinfo.texi(,12945) * Format with tex/texindex::    How to format with explicit shell commands.
12544texinfo.texi(,12946) * Format with texi2dvi::        A simpler way to format.
12545texinfo.texi(,12947) * Print with lpr::              How to print.
12546texinfo.texi(,12948) * Within Emacs::                How to format and print from an Emacs shell.
12547texinfo.texi(,12949) * Texinfo Mode Printing::       How to format and print in Texinfo mode.
12548texinfo.texi(,12950) * Compile-Command::             How to print using Emacs's compile command.
12549texinfo.texi(,12951) * Requirements Summary::        @TeX{} formatting requirements summary.
12550texinfo.texi(,12952) * Preparing for TeX::           What to do before you use @TeX{}.
12551texinfo.texi(,12953) * Overfull hboxes::             What are and what to do with overfull hboxes.
12552texinfo.texi(,12954) * smallbook::                   How to print small format books and manuals.
12553texinfo.texi(,12955) * A4 Paper::                    How to print on A4 or A5 paper.
12554texinfo.texi(,12956) * pagesizes::                   How to print with customized page sizes.
12555texinfo.texi(,12957) * Cropmarks and Magnification::  How to print marks to indicate the size
12556texinfo.texi(,12958)                                 of pages and how to print scaled up output.
12557texinfo.texi(,12959) * PDF Output::                  Portable Document Format output.
12558texinfo.texi(,12960) @end menu
12559texinfo.texi(,12961)
12560texinfo.texi(,12962) @node Use TeX
12561texinfo.texi(,12963) @section Use @TeX{}
12562texinfo.texi(,12964)
12563texinfo.texi(,12965) The typesetting program called @TeX{} is used for formatting a Texinfo
12564texinfo.texi(,12966) file.  @TeX{} is a very powerful typesetting program and, if used correctly,
12565texinfo.texi(,12967) does an exceptionally good job.  (@xref{Obtaining TeX, , How to Obtain
12566texinfo.texi(,12968) @TeX{}}, for information on how to obtain @TeX{}.)
12567texinfo.texi(,12969)
12568texinfo.texi(,12970) The standalone @code{makeinfo} program and Emacs functions
12569texinfo.texi(,12971) @code{texinfo-format-region} and @code{texinfo-format-buffer} commands
12570texinfo.texi(,12972) read the very same @@-commands in the Texinfo file as does @TeX{}, but
12571texinfo.texi(,12973) process them differently to make an Info file (@pxref{Creating an Info
12572texinfo.texi(,12974) File}).
12573texinfo.texi(,12975)
12574texinfo.texi(,12976)
12575texinfo.texi(,12977) @node Format with tex/texindex
12576texinfo.texi(,12978) @section Format with @code{tex} and @code{texindex}
12577texinfo.texi(,12979) @cindex Shell formatting with @code{tex} and @code{texindex}
12578texinfo.texi(,12980) @cindex Formatting with @code{tex} and @code{texindex}
12579texinfo.texi(,12981) @cindex DVI file
12580texinfo.texi(,12982)
12581texinfo.texi(,12983) Format the Texinfo file with the shell command @code{tex} followed by
12582texinfo.texi(,12984) the name of the Texinfo file.  For example:
12583texinfo.texi(,12985)
12584texinfo.texi(,12986) @example
12585texinfo.texi(,12987) tex foo.texi
12586texinfo.texi(,12988) @end example
12587texinfo.texi(,12989)
12588texinfo.texi(,12990) @noindent @TeX{} will produce a @dfn{DVI file} as well as several auxiliary
12589texinfo.texi(,12991) files containing information for indices, cross references, etc.  The
12590texinfo.texi(,12992) DVI file (for @dfn{DeVice Independent} file) can be printed on virtually
12591texinfo.texi(,12993) any device (see the following sections).
12592texinfo.texi(,12994)
12593texinfo.texi(,12995) @pindex texindex
12594texinfo.texi(,12996) The @code{tex} formatting command itself does not sort the indices; it
12595texinfo.texi(,12997) writes an output file of unsorted index data.  (The @code{texi2dvi}
12596texinfo.texi(,12998) command automatically generates indices; @pxref{Format with texi2dvi,,
12597texinfo.texi(,12999) Format with @code{texi2dvi}}.)  To generate a printed index after
12598texinfo.texi(,13000) running the @code{tex} command, you first need a sorted index to work
12599texinfo.texi(,13001) from.  The @code{texindex} command sorts indices.  (The source file
12600texinfo.texi(,13002) @file{texindex.c} comes as part of the standard Texinfo distribution,
12601texinfo.texi(,13003) among other places.)@refill
12602texinfo.texi(,13004)
12603texinfo.texi(,13005) @cindex Names of index files
12604texinfo.texi(,13006) @cindex Index file names
12605texinfo.texi(,13007) The @code{tex} formatting command outputs unsorted index files under
12606texinfo.texi(,13008) names that obey a standard convention: the name of your main input file
12607texinfo.texi(,13009) with any @samp{.tex} (or similar, @pxref{tex invocation,,, web2c,
12608texinfo.texi(,13010) Web2c}) extension removed, followed by the two letter names of indices.
12609texinfo.texi(,13011) For example, the raw index output files for the input file
12610texinfo.texi(,13012) @file{foo.texinfo} would be @file{foo.cp}, @file{foo.vr}, @file{foo.fn},
12611texinfo.texi(,13013) @file{foo.tp}, @file{foo.pg} and @file{foo.ky}.  Those are exactly the
12612texinfo.texi(,13014) arguments to give to @code{texindex}.
12613texinfo.texi(,13015)
12614texinfo.texi(,13016) @need 1000
12615texinfo.texi(,13017) @cindex Wildcards
12616texinfo.texi(,13018) @cindex Globbing
12617texinfo.texi(,13019) Instead of specifying all the unsorted index file names explicitly, you
12618texinfo.texi(,13020) can use @samp{??} as shell wildcards and give the command in this
12619texinfo.texi(,13021) form:
12620texinfo.texi(,13022)
12621texinfo.texi(,13023) @example
12622texinfo.texi(,13024) texindex foo.??
12623texinfo.texi(,13025) @end example
12624texinfo.texi(,13026)
12625texinfo.texi(,13027) @noindent
12626texinfo.texi(,13028) This command will run @code{texindex} on all the unsorted index files,
12627texinfo.texi(,13029) including any that you have defined yourself using @code{@@defindex}
12628texinfo.texi(,13030) or @code{@@defcodeindex}.  (You may execute @samp{texindex foo.??}
12629texinfo.texi(,13031) even if there are similarly named files with two letter extensions
12630texinfo.texi(,13032) that are not index files, such as @samp{foo.el}.  The @code{texindex}
12631texinfo.texi(,13033) command reports but otherwise ignores such files.)
12632texinfo.texi(,13034)
12633texinfo.texi(,13035) For each file specified, @code{texindex} generates a sorted index file
12634texinfo.texi(,13036) whose name is made by appending @samp{s} to the input file name.  The
12635texinfo.texi(,13037) @code{@@printindex} command looks for a file with that name
12636texinfo.texi(,13038) (@pxref{Printing Indices & Menus}).  @code{texindex} does not alter the
12637texinfo.texi(,13039) raw index output file.
12638texinfo.texi(,13040)
12639texinfo.texi(,13041) After you have sorted the indices, you need to rerun the @code{tex}
12640texinfo.texi(,13042) formatting command on the Texinfo file.  This regenerates the DVI file,
12641texinfo.texi(,13043) this time with up-to-date index entries.
12642texinfo.texi(,13044)
12643texinfo.texi(,13045) Finally, you may need to run @code{tex} one more time, to get the page
12644texinfo.texi(,13046) numbers in the cross-references correct.
12645texinfo.texi(,13047)
12646texinfo.texi(,13048) To summarize, this is a five step process:
12647texinfo.texi(,13049)
12648texinfo.texi(,13050) @enumerate
12649texinfo.texi(,13051) @item
12650texinfo.texi(,13052) Run @code{tex} on your Texinfo file.  This generates a DVI file (with
12651texinfo.texi(,13053) undefined cross-references and no indices), and the raw index files
12652texinfo.texi(,13054) (with two letter extensions).
12653texinfo.texi(,13055)
12654texinfo.texi(,13056) @item
12655texinfo.texi(,13057) Run @code{texindex} on the raw index files.  This creates the
12656texinfo.texi(,13058) corresponding sorted index files (with three letter extensions).
12657texinfo.texi(,13059)
12658texinfo.texi(,13060) @item
12659texinfo.texi(,13061) Run @code{tex} again on your Texinfo file.  This regenerates the DVI
12660texinfo.texi(,13062) file, this time with indices and defined cross-references, but with page
12661texinfo.texi(,13063) numbers for the cross-references from last time, generally incorrect.
12662texinfo.texi(,13064)
12663texinfo.texi(,13065) @item
12664texinfo.texi(,13066) Sort the indices again, with @code{texindex}.
12665texinfo.texi(,13067)
12666texinfo.texi(,13068) @item
12667texinfo.texi(,13069) Run @code{tex} one last time.  This time the correct page numbers are
12668texinfo.texi(,13070) written for the cross-references.
12669texinfo.texi(,13071) @end enumerate
12670texinfo.texi(,13072)
12671texinfo.texi(,13073) @pindex texi2dvi
12672texinfo.texi(,13074) Alternatively, it's a one-step process: run @code{texi2dvi}
12673texinfo.texi(,13075) (@pxref{Format with texi2dvi}).
12674texinfo.texi(,13076)
12675texinfo.texi(,13077) You need not run @code{texindex} each time after you run @code{tex}.  If
12676texinfo.texi(,13078) you do not, on the next run, the @code{tex} formatting command will use
12677texinfo.texi(,13079) whatever sorted index files happen to exist from the previous use of
12678texinfo.texi(,13080) @code{texindex}.  This is usually ok while you are debugging.
12679texinfo.texi(,13081)
12680texinfo.texi(,13082) @cindex Auxiliary files, avoiding
12681texinfo.texi(,13083) @findex novalidate
12682texinfo.texi(,13084) @cindex Pointer validation, suppressing
12683texinfo.texi(,13085) @cindex Chapters, formatting one at a time
12684texinfo.texi(,13086) Sometimes you may wish to print a document while you know it is
12685texinfo.texi(,13087) incomplete, or to print just one chapter of a document.  In that case,
12686texinfo.texi(,13088) the usual auxiliary files that @TeX{} creates and warnings @TeX{} gives
12687texinfo.texi(,13089) when cross-references are not satisfied are just nuisances.  You can
12688texinfo.texi(,13090) avoid them with the @code{@@novalidate} command, which you must give
12689texinfo.texi(,13091) @emph{before} the @code{@@setfilename} command
12690texinfo.texi(,13092) (@pxref{setfilename,,@code{@@setfilename}}).  Thus, the beginning of
12691texinfo.texi(,13093) your file would look approximately like this:
12692texinfo.texi(,13094)
12693texinfo.texi(,13095) @example
12694texinfo.texi(,13096) \input texinfo
12695texinfo.texi(,13097) @@novalidate
12696texinfo.texi(,13098) @@setfilename myfile.info
12697texinfo.texi(,13099) @dots{}
12698texinfo.texi(,13100) @end example
12699texinfo.texi(,13101)
12700texinfo.texi(,13102) @noindent @code{@@novalidate} also turns off validation in
12701texinfo.texi(,13103) @code{makeinfo}, just like its @code{--no-validate} option
12702texinfo.texi(,13104) (@pxref{Pointer Validation}).
12703texinfo.texi(,13105)
12704texinfo.texi(,13106)
12705texinfo.texi(,13107) @node Format with texi2dvi
12706texinfo.texi(,13108) @section Format with @code{texi2dvi}
12707texinfo.texi(,13109) @pindex texi2dvi @r{(shell script)}
12708texinfo.texi(,13110)
12709texinfo.texi(,13111) The @code{texi2dvi} command automatically runs both @code{tex} and
12710texinfo.texi(,13112) @code{texindex} as many times as necessary to produce a DVI file with
12711texinfo.texi(,13113) sorted indices and all cross-references resolved.  It simplifies the
12712texinfo.texi(,13114) @code{tex}---@code{texindex}---@code{tex}---@code{tex} sequence
12713texinfo.texi(,13115) described in the previous section.
12714texinfo.texi(,13116)
12715texinfo.texi(,13117) To run @code{texi2dvi} on an input file @file{foo.texi}, do this (where
12716texinfo.texi(,13118) @samp{prompt$ } is your shell prompt):
12717texinfo.texi(,13119)
12718texinfo.texi(,13120) @example
12719texinfo.texi(,13121) prompt$ @kbd{texi2dvi foo.texi}
12720texinfo.texi(,13122) @end example
12721texinfo.texi(,13123)
12722texinfo.texi(,13124) As shown in this example, the input filenames to @code{texi2dvi} must
12723texinfo.texi(,13125) include any extension (@samp{.texi}, @samp{.texinfo}, etc.).  Under
12724texinfo.texi(,13126) MS-DOS and perhaps in other circumstances, you may need to run @samp{sh
12725texinfo.texi(,13127) texi2dvi foo.texi} instead of relying on the operating system to invoke
12726texinfo.texi(,13128) the shell on the @samp{texi2dvi} script.
12727texinfo.texi(,13129)
12728texinfo.texi(,13130) Perhaps the most useful option to @code{texi2dvi} is
12729texinfo.texi(,13131) @samp{--texinfo=@var{cmd}}.  This inserts @var{cmd} on a line by itself
12730texinfo.texi(,13132) after the @code{@@setfilename} in a temporary copy of the input file
12731texinfo.texi(,13133) before running @TeX{}.  With this, you can specify different printing
12732texinfo.texi(,13134) formats, such as @code{@@smallbook} (@pxref{smallbook}),
12733texinfo.texi(,13135) @code{@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes}
12734texinfo.texi(,13136) (@pxref{pagesizes}), without actually changing the document source.
12735texinfo.texi(,13137) (You can also do this on a site-wide basis with @file{texinfo.cnf};
12736texinfo.texi(,13138) @pxref{Preparing for TeX,,Preparing for @TeX{}}).
12737texinfo.texi(,13139)
12738texinfo.texi(,13140) For a list of other options, run @samp{texi2dvi --help}.
12739texinfo.texi(,13141)
12740texinfo.texi(,13142)
12741texinfo.texi(,13143) @node Print with lpr
12742texinfo.texi(,13144) @section Shell Print Using @code{lpr -d}
12743texinfo.texi(,13145) @pindex lpr @r{(DVI print command)}
12744texinfo.texi(,13146)
12745texinfo.texi(,13147) The precise command to print a DVI file depends on your system
12746texinfo.texi(,13148) installation.  Two common ones are @samp{dvips foo.dvi -o} and @samp{lpr
12747texinfo.texi(,13149) -d foo.dvi}.
12748texinfo.texi(,13150)
12749texinfo.texi(,13151) For example, the following commands will (perhaps) suffice to sort the
12750texinfo.texi(,13152) indices, format, and print the @cite{Bison Manual}:
12751texinfo.texi(,13153)
12752texinfo.texi(,13154) @example
12753texinfo.texi(,13155) @group
12754texinfo.texi(,13156) tex bison.texinfo
12755texinfo.texi(,13157) texindex bison.??
12756texinfo.texi(,13158) tex bison.texinfo
12757texinfo.texi(,13159) lpr -d bison.dvi
12758texinfo.texi(,13160) @end group
12759texinfo.texi(,13161) @end example
12760texinfo.texi(,13162)
12761texinfo.texi(,13163) @noindent
12762texinfo.texi(,13164) (Remember that the shell commands may be different at your site; but
12763texinfo.texi(,13165) these are commonly used versions.)
12764texinfo.texi(,13166)
12765texinfo.texi(,13167) Using the @code{texi2dvi} shell script (see the previous section):
12766texinfo.texi(,13168)
12767texinfo.texi(,13169) @example
12768texinfo.texi(,13170) @group
12769texinfo.texi(,13171) texi2dvi bison.texinfo
12770texinfo.texi(,13172) lpr -d bison.dvi
12771texinfo.texi(,13173) # or perhaps dvips bison.dvi -o
12772texinfo.texi(,13174) @end group
12773texinfo.texi(,13175) @end example
12774texinfo.texi(,13176)
12775texinfo.texi(,13177) @cindex Shell printing, on MS-DOS/MS-Windows
12776texinfo.texi(,13178) @cindex Printing DVI files, on MS-DOS/MS-Windows
12777texinfo.texi(,13179) @pindex lpr@r{-d, replacements on MS-DOS/MS-Windows}
12778texinfo.texi(,13180) @code{lpr} is a standard program on Unix systems, but it is usually
12779texinfo.texi(,13181) absent on MS-DOS/MS-Windows.  Some network packages come with a
12780texinfo.texi(,13182) program named @code{lpr}, but these are usually limited to sending files
12781texinfo.texi(,13183) to a print server over the network, and generally don't support the
12782texinfo.texi(,13184) @samp{-d} option.  If you are unfortunate enough to work on one of these
12783texinfo.texi(,13185) systems, you have several alternative ways of printing DVI files:
12784texinfo.texi(,13186)
12785texinfo.texi(,13187) @itemize @bullet{}
12786texinfo.texi(,13188) @item Find and install a Unix-like @code{lpr} program, or its clone.
12787texinfo.texi(,13189) If you can do that, you will be able to print DVI files just like
12788texinfo.texi(,13190) described above.
12789texinfo.texi(,13191)
12790texinfo.texi(,13192) @item Send the DVI files to a network printer queue for DVI files.
12791texinfo.texi(,13193) Some network printers have special queues for printing DVI files.  You
12792texinfo.texi(,13194) should be able to set up your network software to send files to that
12793texinfo.texi(,13195) queue.  In some cases, the version of @code{lpr} which comes with your
12794texinfo.texi(,13196) network software will have a special option to send a file to specific
12795texinfo.texi(,13197) queues, like this:
12796texinfo.texi(,13198)
12797texinfo.texi(,13199) @example
12798texinfo.texi(,13200) lpr -Qdvi -hprint.server.domain bison.dvi
12799texinfo.texi(,13201) @end example
12800texinfo.texi(,13202)
12801texinfo.texi(,13203) @item Convert the DVI file to a Postscript or PCL file and send it to your
12802texinfo.texi(,13204) local printer.  @xref{dvips invocation,,, dvips, Dvips}, and the man
12803texinfo.texi(,13205) pages for @code{dvilj}, for detailed description of these tools.  Once
12804texinfo.texi(,13206) the DVI file is converted to the format your local printer understands
12805texinfo.texi(,13207) directly, just send it to the appropriate port, usually @samp{PRN}.
12806texinfo.texi(,13208) @end itemize
12807texinfo.texi(,13209)
12808texinfo.texi(,13210)
12809texinfo.texi(,13211) @node Within Emacs
12810texinfo.texi(,13212) @section From an Emacs Shell
12811texinfo.texi(,13213) @cindex Print, format from Emacs shell
12812texinfo.texi(,13214) @cindex Format, print from Emacs shell
12813texinfo.texi(,13215) @cindex Shell, format, print from
12814texinfo.texi(,13216) @cindex Emacs shell, format, print from
12815texinfo.texi(,13217) @cindex GNU Emacs shell, format, print from
12816texinfo.texi(,13218)
12817texinfo.texi(,13219) You can give formatting and printing commands from a shell within GNU
12818texinfo.texi(,13220) Emacs.  To create a shell within Emacs, type @kbd{M-x shell}.  In this
12819texinfo.texi(,13221) shell, you can format and print the document.  @xref{Hardcopy, , Format
12820texinfo.texi(,13222) and Print Hardcopy}, for details.
12821texinfo.texi(,13223)
12822texinfo.texi(,13224) You can switch to and from the shell buffer while @code{tex} is
12823texinfo.texi(,13225) running and do other editing.  If you are formatting a long document
12824texinfo.texi(,13226) on a slow machine, this can be very convenient.@refill
12825texinfo.texi(,13227)
12826texinfo.texi(,13228) You can also use @code{texi2dvi} from an Emacs shell.  For example,
12827texinfo.texi(,13229) here is how to use @code{texi2dvi} to format and print @cite{Using and
12828texinfo.texi(,13230) Porting GNU CC} from a shell within Emacs:
12829texinfo.texi(,13231)
12830texinfo.texi(,13232) @example
12831texinfo.texi(,13233) @group
12832texinfo.texi(,13234) texi2dvi gcc.texinfo
12833texinfo.texi(,13235) lpr -d gcc.dvi
12834texinfo.texi(,13236) @end group
12835texinfo.texi(,13237) @end example
12836texinfo.texi(,13239)
12837texinfo.texi(,13240) @xref{Texinfo Mode Printing}, for more information about formatting
12838texinfo.texi(,13241) and printing in Texinfo mode.@refill
12839texinfo.texi(,13243)
12840texinfo.texi(,13244)
12841texinfo.texi(,13245) @node Texinfo Mode Printing, Compile-Command, Within Emacs, Hardcopy
12842texinfo.texi(,13246) @section Formatting and Printing in Texinfo Mode
12843texinfo.texi(,13247) @cindex Region printing in Texinfo mode
12844texinfo.texi(,13248) @cindex Format and print in Texinfo mode
12845texinfo.texi(,13249) @cindex Print and format in Texinfo mode
12846texinfo.texi(,13250)
12847texinfo.texi(,13251) Texinfo mode provides several predefined key commands for @TeX{}
12848texinfo.texi(,13252) formatting and printing.  These include commands for sorting indices,
12849texinfo.texi(,13253) looking at the printer queue, killing the formatting job, and
12850texinfo.texi(,13254) recentering the display of the buffer in which the operations
12851texinfo.texi(,13255) occur.@refill
12852texinfo.texi(,13256)
12853texinfo.texi(,13257) @table @kbd
12854texinfo.texi(,13258) @item C-c C-t C-b
12855texinfo.texi(,13259) @itemx M-x texinfo-tex-buffer
12856texinfo.texi(,13260) Run @code{texi2dvi} on the current buffer.@refill
12857texinfo.texi(,13261)
12858texinfo.texi(,13262) @item C-c C-t C-r
12859texinfo.texi(,13263) @itemx M-x texinfo-tex-region
12860texinfo.texi(,13264) Run @TeX{} on the current region.@refill
12861texinfo.texi(,13265)
12862texinfo.texi(,13266) @item C-c C-t C-i
12863texinfo.texi(,13267) @itemx M-x texinfo-texindex
12864texinfo.texi(,13268) Sort the indices of a Texinfo file formatted with
12865texinfo.texi(,13269) @code{texinfo-tex-region}.@refill
12866texinfo.texi(,13270)
12867texinfo.texi(,13271) @item C-c C-t C-p
12868texinfo.texi(,13272) @itemx M-x texinfo-tex-print
12869texinfo.texi(,13273) Print a DVI file that was made with @code{texinfo-tex-region} or
12870texinfo.texi(,13274) @code{texinfo-tex-buffer}.@refill
12871texinfo.texi(,13275)
12872texinfo.texi(,13276) @item C-c C-t C-q
12873texinfo.texi(,13277) @itemx M-x tex-show-print-queue
12874texinfo.texi(,13278) Show the print queue.@refill
12875texinfo.texi(,13279)
12876texinfo.texi(,13280) @item C-c C-t C-d
12877texinfo.texi(,13281) @itemx M-x texinfo-delete-from-print-queue
12878texinfo.texi(,13282) Delete a job from the print queue; you will be prompted for the job
12879texinfo.texi(,13283) number shown by a preceding @kbd{C-c C-t C-q} command
12880texinfo.texi(,13284) (@code{texinfo-show-tex-print-queue}).@refill
12881texinfo.texi(,13285)
12882texinfo.texi(,13286) @item C-c C-t C-k
12883texinfo.texi(,13287) @itemx M-x tex-kill-job
12884texinfo.texi(,13288) Kill the currently running @TeX{} job started by either
12885texinfo.texi(,13289) @code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other
12886texinfo.texi(,13290) process running in the Texinfo shell buffer.@refill
12887texinfo.texi(,13291)
12888texinfo.texi(,13292) @item C-c C-t C-x
12889texinfo.texi(,13293) @itemx M-x texinfo-quit-job
12890texinfo.texi(,13294) Quit a @TeX{} formatting job that has stopped because of an error by
12891texinfo.texi(,13295) sending an @key{x} to it.  When you do this, @TeX{} preserves a record
12892texinfo.texi(,13296) of what it did in a @file{.log} file.@refill
12893texinfo.texi(,13297)
12894texinfo.texi(,13298) @item C-c C-t C-l
12895texinfo.texi(,13299) @itemx M-x tex-recenter-output-buffer
12896texinfo.texi(,13300) Redisplay the shell buffer in which the @TeX{} printing and formatting
12897texinfo.texi(,13301) commands are run to show its most recent output.@refill
12898texinfo.texi(,13302) @end table
12899texinfo.texi(,13303)
12900texinfo.texi(,13304) @need 1000
12901texinfo.texi(,13305) Thus, the usual sequence of commands for formatting a buffer is as
12902texinfo.texi(,13306) follows (with comments to the right):@refill
12903texinfo.texi(,13307)
12904texinfo.texi(,13308) @example
12905texinfo.texi(,13309) @group
12906texinfo.texi(,13310) C-c C-t C-b             @r{Run @code{texi2dvi} on the buffer.}
12907texinfo.texi(,13311) C-c C-t C-p             @r{Print the DVI file.}
12908texinfo.texi(,13312) C-c C-t C-q             @r{Display the printer queue.}
12909texinfo.texi(,13313) @end group
12910texinfo.texi(,13314) @end example
12911texinfo.texi(,13315)
12912texinfo.texi(,13316) The Texinfo mode @TeX{} formatting commands start a subshell in Emacs
12913texinfo.texi(,13317) called the @file{*tex-shell*}.  The @code{texinfo-tex-command},
12914texinfo.texi(,13318) @code{texinfo-texindex-command}, and @code{tex-dvi-print-command}
12915texinfo.texi(,13319) commands are all run in this shell.
12916texinfo.texi(,13320)
12917texinfo.texi(,13321) You can watch the commands operate in the @samp{*tex-shell*} buffer,
12918texinfo.texi(,13322) and you can switch to and from and use the @samp{*tex-shell*} buffer
12919texinfo.texi(,13323) as you would any other shell buffer.@refill
12920texinfo.texi(,13324)
12921texinfo.texi(,13325) @need 1500
12922texinfo.texi(,13326) The formatting and print commands depend on the values of several variables.
12923texinfo.texi(,13327) The default values are:@refill
12924texinfo.texi(,13328)
12925texinfo.texi(,13329) @example
12926texinfo.texi(,13330) @group
12927texinfo.texi(,13331)      @r{Variable}                              @r{Default value}
12928texinfo.texi(,13332)
12929texinfo.texi(,13333) texinfo-texi2dvi-command                  "texi2dvi"
12930texinfo.texi(,13334) texinfo-tex-command                       "tex"
12931texinfo.texi(,13335) texinfo-texindex-command                  "texindex"
12932texinfo.texi(,13336) texinfo-delete-from-print-queue-command   "lprm"
12933texinfo.texi(,13337) texinfo-tex-trailer                       "@@bye"
12934texinfo.texi(,13338) tex-start-of-header                       "%**start"
12935texinfo.texi(,13339) tex-end-of-header                         "%**end"
12936texinfo.texi(,13340) tex-dvi-print-command                     "lpr -d"
12937texinfo.texi(,13341) tex-show-queue-command                    "lpq"
12938texinfo.texi(,13342) @end group
12939texinfo.texi(,13343) @end example
12940texinfo.texi(,13344)
12941texinfo.texi(,13345) You can change the values of these variables with the @kbd{M-x
12942texinfo.texi(,13346) edit-options} command (@pxref{Edit Options, , Editing Variable Values,
12943texinfo.texi(,13347) emacs, The GNU Emacs Manual}), with the @kbd{M-x set-variable} command
12944texinfo.texi(,13348) (@pxref{Examining, , Examining and Setting Variables, emacs, The GNU
12945texinfo.texi(,13349) Emacs Manual}), or with your @file{.emacs} initialization file
12946texinfo.texi(,13350) (@pxref{Init File, , , emacs, The GNU Emacs Manual}).@refill
12947texinfo.texi(,13351)
12948texinfo.texi(,13352) @cindex Customize Emacs package (@t{Development/Docs/Texinfo})
12949texinfo.texi(,13353) Beginning with version 20, GNU Emacs offers a user-friendly interface,
12950texinfo.texi(,13354) called @dfn{Customize}, for changing values of user-definable variables.
12951texinfo.texi(,13355) @xref{Easy Customization, , Easy Customization Interface, emacs, The GNU
12952texinfo.texi(,13356) Emacs Manual}, for more details about this.  The Texinfo variables can
12953texinfo.texi(,13357) be found in the @samp{Development/Docs/Texinfo} group, once you invoke
12954texinfo.texi(,13358) the @kbd{M-x customize} command.
12955texinfo.texi(,13359)
12956texinfo.texi(,13360)
12957texinfo.texi(,13361) @node Compile-Command
12958texinfo.texi(,13362) @section Using the Local Variables List
12959texinfo.texi(,13363) @cindex Local variables
12960texinfo.texi(,13364) @cindex Compile command for formatting
12961texinfo.texi(,13365) @cindex Format with the compile command
12962texinfo.texi(,13366)
12963texinfo.texi(,13367) Yet another way to apply the @TeX{} formatting command to a Texinfo file
12964texinfo.texi(,13368) is to put that command in a @dfn{local variables list} at the end of the
12965texinfo.texi(,13369) Texinfo file.  You can then specify the @code{tex} or @code{texi2dvi}
12966texinfo.texi(,13370) commands as a @code{compile-command} and have Emacs run it by typing
12967texinfo.texi(,13371) @kbd{M-x compile}.  This creates a special shell called the
12968texinfo.texi(,13372) @file{*compilation*} buffer in which Emacs runs the compile command.
12969texinfo.texi(,13373) For example, at the end of the @file{gdb.texinfo} file, after the
12970texinfo.texi(,13374) @code{@@bye}, you could put the following:@refill
12971texinfo.texi(,13375)
12972texinfo.texi(,13376) @example
12973texinfo.texi(,13377) @group
12974texinfo.texi(,13378) Local Variables:
12975texinfo.texi(,13379) compile-command: "texi2dvi gdb.texinfo"
12976texinfo.texi(,13380) End:
12977texinfo.texi(,13381) @end group
12978texinfo.texi(,13382) @end example
12979texinfo.texi(,13383)
12980texinfo.texi(,13384) @noindent
12981texinfo.texi(,13385) This technique is most often used by programmers who also compile programs
12982texinfo.texi(,13386) this way; see @ref{Compilation, , , emacs, The GNU Emacs Manual}.@refill
12983texinfo.texi(,13387)
12984texinfo.texi(,13388)
12985texinfo.texi(,13389) @node Requirements Summary
12986texinfo.texi(,13390) @section @TeX{} Formatting Requirements Summary
12987texinfo.texi(,13391) @cindex Requirements for formatting
12988texinfo.texi(,13392) @cindex Minimal requirements for formatting
12989texinfo.texi(,13393) @cindex Formatting requirements
12990texinfo.texi(,13394)
12991texinfo.texi(,13395) Every Texinfo file that is to be input to @TeX{} must begin with a
12992texinfo.texi(,13396) @code{\input} command and must contain an @code{@@setfilename} command:
12993texinfo.texi(,13397)
12994texinfo.texi(,13398) @example
12995texinfo.texi(,13399) \input texinfo
12996texinfo.texi(,13400) @@setfilename @var{arg-not-used-by-@TeX{}}
12997texinfo.texi(,13401) @end example
12998texinfo.texi(,13402)
12999texinfo.texi(,13403) @noindent
13000texinfo.texi(,13404) The first command instructs @TeX{} to load the macros it needs to
13001texinfo.texi(,13405) process a Texinfo file and the second command opens auxiliary files.
13002texinfo.texi(,13406)
13003texinfo.texi(,13407) Every Texinfo file must end with a line that terminates @TeX{}'s
13004texinfo.texi(,13408) processing and forces out unfinished pages:
13005texinfo.texi(,13409)
13006texinfo.texi(,13410) @example
13007texinfo.texi(,13411) @@bye
13008texinfo.texi(,13412) @end example
13009texinfo.texi(,13413)
13010texinfo.texi(,13414) Strictly speaking, these lines are all a Texinfo file needs to be
13011texinfo.texi(,13415) processed successfully by @TeX{}.
13012texinfo.texi(,13416)
13013texinfo.texi(,13417) Usually, however, the beginning includes an @code{@@settitle} command to
13014texinfo.texi(,13418) define the title of the printed manual, an @code{@@setchapternewpage}
13015texinfo.texi(,13419) command, a title page, a copyright page, and permissions.  Besides an
13016texinfo.texi(,13420) @code{@@bye}, the end of a file usually includes indices and a table of
13017texinfo.texi(,13421) contents.  (And of course most manuals contain a body of text as well.)
13018texinfo.texi(,13422)
13019texinfo.texi(,13423) For more information, see:
13020texinfo.texi(,13424) @itemize @bullet
13021texinfo.texi(,13425) @item @ref{settitle, , @code{@@settitle}}
13022texinfo.texi(,13426) @item @ref{setchapternewpage, , @code{@@setchapternewpage}}
13023texinfo.texi(,13427) @item @ref{Headings, ,Page Headings}
13024texinfo.texi(,13428) @item @ref{Titlepage & Copyright Page}
13025texinfo.texi(,13429) @item @ref{Printing Indices & Menus}
13026texinfo.texi(,13430) @item @ref{Contents}
13027texinfo.texi(,13431) @end itemize
13028texinfo.texi(,13432)
13029texinfo.texi(,13433)
13030texinfo.texi(,13434) @node Preparing for TeX
13031texinfo.texi(,13435) @section Preparing for @TeX{}
13032texinfo.texi(,13436) @cindex Preparing for @TeX{}
13033texinfo.texi(,13437) @cindex @TeX{} input initialization
13034texinfo.texi(,13438) @cindex @code{TEXINPUTS} environment variable
13035texinfo.texi(,13439) @vindex TEXINPUTS
13036texinfo.texi(,13440) @cindex @b{.profile} initialization file
13037texinfo.texi(,13441) @cindex @b{.cshrc} initialization file
13038texinfo.texi(,13442) @cindex Initialization file for @TeX{} input
13039texinfo.texi(,13443)
13040texinfo.texi(,13444) @TeX{} needs to know where to find the @file{texinfo.tex} file that the
13041texinfo.texi(,13445) @samp{\input texinfo} command on the first line reads.  The
13042texinfo.texi(,13446) @file{texinfo.tex} file tells @TeX{} how to handle @@-commands; it is
13043texinfo.texi(,13447) included in all standard GNU distributions.
13044texinfo.texi(,13448)
13045texinfo.texi(,13449) @pindex texinfo.tex@r{, installing}
13046texinfo.texi(,13450)
13047texinfo.texi(,13451) Usually, the installer has put the @file{texinfo.tex} file in the
13048texinfo.texi(,13452) default directory that contains @TeX{} macros when GNU Texinfo, Emacs or
13049texinfo.texi(,13453) other GNU software is installed.  In this case, @TeX{} will find the
13050texinfo.texi(,13454) file and you do not need to do anything special.  If this has not been
13051texinfo.texi(,13455) done, you can put @file{texinfo.tex} in the current directory when you
13052texinfo.texi(,13456) run @TeX{}, and @TeX{} will find it there.
13053texinfo.texi(,13457)
13054texinfo.texi(,13458) @pindex epsf.tex@r{, installing}
13055texinfo.texi(,13459) Also, you should install @file{epsf.tex}, if it is not already installed
13056texinfo.texi(,13460) from another distribution.  More details are at the end of the description
13057texinfo.texi(,13461) of the @code{@@image} command (@pxref{Images}).
13058texinfo.texi(,13462)
13059texinfo.texi(,13463) @pindex pdfcolor.tex@r{, installing}
13060texinfo.texi(,13464) Likewise for @file{pdfcolor.tex}, if it is not already installed and you
13061texinfo.texi(,13465) use pdftex.
13062texinfo.texi(,13466)
13063texinfo.texi(,13467) @pindex texinfo.cnf @r{installation}
13064texinfo.texi(,13468) @cindex Customizing of @TeX{} for Texinfo
13065texinfo.texi(,13469) @cindex Site-wide Texinfo configuration file
13066texinfo.texi(,13470) Optionally, you may create an additional @file{texinfo.cnf}, and install
13067texinfo.texi(,13471) it as well.  This file is read by @TeX{} when the @code{@@setfilename}
13068texinfo.texi(,13472) command is executed (@pxref{setfilename,, @code{@@setfilename}}).  You can put any
13069texinfo.texi(,13473) commands you like there, according to local site-wide conventions.  They
13070texinfo.texi(,13474) will be read by @TeX{} when processing any Texinfo document.  For
13071texinfo.texi(,13475) example, if @file{texinfo.cnf} contains the line @samp{@@afourpaper}
13072texinfo.texi(,13476) (@pxref{A4 Paper}), then all Texinfo documents will be processed with
13073texinfo.texi(,13477) that page size in effect.  If you have nothing to put in
13074texinfo.texi(,13478) @file{texinfo.cnf}, you do not need to create it.
13075texinfo.texi(,13479)
13076texinfo.texi(,13480) @vindex TEXINPUTS
13077texinfo.texi(,13481) If neither of the above locations for these system files suffice for
13078texinfo.texi(,13482) you, you can specify the directories explicitly.  For
13079texinfo.texi(,13483) @file{texinfo.tex}, you can do this by writing the complete path for the
13080texinfo.texi(,13484) file after the @code{\input} command.  Another way, that works for both
13081texinfo.texi(,13485) @file{texinfo.tex} and @file{texinfo.cnf} (and any other file @TeX{}
13082texinfo.texi(,13486) might read), is to set the @code{TEXINPUTS} environment variable in your
13083texinfo.texi(,13487) @file{.cshrc} or @file{.profile} file.
13084texinfo.texi(,13488)
13085texinfo.texi(,13489) Which you use of @file{.cshrc} or @file{.profile} depends on
13086texinfo.texi(,13490) whether you use a Bourne shell-compatible (@code{sh}, @code{bash},
13087texinfo.texi(,13491) @code{ksh}, @dots{}) or C shell-compatible (@code{csh}, @code{tcsh})
13088texinfo.texi(,13492) command interpreter.  The latter read the @file{.cshrc} file for
13089texinfo.texi(,13493) initialization information, and the former read @file{.profile}.
13090texinfo.texi(,13494)
13091texinfo.texi(,13495) In a @file{.cshrc} file, you could use the following @code{csh} command
13092texinfo.texi(,13496) sequence:
13093texinfo.texi(,13497)
13094texinfo.texi(,13498) @example
13095texinfo.texi(,13499) setenv TEXINPUTS .:/home/me/mylib:/usr/lib/tex/macros
13096texinfo.texi(,13500) @end example
13097texinfo.texi(,13501)
13098texinfo.texi(,13502) @need 1000
13099texinfo.texi(,13503) In a @file{.profile} file, you could use the following @code{sh} command
13100texinfo.texi(,13504) sequence:
13101texinfo.texi(,13505)
13102texinfo.texi(,13506) @example
13103texinfo.texi(,13507) @group
13104texinfo.texi(,13508) TEXINPUTS=.:/home/me/mylib:/usr/lib/tex/macros
13105texinfo.texi(,13509) export TEXINPUTS
13106texinfo.texi(,13510) @end group
13107texinfo.texi(,13511) @end example
13108texinfo.texi(,13512)
13109texinfo.texi(,13513) On MS-DOS/MS-Windows, you would say it like this@footnote{Note the use
13110texinfo.texi(,13514) of the @samp{;} character, instead of @samp{:}, as directory separator
13111texinfo.texi(,13515) on these systems.}:
13112texinfo.texi(,13516)
13113texinfo.texi(,13517) @example
13114texinfo.texi(,13518) @group
13115texinfo.texi(,13519) set TEXINPUTS=.;d:/home/me/mylib;c:/usr/lib/tex/macros
13116texinfo.texi(,13520) @end group
13117texinfo.texi(,13521) @end example
13118texinfo.texi(,13522)
13119texinfo.texi(,13523) @noindent
13120texinfo.texi(,13524) It is customary for DOS/Windows users to put such commands in the
13121texinfo.texi(,13525) @file{autoexec.bat} file, or in the Windows Registry.@refill
13122texinfo.texi(,13526)
13123texinfo.texi(,13527) @noindent
13124texinfo.texi(,13528) These settings would cause @TeX{} to look for @file{\input} file first
13125texinfo.texi(,13529) in the current directory, indicated by the @samp{.}, then in a
13126texinfo.texi(,13530) hypothetical user's @file{me/mylib} directory, and finally in a system
13127texinfo.texi(,13531) directory @file{/usr/lib/tex/macros}.
13128texinfo.texi(,13532)
13129texinfo.texi(,13533) @cindex Dumping a .fmt file
13130texinfo.texi(,13534) @cindex Format file, dumping
13131texinfo.texi(,13535) Finally, you may wish to dump a @file{.fmt} file (@pxref{Memory dumps,,,
13132texinfo.texi(,13536) web2c, Web2c}) so that @TeX{} can load Texinfo faster.  (The
13133texinfo.texi(,13537) disadvantage is that then updating @file{texinfo.tex} requires
13134texinfo.texi(,13538) redumping.)  You can do this by running this command, assuming
13135texinfo.texi(,13539) @file{epsf.tex} is findable by @TeX{}:
13136texinfo.texi(,13540)
13137texinfo.texi(,13541) @example
13138texinfo.texi(,13542) initex texinfo @@dump
13139texinfo.texi(,13543) @end example
13140texinfo.texi(,13544)
13141texinfo.texi(,13545) (@code{dump} is a @TeX{} primitive.)  Then, move @file{texinfo.fmt} to
13142texinfo.texi(,13546) wherever your @code{.fmt} files are found; typically, this will be in the
13143texinfo.texi(,13547) subdirectory @file{web2c} of your @TeX{} installation.
13144texinfo.texi(,13548)
13145texinfo.texi(,13549)
13146texinfo.texi(,13550) @node Overfull hboxes
13147texinfo.texi(,13551) @section Overfull ``hboxes''
13148texinfo.texi(,13552) @cindex Overfull @samp{hboxes}
13149texinfo.texi(,13553) @cindex @samp{hboxes}, overfull
13150texinfo.texi(,13554) @cindex Final output
13151texinfo.texi(,13555)
13152texinfo.texi(,13556) @TeX{} is sometimes unable to typeset a line without extending it into
13153texinfo.texi(,13557) the right margin.  This can occur when @TeX{} comes upon what it
13154texinfo.texi(,13558) interprets as a long word that it cannot hyphenate, such as an
13155texinfo.texi(,13559) electronic mail network address or a very long title.  When this
13156texinfo.texi(,13560) happens, @TeX{} prints an error message like this:
13157texinfo.texi(,13561)
13158texinfo.texi(,13562) @example
13159texinfo.texi(,13563) Overfull @@hbox (20.76302pt too wide)
13160texinfo.texi(,13564) @end example
13161texinfo.texi(,13565)
13162texinfo.texi(,13566) @findex hbox
13163texinfo.texi(,13567) @noindent
13164texinfo.texi(,13568) (In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''.
13165texinfo.texi(,13569) @samp{@@hbox} is a @TeX{} primitive not needed in the Texinfo language.)
13166texinfo.texi(,13570)
13167texinfo.texi(,13571) @TeX{} also provides the line number in the Texinfo source file and
13168texinfo.texi(,13572) the text of the offending line, which is marked at all the places that
13169texinfo.texi(,13573) @TeX{} considered hyphenation.
13170texinfo.texi(,13574) @xref{Debugging with TeX, , Catching Errors with @TeX{} Formatting},
13171texinfo.texi(,13575) for more information about typesetting errors.
13172texinfo.texi(,13576)
13173texinfo.texi(,13577) If the Texinfo file has an overfull hbox, you can rewrite the sentence
13174texinfo.texi(,13578) so the overfull hbox does not occur, or you can decide to leave it.  A
13175texinfo.texi(,13579) small excursion into the right margin often does not matter and may not
13176texinfo.texi(,13580) even be noticeable.
13177texinfo.texi(,13581)
13178texinfo.texi(,13582) If you have many overfull boxes and/or an antipathy to rewriting, you
13179texinfo.texi(,13583) can coerce @TeX{} into greatly increasing the allowable interword
13180texinfo.texi(,13584) spacing, thus (if you're lucky) avoiding many of the bad line breaks,
13181texinfo.texi(,13585) like this:
13182texinfo.texi(,13586)
13183texinfo.texi(,13587) @findex \emergencystretch
13184texinfo.texi(,13588) @example
13185texinfo.texi(,13589) @@tex
13186texinfo.texi(,13590) \global\emergencystretch = .9\hsize
13187texinfo.texi(,13591) @@end tex
13188texinfo.texi(,13592) @end example
13189texinfo.texi(,13593)
13190texinfo.texi(,13594) @noindent
13191texinfo.texi(,13595) (You should adjust the fraction as needed.)  This huge value for
13192texinfo.texi(,13596) @code{\emergencystretch} cannot be the default, since then the typeset
13193texinfo.texi(,13597) output would generally be of noticeably lower quality; the default
13194texinfo.texi(,13598) is @samp{.15\hsize}.  @code{\hsize} is the @TeX{} dimension
13195texinfo.texi(,13599) containing the current line width.
13196texinfo.texi(,13600)
13197texinfo.texi(,13601) @cindex Black rectangle in hardcopy
13198texinfo.texi(,13602) @cindex Rectangle, black in hardcopy
13199texinfo.texi(,13603) @cindex Box, ugly black in hardcopy
13200texinfo.texi(,13604) @cindex Ugly black rectangles in hardcopy
13201texinfo.texi(,13605) For what overfull boxes you have, however, @TeX{} will print a large,
13202texinfo.texi(,13606) ugly, black rectangle beside the line that contains the overfull hbox
13203texinfo.texi(,13607) unless told otherwise.  This is so you will notice the location of the
13204texinfo.texi(,13608) problem if you are correcting a draft.
13205texinfo.texi(,13609)
13206texinfo.texi(,13610) @findex finalout
13207texinfo.texi(,13611) To prevent such a monstrosity from marring your final printout, write
13208texinfo.texi(,13612) the following in the beginning of the Texinfo file on a line of its own,
13209texinfo.texi(,13613) before the @code{@@titlepage} command:
13210texinfo.texi(,13614)
13211texinfo.texi(,13615) @example
13212texinfo.texi(,13616) @@finalout
13213texinfo.texi(,13617) @end example
13214texinfo.texi(,13618)
13215texinfo.texi(,13619)
13216texinfo.texi(,13620) @node smallbook
13217texinfo.texi(,13621) @section Printing ``Small'' Books
13218texinfo.texi(,13622) @findex smallbook
13219texinfo.texi(,13623) @cindex Small book size
13220texinfo.texi(,13624) @cindex Book, printing small
13221texinfo.texi(,13625) @cindex Page sizes for books
13222texinfo.texi(,13626) @cindex Size of printed book
13223texinfo.texi(,13627)
13224texinfo.texi(,13628) By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch
13225texinfo.texi(,13629) format.  However, you can direct @TeX{} to typeset a document in a 7 by
13226texinfo.texi(,13630) 9.25 inch format that is suitable for bound books by inserting the
13227texinfo.texi(,13631) following command on a line by itself at the beginning of the Texinfo
13228texinfo.texi(,13632) file, before the title page:@refill
13229texinfo.texi(,13633)
13230texinfo.texi(,13634) @example
13231texinfo.texi(,13635) @@smallbook
13232texinfo.texi(,13636) @end example
13233texinfo.texi(,13637)
13234texinfo.texi(,13638) @noindent
13235texinfo.texi(,13639) (Since many books are about 7 by 9.25 inches, this command might better
13236texinfo.texi(,13640) have been called the @code{@@regularbooksize} command, but it came to be
13237texinfo.texi(,13641) called the @code{@@smallbook} command by comparison to the 8.5 by 11 inch format.)
13238texinfo.texi(,13642)
13239texinfo.texi(,13643) If you write the @code{@@smallbook} command between the
13240texinfo.texi(,13644) start-of-header and end-of-header lines, the Texinfo mode @TeX{}
13241texinfo.texi(,13645) region formatting command, @code{texinfo-tex-region}, will format the
13242texinfo.texi(,13646) region in ``small'' book size (@pxref{Start of Header}).@refill
13243texinfo.texi(,13647)
13244texinfo.texi(,13648) @xref{small}, for information about
13245texinfo.texi(,13649) commands that make it easier to produce examples for a smaller manual.
13246texinfo.texi(,13650)
13247texinfo.texi(,13651) @xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
13248texinfo.texi(,13652) @TeX{}}, for other ways to format with @code{@@smallbook} that do not
13249texinfo.texi(,13653) require changing the source file.
13250texinfo.texi(,13654)
13251texinfo.texi(,13655)
13252texinfo.texi(,13656) @node A4 Paper
13253texinfo.texi(,13657) @section Printing on A4 Paper
13254texinfo.texi(,13658) @cindex A4 paper, printing on
13255texinfo.texi(,13659) @cindex A5 paper, printing on
13256texinfo.texi(,13660) @cindex Paper size, A4
13257texinfo.texi(,13661) @cindex European A4 paper
13258texinfo.texi(,13662) @findex afourpaper
13259texinfo.texi(,13663)
13260texinfo.texi(,13664) You can tell @TeX{} to format a document for printing on European size
13261texinfo.texi(,13665) A4 paper (or A5) with the @code{@@afourpaper} (or @code{@@afivepaper})
13262texinfo.texi(,13666) command.  Write the command on a line by itself near the beginning of
13263texinfo.texi(,13667) the Texinfo file, before the title page.  For example, this is how you
13264texinfo.texi(,13668) would write the header for this manual:
13265texinfo.texi(,13669)
13266texinfo.texi(,13670) @example
13267texinfo.texi(,13671) @group
13268texinfo.texi(,13672) \input texinfo    @@c -*-texinfo-*-
13269texinfo.texi(,13673) @@c %**start of header
13270texinfo.texi(,13674) @@setfilename texinfo
13271texinfo.texi(,13675) @@settitle Texinfo
13272texinfo.texi(,13676) @@afourpaper
13273texinfo.texi(,13677) @@c %**end of header
13274texinfo.texi(,13678) @end group
13275texinfo.texi(,13679) @end example
13276texinfo.texi(,13680)
13277texinfo.texi(,13681) @xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
13278texinfo.texi(,13682) @TeX{}}, for other ways to format for different paper sizes that do not
13279texinfo.texi(,13683) require changing the source file.
13280texinfo.texi(,13684)
13281texinfo.texi(,13685) @findex afourlatex
13282texinfo.texi(,13686) @findex afourwide
13283texinfo.texi(,13687) You may or may not prefer the formatting that results from the command
13284texinfo.texi(,13688) @code{@@afourlatex}.  There's also @code{@@afourwide} for A4 paper in
13285texinfo.texi(,13689) wide format.
13286texinfo.texi(,13690)
13287texinfo.texi(,13691) @node pagesizes
13288texinfo.texi(,13692) @section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom page sizes
13289texinfo.texi(,13693) @findex pagesizes
13290texinfo.texi(,13694) @cindex Custom page sizes
13291texinfo.texi(,13695) @cindex Page sizes, customized
13292texinfo.texi(,13696) @cindex Text width and height
13293texinfo.texi(,13697) @cindex Width of text area
13294texinfo.texi(,13698) @cindex Height of text area
13295texinfo.texi(,13699) @cindex Depth of text area
13296texinfo.texi(,13700)
13297texinfo.texi(,13701) You can explicitly specify the height and (optionally) width of the main
13298texinfo.texi(,13702) text area on the page with the @code{@@pagesizes} command.  Write this
13299texinfo.texi(,13703) on a line by itself near the beginning of the Texinfo file, before the
13300texinfo.texi(,13704) title page.  The height comes first, then the width if desired,
13301texinfo.texi(,13705) separated by a comma.  Examples:
13302texinfo.texi(,13706)
13303texinfo.texi(,13707) @example
13304texinfo.texi(,13708) @@pagesizes 200mm,150mm  @c for b5 paper
13305texinfo.texi(,13709) @end example
13306texinfo.texi(,13710) @noindent and
13307texinfo.texi(,13711) @example
13308texinfo.texi(,13712) @@pagesizes 11.5in      @c for legal paper
13309texinfo.texi(,13713) @end example
13310texinfo.texi(,13714)
13311texinfo.texi(,13715) @cindex B5 paper, printing on
13312texinfo.texi(,13716) @cindex Legal paper, printing on
13313texinfo.texi(,13717) This would be reasonable for printing on B5-size paper.  To emphasize,
13314texinfo.texi(,13718) this command specifies the size of the @emph{text area}, not the size of
13315texinfo.texi(,13719) the paper (which is 250@dmn{mm} by 177@dmn{mm} for B5, 14@dmn{in} by
13316texinfo.texi(,13720) 8.5@dmn{in} for legal).
13317texinfo.texi(,13721)
13318texinfo.texi(,13722) @cindex Margins on page, not controllable
13319texinfo.texi(,13723) To make more elaborate changes, such as changing any of the page
13320texinfo.texi(,13724) margins, you must define a new command in @file{texinfo.tex} (or
13321texinfo.texi(,13725) @file{texinfo.cnf}, @pxref{Preparing for TeX,,Preparing for @TeX{}}).
13322texinfo.texi(,13726)
13323texinfo.texi(,13727) @xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
13324texinfo.texi(,13728) @TeX{}}, for other ways to specify @code{@@pagesizes} that do not
13325texinfo.texi(,13729) require changing the source file.
13326texinfo.texi(,13730)
13327texinfo.texi(,13731) @code{@@pagesizes} is ignored by @code{makeinfo}.
13328texinfo.texi(,13732)
13329texinfo.texi(,13733)
13330texinfo.texi(,13734) @node Cropmarks and Magnification
13331texinfo.texi(,13735) @section Cropmarks and Magnification
13332texinfo.texi(,13736) @findex cropmarks
13333texinfo.texi(,13737) @cindex Cropmarks for printing
13334texinfo.texi(,13738) @cindex Printing cropmarks
13335texinfo.texi(,13739) You can (attempt to) direct @TeX{} to print cropmarks at the corners of
13336texinfo.texi(,13740) pages with the @code{@@cropmarks} command.  Write the @code{@@cropmarks}
13337texinfo.texi(,13741) command on a line by itself between @code{@@iftex} and @code{@@end
13338texinfo.texi(,13742) iftex} lines near the beginning of the Texinfo file, before the title
13339texinfo.texi(,13743) page, like this:@refill
13340texinfo.texi(,13744)
13341texinfo.texi(,13745) @example
13342texinfo.texi(,13746) @group
13343texinfo.texi(,13747) @@iftex
13344texinfo.texi(,13748) @@cropmarks
13345texinfo.texi(,13749) @@end iftex
13346texinfo.texi(,13750) @end group
13347texinfo.texi(,13751) @end example
13348texinfo.texi(,13752)
13349texinfo.texi(,13753) This command is mainly for printers that typeset several pages on one
13350texinfo.texi(,13754) sheet of film; but you can attempt to use it to mark the corners of a
13351texinfo.texi(,13755) book set to 7 by 9.25 inches with the @code{@@smallbook} command.
13352texinfo.texi(,13756) (Printers will not produce cropmarks for regular sized output that is
13353texinfo.texi(,13757) printed on regular sized paper.)  Since different printing machines work
13354texinfo.texi(,13758) in different ways, you should explore the use of this command with a
13355texinfo.texi(,13759) spirit of adventure.  You may have to redefine the command in
13356texinfo.texi(,13760) @file{texinfo.tex}.
13357texinfo.texi(,13761)
13358texinfo.texi(,13762) @findex \mag @r{(raw @TeX{} magnification)}
13359texinfo.texi(,13763) @cindex Magnified printing
13360texinfo.texi(,13764) @cindex Larger or smaller pages
13361texinfo.texi(,13765) You can attempt to direct @TeX{} to typeset pages larger or smaller than
13362texinfo.texi(,13766) usual with the @code{\mag} @TeX{} command.  Everything that is typeset
13363texinfo.texi(,13767) is scaled proportionally larger or smaller.  (@code{\mag} stands for
13364texinfo.texi(,13768) ``magnification''.)  This is @emph{not} a Texinfo @@-command, but is a
13365texinfo.texi(,13769) plain @TeX{} command that is prefixed with a backslash.  You have to
13366texinfo.texi(,13770) write this command between @code{@@tex} and @code{@@end tex}
13367texinfo.texi(,13771) (@pxref{Raw Formatter Commands}).
13368texinfo.texi(,13772)
13369texinfo.texi(,13773) Follow the @code{\mag} command with an @samp{=} and then a number that
13370texinfo.texi(,13774) is 1000 times the magnification you desire.  For example, to print pages
13371texinfo.texi(,13775) at 1.2 normal size, write the following near the beginning of the
13372texinfo.texi(,13776) Texinfo file, before the title page:
13373texinfo.texi(,13777)
13374texinfo.texi(,13778) @example
13375texinfo.texi(,13779) @group
13376texinfo.texi(,13780) @@tex
13377texinfo.texi(,13781) \mag=1200
13378texinfo.texi(,13782) @@end tex
13379texinfo.texi(,13783) @end group
13380texinfo.texi(,13784) @end example
13381texinfo.texi(,13785)
13382texinfo.texi(,13786) With some printing technologies, you can print normal-sized copies that
13383texinfo.texi(,13787) look better than usual by giving a larger-than-normal master to your
13384texinfo.texi(,13788) print shop.  They do the reduction, thus effectively increasing the
13385texinfo.texi(,13789) resolution.
13386texinfo.texi(,13790)
13387texinfo.texi(,13791) Depending on your system, DVI files prepared with a
13388texinfo.texi(,13792) nonstandard-@code{\mag} may not print or may print only with certain
13389texinfo.texi(,13793) magnifications.  Be prepared to experiment.
13390texinfo.texi(,13794)
13391texinfo.texi(,13795)
13392texinfo.texi(,13796) @node PDF Output
13393texinfo.texi(,13797) @section PDF Output
13394texinfo.texi(,13798) @cindex PDF output
13395texinfo.texi(,13799)
13396texinfo.texi(,13800) @pindex pdftex
13397texinfo.texi(,13801) You can generate a PDF output file from Texinfo source by using the
13398texinfo.texi(,13802) @command{pdftex} program to process your file instead of plain
13399texinfo.texi(,13803) @command{tex}.  Just run @samp{pdftex foo.texi} instead of @samp{tex
13400texinfo.texi(,13804) foo.texi}, or give the @samp{--pdf} option to @command{texi2dvi}.
13401texinfo.texi(,13805)
13402texinfo.texi(,13806) @dfn{PDF} stands for `Portable Document Format'. It was invented by
13403texinfo.texi(,13807) Adobe Systems some years ago for document interchange, based on their
13404texinfo.texi(,13808) PostScript language.  A @uref{http://www.foolabs.com/xpdf/, PDF reader}
13405texinfo.texi(,13809) for the X window system is freely available, as is the
13406texinfo.texi(,13810) @uref{http://partners.adobe.com/asn/developer/technotes/, definition of
13407texinfo.texi(,13811) the file format}.  Since PDF is a binary format, there are no
13408texinfo.texi(,13812) @samp{@@ifpdf} or @samp{@@pdf} commands as with the other output
13409texinfo.texi(,13813) formats.
13410texinfo.texi(,13814)
13411texinfo.texi(,13815) Despite the `portable' in the name, PDF files are nowhere near as
13412texinfo.texi(,13816) portable in practice as the plain ASCII formats (Info, HTML) that
13413texinfo.texi(,13817) Texinfo supports (DVI portability is arguable).  They also tend to be
13414texinfo.texi(,13818) much larger and do not support the bitmap fonts used by @TeX{} (by
13415texinfo.texi(,13819) default) very well.  Nevertheless, a PDF file does preserve an actual
13416texinfo.texi(,13820) printed document on a screen as faithfully as possible, so it has its place.
13417texinfo.texi(,13821)
13418texinfo.texi(,13822) PDF support in Texinfo is fairly rudimentary.
13419texinfo.texi(,13823)
13420texinfo.texi(,13824)
13421texinfo.texi(,13825) @node Creating and Installing Info Files
13422texinfo.texi(,13826) @chapter Creating and Installing Info Files
13423texinfo.texi(,13827)
13424texinfo.texi(,13828) This chapter describes how to create and install Info files.  @xref{Info
13425texinfo.texi(,13829) Files}, for general information about the file format itself.
13426texinfo.texi(,13830)
13427texinfo.texi(,13831) @menu
13428texinfo.texi(,13832) * Creating an Info File::
13429texinfo.texi(,13833) * Installing an Info File::
13430texinfo.texi(,13834) @end menu
13431texinfo.texi(,13835)
13432texinfo.texi(,13836)
13433texinfo.texi(,13837) @node Creating an Info File
13434texinfo.texi(,13838) @section Creating an Info File
13435texinfo.texi(,13839) @cindex Creating an Info file
13436texinfo.texi(,13840) @cindex Info, creating an online file
13437texinfo.texi(,13841) @cindex Formatting a file for Info
13438texinfo.texi(,13842)
13439texinfo.texi(,13843) @code{makeinfo} is a program that converts a Texinfo file into an Info
13440texinfo.texi(,13844) file, HTML file, or plain text.  @code{texinfo-format-region} and
13441texinfo.texi(,13845) @code{texinfo-format-buffer} are GNU Emacs functions that convert
13442texinfo.texi(,13846) Texinfo to Info.
13443texinfo.texi(,13847)
13444texinfo.texi(,13848) For information on installing the Info file in the Info system,
13445texinfo.texi(,13849) @pxref{Installing an Info File}.
13446texinfo.texi(,13850)
13447texinfo.texi(,13851) @menu
13448texinfo.texi(,13852) * makeinfo advantages::         @code{makeinfo} provides better error checking.
13449texinfo.texi(,13853) * Invoking makeinfo::           How to run @code{makeinfo} from a shell.
13450texinfo.texi(,13854) * makeinfo options::            Specify fill-column and other options.
13451texinfo.texi(,13855) * Pointer Validation::          How to check that pointers point somewhere.
13452texinfo.texi(,13856) * makeinfo in Emacs::           How to run @code{makeinfo} from Emacs.
13453texinfo.texi(,13857) * texinfo-format commands::     Two Info formatting commands written
13454texinfo.texi(,13858)                                   in Emacs Lisp are an alternative
13455texinfo.texi(,13859)                                   to @code{makeinfo}.
13456texinfo.texi(,13860) * Batch Formatting::            How to format for Info in Emacs Batch mode.
13457texinfo.texi(,13861) * Tag and Split Files::         How tagged and split files help Info
13458texinfo.texi(,13862)                                   to run better.
13459texinfo.texi(,13863) * makeinfo html::               Generating HTML output.
13460texinfo.texi(,13864) @end menu
13461texinfo.texi(,13865)
13462texinfo.texi(,13866)
13463texinfo.texi(,13867) @node makeinfo advantages
13464texinfo.texi(,13868) @subsection @code{makeinfo} Preferred
13465texinfo.texi(,13869)
13466texinfo.texi(,13870) The @code{makeinfo} utility creates an Info file from a Texinfo source
13467texinfo.texi(,13871) file more quickly than either of the Emacs formatting commands and
13468texinfo.texi(,13872) provides better error messages.  We recommend it.  @code{makeinfo} is a
13469texinfo.texi(,13873) C program that is independent of Emacs.  You do not need to run Emacs to
13470texinfo.texi(,13874) use @code{makeinfo}, which means you can use @code{makeinfo} on machines
13471texinfo.texi(,13875) that are too small to run Emacs.  You can run @code{makeinfo} in any one
13472texinfo.texi(,13876) of three ways: from an operating system shell, from a shell inside
13473texinfo.texi(,13877) Emacs, or by typing the @kbd{C-c C-m C-r} or the @kbd{C-c C-m C-b}
13474texinfo.texi(,13878) command in Texinfo mode in Emacs.
13475texinfo.texi(,13879) @refill
13476texinfo.texi(,13880)
13477texinfo.texi(,13881) The @code{texinfo-format-region} and the @code{texinfo-format-buffer}
13478texinfo.texi(,13882) commands are useful if you cannot run @code{makeinfo}.  Also, in some
13479texinfo.texi(,13883) circumstances, they format short regions or buffers more quickly than
13480texinfo.texi(,13884) @code{makeinfo}.@refill
13481texinfo.texi(,13885)
13482texinfo.texi(,13886) @node Invoking makeinfo
13483texinfo.texi(,13887) @subsection Running @code{makeinfo} from a Shell
13484texinfo.texi(,13888)
13485texinfo.texi(,13889) To create an Info file from a Texinfo file, type @code{makeinfo}
13486texinfo.texi(,13890) followed by the name of the Texinfo file.  Thus, to create the Info
13487texinfo.texi(,13891) file for Bison, type the following to the shell:
13488texinfo.texi(,13892)
13489texinfo.texi(,13893) @example
13490texinfo.texi(,13894) makeinfo bison.texinfo
13491texinfo.texi(,13895) @end example
13492texinfo.texi(,13896)
13493texinfo.texi(,13897) (You can run a shell inside Emacs by typing @kbd{M-x shell}.)@refill
13494texinfo.texi(,13898)
13495texinfo.texi(,13900) Sometimes you will want to specify options.  For example, if you wish
13496texinfo.texi(,13901) to discover which version of @code{makeinfo} you are using,
13497texinfo.texi(,13902) type:@refill
13498texinfo.texi(,13903)
13499texinfo.texi(,13904) @example
13500texinfo.texi(,13905) makeinfo --version
13501texinfo.texi(,13906) @end example
13502texinfo.texi(,13907)
13503texinfo.texi(,13908) @xref{makeinfo options}, for more information.
13504texinfo.texi(,13910)
13505texinfo.texi(,13911)
13506texinfo.texi(,13912) @node makeinfo options
13507texinfo.texi(,13913) @subsection Options for @code{makeinfo}
13508texinfo.texi(,13914) @cindex @code{makeinfo} options
13509texinfo.texi(,13915) @cindex Options for @code{makeinfo}
13510texinfo.texi(,13916)
13511texinfo.texi(,13917) The @code{makeinfo} command takes a number of options.  Most often,
13512texinfo.texi(,13918) options are used to set the value of the fill column and specify the
13513texinfo.texi(,13919) footnote style.  Each command line option is a word preceded by
13514texinfo.texi(,13920) @samp{--} or a letter preceded by @samp{-}.  You can use abbreviations
13515texinfo.texi(,13921) for the long option names as long as they are unique.@refill
13516texinfo.texi(,13922)
13517texinfo.texi(,13923) For example, you could use the following shell command to create an Info
13518texinfo.texi(,13924) file for @file{bison.texinfo} in which each line is filled to only 68
13519texinfo.texi(,13925) columns:@refill
13520texinfo.texi(,13926)
13521texinfo.texi(,13927) @example
13522texinfo.texi(,13928) makeinfo --fill-column=68 bison.texinfo
13523texinfo.texi(,13929) @end example
13524texinfo.texi(,13930)
13525texinfo.texi(,13931) You can write two or more options in sequence, like this:@refill
13526texinfo.texi(,13932)
13527texinfo.texi(,13933) @example
13528texinfo.texi(,13934) makeinfo --no-split --fill-column=70 @dots{}
13529texinfo.texi(,13935) @end example
13530texinfo.texi(,13936)
13531texinfo.texi(,13937) @noindent
13532texinfo.texi(,13938) This would keep the Info file together as one possibly very long
13533texinfo.texi(,13939) file and would also set the fill column to 70.@refill
13534texinfo.texi(,13940)
13535texinfo.texi(,13941) The options are:
13536texinfo.texi(,13942)
13537texinfo.texi(,13943) @table @code
13538texinfo.texi(,13944)
13539texinfo.texi(,13945) @item -D @var{var}
13540texinfo.texi(,13946) @opindex -D @var{var}
13541texinfo.texi(,13947) Cause the variable @var{var} to be defined.  This is equivalent to
13542texinfo.texi(,13948) @code{@@set @var{var}} in the Texinfo file (@pxref{set clear value}).
13543texinfo.texi(,13949)
13544texinfo.texi(,13950) @item --commands-in-node-names
13545texinfo.texi(,13951) @opindex --commands-in-node-names
13546texinfo.texi(,13952) Allow @code{@@}-commands in node names.  This is not recommended, as it
13547texinfo.texi(,13953) can probably never be implemented in @TeX{}.  It also makes
13548texinfo.texi(,13954) @code{makeinfo} much slower.  Also, this option is ignored when
13549texinfo.texi(,13955) @samp{--no-validate} is used.  @xref{Pointer Validation}, for more
13550texinfo.texi(,13956) details.
13551texinfo.texi(,13957)
13552texinfo.texi(,13958) @item --docbook
13553texinfo.texi(,13959) @opindex --docbook
13554texinfo.texi(,13960) Generate DocBook output rather than Info.
13555texinfo.texi(,13961)
13556texinfo.texi(,13962) @item --error-limit=@var{limit}
13557texinfo.texi(,13963) @itemx -e @var{limit}
13558texinfo.texi(,13964) @opindex --error-limit=@var{limit}
13559texinfo.texi(,13965) @opindex -e @var{limit}
13560texinfo.texi(,13966) Set the maximum number of errors that @code{makeinfo} will report
13561texinfo.texi(,13967) before exiting (on the assumption that continuing would be useless);
13562texinfo.texi(,13968) default 100.
13563texinfo.texi(,13969)
13564texinfo.texi(,13970) @item --fill-column=@var{width}
13565texinfo.texi(,13971) @itemx -f @var{width}
13566texinfo.texi(,13972) @opindex --fill-column=@var{width}
13567texinfo.texi(,13973) @opindex -f @var{width}
13568texinfo.texi(,13974) Specify the maximum number of columns in a line; this is the right-hand
13569texinfo.texi(,13975) edge of a line.  Paragraphs that are filled will be filled to this
13570texinfo.texi(,13976) width.  (Filling is the process of breaking up and connecting lines so
13571texinfo.texi(,13977) that lines are the same length as or shorter than the number specified
13572texinfo.texi(,13978) as the fill column.  Lines are broken between words.) The default value
13573texinfo.texi(,13979) is 72.  Ignored with @samp{--html}.
13574texinfo.texi(,13980)
13575texinfo.texi(,13981) @item --footnote-style=@var{style}
13576texinfo.texi(,13982) @itemx -s @var{style}
13577texinfo.texi(,13983) @opindex --footnote-style=@var{style}
13578texinfo.texi(,13984) @opindex -s @var{style}
13579texinfo.texi(,13985) Set the footnote style to @var{style}, either @samp{end} for the end
13580texinfo.texi(,13986) node style (the default) or @samp{separate} for the separate node style.
13581texinfo.texi(,13987) The value set by this option overrides the value set in a Texinfo file
13582texinfo.texi(,13988) by an @code{@@footnotestyle} command (@pxref{Footnotes}).  When the
13583texinfo.texi(,13989) footnote style is @samp{separate}, @code{makeinfo} makes a new node
13584texinfo.texi(,13990) containing the footnotes found in the current node.  When the footnote
13585texinfo.texi(,13991) style is @samp{end}, @code{makeinfo} places the footnote references at
13586texinfo.texi(,13992) the end of the current node.  Ignored with @samp{--html}.
13587texinfo.texi(,13993)
13588texinfo.texi(,13994) @item --force
13589texinfo.texi(,13995) @itemx -F
13590texinfo.texi(,13996) @opindex --force
13591texinfo.texi(,13997) @opindex -F
13592texinfo.texi(,13998) Ordinarily, if the input file has errors, the output files are not
13593texinfo.texi(,13999) created.  With this option, they are preserved.
13594texinfo.texi(,14000)
13595texinfo.texi(,14001) @item --help
13596texinfo.texi(,14002) @itemx -h
13597texinfo.texi(,14003) @opindex --help
13598texinfo.texi(,14004) @opindex -h
13599texinfo.texi(,14005) Print a usage message listing all available options, then exit successfully.
13600texinfo.texi(,14006)
13601texinfo.texi(,14007) @item --html
13602texinfo.texi(,14008) @opindex --html
13603texinfo.texi(,14009) Generate HTML output rather than Info.  @xref{makeinfo html}.  By
13604texinfo.texi(,14010) default, the HTML output is split into one output file per source node,
13605texinfo.texi(,14011) and the split output is written into a subdirectory with the name of the
13606texinfo.texi(,14012) top-level info file.
13607texinfo.texi(,14013)
13608texinfo.texi(,14014) @item -I @var{dir}
13609texinfo.texi(,14015) @opindex -I @var{dir}
13610texinfo.texi(,14016) Append @var{dir} to the directory search list for finding files that
13611texinfo.texi(,14017) are included using the @code{@@include} command.  By default,
13612texinfo.texi(,14018) @code{makeinfo} searches only the current directory.  If @var{dir} is
13613texinfo.texi(,14019) not given, the current directory @file{.} is appended.  Note that
13614texinfo.texi(,14020) @var{dir} can actually be a list of several directories separated by the
13615texinfo.texi(,14021) usual path separator character (@samp{:} on Unix, @samp{;} on
13616texinfo.texi(,14022) MS-DOS/MS-Windows).
13617texinfo.texi(,14023)
13618texinfo.texi(,14024) @item --macro-expand=@var{file}
13619texinfo.texi(,14025) @itemx -E @var{file}
13620texinfo.texi(,14026) Output the Texinfo source with all the macros expanded to the named
13621texinfo.texi(,14027) file.  Normally, the results of macro expansion are used internally by
13622texinfo.texi(,14028) @code{makeinfo} and then discarded.  This option is used by
13623texinfo.texi(,14029) @command{texi2dvi} if you are using an old version of @file{texinfo.tex}
13624texinfo.texi(,14030) that does not support @code{@@macro}.
13625texinfo.texi(,14031)
13626texinfo.texi(,14032) @item --no-headers
13627texinfo.texi(,14033) @opindex --no-headers
13628texinfo.texi(,14034) @cindex Plain text output
13629texinfo.texi(,14035) @cindex ASCII text output
13630texinfo.texi(,14036) @cindex Generating plain text files
13631texinfo.texi(,14037) @cindex @file{INSTALL} file, generating
13632texinfo.texi(,14038) @cindex Node separators, omitting
13633texinfo.texi(,14039) @cindex Menus, omitting
13634texinfo.texi(,14040) For Info output, do not include menus or node separator lines in the
13635texinfo.texi(,14041) output.  This results in a simple plain text file that you can (for
13636texinfo.texi(,14042) example) send in email without complications, or include in a
13637texinfo.texi(,14043) distribution (as in an @file{INSTALL} file).
13638texinfo.texi(,14044)
13639texinfo.texi(,14045) @cindex Navigation links, omitting
13640texinfo.texi(,14046) For HTML output, likewise omit menus.  And if @samp{--no-split} is also
13641texinfo.texi(,14047) specified, do not include a navigation links at the top of each node
13642texinfo.texi(,14048) (these are never included in the default case of split output).
13643texinfo.texi(,14049) @xref{makeinfo html}.
13644texinfo.texi(,14050)
13645texinfo.texi(,14051) In both cases, write to standard output by default (can still be
13646texinfo.texi(,14052) overridden by @option{-o}).
13647texinfo.texi(,14053)
13648texinfo.texi(,14054) @item --no-split
13649texinfo.texi(,14055) @opindex --no-split
13650texinfo.texi(,14056) @cindex Splitting of output files
13651texinfo.texi(,14057) @cindex Output file splitting
13652texinfo.texi(,14058) Suppress the splitting stage of @code{makeinfo}.  By default, large
13653texinfo.texi(,14059) output files (where the size is greater than 70k bytes) are split into
13654texinfo.texi(,14060) smaller subfiles.  For Info output, each one is approximately 50k bytes.
13655texinfo.texi(,14061) For HTML output, each file contains one node (@pxref{makeinfo html}).
13656texinfo.texi(,14062)
13657texinfo.texi(,14063) @item --no-pointer-validate
13658texinfo.texi(,14064) @itemx --no-validate
13659texinfo.texi(,14065) @opindex --no-pointer-validate
13660texinfo.texi(,14066) @opindex --no-validate
13661texinfo.texi(,14067) @cindex Pointer validation, suppressing
13662texinfo.texi(,14068) Suppress the pointer-validation phase of @code{makeinfo}.  This can also
13663texinfo.texi(,14069) be done with the @code{@@novalidate} command (@pxref{Use TeX,,Use
13664texinfo.texi(,14070) @TeX{}}).  Normally, after a Texinfo file is processed, some consistency
13665texinfo.texi(,14071) checks are made to ensure that cross references can be resolved, etc.
13666texinfo.texi(,14072) @xref{Pointer Validation}.
13667texinfo.texi(,14073)
13668texinfo.texi(,14074) @item --no-warn
13669texinfo.texi(,14075) @opindex --no-warn
13670texinfo.texi(,14076) Suppress warning messages (but @emph{not} error messages).  You might
13671texinfo.texi(,14077) want this if the file you are creating has examples of Texinfo cross
13672texinfo.texi(,14078) references within it, and the nodes that are referenced do not actually
13673texinfo.texi(,14079) exist.
13674texinfo.texi(,14080)
13675texinfo.texi(,14081) @item --number-sections
13676texinfo.texi(,14082) @opindex --number-sections
13677texinfo.texi(,14083) Output chapter, section, and appendix numbers as in printed manuals.
13678texinfo.texi(,14084)
13679texinfo.texi(,14085) @item --no-number-footnotes
13680texinfo.texi(,14086) @opindex --no-number-footnotes
13681texinfo.texi(,14087) Suppress automatic footnote numbering.  By default, @code{makeinfo}
13682texinfo.texi(,14088) numbers each footnote sequentially in a single node, resetting the
13683texinfo.texi(,14089) current footnote number to 1 at the start of each node.
13684texinfo.texi(,14090)
13685texinfo.texi(,14091) @item --output=@var{file}
13686texinfo.texi(,14092) @itemx -o @var{file}
13687texinfo.texi(,14093) @opindex --output=@var{file}
13688texinfo.texi(,14094) @opindex -o @var{file}
13689texinfo.texi(,14095) Specify that the output should be directed to @var{file} and not to the
13690texinfo.texi(,14096) file name specified in the @code{@@setfilename} command found in the
13691texinfo.texi(,14097) Texinfo source (@pxref{setfilename}).  If @var{file} is @samp{-}, output
13692texinfo.texi(,14098) goes to standard output and @samp{--no-split} is implied.  For split
13693texinfo.texi(,14099) HTML output, @var{file} is the name for the directory into which all
13694texinfo.texi(,14100) HTML nodes are written (@pxref{makeinfo html}).
13695texinfo.texi(,14101)
13696texinfo.texi(,14102) @item -P @var{dir}
13697texinfo.texi(,14103) @opindex -P @var{dir}
13698texinfo.texi(,14104) Prepend @var{dir} to the directory search list for @code{@@include}.
13699texinfo.texi(,14105) If @var{dir} is not given, the current directory @file{.} is prepended.
13700texinfo.texi(,14106) See @samp{-I} for more details.
13701texinfo.texi(,14107)
13702texinfo.texi(,14108) @item --paragraph-indent=@var{indent}
13703texinfo.texi(,14109) @itemx -p @var{indent}
13704texinfo.texi(,14110) @opindex --paragraph-indent=@var{indent}
13705texinfo.texi(,14111) @opindex -p @var{indent}
13706texinfo.texi(,14112) Set the paragraph indentation style to @var{indent}.  The value set by
13707texinfo.texi(,14113) this option overrides the value set in a Texinfo file by an
13708texinfo.texi(,14114) @code{@@paragraphindent} command (@pxref{paragraphindent}).  The value
13709texinfo.texi(,14115) of @var{indent} is interpreted as follows:
13710texinfo.texi(,14116)
13711texinfo.texi(,14117) @table @asis
13712texinfo.texi(,14118) @item @samp{asis}
13713texinfo.texi(,14119) Preserve any existing indentation at the starts of paragraphs.
13714texinfo.texi(,14120)
13715texinfo.texi(,14121) @item @samp{0} or @samp{none}
13716texinfo.texi(,14122) Delete any existing indentation.
13717texinfo.texi(,14123)
13718texinfo.texi(,14124) @item @var{num}
13719texinfo.texi(,14125) Indent each paragraph by @var{num} spaces.
13720texinfo.texi(,14126) @end table
13721texinfo.texi(,14127)
13722texinfo.texi(,14128) @item --reference-limit=@var{limit}
13723texinfo.texi(,14129) @itemx -r @var{limit}
13724texinfo.texi(,14130) @opindex --reference-limit=@var{limit}
13725texinfo.texi(,14131) @opindex -r @var{limit}
13726texinfo.texi(,14132) Set the value of the number of references to a node that
13727texinfo.texi(,14133) @code{makeinfo} will make without reporting a warning.  If a node has more
13728texinfo.texi(,14134) than this number of references in it, @code{makeinfo} will make the
13729texinfo.texi(,14135) references but also report a warning.  The default is 1000.
13730texinfo.texi(,14136)
13731texinfo.texi(,14137) @item -U @var{var}
13732texinfo.texi(,14138) Cause @var{var} to be undefined.  This is equivalent to
13733texinfo.texi(,14139) @code{@@clear @var{var}} in the Texinfo file (@pxref{set clear value}).
13734texinfo.texi(,14140)
13735texinfo.texi(,14141) @item --verbose
13736texinfo.texi(,14142) @opindex --verbose
13737texinfo.texi(,14143) Cause @code{makeinfo} to display messages saying what it is doing.
13738texinfo.texi(,14144) Normally, @code{makeinfo} only outputs messages if there are errors or
13739texinfo.texi(,14145) warnings.
13740texinfo.texi(,14146)
13741texinfo.texi(,14147) @item --version
13742texinfo.texi(,14148) @itemx -V
13743texinfo.texi(,14149) @opindex --version
13744texinfo.texi(,14150) @opindex -V
13745texinfo.texi(,14151) Print the version number, then exit successfully.
13746texinfo.texi(,14152)
13747texinfo.texi(,14153) @item --xml
13748texinfo.texi(,14154) @opindex --xml
13749texinfo.texi(,14155) Generate XML output rather than Info.
13750texinfo.texi(,14156)
13751texinfo.texi(,14157) @end table
13752texinfo.texi(,14158)
13753texinfo.texi(,14159)
13754texinfo.texi(,14160) @node Pointer Validation
13755texinfo.texi(,14161) @subsection Pointer Validation
13756texinfo.texi(,14162) @cindex Pointer validation with @code{makeinfo}
13757texinfo.texi(,14163) @cindex Validation of pointers
13758texinfo.texi(,14164)
13759texinfo.texi(,14165) If you do not suppress pointer validation with the @samp{--no-validate}
13760texinfo.texi(,14166) option or the @code{@@novalidate} command in the source file (@pxref{Use
13761texinfo.texi(,14167) TeX,,Use @TeX{}}), @code{makeinfo} will check the validity of the final
13762texinfo.texi(,14168) Info file.  Mostly, this means ensuring that nodes you have referenced
13763texinfo.texi(,14169) really exist.  Here is a complete list of what is checked:
13764texinfo.texi(,14170)
13765texinfo.texi(,14171) @enumerate
13766texinfo.texi(,14172) @item
13767texinfo.texi(,14173) If a `Next', `Previous', or `Up' node reference is a reference to a
13768texinfo.texi(,14174) node in the current file and is not an external reference such as to
13769texinfo.texi(,14175) @file{(dir)}, then the referenced node must exist.@refill
13770texinfo.texi(,14176)
13771texinfo.texi(,14177) @item
13772texinfo.texi(,14178) In every node, if the `Previous' node is different from the `Up' node,
13773texinfo.texi(,14179) then the node pointed to by the `Previous' field must have a `Next'
13774texinfo.texi(,14180) field which points back to this node.@refill
13775texinfo.texi(,14181)
13776texinfo.texi(,14182) @item
13777texinfo.texi(,14183) Every node except the `Top' node must have an `Up' pointer.@refill
13778texinfo.texi(,14184)
13779texinfo.texi(,14185) @item
13780texinfo.texi(,14186) The node referenced by an `Up' pointer must itself reference the current
13781texinfo.texi(,14187) node through a menu item, unless the node referenced by `Up'
13782texinfo.texi(,14188) has the form `(@var{file})'.
13783texinfo.texi(,14189)
13784texinfo.texi(,14190) @item
13785texinfo.texi(,14191) If the `Next' reference of a node is not the same as the `Next' reference
13786texinfo.texi(,14192) of the `Up' reference, then the node referenced by the `Next' pointer
13787texinfo.texi(,14193) must have a `Previous' pointer that points back to the current node.
13788texinfo.texi(,14194) This rule allows the last node in a section to point to the first node
13789texinfo.texi(,14195) of the next chapter.@refill
13790texinfo.texi(,14196)
13791texinfo.texi(,14197) @item
13792texinfo.texi(,14198) Every node except `Top' should be referenced by at least one other node,
13793texinfo.texi(,14199) either via the `Previous' or `Next' links, or via a menu or a
13794texinfo.texi(,14200) cross-reference.@refill
13795texinfo.texi(,14201) @end enumerate
13796texinfo.texi(,14202)
13797texinfo.texi(,14203) @cindex @@-commands in @@node, limited support
13798texinfo.texi(,14204) Some Texinfo documents might fail during the validation phase because
13799texinfo.texi(,14205) they use commands like @code{@@value} and @code{@@definfoenclose} in
13800texinfo.texi(,14206) node definitions and cross-references inconsistently.  Consider the
13801texinfo.texi(,14207) following example:
13802texinfo.texi(,14208)
13803texinfo.texi(,14209) @example
13804texinfo.texi(,14210) @group
13805texinfo.texi(,14211) @@set nodename Node 1
13806texinfo.texi(,14212)
13807texinfo.texi(,14213) @@node @@value@{nodename@}, Node 2, Top, Top
13808texinfo.texi(,14214)
13809texinfo.texi(,14215) This is node 1.
13810texinfo.texi(,14216)
13811texinfo.texi(,14217) @@node Node 2, , Node 1, Top
13812texinfo.texi(,14218)
13813texinfo.texi(,14219) This is node 2.
13814texinfo.texi(,14220) @end group
13815texinfo.texi(,14221) @end example
13816texinfo.texi(,14222)
13817texinfo.texi(,14223) @noindent
13818texinfo.texi(,14224) Here, the node ``Node 1'' was referenced both verbatim and through
13819texinfo.texi(,14225) @code{@@value}.
13820texinfo.texi(,14226)
13821texinfo.texi(,14227) By default, @code{makeinfo} fails such cases, because node names are not
13822texinfo.texi(,14228) fully expanded until they are written to the output file.  You should
13823texinfo.texi(,14229) always try to reference nodes consistently; e.g., in the above example,
13824texinfo.texi(,14230) the second @code{@@node} line should have also used @code{@@value}.
13825texinfo.texi(,14231) However, if, for some reason, you @emph{must} reference node names
13826texinfo.texi(,14232) inconsistently, and @code{makeinfo} fails to validate the file, you can
13827texinfo.texi(,14233) use the @samp{--commands-in-node-names} option to force @code{makeinfo}
13828texinfo.texi(,14234) to perform the expensive expansion of all node names it finds in the
13829texinfo.texi(,14235) document.  This might considerably slow down the program, though;
13830texinfo.texi(,14236) twofold increase in conversion time was measured for large documents
13831texinfo.texi(,14237) such as the Jargon file.
13832texinfo.texi(,14238)
13833texinfo.texi(,14239) @cindex @@value in @@node lines
13834texinfo.texi(,14240) The support for @code{@@}-commands in @code{@@node} directives is not
13835texinfo.texi(,14241) general enough to be freely used.  For example, if the example above
13836texinfo.texi(,14242) redefined @code{nodename} somewhere in the document, @code{makeinfo}
13837texinfo.texi(,14243) will fail to convert it, even if invoked with the
13838texinfo.texi(,14244) @samp{--commands-in-node-names} option.
13839texinfo.texi(,14245)
13840texinfo.texi(,14246) @samp{--commands-in-node-names} has no effect if the @samp{--no-validate}
13841texinfo.texi(,14247) option is given.
13842texinfo.texi(,14248)
13843texinfo.texi(,14249)
13844texinfo.texi(,14250) @node makeinfo in Emacs
13845texinfo.texi(,14251) @subsection Running @code{makeinfo} inside Emacs
13846texinfo.texi(,14252) @cindex Running @code{makeinfo} in Emacs
13847texinfo.texi(,14253) @cindex @code{makeinfo} inside Emacs
13848texinfo.texi(,14254) @cindex Shell, running @code{makeinfo} in
13849texinfo.texi(,14255)
13850texinfo.texi(,14256) You can run @code{makeinfo} in GNU Emacs Texinfo mode by using either the
13851texinfo.texi(,14257) @code{makeinfo-region} or the @code{makeinfo-buffer} commands.  In
13852texinfo.texi(,14258) Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c
13853texinfo.texi(,14259) C-m C-b} by default.@refill
13854texinfo.texi(,14260)
13855texinfo.texi(,14261) @table @kbd
13856texinfo.texi(,14262) @item C-c C-m C-r
13857texinfo.texi(,14263) @itemx M-x makeinfo-region
13858texinfo.texi(,14264) Format the current region for Info.@refill
13859texinfo.texi(,14265) @findex makeinfo-region
13860texinfo.texi(,14266)
13861texinfo.texi(,14267) @item C-c C-m C-b
13862texinfo.texi(,14268) @itemx M-x makeinfo-buffer
13863texinfo.texi(,14269) Format the current buffer for Info.@refill
13864texinfo.texi(,14270) @findex makeinfo-buffer
13865texinfo.texi(,14271) @end table
13866texinfo.texi(,14272)
13867texinfo.texi(,14273) When you invoke either @code{makeinfo-region} or
13868texinfo.texi(,14274) @code{makeinfo-buffer}, Emacs prompts for a file name, offering the
13869texinfo.texi(,14275) name of the visited file as the default.  You can edit the default
13870texinfo.texi(,14276) file name in the minibuffer if you wish, before pressing @key{RET} to
13871texinfo.texi(,14277) start the @code{makeinfo} process.@refill
13872texinfo.texi(,14278)
13873texinfo.texi(,14279) The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands
13874texinfo.texi(,14280) run the @code{makeinfo} program in a temporary shell buffer.  If
13875texinfo.texi(,14281) @code{makeinfo} finds any errors, Emacs displays the error messages in
13876texinfo.texi(,14282) the temporary buffer.@refill
13877texinfo.texi(,14283)
13878texinfo.texi(,14284) @cindex Errors, parsing
13879texinfo.texi(,14285) @cindex Parsing errors
13880texinfo.texi(,14286) @findex next-error
13881texinfo.texi(,14287) You can parse the error messages by typing @kbd{C-x `}
13882texinfo.texi(,14288) (@code{next-error}).  This causes Emacs to go to and position the
13883texinfo.texi(,14289) cursor on the line in the Texinfo source that @code{makeinfo} thinks
13884texinfo.texi(,14290) caused the error.  @xref{Compilation, , Running @code{make} or
13885texinfo.texi(,14291) Compilers Generally, emacs, The GNU Emacs Manual}, for more
13886texinfo.texi(,14292) information about using the @code{next-error} command.@refill
13887texinfo.texi(,14293)
13888texinfo.texi(,14294) In addition, you can kill the shell in which the @code{makeinfo}
13889texinfo.texi(,14295) command is running or make the shell buffer display its most recent
13890texinfo.texi(,14296) output.@refill
13891texinfo.texi(,14297)
13892texinfo.texi(,14298) @table @kbd
13893texinfo.texi(,14299) @item C-c C-m C-k
13894texinfo.texi(,14300) @itemx M-x makeinfo-kill-job
13895texinfo.texi(,14301) @findex makeinfo-kill-job
13896texinfo.texi(,14302) Kill the current running @code{makeinfo} job
13897texinfo.texi(,14303) (from @code{makeinfo-region} or @code{makeinfo-buffer}).@refill
13898texinfo.texi(,14304)
13899texinfo.texi(,14305) @item C-c C-m C-l
13900texinfo.texi(,14306) @itemx M-x makeinfo-recenter-output-buffer
13901texinfo.texi(,14307) @findex makeinfo-recenter-output-buffer
13902texinfo.texi(,14308) Redisplay the @code{makeinfo} shell buffer to display its most recent
13903texinfo.texi(,14309) output.@refill
13904texinfo.texi(,14310) @end table
13905texinfo.texi(,14311)
13906texinfo.texi(,14312) @noindent
13907texinfo.texi(,14313) (Note that the parallel commands for killing and recentering a @TeX{}
13908texinfo.texi(,14314) job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}.  @xref{Texinfo Mode
13909texinfo.texi(,14315) Printing}.)@refill
13910texinfo.texi(,14316)
13911texinfo.texi(,14317) You can specify options for @code{makeinfo} by setting the
13912texinfo.texi(,14318) @code{makeinfo-options} variable with either the @kbd{M-x
13913texinfo.texi(,14319) edit-options} or the @kbd{M-x set-variable} command, or by setting the
13914texinfo.texi(,14320) variable in your @file{.emacs} initialization file.@refill
13915texinfo.texi(,14321)
13916texinfo.texi(,14322) For example, you could write the following in your @file{.emacs} file:@refill
13917texinfo.texi(,14323)
13918texinfo.texi(,14324) @example
13919texinfo.texi(,14325) @group
13920texinfo.texi(,14326) (setq makeinfo-options
13921texinfo.texi(,14327)       "--paragraph-indent=0 --no-split
13922texinfo.texi(,14328)        --fill-column=70 --verbose")
13923texinfo.texi(,14329) @end group
13924texinfo.texi(,14330) @end example
13925texinfo.texi(,14331)
13926texinfo.texi(,14332) @c If you write these three cross references using xref, you see
13927texinfo.texi(,14333) @c three references to the same named manual, which looks strange.
13928texinfo.texi(,14340) @noindent
13929texinfo.texi(,14342) For more information, see@*
13930texinfo.texi(,14343) @ref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs Manual},@*
13931texinfo.texi(,14344) @ref{Examining, , Examining and Setting Variables, emacs, The GNU Emacs Manual},@*
13932texinfo.texi(,14345) @ref{Init File, , , emacs, The GNU Emacs Manual}, and@*
13933texinfo.texi(,14346) @ref{makeinfo options, , Options for @code{makeinfo}}.
13934texinfo.texi(,14348)
13935texinfo.texi(,14349) @node texinfo-format commands
13936texinfo.texi(,14350) @comment  node-name,  next,  previous,  up
13937texinfo.texi(,14351) @subsection The @code{texinfo-format@dots{}} Commands
13938texinfo.texi(,14352) @findex texinfo-format-region
13939texinfo.texi(,14353) @findex texinfo-format-buffer
13940texinfo.texi(,14354)
13941texinfo.texi(,14355) In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
13942texinfo.texi(,14356) file with the @code{texinfo-format-region} command.  This formats the
13943texinfo.texi(,14357) current region and displays the formatted text in a temporary buffer
13944texinfo.texi(,14358) called @samp{*Info Region*}.@refill
13945texinfo.texi(,14359)
13946texinfo.texi(,14360) Similarly, you can format a buffer with the
13947texinfo.texi(,14361) @code{texinfo-format-buffer} command.  This command creates a new
13948texinfo.texi(,14362) buffer and generates the Info file in it.  Typing @kbd{C-x C-s} will
13949texinfo.texi(,14363) save the Info file under the name specified by the
13950texinfo.texi(,14364) @code{@@setfilename} line which must be near the beginning of the
13951texinfo.texi(,14365) Texinfo file.@refill
13952texinfo.texi(,14366)
13953texinfo.texi(,14367) @table @kbd
13954texinfo.texi(,14368) @item C-c C-e C-r
13955texinfo.texi(,14369) @itemx @code{texinfo-format-region}
13956texinfo.texi(,14370) Format the current region for Info.
13957texinfo.texi(,14371) @findex texinfo-format-region
13958texinfo.texi(,14372)
13959texinfo.texi(,14373) @item C-c C-e C-b
13960texinfo.texi(,14374) @itemx @code{texinfo-format-buffer}
13961texinfo.texi(,14375) Format the current buffer for Info.
13962texinfo.texi(,14376) @findex texinfo-format-buffer
13963texinfo.texi(,14377) @end table
13964texinfo.texi(,14378)
13965texinfo.texi(,14379) The @code{texinfo-format-region} and @code{texinfo-format-buffer}
13966texinfo.texi(,14380) commands provide you with some error checking, and other functions can
13967texinfo.texi(,14381) provide you with further help in finding formatting errors.  These
13968texinfo.texi(,14382) procedures are described in an appendix; see @ref{Catching Mistakes}.
13969texinfo.texi(,14383) However, the @code{makeinfo} program is often faster and
13970texinfo.texi(,14384) provides better error checking (@pxref{makeinfo in Emacs}).@refill
13971texinfo.texi(,14385)
13972texinfo.texi(,14386) @node Batch Formatting
13973texinfo.texi(,14387) @comment  node-name,  next,  previous,  up
13974texinfo.texi(,14388) @subsection Batch Formatting
13975texinfo.texi(,14389) @cindex Batch formatting for Info
13976texinfo.texi(,14390) @cindex Info batch formatting
13977texinfo.texi(,14391)
13978texinfo.texi(,14392) You can format Texinfo files for Info using @code{batch-texinfo-format}
13979texinfo.texi(,14393) and Emacs Batch mode.  You can run Emacs in Batch mode from any shell,
13980texinfo.texi(,14394) including a shell inside of Emacs.  (@xref{Command Switches, , Command
13981texinfo.texi(,14395) Line Switches and Arguments, emacs, The GNU Emacs Manual}.)@refill
13982texinfo.texi(,14396)
13983texinfo.texi(,14397) Here is a shell command to format all the files that end in
13984texinfo.texi(,14398) @file{.texinfo} in the current directory:
13985texinfo.texi(,14399)
13986texinfo.texi(,14400) @example
13987texinfo.texi(,14401) emacs -batch -funcall batch-texinfo-format *.texinfo
13988texinfo.texi(,14402) @end example
13989texinfo.texi(,14403)
13990texinfo.texi(,14404) @noindent
13991texinfo.texi(,14405) Emacs processes all the files listed on the command line, even if an
13992texinfo.texi(,14406) error occurs while attempting to format some of them.@refill
13993texinfo.texi(,14407)
13994texinfo.texi(,14408) Run @code{batch-texinfo-format} only with Emacs in Batch mode as shown;
13995texinfo.texi(,14409) it is not interactive.  It kills the Batch mode Emacs on completion.@refill
13996texinfo.texi(,14410)
13997texinfo.texi(,14411) @code{batch-texinfo-format} is convenient if you lack @code{makeinfo}
13998texinfo.texi(,14412) and want to format several Texinfo files at once.  When you use Batch
13999texinfo.texi(,14413) mode, you create a new Emacs process.  This frees your current Emacs, so
14000texinfo.texi(,14414) you can continue working in it.  (When you run
14001texinfo.texi(,14415) @code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot
14002texinfo.texi(,14416) use that Emacs for anything else until the command finishes.)@refill
14003texinfo.texi(,14417)
14004texinfo.texi(,14418) @node Tag and Split Files
14005texinfo.texi(,14419) @comment  node-name,  next,  previous,  up
14006texinfo.texi(,14420) @subsection Tag Files and Split Files
14007texinfo.texi(,14421) @cindex Making a tag table automatically
14008texinfo.texi(,14422) @cindex Tag table, making automatically
14009texinfo.texi(,14423)
14010texinfo.texi(,14424) If a Texinfo file has more than 30,000 bytes,
14011texinfo.texi(,14425) @code{texinfo-format-buffer} automatically creates a tag table
14012texinfo.texi(,14426) for its Info file;  @code{makeinfo} always creates a tag table.  With
14013texinfo.texi(,14427) a @dfn{tag table}, Info can jump to new nodes more quickly than it can
14014texinfo.texi(,14428) otherwise.@refill
14015texinfo.texi(,14429)
14016texinfo.texi(,14430) @cindex Indirect subfiles
14017texinfo.texi(,14431) In addition, if the Texinfo file contains more than about 70,000
14018texinfo.texi(,14432) bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the
14019texinfo.texi(,14433) large Info file into shorter @dfn{indirect} subfiles of about 50,000
14020texinfo.texi(,14434) bytes each.  Big files are split into smaller files so that Emacs does
14021texinfo.texi(,14435) not need to make a large buffer to hold the whole of a large Info
14022texinfo.texi(,14436) file; instead, Emacs allocates just enough memory for the small, split-off
14023texinfo.texi(,14437) file that is needed at the time.  This way, Emacs avoids wasting
14024texinfo.texi(,14438) memory when you run Info.  (Before splitting was implemented, Info
14025texinfo.texi(,14439) files were always kept short and @dfn{include files} were designed as
14026texinfo.texi(,14440) a way to create a single, large printed manual out of the smaller Info
14027texinfo.texi(,14441) files.  @xref{Include Files}, for more information.  Include files are
14028texinfo.texi(,14442) still used for very large documents, such as @cite{The Emacs Lisp
14029texinfo.texi(,14443) Reference Manual}, in which each chapter is a separate file.)@refill
14030texinfo.texi(,14444)
14031texinfo.texi(,14445) When a file is split, Info itself makes use of a shortened version of
14032texinfo.texi(,14446) the original file that contains just the tag table and references to
14033texinfo.texi(,14447) the files that were split off.  The split-off files are called
14034texinfo.texi(,14448) @dfn{indirect} files.@refill
14035texinfo.texi(,14449)
14036texinfo.texi(,14450) The split-off files have names that are created by appending @w{@samp{-1}},
14037texinfo.texi(,14451) @w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the
14038texinfo.texi(,14452) @code{@@setfilename} command.  The shortened version of the original file
14039texinfo.texi(,14453) continues to have the name specified by @code{@@setfilename}.@refill
14040texinfo.texi(,14454)
14041texinfo.texi(,14455) At one stage in writing this document, for example, the Info file was saved
14042texinfo.texi(,14456) as the file @file{test-texinfo} and that file looked like this:@refill
14043texinfo.texi(,14457)
14044texinfo.texi(,14458) @example
14045texinfo.texi(,14459) @group
14046texinfo.texi(,14460) Info file: test-texinfo,    -*-Text-*-
14047texinfo.texi(,14461) produced by texinfo-format-buffer
14048texinfo.texi(,14462) from file: new-texinfo-manual.texinfo
14049texinfo.texi(,14463)
14050texinfo.texi(,14464) ^_
14051texinfo.texi(,14465) Indirect:
14052texinfo.texi(,14466) test-texinfo-1: 102
14053texinfo.texi(,14467) test-texinfo-2: 50422
14054texinfo.texi(,14468) @end group
14055texinfo.texi(,14469) @group
14056texinfo.texi(,14470) test-texinfo-3: 101300
14057texinfo.texi(,14471) ^_^L
14058texinfo.texi(,14472) Tag table:
14059texinfo.texi(,14473) (Indirect)
14060texinfo.texi(,14474) Node: overview^?104
14061texinfo.texi(,14475) Node: info file^?1271
14062texinfo.texi(,14476) @end group
14063texinfo.texi(,14477) @group
14064texinfo.texi(,14478) Node: printed manual^?4853
14065texinfo.texi(,14479) Node: conventions^?6855
14066texinfo.texi(,14480) @dots{}
14067texinfo.texi(,14481) @end group
14068texinfo.texi(,14482) @end example
14069texinfo.texi(,14483)
14070texinfo.texi(,14484) @noindent
14071texinfo.texi(,14485) (But @file{test-texinfo} had far more nodes than are shown here.)  Each of
14072texinfo.texi(,14486) the split-off, indirect files, @file{test-texinfo-1},
14073texinfo.texi(,14487) @file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file
14074texinfo.texi(,14488) after the line that says @samp{Indirect:}.  The tag table is listed after
14075texinfo.texi(,14489) the line that says @samp{Tag table:}. @refill
14076texinfo.texi(,14490)
14077texinfo.texi(,14491) In the list of indirect files, the number following the file name
14078texinfo.texi(,14492) records the cumulative number of bytes in the preceding indirect files,
14079texinfo.texi(,14493) not counting the file list itself, the tag table, or the permissions
14080texinfo.texi(,14494) text in each file.  In the tag table, the number following the node name
14081texinfo.texi(,14495) records the location of the beginning of the node, in bytes from the
14082texinfo.texi(,14496) beginning of the (unsplit) output.
14083texinfo.texi(,14497)
14084texinfo.texi(,14498) If you are using @code{texinfo-format-buffer} to create Info files,
14085texinfo.texi(,14499) you may want to run the @code{Info-validate} command.  (The
14086texinfo.texi(,14500) @code{makeinfo} command does such a good job on its own, you do not
14087texinfo.texi(,14501) need @code{Info-validate}.)  However, you cannot run the @kbd{M-x
14088texinfo.texi(,14502) Info-validate} node-checking command on indirect files.  For
14089texinfo.texi(,14503) information on how to prevent files from being split and how to
14090texinfo.texi(,14504) validate the structure of the nodes, see @ref{Using
14091texinfo.texi(,14505) Info-validate}.@refill
14092texinfo.texi(,14506)
14093texinfo.texi(,14507)
14094texinfo.texi(,14508) @node makeinfo html
14095texinfo.texi(,14509) @subsection Generating HTML
14096texinfo.texi(,14510) @cindex HTML
14097texinfo.texi(,14511)
14098texinfo.texi(,14512) Besides generating output in the Info format, you can use the
14099texinfo.texi(,14513) @samp{--html} option to generate output in HTML format, for installation
14100texinfo.texi(,14514) on a web site (for example).  By default, the HTML output is split at
14101texinfo.texi(,14515) node level.
14102texinfo.texi(,14516)
14103texinfo.texi(,14517) When splitting, the HTML output files are written into a subdirectory.
14104texinfo.texi(,14518) The subdirectory is named according to the name from
14105texinfo.texi(,14519) @code{@@setfilename} with any extension removed; for example, HTML
14106texinfo.texi(,14520) output for @code{@@setfilename emacs.info} would be written into a
14107texinfo.texi(,14521) subdirectory named @samp{emacs}.  If that directory cannot be created
14108texinfo.texi(,14522) for any reason, then @samp{.html} is appended to the directory name, as
14109texinfo.texi(,14523) in @samp{emacs.html} (this is necessary because sometimes the info file
14110texinfo.texi(,14524) is named without an extension, e.g., @samp{texinfo}).  If the
14111texinfo.texi(,14525) @samp{@var{name}.html} directory can't be created either,
14112texinfo.texi(,14526) @code{makeinfo} gives up.  In any case, the top-level output file within
14113texinfo.texi(,14527) the directory is always named @samp{index.html}.
14114texinfo.texi(,14528)
14115texinfo.texi(,14529) Monolithic output (@code{--no-split}) is named according to
14116texinfo.texi(,14530) @code{@@setfilename} or @code{--outfile}.  Cross-document node
14117texinfo.texi(,14531) references are not supported in monolithic HTML.
14118texinfo.texi(,14532)
14119texinfo.texi(,14533) Texinfo input marked up with the @code{@@ifhtml} command will produce
14120texinfo.texi(,14534) output only with the @samp{--html} option supplied.  Input marked up
14121texinfo.texi(,14535) with the @code{@@html} is passed literally to the output (suppressing
14122texinfo.texi(,14536) the normal escaping of input @samp{<}, @samp{>} and @samp{&} characters
14123texinfo.texi(,14537) which have special significance in HTML).
14124texinfo.texi(,14538)
14125texinfo.texi(,14539) The @samp{--footnote-style} option is currently ignored for HTML output;
14126texinfo.texi(,14540) footnotes are linked to the end of the output file.
14127texinfo.texi(,14541)
14128texinfo.texi(,14542) The HTML generated is mostly standard (i.e., HTML 2.0, RFC-1866).  The
14129texinfo.texi(,14543) exception is that HTML 3.2 tables are generated from the
14130texinfo.texi(,14544) @code{@@multitable} command, but tagged to degrade as well as possible
14131texinfo.texi(,14545) in browsers without table support.  The HTML 4 @samp{lang} attribute on
14132texinfo.texi(,14546) the @samp{<html>} attribute is also used.  Please report output from an
14133texinfo.texi(,14547) error-free run of @code{makeinfo} which has browser portability problems
14134texinfo.texi(,14548) as a bug.
14135texinfo.texi(,14549)
14136texinfo.texi(,14550) Navigation bars are inserted at the start of nodes, similarly to Info
14137texinfo.texi(,14551) output.  The @samp{--no-headers} option will suppress this if used with
14138texinfo.texi(,14552) @samp{--no-split}.  Header @code{<link>} elements in split output can
14139texinfo.texi(,14553) support info-like navigation with browsers like Lynx and @w{Emacs W3}
14140texinfo.texi(,14554) which implement this @w{HTML 1.0} feature.  @samp{@@xref} commands to
14141texinfo.texi(,14555) other documents are generated assuming the other document is available
14142texinfo.texi(,14556) in split HTML form, and installed in the same HTML documentation tree,
14143texinfo.texi(,14557) at @file{../<info-document>/}.
14144texinfo.texi(,14558)
14145texinfo.texi(,14559)
14146texinfo.texi(,14560) @node Installing an Info File
14147texinfo.texi(,14561) @section Installing an Info File
14148texinfo.texi(,14562) @cindex Installing an Info file
14149texinfo.texi(,14563) @cindex Info file installation
14150texinfo.texi(,14564) @cindex @file{dir} directory for Info installation
14151texinfo.texi(,14565)
14152texinfo.texi(,14566) Info files are usually kept in the @file{info} directory.  You can read
14153texinfo.texi(,14567) Info files using the standalone Info program or the Info reader built
14154texinfo.texi(,14568) into Emacs.  (@inforef{Top, info, info}, for an introduction to Info.)
14155texinfo.texi(,14569)
14156texinfo.texi(,14570) @menu
14157texinfo.texi(,14571) * Directory File::              The top level menu for all Info files.
14158texinfo.texi(,14572) * New Info File::               Listing a new Info file.
14159texinfo.texi(,14573) * Other Info Directories::      How to specify Info files that are
14160texinfo.texi(,14574)                                   located in other directories.
14161texinfo.texi(,14575) * Installing Dir Entries::      How to specify what menu entry to add
14162texinfo.texi(,14576)                                   to the Info directory.
14163texinfo.texi(,14577) * Invoking install-info::       @code{install-info} options.
14164texinfo.texi(,14578) @end menu
14165texinfo.texi(,14579)
14166texinfo.texi(,14580)
14167texinfo.texi(,14581) @node Directory File
14168texinfo.texi(,14582) @subsection The Directory File @file{dir}
14169texinfo.texi(,14583)
14170texinfo.texi(,14584) For Info to work, the @file{info} directory must contain a file that
14171texinfo.texi(,14585) serves as a top level directory for the Info system.  By convention,
14172texinfo.texi(,14586) this file is called @file{dir}.  (You can find the location of this file
14173texinfo.texi(,14587) within Emacs by typing @kbd{C-h i} to enter Info and then typing
14174texinfo.texi(,14588) @kbd{C-x C-f} to see the pathname to the @file{info} directory.)
14175texinfo.texi(,14589)
14176texinfo.texi(,14590) The @file{dir} file is itself an Info file.  It contains the top level
14177texinfo.texi(,14591) menu for all the Info files in the system.  The menu looks like
14178texinfo.texi(,14592) this:@refill
14179texinfo.texi(,14593)
14180texinfo.texi(,14594) @example
14181texinfo.texi(,14595) @group
14182texinfo.texi(,14596) * Menu:
14183texinfo.texi(,14597) * Info:    (info).     Documentation browsing system.
14184texinfo.texi(,14598) * Emacs:   (emacs).    The extensible, self-documenting
14185texinfo.texi(,14599)                        text editor.
14186texinfo.texi(,14600) * Texinfo: (texinfo).  With one source file, make
14187texinfo.texi(,14601)                        either a printed manual using
14188texinfo.texi(,14602)                        @@TeX@{@} or an Info file.
14189texinfo.texi(,14603) @dots{}
14190texinfo.texi(,14604) @end group
14191texinfo.texi(,14605) @end example
14192texinfo.texi(,14606)
14193texinfo.texi(,14607) Each of these menu entries points to the `Top' node of the Info file
14194texinfo.texi(,14608) that is named in parentheses.  (The menu entry does not need to
14195texinfo.texi(,14609) specify the `Top' node, since Info goes to the `Top' node if no node
14196texinfo.texi(,14610) name is mentioned.  @xref{Other Info Files, , Nodes in Other Info
14197texinfo.texi(,14611) Files}.)@refill
14198texinfo.texi(,14612)
14199texinfo.texi(,14613) Thus, the @samp{Info} entry points to the `Top' node of the
14200texinfo.texi(,14614) @file{info} file and the @samp{Emacs} entry points to the `Top' node
14201texinfo.texi(,14615) of the @file{emacs} file.@refill
14202texinfo.texi(,14616)
14203texinfo.texi(,14617) In each of the Info files, the `Up' pointer of the `Top' node refers
14204texinfo.texi(,14618) back to the @code{dir} file.  For example, the line for the `Top'
14205texinfo.texi(,14619) node of the Emacs manual looks like this in Info:@refill
14206texinfo.texi(,14620)
14207texinfo.texi(,14621) @example
14208texinfo.texi(,14622) File: emacs  Node: Top, Up: (DIR), Next: Distrib
14209texinfo.texi(,14623) @end example
14210texinfo.texi(,14624)
14211texinfo.texi(,14625) @noindent
14212texinfo.texi(,14626) In this case, the @file{dir} file name is written in upper case
14213texinfo.texi(,14627) letters---it can be written in either upper or lower case.  This is not
14214texinfo.texi(,14628) true in general, it is a special case for @file{dir}.
14215texinfo.texi(,14629)
14216texinfo.texi(,14630)
14217texinfo.texi(,14631) @node New Info File
14218texinfo.texi(,14632) @subsection Listing a New Info File
14219texinfo.texi(,14633) @cindex Adding a new Info file
14220texinfo.texi(,14634) @cindex Listing a new Info file
14221texinfo.texi(,14635) @cindex New Info file, listing it in @file{dir} file
14222texinfo.texi(,14636) @cindex Info file, listing a new
14223texinfo.texi(,14637) @cindex @file{dir} file listing
14224texinfo.texi(,14638)
14225texinfo.texi(,14639) To add a new Info file to your system, you must write a menu entry to
14226texinfo.texi(,14640) add to the menu in the @file{dir} file in the @file{info} directory.
14227texinfo.texi(,14641) For example, if you were adding documentation for GDB, you would write
14228texinfo.texi(,14642) the following new entry:@refill
14229texinfo.texi(,14643)
14230texinfo.texi(,14644) @example
14231texinfo.texi(,14645) * GDB: (gdb).           The source-level C debugger.
14232texinfo.texi(,14646) @end example
14233texinfo.texi(,14647)
14234texinfo.texi(,14648) @noindent
14235texinfo.texi(,14649) The first part of the menu entry is the menu entry name, followed by a
14236texinfo.texi(,14650) colon.  The second part is the name of the Info file, in parentheses,
14237texinfo.texi(,14651) followed by a period.  The third part is the description.
14238texinfo.texi(,14652)
14239texinfo.texi(,14653) The name of an Info file often has a @file{.info} extension.  Thus, the
14240texinfo.texi(,14654) Info file for GDB might be called either @file{gdb} or @file{gdb.info}.
14241texinfo.texi(,14655) The Info reader programs automatically try the file name both with and
14242texinfo.texi(,14656) without @file{.info}@footnote{On MS-DOS/MS-Windows systems, Info will
14243texinfo.texi(,14657) try the @file{.inf} extension as well.}; so it is better to avoid
14244texinfo.texi(,14658) clutter and not to write @samp{.info} explicitly in the menu entry.  For
14245texinfo.texi(,14659) example, the GDB menu entry should use just @samp{gdb} for the file
14246texinfo.texi(,14660) name, not @samp{gdb.info}.
14247texinfo.texi(,14661)
14248texinfo.texi(,14662)
14249texinfo.texi(,14663) @node Other Info Directories
14250texinfo.texi(,14664) @subsection Info Files in Other Directories
14251texinfo.texi(,14665) @cindex Installing Info in another directory
14252texinfo.texi(,14666) @cindex Info installed in another directory
14253texinfo.texi(,14667) @cindex Another Info directory
14254texinfo.texi(,14668) @cindex @file{dir} files and Info directories
14255texinfo.texi(,14669)
14256texinfo.texi(,14670) If an Info file is not in the @file{info} directory, there are three
14257texinfo.texi(,14671) ways to specify its location:@refill
14258texinfo.texi(,14672)
14259texinfo.texi(,14673) @enumerate
14260texinfo.texi(,14674) @item
14261texinfo.texi(,14675) Write the pathname in the @file{dir} file as the second part of the menu.
14262texinfo.texi(,14676)
14263texinfo.texi(,14677) @item
14264texinfo.texi(,14678) If you are using Emacs, list the name of the file in a second @file{dir}
14265texinfo.texi(,14679) file, in its directory; and then add the name of that directory to the
14266texinfo.texi(,14680) @code{Info-directory-list} variable in your personal or site
14267texinfo.texi(,14681) initialization file.
14268texinfo.texi(,14682)
14269texinfo.texi(,14683) This variable tells Emacs where to look for @file{dir} files (the files
14270texinfo.texi(,14684) must be named @file{dir}).  Emacs merges the files named @file{dir} from
14271texinfo.texi(,14685) each of the listed directories.  (In Emacs version 18, you can set the
14272texinfo.texi(,14686) @code{Info-directory} variable to the name of only one
14273texinfo.texi(,14687) directory.)@refill
14274texinfo.texi(,14688)
14275texinfo.texi(,14689) @item
14276texinfo.texi(,14690) Specify the Info directory name in the @code{INFOPATH} environment
14277texinfo.texi(,14691) variable in your @file{.profile} or @file{.cshrc} initialization file.
14278texinfo.texi(,14692) (Only you and others who set this environment variable will be able to
14279texinfo.texi(,14693) find Info files whose location is specified this way.)
14280texinfo.texi(,14694) @end enumerate
14281texinfo.texi(,14695)
14282texinfo.texi(,14696) For example, to reach a test file in the @file{/home/bob/info}
14283texinfo.texi(,14697) directory, you could add an entry like this to the menu in the
14284texinfo.texi(,14698) standard @file{dir} file:@refill
14285texinfo.texi(,14699)
14286texinfo.texi(,14700) @example
14287texinfo.texi(,14701) * Test: (/home/bob/info/info-test).  Bob's own test file.
14288texinfo.texi(,14702) @end example
14289texinfo.texi(,14703)
14290texinfo.texi(,14704) @noindent
14291texinfo.texi(,14705) In this case, the absolute file name of the @file{info-test} file is
14292texinfo.texi(,14706) written as the second part of the menu entry.@refill
14293texinfo.texi(,14707)
14294texinfo.texi(,14708) Alternatively, you could write the following in your @file{.emacs} file:
14295texinfo.texi(,14709)
14296texinfo.texi(,14710) @vindex Info-directory-list
14297texinfo.texi(,14711) @example
14298texinfo.texi(,14712) @group
14299texinfo.texi(,14713) (require 'info)
14300texinfo.texi(,14714) (setq Info-directory-list
14301texinfo.texi(,14715)   (cons (expand-file-name "/home/bob/info")
14302texinfo.texi(,14716)         Info-directory-list))
14303texinfo.texi(,14717) @end group
14304texinfo.texi(,14718) @end example
14305texinfo.texi(,14719)
14306texinfo.texi(,14720) This tells Emacs to merge the system @file{dir} file with the @file{dir}
14307texinfo.texi(,14721) file in @file{/home/bob/info}.  Thus, Info will list the
14308texinfo.texi(,14722) @file{/home/bob/info/info-test} file as a menu entry in the
14309texinfo.texi(,14723) @file{/home/bob/info/dir} file.  Emacs does the merging only when
14310texinfo.texi(,14724) @kbd{M-x info} is first run, so if you want to set
14311texinfo.texi(,14725) @code{Info-directory-list} in an Emacs session where you've already run
14312texinfo.texi(,14726) @code{info}, you must @code{(setq Info-dir-contents nil)} to force Emacs
14313texinfo.texi(,14727) to recompose the @file{dir} file.
14314texinfo.texi(,14728)
14315texinfo.texi(,14729) @vindex INFOPATH
14316texinfo.texi(,14730) Finally, you can tell Info where to look by setting the @code{INFOPATH}
14317texinfo.texi(,14731) environment variable in your shell startup file, such as @file{.cshrc},
14318texinfo.texi(,14732) @file{.profile} or @file{autoexec.bat}.  If you use a Bourne-compatible
14319texinfo.texi(,14733) shell such as @code{sh} or @code{bash} for your shell command
14320texinfo.texi(,14734) interpreter, you set the @code{INFOPATH} environment variable in the
14321texinfo.texi(,14735) @file{.profile} initialization file; but if you use @code{csh} or
14322texinfo.texi(,14736) @code{tcsh}, you set the variable in the @file{.cshrc} initialization
14323texinfo.texi(,14737) file.  On MS-DOS/MS-Windows systems, you must set @code{INFOPATH} in
14324texinfo.texi(,14738) your @file{autoexec.bat} file or in the Registry.  Each type of shell
14325texinfo.texi(,14739) uses a different syntax.
14326texinfo.texi(,14740)
14327texinfo.texi(,14741) @itemize @bullet
14328texinfo.texi(,14742) @item
14329texinfo.texi(,14743) In a @file{.cshrc} file, you could set the @code{INFOPATH}
14330texinfo.texi(,14744) variable as follows:@refill
14331texinfo.texi(,14745)
14332texinfo.texi(,14746) @smallexample
14333texinfo.texi(,14747) setenv INFOPATH .:~/info:/usr/local/emacs/info
14334texinfo.texi(,14748) @end smallexample
14335texinfo.texi(,14749)
14336texinfo.texi(,14750) @item
14337texinfo.texi(,14751) In a @file{.profile} file, you would achieve the same effect by
14338texinfo.texi(,14752) writing:@refill
14339texinfo.texi(,14753)
14340texinfo.texi(,14754) @smallexample
14341texinfo.texi(,14755) INFOPATH=.:$HOME/info:/usr/local/emacs/info
14342texinfo.texi(,14756) export INFOPATH
14343texinfo.texi(,14757) @end smallexample
14344texinfo.texi(,14758)
14345texinfo.texi(,14759) @item
14346texinfo.texi(,14760) @pindex autoexec.bat
14347texinfo.texi(,14761) In a @file{autoexec.bat} file, you write this command@footnote{Note the
14348texinfo.texi(,14762) use of @samp{;} as the directory separator, and a different syntax for
14349texinfo.texi(,14763) using values of other environment variables.}:
14350texinfo.texi(,14764)
14351texinfo.texi(,14765) @smallexample
14352texinfo.texi(,14766) set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info
14353texinfo.texi(,14767) @end smallexample
14354texinfo.texi(,14768) @end itemize
14355texinfo.texi(,14769)
14356texinfo.texi(,14770) @noindent
14357texinfo.texi(,14771) The @samp{.} indicates the current directory as usual.  Emacs uses the
14358texinfo.texi(,14772) @code{INFOPATH} environment variable to initialize the value of Emacs's
14359texinfo.texi(,14773) own @code{Info-directory-list} variable.  The stand-alone Info reader
14360texinfo.texi(,14774) merges any files named @file{dir} in any directory listed in the
14361texinfo.texi(,14775) @env{INFOPATH} variable into a single menu presented to you in the node
14362texinfo.texi(,14776) called @samp{(dir)Top}.
14363texinfo.texi(,14777)
14364texinfo.texi(,14778) @cindex colon, last in @env{INFOPATH}
14365texinfo.texi(,14779) However you set @env{INFOPATH}, if its last character is a
14366texinfo.texi(,14780) colon@footnote{On MS-DOS/MS-Windows systems, use semi-colon instead.}, this
14367texinfo.texi(,14781) is replaced by the default (compiled-in) path.  This gives you a way to
14368texinfo.texi(,14782) augment the default path with new directories without having to list all
14369texinfo.texi(,14783) the standard places.  For example (using @code{sh} syntax):
14370texinfo.texi(,14784)
14371texinfo.texi(,14785) @example
14372texinfo.texi(,14786) INFOPATH=/local/info:
14373texinfo.texi(,14787) export INFOPATH
14374texinfo.texi(,14788) @end example
14375texinfo.texi(,14789)
14376texinfo.texi(,14790) @noindent
14377texinfo.texi(,14791) will search @file{/local/info} first, then the standard directories.
14378texinfo.texi(,14792) Leading or doubled colons are not treated specially.
14379texinfo.texi(,14793)
14380texinfo.texi(,14794) @cindex @file{dir} file, creating your own
14381texinfo.texi(,14795) When you create your own @file{dir} file for use with
14382texinfo.texi(,14796) @code{Info-directory-list} or @env{INFOPATH}, it's easiest to start by
14383texinfo.texi(,14797) copying an existing @file{dir} file and replace all the text after the
14384texinfo.texi(,14798) @samp{* Menu:} with your desired entries.  That way, the punctuation and
14385texinfo.texi(,14799) special CTRL-_ characters that Info needs will be present.
14386texinfo.texi(,14800)
14387texinfo.texi(,14801)
14388texinfo.texi(,14802) @node Installing Dir Entries
14389texinfo.texi(,14803) @subsection Installing Info Directory Files
14390texinfo.texi(,14804)
14391texinfo.texi(,14805) When you install an Info file onto your system, you can use the program
14392texinfo.texi(,14806) @code{install-info} to update the Info directory file @file{dir}.
14393texinfo.texi(,14807) Normally the makefile for the package runs @code{install-info}, just
14394texinfo.texi(,14808) after copying the Info file into its proper installed location.
14395texinfo.texi(,14809)
14396texinfo.texi(,14810) @findex dircategory
14397texinfo.texi(,14811) @findex direntry
14398texinfo.texi(,14812) In order for the Info file to work with @code{install-info}, you include
14399texinfo.texi(,14813) the commands @code{@@dircategory} and
14400texinfo.texi(,14814) @code{@@direntry}@dots{}@code{@@end direntry} in the Texinfo source
14401texinfo.texi(,14815) file.  Use @code{@@direntry} to specify the menu entries to add to the
14402texinfo.texi(,14816) Info directory file, and use @code{@@dircategory} to specify which part
14403texinfo.texi(,14817) of the Info directory to put it in.  Here is how these commands are used
14404texinfo.texi(,14818) in this manual:
14405texinfo.texi(,14819)
14406texinfo.texi(,14820) @smallexample
14407texinfo.texi(,14821) @@dircategory Texinfo documentation system
14408texinfo.texi(,14822) @@direntry
14409texinfo.texi(,14823) * Texinfo: (texinfo).           The GNU documentation format.
14410texinfo.texi(,14824) * install-info: (texinfo)Invoking install-info. @dots{}
14411texinfo.texi(,14825) @dots{}
14412texinfo.texi(,14826) @@end direntry
14413texinfo.texi(,14827) @end smallexample
14414texinfo.texi(,14828)
14415texinfo.texi(,14829) Here's what this produces in the Info file:
14416texinfo.texi(,14830)
14417texinfo.texi(,14831) @smallexample
14418texinfo.texi(,14832) INFO-DIR-SECTION Texinfo documentation system
14419texinfo.texi(,14833) START-INFO-DIR-ENTRY
14420texinfo.texi(,14834) * Texinfo: (texinfo).           The GNU documentation format.
14421texinfo.texi(,14835) * install-info: (texinfo)Invoking install-info. @dots{}
14422texinfo.texi(,14836) @dots{}
14423texinfo.texi(,14837) END-INFO-DIR-ENTRY
14424texinfo.texi(,14838) @end smallexample
14425texinfo.texi(,14839)
14426texinfo.texi(,14840) @noindent
14427texinfo.texi(,14841) The @code{install-info} program sees these lines in the Info file, and
14428texinfo.texi(,14842) that is how it knows what to do.
14429texinfo.texi(,14843)
14430texinfo.texi(,14844) Always use the @code{@@direntry} and @code{@@dircategory} commands near
14431texinfo.texi(,14845) the beginning of the Texinfo input, before the first @code{@@node}
14432texinfo.texi(,14846) command.  If you use them later on in the input, @code{install-info}
14433texinfo.texi(,14847) will not notice them.
14434texinfo.texi(,14848)
14435texinfo.texi(,14849) If you use @code{@@dircategory} more than once in the Texinfo source,
14436texinfo.texi(,14850) each usage specifies the `current' category; any subsequent
14437texinfo.texi(,14851) @code{@@direntry} commands will add to that category.
14438texinfo.texi(,14852)
14439texinfo.texi(,14853) Here are some recommended @code{@@dircategory} categories:
14440texinfo.texi(,14854)
14441texinfo.texi(,14855) @display
14442texinfo.texi(,14856) GNU packages
14443texinfo.texi(,14857) GNU programming tools
14444texinfo.texi(,14858) GNU programming documentation
14445texinfo.texi(,14859) GNU Emacs Lisp
14446texinfo.texi(,14860) GNU libraries
14447texinfo.texi(,14861) TeX
14448texinfo.texi(,14862) Individual utilities
14449texinfo.texi(,14863) @end display
14450texinfo.texi(,14864)
14451texinfo.texi(,14865) The idea is to include the `Invoking' node for every program installed
14452texinfo.texi(,14866) by a package under `Individual utilities', and an entry for the manual
14453texinfo.texi(,14867) as a whole in the appropriate other category.
14454texinfo.texi(,14868)
14455texinfo.texi(,14869)
14456texinfo.texi(,14870) @node Invoking install-info
14457texinfo.texi(,14871) @subsection Invoking install-info
14458texinfo.texi(,14872)
14459texinfo.texi(,14873) @pindex install-info
14460texinfo.texi(,14874)
14461texinfo.texi(,14875) @code{install-info} inserts menu entries from an Info file into the
14462texinfo.texi(,14876) top-level @file{dir} file in the Info system (see the previous sections
14463texinfo.texi(,14877) for an explanation of how the @file{dir} file works).  It's most often
14464texinfo.texi(,14878) run as part of software installation, or when constructing a @file{dir} file
14465texinfo.texi(,14879) for all manuals on a system.  Synopsis:
14466texinfo.texi(,14880)
14467texinfo.texi(,14881) @example
14468texinfo.texi(,14882) install-info [@var{option}]@dots{} [@var{info-file} [@var{dir-file}]]
14469texinfo.texi(,14883) @end example
14470texinfo.texi(,14884)
14471texinfo.texi(,14885) If @var{info-file} or @var{dir-file} are not specified, the options
14472texinfo.texi(,14886) (described below) that define them must be.  There are no compile-time
14473texinfo.texi(,14887) defaults, and standard input is never used.  @code{install-info} can
14474texinfo.texi(,14888) read only one Info file and write only one @file{dir} file per invocation.
14475texinfo.texi(,14889)
14476texinfo.texi(,14890) @cindex @file{dir}, created by @code{install-info}
14477texinfo.texi(,14891) If @var{dir-file} (however specified) does not exist,
14478texinfo.texi(,14892) @code{install-info} creates it if possible (with no entries).
14479texinfo.texi(,14893)
14480texinfo.texi(,14894) @cindex Compressed files, reading
14481texinfo.texi(,14895) @cindex Dir files, compressed
14482texinfo.texi(,14896) If any input file is compressed with @code{gzip} (@pxref{Invoking
14483texinfo.texi(,14897) gzip,,,gzip, Gzip}), @code{install-info} automatically uncompresses it
14484texinfo.texi(,14898) for reading.  And if @var{dir-file} is compressed, @code{install-info}
14485texinfo.texi(,14899) also automatically leaves it compressed after writing any changes.
14486texinfo.texi(,14900) If @var{dir-file} itself does not exist, @code{install-info} tries to
14487texinfo.texi(,14901) open @file{@var{dir-file}.gz}.
14488texinfo.texi(,14902)
14489texinfo.texi(,14903) Options:
14490texinfo.texi(,14904)
14491texinfo.texi(,14905) @table @code
14492texinfo.texi(,14906) @item --delete
14493texinfo.texi(,14907) @opindex --delete
14494texinfo.texi(,14908) Delete the entries in @var{info-file} from @var{dir-file}.  The file
14495texinfo.texi(,14909) name in the entry in @var{dir-file} must be @var{info-file} (except for
14496texinfo.texi(,14910) an optional @samp{.info} in either one).  Don't insert any new entries.
14497texinfo.texi(,14911)
14498texinfo.texi(,14912) @item --dir-file=@var{name}
14499texinfo.texi(,14913) @itemx -d @var{name}
14500texinfo.texi(,14914) @opindex --dir-file=@var{name}
14501texinfo.texi(,14915) @opindex -d @var{name}
14502texinfo.texi(,14916) Specify file name of the Info directory file.  This is equivalent to
14503texinfo.texi(,14917) using the @var{dir-file} argument.
14504texinfo.texi(,14918)
14505texinfo.texi(,14919) @item --entry=@var{text}
14506texinfo.texi(,14920) @itemx -e @var{text}
14507texinfo.texi(,14921) @opindex --entry=@var{text}
14508texinfo.texi(,14922) @opindex -e @var{text}
14509texinfo.texi(,14923) Insert @var{text} as an Info directory entry; @var{text} should have the
14510texinfo.texi(,14924) form of an Info menu item line plus zero or more extra lines starting
14511texinfo.texi(,14925) with whitespace.  If you specify more than one entry, they are all
14512texinfo.texi(,14926) added.  If you don't specify any entries, they are determined from
14513texinfo.texi(,14927) information in the Info file itself.
14514texinfo.texi(,14928)
14515texinfo.texi(,14929) @item --help
14516texinfo.texi(,14930) @itemx -h
14517texinfo.texi(,14931) @opindex --help
14518texinfo.texi(,14932) @opindex -h
14519texinfo.texi(,14933) Display a usage message listing basic usage and all available options,
14520texinfo.texi(,14934) then exit successfully.
14521texinfo.texi(,14935)
14522texinfo.texi(,14936) @item --info-file=@var{file}
14523texinfo.texi(,14937) @itemx -i @var{file}
14524texinfo.texi(,14938) @opindex --info-file=@var{file}
14525texinfo.texi(,14939) @opindex -i @var{file}
14526texinfo.texi(,14940) Specify Info file to install in the directory.
14527texinfo.texi(,14941) Equivalent to using the @var{info-file} argument.
14528texinfo.texi(,14942)
14529texinfo.texi(,14943) @item --info-dir=@var{dir}
14530texinfo.texi(,14944) @itemx -D @var{dir}
14531texinfo.texi(,14945) @opindex --info-dir=@var{dir}
14532texinfo.texi(,14946) @opindex -D @var{dir}
14533texinfo.texi(,14947) Specify the directory where @file{dir} resides.
14534texinfo.texi(,14948) Equivalent to @samp{--dir-file=@var{dir}/dir}.
14535texinfo.texi(,14949)
14536texinfo.texi(,14950) @item --item=@var{text}
14537texinfo.texi(,14951) @opindex --item=@var{text}
14538texinfo.texi(,14952) Same as @samp{--entry=@var{text}}.  An Info directory entry is actually
14539texinfo.texi(,14953) a menu item.
14540texinfo.texi(,14954)
14541texinfo.texi(,14955) @item --quiet
14542texinfo.texi(,14956) @opindex --quiet
14543texinfo.texi(,14957) Suppress warnings.
14544texinfo.texi(,14958)
14545texinfo.texi(,14959) @item --remove
14546texinfo.texi(,14960) @itemx -r
14547texinfo.texi(,14961) @opindex --remove
14548texinfo.texi(,14962) @opindex -r
14549texinfo.texi(,14963) Same as @samp{--delete}.
14550texinfo.texi(,14964)
14551texinfo.texi(,14965) @item --section=@var{sec}
14552texinfo.texi(,14966) @itemx -s @var{sec}
14553texinfo.texi(,14967) @opindex --section=@var{sec}
14554texinfo.texi(,14968) @opindex -s @var{sec}
14555texinfo.texi(,14969) Put this file's entries in section @var{sec} of the directory.  If you
14556texinfo.texi(,14970) specify more than one section, all the entries are added in each of the
14557texinfo.texi(,14971) sections.  If you don't specify any sections, they are determined from
14558texinfo.texi(,14972) information in the Info file itself.
14559texinfo.texi(,14973)
14560texinfo.texi(,14974) @item --version
14561texinfo.texi(,14975) @itemx -V
14562texinfo.texi(,14976) @opindex --version
14563texinfo.texi(,14977) @opindex -V
14564texinfo.texi(,14978) @cindex version number, finding
14565texinfo.texi(,14979) Display version information and exit successfully.
14566texinfo.texi(,14980)
14567texinfo.texi(,14981) @end table
14568texinfo.texi(,14982)
14569texinfo.texi(,14983)
14570texinfo.texi(,14984) @node Command List
14571texinfo.texi(,14985) @appendix @@-Command List
14572texinfo.texi(,14986) @cindex Alphabetical @@-command list
14573texinfo.texi(,14987) @cindex List of  @@-commands
14574texinfo.texi(,14988) @cindex @@-command list
14575texinfo.texi(,14989) @cindex Reference to @@-commands
14576texinfo.texi(,14990)
14577texinfo.texi(,14991) Here is an alphabetical list of the @@-commands in Texinfo.  Square
14578texinfo.texi(,14992) brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis,
14579texinfo.texi(,14993) @samp{@dots{}}, indicates repeated text.
14580texinfo.texi(,14994)
14581texinfo.texi(,14995) @sp 1
14582texinfo.texi(,14996) @table @code
14583texinfo.texi(,14997) @item @@@var{whitespace}
14584texinfo.texi(,14998) An @code{@@} followed by a space, tab, or newline produces a normal,
14585texinfo.texi(,14999) stretchable, interword space.  @xref{Multiple Spaces}.
14586texinfo.texi(,15000)
14587texinfo.texi(,15001) @item @@!
14588texinfo.texi(,15002) Generate an exclamation point that really does end a sentence (usually
14589texinfo.texi(,15003) after an end-of-sentence capital letter).  @xref{Ending a Sentence}.
14590texinfo.texi(,15004)
14591texinfo.texi(,15005) @item @@"
14592texinfo.texi(,15006) @itemx @@'
14593texinfo.texi(,15007) Generate an umlaut or acute accent, respectively, over the next
14594texinfo.texi(,15008) character, as in @"o and @'o.  @xref{Inserting Accents}.
14595texinfo.texi(,15009)
14596texinfo.texi(,15010) @item @@*
14597texinfo.texi(,15011) Force a line break. Do not end a paragraph that uses @code{@@*} with
14598texinfo.texi(,15012) an @code{@@refill} command.  @xref{Line Breaks}.
14599texinfo.texi(,15013)
14600texinfo.texi(,15014) @item @@,@{@var{c}@}
14601texinfo.texi(,15015) Generate a cedilla accent under @var{c}, as in @,{c}.  @xref{Inserting
14602texinfo.texi(,15016) Accents}.
14603texinfo.texi(,15017)
14604texinfo.texi(,15018) @item @@-
14605texinfo.texi(,15019) Insert a discretionary hyphenation point.  @xref{- and hyphenation}.
14606texinfo.texi(,15020)
14607texinfo.texi(,15021) @item @@.
14608texinfo.texi(,15022) Produce a period that really does end a sentence (usually after an
14609texinfo.texi(,15023) end-of-sentence capital letter).  @xref{Ending a Sentence}.
14610texinfo.texi(,15024)
14611texinfo.texi(,15025) @item @@:
14612texinfo.texi(,15026) Indicate to @TeX{} that an immediately preceding period, question
14613texinfo.texi(,15027) mark, exclamation mark, or colon does not end a sentence.  Prevent
14614texinfo.texi(,15028) @TeX{} from inserting extra whitespace as it does at the end of a
14615texinfo.texi(,15029) sentence.  The command has no effect on the Info file output.
14616texinfo.texi(,15030) @xref{Not Ending a Sentence}.
14617texinfo.texi(,15031)
14618texinfo.texi(,15032) @item @@=
14619texinfo.texi(,15033) Generate a macron (bar) accent over the next character, as in @=o.
14620texinfo.texi(,15034) @xref{Inserting Accents}.
14621texinfo.texi(,15035)
14622texinfo.texi(,15036) @item @@?
14623texinfo.texi(,15037) Generate a question mark that really does end a sentence (usually after
14624texinfo.texi(,15038) an end-of-sentence capital letter).  @xref{Ending a Sentence}.
14625texinfo.texi(,15039)
14626texinfo.texi(,15040) @item @@@@
14627texinfo.texi(,15041) Stands for an at sign, @samp{@@}.
14628texinfo.texi(,15042) @xref{Braces Atsigns, , Inserting @@ and braces}.
14629texinfo.texi(,15043)
14630texinfo.texi(,15044) @item @@\
14631texinfo.texi(,15045) Stands for a backslash (@samp{\}) inside @code{@@math}.
14632texinfo.texi(,15046) @xref{math,,@code{math}}.
14633texinfo.texi(,15047)
14634texinfo.texi(,15048) @item @@^
14635texinfo.texi(,15049) @itemx @@`
14636texinfo.texi(,15050) Generate a circumflex (hat) or grave accent, respectively, over the next
14637texinfo.texi(,15051) character, as in @^o and @`e.
14638texinfo.texi(,15052) @xref{Inserting Accents}.
14639texinfo.texi(,15053)
14640texinfo.texi(,15054) @item @@@{
14641texinfo.texi(,15055) Stands for a left brace, @samp{@{}.
14642texinfo.texi(,15056) @xref{Braces Atsigns, , Inserting @@ and braces}.
14643texinfo.texi(,15057)
14644texinfo.texi(,15058) @item @@@}
14645texinfo.texi(,15059) Stands for a right-hand brace, @samp{@}}.@*
14646texinfo.texi(,15060) @xref{Braces Atsigns, , Inserting @@ and braces}.
14647texinfo.texi(,15061)
14648texinfo.texi(,15062) @item @@~
14649texinfo.texi(,15063) Generate a tilde accent over the next character, as in @~N.
14650texinfo.texi(,15064) @xref{Inserting Accents}.
14651texinfo.texi(,15065)
14652texinfo.texi(,15066) @item @@AA@{@}
14653texinfo.texi(,15067) @itemx @@aa@{@}
14654texinfo.texi(,15068) Generate the uppercase and lowercase Scandinavian A-ring letters,
14655texinfo.texi(,15069) respectively: @AA{}, @aa{}.  @xref{Inserting Accents}.
14656texinfo.texi(,15070)
14657texinfo.texi(,15071) @item @@acronym@{@var{abbrev}@}
14658texinfo.texi(,15072) Tag @var{abbrev} as an acronym, that is, an abbreviation written in all
14659texinfo.texi(,15073) capital letters, such as `NASA'.  @xref{acronym,, @code{acronym}}.
14660texinfo.texi(,15074)
14661texinfo.texi(,15075) @item @@AE@{@}
14662texinfo.texi(,15076) @itemx @@ae@{@}
14663texinfo.texi(,15077) Generate the uppercase and lowercase AE ligatures, respectively:
14664texinfo.texi(,15078) @AE{}, @ae{}.  @xref{Inserting Accents}.
14665texinfo.texi(,15079)
14666texinfo.texi(,15080) @itemx @@afivepaper
14667texinfo.texi(,15081) Change page dimensions for the A5 paper size.  @xref{A4 Paper}.
14668texinfo.texi(,15082)
14669texinfo.texi(,15083) @item @@afourlatex
14670texinfo.texi(,15084) @itemx @@afourpaper
14671texinfo.texi(,15085) @itemx @@afourwide
14672texinfo.texi(,15086) Change page dimensions for the A4 paper size.  @xref{A4 Paper}.
14673texinfo.texi(,15087)
14674texinfo.texi(,15088) @item @@alias @var{new}=@var{existing}
14675texinfo.texi(,15089) Make the command @samp{@@@var{new}} an alias for the existing command
14676texinfo.texi(,15090) @samp{@@@var{existing}}.  @xref{alias}.
14677texinfo.texi(,15091)
14678texinfo.texi(,15092) @item @@anchor@{@var{name}@}
14679texinfo.texi(,15093) Define @var{name} as the current location for use as a cross-reference
14680texinfo.texi(,15094) target.  @xref{anchor,, @code{@@anchor}}.
14681texinfo.texi(,15095)
14682texinfo.texi(,15096) @item @@appendix @var{title}
14683texinfo.texi(,15097) Begin an appendix.  The title appears in the table
14684texinfo.texi(,15098) of contents of a printed manual.  In Info, the title is
14685texinfo.texi(,15099) underlined with asterisks.  @xref{unnumbered & appendix, , The
14686texinfo.texi(,15100) @code{@@unnumbered} and @code{@@appendix} Commands}.@refill
14687texinfo.texi(,15101)
14688texinfo.texi(,15102) @item @@appendixsec @var{title}
14689texinfo.texi(,15103) @itemx @@appendixsection @var{title}
14690texinfo.texi(,15104) Begin an appendix section within an appendix.  The section title appears
14691texinfo.texi(,15105) in the table of contents of a printed manual.  In Info, the title is
14692texinfo.texi(,15106) underlined with equal signs.  @code{@@appendixsection} is a longer
14693texinfo.texi(,15107) spelling of the @code{@@appendixsec} command.  @xref{unnumberedsec
14694texinfo.texi(,15108) appendixsec heading, , Section Commands}.@refill
14695texinfo.texi(,15109)
14696texinfo.texi(,15110) @item @@appendixsubsec @var{title}
14697texinfo.texi(,15111) Begin an appendix subsection within an appendix.  The title appears
14698texinfo.texi(,15112) in the table of contents of a printed manual.  In Info, the title is
14699texinfo.texi(,15113) underlined with hyphens.  @xref{unnumberedsubsec appendixsubsec
14700texinfo.texi(,15114) subheading, , Subsection Commands}.@refill
14701texinfo.texi(,15115)
14702texinfo.texi(,15116) @item @@appendixsubsubsec @var{title}
14703texinfo.texi(,15117) Begin an appendix subsubsection within an appendix subsection.  The
14704texinfo.texi(,15118) title appears in the table of contents of a printed manual.  In Info,
14705texinfo.texi(,15119) the title is underlined with periods.  @xref{subsubsection,, The
14706texinfo.texi(,15120) `subsub' Commands}.@refill
14707texinfo.texi(,15121)
14708texinfo.texi(,15122) @item @@asis
14709texinfo.texi(,15123) Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to
14710texinfo.texi(,15124) print the table's first column without highlighting (``as is'').
14711texinfo.texi(,15125) @xref{Two-column Tables, , Making a Two-column Table}.@refill
14712texinfo.texi(,15126)
14713texinfo.texi(,15127) @item @@author @var{author}
14714texinfo.texi(,15128) Typeset @var{author} flushleft and underline it.  @xref{title
14715texinfo.texi(,15129) subtitle author, , The @code{@@title} and @code{@@author}
14716texinfo.texi(,15130) Commands}.@refill
14717texinfo.texi(,15131)
14718texinfo.texi(,15132) @item @@b@{@var{text}@}
14719texinfo.texi(,15133) Print @var{text} in @b{bold} font.  No effect in Info.  @xref{Fonts}.@refill
14720texinfo.texi(,15134)
14721texinfo.texi(,15140)
14722texinfo.texi(,15141) @item @@bullet@{@}
14723texinfo.texi(,15142) Generate a large round dot, or the closest possible
14724texinfo.texi(,15143) thing to one.  @xref{bullet, , @code{@@bullet}}.@refill
14725texinfo.texi(,15144)
14726texinfo.texi(,15145) @item @@bye
14727texinfo.texi(,15146) Stop formatting a file.  The formatters do not see the contents of a
14728texinfo.texi(,15147) file following an @code{@@bye} command.  @xref{Ending a File}.@refill
14729texinfo.texi(,15148)
14730texinfo.texi(,15149) @item @@c @var{comment}
14731texinfo.texi(,15150) Begin a comment in Texinfo.  The rest of the line does not appear in
14732texinfo.texi(,15151) either the Info file or the printed manual.  A synonym for
14733texinfo.texi(,15152) @code{@@comment}.  @xref{Comments, , Comments}.@refill
14734texinfo.texi(,15153)
14735texinfo.texi(,15154) @item @@cartouche
14736texinfo.texi(,15155) Highlight an example or quotation by drawing a box with rounded
14737texinfo.texi(,15156) corners around it.  Pair with @code{@@end cartouche}.  No effect in
14738texinfo.texi(,15157) Info.  @xref{cartouche, , Drawing Cartouches Around Examples}.)@refill
14739texinfo.texi(,15158)
14740texinfo.texi(,15159) @item @@center @var{line-of-text}
14741texinfo.texi(,15160) Center the line of text following the command.
14742texinfo.texi(,15161) @xref{titlefont center sp, , @code{@@center}}.@refill
14743texinfo.texi(,15162)
14744texinfo.texi(,15163) @item @@centerchap @var{line-of-text}
14745texinfo.texi(,15164) Like @code{@@chapter}, but centers the chapter title.  @xref{chapter,,
14746texinfo.texi(,15165) @code{@@chapter}}.
14747texinfo.texi(,15166)
14748texinfo.texi(,15167) @item @@chapheading @var{title}
14749texinfo.texi(,15168) Print a chapter-like heading in the text, but not in the table of
14750texinfo.texi(,15169) contents of a printed manual.  In Info, the title is underlined with
14751texinfo.texi(,15170) asterisks.  @xref{majorheading & chapheading, , @code{@@majorheading}
14752texinfo.texi(,15171) and @code{@@chapheading}}.@refill
14753texinfo.texi(,15172)
14754texinfo.texi(,15173) @item @@chapter @var{title}
14755texinfo.texi(,15174) Begin a chapter.  The chapter title appears in the table of
14756texinfo.texi(,15175) contents of a printed manual.  In Info, the title is underlined with
14757texinfo.texi(,15176) asterisks.  @xref{chapter, , @code{@@chapter}}.@refill
14758texinfo.texi(,15177)
14759texinfo.texi(,15178) @item @@cindex @var{entry}
14760texinfo.texi(,15179) Add @var{entry} to the index of concepts.  @xref{Index Entries, ,
14761texinfo.texi(,15180) Defining the Entries of an Index}.@refill
14762texinfo.texi(,15181)
14763texinfo.texi(,15182) @item @@cite@{@var{reference}@}
14764texinfo.texi(,15183) Highlight the name of a book or other reference that lacks a
14765texinfo.texi(,15184) companion Info file.  @xref{cite, , @code{@@cite}}.@refill
14766texinfo.texi(,15185)
14767texinfo.texi(,15186) @item @@clear @var{flag}
14768texinfo.texi(,15187) Unset @var{flag}, preventing the Texinfo formatting commands from
14769texinfo.texi(,15188) formatting text between subsequent pairs of @code{@@ifset @var{flag}}
14770texinfo.texi(,15189) and @code{@@end ifset} commands, and preventing
14771texinfo.texi(,15190) @code{@@value@{@var{flag}@}} from expanding to the value to which
14772texinfo.texi(,15191) @var{flag} is set.
14773texinfo.texi(,15192) @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
14774texinfo.texi(,15193)
14775texinfo.texi(,15194) @item @@code@{@var{sample-code}@}
14776texinfo.texi(,15195) Highlight text that is an expression, a syntactically complete token
14777texinfo.texi(,15196) of a program, or a program name.  @xref{code, , @code{@@code}}.@refill
14778texinfo.texi(,15197)
14779texinfo.texi(,15198) @item @@command@{@var{command-name}@}
14780texinfo.texi(,15199) Indicate a command name, such as @command{ls}.
14781texinfo.texi(,15200) @xref{command,, @code{@@command}}.
14782texinfo.texi(,15201)
14783texinfo.texi(,15202) @item @@comment @var{comment}
14784texinfo.texi(,15203) Begin a comment in Texinfo.  The rest of the line does not appear in
14785texinfo.texi(,15204) either the Info file or the printed manual.  A synonym for @code{@@c}.
14786texinfo.texi(,15205) @xref{Comments}.
14787texinfo.texi(,15206)
14788texinfo.texi(,15207) @item @@contents
14789texinfo.texi(,15208) Print a complete table of contents.  Has no effect in Info, which uses
14790texinfo.texi(,15209) menus instead.  @xref{Contents, , Generating a Table of
14791texinfo.texi(,15210) Contents}.@refill
14792texinfo.texi(,15211)
14793texinfo.texi(,15212) @item @@copyright@{@}
14794texinfo.texi(,15213) Generate a copyright symbol.  @xref{copyright symbol, ,
14795texinfo.texi(,15214) @code{@@copyright}}.@refill
14796texinfo.texi(,15215)
14797texinfo.texi(,15221)
14798texinfo.texi(,15222) @item @@defcodeindex @var{index-name}
14799texinfo.texi(,15223) Define a new index and its indexing command.  Print entries in an
14800texinfo.texi(,15224) @code{@@code} font.  @xref{New Indices, , Defining New
14801texinfo.texi(,15225) Indices}.@refill
14802texinfo.texi(,15226)
14803texinfo.texi(,15227) @item @@defcv @var{category} @var{class} @var{name}
14804texinfo.texi(,15228) @itemx @@defcvx @var{category} @var{class} @var{name}
14805texinfo.texi(,15229) Format a description for a variable associated with a class in
14806texinfo.texi(,15230) object-oriented programming.  Takes three arguments: the category of
14807texinfo.texi(,15231) thing being defined, the class to which it belongs, and its name.
14808texinfo.texi(,15232) @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
14809texinfo.texi(,15233)
14810texinfo.texi(,15234) @item @@deffn @var{category} @var{name} @var{arguments}@dots{}
14811texinfo.texi(,15235) @itemx @@deffnx @var{category} @var{name} @var{arguments}@dots{}
14812texinfo.texi(,15236) Format a description for a function, interactive command, or similar
14813texinfo.texi(,15237) entity that may take arguments.  @code{@@deffn} takes as arguments the
14814texinfo.texi(,15238) category of entity being described, the name of this particular
14815texinfo.texi(,15239) entity, and its arguments, if any.  @xref{Definition Commands}.@refill
14816texinfo.texi(,15240)
14817texinfo.texi(,15241) @item @@defindex @var{index-name}
14818texinfo.texi(,15242) Define a new index and its indexing command.  Print entries in a roman
14819texinfo.texi(,15243) font.  @xref{New Indices, , Defining New Indices}.@refill
14820texinfo.texi(,15244)
14821texinfo.texi(,15245) @item @@definfoenclose @var{newcmd}, @var{before}, @var{after},
14822texinfo.texi(,15246) Create new @@-command @var{newcmd} for Info that marks text by enclosing
14823texinfo.texi(,15247) it in strings that precede and follow the text.  @xref{definfoenclose}.
14824texinfo.texi(,15248)
14825texinfo.texi(,15249) @item @@defivar @var{class} @var{instance-variable-name}
14826texinfo.texi(,15250) @itemx @@defivarx @var{class} @var{instance-variable-name}
14827texinfo.texi(,15251) This command formats a description for an instance variable in
14828texinfo.texi(,15252) object-oriented programming.  The command is equivalent to @samp{@@defcv
14829texinfo.texi(,15253) @{Instance Variable@} @dots{}}.  @xref{Definition Commands}, and
14830texinfo.texi(,15254) @ref{deffnx,, Def Cmds in Detail}.
14831texinfo.texi(,15255)
14832texinfo.texi(,15256) @item @@defmac @var{macroname} @var{arguments}@dots{}
14833texinfo.texi(,15257) @itemx @@defmacx @var{macroname} @var{arguments}@dots{}
14834texinfo.texi(,15258) Format a description for a macro.  The command is equivalent to
14835texinfo.texi(,15259) @samp{@@deffn Macro @dots{}}.  @xref{Definition Commands}, and
14836texinfo.texi(,15260) @ref{deffnx,, Def Cmds in Detail}.
14837texinfo.texi(,15261)
14838texinfo.texi(,15262) @item @@defmethod @var{class} @var{method-name} @var{arguments}@dots{}
14839texinfo.texi(,15263) @itemx @@defmethodx @var{class} @var{method-name} @var{arguments}@dots{}
14840texinfo.texi(,15264) Format a description for a method in object-oriented programming.  The
14841texinfo.texi(,15265) command is equivalent to @samp{@@defop Method @dots{}}.  Takes as
14842texinfo.texi(,15266) arguments the name of the class of the method, the name of the
14843texinfo.texi(,15267) method, and its arguments, if any.  @xref{Definition Commands}, and
14844texinfo.texi(,15268) @ref{deffnx,, Def Cmds in Detail}.
14845texinfo.texi(,15269)
14846texinfo.texi(,15270) @item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
14847texinfo.texi(,15271) @itemx @@defopx @var{category} @var{class} @var{name} @var{arguments}@dots{}
14848texinfo.texi(,15272) Format a description for an operation in object-oriented programming.
14849texinfo.texi(,15273) @code{@@defop} takes as arguments the overall name of the category of
14850texinfo.texi(,15274) operation, the name of the class of the operation, the name of the
14851texinfo.texi(,15275) operation, and its arguments, if any.  @xref{Definition
14852texinfo.texi(,15276) Commands}, and @ref{Abstract Objects}.
14853texinfo.texi(,15277)
14854texinfo.texi(,15278) @item @@defopt @var{option-name}
14855texinfo.texi(,15279) @itemx @@defoptx @var{option-name}
14856texinfo.texi(,15280) Format a description for a user option.  The command is equivalent to
14857texinfo.texi(,15281) @samp{@@defvr @{User Option@} @dots{}}.  @xref{Definition Commands}, and
14858texinfo.texi(,15282) @ref{deffnx,, Def Cmds in Detail}.
14859texinfo.texi(,15283)
14860texinfo.texi(,15284) @item @@defspec @var{special-form-name} @var{arguments}@dots{}
14861texinfo.texi(,15285) @itemx @@defspecx @var{special-form-name} @var{arguments}@dots{}
14862texinfo.texi(,15286) Format a description for a special form.  The command is equivalent to
14863texinfo.texi(,15287) @samp{@@deffn @{Special Form@} @dots{}}.  @xref{Definition Commands},
14864texinfo.texi(,15288) and @ref{deffnx,, Def Cmds in Detail}.
14865texinfo.texi(,15289)
14866texinfo.texi(,15290) @item @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
14867texinfo.texi(,15291) @itemx @@deftpx @var{category} @var{name-of-type} @var{attributes}@dots{}
14868texinfo.texi(,15292) Format a description for a data type.  @code{@@deftp} takes as arguments
14869texinfo.texi(,15293) the category, the name of the type (which is a word like @samp{int} or
14870texinfo.texi(,15294) @samp{float}), and then the names of attributes of objects of that type.
14871texinfo.texi(,15295) @xref{Definition Commands}, and @ref{Data Types}.
14872texinfo.texi(,15296)
14873texinfo.texi(,15297) @item @@deftypefn @var{classification} @var{data-type} @var{name} @var{arguments}@dots{}
14874texinfo.texi(,15298) @itemx @@deftypefnx @var{classification} @var{data-type} @var{name} @var{arguments}@dots{}
14875texinfo.texi(,15299) Format a description for a function or similar entity that may take
14876texinfo.texi(,15300) arguments and that is typed.  @code{@@deftypefn} takes as arguments the
14877texinfo.texi(,15301) classification of entity being described, the type, the name of the
14878texinfo.texi(,15302) entity, and its arguments, if any.  @xref{Definition Commands}, and
14879texinfo.texi(,15303) @ref{deffnx,, Def Cmds in Detail}.
14880texinfo.texi(,15304)
14881texinfo.texi(,15305) @item @@deftypefun @var{data-type} @var{function-name} @var{arguments}@dots{}
14882texinfo.texi(,15306) @itemx @@deftypefunx @var{data-type} @var{function-name} @var{arguments}@dots{}
14883texinfo.texi(,15307) Format a description for a function in a typed language.
14884texinfo.texi(,15308) The command is equivalent to @samp{@@deftypefn Function @dots{}}.
14885texinfo.texi(,15309) @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
14886texinfo.texi(,15310)
14887texinfo.texi(,15311) @item @@deftypeivar @var{class} @var{data-type} @var{variable-name}
14888texinfo.texi(,15312) @itemx @@deftypeivarx @var{class} @var{data-type} @var{variable-name}
14889texinfo.texi(,15313) Format a description for a typed instance variable in object-oriented
14890texinfo.texi(,15314) programming. @xref{Definition Commands}, and @ref{Abstract Objects}.
14891texinfo.texi(,15315)
14892texinfo.texi(,15316) @item @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
14893texinfo.texi(,15317) @itemx @@deftypemethodx @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
14894texinfo.texi(,15318) Format a description for a typed method in object-oriented programming.
14895texinfo.texi(,15319) @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
14896texinfo.texi(,15320)
14897texinfo.texi(,15321) @item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
14898texinfo.texi(,15322) @itemx @@deftypeopx @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
14899texinfo.texi(,15323) Format a description for a typed operation in object-oriented programming.
14900texinfo.texi(,15324) @xref{Definition Commands}, and @ref{Abstract Objects}.
14901texinfo.texi(,15325)
14902texinfo.texi(,15326) @item @@deftypevar @var{data-type} @var{variable-name}
14903texinfo.texi(,15327) @itemx @@deftypevarx @var{data-type} @var{variable-name}
14904texinfo.texi(,15328) Format a description for a variable in a typed language.  The command is
14905texinfo.texi(,15329) equivalent to @samp{@@deftypevr Variable @dots{}}.  @xref{Definition
14906texinfo.texi(,15330) Commands}, and @ref{deffnx,, Def Cmds in Detail}.
14907texinfo.texi(,15331)
14908texinfo.texi(,15332) @item @@deftypevr @var{classification} @var{data-type} @var{name}
14909texinfo.texi(,15333) @itemx @@deftypevrx @var{classification} @var{data-type} @var{name}
14910texinfo.texi(,15334) Format a description for something like a variable in a typed
14911texinfo.texi(,15335) language---an entity that records a value.  Takes as arguments the
14912texinfo.texi(,15336) classification of entity being described, the type, and the name of the
14913texinfo.texi(,15337) entity.  @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in
14914texinfo.texi(,15338) Detail}.
14915texinfo.texi(,15339)
14916texinfo.texi(,15340) @item @@defun @var{function-name} @var{arguments}@dots{}
14917texinfo.texi(,15341) @itemx @@defunx @var{function-name} @var{arguments}@dots{}
14918texinfo.texi(,15342) Format a description for functions.  The command is equivalent to
14919texinfo.texi(,15343) @samp{@@deffn Function @dots{}}.  @xref{Definition Commands}, and
14920texinfo.texi(,15344) @ref{deffnx,, Def Cmds in Detail}.
14921texinfo.texi(,15345)
14922texinfo.texi(,15346) @item @@defvar @var{variable-name}
14923texinfo.texi(,15347) @itemx @@defvarx @var{variable-name}
14924texinfo.texi(,15348) Format a description for variables.  The command is equivalent to
14925texinfo.texi(,15349) @samp{@@defvr Variable @dots{}}.  @xref{Definition Commands}, and
14926texinfo.texi(,15350) @ref{deffnx,, Def Cmds in Detail}.
14927texinfo.texi(,15351)
14928texinfo.texi(,15352) @item @@defvr @var{category} @var{name}
14929texinfo.texi(,15353) @itemx @@defvrx @var{category} @var{name}
14930texinfo.texi(,15354) Format a description for any kind of variable.  @code{@@defvr} takes
14931texinfo.texi(,15355) as arguments the category of the entity and the name of the entity.
14932texinfo.texi(,15356) @xref{Definition Commands},
14933texinfo.texi(,15357) and @ref{deffnx,, Def Cmds in Detail}.
14934texinfo.texi(,15358)
14935texinfo.texi(,15359) @item @@detailmenu
14936texinfo.texi(,15360) Avoid @code{makeinfo} confusion stemming from the detailed node listing
14937texinfo.texi(,15361) in a master menu.  @xref{Master Menu Parts}.
14938texinfo.texi(,15362)
14939texinfo.texi(,15363) @item @@dfn@{@var{term}@}
14940texinfo.texi(,15364) Highlight the introductory or defining use of a term.
14941texinfo.texi(,15365) @xref{dfn, , @code{@@dfn}}.@refill
14942texinfo.texi(,15366)
14943texinfo.texi(,15367) @item @@dircategory @var{dirpart}
14944texinfo.texi(,15368) Specify a part of the Info directory menu where this file's entry should
14945texinfo.texi(,15369) go.  @xref{Installing Dir Entries}.
14946texinfo.texi(,15370)
14947texinfo.texi(,15371) @item @@direntry
14948texinfo.texi(,15372) Begin the Info directory menu entry for this file.  Pair with
14949texinfo.texi(,15373) @code{@@end direntry}.  @xref{Installing Dir Entries}.
14950texinfo.texi(,15374)
14951texinfo.texi(,15375) @item @@display
14952texinfo.texi(,15376) Begin a kind of example.  Like @code{@@example} (indent text, do not
14953texinfo.texi(,15377) fill), but do not select a new font.  Pair with @code{@@end display}.
14954texinfo.texi(,15378) @xref{display, , @code{@@display}}.
14955texinfo.texi(,15379)
14956texinfo.texi(,15380) @item @@dmn@{@var{dimension}@}
14957texinfo.texi(,15381) Format a unit of measure, as in 12@dmn{pt}.  Causes @TeX{} to insert a
14958texinfo.texi(,15382) thin space before @var{dimension}.  No effect in Info.
14959texinfo.texi(,15383) @xref{dmn, , @code{@@dmn}}.
14960texinfo.texi(,15384)
14961texinfo.texi(,15385) @item @@documentdescription
14962texinfo.texi(,15386) Set the document description text, included in the HTML output.  Pair
14963texinfo.texi(,15387) with @code{@@end documentdescription}.  @xref{documentdescription,,
14964texinfo.texi(,15388) @code{@@documentdescription}}.
14965texinfo.texi(,15389)
14966texinfo.texi(,15390) @item @@documentencoding @var{enc}
14967texinfo.texi(,15391) Declare the input encoding to be @var{enc}.
14968texinfo.texi(,15392) @xref{documentencoding,, @code{@@documentencoding}}.
14969texinfo.texi(,15393)
14970texinfo.texi(,15394) @item @@documentlanguage @var{CC}
14971texinfo.texi(,15395) Declare the document language as the two-character ISO-639 abbreviation
14972texinfo.texi(,15396) @var{CC}.  @xref{documentlanguage,, @code{@@documentlanguage}}.
14973texinfo.texi(,15397)
14974texinfo.texi(,15398) @item @@dotaccent@{@var{c}@}
14975texinfo.texi(,15399) Generate a dot accent over the character @var{c}, as in @dotaccent{o}.
14976texinfo.texi(,15400) @xref{Inserting Accents}.
14977texinfo.texi(,15401)
14978texinfo.texi(,15402) @item @@dots@{@}
14979texinfo.texi(,15403) Insert an ellipsis: @samp{@dots{}}.
14980texinfo.texi(,15404) @xref{dots, , @code{@@dots}}.@refill
14981texinfo.texi(,15405)
14982texinfo.texi(,15406) @item @@email@{@var{address}[, @var{displayed-text}]@}
14983texinfo.texi(,15407) Indicate an electronic mail address.
14984texinfo.texi(,15408) @xref{email, , @code{@@email}}.
14985texinfo.texi(,15409)
14986texinfo.texi(,15410) @item @@emph@{@var{text}@}
14987texinfo.texi(,15411) Highlight @var{text}; text is displayed in @emph{italics} in printed
14988texinfo.texi(,15412) output, and surrounded by asterisks in Info.  @xref{Emphasis, ,
14989texinfo.texi(,15413) Emphasizing Text}.
14990texinfo.texi(,15414)
14991texinfo.texi(,15415) @item @@end @var{environment}
14992texinfo.texi(,15416) Ends @var{environment}, as in @samp{@@end example}.  @xref{Formatting
14993texinfo.texi(,15417) Commands,,@@-commands}.
14994texinfo.texi(,15418)
14995texinfo.texi(,15419) @item @@env@{@var{environment-variable}@}
14996texinfo.texi(,15420) Indicate an environment variable name, such as @env{PATH}.
14997texinfo.texi(,15421) @xref{env,, @code{@@env}}.
14998texinfo.texi(,15422)
14999texinfo.texi(,15423) @item @@enddots@{@}
15000texinfo.texi(,15424) Generate an end-of-sentence of ellipsis, like this @enddots{}
15001texinfo.texi(,15425) @xref{dots,,@code{@@dots@{@}}}.
15002texinfo.texi(,15426)
15003texinfo.texi(,15427) @item @@enumerate [@var{number-or-letter}]
15004texinfo.texi(,15428) Begin a numbered list, using @code{@@item} for each entry.
15005texinfo.texi(,15429) Optionally, start list with @var{number-or-letter}.  Pair with
15006texinfo.texi(,15430) @code{@@end enumerate}.  @xref{enumerate, ,
15007texinfo.texi(,15431) @code{@@enumerate}}.@refill
15008texinfo.texi(,15432)
15009texinfo.texi(,15433) @item @@equiv@{@}
15010texinfo.texi(,15434) Indicate to the reader the exact equivalence of two forms with a
15011texinfo.texi(,15435) glyph: @samp{@equiv{}}.  @xref{Equivalence}.@refill
15012texinfo.texi(,15436)
15013texinfo.texi(,15437) @item @@error@{@}
15014texinfo.texi(,15438) Indicate to the reader with a glyph that the following text is
15015texinfo.texi(,15439) an error message: @samp{@error{}}.  @xref{Error Glyph}.@refill
15016texinfo.texi(,15440)
15017texinfo.texi(,15441) @item  @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
15018texinfo.texi(,15442) @itemx @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
15019texinfo.texi(,15443) Specify page footings resp.@: headings for even-numbered (left-hand)
15020texinfo.texi(,15444) pages.  @xref{Custom Headings, ,
15021texinfo.texi(,15445) How to Make Your Own Headings}.@refill
15022texinfo.texi(,15446)
15023texinfo.texi(,15447) @item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
15024texinfo.texi(,15448) @itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
15025texinfo.texi(,15449) Specify page footings resp.@: headings for every page.  Not relevant to
15026texinfo.texi(,15450) Info.  @xref{Custom Headings, , How to Make Your Own Headings}.@refill
15027texinfo.texi(,15451)
15028texinfo.texi(,15452) @item @@example
15029texinfo.texi(,15453) Begin an example.  Indent text, do not fill, and select fixed-width font.
15030texinfo.texi(,15454) Pair with @code{@@end example}.  @xref{example, ,
15031texinfo.texi(,15455) @code{@@example}}.@refill
15032texinfo.texi(,15456)
15033texinfo.texi(,15457) @item @@exampleindent @var{indent}
15034texinfo.texi(,15458) Indent example-like environments by @var{indent} number of spaces
15035texinfo.texi(,15459) (perhaps 0).  @xref{exampleindent,, Paragraph Indenting}.
15036texinfo.texi(,15460)
15037texinfo.texi(,15461) @item @@exclamdown@{@}
15038texinfo.texi(,15462) Produce an upside-down exclamation point.  @xref{Inserting Accents}.
15039texinfo.texi(,15463)
15040texinfo.texi(,15464) @item @@exdent @var{line-of-text}
15041texinfo.texi(,15465) Remove any indentation a line might have.  @xref{exdent, ,
15042texinfo.texi(,15466) Undoing the Indentation of a Line}.@refill
15043texinfo.texi(,15467)
15044texinfo.texi(,15468) @item @@expansion@{@}
15045texinfo.texi(,15469) Indicate the result of a macro expansion to the reader with a special
15046texinfo.texi(,15470) glyph: @samp{@expansion{}}.
15047texinfo.texi(,15471) @xref{expansion, , @expansion{} Indicating an Expansion}.@refill
15048texinfo.texi(,15472)
15049texinfo.texi(,15473) @item @@file@{@var{filename}@}
15050texinfo.texi(,15474) Highlight the name of a file, buffer, node, or directory.  @xref{file, ,
15051texinfo.texi(,15475) @code{@@file}}.@refill
15052texinfo.texi(,15476)
15053texinfo.texi(,15477) @item @@finalout
15054texinfo.texi(,15478) Prevent @TeX{} from printing large black warning rectangles beside
15055texinfo.texi(,15479) over-wide lines.  @xref{Overfull hboxes}.@refill
15056texinfo.texi(,15480)
15057texinfo.texi(,15481) @item @@findex @var{entry}
15058texinfo.texi(,15482) Add @var{entry} to the index of functions.  @xref{Index Entries, ,
15059texinfo.texi(,15483) Defining the Entries of an Index}.@refill
15060texinfo.texi(,15484)
15061texinfo.texi(,15485) @item @@flushleft
15062texinfo.texi(,15486) @itemx @@flushright
15063texinfo.texi(,15487) Left justify every line but leave the right end ragged.
15064texinfo.texi(,15488) Leave font as is.  Pair with @code{@@end flushleft}.
15065texinfo.texi(,15489) @code{@@flushright} analogous.
15066texinfo.texi(,15490) @xref{flushleft & flushright, , @code{@@flushleft} and
15067texinfo.texi(,15491) @code{@@flushright}}.@refill
15068texinfo.texi(,15492)
15069texinfo.texi(,15493) @item @@footnote@{@var{text-of-footnote}@}
15070texinfo.texi(,15494) Enter a footnote.  Footnote text is printed at the bottom of the page
15071texinfo.texi(,15495) by @TeX{}; Info may format in either `End' node or `Separate' node style.
15072texinfo.texi(,15496) @xref{Footnotes}.@refill
15073texinfo.texi(,15497)
15074texinfo.texi(,15498) @item @@footnotestyle @var{style}
15075texinfo.texi(,15499) Specify an Info file's footnote style, either @samp{end} for the end
15076texinfo.texi(,15500) node style or @samp{separate} for the separate node style.
15077texinfo.texi(,15501) @xref{Footnotes}.@refill
15078texinfo.texi(,15502)
15079texinfo.texi(,15503) @item @@format
15080texinfo.texi(,15504) Begin a kind of example.  Like @code{@@display}, but do not narrow the
15081texinfo.texi(,15505) margins.  Pair with @code{@@end format}.  @xref{example,,
15082texinfo.texi(,15506) @code{@@example}}.
15083texinfo.texi(,15507)
15084texinfo.texi(,15508) @item @@ftable @var{formatting-command}
15085texinfo.texi(,15509) Begin a two-column table, using @code{@@item} for each entry.
15086texinfo.texi(,15510) Automatically enter each of the items in the first column into the
15087texinfo.texi(,15511) index of functions.  Pair with @code{@@end ftable}.  The same as
15088texinfo.texi(,15512) @code{@@table}, except for indexing.  @xref{ftable vtable, ,
15089texinfo.texi(,15513) @code{@@ftable} and @code{@@vtable}}.@refill
15090texinfo.texi(,15514)
15091texinfo.texi(,15515) @item @@group
15092texinfo.texi(,15516) Hold text together that must appear on one printed page.  Pair with
15093texinfo.texi(,15517) @code{@@end group}.  Not relevant to Info.  @xref{group, ,
15094texinfo.texi(,15518) @code{@@group}}.@refill
15095texinfo.texi(,15519)
15096texinfo.texi(,15520) @item @@H@{@var{c}@}
15097texinfo.texi(,15521) Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}.
15098texinfo.texi(,15522)
15099texinfo.texi(,15523) @item @@heading @var{title}
15100texinfo.texi(,15524) Print an unnumbered section-like heading in the text, but not in the
15101texinfo.texi(,15525) table of contents of a printed manual.  In Info, the title is
15102texinfo.texi(,15526) underlined with equal signs.  @xref{unnumberedsec appendixsec heading,
15103texinfo.texi(,15527) , Section Commands}.@refill
15104texinfo.texi(,15528)
15105texinfo.texi(,15529) @item @@headings @var{on-off-single-double}
15106texinfo.texi(,15530) Turn page headings on or off, and/or specify single-sided or double-sided
15107texinfo.texi(,15531) page headings for printing.  @xref{headings on off, , The
15108texinfo.texi(,15532) @code{@@headings} Command}.
15109texinfo.texi(,15533)
15110texinfo.texi(,15534) @item @@html
15111texinfo.texi(,15535) Enter HTML completely.  Pair with @code{@@end html}.  @xref{Raw
15112texinfo.texi(,15536) Formatter Commands}.
15113texinfo.texi(,15537)
15114texinfo.texi(,15538) @item @@hyphenation@{@var{hy-phen-a-ted words}@}
15115texinfo.texi(,15539) Explicitly define hyphenation points.  @xref{- and hyphenation,,
15116texinfo.texi(,15540) @code{@@-} and @code{@@hyphenation}}.
15117texinfo.texi(,15541)
15118texinfo.texi(,15542) @item @@i@{@var{text}@}
15119texinfo.texi(,15543) Print @var{text} in @i{italic} font.  No effect in Info.  @xref{Fonts}.
15120texinfo.texi(,15544)
15121texinfo.texi(,15545) @item @@ifclear @var{flag}
15122texinfo.texi(,15546) If @var{flag} is cleared, the Texinfo formatting commands format text
15123texinfo.texi(,15547) between @code{@@ifclear @var{flag}} and the following @code{@@end
15124texinfo.texi(,15548) ifclear} command.
15125texinfo.texi(,15549) @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
15126texinfo.texi(,15550)
15127texinfo.texi(,15551) @item @@ifhtml
15128texinfo.texi(,15552) @itemx @@ifinfo
15129texinfo.texi(,15553) Begin a stretch of text that will be ignored by @TeX{} when it typesets
15130texinfo.texi(,15554) the printed manual.  @code{@@ifhtml} text appears only in the HTML
15131texinfo.texi(,15555) output.  @code{@@ifinfo} output appears in both Info and (for historical
15132texinfo.texi(,15556) compatibility) plain text output .  Pair with @code{@@end ifhtml}
15133texinfo.texi(,15557) resp.@: @code{@@end ifinfo}.  @xref{Conditionals}.
15134texinfo.texi(,15558)
15135texinfo.texi(,15559) @item @@ifnothtml
15136texinfo.texi(,15560) @itemx @@ifnotinfo
15137texinfo.texi(,15561) @itemx @@ifnotplaintext
15138texinfo.texi(,15562) @itemx @@ifnottex
15139texinfo.texi(,15563) Begin a stretch of text that will be ignored in one output format but
15140texinfo.texi(,15564) not the others.  The text appears in the formats not specified:
15141texinfo.texi(,15565) @code{@@ifnothtml} text is omitted from html output, etc.  The exception
15142texinfo.texi(,15566) is @code{@@ifnotinfo} text, which is omitted from plain text output as
15143texinfo.texi(,15567) well as Info output.  Pair with @code{@@end ifnothtml} resp.@:
15144texinfo.texi(,15568) @code{@@end ifnotinfo} resp.@: @code{@@end ifnotplaintext} resp.@:
15145texinfo.texi(,15569) @code{@@end ifnottex}.  @xref{Conditionals}.
15146texinfo.texi(,15570)
15147texinfo.texi(,15571) @item @@ifplaintext
15148texinfo.texi(,15572) Begin a stretch of text that appears only in the plain text output.
15149texinfo.texi(,15573) Pair with @code{@@end ifplaintext}.  @xref{Conditionals}.
15150texinfo.texi(,15574)
15151texinfo.texi(,15575) @item @@ifset @var{flag}
15152texinfo.texi(,15576) If @var{flag} is set, the Texinfo formatting commands format text
15153texinfo.texi(,15577) between @code{@@ifset @var{flag}} and the following @code{@@end ifset}
15154texinfo.texi(,15578) command.
15155texinfo.texi(,15579) @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
15156texinfo.texi(,15580)
15157texinfo.texi(,15581) @item @@iftex
15158texinfo.texi(,15582) Begin a stretch of text that will not appear in the Info file, but
15159texinfo.texi(,15583) will be processed only by @TeX{}.  Pair with @code{@@end iftex}.
15160texinfo.texi(,15584) @xref{Conditionals, , Conditionally Visible Text}.@refill
15161texinfo.texi(,15585)
15162texinfo.texi(,15586) @item @@ignore
15163texinfo.texi(,15587) Begin a stretch of text that will not appear in either the Info file
15164texinfo.texi(,15588) or the printed output.  Pair with @code{@@end ignore}.
15165texinfo.texi(,15589) @xref{Comments, , Comments and Ignored Text}.@refill
15166texinfo.texi(,15590)
15167texinfo.texi(,15591) @item @@image@{@var{filename}, [@var{width}], [@var{height}], [@var{alt}], [@var{ext}]@}
15168texinfo.texi(,15592) Include graphics image in external @var{filename} scaled to the given
15169texinfo.texi(,15593) @var{width} and/or @var{height}, using @var{alt} text and looking for
15170texinfo.texi(,15594) @samp{@var{filename}.@var{ext}} in HTML.  @xref{Images}.
15171texinfo.texi(,15595)
15172texinfo.texi(,15596) @item @@include @var{filename}
15173texinfo.texi(,15597) Incorporate the contents of the file @var{filename} into the Info file
15174texinfo.texi(,15598) or printed document.  @xref{Include Files}.@refill
15175texinfo.texi(,15599)
15176texinfo.texi(,15600) @item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@}
15177texinfo.texi(,15601) Make a cross reference to an Info file for which there is no printed
15178texinfo.texi(,15602) manual.  @xref{inforef, , Cross references using
15179texinfo.texi(,15603) @code{@@inforef}}.@refill
15180texinfo.texi(,15604)
15181texinfo.texi(,15605) @item \input @var{macro-definitions-file}
15182texinfo.texi(,15606) Use the specified macro definitions file.  This command is used only
15183texinfo.texi(,15607) in the first line of a Texinfo file to cause @TeX{} to make use of the
15184texinfo.texi(,15608) @file{texinfo} macro definitions file.  The backslash in @code{\input}
15185texinfo.texi(,15609) is used instead of an @code{@@} because @TeX{} does not
15186texinfo.texi(,15610) recognize @code{@@} until after it has read the definitions file.
15187texinfo.texi(,15611) @xref{Texinfo File Header}.
15188texinfo.texi(,15612)
15189texinfo.texi(,15613) @item @@item
15190texinfo.texi(,15614) Indicate the beginning of a marked paragraph for @code{@@itemize} and
15191texinfo.texi(,15615) @code{@@enumerate}; indicate the beginning of the text of a first column
15192texinfo.texi(,15616) entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}.
15193texinfo.texi(,15617) @xref{Lists and Tables}.@refill
15194texinfo.texi(,15618)
15195texinfo.texi(,15619) @item @@itemize  @var{mark-generating-character-or-command}
15196texinfo.texi(,15620) Produce a sequence of indented paragraphs, with a mark inside the left
15197texinfo.texi(,15621) margin at the beginning of each paragraph.  Pair with @code{@@end
15198texinfo.texi(,15622) itemize}.  @xref{itemize, , @code{@@itemize}}.@refill
15199texinfo.texi(,15623)
15200texinfo.texi(,15624) @item @@itemx
15201texinfo.texi(,15625) Like @code{@@item} but do not generate extra vertical space above the
15202texinfo.texi(,15626) item text.  @xref{itemx, , @code{@@itemx}}.@refill
15203texinfo.texi(,15627)
15204texinfo.texi(,15628) @item @@kbd@{@var{keyboard-characters}@}
15205texinfo.texi(,15629) Indicate text that is characters of input to be typed by
15206texinfo.texi(,15630) users.  @xref{kbd, , @code{@@kbd}}.@refill
15207texinfo.texi(,15631)
15208texinfo.texi(,15632) @item @@kbdinputstyle @var{style}
15209texinfo.texi(,15633) Specify when @code{@@kbd} should use a font distinct from @code{@@code}.
15210texinfo.texi(,15634) @xref{kbd, , @code{@@kbd}}.@refill
15211texinfo.texi(,15635)
15212texinfo.texi(,15636) @item @@key@{@var{key-name}@}
15213texinfo.texi(,15637) Indicate a name for a key on a keyboard.
15214texinfo.texi(,15638) @xref{key, , @code{@@key}}.@refill
15215texinfo.texi(,15639)
15216texinfo.texi(,15640) @item @@kindex @var{entry}
15217texinfo.texi(,15641) Add @var{entry} to the index of keys.
15218texinfo.texi(,15642) @xref{Index Entries, , Defining the Entries of an Index}.@refill
15219texinfo.texi(,15643)
15220texinfo.texi(,15644) @item @@L@{@}
15221texinfo.texi(,15645) @itemx @@l@{@}
15222texinfo.texi(,15646) Generate the uppercase and lowercase Polish suppressed-L letters,
15223texinfo.texi(,15647) respectively: @L{}, @l{}.
15224texinfo.texi(,15648)
15225texinfo.texi(,15649) @c Possibly this can be tossed now that we have macros.  --karl, 16sep96.
15226texinfo.texi(,15650) @c Yes, let's toss it, it's pretty weird.  --karl, 15jun97.
15227texinfo.texi(,15651) @c @item @@global@@let@var{new-command}=@var{existing-command}
15228texinfo.texi(,15652) @c Equate a new highlighting command with an existing one.  Only for
15229texinfo.texi(,15653) @c @TeX{}.  Write definition inside of @code{@@iftex} @dots{} @code{@@end
15230texinfo.texi(,15654) @c iftex}.  @xref{Customized Highlighting}.@refill
15231texinfo.texi(,15655)
15232texinfo.texi(,15656) @item @@lisp
15233texinfo.texi(,15657) Begin an example of Lisp code.  Indent text, do not fill, and select
15234texinfo.texi(,15658) fixed-width font.  Pair with @code{@@end lisp}.  @xref{lisp, , @code{@@lisp}}.
15235texinfo.texi(,15659)
15236texinfo.texi(,15660) @item @@lowersections
15237texinfo.texi(,15661) Change subsequent chapters to sections, sections to subsections, and so
15238texinfo.texi(,15662) on. @xref{Raise/lower sections, , @code{@@raisesections} and
15239texinfo.texi(,15663) @code{@@lowersections}}.@refill
15240texinfo.texi(,15664)
15241texinfo.texi(,15665) @item @@macro @var{macroname} @{@var{params}@}
15242texinfo.texi(,15666) Define a new Texinfo command @code{@@@var{macroname}@{@var{params}@}}.
15243texinfo.texi(,15667) Only supported by @code{makeinfo} and @code{texi2dvi}.  @xref{Defining
15244texinfo.texi(,15668) Macros}.
15245texinfo.texi(,15669)
15246texinfo.texi(,15670) @item @@majorheading @var{title}
15247texinfo.texi(,15671) Print a chapter-like heading in the text, but not in the table of
15248texinfo.texi(,15672) contents of a printed manual.  Generate more vertical whitespace before
15249texinfo.texi(,15673) the heading than the @code{@@chapheading} command.  In Info, the chapter
15250texinfo.texi(,15674) heading line is underlined with asterisks.  @xref{majorheading &
15251texinfo.texi(,15675) chapheading, , @code{@@majorheading} and @code{@@chapheading}}.@refill
15252texinfo.texi(,15676)
15253texinfo.texi(,15677) @item @@math@{@var{mathematical-expression}@}
15254texinfo.texi(,15678) Format a mathematical expression.
15255texinfo.texi(,15679) @xref{math, , @code{@@math}: Inserting Mathematical Expressions}.
15256texinfo.texi(,15680)
15257texinfo.texi(,15681) @item @@menu
15258texinfo.texi(,15682) Mark the beginning of a menu of nodes in Info.  No effect in a printed
15259texinfo.texi(,15683) manual.  Pair with @code{@@end menu}.  @xref{Menus}.@refill
15260texinfo.texi(,15684)
15261texinfo.texi(,15685) @item @@minus@{@}
15262texinfo.texi(,15686) Generate a minus sign, `@minus{}'.  @xref{minus, , @code{@@minus}}.@refill
15263texinfo.texi(,15687)
15264texinfo.texi(,15688) @item @@multitable @var{column-width-spec}
15265texinfo.texi(,15689) Begin a multi-column table.  Pair with @code{@@end multitable}.
15266texinfo.texi(,15690) @xref{Multitable Column Widths}.
15267texinfo.texi(,15691)
15268texinfo.texi(,15692) @item @@need @var{n}
15269texinfo.texi(,15693) Start a new page in a printed manual if fewer than @var{n} mils
15270texinfo.texi(,15694) (thousandths of an inch) remain on the current page.  @xref{need, ,
15271texinfo.texi(,15695) @code{@@need}}.@refill
15272texinfo.texi(,15696)
15273texinfo.texi(,15697) @item @@node @var{name}, @var{next}, @var{previous}, @var{up}
15274texinfo.texi(,15698) Define the beginning of a new node in Info, and serve as a locator for
15275texinfo.texi(,15699) references for @TeX{}.  @xref{node, , @code{@@node}}.@refill
15276texinfo.texi(,15700)
15277texinfo.texi(,15701) @item @@noindent
15278texinfo.texi(,15702) Prevent text from being indented as if it were a new paragraph.
15279texinfo.texi(,15703) @xref{noindent, , @code{@@noindent}}.@refill
15280texinfo.texi(,15704)
15281texinfo.texi(,15705) @item @@novalidate
15282texinfo.texi(,15706) Suppress validation of node references, omit creation of auxiliary files
15283texinfo.texi(,15707) with @TeX{}.  Use before @code{@@setfilename}.  @xref{Pointer Validation}.
15284texinfo.texi(,15708)
15285texinfo.texi(,15709) @item @@O@{@}
15286texinfo.texi(,15710) @itemx @@o@{@}
15287texinfo.texi(,15711) Generate the uppercase and lowercase O-with-slash letters, respectively:
15288texinfo.texi(,15712) @O{}, @o{}.
15289texinfo.texi(,15713)
15290texinfo.texi(,15714) @item  @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
15291texinfo.texi(,15715) @itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
15292texinfo.texi(,15716) Specify page footings resp.@: headings for odd-numbered (right-hand)
15293texinfo.texi(,15717) pages.  @xref{Custom Headings, ,
15294texinfo.texi(,15718) How to Make Your Own Headings}.@refill
15295texinfo.texi(,15719)
15296texinfo.texi(,15720) @item @@OE@{@}
15297texinfo.texi(,15721) @itemx @@oe@{@}
15298texinfo.texi(,15722) Generate the uppercase and lowercase OE ligatures, respectively:
15299texinfo.texi(,15723) @OE{}, @oe{}.  @xref{Inserting Accents}.
15300texinfo.texi(,15724)
15301texinfo.texi(,15725) @item @@option@{@var{option-name}@}
15302texinfo.texi(,15726) Indicate a command-line option, such as @option{-l} or @option{--help}.
15303texinfo.texi(,15727) @xref{option,, @code{@@option}}.
15304texinfo.texi(,15728)
15305texinfo.texi(,15729) @item @@page
15306texinfo.texi(,15730) Start a new page in a printed manual.  No effect in Info.
15307texinfo.texi(,15731) @xref{page, , @code{@@page}}.@refill
15308texinfo.texi(,15732)
15309texinfo.texi(,15733) @item @@pagesizes [@var{width}][, @var{height}]
15310texinfo.texi(,15734) Change page dimensions.  @xref{pagesizes}.
15311texinfo.texi(,15735)
15312texinfo.texi(,15736) @item @@paragraphindent @var{indent}
15313texinfo.texi(,15737) Indent paragraphs by @var{indent} number of spaces (perhaps 0); preserve
15314texinfo.texi(,15738) source file indentation if @var{indent} is @code{asis}.
15315texinfo.texi(,15739) @xref{paragraphindent,, Paragraph Indenting}.
15316texinfo.texi(,15740)
15317texinfo.texi(,15741) @item @@pindex @var{entry}
15318texinfo.texi(,15742) Add @var{entry} to the index of programs.  @xref{Index Entries, , Defining
15319texinfo.texi(,15743) the Entries of an Index}.@refill
15320texinfo.texi(,15744)
15321texinfo.texi(,15745) @item @@point@{@}
15322texinfo.texi(,15746) Indicate the position of point in a buffer to the reader with a
15323texinfo.texi(,15747) glyph: @samp{@point{}}.  @xref{Point Glyph, , Indicating
15324texinfo.texi(,15748) Point in a Buffer}.@refill
15325texinfo.texi(,15749)
15326texinfo.texi(,15750) @item @@pounds@{@}
15327texinfo.texi(,15751) Generate the pounds sterling currency sign.
15328texinfo.texi(,15752) @xref{pounds,,@code{@@pounds@{@}}}.
15329texinfo.texi(,15753)
15330texinfo.texi(,15754) @item @@print@{@}
15331texinfo.texi(,15755) Indicate printed output to the reader with a glyph:
15332texinfo.texi(,15756) @samp{@print{}}.  @xref{Print Glyph}.@refill
15333texinfo.texi(,15757)
15334texinfo.texi(,15758) @item @@printindex @var{index-name}
15335texinfo.texi(,15759) Print an alphabetized two-column index in a printed manual or generate
15336texinfo.texi(,15760) an alphabetized menu of index entries for Info.  @xref{Printing
15337texinfo.texi(,15761) Indices & Menus}.@refill
15338texinfo.texi(,15762)
15339texinfo.texi(,15763) @item @@pxref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
15340texinfo.texi(,15764) Make a reference that starts with a lower case `see' in a printed
15341texinfo.texi(,15765) manual.  Use within parentheses only.  Do not follow command with a
15342texinfo.texi(,15766) punctuation mark---the Info formatting commands automatically insert
15343texinfo.texi(,15767) terminating punctuation as needed.  Only the first argument is mandatory.
15344texinfo.texi(,15768) @xref{pxref, , @code{@@pxref}}.@refill
15345texinfo.texi(,15769)
15346texinfo.texi(,15770) @item @@questiondown@{@}
15347texinfo.texi(,15771) Generate an upside-down question mark.  @xref{Inserting Accents}.
15348texinfo.texi(,15772)
15349texinfo.texi(,15773) @item @@quotation
15350texinfo.texi(,15774) Narrow the margins to indicate text that is quoted from another real
15351texinfo.texi(,15775) or imaginary work.  Write command on a line of its own.  Pair with
15352texinfo.texi(,15776) @code{@@end quotation}.  @xref{quotation, ,
15353texinfo.texi(,15777) @code{@@quotation}}.@refill
15354texinfo.texi(,15778)
15355texinfo.texi(,15779) @item @@r@{@var{text}@}
15356texinfo.texi(,15780) Print @var{text} in @r{roman} font.  No effect in Info.
15357texinfo.texi(,15781) @xref{Fonts}.@refill
15358texinfo.texi(,15782)
15359texinfo.texi(,15783) @item @@raisesections
15360texinfo.texi(,15784) Change subsequent sections to chapters, subsections to sections, and so
15361texinfo.texi(,15785) on.  @xref{Raise/lower sections, , @code{@@raisesections} and
15362texinfo.texi(,15786) @code{@@lowersections}}.@refill
15363texinfo.texi(,15787)
15364texinfo.texi(,15788) @item @@ref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
15365texinfo.texi(,15789) Make a reference.  In a printed manual, the reference does not start
15366texinfo.texi(,15790) with a `See'.  Follow command with a punctuation mark.  Only the first
15367texinfo.texi(,15791) argument is mandatory.  @xref{ref, , @code{@@ref}}.@refill
15368texinfo.texi(,15792)
15369texinfo.texi(,15793) @item @@refill
15370texinfo.texi(,15794) In Info, refill and indent the paragraph after all the other processing
15371texinfo.texi(,15795) has been done.  No effect on @TeX{}, which always refills.  This command
15372texinfo.texi(,15796) is no longer needed, since all formatters now automatically refill.
15373texinfo.texi(,15797) @xref{Refilling Paragraphs}.@refill
15374texinfo.texi(,15798)
15375texinfo.texi(,15799) @item @@result@{@}
15376texinfo.texi(,15800) Indicate the result of an expression to the reader with a special
15377texinfo.texi(,15801) glyph: @samp{@result{}}.  @xref{result, , @code{@@result}}.@refill
15378texinfo.texi(,15802)
15379texinfo.texi(,15803) @item @@ringaccent@{@var{c}@}
15380texinfo.texi(,15804) Generate a ring accent over the next character, as in @ringaccent{o}.
15381texinfo.texi(,15805) @xref{Inserting Accents}.
15382texinfo.texi(,15806)
15383texinfo.texi(,15807) @item @@samp@{@var{text}@}
15384texinfo.texi(,15808) Highlight @var{text} that is a literal example of a sequence of
15385texinfo.texi(,15809) characters.  Used for single characters, for statements, and often for
15386texinfo.texi(,15810) entire shell commands.  @xref{samp, , @code{@@samp}}.@refill
15387texinfo.texi(,15811)
15388texinfo.texi(,15812) @item @@sc@{@var{text}@}
15389texinfo.texi(,15813) Set @var{text} in a printed output in @sc{the small caps font} and
15390texinfo.texi(,15814) set text in the Info file in uppercase letters.
15391texinfo.texi(,15815) @xref{Smallcaps}.@refill
15392texinfo.texi(,15816)
15393texinfo.texi(,15817) @item @@section @var{title}
15394texinfo.texi(,15818) Begin a section within a chapter.  In a printed manual, the section
15395texinfo.texi(,15819) title is numbered and appears in the table of contents.  In Info, the
15396texinfo.texi(,15820) title is underlined with equal signs.  @xref{section, ,
15397texinfo.texi(,15821) @code{@@section}}.@refill
15398texinfo.texi(,15822)
15399texinfo.texi(,15823) @item @@set @var{flag} [@var{string}]
15400texinfo.texi(,15824) Make @var{flag} active, causing the Texinfo formatting commands to
15401texinfo.texi(,15825) format text between subsequent pairs of @code{@@ifset @var{flag}} and
15402texinfo.texi(,15826) @code{@@end ifset} commands.  Optionally, set value of @var{flag} to
15403texinfo.texi(,15827) @var{string}.
15404texinfo.texi(,15828) @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.
15405texinfo.texi(,15829)
15406texinfo.texi(,15830) @item @@setchapternewpage @var{on-off-odd}
15407texinfo.texi(,15831) Specify whether chapters start on new pages, and if so, whether on
15408texinfo.texi(,15832) odd-numbered (right-hand) new pages.  @xref{setchapternewpage, ,
15409texinfo.texi(,15833) @code{@@setchapternewpage}}.
15410texinfo.texi(,15834)
15411texinfo.texi(,15835) @item @@setcontentsaftertitlepage
15412texinfo.texi(,15836) Put the table of contents after the @samp{@@end titlepage} even if the
15413texinfo.texi(,15837) @code{@@contents} command is not there.  @xref{Contents}.
15414texinfo.texi(,15838)
15415texinfo.texi(,15839) @item @@setfilename @var{info-file-name}
15416texinfo.texi(,15840) Provide a name to be used by the Info file.  This command is essential
15417texinfo.texi(,15841) for @TeX{} formatting as well, even though it produces no output.
15418texinfo.texi(,15842) @xref{setfilename, , @code{@@setfilename}}.
15419texinfo.texi(,15843)
15420texinfo.texi(,15844) @item @@setshortcontentsaftertitlepage
15421texinfo.texi(,15845) Place the short table of contents after the @samp{@@end titlepage}
15422texinfo.texi(,15846) command even if the @code{@@shortcontents} command is not there.
15423texinfo.texi(,15847) @xref{Contents}.
15424texinfo.texi(,15848)
15425texinfo.texi(,15849) @item @@settitle @var{title}
15426texinfo.texi(,15850) Provide a title for page headers in a printed manual, and the default
15427texinfo.texi(,15851) document description for HTML @samp{<head>}.
15428texinfo.texi(,15852) @xref{settitle, , @code{@@settitle}}.@refill
15429texinfo.texi(,15853)
15430texinfo.texi(,15854) @item @@shortcontents
15431texinfo.texi(,15855) Print a short table of contents.  Not relevant to Info, which uses
15432texinfo.texi(,15856) menus rather than tables of contents.  A synonym for
15433texinfo.texi(,15857) @code{@@summarycontents}.  @xref{Contents, , Generating a Table of
15434texinfo.texi(,15858) Contents}.@refill
15435texinfo.texi(,15859)
15436texinfo.texi(,15860) @item @@shorttitlepage @var{title}
15437texinfo.texi(,15861) Generate a minimal title page.  @xref{titlepage,,@code{@@titlepage}}.
15438texinfo.texi(,15862)
15439texinfo.texi(,15863) @item @@smallbook
15440texinfo.texi(,15864) Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format
15441texinfo.texi(,15865) rather than the regular 8.5 by 11 inch format.  @xref{smallbook, ,
15442texinfo.texi(,15866) Printing Small Books}.  Also, see @ref{small}.
15443texinfo.texi(,15867)
15444texinfo.texi(,15868) @item @@smalldisplay
15445texinfo.texi(,15869) Begin a kind of example.  Like @code{@@smallexample} (narrow margins, no
15446texinfo.texi(,15870) filling), but do not select the fixed-width font.  Pair with @code{@@end
15447texinfo.texi(,15871) smalldisplay}.  @xref{small}.
15448texinfo.texi(,15872)
15449texinfo.texi(,15873) @item @@smallexample
15450texinfo.texi(,15874) Indent text to indicate an example.  Do not fill, select fixed-width
15451texinfo.texi(,15875) font, narrow the margins.  In printed manuals, print text in a smaller
15452texinfo.texi(,15876) font than with @code{@@example}.  Pair with @code{@@end smallexample}.
15453texinfo.texi(,15877) @xref{small}.
15454texinfo.texi(,15878)
15455texinfo.texi(,15879) @item @@smallformat
15456texinfo.texi(,15880) Begin a kind of example.  Like @code{@@smalldisplay}, but do not narrow
15457texinfo.texi(,15881) the margins.  Pair with @code{@@end smallformat}.  @xref{small}.
15458texinfo.texi(,15882)
15459texinfo.texi(,15883) @item @@smalllisp
15460texinfo.texi(,15884) Begin an example of Lisp code.  Same as @code{@@smallexample}.  Pair
15461texinfo.texi(,15885) with @code{@@end smalllisp}.  @xref{small}.
15462texinfo.texi(,15886)
15463texinfo.texi(,15887) @item @@sp @var{n}
15464texinfo.texi(,15888) Skip @var{n} blank lines.  @xref{sp, , @code{@@sp}}.@refill
15465texinfo.texi(,15889)
15466texinfo.texi(,15890) @item @@ss@{@}
15467texinfo.texi(,15891) Generate the German sharp-S es-zet letter, @ss{}.  @xref{Inserting Accents}.
15468texinfo.texi(,15892)
15469texinfo.texi(,15893) @item @@strong @{@var{text}@}
15470texinfo.texi(,15894) Emphasize @var{text} by typesetting it in a @strong{bold} font for the
15471texinfo.texi(,15895) printed manual and by surrounding it with asterisks for Info.
15472texinfo.texi(,15896) @xref{emph & strong, , Emphasizing Text}.@refill
15473texinfo.texi(,15897)
15474texinfo.texi(,15898) @item @@subheading @var{title}
15475texinfo.texi(,15899) Print an unnumbered subsection-like heading in the text, but not in
15476texinfo.texi(,15900) the table of contents of a printed manual.  In Info, the title is
15477texinfo.texi(,15901) underlined with hyphens.  @xref{unnumberedsubsec appendixsubsec
15478texinfo.texi(,15902) subheading, , @code{@@unnumberedsubsec} @code{@@appendixsubsec}
15479texinfo.texi(,15903) @code{@@subheading}}.@refill
15480texinfo.texi(,15904)
15481texinfo.texi(,15905) @item @@subsection @var{title}
15482texinfo.texi(,15906) Begin a subsection within a section.  In a printed manual, the
15483texinfo.texi(,15907) subsection title is numbered and appears in the table of contents.  In
15484texinfo.texi(,15908) Info, the title is underlined with hyphens.  @xref{subsection, ,
15485texinfo.texi(,15909) @code{@@subsection}}.@refill
15486texinfo.texi(,15910)
15487texinfo.texi(,15911) @item @@subsubheading @var{title}
15488texinfo.texi(,15912) Print an unnumbered subsubsection-like heading in the text, but not in
15489texinfo.texi(,15913) the table of contents of a printed manual.  In Info, the title is
15490texinfo.texi(,15914) underlined with periods.  @xref{subsubsection, , The `subsub'
15491texinfo.texi(,15915) Commands}.@refill
15492texinfo.texi(,15916)
15493texinfo.texi(,15917) @item @@subsubsection @var{title}
15494texinfo.texi(,15918) Begin a subsubsection within a subsection.  In a printed manual,
15495texinfo.texi(,15919) the subsubsection title is numbered and appears in the table of
15496texinfo.texi(,15920) contents.  In Info, the title is underlined with periods.
15497texinfo.texi(,15921) @xref{subsubsection, , The `subsub' Commands}.@refill
15498texinfo.texi(,15922)
15499texinfo.texi(,15923) @item @@subtitle @var{title}
15500texinfo.texi(,15924) In a printed manual, set a subtitle in a normal sized font flush to
15501texinfo.texi(,15925) the right-hand side of the page.  Not relevant to Info, which does not
15502texinfo.texi(,15926) have title pages.  @xref{title subtitle author, , @code{@@title}
15503texinfo.texi(,15927) @code{@@subtitle} and @code{@@author} Commands}.@refill
15504texinfo.texi(,15928)
15505texinfo.texi(,15929) @item @@summarycontents
15506texinfo.texi(,15930) Print a short table of contents.  Not relevant to Info, which uses
15507texinfo.texi(,15931) menus rather than tables of contents.  A synonym for
15508texinfo.texi(,15932) @code{@@shortcontents}.  @xref{Contents, , Generating a Table of
15509texinfo.texi(,15933) Contents}.@refill
15510texinfo.texi(,15934)
15511texinfo.texi(,15935) @item @@syncodeindex @var{from-index} @var{into-index}
15512texinfo.texi(,15936) Merge the index named in the first argument into the index named in
15513texinfo.texi(,15937) the second argument, printing the entries from the first index in
15514texinfo.texi(,15938) @code{@@code} font.  @xref{Combining Indices}.@refill
15515texinfo.texi(,15939)
15516texinfo.texi(,15940) @item @@synindex @var{from-index} @var{into-index}
15517texinfo.texi(,15941) Merge the index named in the first argument into the index named in
15518texinfo.texi(,15942) the second argument.  Do not change the font of @var{from-index}
15519texinfo.texi(,15943) entries.  @xref{Combining Indices}.@refill
15520texinfo.texi(,15944)
15521texinfo.texi(,15945) @item @@t@{@var{text}@}
15522texinfo.texi(,15946) Print @var{text} in a @t{fixed-width}, typewriter-like font.
15523texinfo.texi(,15947) No effect in Info.  @xref{Fonts}.@refill
15524texinfo.texi(,15948)
15525texinfo.texi(,15949) @item @@tab
15526texinfo.texi(,15950) Separate columns in a multitable.  @xref{Multitable Rows}.
15527texinfo.texi(,15951)
15528texinfo.texi(,15952) @item @@table @var{formatting-command}
15529texinfo.texi(,15953) Begin a two-column table, using @code{@@item} for each entry.  Write
15530texinfo.texi(,15954) each first column entry on the same line as @code{@@item}.  First
15531texinfo.texi(,15955) column entries are printed in the font resulting from
15532texinfo.texi(,15956) @var{formatting-command}.  Pair with @code{@@end table}.
15533texinfo.texi(,15957) @xref{Two-column Tables, , Making a Two-column Table}.
15534texinfo.texi(,15958) Also see @ref{ftable vtable, , @code{@@ftable} and @code{@@vtable}},
15535texinfo.texi(,15959) and @ref{itemx, , @code{@@itemx}}.@refill
15536texinfo.texi(,15960)
15537texinfo.texi(,15961) @item @@TeX@{@}
15538texinfo.texi(,15962) Insert the logo @TeX{}.  @xref{TeX and copyright, , Inserting @TeX{}
15539texinfo.texi(,15963) and @copyright{}}.@refill
15540texinfo.texi(,15964)
15541texinfo.texi(,15965) @item @@tex
15542texinfo.texi(,15966) Enter @TeX{} completely.  Pair with @code{@@end tex}.  @xref{Raw
15543texinfo.texi(,15967) Formatter Commands}.
15544texinfo.texi(,15968)
15545texinfo.texi(,15969) @item @@thischapter
15546texinfo.texi(,15970) @itemx @@thischaptername
15547texinfo.texi(,15971) @itemx @@thisfile
15548texinfo.texi(,15972) @itemx @@thispage
15549texinfo.texi(,15973) @itemx @@thistitle
15550texinfo.texi(,15974) Only allowed in a heading or footing.  Stands for the number and name of
15551texinfo.texi(,15975) the current chapter (in the format `Chapter 1: Title'), the chapter name
15552texinfo.texi(,15976) only, the filename, the current page number, and the title of the
15553texinfo.texi(,15977) document, respectively.  @xref{Custom Headings, , How to Make Your Own
15554texinfo.texi(,15978) Headings}.@refill
15555texinfo.texi(,15979)
15556texinfo.texi(,15980) @item @@tieaccent@{@var{cc}@}
15557texinfo.texi(,15981) Generate a tie-after accent over the next two characters @var{cc}, as in
15558texinfo.texi(,15982) `@tieaccent{oo}'.  @xref{Inserting Accents}.
15559texinfo.texi(,15983)
15560texinfo.texi(,15984) @item @@tindex @var{entry}
15561texinfo.texi(,15985) Add @var{entry} to the index of data types.  @xref{Index Entries, ,
15562texinfo.texi(,15986) Defining the Entries of an Index}.@refill
15563texinfo.texi(,15987)
15564texinfo.texi(,15988) @item @@title @var{title}
15565texinfo.texi(,15989) In a printed manual, set a title flush to the left-hand side of the
15566texinfo.texi(,15990) page in a larger than normal font and underline it with a black rule.
15567texinfo.texi(,15991) Not relevant to Info, which does not have title pages.  @xref{title
15568texinfo.texi(,15992) subtitle author, , The @code{@@title} @code{@@subtitle} and
15569texinfo.texi(,15993) @code{@@author} Commands}.@refill
15570texinfo.texi(,15994)
15571texinfo.texi(,15995) @item @@titlefont@{@var{text}@}
15572texinfo.texi(,15996) In a printed manual, print @var{text} in a larger than normal font.
15573texinfo.texi(,15997) Not relevant to Info, which does not have title pages.
15574texinfo.texi(,15998) @xref{titlefont center sp, , The @code{@@titlefont} @code{@@center}
15575texinfo.texi(,15999) and @code{@@sp} Commands}.@refill
15576texinfo.texi(,16000)
15577texinfo.texi(,16001) @item @@titlepage
15578texinfo.texi(,16002) Indicate to Texinfo the beginning of the title page.  Write command on
15579texinfo.texi(,16003) a line of its own.  Pair with @code{@@end titlepage}.  Nothing between
15580texinfo.texi(,16004) @code{@@titlepage} and @code{@@end titlepage} appears in Info.
15581texinfo.texi(,16005) @xref{titlepage, , @code{@@titlepage}}.@refill
15582texinfo.texi(,16006)
15583texinfo.texi(,16007) @item @@today@{@}
15584texinfo.texi(,16008) Insert the current date, in `1 Jan 1900' style.  @xref{Custom
15585texinfo.texi(,16009) Headings, , How to Make Your Own Headings}.@refill
15586texinfo.texi(,16010)
15587texinfo.texi(,16011) @item @@top @var{title}
15588texinfo.texi(,16012) In a Texinfo file to be formatted with @code{makeinfo}, identify the
15589texinfo.texi(,16013) topmost @code{@@node} in the file, which must be written on the line
15590texinfo.texi(,16014) immediately preceding the @code{@@top} command.  Used for
15591texinfo.texi(,16015) @code{makeinfo}'s node pointer insertion feature.  The title is
15592texinfo.texi(,16016) underlined with asterisks.  Both the @code{@@node} line and the @code{@@top}
15593texinfo.texi(,16017) line normally should be enclosed by @code{@@ifnottex} and @code{@@end
15594texinfo.texi(,16018) ifnottex}.  In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
15595texinfo.texi(,16019) command is merely a synonym for @code{@@unnumbered}.  @xref{makeinfo
15596texinfo.texi(,16020) Pointer Creation, , Creating Pointers with @code{makeinfo}}.
15597texinfo.texi(,16021)
15598texinfo.texi(,16022) @item @@u@{@var{c}@}
15599texinfo.texi(,16023) @itemx @@ubaraccent@{@var{c}@}
15600texinfo.texi(,16024) @itemx @@udotaccent@{@var{c}@}
15601texinfo.texi(,16025) Generate a breve, underbar, or underdot accent, respectively, over or
15602texinfo.texi(,16026) under the character @var{c}, as in @u{o}, @ubaraccent{o},
15603texinfo.texi(,16027) @udotaccent{o}.  @xref{Inserting Accents}.
15604texinfo.texi(,16028)
15605texinfo.texi(,16029) @item @@unnumbered @var{title}
15606texinfo.texi(,16030) In a printed manual, begin a chapter that appears without chapter
15607texinfo.texi(,16031) numbers of any kind.  The title appears in the table of contents of a
15608texinfo.texi(,16032) printed manual.  In Info, the title is underlined with asterisks.
15609texinfo.texi(,16033) @xref{unnumbered & appendix, , @code{@@unnumbered} and
15610texinfo.texi(,16034) @code{@@appendix}}.@refill
15611texinfo.texi(,16035)
15612texinfo.texi(,16036) @item @@unnumberedsec @var{title}
15613texinfo.texi(,16037) In a printed manual, begin a section that appears without section
15614texinfo.texi(,16038) numbers of any kind.  The title appears in the table of contents of a
15615texinfo.texi(,16039) printed manual.  In Info, the title is underlined with equal signs.
15616texinfo.texi(,16040) @xref{unnumberedsec appendixsec heading, , Section Commands}.@refill
15617texinfo.texi(,16041)
15618texinfo.texi(,16042) @item @@unnumberedsubsec @var{title}
15619texinfo.texi(,16043) In a printed manual, begin an unnumbered subsection within a
15620texinfo.texi(,16044) chapter.  The title appears in the table of contents of a printed
15621texinfo.texi(,16045) manual.  In Info, the title is underlined with hyphens.
15622texinfo.texi(,16046) @xref{unnumberedsubsec appendixsubsec subheading, ,
15623texinfo.texi(,16047) @code{@@unnumberedsubsec} @code{@@appendixsubsec}
15624texinfo.texi(,16048) @code{@@subheading}}.@refill
15625texinfo.texi(,16049)
15626texinfo.texi(,16050) @item @@unnumberedsubsubsec @var{title}
15627texinfo.texi(,16051) In a printed manual, begin an unnumbered subsubsection within a
15628texinfo.texi(,16052) chapter.  The title appears in the table of contents of a printed
15629texinfo.texi(,16053) manual.  In Info, the title is underlined with periods.
15630texinfo.texi(,16054) @xref{subsubsection, , The `subsub' Commands}.@refill
15631texinfo.texi(,16055)
15632texinfo.texi(,16056) @item @@uref@{@var{url}[, @var{displayed-text}][, @var{replacement}@}
15633texinfo.texi(,16057) Define a cross reference to an external uniform resource locator for the
15634texinfo.texi(,16058) World Wide Web.  @xref{uref, , @code{@@uref}}.@refill
15635texinfo.texi(,16059)
15636texinfo.texi(,16060) @item @@url@{@var{url}@}
15637texinfo.texi(,16061) Indicate text that is a uniform resource locator for the World Wide
15638texinfo.texi(,16062) Web.  @xref{url, , @code{@@url}}.@refill
15639texinfo.texi(,16063)
15640texinfo.texi(,16064) @item @@v@{@var{c}@}
15641texinfo.texi(,16065) Generate check accent over the character @var{c}, as in @v{o}.
15642texinfo.texi(,16066) @xref{Inserting Accents}.
15643texinfo.texi(,16067)
15644texinfo.texi(,16068) @item @@value@{@var{flag}@}
15645texinfo.texi(,16069) Replace @var{flag} with the value to which it is set by @code{@@set
15646texinfo.texi(,16070) @var{flag}}.
15647texinfo.texi(,16071) @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
15648texinfo.texi(,16072)
15649texinfo.texi(,16073) @item @@var@{@var{metasyntactic-variable}@}
15650texinfo.texi(,16074) Highlight a metasyntactic variable, which is something that stands for
15651texinfo.texi(,16075) another piece of text.  @xref{var, , Indicating Metasyntactic
15652texinfo.texi(,16076) Variables}.@refill
15653texinfo.texi(,16077)
15654texinfo.texi(,16078) @item @@verb@{@var{delim} @var{literal} @var{delim}@}
15655texinfo.texi(,16079) Output @var{literal}, delimited by the single character @var{delim},
15656texinfo.texi(,16080) exactly as is (in the fixed-width font), including any whitespace or
15657texinfo.texi(,16081) Texinfo special characters.  @xref{verb,,@code{verb}}.
15658texinfo.texi(,16082)
15659texinfo.texi(,16083) @item @@verbatim
15660texinfo.texi(,16084) Output the text of the environment exactly as is (in the fixed-width
15661texinfo.texi(,16085) font).  Pair with @code{@@end verbatim}.  @xref{verbatim,,@code{verbatim}}.
15662texinfo.texi(,16086)
15663texinfo.texi(,16087) @item @@verbatiminclude @var{filename}
15664texinfo.texi(,16088) Output the contents of @var{filename} exactly as is (in the fixed-width font).
15665texinfo.texi(,16089) @xref{verbatiminclude,,@code{verbatiminclude}}.
15666texinfo.texi(,16090)
15667texinfo.texi(,16091) @item @@vindex @var{entry}
15668texinfo.texi(,16092) Add @var{entry} to the index of variables.  @xref{Index Entries, ,
15669texinfo.texi(,16093) Defining the Entries of an Index}.@refill
15670texinfo.texi(,16094)
15671texinfo.texi(,16095) @item @@vskip @var{amount}
15672texinfo.texi(,16096) In a printed manual, insert whitespace so as to push text on the
15673texinfo.texi(,16097) remainder of the page towards the bottom of the page.  Used in
15674texinfo.texi(,16098) formatting the copyright page with the argument @samp{0pt plus
15675texinfo.texi(,16099) 1filll}.  (Note spelling of @samp{filll}.)  @code{@@vskip} may be used
15676texinfo.texi(,16100) only in contexts ignored for Info.  @xref{Copyright}.
15677texinfo.texi(,16101)
15678texinfo.texi(,16102) @item @@vtable @var{formatting-command}
15679texinfo.texi(,16103) Begin a two-column table, using @code{@@item} for each entry.
15680texinfo.texi(,16104) Automatically enter each of the items in the first column into the
15681texinfo.texi(,16105) index of variables.  Pair with @code{@@end vtable}.  The same as
15682texinfo.texi(,16106) @code{@@table}, except for indexing.  @xref{ftable vtable, ,
15683texinfo.texi(,16107) @code{@@ftable} and @code{@@vtable}}.@refill
15684texinfo.texi(,16108)
15685texinfo.texi(,16109) @item @@w@{@var{text}@}
15686texinfo.texi(,16110) Prevent @var{text} from being split across two lines.  Do not end a
15687texinfo.texi(,16111) paragraph that uses @code{@@w} with an @code{@@refill} command.
15688texinfo.texi(,16112) @xref{w, , @code{@@w}}.@refill
15689texinfo.texi(,16113)
15690texinfo.texi(,16114) @item @@xref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
15691texinfo.texi(,16115) Make a reference that starts with `See' in a printed manual.  Follow
15692texinfo.texi(,16116) command with a punctuation mark.  Only the first argument is
15693texinfo.texi(,16117) mandatory.  @xref{xref, , @code{@@xref}}.@refill
15694texinfo.texi(,16118) @end table
15695texinfo.texi(,16119)
15696texinfo.texi(,16120)
15697texinfo.texi(,16121) @node Tips
15698texinfo.texi(,16122) @appendix Tips and Hints
15699texinfo.texi(,16123)
15700texinfo.texi(,16124) Here are some tips for writing Texinfo documentation:@refill
15701texinfo.texi(,16125)
15702texinfo.texi(,16126) @cindex Tips
15703texinfo.texi(,16127) @cindex Usage tips
15704texinfo.texi(,16128) @cindex Hints
15705texinfo.texi(,16129) @itemize @bullet
15706texinfo.texi(,16130) @item
15707texinfo.texi(,16131) Write in the present tense, not in the past or the future.
15708texinfo.texi(,16132)
15709texinfo.texi(,16133) @item
15710texinfo.texi(,16134) Write actively!  For example, write ``We recommend that @dots{}'' rather
15711texinfo.texi(,16135) than ``It is recommended that @dots{}''.
15712texinfo.texi(,16136)
15713texinfo.texi(,16137) @item
15714texinfo.texi(,16138) Use 70 or 72 as your fill column.  Longer lines are hard to read.
15715texinfo.texi(,16139)
15716texinfo.texi(,16140) @item
15717texinfo.texi(,16141) Include a copyright notice and copying permissions.
15718texinfo.texi(,16142) @end itemize
15719texinfo.texi(,16143)
15720texinfo.texi(,16144) @subsubheading Index, Index, Index!
15721texinfo.texi(,16145)
15722texinfo.texi(,16146) Write many index entries, in different ways.
15723texinfo.texi(,16147) Readers like indices; they are helpful and convenient.
15724texinfo.texi(,16148)
15725texinfo.texi(,16149) Although it is easiest to write index entries as you write the body of
15726texinfo.texi(,16150) the text, some people prefer to write entries afterwards.  In either
15727texinfo.texi(,16151) case, write an entry before the paragraph to which it applies.  This
15728texinfo.texi(,16152) way, an index entry points to the first page of a paragraph that is
15729texinfo.texi(,16153) split across pages.
15730texinfo.texi(,16154)
15731texinfo.texi(,16155) Here are more hints we have found valuable:
15732texinfo.texi(,16156)
15733texinfo.texi(,16157) @itemize @bullet
15734texinfo.texi(,16158) @item
15735texinfo.texi(,16159) Write each index entry differently, so each entry refers to a different
15736texinfo.texi(,16160) place in the document.
15737texinfo.texi(,16161)
15738texinfo.texi(,16162) @item
15739texinfo.texi(,16163) Write index entries only where a topic is discussed significantly.  For
15740texinfo.texi(,16164) example, it is not useful to index ``debugging information'' in a
15741texinfo.texi(,16165) chapter on reporting bugs.  Someone who wants to know about debugging
15742texinfo.texi(,16166) information will certainly not find it in that chapter.
15743texinfo.texi(,16167)
15744texinfo.texi(,16168) @item
15745texinfo.texi(,16169) Consistently capitalize the first word of every concept index entry,
15746texinfo.texi(,16170) or else consistently use lower case.  Terse entries often call for
15747texinfo.texi(,16171) lower case; longer entries for capitalization.  Whichever case
15748texinfo.texi(,16172) convention you use, please use one or the other consistently!  Mixing
15749texinfo.texi(,16173) the two styles looks bad.
15750texinfo.texi(,16174)
15751texinfo.texi(,16175) @item
15752texinfo.texi(,16176) Always capitalize or use upper case for those words in an index for
15753texinfo.texi(,16177) which this is proper, such as names of countries or acronyms.  Always
15754texinfo.texi(,16178) use the appropriate case for case-sensitive names, such as those in C or
15755texinfo.texi(,16179) Lisp.
15756texinfo.texi(,16180)
15757texinfo.texi(,16181) @item
15758texinfo.texi(,16182) Write the indexing commands that refer to a whole section immediately
15759texinfo.texi(,16183) after the section command, and write the indexing commands that refer to
15760texinfo.texi(,16184) a paragraph before that paragraph.
15761texinfo.texi(,16185)
15762texinfo.texi(,16186) In the example that follows, a blank line comes after the index
15763texinfo.texi(,16187) entry for ``Leaping'':
15764texinfo.texi(,16188)
15765texinfo.texi(,16189) @example
15766texinfo.texi(,16190) @group
15767texinfo.texi(,16191) @@section The Dog and the Fox
15768texinfo.texi(,16192) @@cindex Jumping, in general
15769texinfo.texi(,16193) @@cindex Leaping
15770texinfo.texi(,16194)
15771texinfo.texi(,16195) @@cindex Dog, lazy, jumped over
15772texinfo.texi(,16196) @@cindex Lazy dog jumped over
15773texinfo.texi(,16197) @@cindex Fox, jumps over dog
15774texinfo.texi(,16198) @@cindex Quick fox jumps over dog
15775texinfo.texi(,16199) The quick brown fox jumps over the lazy dog.
15776texinfo.texi(,16200) @end group
15777texinfo.texi(,16201) @end example
15778texinfo.texi(,16202)
15779texinfo.texi(,16203) @noindent
15780texinfo.texi(,16204) (Note that the example shows entries for the same concept that are
15781texinfo.texi(,16205) written in different ways---@samp{Lazy dog}, and @samp{Dog, lazy}---so
15782texinfo.texi(,16206) readers can look up the concept in different ways.)
15783texinfo.texi(,16207) @end itemize
15784texinfo.texi(,16208)
15785texinfo.texi(,16209) @subsubheading Blank Lines
15786texinfo.texi(,16210)
15787texinfo.texi(,16211) @itemize @bullet
15788texinfo.texi(,16212) @item
15789texinfo.texi(,16213) Insert a blank line between a sectioning command and the first following
15790texinfo.texi(,16214) sentence or paragraph, or between the indexing commands associated with
15791texinfo.texi(,16215) the sectioning command and the first following sentence or paragraph, as
15792texinfo.texi(,16216) shown in the tip on indexing.  Otherwise, a formatter may fold title and
15793texinfo.texi(,16217) paragraph together.
15794texinfo.texi(,16218)
15795texinfo.texi(,16219) @item
15796texinfo.texi(,16220) Always insert a blank line before an @code{@@table} command and after an
15797texinfo.texi(,16221) @code{@@end table} command; but never insert a blank line after an
15798texinfo.texi(,16222) @code{@@table} command or before an @code{@@end table} command.
15799texinfo.texi(,16223)
15800texinfo.texi(,16224) @need 1000
15801texinfo.texi(,16225) For example,
15802texinfo.texi(,16226)
15803texinfo.texi(,16227) @example
15804texinfo.texi(,16228) @group
15805texinfo.texi(,16229) Types of fox:
15806texinfo.texi(,16230)
15807texinfo.texi(,16231) @@table @@samp
15808texinfo.texi(,16232) @@item Quick
15809texinfo.texi(,16233) Jump over lazy dogs.
15810texinfo.texi(,16234) @end group
15811texinfo.texi(,16235)
15812texinfo.texi(,16236) @group
15813texinfo.texi(,16237) @@item Brown
15814texinfo.texi(,16238) Also jump over lazy dogs.
15815texinfo.texi(,16239) @@end table
15816texinfo.texi(,16240)
15817texinfo.texi(,16241) @end group
15818texinfo.texi(,16242) @group
15819texinfo.texi(,16243) @@noindent
15820texinfo.texi(,16244) On the other hand, @dots{}
15821texinfo.texi(,16245) @end group
15822texinfo.texi(,16246) @end example
15823texinfo.texi(,16247)
15824texinfo.texi(,16248) Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end
15825texinfo.texi(,16249) itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the
15826texinfo.texi(,16250) same way.
15827texinfo.texi(,16251) @end itemize
15828texinfo.texi(,16252)
15829texinfo.texi(,16253) @subsubheading Complete Phrases
15830texinfo.texi(,16254)
15831texinfo.texi(,16255) Complete phrases are easier to read than @dots{}
15832texinfo.texi(,16256)
15833texinfo.texi(,16257) @itemize @bullet
15834texinfo.texi(,16258) @item
15835texinfo.texi(,16259) Write entries in an itemized list as complete sentences; or at least, as
15836texinfo.texi(,16260) complete phrases.  Incomplete expressions @dots{} awkward @dots{} like
15837texinfo.texi(,16261) this.
15838texinfo.texi(,16262)
15839texinfo.texi(,16263) @item
15840texinfo.texi(,16264) Write the prefatory sentence or phrase for a multi-item list or table as
15841texinfo.texi(,16265) a complete expression.  Do not write ``You can set:''; instead, write
15842texinfo.texi(,16266) ``You can set these variables:''.  The former expression sounds cut off.
15843texinfo.texi(,16267) @end itemize
15844texinfo.texi(,16268)
15845texinfo.texi(,16269) @subsubheading Editions, Dates and Versions
15846texinfo.texi(,16270)
15847texinfo.texi(,16271) Include edition numbers, version numbers, and dates in the
15848texinfo.texi(,16272) @code{@@copying} text (for people reading the Texinfo file, and for the
15849texinfo.texi(,16273) legal copyright in the output files).  Then use @code{@@insertcopying}
15850texinfo.texi(,16274) in the @code{@@titlepage} section (for people reading the printed
15851texinfo.texi(,16275) output) and the Top node (for people reading the online output).
15852texinfo.texi(,16276)
15853texinfo.texi(,16277) It is easiest to do this using @code{@@set} and @code{@@value}.
15854texinfo.texi(,16278) @xref{value Example, , @code{@@value} Example}, and @ref{GNU Sample Texts}.
15855texinfo.texi(,16279)
15856texinfo.texi(,16280)
15857texinfo.texi(,16281) @subsubheading Definition Commands
15858texinfo.texi(,16282)
15859texinfo.texi(,16283) Definition commands are @code{@@deffn}, @code{@@defun},
15860texinfo.texi(,16284) @code{@@defmac}, and the like, and enable you to write descriptions in
15861texinfo.texi(,16285) a uniform format.@refill
15862texinfo.texi(,16286)
15863texinfo.texi(,16287) @itemize @bullet
15864texinfo.texi(,16288) @item
15865texinfo.texi(,16289) Write just one definition command for each entity you define with a
15866texinfo.texi(,16290) definition command.  The automatic indexing feature creates an index
15867texinfo.texi(,16291) entry that leads the reader to the definition.
15868texinfo.texi(,16292)
15869texinfo.texi(,16293) @item
15870texinfo.texi(,16294) Use @code{@@table} @dots{} @code{@@end table} in an appendix that
15871texinfo.texi(,16295) contains a summary of functions, not @code{@@deffn} or other definition
15872texinfo.texi(,16296) commands.
15873texinfo.texi(,16297) @end itemize
15874texinfo.texi(,16298)
15875texinfo.texi(,16299) @subsubheading Capitalization
15876texinfo.texi(,16300)
15877texinfo.texi(,16301) @itemize @bullet
15878texinfo.texi(,16302) @item
15879texinfo.texi(,16303) Capitalize ``Texinfo''; it is a name.  Do not write the @samp{x} or
15880texinfo.texi(,16304) @samp{i} in upper case.
15881texinfo.texi(,16305)
15882texinfo.texi(,16306) @item
15883texinfo.texi(,16307) Capitalize ``Info''; it is a name.
15884texinfo.texi(,16308)
15885texinfo.texi(,16309) @item
15886texinfo.texi(,16310) Write @TeX{} using the @code{@@TeX@{@}} command.  Note the uppercase
15887texinfo.texi(,16311) @samp{T} and @samp{X}.  This command causes the formatters to
15888texinfo.texi(,16312) typeset the name according to the wishes of Donald Knuth, who wrote
15889texinfo.texi(,16313) @TeX{}.
15890texinfo.texi(,16314) @end itemize
15891texinfo.texi(,16315)
15892texinfo.texi(,16316) @subsubheading Spaces
15893texinfo.texi(,16317)
15894texinfo.texi(,16318) Do not use spaces to format a Texinfo file, except inside of
15895texinfo.texi(,16319) @code{@@example} @dots{} @code{@@end example} and similar commands.
15896texinfo.texi(,16320)
15897texinfo.texi(,16321) @need 700
15898texinfo.texi(,16322) For example, @TeX{} fills the following:
15899texinfo.texi(,16323)
15900texinfo.texi(,16324) @example
15901texinfo.texi(,16325) @group
15902texinfo.texi(,16326)     @@kbd@{C-x v@}
15903texinfo.texi(,16327)     @@kbd@{M-x vc-next-action@}
15904texinfo.texi(,16328)        Perform the next logical operation
15905texinfo.texi(,16329)        on the version-controlled file
15906texinfo.texi(,16330)        corresponding to the current buffer.
15907texinfo.texi(,16331) @end group
15908texinfo.texi(,16332) @end example
15909texinfo.texi(,16333)
15910texinfo.texi(,16334) @need 950
15911texinfo.texi(,16335) @noindent
15912texinfo.texi(,16336) so it looks like this:
15913texinfo.texi(,16337)
15914texinfo.texi(,16347) @quotation
15915texinfo.texi(,16348) `C-x v' `M-x vc-next-action' Perform the next logical operation on the
15916texinfo.texi(,16349) version-controlled file corresponding to the current buffer.
15917texinfo.texi(,16350) @end quotation
15918texinfo.texi(,16352)
15919texinfo.texi(,16353) @noindent
15920texinfo.texi(,16354) In this case, the text should be formatted with
15921texinfo.texi(,16355) @code{@@table}, @code{@@item}, and @code{@@itemx}, to create a table.
15922texinfo.texi(,16356)
15923texinfo.texi(,16357) @subsubheading @@code, @@samp, @@var, and @samp{---}
15924texinfo.texi(,16358)
15925texinfo.texi(,16359) @itemize @bullet
15926texinfo.texi(,16360) @item
15927texinfo.texi(,16361) Use @code{@@code} around Lisp symbols, including command names.
15928texinfo.texi(,16362) For example,
15929texinfo.texi(,16363)
15930texinfo.texi(,16364) @example
15931texinfo.texi(,16365) The main function is @@code@{vc-next-action@}, @dots{}
15932texinfo.texi(,16366) @end example
15933texinfo.texi(,16367)
15934texinfo.texi(,16368) @item
15935texinfo.texi(,16369) Avoid putting letters such as @samp{s} immediately after an
15936texinfo.texi(,16370) @samp{@@code}.  Such letters look bad.
15937texinfo.texi(,16371)
15938texinfo.texi(,16372) @item
15939texinfo.texi(,16373) Use @code{@@var} around meta-variables.  Do not write angle brackets
15940texinfo.texi(,16374) around them.
15941texinfo.texi(,16375)
15942texinfo.texi(,16376) @item
15943texinfo.texi(,16377) Use three hyphens in a row, @samp{---}, to indicate a long dash.  @TeX{}
15944texinfo.texi(,16378) typesets these as a long dash and the Info formatters reduce three
15945texinfo.texi(,16379) hyphens to two.
15946texinfo.texi(,16380) @end itemize
15947texinfo.texi(,16381)
15948texinfo.texi(,16382) @subsubheading Periods Outside of Quotes
15949texinfo.texi(,16383)
15950texinfo.texi(,16384) Place periods and other punctuation marks @emph{outside} of quotations,
15951texinfo.texi(,16385) unless the punctuation is part of the quotation.  This practice goes
15952texinfo.texi(,16386) against publishing conventions in the United States, but enables the
15953texinfo.texi(,16387) reader to distinguish between the contents of the quotation and the
15954texinfo.texi(,16388) whole passage.
15955texinfo.texi(,16389)
15956texinfo.texi(,16390) For example, you should write the following sentence with the period
15957texinfo.texi(,16391) outside the end quotation marks:
15958texinfo.texi(,16392)
15959texinfo.texi(,16393) @example
15960texinfo.texi(,16394) Evidently, @samp{au} is an abbreviation for ``author''.
15961texinfo.texi(,16395) @end example
15962texinfo.texi(,16396)
15963texinfo.texi(,16397) @noindent
15964texinfo.texi(,16398) since @samp{au} does @emph{not} serve as an  abbreviation for
15965texinfo.texi(,16399) @samp{author.} (with a period following the word).
15966texinfo.texi(,16400)
15967texinfo.texi(,16401) @subsubheading Introducing New Terms
15968texinfo.texi(,16402)
15969texinfo.texi(,16403) @itemize @bullet
15970texinfo.texi(,16404) @item
15971texinfo.texi(,16405) Introduce new terms so that a reader who does not know them can
15972texinfo.texi(,16406) understand them from context; or write a definition for the term.
15973texinfo.texi(,16407)
15974texinfo.texi(,16408) For example, in the following, the terms ``check in'', ``register'' and
15975texinfo.texi(,16409) ``delta'' are all appearing for the first time; the example sentence should be
15976texinfo.texi(,16410) rewritten so they are understandable.
15977texinfo.texi(,16411)
15978texinfo.texi(,16412) @quotation
15979texinfo.texi(,16413) The major function assists you in checking in a file to your
15980texinfo.texi(,16414) version control system and registering successive sets of changes to
15981texinfo.texi(,16415) it as deltas.
15982texinfo.texi(,16416) @end quotation
15983texinfo.texi(,16417)
15984texinfo.texi(,16418) @item
15985texinfo.texi(,16419) Use the @code{@@dfn} command around a word being introduced, to indicate
15986texinfo.texi(,16420) that the reader should not expect to know the meaning already, and
15987texinfo.texi(,16421) should expect to learn the meaning from this passage.
15988texinfo.texi(,16422) @end itemize
15989texinfo.texi(,16423)
15990texinfo.texi(,16424) @subsubheading @@pxref
15991texinfo.texi(,16425)
15992texinfo.texi(,16426) @c !!! maybe include this in the tips on pxref
15993texinfo.texi(,16434) Absolutely never use @code{@@pxref} except in the special context for
15994texinfo.texi(,16435) which it is designed: inside parentheses, with the closing parenthesis
15995texinfo.texi(,16436) following immediately after the closing brace.  One formatter
15996texinfo.texi(,16437) automatically inserts closing punctuation and the other does not.  This
15997texinfo.texi(,16438) means that the output looks right both in printed output and in an Info
15998texinfo.texi(,16439) file, but only when the command is used inside parentheses.
15999texinfo.texi(,16440)
16000texinfo.texi(,16441) @subsubheading Invoking from a Shell
16001texinfo.texi(,16442)
16002texinfo.texi(,16443) You can invoke programs such as Emacs, GCC, and @code{gawk} from a
16003texinfo.texi(,16444) shell.  The documentation for each program should contain a section that
16004texinfo.texi(,16445) describes this.  Unfortunately, if the node names and titles for these
16005texinfo.texi(,16446) sections are all different, they are difficult for users to find.
16006texinfo.texi(,16447)
16007texinfo.texi(,16448) So, there is a convention to name such sections with a phrase beginning
16008texinfo.texi(,16449) with the word `Invoking', as in `Invoking Emacs'; this way, users can
16009texinfo.texi(,16450) find the section easily.
16010texinfo.texi(,16451)
16011texinfo.texi(,16452)
16012texinfo.texi(,16453) @subsubheading ANSI C Syntax
16013texinfo.texi(,16454)
16014texinfo.texi(,16455) When you use @code{@@example} to describe a C function's calling
16015texinfo.texi(,16456) conventions, use the ANSI C syntax, like this:@refill
16016texinfo.texi(,16457)
16017texinfo.texi(,16458) @example
16018texinfo.texi(,16459) void dld_init (char *@@var@{path@});
16019texinfo.texi(,16460) @end example
16020texinfo.texi(,16461)
16021texinfo.texi(,16462) @noindent
16022texinfo.texi(,16463) And in the subsequent discussion, refer to the argument values by
16023texinfo.texi(,16464) writing the same argument names, again highlighted with
16024texinfo.texi(,16465) @code{@@var}.@refill
16025texinfo.texi(,16466)
16026texinfo.texi(,16467) @need 800
16027texinfo.texi(,16468) Avoid the obsolete style that looks like this:@refill
16028texinfo.texi(,16469)
16029texinfo.texi(,16470) @example
16030texinfo.texi(,16471) #include <dld.h>
16031texinfo.texi(,16472)
16032texinfo.texi(,16473) dld_init (path)
16033texinfo.texi(,16474) char *path;
16034texinfo.texi(,16475) @end example
16035texinfo.texi(,16476)
16036texinfo.texi(,16477) Also, it is best to avoid writing @code{#include} above the
16037texinfo.texi(,16478) declaration just to indicate that the function is declared in a
16038texinfo.texi(,16479) header file.  The practice may give the misimpression that the
16039texinfo.texi(,16480) @code{#include} belongs near the declaration of the function.  Either
16040texinfo.texi(,16481) state explicitly which header file holds the declaration or, better
16041texinfo.texi(,16482) yet, name the header file used for a group of functions at the
16042texinfo.texi(,16483) beginning of the section that describes the functions.@refill
16043texinfo.texi(,16484)
16044texinfo.texi(,16485) @subsubheading Bad Examples
16045texinfo.texi(,16486)
16046texinfo.texi(,16487) Here are several examples of bad writing to avoid:
16047texinfo.texi(,16488)
16048texinfo.texi(,16489) In this example, say, `` @dots{} you must @code{@@dfn}@{check
16049texinfo.texi(,16490) in@} the new version.''  That flows better.
16050texinfo.texi(,16491)
16051texinfo.texi(,16492) @quotation
16052texinfo.texi(,16493) When you are done editing the file, you must perform a
16053texinfo.texi(,16494) @code{@@dfn}@{check in@}.
16054texinfo.texi(,16495) @end quotation
16055texinfo.texi(,16496)
16056texinfo.texi(,16497) In the following example, say, ``@dots{} makes a unified interface such as VC
16057texinfo.texi(,16498) mode possible.''
16058texinfo.texi(,16499)
16059texinfo.texi(,16500) @quotation
16060texinfo.texi(,16501) SCCS, RCS and other version-control systems all perform similar
16061texinfo.texi(,16502) functions in broadly similar ways (it is this resemblance which makes
16062texinfo.texi(,16503) a unified control mode like this possible).
16063texinfo.texi(,16504) @end quotation
16064texinfo.texi(,16505)
16065texinfo.texi(,16506) And in this example, you should specify what `it' refers to:
16066texinfo.texi(,16507)
16067texinfo.texi(,16508) @quotation
16068texinfo.texi(,16509) If you are working with other people, it assists in coordinating
16069texinfo.texi(,16510) everyone's changes so they do not step on each other.
16070texinfo.texi(,16511) @end quotation
16071texinfo.texi(,16512)
16072texinfo.texi(,16513) @subsubheading And Finally @dots{}
16073texinfo.texi(,16514)
16074texinfo.texi(,16515) @itemize @bullet
16075texinfo.texi(,16516) @item
16076texinfo.texi(,16517) Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last
16077texinfo.texi(,16518) sound in the name `Bach'.  But pronounce Texinfo as in `speck':
16078texinfo.texi(,16519) ``teckinfo''.
16079texinfo.texi(,16520)
16080texinfo.texi(,16521) @item
16081texinfo.texi(,16522) Write notes for yourself at the very end of a Texinfo file after the
16082texinfo.texi(,16523) @code{@@bye}.  None of the formatters process text after the
16083texinfo.texi(,16524) @code{@@bye}; it is as if the text were within @code{@@ignore} @dots{}
16084texinfo.texi(,16525) @code{@@end ignore}.
16085texinfo.texi(,16526) @end itemize
16086texinfo.texi(,16527)
16087texinfo.texi(,16528)
16088texinfo.texi(,16529) @node Sample Texinfo Files
16089texinfo.texi(,16530) @appendix Sample Texinfo Files
16090texinfo.texi(,16531) @cindex Sample Texinfo files
16091texinfo.texi(,16532)
16092texinfo.texi(,16533) The first example is from the first chapter (@pxref{Short Sample}),
16093texinfo.texi(,16534) given here in its entirety, without commentary.  The second sample
16094texinfo.texi(,16535) includes the full texts to be used in GNU manuals.
16095texinfo.texi(,16536)
16096texinfo.texi(,16537) @menu
16097texinfo.texi(,16538) * Short Sample Texinfo File::
16098texinfo.texi(,16539) * GNU Sample Texts::
16099texinfo.texi(,16540) @end menu
16100texinfo.texi(,16541)
16101texinfo.texi(,16542)
16102texinfo.texi(,16543) @node Short Sample Texinfo File
16103texinfo.texi(,16544) @section Short Sample
16104texinfo.texi(,16545) @cindex Sample Texinfo file, no comments
16105texinfo.texi(,16546)
16106texinfo.texi(,16547) Here is a complete, short sample Texinfo file, without any commentary.
16107texinfo.texi(,16548) You can see this file, with comments, in the first chapter.  @xref{Short
16108texinfo.texi(,16549) Sample}.
16109texinfo.texi(,16550)
16110texinfo.texi(,16551) In a nutshell: The @command{makeinfo} program transforms a Texinfo
16111texinfo.texi(,16552) source file such as this into an Info file or HTML; and @TeX{} typesets
16112texinfo.texi(,16553) it for a printed manual.
16113texinfo.texi(,16554)
16114texinfo.texi(,16555)
16115texinfo.texi(,16556) @sp 1
16116texinfo.texi(,16557) @example
16117texinfo.texi(,16558) \input texinfo   @@c -*-texinfo-*-
16118texinfo.texi(,16559) @@c %**start of header
16119texinfo.texi(,16560) @@setfilename sample.info
16120texinfo.texi(,16561) @@settitle Sample Manual 1.0
16121texinfo.texi(,16562) @@c %**end of header
16122texinfo.texi(,16563)
16123texinfo.texi(,16564) @@copying
16124texinfo.texi(,16565) This is a short example of a complete Texinfo file.
16125texinfo.texi(,16566)
16126texinfo.texi(,16567) Copyright (C) 2002 Free Software Foundation, Inc.
16127texinfo.texi(,16568) @@end copying
16128texinfo.texi(,16569)
16129texinfo.texi(,16570) @@titlepage
16130texinfo.texi(,16571) @@title Sample Title
16131texinfo.texi(,16572) @@page
16132texinfo.texi(,16573) @@vskip 0pt plus 1filll
16133texinfo.texi(,16574) @@insertcopying
16134texinfo.texi(,16575) @@end titlepage
16135texinfo.texi(,16576)
16136texinfo.texi(,16577) @@c Output the table of the contents at the beginning.
16137texinfo.texi(,16578) @@contents
16138texinfo.texi(,16579)
16139texinfo.texi(,16580) @@ifnottex
16140texinfo.texi(,16581) @@node Top
16141texinfo.texi(,16582)
16142texinfo.texi(,16583) @@insertcopying
16143texinfo.texi(,16584) @@end ifnottex
16144texinfo.texi(,16585)
16145texinfo.texi(,16586) @@menu
16146texinfo.texi(,16587) * First Chapter::    The first chapter is the
16147texinfo.texi(,16588)                        only chapter in this sample.
16148texinfo.texi(,16589) * Index::            Complete index.
16149texinfo.texi(,16590) @@end menu
16150texinfo.texi(,16591)
16151texinfo.texi(,16592)
16152texinfo.texi(,16593) @@node First Chapter
16153texinfo.texi(,16594) @@chapter First Chapter
16154texinfo.texi(,16595)
16155texinfo.texi(,16596) @@cindex chapter, first
16156texinfo.texi(,16597)
16157texinfo.texi(,16598) This is the first chapter.
16158texinfo.texi(,16599) @@cindex index entry, another
16159texinfo.texi(,16600)
16160texinfo.texi(,16601) Here is a numbered list.
16161texinfo.texi(,16602)
16162texinfo.texi(,16603) @@enumerate
16163texinfo.texi(,16604) @@item
16164texinfo.texi(,16605) This is the first item.
16165texinfo.texi(,16606)
16166texinfo.texi(,16607) @@item
16167texinfo.texi(,16608) This is the second item.
16168texinfo.texi(,16609) @@end enumerate
16169texinfo.texi(,16610)
16170texinfo.texi(,16611)
16171texinfo.texi(,16612) @@node Index
16172texinfo.texi(,16613) @@unnumbered Index
16173texinfo.texi(,16614)
16174texinfo.texi(,16615) @@printindex cp
16175texinfo.texi(,16616)
16176texinfo.texi(,16617) @@bye
16177texinfo.texi(,16618) @end example
16178texinfo.texi(,16619)
16179texinfo.texi(,16620)
16180texinfo.texi(,16621) @node GNU Sample Texts
16181texinfo.texi(,16622) @section GNU Sample Texts
16182texinfo.texi(,16623)
16183texinfo.texi(,16624) @cindex GNU sample texts
16184texinfo.texi(,16625) @cindex Sample texts, GNU
16185texinfo.texi(,16626) @cindex Full texts, GNU
16186texinfo.texi(,16627)
16187texinfo.texi(,16628) Here is a sample Texinfo document with the full texts that should be
16188texinfo.texi(,16629) used in GNU manuals.
16189texinfo.texi(,16630)
16190texinfo.texi(,16631) As well as the legal texts, it also serves as a practical example of how
16191texinfo.texi(,16632) many elements in a GNU system can affect the manual.  If you're not
16192texinfo.texi(,16633) familiar with all these different elements, don't worry.  They're not
16193texinfo.texi(,16634) required and a perfectly good manual can be written without them.
16194texinfo.texi(,16635) They're included here nonetheless because many manuals do (or could)
16195texinfo.texi(,16636) benefit from them.
16196texinfo.texi(,16637)
16197texinfo.texi(,16638) @xref{Short Sample}, for a minimal example of a Texinfo file.
16198texinfo.texi(,16639) @xref{Beginning a File}, for a full explanation of that minimal
16199texinfo.texi(,16640) example.
16200texinfo.texi(,16641)
16201texinfo.texi(,16642) Here are some notes on the example:
16202texinfo.texi(,16643)
16203texinfo.texi(,16644) @itemize @bullet
16204texinfo.texi(,16645) @item
16205texinfo.texi(,16646) @cindex $ @c Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $ comment
16206texinfo.texi(,16647) @cindex CVS Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $, in Texinfo
16207texinfo.texi(,16648) @cindex RCS Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $, in Texinfo
16208texinfo.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,
16209texinfo.texi(,16650) Concurrent Versions System}) or RCS (see rcsintro(1)) version control
16210texinfo.texi(,16651) systems, which expand it into a string such as:
16211texinfo.texi(,16652) @example
16212texinfo.texi(,16653) Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $
16213texinfo.texi(,16654) @end example
16214texinfo.texi(,16655) (This is useful in all sources that use version control, not just manuals.)
16215texinfo.texi(,16656)
16216texinfo.texi(,16657) @item
16217texinfo.texi(,16658) @pindex automake@r{, and version info}
16218texinfo.texi(,16659) The @file{version.texi} in the @code{@@include} command is maintained
16219texinfo.texi(,16660) automatically by Automake (@pxref{Top,, Introduction, automake, GNU
16220texinfo.texi(,16661) Automake}).  It sets the @samp{VERSION} and @samp{UPDATED} values used
16221texinfo.texi(,16662) elsewhere.  If your distribution doesn't use Automake, you can mimic
16222texinfo.texi(,16663) these or equivalent settings.
16223texinfo.texi(,16664)
16224texinfo.texi(,16665) @item
16225texinfo.texi(,16666) The @code{@@syncodeindex} command reflects the recommendation to use only
16226texinfo.texi(,16667) one index if at all possible, to make it easier for readers.
16227texinfo.texi(,16668)
16228texinfo.texi(,16669) @item
16229texinfo.texi(,16670) The @code{@@dircategory} is for constructing the Info directory.
16230texinfo.texi(,16671) @xref{Installing Dir Entries}, which includes a variety of recommended
16231texinfo.texi(,16672) category names.
16232texinfo.texi(,16673)
16233texinfo.texi(,16674) @item
16234texinfo.texi(,16675) The `Invoking' node is a GNU standard to help users find the basic
16235texinfo.texi(,16676) information about command-line usage of a given program.  @xref{Manual
16236texinfo.texi(,16677) Structure Details,,,standards, GNU Coding Standards}.
16237texinfo.texi(,16678)
16238texinfo.texi(,16679) @item
16239texinfo.texi(,16680) It is best to include the entire GNU Free Documentation License in a GNU
16240texinfo.texi(,16681) manual, unless the manual is only a few pages long.  Of course this
16241texinfo.texi(,16682) sample is even shorter than that, but it includes the FDL anyway in
16242texinfo.texi(,16683) order to show one conventional way of doing so.  The @file{fdl.texi}
16243texinfo.texi(,16684) file is available on the GNU machines (and in the Texinfo and other GNU
16244texinfo.texi(,16685) distributions).
16245texinfo.texi(,16686)
16246texinfo.texi(,16687) The FDL provides for omitting itself under certain conditions, but in
16247texinfo.texi(,16688) that case the sample texts given here have to be modified.  @xref{GNU
16248texinfo.texi(,16689) Free Documentation License}.
16249texinfo.texi(,16690)
16250texinfo.texi(,16691) @item
16251texinfo.texi(,16692) If your manual has invariant sections (again, see the license itself for
16252texinfo.texi(,16693) details), then don't forget to include them.
16253texinfo.texi(,16694) @end itemize
16254texinfo.texi(,16695)
16255texinfo.texi(,16696) Here is the sample document:
16256texinfo.texi(,16697)
16257texinfo.texi(,16698) @c We do the first part of this with @example instead of @verbatim
16258texinfo.texi(,16699) @c because the literal @setfilename and @include confuse Automake.  Argh.
16259texinfo.texi(,16700) @example
16260texinfo.texi(,16701) \input texinfo    @@c -*-texinfo-*-
16261texinfo.texi(,16702) @@comment Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $
16262texinfo.texi(,16703) @@comment %**start of header
16263texinfo.texi(,16704) @@setfilename sample.info
16264texinfo.texi(,16705) @@include version.texi
16265texinfo.texi(,16706) @@settitle GNU Sample @@value@{VERSION@}
16266texinfo.texi(,16707) @@syncodeindex pg cp
16267texinfo.texi(,16708) @@comment %**end of header
16268texinfo.texi(,16709) @@copying
16269texinfo.texi(,16710) This manual is for GNU Sample
16270texinfo.texi(,16711) (version @@value@{VERSION@}, @@value@{UPDATED@}),
16271texinfo.texi(,16712) which is an example in the Texinfo documentation.
16272texinfo.texi(,16713)
16273texinfo.texi(,16714) Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
16274texinfo.texi(,16715)
16275texinfo.texi(,16716) @@quotation
16276texinfo.texi(,16717) Permission is granted to copy, distribute and/or modify this document
16277texinfo.texi(,16718) under the terms of the GNU Free Documentation License, Version 1.1 or
16278texinfo.texi(,16719) any later version published by the Free Software Foundation; with no
16279texinfo.texi(,16720) Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
16280texinfo.texi(,16721) and with the Back-Cover Texts as in (a) below.  A copy of the
16281texinfo.texi(,16722) license is included in the section entitled ``GNU Free Documentation
16282texinfo.texi(,16723) License.''
16283texinfo.texi(,16724)
16284texinfo.texi(,16725) (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
16285texinfo.texi(,16726) this GNU Manual, like GNU software.  Copies published by the Free
16286texinfo.texi(,16727) Software Foundation raise funds for GNU development.''
16287texinfo.texi(,16728) @@end quotation
16288texinfo.texi(,16729) @@end copying
16289texinfo.texi(,16730)
16290texinfo.texi(,16731) @@dircategory Texinfo documentation system
16291texinfo.texi(,16732) @@direntry
16292texinfo.texi(,16733) * sample: (sample)Invoking sample.
16293texinfo.texi(,16734) @@end direntry
16294texinfo.texi(,16735)
16295texinfo.texi(,16736) @@titlepage
16296texinfo.texi(,16737) @@title GNU Sample
16297texinfo.texi(,16738) @@subtitle for version @@value@{VERSION@}, @@value@{UPDATED@}
16298texinfo.texi(,16739) @@author A.U. Thor (@@email@{bug-texinfo@@@@gnu.org@})
16299texinfo.texi(,16740) @@page
16300texinfo.texi(,16741) @@vskip 0pt plus 1filll
16301texinfo.texi(,16742) @@insertcopying
16302texinfo.texi(,16743) @@end titlepage
16303texinfo.texi(,16744)
16304texinfo.texi(,16745) @@contents
16305texinfo.texi(,16746)
16306texinfo.texi(,16747) @@ifnottex
16307texinfo.texi(,16748) @@node Top
16308texinfo.texi(,16749) @@top GNU Sample
16309texinfo.texi(,16750)
16310texinfo.texi(,16751) @@insertcopying
16311texinfo.texi(,16752) @@end ifnottex
16312texinfo.texi(,16753)
16313texinfo.texi(,16754) @@menu
16314texinfo.texi(,16755) * Invoking sample::
16315texinfo.texi(,16756) * Copying This Manual::
16316texinfo.texi(,16757) * Index::
16317texinfo.texi(,16758) @@end menu
16318texinfo.texi(,16759)
16319texinfo.texi(,16760)
16320texinfo.texi(,16761) @@node Invoking sample
16321texinfo.texi(,16762) @@chapter Invoking sample
16322texinfo.texi(,16763)
16323texinfo.texi(,16764) @@pindex sample
16324texinfo.texi(,16765) @@cindex invoking @@command@{sample@}
16325texinfo.texi(,16766)
16326texinfo.texi(,16767) This is a sample manual.  There is no sample program to
16327texinfo.texi(,16768) invoke, but if there was, you could see its basic usage
16328texinfo.texi(,16769) and command line options here.
16329texinfo.texi(,16770)
16330texinfo.texi(,16771)
16331texinfo.texi(,16772) @@node Copying This Manual
16332texinfo.texi(,16773) @@appendix Copying This Manual
16333texinfo.texi(,16774)
16334texinfo.texi(,16775) @@menu
16335texinfo.texi(,16776) * GNU Free Documentation License::  License for copying this manual.
16336texinfo.texi(,16777) @@end menu
16337texinfo.texi(,16778)
16338texinfo.texi(,16779) @@include fdl.texi
16339texinfo.texi(,16780)
16340texinfo.texi(,16781)
16341texinfo.texi(,16782) @@node Index
16342texinfo.texi(,16783) @@unnumbered Index
16343texinfo.texi(,16784)
16344texinfo.texi(,16785) @@printindex cp
16345texinfo.texi(,16786)
16346texinfo.texi(,16787) @@bye
16347texinfo.texi(,16788) @end example
16348texinfo.texi(,16789)
16349texinfo.texi(,16790)
16350texinfo.texi(,16791) @node Include Files
16351texinfo.texi(,16792) @appendix Include Files
16352texinfo.texi(,16793) @cindex Include files
16353texinfo.texi(,16794)
16354texinfo.texi(,16795) When @TeX{} or an Info formatting command sees an @code{@@include}
16355texinfo.texi(,16796) command in a Texinfo file, it processes the contents of the file named
16356texinfo.texi(,16797) by the command and incorporates them into the DVI or Info file being
16357texinfo.texi(,16798) created.  Index entries from the included file are incorporated into
16358texinfo.texi(,16799) the indices of the output file.
16359texinfo.texi(,16800)
16360texinfo.texi(,16801) Include files let you keep a single large document as a collection of
16361texinfo.texi(,16802) conveniently small parts.
16362texinfo.texi(,16803)
16363texinfo.texi(,16804) @menu
16364texinfo.texi(,16805) * Using Include Files::         How to use the @code{@@include} command.
16365texinfo.texi(,16806) * texinfo-multiple-files-update::  How to create and update nodes and
16366texinfo.texi(,16807)                                   menus when using included files.
16367texinfo.texi(,16808) * Include File Requirements::   What @code{texinfo-multiple-files-update} expects.
16368texinfo.texi(,16809) * Sample Include File::         A sample outer file with included files
16369texinfo.texi(,16810)                                   within it; and a sample included file.
16370texinfo.texi(,16811) * Include Files Evolution::     How use of the @code{@@include} command
16371texinfo.texi(,16812)                                   has changed over time.
16372texinfo.texi(,16813) @end menu
16373texinfo.texi(,16814)
16374texinfo.texi(,16815) @node Using Include Files, texinfo-multiple-files-update, Include Files, Include Files
16375texinfo.texi(,16816) @section How to Use Include Files
16376texinfo.texi(,16817) @findex include
16377texinfo.texi(,16818)
16378texinfo.texi(,16819) To include another file within a Texinfo file, write the
16379texinfo.texi(,16820) @code{@@include} command at the beginning of a line and follow it on
16380texinfo.texi(,16821) the same line by the name of a file to be included.  For
16381texinfo.texi(,16822) example:@refill
16382texinfo.texi(,16823)
16383texinfo.texi(,16824) @example
16384texinfo.texi(,16825) @@include buffers.texi
16385texinfo.texi(,16826) @end example
16386texinfo.texi(,16827)
16387texinfo.texi(,16828) An included file should simply be a segment of text that you expect to
16388texinfo.texi(,16829) be included as is into the overall or @dfn{outer} Texinfo file; it
16389texinfo.texi(,16830) should not contain the standard beginning and end parts of a Texinfo
16390texinfo.texi(,16831) file.  In particular, you should not start an included file with a
16391texinfo.texi(,16832) line saying @samp{\input texinfo}; if you do, that phrase is inserted
16392texinfo.texi(,16833) into the output file as is.  Likewise, you should not end an included
16393texinfo.texi(,16834) file with an @code{@@bye} command; nothing after @code{@@bye} is
16394texinfo.texi(,16835) formatted.@refill
16395texinfo.texi(,16836)
16396texinfo.texi(,16837) In the past, you were required to write an @code{@@setfilename} line at the
16397texinfo.texi(,16838) beginning of an included file, but no longer.  Now, it does not matter
16398texinfo.texi(,16839) whether you write such a line.  If an @code{@@setfilename} line exists
16399texinfo.texi(,16840) in an included file, it is ignored.@refill
16400texinfo.texi(,16841)
16401texinfo.texi(,16842) Conventionally, an included file begins with an @code{@@node} line that
16402texinfo.texi(,16843) is followed by an @code{@@chapter} line.  Each included file is one
16403texinfo.texi(,16844) chapter.  This makes it easy to use the regular node and menu creating
16404texinfo.texi(,16845) and updating commands to create the node pointers and menus within the
16405texinfo.texi(,16846) included file.  However, the simple Emacs node and menu creating and
16406texinfo.texi(,16847) updating commands do not work with multiple Texinfo files.  Thus you
16407texinfo.texi(,16848) cannot use these commands to fill in the `Next', `Previous', and `Up'
16408texinfo.texi(,16849) pointers of the @code{@@node} line that begins the included file.  Also,
16409texinfo.texi(,16850) you cannot use the regular commands to create a master menu for the
16410texinfo.texi(,16851) whole file.  Either you must insert the menus and the `Next',
16411texinfo.texi(,16852) `Previous', and `Up' pointers by hand, or you must use the GNU Emacs
16412texinfo.texi(,16853) Texinfo mode command, @code{texinfo-multiple-files-update}, that is
16413texinfo.texi(,16854) designed for @code{@@include} files.@refill
16414texinfo.texi(,16855)
16415texinfo.texi(,16856) @node texinfo-multiple-files-update, Include File Requirements, Using Include Files, Include Files
16416texinfo.texi(,16857) @section @code{texinfo-multiple-files-update}
16417texinfo.texi(,16858) @findex texinfo-multiple-files-update
16418texinfo.texi(,16859)
16419texinfo.texi(,16860) GNU Emacs Texinfo mode provides the @code{texinfo-multiple-files-update}
16420texinfo.texi(,16861) command.  This command creates or updates `Next', `Previous', and `Up'
16421texinfo.texi(,16862) pointers of included files as well as those in the outer or overall
16422texinfo.texi(,16863) Texinfo file, and it creates or updates a main menu in the outer file.
16423texinfo.texi(,16864) Depending whether you call it with optional arguments, the command
16424texinfo.texi(,16865) updates only the pointers in the first @code{@@node} line of the
16425texinfo.texi(,16866) included files or all of them:@refill
16426texinfo.texi(,16867)
16427texinfo.texi(,16868) @table @kbd
16428texinfo.texi(,16869) @item M-x texinfo-multiple-files-update
16429texinfo.texi(,16870) Called without any arguments:@refill
16430texinfo.texi(,16871)
16431texinfo.texi(,16872) @itemize @minus
16432texinfo.texi(,16873) @item
16433texinfo.texi(,16874) Create or update the `Next', `Previous', and `Up' pointers of the
16434texinfo.texi(,16875) first @code{@@node} line in each file included in an outer or overall
16435texinfo.texi(,16876) Texinfo file.@refill
16436texinfo.texi(,16877)
16437texinfo.texi(,16878) @item
16438texinfo.texi(,16879) Create or update the `Top' level node pointers of the outer or
16439texinfo.texi(,16880) overall file.@refill
16440texinfo.texi(,16881)
16441texinfo.texi(,16882) @item
16442texinfo.texi(,16883) Create or update a main menu in the outer file.@refill
16443texinfo.texi(,16884) @end itemize
16444texinfo.texi(,16885)
16445texinfo.texi(,16886) @item C-u M-x texinfo-multiple-files-update
16446texinfo.texi(,16887) Called with @kbd{C-u} as a prefix argument:
16447texinfo.texi(,16888)
16448texinfo.texi(,16889) @itemize @minus{}
16449texinfo.texi(,16890) @item
16450texinfo.texi(,16891) Create or update pointers in the first @code{@@node} line in each
16451texinfo.texi(,16892) included file.
16452texinfo.texi(,16893)
16453texinfo.texi(,16894) @item
16454texinfo.texi(,16895) Create or update the `Top' level node pointers of the outer file.
16455texinfo.texi(,16896)
16456texinfo.texi(,16897) @item
16457texinfo.texi(,16898) Create and insert a master menu in the outer file.  The master menu
16458texinfo.texi(,16899) is made from all the menus in all the included files.@refill
16459texinfo.texi(,16900) @end itemize
16460texinfo.texi(,16901)
16461texinfo.texi(,16902) @item C-u 8 M-x texinfo-multiple-files-update
16462texinfo.texi(,16903) Called with a numeric prefix argument, such as @kbd{C-u 8}:
16463texinfo.texi(,16904)
16464texinfo.texi(,16905) @itemize @minus
16465texinfo.texi(,16906) @item
16466texinfo.texi(,16907) Create or update @strong{all} the `Next', `Previous', and `Up' pointers
16467texinfo.texi(,16908) of all the included files.@refill
16468texinfo.texi(,16909)
16469texinfo.texi(,16910) @item
16470texinfo.texi(,16911) Create or update @strong{all} the menus of all the included
16471texinfo.texi(,16912) files.@refill
16472texinfo.texi(,16913)
16473texinfo.texi(,16914) @item
16474texinfo.texi(,16915) Create or update the `Top' level node pointers of the outer or
16475texinfo.texi(,16916) overall file.@refill
16476texinfo.texi(,16917)
16477texinfo.texi(,16918) @item
16478texinfo.texi(,16919) And then create a master menu in the outer file.  This is similar to
16479texinfo.texi(,16920) invoking @code{texinfo-master-menu} with an argument when you are
16480texinfo.texi(,16921) working with just one file.@refill
16481texinfo.texi(,16922) @end itemize
16482texinfo.texi(,16923) @end table
16483texinfo.texi(,16924)
16484texinfo.texi(,16925) Note the use of the prefix argument in interactive use: with a regular
16485texinfo.texi(,16926) prefix argument, just @w{@kbd{C-u}}, the
16486texinfo.texi(,16927) @code{texinfo-multiple-files-update} command inserts a master menu;
16487texinfo.texi(,16928) with a numeric prefix argument, such as @kbd{C-u 8}, the command
16488texinfo.texi(,16929) updates @strong{every} pointer and menu in @strong{all} the files and then inserts a
16489texinfo.texi(,16930) master menu.@refill
16490texinfo.texi(,16931)
16491texinfo.texi(,16932)
16492texinfo.texi(,16933) @node Include File Requirements
16493texinfo.texi(,16934) @section Include File Requirements
16494texinfo.texi(,16935) @cindex Include file requirements
16495texinfo.texi(,16936) @cindex Requirements for include files
16496texinfo.texi(,16937)
16497texinfo.texi(,16938) If you plan to use the @code{texinfo-multiple-files-update} command,
16498texinfo.texi(,16939) the outer Texinfo file that lists included files within it should
16499texinfo.texi(,16940) contain nothing but the beginning and end parts of a Texinfo file, and
16500texinfo.texi(,16941) a number of @code{@@include} commands listing the included files.  It
16501texinfo.texi(,16942) should not even include indices, which should be listed in an included
16502texinfo.texi(,16943) file of their own.@refill
16503texinfo.texi(,16944)
16504texinfo.texi(,16945) Moreover, each of the included files must contain exactly one highest
16505texinfo.texi(,16946) level node (conventionally, @code{@@chapter} or equivalent),
16506texinfo.texi(,16947) and this node must be the first node in the included file.
16507texinfo.texi(,16948) Furthermore, each of these highest level nodes in each included file
16508texinfo.texi(,16949) must be at the same hierarchical level in the file structure.
16509texinfo.texi(,16950) Usually, each is an @code{@@chapter}, an @code{@@appendix}, or an
16510texinfo.texi(,16951) @code{@@unnumbered} node.  Thus, normally, each included file contains
16511texinfo.texi(,16952) one, and only one, chapter or equivalent-level node.@refill
16512texinfo.texi(,16953)
16513texinfo.texi(,16954) The outer file should contain only @emph{one} node, the `Top' node.  It
16514texinfo.texi(,16955) should @emph{not} contain any nodes besides the single `Top' node.  The
16515texinfo.texi(,16956) @code{texinfo-multiple-files-update} command will not process
16516texinfo.texi(,16957) them.@refill
16517texinfo.texi(,16958)
16518texinfo.texi(,16959) @node Sample Include File, Include Files Evolution, Include File Requirements, Include Files
16519texinfo.texi(,16960) @section Sample File with @code{@@include}
16520texinfo.texi(,16961) @cindex Sample @code{@@include} file
16521texinfo.texi(,16962) @cindex Include file sample
16522texinfo.texi(,16963) @cindex @code{@@include} file sample
16523texinfo.texi(,16964)
16524texinfo.texi(,16965) Here is an example of a complete outer Texinfo file with @code{@@include} files
16525texinfo.texi(,16966) within it before running @code{texinfo-multiple-files-update}, which
16526texinfo.texi(,16967) would insert a main or master menu:@refill
16527texinfo.texi(,16968)
16528texinfo.texi(,16969) @example
16529texinfo.texi(,16970) @group
16530texinfo.texi(,16971) \input texinfo @@c -*-texinfo-*-
16531texinfo.texi(,16972) @c %**start of header
16532texinfo.texi(,16973) @@setfilename  include-example.info
16533texinfo.texi(,16974) @@settitle Include Example
16534texinfo.texi(,16975) @c %**end of header
16535texinfo.texi(,16976) @end group
16536texinfo.texi(,16977)
16537texinfo.texi(,16978) @group
16538texinfo.texi(,16979) @@setchapternewpage odd
16539texinfo.texi(,16980) @@titlepage
16540texinfo.texi(,16981) @@sp 12
16541texinfo.texi(,16982) @@center @@titlefont@{Include Example@}
16542texinfo.texi(,16983) @@sp 2
16543texinfo.texi(,16984) @@center by Whom Ever
16544texinfo.texi(,16985) @end group
16545texinfo.texi(,16986)
16546texinfo.texi(,16987) @group
16547texinfo.texi(,16988) @@page
16548texinfo.texi(,16989) @@vskip 0pt plus 1filll
16549texinfo.texi(,16990) Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
16550texinfo.texi(,16991) @@end titlepage
16551texinfo.texi(,16992) @end group
16552texinfo.texi(,16993)
16553texinfo.texi(,16994) @group
16554texinfo.texi(,16995) @@ifinfo
16555texinfo.texi(,16996) @@node Top, First, , (dir)
16556texinfo.texi(,16997) @@top Master Menu
16557texinfo.texi(,16998) @@end ifinfo
16558texinfo.texi(,16999) @end group
16559texinfo.texi(,17000)
16560texinfo.texi(,17001) @group
16561texinfo.texi(,17002) @@include foo.texinfo
16562texinfo.texi(,17003) @@include bar.texinfo
16563texinfo.texi(,17004) @@include concept-index.texinfo
16564texinfo.texi(,17005) @end group
16565texinfo.texi(,17006)
16566texinfo.texi(,17007) @group
16567texinfo.texi(,17008) @@summarycontents
16568texinfo.texi(,17009) @@contents
16569texinfo.texi(,17010)
16570texinfo.texi(,17011) @@bye
16571texinfo.texi(,17012) @end group
16572texinfo.texi(,17013) @end example
16573texinfo.texi(,17014)
16574texinfo.texi(,17015) An included file, such as @file{foo.texinfo}, might look like this:
16575texinfo.texi(,17016)
16576texinfo.texi(,17017) @example
16577texinfo.texi(,17018) @group
16578texinfo.texi(,17019) @@node First, Second, , Top
16579texinfo.texi(,17020) @@chapter First Chapter
16580texinfo.texi(,17021)
16581texinfo.texi(,17022) Contents of first chapter @dots{}
16582texinfo.texi(,17023) @end group
16583texinfo.texi(,17024) @end example
16584texinfo.texi(,17025)
16585texinfo.texi(,17026) The full contents of @file{concept-index.texinfo} might be as simple as this:
16586texinfo.texi(,17027)
16587texinfo.texi(,17028) @example
16588texinfo.texi(,17029) @group
16589texinfo.texi(,17030) @@node Concept Index
16590texinfo.texi(,17031) @@unnumbered Concept Index
16591texinfo.texi(,17032)
16592texinfo.texi(,17033) @@printindex cp
16593texinfo.texi(,17034) @end group
16594texinfo.texi(,17035) @end example
16595texinfo.texi(,17036)
16596texinfo.texi(,17037) The outer Texinfo source file for @cite{The GNU Emacs Lisp Reference
16597texinfo.texi(,17038) Manual} is named @file{elisp.texi}.  This outer file contains a master
16598texinfo.texi(,17039) menu with 417 entries and a list of 41 @code{@@include}
16599texinfo.texi(,17040) files.@refill
16600texinfo.texi(,17041)
16601texinfo.texi(,17042)
16602texinfo.texi(,17043) @node Include Files Evolution
16603texinfo.texi(,17044) @section Evolution of Include Files
16604texinfo.texi(,17045)
16605texinfo.texi(,17046) When Info was first created, it was customary to create many small
16606texinfo.texi(,17047) Info files on one subject.  Each Info file was formatted from its own
16607texinfo.texi(,17048) Texinfo source file.  This custom meant that Emacs did not need to
16608texinfo.texi(,17049) make a large buffer to hold the whole of a large Info file when
16609texinfo.texi(,17050) someone wanted information; instead, Emacs allocated just enough
16610texinfo.texi(,17051) memory for the small Info file that contained the particular
16611texinfo.texi(,17052) information sought.  This way, Emacs could avoid wasting memory.@refill
16612texinfo.texi(,17053)
16613texinfo.texi(,17054) References from one file to another were made by referring to the file
16614texinfo.texi(,17055) name as well as the node name. (@xref{Other Info Files, , Referring to
16615texinfo.texi(,17056) Other Info Files}.  Also, see @ref{Four and Five Arguments, ,
16616texinfo.texi(,17057) @code{@@xref} with Four and Five Arguments}.)@refill
16617texinfo.texi(,17058)
16618texinfo.texi(,17059) Include files were designed primarily as a way to create a single,
16619texinfo.texi(,17060) large printed manual out of several smaller Info files.  In a printed
16620texinfo.texi(,17061) manual, all the references were within the same document, so @TeX{}
16621texinfo.texi(,17062) could automatically determine the references' page numbers.  The Info
16622texinfo.texi(,17063) formatting commands used include files only for creating joint
16623texinfo.texi(,17064) indices; each of the individual Texinfo files had to be formatted for
16624texinfo.texi(,17065) Info individually.  (Each, therefore, required its own
16625texinfo.texi(,17066) @code{@@setfilename} line.)@refill
16626texinfo.texi(,17067)
16627texinfo.texi(,17068) However, because large Info files are now split automatically, it is
16628texinfo.texi(,17069) no longer necessary to keep them small.@refill
16629texinfo.texi(,17070)
16630texinfo.texi(,17071) Nowadays, multiple Texinfo files are used mostly for large documents,
16631texinfo.texi(,17072) such as @cite{The GNU Emacs Lisp Reference Manual}, and for projects
16632texinfo.texi(,17073) in which several different people write different sections of a
16633texinfo.texi(,17074) document simultaneously.@refill
16634texinfo.texi(,17075)
16635texinfo.texi(,17076) In addition, the Info formatting commands have been extended to work
16636texinfo.texi(,17077) with the @code{@@include} command so as to create a single large Info
16637texinfo.texi(,17078) file that is split into smaller files if necessary.  This means that
16638texinfo.texi(,17079) you can write menus and cross references without naming the different
16639texinfo.texi(,17080) Texinfo files.@refill
16640texinfo.texi(,17081)
16641texinfo.texi(,17082)
16642texinfo.texi(,17083) @node Headings
16643texinfo.texi(,17084) @appendix Page Headings
16644texinfo.texi(,17085) @cindex Headings
16645texinfo.texi(,17086) @cindex Footings
16646texinfo.texi(,17087) @cindex Page numbering
16647texinfo.texi(,17088) @cindex Page headings
16648texinfo.texi(,17089) @cindex Formatting headings and footings
16649texinfo.texi(,17090)
16650texinfo.texi(,17091) Most printed manuals contain headings along the top of every page
16651texinfo.texi(,17092) except the title and copyright pages.  Some manuals also contain
16652texinfo.texi(,17093) footings.  (Headings and footings have no meaning to Info, which is
16653texinfo.texi(,17094) not paginated.)@refill
16654texinfo.texi(,17095)
16655texinfo.texi(,17096) @menu
16656texinfo.texi(,17097) * Headings Introduced::         Conventions for using page headings.
16657texinfo.texi(,17098) * Heading Format::              Standard page heading formats.
16658texinfo.texi(,17099) * Heading Choice::              How to specify the type of page heading.
16659texinfo.texi(,17100) * Custom Headings::             How to create your own headings and footings.
16660texinfo.texi(,17101) @end menu
16661texinfo.texi(,17102)
16662texinfo.texi(,17103) @node Headings Introduced, Heading Format, Headings, Headings
16663texinfo.texi(,17105) @heading Headings Introduced
16664texinfo.texi(,17107)
16665texinfo.texi(,17108) Texinfo provides standard page heading formats for manuals that are
16666texinfo.texi(,17109) printed on one side of each sheet of paper and for manuals that are
16667texinfo.texi(,17110) printed on both sides of the paper.  Typically, you will use these
16668texinfo.texi(,17111) formats, but you can specify your own format if you wish.@refill
16669texinfo.texi(,17112)
16670texinfo.texi(,17113) In addition, you can specify whether chapters should begin on a new
16671texinfo.texi(,17114) page, or merely continue the same page as the previous chapter; and if
16672texinfo.texi(,17115) chapters begin on new pages, you can specify whether they must be
16673texinfo.texi(,17116) odd-numbered pages.@refill
16674texinfo.texi(,17117)
16675texinfo.texi(,17118) By convention, a book is printed on both sides of each sheet of paper.
16676texinfo.texi(,17119) When you open a book, the right-hand page is odd-numbered, and
16677texinfo.texi(,17120) chapters begin on right-hand pages---a preceding left-hand page is
16678texinfo.texi(,17121) left blank if necessary.  Reports, however, are often printed on just
16679texinfo.texi(,17122) one side of paper, and chapters begin on a fresh page immediately
16680texinfo.texi(,17123) following the end of the preceding chapter.  In short or informal
16681texinfo.texi(,17124) reports, chapters often do not begin on a new page at all, but are
16682texinfo.texi(,17125) separated from the preceding text by a small amount of whitespace.@refill
16683texinfo.texi(,17126)
16684texinfo.texi(,17127) The @code{@@setchapternewpage} command controls whether chapters begin
16685texinfo.texi(,17128) on new pages, and whether one of the standard heading formats is used.
16686texinfo.texi(,17129) In addition, Texinfo has several heading and footing commands that you
16687texinfo.texi(,17130) can use to generate your own heading and footing formats.@refill
16688texinfo.texi(,17131)
16689texinfo.texi(,17132) In Texinfo, headings and footings are single lines at the tops and
16690texinfo.texi(,17133) bottoms of pages; you cannot create multiline headings or footings.
16691texinfo.texi(,17134) Each header or footer line is divided into three parts: a left part, a
16692texinfo.texi(,17135) middle part, and a right part.  Any part, or a whole line, may be left
16693texinfo.texi(,17136) blank.  Text for the left part of a header or footer line is set
16694texinfo.texi(,17137) flushleft; text for the middle part is centered; and, text for the
16695texinfo.texi(,17138) right part is set flushright.@refill
16696texinfo.texi(,17139)
16697texinfo.texi(,17140) @node Heading Format, Heading Choice, Headings Introduced, Headings
16698texinfo.texi(,17141) @comment  node-name,  next,  previous,  up
16699texinfo.texi(,17142) @section Standard Heading Formats
16700texinfo.texi(,17143)
16701texinfo.texi(,17144) Texinfo provides two standard heading formats, one for manuals printed
16702texinfo.texi(,17145) on one side of each sheet of paper, and the other for manuals printed
16703texinfo.texi(,17146) on both sides of the paper.
16704texinfo.texi(,17147)
16705texinfo.texi(,17148) By default, nothing is specified for the footing of a Texinfo file,
16706texinfo.texi(,17149) so the footing remains blank.@refill
16707texinfo.texi(,17150)
16708texinfo.texi(,17151) The standard format for single-sided printing consists of a header
16709texinfo.texi(,17152) line in which the left-hand part contains the name of the chapter, the
16710texinfo.texi(,17153) central part is blank, and the right-hand part contains the page
16711texinfo.texi(,17154) number.@refill
16712texinfo.texi(,17155)
16713texinfo.texi(,17156) @need 950
16714texinfo.texi(,17157) A single-sided page looks like this:
16715texinfo.texi(,17158)
16716texinfo.texi(,17159) @example
16717texinfo.texi(,17160) @group
16718texinfo.texi(,17161)    _______________________
16719texinfo.texi(,17162)   |                       |
16720texinfo.texi(,17163)   | chapter   page number |
16721texinfo.texi(,17164)   |                       |
16722texinfo.texi(,17165)   | Start of text ...     |
16723texinfo.texi(,17166)   | ...                   |
16724texinfo.texi(,17167)   |                       |
16725texinfo.texi(,17168)
16726texinfo.texi(,17169) @end group
16727texinfo.texi(,17170) @end example
16728texinfo.texi(,17171)
16729texinfo.texi(,17172) The standard format for two-sided printing depends on whether the page
16730texinfo.texi(,17173) number is even or odd.  By convention, even-numbered pages are on the
16731texinfo.texi(,17174) left- and odd-numbered pages are on the right.  (@TeX{} will adjust the
16732texinfo.texi(,17175) widths of the left- and right-hand margins.  Usually, widths are
16733texinfo.texi(,17176) correct, but during double-sided printing, it is wise to check that
16734texinfo.texi(,17177) pages will bind properly---sometimes a printer will produce output in
16735texinfo.texi(,17178) which the even-numbered pages have a larger right-hand margin than the
16736texinfo.texi(,17179) odd-numbered pages.)@refill
16737texinfo.texi(,17180)
16738texinfo.texi(,17181) In the standard double-sided format, the left part of the left-hand
16739texinfo.texi(,17182) (even-numbered) page contains the page number, the central part is
16740texinfo.texi(,17183) blank, and the right part contains the title (specified by the
16741texinfo.texi(,17184) @code{@@settitle} command).  The left part of the right-hand
16742texinfo.texi(,17185) (odd-numbered) page contains the name of the chapter, the central part
16743texinfo.texi(,17186) is blank, and the right part contains the page number.@refill
16744texinfo.texi(,17187)
16745texinfo.texi(,17188) @need 750
16746texinfo.texi(,17189) Two pages, side by side as in an open book, look like this:@refill
16747texinfo.texi(,17190)
16748texinfo.texi(,17191) @example
16749texinfo.texi(,17192) @group
16750texinfo.texi(,17193)    _______________________     _______________________
16751texinfo.texi(,17194)   |                       |   |                       |
16752texinfo.texi(,17195)   | page number     title |   | chapter   page number |
16753texinfo.texi(,17196)   |                       |   |                       |
16754texinfo.texi(,17197)   | Start of text ...     |   | More  text ...        |
16755texinfo.texi(,17198)   | ...                   |   | ...                   |
16756texinfo.texi(,17199)   |                       |   |                       |
16757texinfo.texi(,17200)
16758texinfo.texi(,17201) @end group
16759texinfo.texi(,17202) @end example
16760texinfo.texi(,17203)
16761texinfo.texi(,17204) @noindent
16762texinfo.texi(,17205) The chapter name is preceded by the word ``Chapter'', the chapter number
16763texinfo.texi(,17206) and a colon.  This makes it easier to keep track of where you are in the
16764texinfo.texi(,17207) manual.@refill
16765texinfo.texi(,17208)
16766texinfo.texi(,17209) @node Heading Choice, Custom Headings, Heading Format, Headings
16767texinfo.texi(,17210) @comment  node-name,  next,  previous,  up
16768texinfo.texi(,17211) @section Specifying the Type of Heading
16769texinfo.texi(,17212)
16770texinfo.texi(,17213) @TeX{} does not begin to generate page headings for a standard Texinfo
16771texinfo.texi(,17214) file until it reaches the @code{@@end titlepage} command.  Thus, the
16772texinfo.texi(,17215) title and copyright pages are not numbered.  The @code{@@end
16773texinfo.texi(,17216) titlepage} command causes @TeX{} to begin to generate page headings
16774texinfo.texi(,17217) according to a standard format specified by the
16775texinfo.texi(,17218) @code{@@setchapternewpage} command that precedes the
16776texinfo.texi(,17219) @code{@@titlepage} section.@refill
16777texinfo.texi(,17220)
16778texinfo.texi(,17221) @need 1000
16779texinfo.texi(,17222) There are four possibilities:@refill
16780texinfo.texi(,17223)
16781texinfo.texi(,17224) @table @asis
16782texinfo.texi(,17225) @item No @code{@@setchapternewpage} command
16783texinfo.texi(,17226) Cause @TeX{} to specify the single-sided heading format, with chapters
16784texinfo.texi(,17227) on new pages. This is the same as @code{@@setchapternewpage on}.@refill
16785texinfo.texi(,17228)
16786texinfo.texi(,17229) @item @code{@@setchapternewpage on}
16787texinfo.texi(,17230) Specify the single-sided heading format, with chapters on new pages.@refill
16788texinfo.texi(,17231)
16789texinfo.texi(,17232) @item @code{@@setchapternewpage off}
16790texinfo.texi(,17233) Cause @TeX{} to start a new chapter on the same page as the last page of
16791texinfo.texi(,17234) the preceding chapter, after skipping some vertical whitespace.  Also
16792texinfo.texi(,17235) cause @TeX{} to typeset for single-sided printing.  (You can override
16793texinfo.texi(,17236) the headers format with the @code{@@headings double} command; see
16794texinfo.texi(,17237) @ref{headings on off, , The @code{@@headings} Command}.)@refill
16795texinfo.texi(,17238)
16796texinfo.texi(,17239) @item @code{@@setchapternewpage odd}
16797texinfo.texi(,17240) Specify the double-sided heading format, with chapters on new pages.@refill
16798texinfo.texi(,17241) @end table
16799texinfo.texi(,17242)
16800texinfo.texi(,17243) @noindent
16801texinfo.texi(,17244) Texinfo lacks an @code{@@setchapternewpage even} command.@refill
16802texinfo.texi(,17245)
16803texinfo.texi(,17246) @node Custom Headings,  , Heading Choice, Headings
16804texinfo.texi(,17247) @comment  node-name,  next,  previous,  up
16805texinfo.texi(,17248) @section How to Make Your Own Headings
16806texinfo.texi(,17249)
16807texinfo.texi(,17250) You can use the standard headings provided with Texinfo or specify
16808texinfo.texi(,17251) your own.  By default, Texinfo has no footers, so if you specify them,
16809texinfo.texi(,17252) the available page size for the main text will be slightly reduced.
16810texinfo.texi(,17253)
16811texinfo.texi(,17254) Texinfo provides six commands for specifying headings and
16812texinfo.texi(,17255) footings:
16813texinfo.texi(,17256) @itemize @bullet
16814texinfo.texi(,17257) @item
16815texinfo.texi(,17258) @code{@@everyheading} @code{@@everyfooting} generate page headers and
16816texinfo.texi(,17259) footers that are the same for both even- and odd-numbered pages.
16817texinfo.texi(,17260) @item
16818texinfo.texi(,17261) @code{@@evenheading} and @code{@@evenfooting} command generate headers
16819texinfo.texi(,17262) and footers for even-numbered (left-hand) pages.
16820texinfo.texi(,17263) @item
16821texinfo.texi(,17264) @code{@@oddheading} and @code{@@oddfooting} generate headers and footers
16822texinfo.texi(,17265) for odd-numbered (right-hand) pages.
16823texinfo.texi(,17266) @end itemize
16824texinfo.texi(,17267)
16825texinfo.texi(,17268) Write custom heading specifications in the Texinfo file immediately
16826texinfo.texi(,17269) after the @code{@@end titlepage} command.
16827texinfo.texi(,17270) You must cancel the predefined heading commands with the
16828texinfo.texi(,17271) @code{@@headings off} command before defining your own
16829texinfo.texi(,17272) specifications.@refill
16830texinfo.texi(,17273)
16831texinfo.texi(,17274) @need 1000
16832texinfo.texi(,17275) Here is how to tell @TeX{} to place the chapter name at the left, the
16833texinfo.texi(,17276) page number in the center, and the date at the right of every header
16834texinfo.texi(,17277) for both even- and odd-numbered pages:@refill
16835texinfo.texi(,17278)
16836texinfo.texi(,17279) @example
16837texinfo.texi(,17280) @group
16838texinfo.texi(,17281) @@headings off
16839texinfo.texi(,17282) @@everyheading @@thischapter @@| @@thispage @@| @@today@{@}
16840texinfo.texi(,17283) @end group
16841texinfo.texi(,17284) @end example
16842texinfo.texi(,17285)
16843texinfo.texi(,17286) @noindent
16844texinfo.texi(,17287) You need to divide the left part from the central part and the central
16845texinfo.texi(,17288) part from the right part by inserting @samp{@@|} between parts.
16846texinfo.texi(,17289) Otherwise, the specification command will not be able to tell where
16847texinfo.texi(,17290) the text for one part ends and the next part begins.@refill
16848texinfo.texi(,17291)
16849texinfo.texi(,17292) Each part can contain text or @@-commands.  The text
16850texinfo.texi(,17293) is printed as if the part were within an ordinary paragraph in the
16851texinfo.texi(,17294) body of the page.  The @@-commands replace
16852texinfo.texi(,17295) themselves with the page number, date, chapter name, or
16853texinfo.texi(,17296) whatever.@refill
16854texinfo.texi(,17297)
16855texinfo.texi(,17298) @need 950
16856texinfo.texi(,17299) Here are the six heading and footing commands:@refill
16857texinfo.texi(,17300)
16858texinfo.texi(,17301) @findex everyheading
16859texinfo.texi(,17302) @findex everyfooting
16860texinfo.texi(,17303) @table @code
16861texinfo.texi(,17304) @item @@everyheading @var{left} @@| @var{center} @@| @var{right}
16862texinfo.texi(,17305) @itemx @@everyfooting @var{left} @@| @var{center} @@| @var{right}
16863texinfo.texi(,17306)
16864texinfo.texi(,17307) The `every' commands specify the format for both even- and odd-numbered
16865texinfo.texi(,17308) pages.  These commands are for documents that are printed on one side
16866texinfo.texi(,17309) of each sheet of paper, or for documents in which you want symmetrical
16867texinfo.texi(,17310) headers or footers.@refill
16868texinfo.texi(,17311)
16869texinfo.texi(,17312) @findex evenheading
16870texinfo.texi(,17313) @findex evenfooting
16871texinfo.texi(,17314) @findex oddheading
16872texinfo.texi(,17315) @findex oddfooting
16873texinfo.texi(,17316) @item @@evenheading @var{left} @@| @var{center} @@| @var{right}
16874texinfo.texi(,17317) @itemx @@oddheading  @var{left} @@| @var{center} @@| @var{right}
16875texinfo.texi(,17318)
16876texinfo.texi(,17319) @itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right}
16877texinfo.texi(,17320) @itemx @@oddfooting  @var{left} @@| @var{center} @@| @var{right}
16878texinfo.texi(,17321)
16879texinfo.texi(,17322) The `even' and `odd' commands specify the format for even-numbered
16880texinfo.texi(,17323) pages and odd-numbered pages.  These commands are for books and
16881texinfo.texi(,17324) manuals that are printed on both sides of each sheet of paper.
16882texinfo.texi(,17325) @end table
16883texinfo.texi(,17326)
16884texinfo.texi(,17327) Use the @samp{@@this@dots{}} series of @@-commands to
16885texinfo.texi(,17328) provide the names of chapters
16886texinfo.texi(,17329) and sections and the page number.  You can use the
16887texinfo.texi(,17330) @samp{@@this@dots{}} commands in the left, center, or right portions
16888texinfo.texi(,17331) of headers and footers, or anywhere else in a Texinfo file so long as
16889texinfo.texi(,17332) they are between @code{@@iftex} and @code{@@end iftex} commands.@refill
16890texinfo.texi(,17333)
16891texinfo.texi(,17334) @need 1000
16892texinfo.texi(,17335) Here are the @samp{@@this@dots{}} commands:@refill
16893texinfo.texi(,17336)
16894texinfo.texi(,17337) @table @code
16895texinfo.texi(,17338) @findex thispage
16896texinfo.texi(,17339) @item @@thispage
16897texinfo.texi(,17340) Expands to the current page number.@refill
16898texinfo.texi(,17341) @c !!! Karl Berry says that `thissection' can fail on page breaks.
16899texinfo.texi(,17346)
16900texinfo.texi(,17347) @findex thischaptername
16901texinfo.texi(,17348) @item @@thischaptername
16902texinfo.texi(,17349) Expands to the name of the current chapter.@refill
16903texinfo.texi(,17350)
16904texinfo.texi(,17351) @findex thischapter
16905texinfo.texi(,17352) @item @@thischapter
16906texinfo.texi(,17353) Expands to the number and name of the current
16907texinfo.texi(,17354) chapter, in the format `Chapter 1: Title'.@refill
16908texinfo.texi(,17355)
16909texinfo.texi(,17356) @findex thistitle
16910texinfo.texi(,17357) @item @@thistitle
16911texinfo.texi(,17358) Expands to the name of the document, as specified by the
16912texinfo.texi(,17359) @code{@@settitle} command.@refill
16913texinfo.texi(,17360)
16914texinfo.texi(,17361) @findex thisfile
16915texinfo.texi(,17362) @item @@thisfile
16916texinfo.texi(,17363) For @code{@@include} files only: expands to the name of the current
16917texinfo.texi(,17364) @code{@@include} file.  If the current Texinfo source file is not an
16918texinfo.texi(,17365) @code{@@include} file, this command has no effect.  This command does
16919texinfo.texi(,17366) @emph{not} provide the name of the current Texinfo source file unless
16920texinfo.texi(,17367) it is an @code{@@include} file.  (@xref{Include Files}, for more
16921texinfo.texi(,17368) information about @code{@@include} files.)@refill
16922texinfo.texi(,17369) @end table
16923texinfo.texi(,17370)
16924texinfo.texi(,17371) @noindent
16925texinfo.texi(,17372) You can also use the @code{@@today@{@}} command, which expands to the
16926texinfo.texi(,17373) current date, in `1 Jan 1900' format.@refill
16927texinfo.texi(,17374) @findex today
16928texinfo.texi(,17375)
16929texinfo.texi(,17376) Other @@-commands and text are printed in a header or footer just as
16930texinfo.texi(,17377) if they were in the body of a page.  It is useful to incorporate text,
16931texinfo.texi(,17378) particularly when you are writing drafts:@refill
16932texinfo.texi(,17379)
16933texinfo.texi(,17380) @example
16934texinfo.texi(,17381) @group
16935texinfo.texi(,17382) @@headings off
16936texinfo.texi(,17383) @@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter
16937texinfo.texi(,17384) @@everyfooting @@| @@| Version: 0.27: @@today@{@}
16938texinfo.texi(,17385) @end group
16939texinfo.texi(,17386) @end example
16940texinfo.texi(,17387)
16941texinfo.texi(,17388) Beware of overlong titles: they may overlap another part of the
16942texinfo.texi(,17389) header or footer and blot it out.@refill
16943texinfo.texi(,17390)
16944texinfo.texi(,17391)
16945texinfo.texi(,17392) @node Catching Mistakes
16946texinfo.texi(,17393) @appendix Formatting Mistakes
16947texinfo.texi(,17394) @cindex Structure, catching mistakes in
16948texinfo.texi(,17395) @cindex Nodes, catching mistakes
16949texinfo.texi(,17396) @cindex Catching mistakes
16950texinfo.texi(,17397) @cindex Correcting mistakes
16951texinfo.texi(,17398) @cindex Mistakes, catching
16952texinfo.texi(,17399) @cindex Problems, catching
16953texinfo.texi(,17400) @cindex Debugging the Texinfo structure
16954texinfo.texi(,17401)
16955texinfo.texi(,17402) Besides mistakes in the content of your documentation, there are two
16956texinfo.texi(,17403) kinds of mistake you can make with Texinfo: you can make mistakes with
16957texinfo.texi(,17404) @@-commands, and you can make mistakes with the structure of the nodes
16958texinfo.texi(,17405) and chapters.
16959texinfo.texi(,17406)
16960texinfo.texi(,17407) Emacs has two tools for catching the @@-command mistakes and two for
16961texinfo.texi(,17408) catching structuring mistakes.@refill
16962texinfo.texi(,17409)
16963texinfo.texi(,17410) For finding problems with @@-commands, you can run @TeX{} or a region
16964texinfo.texi(,17411) formatting command on the region that has a problem; indeed, you can
16965texinfo.texi(,17412) run these commands on each region as you write it.@refill
16966texinfo.texi(,17413)
16967texinfo.texi(,17414) For finding problems with the structure of nodes and chapters, you can use
16968texinfo.texi(,17415) @kbd{C-c C-s} (@code{texinfo-show-structure}) and the related @code{occur}
16969texinfo.texi(,17416) command and you can use the @kbd{M-x Info-validate} command.@refill
16970texinfo.texi(,17417)
16971texinfo.texi(,17418) @menu
16972texinfo.texi(,17419) * makeinfo Preferred::          @code{makeinfo} finds errors.
16973texinfo.texi(,17420) * Debugging with Info::         How to catch errors with Info formatting.
16974texinfo.texi(,17421) * Debugging with TeX::          How to catch errors with @TeX{} formatting.
16975texinfo.texi(,17422) * Using texinfo-show-structure::  How to use @code{texinfo-show-structure}.
16976texinfo.texi(,17423) * Using occur::                 How to list all lines containing a pattern.
16977texinfo.texi(,17424) * Running Info-Validate::       How to find badly referenced nodes.
16978texinfo.texi(,17425) @end menu
16979texinfo.texi(,17426)
16980texinfo.texi(,17427) @node makeinfo Preferred, Debugging with Info, Catching Mistakes, Catching Mistakes
16981texinfo.texi(,17429) @heading @code{makeinfo} Find Errors
16982texinfo.texi(,17431)
16983texinfo.texi(,17432) The @code{makeinfo} program does an excellent job of catching errors
16984texinfo.texi(,17433) and reporting them---far better than @code{texinfo-format-region} or
16985texinfo.texi(,17434) @code{texinfo-format-buffer}.  In addition, the various functions for
16986texinfo.texi(,17435) automatically creating and updating node pointers and menus remove
16987texinfo.texi(,17436) many opportunities for human error.@refill
16988texinfo.texi(,17437)
16989texinfo.texi(,17438) If you can, use the updating commands to create and insert pointers
16990texinfo.texi(,17439) and menus.  These prevent many errors.  Then use @code{makeinfo} (or
16991texinfo.texi(,17440) its Texinfo mode manifestations, @code{makeinfo-region} and
16992texinfo.texi(,17441) @code{makeinfo-buffer}) to format your file and check for other
16993texinfo.texi(,17442) errors.  This is the best way to work with Texinfo.  But if you
16994texinfo.texi(,17443) cannot use @code{makeinfo}, or your problem is very puzzling, then you
16995texinfo.texi(,17444) may want to use the tools described in this appendix.@refill
16996texinfo.texi(,17445)
16997texinfo.texi(,17446) @node Debugging with Info, Debugging with TeX, makeinfo Preferred, Catching Mistakes
16998texinfo.texi(,17447) @comment  node-name,  next,  previous,  up
16999texinfo.texi(,17448) @section Catching Errors with Info Formatting
17000texinfo.texi(,17449) @cindex Catching errors with Info formatting
17001texinfo.texi(,17450) @cindex Debugging with Info formatting
17002texinfo.texi(,17451)
17003texinfo.texi(,17452) After you have written part of a Texinfo file, you can use the
17004texinfo.texi(,17453) @code{texinfo-format-region} or the @code{makeinfo-region} command to
17005texinfo.texi(,17454) see whether the region formats properly.@refill
17006texinfo.texi(,17455)
17007texinfo.texi(,17456) Most likely, however, you are reading this section because for some
17008texinfo.texi(,17457) reason you cannot use the @code{makeinfo-region} command; therefore, the
17009texinfo.texi(,17458) rest of this section presumes that you are using
17010texinfo.texi(,17459) @code{texinfo-format-region}.@refill
17011texinfo.texi(,17460)
17012texinfo.texi(,17461) If you have made a mistake with an @@-command,
17013texinfo.texi(,17462) @code{texinfo-format-region} will stop processing at or after the
17014texinfo.texi(,17463) error and display an error message.  To see where in the buffer the
17015texinfo.texi(,17464) error occurred, switch to the @samp{*Info Region*} buffer; the cursor
17016texinfo.texi(,17465) will be in a position that is after the location of the error.  Also,
17017texinfo.texi(,17466) the text will not be formatted after the place where the error
17018texinfo.texi(,17467) occurred (or more precisely, where it was detected).@refill
17019texinfo.texi(,17468)
17020texinfo.texi(,17469) For example, if you accidentally end a menu with the command @code{@@end
17021texinfo.texi(,17470) menus} with an `s' on the end, instead of with @code{@@end menu}, you
17022texinfo.texi(,17471) will see an error message that says:@refill
17023texinfo.texi(,17472)
17024texinfo.texi(,17473) @example
17025texinfo.texi(,17474) @@end menus is not handled by texinfo
17026texinfo.texi(,17475) @end example
17027texinfo.texi(,17476)
17028texinfo.texi(,17477) @noindent
17029texinfo.texi(,17478) The cursor will stop at the point in the buffer where the error
17030texinfo.texi(,17479) occurs, or not long after it.  The buffer will look like this:@refill
17031texinfo.texi(,17480)
17032texinfo.texi(,17481) @example
17033texinfo.texi(,17482) @group
17034texinfo.texi(,17483) ---------- Buffer: *Info Region* ----------
17035texinfo.texi(,17484) * Menu:
17036texinfo.texi(,17485)
17037texinfo.texi(,17486) * Using texinfo-show-structure::  How to use
17038texinfo.texi(,17487)                                   `texinfo-show-structure'
17039texinfo.texi(,17488)                                   to catch mistakes.
17040texinfo.texi(,17489) * Running Info-Validate::         How to check for
17041texinfo.texi(,17490)                                   unreferenced nodes.
17042texinfo.texi(,17491) @@end menus
17043texinfo.texi(,17492) @point{}
17044texinfo.texi(,17493) ---------- Buffer: *Info Region* ----------
17045texinfo.texi(,17494) @end group
17046texinfo.texi(,17495) @end example
17047texinfo.texi(,17496)
17048texinfo.texi(,17497) The @code{texinfo-format-region} command sometimes provides slightly
17049texinfo.texi(,17498) odd error messages.  For example, the following cross reference fails to format:@refill
17050texinfo.texi(,17499)
17051texinfo.texi(,17500) @example
17052texinfo.texi(,17501) (@@xref@{Catching Mistakes, for more info.)
17053texinfo.texi(,17502) @end example
17054texinfo.texi(,17503)
17055texinfo.texi(,17504) @noindent
17056texinfo.texi(,17505) In this case, @code{texinfo-format-region} detects the missing closing
17057texinfo.texi(,17506) brace but displays a message that says @samp{Unbalanced parentheses}
17058texinfo.texi(,17507) rather than @samp{Unbalanced braces}.  This is because the formatting
17059texinfo.texi(,17508) command looks for mismatches between braces as if they were
17060texinfo.texi(,17509) parentheses.@refill
17061texinfo.texi(,17510)
17062texinfo.texi(,17511) Sometimes @code{texinfo-format-region} fails to detect mistakes.  For
17063texinfo.texi(,17512) example, in the following, the closing brace is swapped with the
17064texinfo.texi(,17513) closing parenthesis:@refill
17065texinfo.texi(,17514)
17066texinfo.texi(,17515) @example
17067texinfo.texi(,17516) (@@xref@{Catching Mistakes), for more info.@}
17068texinfo.texi(,17517) @end example
17069texinfo.texi(,17518)
17070texinfo.texi(,17519) @noindent
17071texinfo.texi(,17520) Formatting produces:
17072texinfo.texi(,17521) @example
17073texinfo.texi(,17522) (*Note for more info.: Catching Mistakes)
17074texinfo.texi(,17523) @end example
17075texinfo.texi(,17524)
17076texinfo.texi(,17525) The only way for you to detect this error is to realize that the
17077texinfo.texi(,17526) reference should have looked like this:@refill
17078texinfo.texi(,17527)
17079texinfo.texi(,17528) @example
17080texinfo.texi(,17529) (*Note Catching Mistakes::, for more info.)
17081texinfo.texi(,17530) @end example
17082texinfo.texi(,17531)
17083texinfo.texi(,17532) Incidentally, if you are reading this node in Info and type @kbd{f
17084texinfo.texi(,17533) @key{RET}} (@code{Info-follow-reference}), you will generate an error
17085texinfo.texi(,17534) message that says:
17086texinfo.texi(,17535)
17087texinfo.texi(,17536) @example
17088texinfo.texi(,17537) No such node: "Catching Mistakes) The only way @dots{}
17089texinfo.texi(,17538) @end example
17090texinfo.texi(,17539)
17091texinfo.texi(,17540) @noindent
17092texinfo.texi(,17541) This is because Info perceives the example of the error as the first
17093texinfo.texi(,17542) cross reference in this node and if you type a @key{RET} immediately
17094texinfo.texi(,17543) after typing the Info @kbd{f} command, Info will attempt to go to the
17095texinfo.texi(,17544) referenced node.  If you type @kbd{f catch @key{TAB} @key{RET}}, Info
17096texinfo.texi(,17545) will complete the node name of the correctly written example and take
17097texinfo.texi(,17546) you to the `Catching Mistakes' node.  (If you try this, you can return
17098texinfo.texi(,17547) from the `Catching Mistakes' node by typing @kbd{l}
17099texinfo.texi(,17548) (@code{Info-last}).)
17100texinfo.texi(,17549)
17101texinfo.texi(,17550) @c !!! section on using Elisp debugger ignored.
17102texinfo.texi(,17632)
17103texinfo.texi(,17633) @node Debugging with TeX, Using texinfo-show-structure, Debugging with Info, Catching Mistakes
17104texinfo.texi(,17634) @comment  node-name,  next,  previous,  up
17105texinfo.texi(,17635) @section Catching Errors with @TeX{} Formatting
17106texinfo.texi(,17636) @cindex Catching errors with @TeX{} formatting
17107texinfo.texi(,17637) @cindex Debugging with @TeX{} formatting
17108texinfo.texi(,17638)
17109texinfo.texi(,17639) You can also catch mistakes when you format a file with @TeX{}.@refill
17110texinfo.texi(,17640)
17111texinfo.texi(,17641) Usually, you will want to do this after you have run
17112texinfo.texi(,17642) @code{texinfo-format-buffer} (or, better, @code{makeinfo-buffer}) on
17113texinfo.texi(,17643) the same file, because @code{texinfo-format-buffer} sometimes displays
17114texinfo.texi(,17644) error messages that make more sense than @TeX{}.  (@xref{Debugging
17115texinfo.texi(,17645) with Info}, for more information.)@refill
17116texinfo.texi(,17646)
17117texinfo.texi(,17647) For example, @TeX{} was run on a Texinfo file, part of which is shown
17118texinfo.texi(,17648) here:@refill
17119texinfo.texi(,17649)
17120texinfo.texi(,17650) @example
17121texinfo.texi(,17651) ---------- Buffer: texinfo.texi ----------
17122texinfo.texi(,17652) name of the Texinfo file as an extension.  The
17123texinfo.texi(,17653) @@samp@{??@} are `wildcards' that cause the shell to
17124texinfo.texi(,17654) substitute all the raw index files.  (@@xref@{sorting
17125texinfo.texi(,17655) indices, for more information about sorting
17126texinfo.texi(,17656) indices.)@@refill
17127texinfo.texi(,17657) ---------- Buffer: texinfo.texi ----------
17128texinfo.texi(,17658) @end example
17129texinfo.texi(,17659)
17130texinfo.texi(,17660) @noindent
17131texinfo.texi(,17661) (The cross reference lacks a closing brace.)
17132texinfo.texi(,17662) @TeX{} produced the following output, after which it stopped:@refill
17133texinfo.texi(,17663)
17134texinfo.texi(,17664) @example
17135texinfo.texi(,17665) ---------- Buffer: *tex-shell* ----------
17136texinfo.texi(,17666) Runaway argument?
17137texinfo.texi(,17667) @{sorting indices, for more information about sorting
17138texinfo.texi(,17668) indices.) @@refill @@ETC.
17139texinfo.texi(,17669) ! Paragraph ended before @@xref was complete.
17140texinfo.texi(,17670) <to be read again>
17141texinfo.texi(,17671)                    @@par
17142texinfo.texi(,17672) l.27
17143texinfo.texi(,17673)
17144texinfo.texi(,17674) ?
17145texinfo.texi(,17675) ---------- Buffer: *tex-shell* ----------
17146texinfo.texi(,17676) @end example
17147texinfo.texi(,17677)
17148texinfo.texi(,17678) In this case, @TeX{} produced an accurate and
17149texinfo.texi(,17679) understandable error message:
17150texinfo.texi(,17680)
17151texinfo.texi(,17681) @example
17152texinfo.texi(,17682) Paragraph ended before @@xref was complete.
17153texinfo.texi(,17683) @end example
17154texinfo.texi(,17684)
17155texinfo.texi(,17685) @noindent
17156texinfo.texi(,17686) @samp{@@par} is an internal @TeX{} command of no relevance to Texinfo.
17157texinfo.texi(,17687) @samp{l.27} means that @TeX{} detected the problem on line 27 of the
17158texinfo.texi(,17688) Texinfo file.  The @samp{?} is the prompt @TeX{} uses in this
17159texinfo.texi(,17689) circumstance.@refill
17160texinfo.texi(,17690)
17161texinfo.texi(,17691) Unfortunately, @TeX{} is not always so helpful, and sometimes you must
17162texinfo.texi(,17692) truly be a Sherlock Holmes to discover what went wrong.@refill
17163texinfo.texi(,17693)
17164texinfo.texi(,17694) In any case, if you run into a problem like this, you can do one of three
17165texinfo.texi(,17695) things.@refill
17166texinfo.texi(,17696)
17167texinfo.texi(,17697) @enumerate
17168texinfo.texi(,17698) @item
17169texinfo.texi(,17699) You can tell @TeX{} to continue running and ignore just this error by
17170texinfo.texi(,17700) typing @key{RET} at the @samp{?} prompt.@refill
17171texinfo.texi(,17701)
17172texinfo.texi(,17702) @item
17173texinfo.texi(,17703) You can tell @TeX{} to continue running and to ignore all errors as best
17174texinfo.texi(,17704) it can by typing @kbd{r @key{RET}} at the @samp{?} prompt.@refill
17175texinfo.texi(,17705)
17176texinfo.texi(,17706) This is often the best thing to do.  However, beware: the one error
17177texinfo.texi(,17707) may produce a cascade of additional error messages as its consequences
17178texinfo.texi(,17708) are felt through the rest of the file.  To stop @TeX{} when it is
17179texinfo.texi(,17709) producing such an avalanche of error messages, type @kbd{C-c} (or
17180texinfo.texi(,17710) @kbd{C-c C-c}, if you are running a shell inside Emacs).
17181texinfo.texi(,17711)
17182texinfo.texi(,17712) @item
17183texinfo.texi(,17713) You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}}
17184texinfo.texi(,17714) at the @samp{?} prompt.@refill
17185texinfo.texi(,17715) @end enumerate
17186texinfo.texi(,17716)
17187texinfo.texi(,17717) If you are running @TeX{} inside Emacs, you need to switch to the shell
17188texinfo.texi(,17718) buffer and line at which @TeX{} offers the @samp{?} prompt.
17189texinfo.texi(,17719)
17190texinfo.texi(,17720) Sometimes @TeX{} will format a file without producing error messages even
17191texinfo.texi(,17721) though there is a problem.  This usually occurs if a command is not ended
17192texinfo.texi(,17722) but @TeX{} is able to continue processing anyhow.  For example, if you fail
17193texinfo.texi(,17723) to end an itemized list with the @code{@@end itemize} command, @TeX{} will
17194texinfo.texi(,17724) write a DVI file that you can print out.  The only error message that
17195texinfo.texi(,17725) @TeX{} will give you is the somewhat mysterious comment that@refill
17196texinfo.texi(,17726)
17197texinfo.texi(,17727) @example
17198texinfo.texi(,17728) (@@end occurred inside a group at level 1)
17199texinfo.texi(,17729) @end example
17200texinfo.texi(,17730)
17201texinfo.texi(,17731) @noindent
17202texinfo.texi(,17732) However, if you print the DVI file, you will find that the text
17203texinfo.texi(,17733) of the file that follows the itemized list is entirely indented as if
17204texinfo.texi(,17734) it were part of the last item in the itemized list.  The error message
17205texinfo.texi(,17735) is the way @TeX{} says that it expected to find an @code{@@end}
17206texinfo.texi(,17736) command somewhere in the file; but that it could not determine where
17207texinfo.texi(,17737) it was needed.@refill
17208texinfo.texi(,17738)
17209texinfo.texi(,17739) Another source of notoriously hard-to-find errors is a missing
17210texinfo.texi(,17740) @code{@@end group} command.  If you ever are stumped by
17211texinfo.texi(,17741) incomprehensible errors, look for a missing @code{@@end group} command
17212texinfo.texi(,17742) first.@refill
17213texinfo.texi(,17743)
17214texinfo.texi(,17744) If the Texinfo file lacks header lines,
17215texinfo.texi(,17745) @TeX{} may stop in the
17216texinfo.texi(,17746) beginning of its run and display output that looks like the following.
17217texinfo.texi(,17747) The @samp{*} indicates that @TeX{} is waiting for input.@refill
17218texinfo.texi(,17748)
17219texinfo.texi(,17749) @example
17220texinfo.texi(,17750) This is TeX, Version 3.14159 (Web2c 7.0)
17221texinfo.texi(,17751) (test.texinfo [1])
17222texinfo.texi(,17752) *
17223texinfo.texi(,17753) @end example
17224texinfo.texi(,17754)
17225texinfo.texi(,17755) @noindent
17226texinfo.texi(,17756) In this case, simply type @kbd{\end @key{RET}} after the asterisk.  Then
17227texinfo.texi(,17757) write the header lines in the Texinfo file and run the @TeX{} command
17228texinfo.texi(,17758) again. (Note the use of the backslash, @samp{\}.  @TeX{} uses @samp{\}
17229texinfo.texi(,17759) instead of @samp{@@}; and in this circumstance, you are working
17230texinfo.texi(,17760) directly with @TeX{}, not with Texinfo.)@refill
17231texinfo.texi(,17761)
17232texinfo.texi(,17762) @node Using texinfo-show-structure, Using occur, Debugging with TeX, Catching Mistakes
17233texinfo.texi(,17763) @comment  node-name,  next,  previous,  up
17234texinfo.texi(,17764) @section Using @code{texinfo-show-structure}
17235texinfo.texi(,17765) @cindex Showing the structure of a file
17236texinfo.texi(,17766) @findex texinfo-show-structure
17237texinfo.texi(,17767)
17238texinfo.texi(,17768) It is not always easy to keep track of the nodes, chapters, sections, and
17239texinfo.texi(,17769) subsections of a Texinfo file.  This is especially true if you are revising
17240texinfo.texi(,17770) or adding to a Texinfo file that someone else has written.@refill
17241texinfo.texi(,17771)
17242texinfo.texi(,17772) In GNU Emacs, in Texinfo mode, the @code{texinfo-show-structure}
17243texinfo.texi(,17773) command lists all the lines that begin with the @@-commands that
17244texinfo.texi(,17774) specify the structure: @code{@@chapter}, @code{@@section},
17245texinfo.texi(,17775) @code{@@appendix}, and so on.  With an argument (@w{@kbd{C-u}}
17246texinfo.texi(,17776) as prefix argument, if interactive),
17247texinfo.texi(,17777) the command also shows the @code{@@node} lines.  The
17248texinfo.texi(,17778) @code{texinfo-show-structure} command is bound to @kbd{C-c C-s} in
17249texinfo.texi(,17779) Texinfo mode, by default.@refill
17250texinfo.texi(,17780)
17251texinfo.texi(,17781) The lines are displayed in a buffer called the @samp{*Occur*} buffer,
17252texinfo.texi(,17782) indented by hierarchical level.  For example, here is a part of what was
17253texinfo.texi(,17783) produced by running @code{texinfo-show-structure} on this manual:@refill
17254texinfo.texi(,17784)
17255texinfo.texi(,17785) @example
17256texinfo.texi(,17786) @group
17257texinfo.texi(,17787)  Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\|
17258texinfo.texi(,17788)  unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
17259texinfo.texi(,17789)  in buffer texinfo.texi.
17260texinfo.texi(,17790)  @dots{}
17261texinfo.texi(,17791)  4177:@@chapter Nodes
17262texinfo.texi(,17792)  4198:    @@heading Two Paths
17263texinfo.texi(,17793)  4231:    @@section Node and Menu Illustration
17264texinfo.texi(,17794)  4337:    @@section The @@code@{@@@@node@} Command
17265texinfo.texi(,17795)  4393:        @@subheading Choosing Node and Pointer Names
17266texinfo.texi(,17796)  4417:        @@subsection How to Write an @@code@{@@@@node@} Line
17267texinfo.texi(,17797)  4469:        @@subsection @@code@{@@@@node@} Line Tips
17268texinfo.texi(,17798)  @dots{}
17269texinfo.texi(,17799) @end group
17270texinfo.texi(,17800) @end example
17271texinfo.texi(,17801)
17272texinfo.texi(,17802) This says that lines 4337, 4393, and 4417 of @file{texinfo.texi} begin
17273texinfo.texi(,17803) with the @code{@@section}, @code{@@subheading}, and @code{@@subsection}
17274texinfo.texi(,17804) commands respectively.  If you move your cursor into the @samp{*Occur*}
17275texinfo.texi(,17805) window, you can position the cursor over one of the lines and use the
17276texinfo.texi(,17806) @kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to
17277texinfo.texi(,17807) the corresponding spot in the Texinfo file.  @xref{Other Repeating
17278texinfo.texi(,17808) Search, , Using Occur, emacs, The GNU Emacs Manual}, for more
17279texinfo.texi(,17809) information about @code{occur-mode-goto-occurrence}.@refill
17280texinfo.texi(,17810)
17281texinfo.texi(,17811) The first line in the @samp{*Occur*} window describes the @dfn{regular
17282texinfo.texi(,17812) expression} specified by @var{texinfo-heading-pattern}.  This regular
17283texinfo.texi(,17813) expression is the pattern that @code{texinfo-show-structure} looks for.
17284texinfo.texi(,17814) @xref{Regexps, , Using Regular Expressions, emacs, The GNU Emacs Manual},
17285texinfo.texi(,17815) for more information.@refill
17286texinfo.texi(,17816)
17287texinfo.texi(,17817) When you invoke the @code{texinfo-show-structure} command, Emacs will
17288texinfo.texi(,17818) display the structure of the whole buffer.  If you want to see the
17289texinfo.texi(,17819) structure of just a part of the buffer, of one chapter, for example,
17290texinfo.texi(,17820) use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the
17291texinfo.texi(,17821) region.  (@xref{Narrowing, , , emacs, The GNU Emacs Manual}.)  This is
17292texinfo.texi(,17822) how the example used above was generated.  (To see the whole buffer
17293texinfo.texi(,17823) again, use @kbd{C-x n w} (@code{widen}).)@refill
17294texinfo.texi(,17824)
17295texinfo.texi(,17825) If you call @code{texinfo-show-structure} with a prefix argument by
17296texinfo.texi(,17826) typing @w{@kbd{C-u C-c C-s}}, it will list lines beginning with
17297texinfo.texi(,17827) @code{@@node} as well as the lines beginning with the @@-sign commands
17298texinfo.texi(,17828) for @code{@@chapter}, @code{@@section}, and the like.@refill
17299texinfo.texi(,17829)
17300texinfo.texi(,17830) You can remind yourself of the structure of a Texinfo file by looking at
17301texinfo.texi(,17831) the list in the @samp{*Occur*} window; and if you have mis-named a node
17302texinfo.texi(,17832) or left out a section, you can correct the mistake.@refill
17303texinfo.texi(,17833)
17304texinfo.texi(,17834) @node Using occur, Running Info-Validate, Using texinfo-show-structure, Catching Mistakes
17305texinfo.texi(,17835) @comment  node-name,  next,  previous,  up
17306texinfo.texi(,17836) @section Using @code{occur}
17307texinfo.texi(,17837) @cindex Occurrences, listing with @code{@@occur}
17308texinfo.texi(,17838) @findex occur
17309texinfo.texi(,17839)
17310texinfo.texi(,17840) Sometimes the @code{texinfo-show-structure} command produces too much
17311texinfo.texi(,17841) information.  Perhaps you want to remind yourself of the overall structure
17312texinfo.texi(,17842) of a Texinfo file, and are overwhelmed by the detailed list produced by
17313texinfo.texi(,17843) @code{texinfo-show-structure}.  In this case, you can use the @code{occur}
17314texinfo.texi(,17844) command directly.  To do this, type@refill
17315texinfo.texi(,17845)
17316texinfo.texi(,17846) @example
17317texinfo.texi(,17847) @kbd{M-x occur}
17318texinfo.texi(,17848) @end example
17319texinfo.texi(,17849)
17320texinfo.texi(,17850) @noindent
17321texinfo.texi(,17851) and then, when prompted, type a @dfn{regexp}, a regular expression for
17322texinfo.texi(,17852) the pattern you want to match.  (@xref{Regexps, , Regular Expressions,
17323texinfo.texi(,17853) emacs, The GNU Emacs Manual}.)  The @code{occur} command works from
17324texinfo.texi(,17854) the current location of the cursor in the buffer to the end of the
17325texinfo.texi(,17855) buffer.  If you want to run @code{occur} on the whole buffer, place
17326texinfo.texi(,17856) the cursor at the beginning of the buffer.@refill
17327texinfo.texi(,17857)
17328texinfo.texi(,17858) For example, to see all the lines that contain the word
17329texinfo.texi(,17859) @samp{@@chapter} in them, just type @samp{@@chapter}.  This will
17330texinfo.texi(,17860) produce a list of the chapters.  It will also list all the sentences
17331texinfo.texi(,17861) with @samp{@@chapter} in the middle of the line.@refill
17332texinfo.texi(,17862)
17333texinfo.texi(,17863) If you want to see only those lines that start with the word
17334texinfo.texi(,17864) @samp{@@chapter}, type @samp{^@@chapter} when prompted by
17335texinfo.texi(,17865) @code{occur}.  If you want to see all the lines that end with a word
17336texinfo.texi(,17866) or phrase, end the last word with a @samp{$}; for example,
17337texinfo.texi(,17867) @samp{catching mistakes$}.  This can be helpful when you want to see
17338texinfo.texi(,17868) all the nodes that are part of the same chapter or section and
17339texinfo.texi(,17869) therefore have the same `Up' pointer.@refill
17340texinfo.texi(,17870)
17341texinfo.texi(,17871) @xref{Other Repeating Search, , Using Occur, emacs , The GNU Emacs Manual},
17342texinfo.texi(,17872) for more information.@refill
17343texinfo.texi(,17873)
17344texinfo.texi(,17874) @node Running Info-Validate,  , Using occur, Catching Mistakes
17345texinfo.texi(,17875) @comment  node-name,  next,  previous,  up
17346texinfo.texi(,17876) @section Finding Badly Referenced Nodes
17347texinfo.texi(,17877) @findex Info-validate
17348texinfo.texi(,17878) @cindex Nodes, checking for badly referenced
17349texinfo.texi(,17879) @cindex Checking for badly referenced nodes
17350texinfo.texi(,17880) @cindex Looking for badly referenced nodes
17351texinfo.texi(,17881) @cindex Finding badly referenced nodes
17352texinfo.texi(,17882) @cindex Badly referenced nodes
17353texinfo.texi(,17883)
17354texinfo.texi(,17884) You can use the @code{Info-validate} command to check whether any of
17355texinfo.texi(,17885) the `Next', `Previous', `Up' or other node pointers fail to point to a
17356texinfo.texi(,17886) node.  This command checks that every node pointer points to an
17357texinfo.texi(,17887) existing node.  The @code{Info-validate} command works only on Info
17358texinfo.texi(,17888) files, not on Texinfo files.@refill
17359texinfo.texi(,17889)
17360texinfo.texi(,17890) The @code{makeinfo} program validates pointers automatically, so you
17361texinfo.texi(,17891) do not need to use the @code{Info-validate} command if you are using
17362texinfo.texi(,17892) @code{makeinfo}.  You only may need to use @code{Info-validate} if you
17363texinfo.texi(,17893) are unable to run @code{makeinfo} and instead must create an Info file
17364texinfo.texi(,17894) using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or
17365texinfo.texi(,17895) if you write an Info file from scratch.@refill
17366texinfo.texi(,17896)
17367texinfo.texi(,17897) @menu
17368texinfo.texi(,17898) * Using Info-validate::         How to run @code{Info-validate}.
17369texinfo.texi(,17899) * Unsplit::                     How to create an unsplit file.
17370texinfo.texi(,17900) * Tagifying::                   How to tagify a file.
17371texinfo.texi(,17901) * Splitting::                   How to split a file manually.
17372texinfo.texi(,17902) @end menu
17373texinfo.texi(,17903)
17374texinfo.texi(,17904) @node Using Info-validate, Unsplit, Running Info-Validate, Running Info-Validate
17375texinfo.texi(,17905) @subsection Running @code{Info-validate}
17376texinfo.texi(,17906) @cindex Running @code{Info-validate}
17377texinfo.texi(,17907) @cindex Info validating a large file
17378texinfo.texi(,17908) @cindex Validating a large file
17379texinfo.texi(,17909)
17380texinfo.texi(,17910) To use @code{Info-validate}, visit the Info file you wish to check and
17381texinfo.texi(,17911) type:@refill
17382texinfo.texi(,17912)
17383texinfo.texi(,17913) @example
17384texinfo.texi(,17914) M-x Info-validate
17385texinfo.texi(,17915) @end example
17386texinfo.texi(,17916)
17387texinfo.texi(,17917) @noindent
17388texinfo.texi(,17918) Note that the @code{Info-validate} command requires an upper case
17389texinfo.texi(,17919) `I'.  You may also need to create a tag table before running
17390texinfo.texi(,17920) @code{Info-validate}.  @xref{Tagifying}.
17391texinfo.texi(,17921)
17392texinfo.texi(,17922) If your file is valid, you will receive a message that says ``File appears
17393texinfo.texi(,17923) valid''.  However, if you have a pointer that does not point to a node,
17394texinfo.texi(,17924) error messages will be displayed in a buffer called @samp{*problems in
17395texinfo.texi(,17925) info file*}.@refill
17396texinfo.texi(,17926)
17397texinfo.texi(,17927) For example, @code{Info-validate} was run on a test file that contained
17398texinfo.texi(,17928) only the first node of this manual.  One of the messages said:@refill
17399texinfo.texi(,17929)
17400texinfo.texi(,17930) @example
17401texinfo.texi(,17931) In node "Overview", invalid Next: Texinfo Mode
17402texinfo.texi(,17932) @end example
17403texinfo.texi(,17933)
17404texinfo.texi(,17934) @noindent
17405texinfo.texi(,17935) This meant that the node called @samp{Overview} had a `Next' pointer that
17406texinfo.texi(,17936) did not point to anything (which was true in this case, since the test file
17407texinfo.texi(,17937) had only one node in it).@refill
17408texinfo.texi(,17938)
17409texinfo.texi(,17939) Now suppose we add a node named @samp{Texinfo Mode} to our test case
17410texinfo.texi(,17940) but we do not specify a `Previous' for this node.  Then we will get
17411texinfo.texi(,17941) the following error message:@refill
17412texinfo.texi(,17942)
17413texinfo.texi(,17943) @example
17414texinfo.texi(,17944) In node "Texinfo Mode", should have Previous: Overview
17415texinfo.texi(,17945) @end example
17416texinfo.texi(,17946)
17417texinfo.texi(,17947) @noindent
17418texinfo.texi(,17948) This is because every `Next' pointer should be matched by a
17419texinfo.texi(,17949) `Previous' (in the node where the `Next' points) which points back.@refill
17420texinfo.texi(,17950)
17421texinfo.texi(,17951) @code{Info-validate} also checks that all menu entries and cross references
17422texinfo.texi(,17952) point to actual nodes.@refill
17423texinfo.texi(,17953)
17424texinfo.texi(,17954) @code{Info-validate} requires a tag table and does not work with files
17425texinfo.texi(,17955) that have been split.  (The @code{texinfo-format-buffer} command
17426texinfo.texi(,17956) automatically splits large files.)  In order to use @code{Info-validate}
17427texinfo.texi(,17957) on a large file, you must run @code{texinfo-format-buffer} with an
17428texinfo.texi(,17958) argument so that it does not split the Info file; and you must create a
17429texinfo.texi(,17959) tag table for the unsplit file.
17430texinfo.texi(,17960)
17431texinfo.texi(,17961) @node Unsplit, Tagifying, Using Info-validate, Running Info-Validate
17432texinfo.texi(,17962) @comment  node-name,  next,  previous,  up
17433texinfo.texi(,17963) @subsection Creating an Unsplit File
17434texinfo.texi(,17964) @cindex Creating an unsplit file
17435texinfo.texi(,17965) @cindex Unsplit file creation
17436texinfo.texi(,17966)
17437texinfo.texi(,17967) You can run @code{Info-validate} only on a single Info file that has a
17438texinfo.texi(,17968) tag table.  The command will not work on the indirect subfiles that
17439texinfo.texi(,17969) are generated when a master file is split.  If you have a large file
17440texinfo.texi(,17970) (longer than 70,000 bytes or so), you need to run the
17441texinfo.texi(,17971) @code{texinfo-format-buffer} or @code{makeinfo-buffer} command in such
17442texinfo.texi(,17972) a way that it does not create indirect subfiles.  You will also need
17443texinfo.texi(,17973) to create a tag table for the Info file.  After you have done this,
17444texinfo.texi(,17974) you can run @code{Info-validate} and look for badly referenced
17445texinfo.texi(,17975) nodes.@refill
17446texinfo.texi(,17976)
17447texinfo.texi(,17977) The first step is to create an unsplit Info file.  To prevent
17448texinfo.texi(,17978) @code{texinfo-format-buffer} from splitting a Texinfo file into
17449texinfo.texi(,17979) smaller Info files, give a prefix to the @kbd{M-x
17450texinfo.texi(,17980) texinfo-format-buffer} command:@refill
17451texinfo.texi(,17981)
17452texinfo.texi(,17982) @example
17453texinfo.texi(,17983) C-u M-x texinfo-format-buffer
17454texinfo.texi(,17984) @end example
17455texinfo.texi(,17985)
17456texinfo.texi(,17986) @noindent
17457texinfo.texi(,17987) or else
17458texinfo.texi(,17988)
17459texinfo.texi(,17989) @example
17460texinfo.texi(,17990) C-u C-c C-e C-b
17461texinfo.texi(,17991) @end example
17462texinfo.texi(,17992)
17463texinfo.texi(,17993) @noindent
17464texinfo.texi(,17994) When you do this, Texinfo will not split the file and will not create
17465texinfo.texi(,17995) a tag table for it. @refill
17466texinfo.texi(,17996) @cindex Making a tag table manually
17467texinfo.texi(,17997) @cindex Tag table, making manually
17468texinfo.texi(,17998)
17469texinfo.texi(,17999) @node Tagifying, Splitting, Unsplit, Running Info-Validate
17470texinfo.texi(,18000) @subsection Tagifying a File
17471texinfo.texi(,18001)
17472texinfo.texi(,18002) After creating an unsplit Info file, you must create a tag table for
17473texinfo.texi(,18003) it.  Visit the Info file you wish to tagify and type:@refill
17474texinfo.texi(,18004)
17475texinfo.texi(,18005) @example
17476texinfo.texi(,18006) M-x Info-tagify
17477texinfo.texi(,18007) @end example
17478texinfo.texi(,18008)
17479texinfo.texi(,18009) @noindent
17480texinfo.texi(,18010) (Note the upper case @samp{I} in @code{Info-tagify}.)  This creates an
17481texinfo.texi(,18011) Info file with a tag table that you can validate.@refill
17482texinfo.texi(,18012)
17483texinfo.texi(,18013) The third step is to validate the Info file:@refill
17484texinfo.texi(,18014)
17485texinfo.texi(,18015) @example
17486texinfo.texi(,18016) M-x Info-validate
17487texinfo.texi(,18017) @end example
17488texinfo.texi(,18018)
17489texinfo.texi(,18019) @noindent
17490texinfo.texi(,18020) (Note the upper case @samp{I} in @code{Info-validate}.)
17491texinfo.texi(,18021) In brief, the steps are:@refill
17492texinfo.texi(,18022)
17493texinfo.texi(,18023) @example
17494texinfo.texi(,18024) @group
17495texinfo.texi(,18025) C-u M-x texinfo-format-buffer
17496texinfo.texi(,18026) M-x Info-tagify
17497texinfo.texi(,18027) M-x Info-validate
17498texinfo.texi(,18028) @end group
17499texinfo.texi(,18029) @end example
17500texinfo.texi(,18030)
17501texinfo.texi(,18031) After you have validated the node structure, you can rerun
17502texinfo.texi(,18032) @code{texinfo-format-buffer} in the normal way so it will construct a
17503texinfo.texi(,18033) tag table and split the file automatically, or you can make the tag
17504texinfo.texi(,18034) table and split the file manually.@refill
17505texinfo.texi(,18035)
17506texinfo.texi(,18036) @node Splitting,  , Tagifying, Running Info-Validate
17507texinfo.texi(,18037) @comment  node-name,  next,  previous,  up
17508texinfo.texi(,18038) @subsection Splitting a File Manually
17509texinfo.texi(,18039) @cindex Splitting an Info file manually
17510texinfo.texi(,18040) @cindex Info file, splitting manually
17511texinfo.texi(,18041)
17512texinfo.texi(,18042) You should split a large file or else let the
17513texinfo.texi(,18043) @code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it
17514texinfo.texi(,18044) for you automatically.  (Generally you will let one of the formatting
17515texinfo.texi(,18045) commands do this job for you.  @xref{Creating an Info File}.)@refill
17516texinfo.texi(,18046)
17517texinfo.texi(,18047) The split-off files are called the indirect subfiles.@refill
17518texinfo.texi(,18048)
17519texinfo.texi(,18049) Info files are split to save memory.  With smaller files, Emacs does not
17520texinfo.texi(,18050) have make such a large buffer to hold the information.@refill
17521texinfo.texi(,18051)
17522texinfo.texi(,18052) If an Info file has more than 30 nodes, you should also make a tag
17523texinfo.texi(,18053) table for it. @xref{Using Info-validate}, for information
17524texinfo.texi(,18054) about creating a tag table.  (Again, tag tables are usually created
17525texinfo.texi(,18055) automatically by the formatting command; you only need to create a tag
17526texinfo.texi(,18056) table yourself if you are doing the job manually.  Most likely, you
17527texinfo.texi(,18057) will do this for a large, unsplit file on which you have run
17528texinfo.texi(,18058) @code{Info-validate}.)@refill
17529texinfo.texi(,18059)
17530texinfo.texi(,18060) @c Info-split is autoloaded in `loaddefs.el' in Emacs 18.51
17531texinfo.texi(,18066)
17532texinfo.texi(,18067) Visit the Info file you wish to tagify and split and type the two
17533texinfo.texi(,18068) commands:@refill
17534texinfo.texi(,18069)
17535texinfo.texi(,18070) @example
17536texinfo.texi(,18071) M-x Info-tagify
17537texinfo.texi(,18072) M-x Info-split
17538texinfo.texi(,18073) @end example
17539texinfo.texi(,18074)
17540texinfo.texi(,18075) @noindent
17541texinfo.texi(,18076) (Note that the @samp{I} in @samp{Info} is upper case.)@refill
17542texinfo.texi(,18077)
17543texinfo.texi(,18078) When you use the @code{Info-split} command, the buffer is modified into a
17544texinfo.texi(,18079) (small) Info file which lists the indirect subfiles.  This file should be
17545texinfo.texi(,18080) saved in place of the original visited file.  The indirect subfiles are
17546texinfo.texi(,18081) written in the same directory the original file is in, with names generated
17547texinfo.texi(,18082) by appending @samp{-} and a number to the original file name.@refill
17548texinfo.texi(,18083)
17549texinfo.texi(,18084) The primary file still functions as an Info file, but it contains just
17550texinfo.texi(,18085) the tag table and a directory of subfiles.@refill
17551texinfo.texi(,18086)
17552texinfo.texi(,18087)
17553texinfo.texi(,18088) @node Refilling Paragraphs
17554texinfo.texi(,18089) @appendix Refilling Paragraphs
17555texinfo.texi(,18090) @cindex Refilling paragraphs
17556texinfo.texi(,18091) @cindex Filling paragraphs
17557texinfo.texi(,18092) @cindex Paragraphs, filling
17558texinfo.texi(,18093) @findex refill
17559texinfo.texi(,18094)
17560texinfo.texi(,18095) The @code{@@refill} command refills and, optionally, indents the first
17561texinfo.texi(,18096) line of a paragraph.@footnote{Perhaps the command should have been
17562texinfo.texi(,18097) called the @code{@@refillandindent} command, but @code{@@refill} is
17563texinfo.texi(,18098) shorter and the name was chosen before indenting was possible.} The
17564texinfo.texi(,18099) @code{@@refill} command is no longer important, but we describe it here
17565texinfo.texi(,18100) because you once needed it.  You will see it in many old Texinfo
17566texinfo.texi(,18101) files.@refill
17567texinfo.texi(,18102)
17568texinfo.texi(,18103) Without refilling, paragraphs containing long @@-constructs may look
17569texinfo.texi(,18104) bad after formatting because the formatter removes @@-commands and
17570texinfo.texi(,18105) shortens some lines more than others.  In the past, neither the
17571texinfo.texi(,18106) @code{texinfo-format-region} command nor the
17572texinfo.texi(,18107) @code{texinfo-format-buffer} command refilled paragraphs
17573texinfo.texi(,18108) automatically.  The @code{@@refill} command had to be written at the
17574texinfo.texi(,18109) end of every paragraph to cause these formatters to fill them.  (Both
17575texinfo.texi(,18110) @TeX{} and @code{makeinfo} have always refilled paragraphs
17576texinfo.texi(,18111) automatically.)  Now, all the Info formatters automatically fill and
17577texinfo.texi(,18112) indent those paragraphs that need to be filled and indented.@refill
17578texinfo.texi(,18113)
17579texinfo.texi(,18114) The @code{@@refill} command causes @code{texinfo-format-region} and
17580texinfo.texi(,18115) @code{texinfo-format-buffer} to refill a paragraph in the Info file
17581texinfo.texi(,18116) @emph{after} all the other processing has been done.  For this reason,
17582texinfo.texi(,18117) you can not use @code{@@refill} with a paragraph containing either
17583texinfo.texi(,18118) @code{@@*} or @code{@@w@{ @dots{} @}} since the refilling action will
17584texinfo.texi(,18119) override those two commands.@refill
17585texinfo.texi(,18120)
17586texinfo.texi(,18121) The @code{texinfo-format-region} and @code{texinfo-format-buffer}
17587texinfo.texi(,18122) commands now automatically append @code{@@refill} to the end of each
17588texinfo.texi(,18123) paragraph that should be filled.  They do not append @code{@@refill} to
17589texinfo.texi(,18124) the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}}
17590texinfo.texi(,18125) and therefore do not refill or indent them.@refill
17591texinfo.texi(,18126)
17592texinfo.texi(,18127)
17593texinfo.texi(,18128) @node Command Syntax
17594texinfo.texi(,18129) @appendix @@-Command Syntax
17595texinfo.texi(,18130) @cindex @@-command syntax
17596texinfo.texi(,18131) @cindex Syntax, of @@-commands
17597texinfo.texi(,18132) @cindex Command syntax
17598texinfo.texi(,18133)
17599texinfo.texi(,18134) The character @samp{@@} is used to start special Texinfo commands.
17600texinfo.texi(,18135) (It has the same meaning that @samp{\} has in plain @TeX{}.)  Texinfo
17601texinfo.texi(,18136) has four types of @@-command:@refill
17602texinfo.texi(,18137)
17603texinfo.texi(,18138) @table @asis
17604texinfo.texi(,18139) @item 1. Non-alphabetic commands.
17605texinfo.texi(,18140) These commands consist of an @@ followed by a punctuation mark or other
17606texinfo.texi(,18141) character that is not part of the alphabet.  Non-alphabetic commands are
17607texinfo.texi(,18142) almost always part of the text within a paragraph, and never take any
17608texinfo.texi(,18143) argument.  The two characters (@@ and the other one) are complete in
17609texinfo.texi(,18144) themselves; none is followed by braces.  The non-alphabetic commands
17610texinfo.texi(,18145) are: @code{@@.}, @code{@@:}, @code{@@*}, @code{@@@kbd{SPACE}},
17611texinfo.texi(,18146) @code{@@@kbd{TAB}}, @code{@@@kbd{NL}}, @code{@@@@}, @code{@@@{}, and
17612texinfo.texi(,18147) @code{@@@}}.@refill
17613texinfo.texi(,18148)
17614texinfo.texi(,18149) @item 2. Alphabetic commands that do not require arguments.
17615texinfo.texi(,18150) These commands start with @@ followed by a word followed by left- and
17616texinfo.texi(,18151) right-hand braces.  These commands insert special symbols in the
17617texinfo.texi(,18152) document; they do not require arguments.  For example,
17618texinfo.texi(,18153) @code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}}
17619texinfo.texi(,18154) @result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}',
17620texinfo.texi(,18155) and @code{@@bullet@{@}} @result{} @samp{@bullet{}}.@refill
17621texinfo.texi(,18156)
17622texinfo.texi(,18157) @item 3. Alphabetic commands that require arguments within braces.
17623texinfo.texi(,18158) These commands start with @@ followed by a letter or a word, followed by an
17624texinfo.texi(,18159) argument within braces.  For example, the command @code{@@dfn} indicates
17625texinfo.texi(,18160) the introductory or defining use of a term; it is used as follows: @samp{In
17626texinfo.texi(,18161) Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.}@refill
17627texinfo.texi(,18162)
17628texinfo.texi(,18163) @item 4. Alphabetic commands that occupy an entire line.
17629texinfo.texi(,18164) These commands occupy an entire line.  The line starts with @@,
17630texinfo.texi(,18165) followed by the name of the command (a word); for example, @code{@@center}
17631texinfo.texi(,18166) or @code{@@cindex}.  If no argument is needed, the word is followed by
17632texinfo.texi(,18167) the end of the line.  If there is an argument, it is separated from
17633texinfo.texi(,18168) the command name by a space.  Braces are not used.@refill
17634texinfo.texi(,18169) @end table
17635texinfo.texi(,18170)
17636texinfo.texi(,18171) @cindex Braces and argument syntax
17637texinfo.texi(,18172) Thus, the alphabetic commands fall into classes that have
17638texinfo.texi(,18173) different argument syntaxes.  You cannot tell to which class a command
17639texinfo.texi(,18174) belongs by the appearance of its name, but you can tell by the
17640texinfo.texi(,18175) command's meaning: if the command stands for a glyph, it is in
17641texinfo.texi(,18176) class 2 and does not require an argument; if it makes sense to use the
17642texinfo.texi(,18177) command together with other text as part of a paragraph, the command
17643texinfo.texi(,18178) is in class 3 and must be followed by an argument in braces;
17644texinfo.texi(,18179) otherwise, it is in class 4 and uses the rest of the line as its
17645texinfo.texi(,18180) argument.@refill
17646texinfo.texi(,18181)
17647texinfo.texi(,18182) The purpose of having a different syntax for commands of classes 3 and
17648texinfo.texi(,18183) 4 is to make Texinfo files easier to read, and also to help the GNU
17649texinfo.texi(,18184) Emacs paragraph and filling commands work properly.  There is only one
17650texinfo.texi(,18185) exception to this rule: the command @code{@@refill}, which is always
17651texinfo.texi(,18186) used at the end of a paragraph immediately following the final period
17652texinfo.texi(,18187) or other punctuation character.  @code{@@refill} takes no argument and
17653texinfo.texi(,18188) does @emph{not} require braces.  @code{@@refill} never confuses the
17654texinfo.texi(,18189) Emacs paragraph commands because it cannot appear at the beginning of
17655texinfo.texi(,18190) a line.@refill
17656texinfo.texi(,18191)
17657texinfo.texi(,18192)
17658texinfo.texi(,18193) @node Obtaining TeX
17659texinfo.texi(,18194) @appendix How to Obtain @TeX{}
17660texinfo.texi(,18195) @cindex Obtaining @TeX{}
17661texinfo.texi(,18196) @cindex @TeX{}, how to obtain
17662texinfo.texi(,18197)
17663texinfo.texi(,18198) @c !!! Here is information about obtaining TeX.  Update it whenever.
17664texinfo.texi(,18199) @c !!! Also consider updating TeX.README on ftp.gnu.org.
17665texinfo.texi(,18200) @c     Updated by RJC on 1 March 1995, conversation with MacKay.
17666texinfo.texi(,18201) @c     Updated by kb@cs.umb.edu on 29 July 1996.
17667texinfo.texi(,18202) @c     Updated by kb@cs.umb.edu on 25 April 1997.
17668texinfo.texi(,18203) @c     Updated by kb@cs.umb.edu on 27 February 1998.
17669texinfo.texi(,18204) @TeX{} is freely redistributable.  You can obtain @TeX{} for Unix
17670texinfo.texi(,18205) systems via anonymous ftp or on physical media.  The core material
17671texinfo.texi(,18206) consists of the Web2c @TeX{} distribution (@uref{http://tug.org/web2c}).
17672texinfo.texi(,18207)
17673texinfo.texi(,18208) Instructions for retrieval by anonymous ftp and information on other
17674texinfo.texi(,18209) available distributions:
17675texinfo.texi(,18210) @example
17676texinfo.texi(,18211) @uref{ftp://tug.org/tex/unixtex.ftp}
17677texinfo.texi(,18212) @uref{http://tug.org/unixtex.ftp}
17678texinfo.texi(,18213) @end example
17679texinfo.texi(,18214)
17680texinfo.texi(,18215) The Free Software Foundation provides a core distribution on its Source
17681texinfo.texi(,18216) Code CD-ROM suitable for printing Texinfo manuals.  To order it, contact:
17682texinfo.texi(,18217)
17683texinfo.texi(,18218) @display
17684texinfo.texi(,18219) @group
17685texinfo.texi(,18220) Free Software Foundation, Inc.
17686texinfo.texi(,18221) 59 Temple Place Suite 330
17687texinfo.texi(,18222) Boston, MA @ @ 02111-1307
17688texinfo.texi(,18223) USA
17689texinfo.texi(,18224) Telephone: @w{+1-617-542-5942}
17690texinfo.texi(,18225) Fax: (including Japan) @w{+1-617-542-2652}
17691texinfo.texi(,18226) Free Dial Fax (in Japan):
17692texinfo.texi(,18227) @w{ } @w{ } @w{ } 0031-13-2473 (KDD)
17693texinfo.texi(,18228) @w{ } @w{ } @w{ } 0066-3382-0158 (IDC)
17694texinfo.texi(,18229) Electronic mail: @code{gnu@@gnu.org}
17695texinfo.texi(,18230) @end group
17696texinfo.texi(,18231) @end display
17697texinfo.texi(,18232)
17698texinfo.texi(,18233) Many other @TeX{} distributions are available; see
17699texinfo.texi(,18234) @uref{http://tug.org/}.
17700texinfo.texi(,18235)
17701texinfo.texi(,18236)
17702texinfo.texi(,18237) @c These are no longer ``new'', and the explanations
17703texinfo.texi(,18238) @c are all given elsewhere anyway, I think.  --karl, 25apr97.
17704texinfo.texi(,18239) @c So ignore the entire appendix.
17705texinfo.texi(,18726)
17706texinfo.texi(,18727)
17707texinfo.texi(,18728) @node Copying This Manual
17708texinfo.texi(,18729) @appendix Copying This Manual
17709texinfo.texi(,18730)
17710texinfo.texi(,18731) @menu
17711texinfo.texi(,18732) * GNU Free Documentation License::  License for copying this manual.
17712texinfo.texi(,18733) @end menu
17713texinfo.texi(,18734)
17714fdl.texi(,1)
17715fdl.texi(,2) @node GNU Free Documentation License
17716fdl.texi(,3) @appendixsec GNU Free Documentation License
17717fdl.texi(,4)
17718fdl.texi(,5) @cindex FDL, GNU Free Documentation License
17719fdl.texi(,6) @center Version 1.1, March 2000
17720fdl.texi(,7)
17721fdl.texi(,8) @display
17722fdl.texi(,9) Copyright @copyright{} 2000 Free Software Foundation, Inc.
17723fdl.texi(,10) 59 Temple Place, Suite 330, Boston, MA  02111-1307, USA
17724fdl.texi(,11)
17725fdl.texi(,12) Everyone is permitted to copy and distribute verbatim copies
17726fdl.texi(,13) of this license document, but changing it is not allowed.
17727fdl.texi(,14) @end display
17728fdl.texi(,15)
17729fdl.texi(,16) @enumerate 0
17730fdl.texi(,17) @item
17731fdl.texi(,18) PREAMBLE
17732fdl.texi(,19)
17733fdl.texi(,20) The purpose of this License is to make a manual, textbook, or other
17734fdl.texi(,21) written document @dfn{free} in the sense of freedom: to assure everyone
17735fdl.texi(,22) the effective freedom to copy and redistribute it, with or without
17736fdl.texi(,23) modifying it, either commercially or noncommercially.  Secondarily,
17737fdl.texi(,24) this License preserves for the author and publisher a way to get
17738fdl.texi(,25) credit for their work, while not being considered responsible for
17739fdl.texi(,26) modifications made by others.
17740fdl.texi(,27)
17741fdl.texi(,28) This License is a kind of ``copyleft'', which means that derivative
17742fdl.texi(,29) works of the document must themselves be free in the same sense.  It
17743fdl.texi(,30) complements the GNU General Public License, which is a copyleft
17744fdl.texi(,31) license designed for free software.
17745fdl.texi(,32)
17746fdl.texi(,33) We have designed this License in order to use it for manuals for free
17747fdl.texi(,34) software, because free software needs free documentation: a free
17748fdl.texi(,35) program should come with manuals providing the same freedoms that the
17749fdl.texi(,36) software does.  But this License is not limited to software manuals;
17750fdl.texi(,37) it can be used for any textual work, regardless of subject matter or
17751fdl.texi(,38) whether it is published as a printed book.  We recommend this License
17752fdl.texi(,39) principally for works whose purpose is instruction or reference.
17753fdl.texi(,40)
17754fdl.texi(,41) @item
17755fdl.texi(,42) APPLICABILITY AND DEFINITIONS
17756fdl.texi(,43)
17757fdl.texi(,44) This License applies to any manual or other work that contains a
17758fdl.texi(,45) notice placed by the copyright holder saying it can be distributed
17759fdl.texi(,46) under the terms of this License.  The ``Document'', below, refers to any
17760fdl.texi(,47) such manual or work.  Any member of the public is a licensee, and is
17761fdl.texi(,48) addressed as ``you''.
17762fdl.texi(,49)
17763fdl.texi(,50) A ``Modified Version'' of the Document means any work containing the
17764fdl.texi(,51) Document or a portion of it, either copied verbatim, or with
17765fdl.texi(,52) modifications and/or translated into another language.
17766fdl.texi(,53)
17767fdl.texi(,54) A ``Secondary Section'' is a named appendix or a front-matter section of
17768fdl.texi(,55) the Document that deals exclusively with the relationship of the
17769fdl.texi(,56) publishers or authors of the Document to the Document's overall subject
17770fdl.texi(,57) (or to related matters) and contains nothing that could fall directly
17771fdl.texi(,58) within that overall subject.  (For example, if the Document is in part a
17772fdl.texi(,59) textbook of mathematics, a Secondary Section may not explain any
17773fdl.texi(,60) mathematics.)  The relationship could be a matter of historical
17774fdl.texi(,61) connection with the subject or with related matters, or of legal,
17775fdl.texi(,62) commercial, philosophical, ethical or political position regarding
17776fdl.texi(,63) them.
17777fdl.texi(,64)
17778fdl.texi(,65) The ``Invariant Sections'' are certain Secondary Sections whose titles
17779fdl.texi(,66) are designated, as being those of Invariant Sections, in the notice
17780fdl.texi(,67) that says that the Document is released under this License.
17781fdl.texi(,68)
17782fdl.texi(,69) The ``Cover Texts'' are certain short passages of text that are listed,
17783fdl.texi(,70) as Front-Cover Texts or Back-Cover Texts, in the notice that says that
17784fdl.texi(,71) the Document is released under this License.
17785fdl.texi(,72)
17786fdl.texi(,73) A ``Transparent'' copy of the Document means a machine-readable copy,
17787fdl.texi(,74) represented in a format whose specification is available to the
17788fdl.texi(,75) general public, whose contents can be viewed and edited directly and
17789fdl.texi(,76) straightforwardly with generic text editors or (for images composed of
17790fdl.texi(,77) pixels) generic paint programs or (for drawings) some widely available
17791fdl.texi(,78) drawing editor, and that is suitable for input to text formatters or
17792fdl.texi(,79) for automatic translation to a variety of formats suitable for input
17793fdl.texi(,80) to text formatters.  A copy made in an otherwise Transparent file
17794fdl.texi(,81) format whose markup has been designed to thwart or discourage
17795fdl.texi(,82) subsequent modification by readers is not Transparent.  A copy that is
17796fdl.texi(,83) not ``Transparent'' is called ``Opaque''.
17797fdl.texi(,84)
17798fdl.texi(,85) Examples of suitable formats for Transparent copies include plain
17799fdl.texi(,86) @sc{ascii} without markup, Texinfo input format, La@TeX{} input format,
17800fdl.texi(,87) @acronym{SGML} or @acronym{XML} using a publicly available
17801fdl.texi(,88) @acronym{DTD}, and standard-conforming simple @acronym{HTML} designed
17802fdl.texi(,89) for human modification.  Opaque formats include PostScript,
17803fdl.texi(,90) @acronym{PDF}, proprietary formats that can be read and edited only by
17804fdl.texi(,91) proprietary word processors, @acronym{SGML} or @acronym{XML} for which
17805fdl.texi(,92) the @acronym{DTD} and/or processing tools are not generally available,
17806fdl.texi(,93) and the machine-generated @acronym{HTML} produced by some word
17807fdl.texi(,94) processors for output purposes only.
17808fdl.texi(,95)
17809fdl.texi(,96) The ``Title Page'' means, for a printed book, the title page itself,
17810fdl.texi(,97) plus such following pages as are needed to hold, legibly, the material
17811fdl.texi(,98) this License requires to appear in the title page.  For works in
17812fdl.texi(,99) formats which do not have any title page as such, ``Title Page'' means
17813fdl.texi(,100) the text near the most prominent appearance of the work's title,
17814fdl.texi(,101) preceding the beginning of the body of the text.
17815fdl.texi(,102)
17816fdl.texi(,103) @item
17817fdl.texi(,104) VERBATIM COPYING
17818fdl.texi(,105)
17819fdl.texi(,106) You may copy and distribute the Document in any medium, either
17820fdl.texi(,107) commercially or noncommercially, provided that this License, the
17821fdl.texi(,108) copyright notices, and the license notice saying this License applies
17822fdl.texi(,109) to the Document are reproduced in all copies, and that you add no other
17823fdl.texi(,110) conditions whatsoever to those of this License.  You may not use
17824fdl.texi(,111) technical measures to obstruct or control the reading or further
17825fdl.texi(,112) copying of the copies you make or distribute.  However, you may accept
17826fdl.texi(,113) compensation in exchange for copies.  If you distribute a large enough
17827fdl.texi(,114) number of copies you must also follow the conditions in section 3.
17828fdl.texi(,115)
17829fdl.texi(,116) You may also lend copies, under the same conditions stated above, and
17830fdl.texi(,117) you may publicly display copies.
17831fdl.texi(,118)
17832fdl.texi(,119) @item
17833fdl.texi(,120) COPYING IN QUANTITY
17834fdl.texi(,121)
17835fdl.texi(,122) If you publish printed copies of the Document numbering more than 100,
17836fdl.texi(,123) and the Document's license notice requires Cover Texts, you must enclose
17837fdl.texi(,124) the copies in covers that carry, clearly and legibly, all these Cover
17838fdl.texi(,125) Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
17839fdl.texi(,126) the back cover.  Both covers must also clearly and legibly identify
17840fdl.texi(,127) you as the publisher of these copies.  The front cover must present
17841fdl.texi(,128) the full title with all words of the title equally prominent and
17842fdl.texi(,129) visible.  You may add other material on the covers in addition.
17843fdl.texi(,130) Copying with changes limited to the covers, as long as they preserve
17844fdl.texi(,131) the title of the Document and satisfy these conditions, can be treated
17845fdl.texi(,132) as verbatim copying in other respects.
17846fdl.texi(,133)
17847fdl.texi(,134) If the required texts for either cover are too voluminous to fit
17848fdl.texi(,135) legibly, you should put the first ones listed (as many as fit
17849fdl.texi(,136) reasonably) on the actual cover, and continue the rest onto adjacent
17850fdl.texi(,137) pages.
17851fdl.texi(,138)
17852fdl.texi(,139) If you publish or distribute Opaque copies of the Document numbering
17853fdl.texi(,140) more than 100, you must either include a machine-readable Transparent
17854fdl.texi(,141) copy along with each Opaque copy, or state in or with each Opaque copy
17855fdl.texi(,142) a publicly-accessible computer-network location containing a complete
17856fdl.texi(,143) Transparent copy of the Document, free of added material, which the
17857fdl.texi(,144) general network-using public has access to download anonymously at no
17858fdl.texi(,145) charge using public-standard network protocols.  If you use the latter
17859fdl.texi(,146) option, you must take reasonably prudent steps, when you begin
17860fdl.texi(,147) distribution of Opaque copies in quantity, to ensure that this
17861fdl.texi(,148) Transparent copy will remain thus accessible at the stated location
17862fdl.texi(,149) until at least one year after the last time you distribute an Opaque
17863fdl.texi(,150) copy (directly or through your agents or retailers) of that edition to
17864fdl.texi(,151) the public.
17865fdl.texi(,152)
17866fdl.texi(,153) It is requested, but not required, that you contact the authors of the
17867fdl.texi(,154) Document well before redistributing any large number of copies, to give
17868fdl.texi(,155) them a chance to provide you with an updated version of the Document.
17869fdl.texi(,156)
17870fdl.texi(,157) @item
17871fdl.texi(,158) MODIFICATIONS
17872fdl.texi(,159)
17873fdl.texi(,160) You may copy and distribute a Modified Version of the Document under
17874fdl.texi(,161) the conditions of sections 2 and 3 above, provided that you release
17875fdl.texi(,162) the Modified Version under precisely this License, with the Modified
17876fdl.texi(,163) Version filling the role of the Document, thus licensing distribution
17877fdl.texi(,164) and modification of the Modified Version to whoever possesses a copy
17878fdl.texi(,165) of it.  In addition, you must do these things in the Modified Version:
17879fdl.texi(,166)
17880fdl.texi(,167) @enumerate A
17881fdl.texi(,168) @item
17882fdl.texi(,169) Use in the Title Page (and on the covers, if any) a title distinct
17883fdl.texi(,170) from that of the Document, and from those of previous versions
17884fdl.texi(,171) (which should, if there were any, be listed in the History section
17885fdl.texi(,172) of the Document).  You may use the same title as a previous version
17886fdl.texi(,173) if the original publisher of that version gives permission.
17887fdl.texi(,174)
17888fdl.texi(,175) @item
17889fdl.texi(,176) List on the Title Page, as authors, one or more persons or entities
17890fdl.texi(,177) responsible for authorship of the modifications in the Modified
17891fdl.texi(,178) Version, together with at least five of the principal authors of the
17892fdl.texi(,179) Document (all of its principal authors, if it has less than five).
17893fdl.texi(,180)
17894fdl.texi(,181) @item
17895fdl.texi(,182) State on the Title page the name of the publisher of the
17896fdl.texi(,183) Modified Version, as the publisher.
17897fdl.texi(,184)
17898fdl.texi(,185) @item
17899fdl.texi(,186) Preserve all the copyright notices of the Document.
17900fdl.texi(,187)
17901fdl.texi(,188) @item
17902fdl.texi(,189) Add an appropriate copyright notice for your modifications
17903fdl.texi(,190) adjacent to the other copyright notices.
17904fdl.texi(,191)
17905fdl.texi(,192) @item
17906fdl.texi(,193) Include, immediately after the copyright notices, a license notice
17907fdl.texi(,194) giving the public permission to use the Modified Version under the
17908fdl.texi(,195) terms of this License, in the form shown in the Addendum below.
17909fdl.texi(,196)
17910fdl.texi(,197) @item
17911fdl.texi(,198) Preserve in that license notice the full lists of Invariant Sections
17912fdl.texi(,199) and required Cover Texts given in the Document's license notice.
17913fdl.texi(,200)
17914fdl.texi(,201) @item
17915fdl.texi(,202) Include an unaltered copy of this License.
17916fdl.texi(,203)
17917fdl.texi(,204) @item
17918fdl.texi(,205) Preserve the section entitled ``History'', and its title, and add to
17919fdl.texi(,206) it an item stating at least the title, year, new authors, and
17920fdl.texi(,207) publisher of the Modified Version as given on the Title Page.  If
17921fdl.texi(,208) there is no section entitled ``History'' in the Document, create one
17922fdl.texi(,209) stating the title, year, authors, and publisher of the Document as
17923fdl.texi(,210) given on its Title Page, then add an item describing the Modified
17924fdl.texi(,211) Version as stated in the previous sentence.
17925fdl.texi(,212)
17926fdl.texi(,213) @item
17927fdl.texi(,214) Preserve the network location, if any, given in the Document for
17928fdl.texi(,215) public access to a Transparent copy of the Document, and likewise
17929fdl.texi(,216) the network locations given in the Document for previous versions
17930fdl.texi(,217) it was based on.  These may be placed in the ``History'' section.
17931fdl.texi(,218) You may omit a network location for a work that was published at
17932fdl.texi(,219) least four years before the Document itself, or if the original
17933fdl.texi(,220) publisher of the version it refers to gives permission.
17934fdl.texi(,221)
17935fdl.texi(,222) @item
17936fdl.texi(,223) In any section entitled ``Acknowledgments'' or ``Dedications'',
17937fdl.texi(,224) preserve the section's title, and preserve in the section all the
17938fdl.texi(,225) substance and tone of each of the contributor acknowledgments
17939fdl.texi(,226) and/or dedications given therein.
17940fdl.texi(,227)
17941fdl.texi(,228) @item
17942fdl.texi(,229) Preserve all the Invariant Sections of the Document,
17943fdl.texi(,230) unaltered in their text and in their titles.  Section numbers
17944fdl.texi(,231) or the equivalent are not considered part of the section titles.
17945fdl.texi(,232)
17946fdl.texi(,233) @item
17947fdl.texi(,234) Delete any section entitled ``Endorsements''.  Such a section
17948fdl.texi(,235) may not be included in the Modified Version.
17949fdl.texi(,236)
17950fdl.texi(,237) @item
17951fdl.texi(,238) Do not retitle any existing section as ``Endorsements''
17952fdl.texi(,239) or to conflict in title with any Invariant Section.
17953fdl.texi(,240) @end enumerate
17954fdl.texi(,241)
17955fdl.texi(,242) If the Modified Version includes new front-matter sections or
17956fdl.texi(,243) appendices that qualify as Secondary Sections and contain no material
17957fdl.texi(,244) copied from the Document, you may at your option designate some or all
17958fdl.texi(,245) of these sections as invariant.  To do this, add their titles to the
17959fdl.texi(,246) list of Invariant Sections in the Modified Version's license notice.
17960fdl.texi(,247) These titles must be distinct from any other section titles.
17961fdl.texi(,248)
17962fdl.texi(,249) You may add a section entitled ``Endorsements'', provided it contains
17963fdl.texi(,250) nothing but endorsements of your Modified Version by various
17964fdl.texi(,251) parties---for example, statements of peer review or that the text has
17965fdl.texi(,252) been approved by an organization as the authoritative definition of a
17966fdl.texi(,253) standard.
17967fdl.texi(,254)
17968fdl.texi(,255) You may add a passage of up to five words as a Front-Cover Text, and a
17969fdl.texi(,256) passage of up to 25 words as a Back-Cover Text, to the end of the list
17970fdl.texi(,257) of Cover Texts in the Modified Version.  Only one passage of
17971fdl.texi(,258) Front-Cover Text and one of Back-Cover Text may be added by (or
17972fdl.texi(,259) through arrangements made by) any one entity.  If the Document already
17973fdl.texi(,260) includes a cover text for the same cover, previously added by you or
17974fdl.texi(,261) by arrangement made by the same entity you are acting on behalf of,
17975fdl.texi(,262) you may not add another; but you may replace the old one, on explicit
17976fdl.texi(,263) permission from the previous publisher that added the old one.
17977fdl.texi(,264)
17978fdl.texi(,265) The author(s) and publisher(s) of the Document do not by this License
17979fdl.texi(,266) give permission to use their names for publicity for or to assert or
17980fdl.texi(,267) imply endorsement of any Modified Version.
17981fdl.texi(,268)
17982fdl.texi(,269) @item
17983fdl.texi(,270) COMBINING DOCUMENTS
17984fdl.texi(,271)
17985fdl.texi(,272) You may combine the Document with other documents released under this
17986fdl.texi(,273) License, under the terms defined in section 4 above for modified
17987fdl.texi(,274) versions, provided that you include in the combination all of the
17988fdl.texi(,275) Invariant Sections of all of the original documents, unmodified, and
17989fdl.texi(,276) list them all as Invariant Sections of your combined work in its
17990fdl.texi(,277) license notice.
17991fdl.texi(,278)
17992fdl.texi(,279) The combined work need only contain one copy of this License, and
17993fdl.texi(,280) multiple identical Invariant Sections may be replaced with a single
17994fdl.texi(,281) copy.  If there are multiple Invariant Sections with the same name but
17995fdl.texi(,282) different contents, make the title of each such section unique by
17996fdl.texi(,283) adding at the end of it, in parentheses, the name of the original
17997fdl.texi(,284) author or publisher of that section if known, or else a unique number.
17998fdl.texi(,285) Make the same adjustment to the section titles in the list of
17999fdl.texi(,286) Invariant Sections in the license notice of the combined work.
18000fdl.texi(,287)
18001fdl.texi(,288) In the combination, you must combine any sections entitled ``History''
18002fdl.texi(,289) in the various original documents, forming one section entitled
18003fdl.texi(,290) ``History''; likewise combine any sections entitled ``Acknowledgments'',
18004fdl.texi(,291) and any sections entitled ``Dedications''.  You must delete all sections
18005fdl.texi(,292) entitled ``Endorsements.''
18006fdl.texi(,293)
18007fdl.texi(,294) @item
18008fdl.texi(,295) COLLECTIONS OF DOCUMENTS
18009fdl.texi(,296)
18010fdl.texi(,297) You may make a collection consisting of the Document and other documents
18011fdl.texi(,298) released under this License, and replace the individual copies of this
18012fdl.texi(,299) License in the various documents with a single copy that is included in
18013fdl.texi(,300) the collection, provided that you follow the rules of this License for
18014fdl.texi(,301) verbatim copying of each of the documents in all other respects.
18015fdl.texi(,302)
18016fdl.texi(,303) You may extract a single document from such a collection, and distribute
18017fdl.texi(,304) it individually under this License, provided you insert a copy of this
18018fdl.texi(,305) License into the extracted document, and follow this License in all
18019fdl.texi(,306) other respects regarding verbatim copying of that document.
18020fdl.texi(,307)
18021fdl.texi(,308) @item
18022fdl.texi(,309) AGGREGATION WITH INDEPENDENT WORKS
18023fdl.texi(,310)
18024fdl.texi(,311) A compilation of the Document or its derivatives with other separate
18025fdl.texi(,312) and independent documents or works, in or on a volume of a storage or
18026fdl.texi(,313) distribution medium, does not as a whole count as a Modified Version
18027fdl.texi(,314) of the Document, provided no compilation copyright is claimed for the
18028fdl.texi(,315) compilation.  Such a compilation is called an ``aggregate'', and this
18029fdl.texi(,316) License does not apply to the other self-contained works thus compiled
18030fdl.texi(,317) with the Document, on account of their being thus compiled, if they
18031fdl.texi(,318) are not themselves derivative works of the Document.
18032fdl.texi(,319)
18033fdl.texi(,320) If the Cover Text requirement of section 3 is applicable to these
18034fdl.texi(,321) copies of the Document, then if the Document is less than one quarter
18035fdl.texi(,322) of the entire aggregate, the Document's Cover Texts may be placed on
18036fdl.texi(,323) covers that surround only the Document within the aggregate.
18037fdl.texi(,324) Otherwise they must appear on covers around the whole aggregate.
18038fdl.texi(,325)
18039fdl.texi(,326) @item
18040fdl.texi(,327) TRANSLATION
18041fdl.texi(,328)
18042fdl.texi(,329) Translation is considered a kind of modification, so you may
18043fdl.texi(,330) distribute translations of the Document under the terms of section 4.
18044fdl.texi(,331) Replacing Invariant Sections with translations requires special
18045fdl.texi(,332) permission from their copyright holders, but you may include
18046fdl.texi(,333) translations of some or all Invariant Sections in addition to the
18047fdl.texi(,334) original versions of these Invariant Sections.  You may include a
18048fdl.texi(,335) translation of this License provided that you also include the
18049fdl.texi(,336) original English version of this License.  In case of a disagreement
18050fdl.texi(,337) between the translation and the original English version of this
18051fdl.texi(,338) License, the original English version will prevail.
18052fdl.texi(,339)
18053fdl.texi(,340) @item
18054fdl.texi(,341) TERMINATION
18055fdl.texi(,342)
18056fdl.texi(,343) You may not copy, modify, sublicense, or distribute the Document except
18057fdl.texi(,344) as expressly provided for under this License.  Any other attempt to
18058fdl.texi(,345) copy, modify, sublicense or distribute the Document is void, and will
18059fdl.texi(,346) automatically terminate your rights under this License.  However,
18060fdl.texi(,347) parties who have received copies, or rights, from you under this
18061fdl.texi(,348) License will not have their licenses terminated so long as such
18062fdl.texi(,349) parties remain in full compliance.
18063fdl.texi(,350)
18064fdl.texi(,351) @item
18065fdl.texi(,352) FUTURE REVISIONS OF THIS LICENSE
18066fdl.texi(,353)
18067fdl.texi(,354) The Free Software Foundation may publish new, revised versions
18068fdl.texi(,355) of the GNU Free Documentation License from time to time.  Such new
18069fdl.texi(,356) versions will be similar in spirit to the present version, but may
18070fdl.texi(,357) differ in detail to address new problems or concerns.  See
18071fdl.texi(,358) @uref{http://www.gnu.org/copyleft/}.
18072fdl.texi(,359)
18073fdl.texi(,360) Each version of the License is given a distinguishing version number.
18074fdl.texi(,361) If the Document specifies that a particular numbered version of this
18075fdl.texi(,362) License ``or any later version'' applies to it, you have the option of
18076fdl.texi(,363) following the terms and conditions either of that specified version or
18077fdl.texi(,364) of any later version that has been published (not as a draft) by the
18078fdl.texi(,365) Free Software Foundation.  If the Document does not specify a version
18079fdl.texi(,366) number of this License, you may choose any version ever published (not
18080fdl.texi(,367) as a draft) by the Free Software Foundation.
18081fdl.texi(,368) @end enumerate
18082fdl.texi(,369)
18083fdl.texi(,370) @page
18084fdl.texi(,371) @appendixsubsec ADDENDUM: How to use this License for your documents
18085fdl.texi(,372)
18086fdl.texi(,373) To use this License in a document you have written, include a copy of
18087fdl.texi(,374) the License in the document and put the following copyright and
18088fdl.texi(,375) license notices just after the title page:
18089fdl.texi(,376)
18090fdl.texi(,377) @smallexample
18091fdl.texi(,378) @group
18092fdl.texi(,379)   Copyright (C)  @var{year}  @var{your name}.
18093fdl.texi(,380)   Permission is granted to copy, distribute and/or modify this document
18094fdl.texi(,381)   under the terms of the GNU Free Documentation License, Version 1.1
18095fdl.texi(,382)   or any later version published by the Free Software Foundation;
18096fdl.texi(,383)   with the Invariant Sections being @var{list their titles}, with the
18097fdl.texi(,384)   Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}.
18098fdl.texi(,385)   A copy of the license is included in the section entitled ``GNU
18099fdl.texi(,386)   Free Documentation License''.
18100fdl.texi(,387) @end group
18101fdl.texi(,388) @end smallexample
18102fdl.texi(,389)
18103fdl.texi(,390) If you have no Invariant Sections, write ``with no Invariant Sections''
18104fdl.texi(,391) instead of saying which ones are invariant.  If you have no
18105fdl.texi(,392) Front-Cover Texts, write ``no Front-Cover Texts'' instead of
18106fdl.texi(,393) ``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
18107fdl.texi(,394)
18108fdl.texi(,395) If your document contains nontrivial examples of program code, we
18109fdl.texi(,396) recommend releasing these examples in parallel under your choice of
18110fdl.texi(,397) free software license, such as the GNU General Public License,
18111fdl.texi(,398) to permit their use in free software.
18112fdl.texi(,399)
18113fdl.texi(,400) @c Local Variables:
18114fdl.texi(,401) @c ispell-local-pdict: "ispell-dict"
18115fdl.texi(,402) @c End:
18116fdl.texi(,403)
18117texinfo.texi(,18736)
18118texinfo.texi(,18737)
18119texinfo.texi(,18738) @node Command and Variable Index
18120texinfo.texi(,18739) @unnumbered Command and Variable Index
18121texinfo.texi(,18740)
18122texinfo.texi(,18741) This is an alphabetical list of all the @@-commands, assorted Emacs Lisp
18123texinfo.texi(,18742) functions, and several variables.  To make the list easier to use, the
18124texinfo.texi(,18743) commands are listed without their preceding @samp{@@}.@refill
18125texinfo.texi(,18744)
18126texinfo.texi(,18745) @printindex fn
18127texinfo.texi(,18746)
18128texinfo.texi(,18747)
18129texinfo.texi(,18748) @node Concept Index
18130texinfo.texi(,18749) @unnumbered Concept Index
18131texinfo.texi(,18750)
18132texinfo.texi(,18751) @printindex cp
18133texinfo.texi(,18752)
18134texinfo.texi(,18753)
18135texinfo.texi(,18754) @bye
18136