1\input texinfo.tex @c -*-texinfo-*-
| 1\input texinfo.tex @c -*-texinfo-*-
|
2@c $Id: texinfo.txi,v 1.192 2002/03/04 14:52:52 karl Exp $
| 2@c $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $
3@c Ordinarily Texinfo files have the extension .texi. But texinfo.texi
4@c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi.
5
6@c Everything between the start/end of header lines will be passed by
7@c Emacs's {texinfo,makeinfo}-format region commands. See the `start of
8@c header' node for more info.
|
3@c %**start of header
4
| 9@c %**start of header
10
|
5@c All text is ignored before the setfilename.
| 11@c makeinfo and texinfo.tex ignore all text before @setfilename.
12@c
13@c Ordinarily the setfilename argument ends with .info. But
14@c texinfo.info-13 is too long for 14-character filesystems.
|
6@setfilename texinfo
7
| 15@setfilename texinfo
16
|
| 17@c Automake automatically updates version.texi to @set VERSION and
18@c @set UPDATED to appropriate values.
|
8@include version.texi
| 19@include version.texi
|
9@settitle Texinfo @value{VERSION}
| 20@settitle GNU Texinfo @value{VERSION}
|
10
11@c Define a new index for options.
12@defcodeindex op
13@c Put everything except function (command, in this case) names in one
14@c index (arbitrarily chosen to be the concept index).
15@syncodeindex op cp
16@syncodeindex vr cp
17@syncodeindex pg cp
18
19@footnotestyle separate
20@paragraphindent 2
21@c finalout
22
23@comment %**end of header
24
| 21
22@c Define a new index for options.
23@defcodeindex op
24@c Put everything except function (command, in this case) names in one
25@c index (arbitrarily chosen to be the concept index).
26@syncodeindex op cp
27@syncodeindex vr cp
28@syncodeindex pg cp
29
30@footnotestyle separate
31@paragraphindent 2
32@c finalout
33
34@comment %**end of header
35
|
| 36@copying
37This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}),
38a documentation system that can produce both online information and a
39printed manual from a single source.
40
41Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99, 2000, 01, 02
42Free Software Foundation, Inc.
43
44@quotation
45Permission is granted to copy, distribute and/or modify this document
46under the terms of the GNU Free Documentation License, Version 1.1 or
47any later version published by the Free Software Foundation; with no
48Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
49and with the Back-Cover Texts as in (a) below. A copy of the license is
50included in the section entitled ``GNU Free Documentation License.''
51
52(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
53this GNU Manual, like GNU software. Copies published by the Free
54Software Foundation raise funds for GNU development.''
55@end quotation
56@end copying
57
|
25@dircategory Texinfo documentation system
26@direntry
27* Texinfo: (texinfo). The GNU documentation format.
28* install-info: (texinfo)Invoking install-info. Update info/dir entries.
29* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
30* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
31* makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source.
32@end direntry
33
34@c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a
35@c prefix arg). This updates the node pointers, which texinfmt.el needs.
36
37@c Set smallbook if printing in smallbook format so the example of the
38@c smallbook font is actually written using smallbook; in bigbook, a kludge
39@c is used for TeX output. Do this through the -t option to texi2dvi,
40@c so this same source can be used for other paper sizes as well.
41@c smallbook
42@c set smallbook
43@c @@clear smallbook
44
| 58@dircategory Texinfo documentation system
59@direntry
60* Texinfo: (texinfo). The GNU documentation format.
61* install-info: (texinfo)Invoking install-info. Update info/dir entries.
62* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
63* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
64* makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source.
65@end direntry
66
67@c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a
68@c prefix arg). This updates the node pointers, which texinfmt.el needs.
69
70@c Set smallbook if printing in smallbook format so the example of the
71@c smallbook font is actually written using smallbook; in bigbook, a kludge
72@c is used for TeX output. Do this through the -t option to texi2dvi,
73@c so this same source can be used for other paper sizes as well.
74@c smallbook
75@c set smallbook
76@c @@clear smallbook
77
|
45@c If you like blank pages. Can add through texi2dvi -t.
| 78@c If you like blank pages, add through texi2dvi -t.
|
46@c setchapternewpage odd
47
48@c Currently undocumented command, 5 December 1993:
49@c nwnode (Same as node, but no warnings; for `makeinfo'.)
50
| 79@c setchapternewpage odd
80
81@c Currently undocumented command, 5 December 1993:
82@c nwnode (Same as node, but no warnings; for `makeinfo'.)
83
|
51@ifinfo
52This file documents Texinfo, a documentation system that can produce
53both online information and a printed manual from a single source. This
54edition is for Texinfo version @value{VERSION}, @value{UPDATED}.
| |
55
| 84
|
56Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99, 2000, 01, 02
57Free Software Foundation, Inc.
58
59Permission is granted to copy, distribute and/or modify this document
60under the terms of the GNU Free Documentation License, Version 1.1 or
61any later version published by the Free Software Foundation; with the
62Invariant Section being ``History'', with no Front-Cover Texts, and with
63no Back-Cover Texts. A copy of the license is included in the section
64entitled ``GNU Free Documentation License''.
65@end ifinfo
66
67
| |
68@shorttitlepage Texinfo
69
70@titlepage
71@title Texinfo
72@subtitle The GNU Documentation Format
73@subtitle for Texinfo version @value{VERSION}, @value{UPDATED}
74
75@author Robert J. Chassell
76@author Richard M. Stallman
77
78@c Include the Distribution inside the titlepage so
79@c that headings are turned off.
80
81@page
82@vskip 0pt plus 1filll
| 85@shorttitlepage Texinfo
86
87@titlepage
88@title Texinfo
89@subtitle The GNU Documentation Format
90@subtitle for Texinfo version @value{VERSION}, @value{UPDATED}
91
92@author Robert J. Chassell
93@author Richard M. Stallman
94
95@c Include the Distribution inside the titlepage so
96@c that headings are turned off.
97
98@page
99@vskip 0pt plus 1filll
|
83Copyright @copyright{} 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99, 2000, 01, 02
84Free Software Foundation, Inc.
| 100@insertcopying
|
85
| 101
|
86This manual is for Texinfo version @value{VERSION}, @value{UPDATED}.
87
| |
88Published by the Free Software Foundation @*
8959 Temple Place Suite 330 @*
90Boston, MA 02111-1307 @*
91USA @*
92ISBN 1-882114-67-1 @c for version 4.0, September 1999.
| 102Published by the Free Software Foundation @*
10359 Temple Place Suite 330 @*
104Boston, MA 02111-1307 @*
105USA @*
106ISBN 1-882114-67-1 @c for version 4.0, September 1999.
|
93@c ISBN 1-882114-65-5 @c for version 3.12, March 1998.
94@c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995
| 107@c ISBN 1-882114-65-5 is for version 3.12, March 1998.
|
95@c ISBN 1-882114-64-7 is for edition 2.24 of November 1996.
| 108@c ISBN 1-882114-64-7 is for edition 2.24 of November 1996.
|
| 109@c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995
|
96
97Cover art by Etienne Suvasa.
| 110
111Cover art by Etienne Suvasa.
|
98
99Permission is granted to copy, distribute and/or modify this document
100under the terms of the GNU Free Documentation License, Version 1.1 or
101any later version published by the Free Software Foundation; with the
102Invariant Section being ``History'', with no Front-Cover Texts, and with
103no Back-Cover Texts. A copy of the license is included in the section
104entitled ``GNU Free Documentation License''.
105
| |
106@end titlepage
107
| 112@end titlepage
113
|
| 114
|
108@summarycontents
109@contents
110
| 115@summarycontents
116@contents
117
|
| 118
|
111@ifnottex
112@node Top
113@top Texinfo
114
| 119@ifnottex
120@node Top
121@top Texinfo
122
|
115Texinfo is a documentation system that uses a single source to produce
116both online information and printed output.
| 123@insertcopying
|
117
118The first part of this master menu lists the major nodes in this Info
119document, including the @@-command and concept indices. The rest of
120the menu lists all the lower level nodes in the document.
121
| 124
125The first part of this master menu lists the major nodes in this Info
126document, including the @@-command and concept indices. The rest of
127the menu lists all the lower level nodes in the document.
128
|
122This is Edition @value{VERSION} of the Texinfo manual, updated @value{UPDATED}.
| |
123@end ifnottex
124
125@menu
| 129@end ifnottex
130
131@menu
|
126* Copying:: Your rights.
| 132* Copying Conditions:: Your rights.
|
127* Overview:: Texinfo in brief.
128* Texinfo Mode:: How to use Texinfo mode.
129* Beginning a File:: What is at the beginning of a Texinfo file?
130* Ending a File:: What is at the end of a Texinfo file?
131* Structuring:: How to create chapters, sections, subsections,
132 appendices, and other parts.
133* Nodes:: How to write nodes.
134* Menus:: How to write menus.
135* Cross References:: How to write cross references.
136* Marking Text:: How to mark words and phrases as code,
137 keyboard input, meta-syntactic
138 variables, and the like.
139* Quotations and Examples:: How to write quotations, examples, etc.
140* Lists and Tables:: How to write lists and tables.
141* Indices:: How to create indices.
142* Insertions:: How to insert @@-signs, braces, etc.
143* Breaks:: How to force and prevent line and page breaks.
144* Definition Commands:: How to describe functions and the like
145 in a uniform manner.
146* Conditionals:: How to specify text for either @TeX{} or Info.
147* Internationalization::
148* Defining New Texinfo Commands::
149* Hardcopy:: How to convert a Texinfo file to a file
150 for printing and how to print that file.
151* Creating and Installing Info Files::
152* Command List:: All the Texinfo @@-commands.
153* Tips:: Hints on how to write a Texinfo document.
| 133* Overview:: Texinfo in brief.
134* Texinfo Mode:: How to use Texinfo mode.
135* Beginning a File:: What is at the beginning of a Texinfo file?
136* Ending a File:: What is at the end of a Texinfo file?
137* Structuring:: How to create chapters, sections, subsections,
138 appendices, and other parts.
139* Nodes:: How to write nodes.
140* Menus:: How to write menus.
141* Cross References:: How to write cross references.
142* Marking Text:: How to mark words and phrases as code,
143 keyboard input, meta-syntactic
144 variables, and the like.
145* Quotations and Examples:: How to write quotations, examples, etc.
146* Lists and Tables:: How to write lists and tables.
147* Indices:: How to create indices.
148* Insertions:: How to insert @@-signs, braces, etc.
149* Breaks:: How to force and prevent line and page breaks.
150* Definition Commands:: How to describe functions and the like
151 in a uniform manner.
152* Conditionals:: How to specify text for either @TeX{} or Info.
153* Internationalization::
154* Defining New Texinfo Commands::
155* Hardcopy:: How to convert a Texinfo file to a file
156 for printing and how to print that file.
157* Creating and Installing Info Files::
158* Command List:: All the Texinfo @@-commands.
159* Tips:: Hints on how to write a Texinfo document.
|
154* Sample Texinfo File:: A sample Texinfo file to look at.
| 160* Sample Texinfo Files:: Complete examples, including full texts.
|
155* Include Files:: How to incorporate other Texinfo files.
156* Headings:: How to write page headings and footings.
157* Catching Mistakes:: How to find formatting mistakes.
158* Refilling Paragraphs:: All about paragraph refilling.
159* Command Syntax:: A description of @@-Command syntax.
160* Obtaining TeX:: How to Obtain @TeX{}.
| 161* Include Files:: How to incorporate other Texinfo files.
162* Headings:: How to write page headings and footings.
163* Catching Mistakes:: How to find formatting mistakes.
164* Refilling Paragraphs:: All about paragraph refilling.
165* Command Syntax:: A description of @@-Command syntax.
166* Obtaining TeX:: How to Obtain @TeX{}.
|
161* Documentation Copying:: The GNU Free Documentation License.
| 167* Copying This Manual:: The GNU Free Documentation License.
|
162* Command and Variable Index:: A menu containing commands and variables.
163* Concept Index:: A menu covering many topics.
164
165@detailmenu
166 --- The Detailed Node Listing ---
167
168Overview of Texinfo
169
170* Reporting Bugs:: Submitting effective bug reports.
171* Using Texinfo:: Create printed or online output.
172* Info Files:: What is an Info file?
173* Printed Books:: Characteristics of a printed book or manual.
174* Formatting Commands:: @@-commands are used for formatting.
175* Conventions:: General rules for writing a Texinfo file.
176* Comments:: Writing comments and ignored text in general.
177* Minimum:: What a Texinfo file must have.
178* Six Parts:: Usually, a Texinfo file has six parts.
179* Short Sample:: A short sample Texinfo file.
180* History:: Acknowledgements, contributors and genesis.
181
182Using Texinfo Mode
183
184* Texinfo Mode Overview:: How Texinfo mode can help you.
185* Emacs Editing:: Texinfo mode adds to GNU Emacs' general
186 purpose editing features.
187* Inserting:: How to insert frequently used @@-commands.
188* Showing the Structure:: How to show the structure of a file.
189* Updating Nodes and Menus:: How to update or create new nodes and menus.
190* Info Formatting:: How to format for Info.
191* Printing:: How to format and print part or all of a file.
192* Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
193
194Updating Nodes and Menus
195
196* Updating Commands:: Five major updating commands.
197* Updating Requirements:: How to structure a Texinfo file for
198 using the updating command.
199* Other Updating Commands:: How to indent descriptions, insert
200 missing nodes lines, and update
201 nodes in sequence.
202
203Beginning a Texinfo File
204
| 168* Command and Variable Index:: A menu containing commands and variables.
169* Concept Index:: A menu covering many topics.
170
171@detailmenu
172 --- The Detailed Node Listing ---
173
174Overview of Texinfo
175
176* Reporting Bugs:: Submitting effective bug reports.
177* Using Texinfo:: Create printed or online output.
178* Info Files:: What is an Info file?
179* Printed Books:: Characteristics of a printed book or manual.
180* Formatting Commands:: @@-commands are used for formatting.
181* Conventions:: General rules for writing a Texinfo file.
182* Comments:: Writing comments and ignored text in general.
183* Minimum:: What a Texinfo file must have.
184* Six Parts:: Usually, a Texinfo file has six parts.
185* Short Sample:: A short sample Texinfo file.
186* History:: Acknowledgements, contributors and genesis.
187
188Using Texinfo Mode
189
190* Texinfo Mode Overview:: How Texinfo mode can help you.
191* Emacs Editing:: Texinfo mode adds to GNU Emacs' general
192 purpose editing features.
193* Inserting:: How to insert frequently used @@-commands.
194* Showing the Structure:: How to show the structure of a file.
195* Updating Nodes and Menus:: How to update or create new nodes and menus.
196* Info Formatting:: How to format for Info.
197* Printing:: How to format and print part or all of a file.
198* Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
199
200Updating Nodes and Menus
201
202* Updating Commands:: Five major updating commands.
203* Updating Requirements:: How to structure a Texinfo file for
204 using the updating command.
205* Other Updating Commands:: How to indent descriptions, insert
206 missing nodes lines, and update
207 nodes in sequence.
208
209Beginning a Texinfo File
210
|
205* Four Parts:: Four parts begin a Texinfo file.
206* Sample Beginning:: Here is a sample beginning for a Texinfo file.
207* Header:: The very beginning of a Texinfo file.
208* Info Summary and Permissions:: Summary and copying permissions for Info.
| 211* Sample Beginning:: A sample beginning for a Texinfo file.
212* Texinfo File Header::
213* Document Permissions::
|
209* Titlepage & Copyright Page:: Creating the title and copyright pages.
210* The Top Node:: Creating the `Top' node and master menu.
| 214* Titlepage & Copyright Page:: Creating the title and copyright pages.
215* The Top Node:: Creating the `Top' node and master menu.
|
| 216* Global Document Commands::
|
211* Software Copying Permissions:: Ensure that you and others continue to
| 217* Software Copying Permissions:: Ensure that you and others continue to
|
212 have the right to use and share software.
| 218 have the right to use and share software.
|
213
| 219
|
214The Texinfo File Header
| 220Texinfo File Header
|
215
216* First Line:: The first line of a Texinfo file.
217* Start of Header:: Formatting a region requires this.
218* setfilename:: Tell Info the name of the Info file.
219* settitle:: Create a title for the printed work.
| 221
222* First Line:: The first line of a Texinfo file.
223* Start of Header:: Formatting a region requires this.
224* setfilename:: Tell Info the name of the Info file.
225* settitle:: Create a title for the printed work.
|
220* documentdescription:: Document summary for the HTML output.
221* setchapternewpage:: Start chapters on right-hand pages.
222* paragraphindent:: Specify paragraph indentation.
223* exampleindent:: Specify environment indentation.
| |
224* End of Header:: Formatting a region requires this.
225
| 226* End of Header:: Formatting a region requires this.
227
|
226The Title and Copyright Pages
| 228Document Permissions
|
227
| 229
|
| 230* copying:: Declare the document's copying permissions.
231* insertcopying:: Where to insert the permissions.
232
233Title and Copyright Pages
234
|
228* titlepage:: Create a title for the printed document.
229* titlefont center sp:: The @code{@@titlefont}, @code{@@center},
230 and @code{@@sp} commands.
231* title subtitle author:: The @code{@@title}, @code{@@subtitle},
232 and @code{@@author} commands.
| 235* titlepage:: Create a title for the printed document.
236* titlefont center sp:: The @code{@@titlefont}, @code{@@center},
237 and @code{@@sp} commands.
238* title subtitle author:: The @code{@@title}, @code{@@subtitle},
239 and @code{@@author} commands.
|
233* Copyright & Permissions:: How to write the copyright notice and
| 240* Copyright:: How to write the copyright notice and
|
234 include copying permissions.
235* end titlepage:: Turn on page headings after the title and
236 copyright pages.
237* headings on off:: An option for turning headings on and off
238 and double or single sided printing.
239
240The `Top' Node and Master Menu
241
| 241 include copying permissions.
242* end titlepage:: Turn on page headings after the title and
243 copyright pages.
244* headings on off:: An option for turning headings on and off
245 and double or single sided printing.
246
247The `Top' Node and Master Menu
248
|
242* Title of Top Node:: Sketch what the file is about.
243* Master Menu Parts:: A master menu has three or more parts.
| 249* Top Node Example::
250* Master Menu Parts::
|
244
| 251
|
| 252Global Document Commands
253
254* documentdescription:: Document summary for the HTML output.
255* setchapternewpage:: Start chapters on right-hand pages.
256* paragraphindent:: Specify paragraph indentation.
257* exampleindent:: Specify environment indentation.
258
|
245Ending a Texinfo File
246
247* Printing Indices & Menus:: How to print an index in hardcopy and
248 generate index menus in Info.
249* Contents:: How to create a table of contents.
250* File End:: How to mark the end of a file.
251
252Chapter Structuring
253
254* Tree Structuring:: A manual is like an upside down tree @dots{}
255* Structuring Command Types:: How to divide a manual into parts.
256* makeinfo top:: The @code{@@top} command, part of the `Top' node.
257* chapter::
258* unnumbered & appendix::
259* majorheading & chapheading::
260* section::
261* unnumberedsec appendixsec heading::
262* subsection::
263* unnumberedsubsec appendixsubsec subheading::
264* subsubsection:: Commands for the lowest level sections.
265* Raise/lower sections:: How to change commands' hierarchical level.
266
267Nodes
268
269* Two Paths:: Different commands to structure
270 Info output and printed output.
271* Node Menu Illustration:: A diagram, and sample nodes and menus.
272* node:: Creating nodes, in detail.
273* makeinfo Pointer Creation:: Letting makeinfo determine node pointers.
274* anchor:: Defining arbitrary cross-reference targets.
275
276The @code{@@node} Command
277
278* Node Names:: How to choose node and pointer names.
279* Writing a Node:: How to write an @code{@@node} line.
280* Node Line Tips:: Keep names short.
281* Node Line Requirements:: Keep names unique, without @@-commands.
282* First Node:: How to write a `Top' node.
283* makeinfo top command:: How to use the @code{@@top} command.
| 259Ending a Texinfo File
260
261* Printing Indices & Menus:: How to print an index in hardcopy and
262 generate index menus in Info.
263* Contents:: How to create a table of contents.
264* File End:: How to mark the end of a file.
265
266Chapter Structuring
267
268* Tree Structuring:: A manual is like an upside down tree @dots{}
269* Structuring Command Types:: How to divide a manual into parts.
270* makeinfo top:: The @code{@@top} command, part of the `Top' node.
271* chapter::
272* unnumbered & appendix::
273* majorheading & chapheading::
274* section::
275* unnumberedsec appendixsec heading::
276* subsection::
277* unnumberedsubsec appendixsubsec subheading::
278* subsubsection:: Commands for the lowest level sections.
279* Raise/lower sections:: How to change commands' hierarchical level.
280
281Nodes
282
283* Two Paths:: Different commands to structure
284 Info output and printed output.
285* Node Menu Illustration:: A diagram, and sample nodes and menus.
286* node:: Creating nodes, in detail.
287* makeinfo Pointer Creation:: Letting makeinfo determine node pointers.
288* anchor:: Defining arbitrary cross-reference targets.
289
290The @code{@@node} Command
291
292* Node Names:: How to choose node and pointer names.
293* Writing a Node:: How to write an @code{@@node} line.
294* Node Line Tips:: Keep names short.
295* Node Line Requirements:: Keep names unique, without @@-commands.
296* First Node:: How to write a `Top' node.
297* makeinfo top command:: How to use the @code{@@top} command.
|
284* Top Node Summary:: Write a brief description for readers.
| |
285
286Menus
287
288* Menu Location:: Put a menu in a short node.
289* Writing a Menu:: What is a menu?
290* Menu Parts:: A menu entry has three parts.
291* Less Cluttered Menu Entry:: Two part menu entry.
292* Menu Example:: Two and three part menu entries.
293* Other Info Files:: How to refer to a different Info file.
294
295Cross References
296
297* References:: What cross references are for.
298* Cross Reference Commands:: A summary of the different commands.
299* Cross Reference Parts:: A cross reference has several parts.
300* xref:: Begin a reference with `See' @dots{}
301* Top Node Naming:: How to refer to the beginning of another file.
302* ref:: A reference for the last part of a sentence.
303* pxref:: How to write a parenthetical cross reference.
304* inforef:: How to refer to an Info-only file.
305* uref:: How to refer to a uniform resource locator.
306
307@code{@@xref}
308
309* Reference Syntax:: What a reference looks like and requires.
310* One Argument:: @code{@@xref} with one argument.
311* Two Arguments:: @code{@@xref} with two arguments.
312* Three Arguments:: @code{@@xref} with three arguments.
313* Four and Five Arguments:: @code{@@xref} with four and five arguments.
314
315Marking Words and Phrases
316
317* Indicating:: How to indicate definitions, files, etc.
318* Emphasis:: How to emphasize text.
319
320Indicating Definitions, Commands, etc.
321
322* Useful Highlighting:: Highlighting provides useful information.
323* code:: Indicating program code.
324* kbd:: Showing keyboard input.
325* key:: Specifying keys.
326* samp:: A literal sequence of characters.
| 298
299Menus
300
301* Menu Location:: Put a menu in a short node.
302* Writing a Menu:: What is a menu?
303* Menu Parts:: A menu entry has three parts.
304* Less Cluttered Menu Entry:: Two part menu entry.
305* Menu Example:: Two and three part menu entries.
306* Other Info Files:: How to refer to a different Info file.
307
308Cross References
309
310* References:: What cross references are for.
311* Cross Reference Commands:: A summary of the different commands.
312* Cross Reference Parts:: A cross reference has several parts.
313* xref:: Begin a reference with `See' @dots{}
314* Top Node Naming:: How to refer to the beginning of another file.
315* ref:: A reference for the last part of a sentence.
316* pxref:: How to write a parenthetical cross reference.
317* inforef:: How to refer to an Info-only file.
318* uref:: How to refer to a uniform resource locator.
319
320@code{@@xref}
321
322* Reference Syntax:: What a reference looks like and requires.
323* One Argument:: @code{@@xref} with one argument.
324* Two Arguments:: @code{@@xref} with two arguments.
325* Three Arguments:: @code{@@xref} with three arguments.
326* Four and Five Arguments:: @code{@@xref} with four and five arguments.
327
328Marking Words and Phrases
329
330* Indicating:: How to indicate definitions, files, etc.
331* Emphasis:: How to emphasize text.
332
333Indicating Definitions, Commands, etc.
334
335* Useful Highlighting:: Highlighting provides useful information.
336* code:: Indicating program code.
337* kbd:: Showing keyboard input.
338* key:: Specifying keys.
339* samp:: A literal sequence of characters.
|
327* verb:: A verbatim sequence of characters.
| 340* verb:: A verbatim sequence of characters.
|
328* var:: Indicating metasyntactic variables.
329* env:: Indicating environment variables.
330* file:: Indicating file names.
331* command:: Indicating command names.
332* option:: Indicating option names.
333* dfn:: Specifying definitions.
334* cite:: Referring to books not in the Info system.
335* acronym:: Indicating acronyms.
336* url:: Indicating a World Wide Web reference.
337* email:: Indicating an electronic mail address.
338
339Emphasizing Text
340
341* emph & strong:: How to emphasize text in Texinfo.
342* Smallcaps:: How to use the small caps font.
343* Fonts:: Various font commands for printed output.
344
345Quotations and Examples
346
347* Block Enclosing Commands:: Different constructs for different purposes.
348* quotation:: Writing a quotation.
349* example:: Writing an example in a fixed-width font.
350* verbatim:: Writing a verbatim example.
| 341* var:: Indicating metasyntactic variables.
342* env:: Indicating environment variables.
343* file:: Indicating file names.
344* command:: Indicating command names.
345* option:: Indicating option names.
346* dfn:: Specifying definitions.
347* cite:: Referring to books not in the Info system.
348* acronym:: Indicating acronyms.
349* url:: Indicating a World Wide Web reference.
350* email:: Indicating an electronic mail address.
351
352Emphasizing Text
353
354* emph & strong:: How to emphasize text in Texinfo.
355* Smallcaps:: How to use the small caps font.
356* Fonts:: Various font commands for printed output.
357
358Quotations and Examples
359
360* Block Enclosing Commands:: Different constructs for different purposes.
361* quotation:: Writing a quotation.
362* example:: Writing an example in a fixed-width font.
363* verbatim:: Writing a verbatim example.
|
351* verbatiminclude:: Including a file verbatim.
| 364* verbatiminclude:: Including a file verbatim.
|
352* lisp:: Illustrating Lisp code.
353* small:: Forms for @code{@@smallbook}.
354* display:: Writing an example in the current font.
355* format:: Writing an example without narrowed margins.
356* exdent:: Undo indentation on a line.
357* flushleft & flushright:: Pushing text flush left or flush right.
358* noindent:: Preventing paragraph indentation.
359* cartouche:: Drawing rounded rectangles around examples.
360
361Lists and Tables
362
363* Introducing Lists:: Texinfo formats lists for you.
364* itemize:: How to construct a simple list.
365* enumerate:: How to construct a numbered list.
366* Two-column Tables:: How to construct a two-column table.
367* Multi-column Tables:: How to construct generalized tables.
368
369Making a Two-column Table
370
371* table:: How to construct a two-column table.
372* ftable vtable:: Automatic indexing for two-column tables.
373* itemx:: How to put more entries in the first column.
374
375Multi-column Tables
376
377* Multitable Column Widths:: Defining multitable column widths.
378* Multitable Rows:: Defining multitable rows, with examples.
379
380Indices
381
382* Index Entries:: Choose different words for index entries.
383* Predefined Indices:: Use different indices for different kinds
384 of entry.
385* Indexing Commands:: How to make an index entry.
386* Combining Indices:: How to combine indices.
387* New Indices:: How to define your own indices.
388
389Combining Indices
390
391* syncodeindex:: How to merge two indices, using @code{@@code}
392 font for the merged-from index.
393* synindex:: How to merge two indices, using the
394 default font of the merged-to index.
395
396Special Insertions
397
398* Braces Atsigns:: How to insert braces, @samp{@@}.
399* Inserting Space:: How to insert the right amount of space
400 within a sentence.
401* Inserting Accents:: How to insert accents and special characters.
402* Dots Bullets:: How to insert dots and bullets.
403* TeX and copyright:: How to insert the @TeX{} logo
404 and the copyright symbol.
405* pounds:: How to insert the pounds currency symbol.
406* minus:: How to insert a minus sign.
407* math:: How to format a mathematical expression.
408* Glyphs:: How to indicate results of evaluation,
409 expansion of macros, errors, etc.
410* Footnotes:: How to include footnotes.
411* Images:: How to include graphics.
412
413Inserting @@ and Braces
414
415* Inserting An Atsign:: How to insert @samp{@@}.
416* Inserting Braces:: How to insert @samp{@{} and @samp{@}}.
417
418Inserting Space
419
420* Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
421* Ending a Sentence:: Sometimes it does.
422* Multiple Spaces:: Inserting multiple spaces.
423* dmn:: How to format a dimension.
424
425Inserting Ellipsis and Bullets
426
427* dots:: How to insert dots @dots{}
428* bullet:: How to insert a bullet.
429
430Inserting @TeX{} and the Copyright Symbol
431
432* tex:: How to insert the @TeX{} logo.
433* copyright symbol:: How to use @code{@@copyright}@{@}.
434
435Glyphs for Examples
436
437* Glyphs Summary::
438* result:: How to show the result of expression.
439* expansion:: How to indicate an expansion.
440* Print Glyph:: How to indicate printed output.
441* Error Glyph:: How to indicate an error message.
442* Equivalence:: How to indicate equivalence.
443* Point Glyph:: How to indicate the location of point.
444
445Glyphs Summary
446
447* result::
448* expansion::
449* Print Glyph::
450* Error Glyph::
451* Equivalence::
452* Point Glyph::
453
454Footnotes
455
456* Footnote Commands:: How to write a footnote in Texinfo.
457* Footnote Styles:: Controlling how footnotes appear in Info.
458
459Making and Preventing Breaks
460
461* Break Commands:: Cause and prevent splits.
462* Line Breaks:: How to force a single line to use two lines.
463* - and hyphenation:: How to tell @TeX{} about hyphenation points.
464* w:: How to prevent unwanted line breaks.
465* sp:: How to insert blank lines.
466* page:: How to force the start of a new page.
467* group:: How to prevent unwanted page breaks.
468* need:: Another way to prevent unwanted page breaks.
469
470Definition Commands
471
472* Def Cmd Template:: How to structure a description using a
473 definition command.
474* Optional Arguments:: How to handle optional and repeated arguments.
475* deffnx:: How to group two or more `first' lines.
476* Def Cmds in Detail:: All the definition commands.
477* Def Cmd Conventions:: Conventions for writing definitions.
478* Sample Function Definition::
479
480The Definition Commands
481
482* Functions Commands:: Commands for functions and similar entities.
483* Variables Commands:: Commands for variables and similar entities.
484* Typed Functions:: Commands for functions in typed languages.
485* Typed Variables:: Commands for variables in typed languages.
486* Abstract Objects:: Commands for object-oriented programming.
487* Data Types:: The definition command for data types.
488
489Conditionally Visible Text
490
491* Conditional Commands:: Specifying text for HTML, Info, or @TeX{}.
492* Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}.
493* Raw Formatter Commands:: Using raw @TeX{} or HTML commands.
494* set clear value:: Designating which text to format (for
495 all output formats); and how to set a
496 flag to a string that you can insert.
497
498@code{@@set}, @code{@@clear}, and @code{@@value}
499
500* set value:: Expand a flag variable to a string.
501* ifset ifclear:: Format a region if a flag is set.
502* value Example:: An easy way to update edition information.
503
504Internationalization
505
506* documentlanguage:: Declaring the current language.
507* documentencoding:: Declaring the input encoding.
508
509Defining New Texinfo Commands
510
511* Defining Macros:: Defining and undefining new commands.
512* Invoking Macros:: Using a macro, once you've defined it.
513* Macro Details:: Beyond basic macro usage.
514* alias:: Command aliases.
515* definfoenclose:: Customized highlighting.
516
517Formatting and Printing Hardcopy
518
519* Use TeX:: Use @TeX{} to format for hardcopy.
520* Format with tex/texindex:: How to format with explicit shell commands.
521* Format with texi2dvi:: A simpler way to format.
522* Print with lpr:: How to print.
523* Within Emacs:: How to format and print from an Emacs shell.
524* Texinfo Mode Printing:: How to format and print in Texinfo mode.
525* Compile-Command:: How to print using Emacs's compile command.
526* Requirements Summary:: @TeX{} formatting requirements summary.
527* Preparing for TeX:: What to do before you use @TeX{}.
528* Overfull hboxes:: What are and what to do with overfull hboxes.
529* smallbook:: How to print small format books and manuals.
530* A4 Paper:: How to print on A4 or A5 paper.
531* pagesizes:: How to print with customized page sizes.
532* Cropmarks and Magnification:: How to print marks to indicate the size
533 of pages and how to print scaled up output.
534* PDF Output:: Portable Document Format output.
535
536Creating and Installing Info Files
537
538* Creating an Info File::
| 365* lisp:: Illustrating Lisp code.
366* small:: Forms for @code{@@smallbook}.
367* display:: Writing an example in the current font.
368* format:: Writing an example without narrowed margins.
369* exdent:: Undo indentation on a line.
370* flushleft & flushright:: Pushing text flush left or flush right.
371* noindent:: Preventing paragraph indentation.
372* cartouche:: Drawing rounded rectangles around examples.
373
374Lists and Tables
375
376* Introducing Lists:: Texinfo formats lists for you.
377* itemize:: How to construct a simple list.
378* enumerate:: How to construct a numbered list.
379* Two-column Tables:: How to construct a two-column table.
380* Multi-column Tables:: How to construct generalized tables.
381
382Making a Two-column Table
383
384* table:: How to construct a two-column table.
385* ftable vtable:: Automatic indexing for two-column tables.
386* itemx:: How to put more entries in the first column.
387
388Multi-column Tables
389
390* Multitable Column Widths:: Defining multitable column widths.
391* Multitable Rows:: Defining multitable rows, with examples.
392
393Indices
394
395* Index Entries:: Choose different words for index entries.
396* Predefined Indices:: Use different indices for different kinds
397 of entry.
398* Indexing Commands:: How to make an index entry.
399* Combining Indices:: How to combine indices.
400* New Indices:: How to define your own indices.
401
402Combining Indices
403
404* syncodeindex:: How to merge two indices, using @code{@@code}
405 font for the merged-from index.
406* synindex:: How to merge two indices, using the
407 default font of the merged-to index.
408
409Special Insertions
410
411* Braces Atsigns:: How to insert braces, @samp{@@}.
412* Inserting Space:: How to insert the right amount of space
413 within a sentence.
414* Inserting Accents:: How to insert accents and special characters.
415* Dots Bullets:: How to insert dots and bullets.
416* TeX and copyright:: How to insert the @TeX{} logo
417 and the copyright symbol.
418* pounds:: How to insert the pounds currency symbol.
419* minus:: How to insert a minus sign.
420* math:: How to format a mathematical expression.
421* Glyphs:: How to indicate results of evaluation,
422 expansion of macros, errors, etc.
423* Footnotes:: How to include footnotes.
424* Images:: How to include graphics.
425
426Inserting @@ and Braces
427
428* Inserting An Atsign:: How to insert @samp{@@}.
429* Inserting Braces:: How to insert @samp{@{} and @samp{@}}.
430
431Inserting Space
432
433* Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
434* Ending a Sentence:: Sometimes it does.
435* Multiple Spaces:: Inserting multiple spaces.
436* dmn:: How to format a dimension.
437
438Inserting Ellipsis and Bullets
439
440* dots:: How to insert dots @dots{}
441* bullet:: How to insert a bullet.
442
443Inserting @TeX{} and the Copyright Symbol
444
445* tex:: How to insert the @TeX{} logo.
446* copyright symbol:: How to use @code{@@copyright}@{@}.
447
448Glyphs for Examples
449
450* Glyphs Summary::
451* result:: How to show the result of expression.
452* expansion:: How to indicate an expansion.
453* Print Glyph:: How to indicate printed output.
454* Error Glyph:: How to indicate an error message.
455* Equivalence:: How to indicate equivalence.
456* Point Glyph:: How to indicate the location of point.
457
458Glyphs Summary
459
460* result::
461* expansion::
462* Print Glyph::
463* Error Glyph::
464* Equivalence::
465* Point Glyph::
466
467Footnotes
468
469* Footnote Commands:: How to write a footnote in Texinfo.
470* Footnote Styles:: Controlling how footnotes appear in Info.
471
472Making and Preventing Breaks
473
474* Break Commands:: Cause and prevent splits.
475* Line Breaks:: How to force a single line to use two lines.
476* - and hyphenation:: How to tell @TeX{} about hyphenation points.
477* w:: How to prevent unwanted line breaks.
478* sp:: How to insert blank lines.
479* page:: How to force the start of a new page.
480* group:: How to prevent unwanted page breaks.
481* need:: Another way to prevent unwanted page breaks.
482
483Definition Commands
484
485* Def Cmd Template:: How to structure a description using a
486 definition command.
487* Optional Arguments:: How to handle optional and repeated arguments.
488* deffnx:: How to group two or more `first' lines.
489* Def Cmds in Detail:: All the definition commands.
490* Def Cmd Conventions:: Conventions for writing definitions.
491* Sample Function Definition::
492
493The Definition Commands
494
495* Functions Commands:: Commands for functions and similar entities.
496* Variables Commands:: Commands for variables and similar entities.
497* Typed Functions:: Commands for functions in typed languages.
498* Typed Variables:: Commands for variables in typed languages.
499* Abstract Objects:: Commands for object-oriented programming.
500* Data Types:: The definition command for data types.
501
502Conditionally Visible Text
503
504* Conditional Commands:: Specifying text for HTML, Info, or @TeX{}.
505* Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}.
506* Raw Formatter Commands:: Using raw @TeX{} or HTML commands.
507* set clear value:: Designating which text to format (for
508 all output formats); and how to set a
509 flag to a string that you can insert.
510
511@code{@@set}, @code{@@clear}, and @code{@@value}
512
513* set value:: Expand a flag variable to a string.
514* ifset ifclear:: Format a region if a flag is set.
515* value Example:: An easy way to update edition information.
516
517Internationalization
518
519* documentlanguage:: Declaring the current language.
520* documentencoding:: Declaring the input encoding.
521
522Defining New Texinfo Commands
523
524* Defining Macros:: Defining and undefining new commands.
525* Invoking Macros:: Using a macro, once you've defined it.
526* Macro Details:: Beyond basic macro usage.
527* alias:: Command aliases.
528* definfoenclose:: Customized highlighting.
529
530Formatting and Printing Hardcopy
531
532* Use TeX:: Use @TeX{} to format for hardcopy.
533* Format with tex/texindex:: How to format with explicit shell commands.
534* Format with texi2dvi:: A simpler way to format.
535* Print with lpr:: How to print.
536* Within Emacs:: How to format and print from an Emacs shell.
537* Texinfo Mode Printing:: How to format and print in Texinfo mode.
538* Compile-Command:: How to print using Emacs's compile command.
539* Requirements Summary:: @TeX{} formatting requirements summary.
540* Preparing for TeX:: What to do before you use @TeX{}.
541* Overfull hboxes:: What are and what to do with overfull hboxes.
542* smallbook:: How to print small format books and manuals.
543* A4 Paper:: How to print on A4 or A5 paper.
544* pagesizes:: How to print with customized page sizes.
545* Cropmarks and Magnification:: How to print marks to indicate the size
546 of pages and how to print scaled up output.
547* PDF Output:: Portable Document Format output.
548
549Creating and Installing Info Files
550
551* Creating an Info File::
|
539* Installing an Info File::
| 552* Installing an Info File::
|
540
541Creating an Info File
542
543* makeinfo advantages:: @code{makeinfo} provides better error checking.
544* Invoking makeinfo:: How to run @code{makeinfo} from a shell.
545* makeinfo options:: Specify fill-column and other options.
546* Pointer Validation:: How to check that pointers point somewhere.
547* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs.
548* texinfo-format commands:: Two Info formatting commands written
549 in Emacs Lisp are an alternative
550 to @code{makeinfo}.
551* Batch Formatting:: How to format for Info in Emacs Batch mode.
552* Tag and Split Files:: How tagged and split files help Info
553 to run better.
554* makeinfo html:: Generating HTML output.
555
556Installing an Info File
557
558* Directory File:: The top level menu for all Info files.
559* New Info File:: Listing a new Info file.
560* Other Info Directories:: How to specify Info files that are
561 located in other directories.
562* Installing Dir Entries:: How to specify what menu entry to add
563 to the Info directory.
564* Invoking install-info:: @code{install-info} options.
565
| 553
554Creating an Info File
555
556* makeinfo advantages:: @code{makeinfo} provides better error checking.
557* Invoking makeinfo:: How to run @code{makeinfo} from a shell.
558* makeinfo options:: Specify fill-column and other options.
559* Pointer Validation:: How to check that pointers point somewhere.
560* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs.
561* texinfo-format commands:: Two Info formatting commands written
562 in Emacs Lisp are an alternative
563 to @code{makeinfo}.
564* Batch Formatting:: How to format for Info in Emacs Batch mode.
565* Tag and Split Files:: How tagged and split files help Info
566 to run better.
567* makeinfo html:: Generating HTML output.
568
569Installing an Info File
570
571* Directory File:: The top level menu for all Info files.
572* New Info File:: Listing a new Info file.
573* Other Info Directories:: How to specify Info files that are
574 located in other directories.
575* Installing Dir Entries:: How to specify what menu entry to add
576 to the Info directory.
577* Invoking install-info:: @code{install-info} options.
578
|
| 579Sample Texinfo Files
580
581* Short Sample Texinfo File::
582* GNU Sample Texts::
583
|
566Include Files
567
568* Using Include Files:: How to use the @code{@@include} command.
569* texinfo-multiple-files-update:: How to create and update nodes and
570 menus when using included files.
571* Include File Requirements:: What @code{texinfo-multiple-files-update} expects.
572* Sample Include File:: A sample outer file with included files
573 within it; and a sample included file.
574* Include Files Evolution:: How use of the @code{@@include} command
575 has changed over time.
576
577Page Headings
578
579* Headings Introduced:: Conventions for using page headings.
580* Heading Format:: Standard page heading formats.
581* Heading Choice:: How to specify the type of page heading.
582* Custom Headings:: How to create your own headings and footings.
583
584Formatting Mistakes
585
586* makeinfo Preferred:: @code{makeinfo} finds errors.
587* Debugging with Info:: How to catch errors with Info formatting.
588* Debugging with TeX:: How to catch errors with @TeX{} formatting.
589* Using texinfo-show-structure:: How to use @code{texinfo-show-structure}.
590* Using occur:: How to list all lines containing a pattern.
591* Running Info-Validate:: How to find badly referenced nodes.
592
593Finding Badly Referenced Nodes
594
595* Using Info-validate:: How to run @code{Info-validate}.
596* Unsplit:: How to create an unsplit file.
597* Tagifying:: How to tagify a file.
598* Splitting:: How to split a file manually.
599
| 584Include Files
585
586* Using Include Files:: How to use the @code{@@include} command.
587* texinfo-multiple-files-update:: How to create and update nodes and
588 menus when using included files.
589* Include File Requirements:: What @code{texinfo-multiple-files-update} expects.
590* Sample Include File:: A sample outer file with included files
591 within it; and a sample included file.
592* Include Files Evolution:: How use of the @code{@@include} command
593 has changed over time.
594
595Page Headings
596
597* Headings Introduced:: Conventions for using page headings.
598* Heading Format:: Standard page heading formats.
599* Heading Choice:: How to specify the type of page heading.
600* Custom Headings:: How to create your own headings and footings.
601
602Formatting Mistakes
603
604* makeinfo Preferred:: @code{makeinfo} finds errors.
605* Debugging with Info:: How to catch errors with Info formatting.
606* Debugging with TeX:: How to catch errors with @TeX{} formatting.
607* Using texinfo-show-structure:: How to use @code{texinfo-show-structure}.
608* Using occur:: How to list all lines containing a pattern.
609* Running Info-Validate:: How to find badly referenced nodes.
610
611Finding Badly Referenced Nodes
612
613* Using Info-validate:: How to run @code{Info-validate}.
614* Unsplit:: How to create an unsplit file.
615* Tagifying:: How to tagify a file.
616* Splitting:: How to split a file manually.
617
|
| 618Copying This Manual
619
620* GNU Free Documentation License:: License for copying this manual.
621
|
600@end detailmenu
601@end menu
602
603@c Reward readers for getting to the end of the menu :).
604@c Contributed by Arnold Robbins.
605@quotation
606Documentation is like sex: when it is good, it is very, very good; and
607when it is bad, it is better than nothing.
608---Dick Brandon
609@end quotation
610
611
| 622@end detailmenu
623@end menu
624
625@c Reward readers for getting to the end of the menu :).
626@c Contributed by Arnold Robbins.
627@quotation
628Documentation is like sex: when it is good, it is very, very good; and
629when it is bad, it is better than nothing.
630---Dick Brandon
631@end quotation
632
633
|
612@node Copying
| 634@node Copying Conditions
|
613@unnumbered Texinfo Copying Conditions
614@cindex Copying conditions
615@cindex Conditions for copying Texinfo
616
617The programs currently being distributed that relate to Texinfo include
618@code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}.
619These programs are @dfn{free}; this means that everyone is free to use
620them and free to redistribute them on a free basis. The Texinfo-related
621programs are not in the public domain; they are copyrighted and there
622are restrictions on their distribution, but these restrictions are
623designed to permit everything that a good cooperating citizen would want
624to do. What is not allowed is to try to prevent others from further
625sharing any version of these programs that they might get from you.
626
627Specifically, we want to make sure that you have the right to give away
628copies of the programs that relate to Texinfo, that you receive source
629code or else can get it if you want it, that you can change these
630programs or use pieces of them in new free programs, and that you know
631you can do these things.
632
633To make sure that everyone has such rights, we have to forbid you to
634deprive anyone else of these rights. For example, if you distribute
635copies of the Texinfo related programs, you must give the recipients all
636the rights that you have. You must make sure that they, too, receive or
637can get the source code. And you must tell them their rights.
638
639Also, for our own protection, we must make certain that everyone finds
640out that there is no warranty for the programs that relate to Texinfo.
641If these programs are modified by someone else and passed on, we want
642their recipients to know that what they have is not what we distributed,
643so that any problems introduced by others will not reflect on our
644reputation.
645
646The precise conditions of the licenses for the programs currently being
647distributed that relate to Texinfo are found in the General Public
| 635@unnumbered Texinfo Copying Conditions
636@cindex Copying conditions
637@cindex Conditions for copying Texinfo
638
639The programs currently being distributed that relate to Texinfo include
640@code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}.
641These programs are @dfn{free}; this means that everyone is free to use
642them and free to redistribute them on a free basis. The Texinfo-related
643programs are not in the public domain; they are copyrighted and there
644are restrictions on their distribution, but these restrictions are
645designed to permit everything that a good cooperating citizen would want
646to do. What is not allowed is to try to prevent others from further
647sharing any version of these programs that they might get from you.
648
649Specifically, we want to make sure that you have the right to give away
650copies of the programs that relate to Texinfo, that you receive source
651code or else can get it if you want it, that you can change these
652programs or use pieces of them in new free programs, and that you know
653you can do these things.
654
655To make sure that everyone has such rights, we have to forbid you to
656deprive anyone else of these rights. For example, if you distribute
657copies of the Texinfo related programs, you must give the recipients all
658the rights that you have. You must make sure that they, too, receive or
659can get the source code. And you must tell them their rights.
660
661Also, for our own protection, we must make certain that everyone finds
662out that there is no warranty for the programs that relate to Texinfo.
663If these programs are modified by someone else and passed on, we want
664their recipients to know that what they have is not what we distributed,
665so that any problems introduced by others will not reflect on our
666reputation.
667
668The precise conditions of the licenses for the programs currently being
669distributed that relate to Texinfo are found in the General Public
|
648Licenses that accompany them.
| 670Licenses that accompany them. This manual specifically is covered by
671the GNU Free Documentation License (@pxref{GNU Free Documentation
672License}).
|
649
650
651@node Overview
652@chapter Overview of Texinfo
653@cindex Overview of Texinfo
654@cindex Texinfo overview
655
656@dfn{Texinfo}@footnote{The first syllable of ``Texinfo'' is pronounced
657like ``speck'', not ``hex''. This odd pronunciation is derived from,
658but is not the same as, the pronunciation of @TeX{}. In the word
659@TeX{}, the @samp{X} is actually the Greek letter ``chi'' rather than
660the English letter ``ex''. Pronounce @TeX{} as if the @samp{X} were the
661last sound in the name `Bach'; but pronounce Texinfo as if the @samp{x}
662were a `k'. Spell ``Texinfo'' with a capital ``T'' and the other
663letters in lower case.} is a documentation system that uses a single
664source file to produce both online information and printed output. This
665means that instead of writing two different documents, one for the
666online information and the other for a printed work, you need write only
667one document. Therefore, when the work is revised, you need revise only
668that one document.
669
670@menu
671* Reporting Bugs:: Submitting effective bug reports.
672* Using Texinfo:: Create printed or online output.
673* Info Files:: What is an Info file?
674* Printed Books:: Characteristics of a printed book or manual.
675* Formatting Commands:: @@-commands are used for formatting.
676* Conventions:: General rules for writing a Texinfo file.
677* Comments:: Writing comments and ignored text in general.
678* Minimum:: What a Texinfo file must have.
679* Six Parts:: Usually, a Texinfo file has six parts.
680* Short Sample:: A short sample Texinfo file.
681* History:: Acknowledgements, contributors and genesis.
682@end menu
683
684
685@node Reporting Bugs
686@section Reporting Bugs
687
688@cindex Bugs, reporting
689@cindex Suggestions for Texinfo, making
690@cindex Reporting bugs
691We welcome bug reports and suggestions for any aspect of the Texinfo system,
692programs, documentation, installation, anything. Please email them to
693@email{bug-texinfo@@gnu.org}. You can get the latest version of Texinfo
694from @uref{ftp://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide.
695
696@cindex Checklist for bug reports
697For bug reports, please include enough information for the maintainers
698to reproduce the problem. Generally speaking, that means:
699
700@itemize @bullet
701@item the version number of Texinfo and the program(s) or manual(s) involved.
| 673
674
675@node Overview
676@chapter Overview of Texinfo
677@cindex Overview of Texinfo
678@cindex Texinfo overview
679
680@dfn{Texinfo}@footnote{The first syllable of ``Texinfo'' is pronounced
681like ``speck'', not ``hex''. This odd pronunciation is derived from,
682but is not the same as, the pronunciation of @TeX{}. In the word
683@TeX{}, the @samp{X} is actually the Greek letter ``chi'' rather than
684the English letter ``ex''. Pronounce @TeX{} as if the @samp{X} were the
685last sound in the name `Bach'; but pronounce Texinfo as if the @samp{x}
686were a `k'. Spell ``Texinfo'' with a capital ``T'' and the other
687letters in lower case.} is a documentation system that uses a single
688source file to produce both online information and printed output. This
689means that instead of writing two different documents, one for the
690online information and the other for a printed work, you need write only
691one document. Therefore, when the work is revised, you need revise only
692that one document.
693
694@menu
695* Reporting Bugs:: Submitting effective bug reports.
696* Using Texinfo:: Create printed or online output.
697* Info Files:: What is an Info file?
698* Printed Books:: Characteristics of a printed book or manual.
699* Formatting Commands:: @@-commands are used for formatting.
700* Conventions:: General rules for writing a Texinfo file.
701* Comments:: Writing comments and ignored text in general.
702* Minimum:: What a Texinfo file must have.
703* Six Parts:: Usually, a Texinfo file has six parts.
704* Short Sample:: A short sample Texinfo file.
705* History:: Acknowledgements, contributors and genesis.
706@end menu
707
708
709@node Reporting Bugs
710@section Reporting Bugs
711
712@cindex Bugs, reporting
713@cindex Suggestions for Texinfo, making
714@cindex Reporting bugs
715We welcome bug reports and suggestions for any aspect of the Texinfo system,
716programs, documentation, installation, anything. Please email them to
717@email{bug-texinfo@@gnu.org}. You can get the latest version of Texinfo
718from @uref{ftp://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide.
719
720@cindex Checklist for bug reports
721For bug reports, please include enough information for the maintainers
722to reproduce the problem. Generally speaking, that means:
723
724@itemize @bullet
725@item the version number of Texinfo and the program(s) or manual(s) involved.
|
702@item hardware, operating system, and compiler versions.
703@item any unusual options you gave to @command{configure}.
| 726@item hardware and operating system names and versions.
|
704@item the contents of any input files necessary to reproduce the bug.
705@item a description of the problem and samples of any erroneous output.
| 727@item the contents of any input files necessary to reproduce the bug.
728@item a description of the problem and samples of any erroneous output.
|
| 729@item any unusual options you gave to @command{configure}.
|
706@item anything else that you think would be helpful.
707@end itemize
708
709When in doubt whether something is needed or not, include it. It's
710better to include too much than to leave out something important.
711
| 730@item anything else that you think would be helpful.
731@end itemize
732
733When in doubt whether something is needed or not, include it. It's
734better to include too much than to leave out something important.
735
|
| 736@cindex Patches, contributing
|
712Patches are most welcome; if possible, please make them with
713@samp{@w{diff -c}} (@pxref{Top,, Overview, diffutils, Comparing and
714Merging Files}) and include @file{ChangeLog} entries (@pxref{Change
715Log,,, emacs, The GNU Emacs Manual}).
716
717When sending patches, if possible please do not encode or split them in
718any way; it's much easier to deal with one plain text message, however
719large, than many small ones. @uref{ftp://ftp.gnu.org/gnu/sharutils/,
720GNU shar} is a convenient way of packaging multiple and/or binary files
721for email.
722
723
724@node Using Texinfo
725@section Using Texinfo
726
727@cindex Using Texinfo in general
728@cindex Texinfo, introduction to
729@cindex Introduction to Texinfo
730
731Using Texinfo, you can create a printed document with the normal
732features of a book, including chapters, sections, cross references, and
733indices. From the same Texinfo source file, you can create a
734menu-driven, online Info file with nodes, menus, cross references, and
735indices. You can also create from that same source file an HTML output
736file suitable for use with a web browser, or an XML file. @cite{The GNU
737Emacs Manual} is a good example of a Texinfo file, as is this manual.
738
739To make a printed document, you process a Texinfo source file with the
740@TeX{} typesetting program (but the Texinfo language is very different
| 737Patches are most welcome; if possible, please make them with
738@samp{@w{diff -c}} (@pxref{Top,, Overview, diffutils, Comparing and
739Merging Files}) and include @file{ChangeLog} entries (@pxref{Change
740Log,,, emacs, The GNU Emacs Manual}).
741
742When sending patches, if possible please do not encode or split them in
743any way; it's much easier to deal with one plain text message, however
744large, than many small ones. @uref{ftp://ftp.gnu.org/gnu/sharutils/,
745GNU shar} is a convenient way of packaging multiple and/or binary files
746for email.
747
748
749@node Using Texinfo
750@section Using Texinfo
751
752@cindex Using Texinfo in general
753@cindex Texinfo, introduction to
754@cindex Introduction to Texinfo
755
756Using Texinfo, you can create a printed document with the normal
757features of a book, including chapters, sections, cross references, and
758indices. From the same Texinfo source file, you can create a
759menu-driven, online Info file with nodes, menus, cross references, and
760indices. You can also create from that same source file an HTML output
761file suitable for use with a web browser, or an XML file. @cite{The GNU
762Emacs Manual} is a good example of a Texinfo file, as is this manual.
763
764To make a printed document, you process a Texinfo source file with the
765@TeX{} typesetting program (but the Texinfo language is very different
|
741from @TeX{}'s usual language, plain @TeX{}). This creates a DVI file
742that you can typeset and print as a book or report (@pxref{Hardcopy}).
| 766and much stricter than @TeX{}'s usual language, plain @TeX{}). This
767creates a DVI file that you can typeset and print as a book or report
768(@pxref{Hardcopy}).
|
743
744@pindex makeinfo
745To output an Info file, process your Texinfo source with the
746@code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command.
747You can install the result in your Info tree (@pxref{Installing an Info
748File}).
749
750To output an HTML file, run @code{makeinfo --html} on your Texinfo
751source. You can (for example) install the result on your web site.
752
753@cindex Docbook, converting to Texinfo
754@cindex Conversion, from Docbook to Texinfo
755To output an XML file, run @code{makeinfo --xml} on your Texinfo source.
| 769
770@pindex makeinfo
771To output an Info file, process your Texinfo source with the
772@code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command.
773You can install the result in your Info tree (@pxref{Installing an Info
774File}).
775
776To output an HTML file, run @code{makeinfo --html} on your Texinfo
777source. You can (for example) install the result on your web site.
778
779@cindex Docbook, converting to Texinfo
780@cindex Conversion, from Docbook to Texinfo
781To output an XML file, run @code{makeinfo --xml} on your Texinfo source.
|
756To output DocBook, run @code{makeinfo --docbook}. If you want to
757convert from Docbook @emph{to} Texinfo, please see
758@uref{http://docbook2X.sourceforge.net/}.
| 782To output DocBook (a particular form of XML), run @code{makeinfo
783--docbook}. If you want to convert from Docbook @emph{to} Texinfo,
784please see @uref{http://docbook2X.sourceforge.net/}.
|
759
760@cindex Output formats, supporting more
761@cindex SGML-tools output format
762If you are a programmer and would like to contribute to the GNU project
763by implementing additional output formats for Texinfo, that would be
764excellent. But please do not write a separate translator texi2foo for
765your favorite format foo! That is the hard way to do the job, and makes
766extra work in subsequent maintenance, since the Texinfo language is
767continually being enhanced and updated. Instead, the best approach is
768modify @code{makeinfo} to generate the new format, as it does now for
| 785
786@cindex Output formats, supporting more
787@cindex SGML-tools output format
788If you are a programmer and would like to contribute to the GNU project
789by implementing additional output formats for Texinfo, that would be
790excellent. But please do not write a separate translator texi2foo for
791your favorite format foo! That is the hard way to do the job, and makes
792extra work in subsequent maintenance, since the Texinfo language is
793continually being enhanced and updated. Instead, the best approach is
794modify @code{makeinfo} to generate the new format, as it does now for
|
769Info and HTML.
| 795Info, plain text, HTML, XML, and DocBook.
|
770
771@TeX{} works with virtually all printers; Info works with virtually all
772computer terminals; the HTML output works with virtually all web
773browsers. Thus Texinfo can be used by almost any computer user.
774
775@cindex Source file
776A Texinfo source file is a plain @sc{ascii} file containing text and
777@dfn{@@-commands} (words preceded by an @samp{@@}) that tell the
778typesetting and formatting programs what to do. You may edit a Texinfo
779file with any text editor; but it is especially convenient to use GNU
780Emacs since that editor has a special mode, called Texinfo mode, that
781provides various Texinfo-related features. (@xref{Texinfo Mode}.)
782
783Before writing a Texinfo source file, you should learn about nodes,
784menus, cross references, and the rest, for example by reading this
785manual.
786
787You can use Texinfo to create both online help and printed manuals;
788moreover, Texinfo is freely redistributable. For these reasons, Texinfo
789is the official documentation format of the GNU project. More
790information is available at the @uref{http://www.gnu.org/doc/, GNU
791documentation web page}.
792
793@cindex Man page output, not supported
794From time to time, proposals are made to generate traditional Unix man
795pages from Texinfo source. This is not likely to ever be supported,
796because man pages have a very strict conventional format. Merely
797enhancing @command{makeinfo} to output troff format would be
798insufficient. Generating a good man page therefore requires a
799completely different source than the typical Texinfo applications of
| 796
797@TeX{} works with virtually all printers; Info works with virtually all
798computer terminals; the HTML output works with virtually all web
799browsers. Thus Texinfo can be used by almost any computer user.
800
801@cindex Source file
802A Texinfo source file is a plain @sc{ascii} file containing text and
803@dfn{@@-commands} (words preceded by an @samp{@@}) that tell the
804typesetting and formatting programs what to do. You may edit a Texinfo
805file with any text editor; but it is especially convenient to use GNU
806Emacs since that editor has a special mode, called Texinfo mode, that
807provides various Texinfo-related features. (@xref{Texinfo Mode}.)
808
809Before writing a Texinfo source file, you should learn about nodes,
810menus, cross references, and the rest, for example by reading this
811manual.
812
813You can use Texinfo to create both online help and printed manuals;
814moreover, Texinfo is freely redistributable. For these reasons, Texinfo
815is the official documentation format of the GNU project. More
816information is available at the @uref{http://www.gnu.org/doc/, GNU
817documentation web page}.
818
819@cindex Man page output, not supported
820From time to time, proposals are made to generate traditional Unix man
821pages from Texinfo source. This is not likely to ever be supported,
822because man pages have a very strict conventional format. Merely
823enhancing @command{makeinfo} to output troff format would be
824insufficient. Generating a good man page therefore requires a
825completely different source than the typical Texinfo applications of
|
800generating a good user manual or a good reference manual. This makes
| 826writing a good user tutorial or a good reference manual. This makes
|
801generating man pages incompatible with the Texinfo design goal of not
802having to document the same information in different ways for different
803output formats. You might as well just write the man page directly.
804
805@pindex help2man
806@cindex O'Dea, Brendan
| 827generating man pages incompatible with the Texinfo design goal of not
828having to document the same information in different ways for different
829output formats. You might as well just write the man page directly.
830
831@pindex help2man
832@cindex O'Dea, Brendan
|
807If you wish to support man pages, the program @command{help2man} may be
808useful; it generates a traditional man page from the @samp{--help}
809output of a program. In fact, this is currently used to generate man
810pages for the Texinfo programs themselves. It is GNU software written
811by Brendan O'Dea, available from
812@uref{http://www.ozemail.com.au/~bod/help2man.tar.gz}.
| 833Man pages still have their place, and if you wish to support them, the
834program @command{help2man} may be useful; it generates a traditional man
835page from the @samp{--help} output of a program. In fact, this is
836currently used to generate man pages for the Texinfo programs
837themselves. It is GNU software written by Brendan O'Dea, available from
838@uref{ftp://ftp.gnu.org/gnu/help2man/}.
|
813
814
815@node Info Files
816@section Info files
817@cindex Info files
818
819An Info file is a Texinfo file formatted so that the Info documentation
820reading program can operate on it. (@code{makeinfo}
821and @code{texinfo-format-buffer} are two commands that convert a Texinfo file
| 839
840
841@node Info Files
842@section Info files
843@cindex Info files
844
845An Info file is a Texinfo file formatted so that the Info documentation
846reading program can operate on it. (@code{makeinfo}
847and @code{texinfo-format-buffer} are two commands that convert a Texinfo file
|
822into an Info file.)@refill
| 848into an Info file.)
|
823
824Info files are divided into pieces called @dfn{nodes}, each of which
825contains the discussion of one topic. Each node has a name, and
826contains both text for the user to read and pointers to other nodes,
827which are identified by their names. The Info program displays one node
828at a time, and provides commands with which the user can move to other
| 849
850Info files are divided into pieces called @dfn{nodes}, each of which
851contains the discussion of one topic. Each node has a name, and
852contains both text for the user to read and pointers to other nodes,
853which are identified by their names. The Info program displays one node
854at a time, and provides commands with which the user can move to other
|
829related nodes.@refill
| 855related nodes.
|
830
831@ifinfo
| 856
857@ifinfo
|
832@inforef{Top, info, info}, for more information about using Info.@refill
| 858@inforef{Top, info, info}, for more information about using Info.
|
833@end ifinfo
834
835Each node of an Info file may have any number of child nodes that
836describe subtopics of the node's topic. The names of child
837nodes are listed in a @dfn{menu} within the parent node; this
838allows you to use certain Info commands to move to one of the child
839nodes. Generally, an Info file is organized like a book. If a node
840is at the logical level of a chapter, its child nodes are at the level
841of sections; likewise, the child nodes of sections are at the level
| 859@end ifinfo
860
861Each node of an Info file may have any number of child nodes that
862describe subtopics of the node's topic. The names of child
863nodes are listed in a @dfn{menu} within the parent node; this
864allows you to use certain Info commands to move to one of the child
865nodes. Generally, an Info file is organized like a book. If a node
866is at the logical level of a chapter, its child nodes are at the level
867of sections; likewise, the child nodes of sections are at the level
|
842of subsections.@refill
| 868of subsections.
|
843
844All the children of any one parent are linked together in a
845bidirectional chain of `Next' and `Previous' pointers. The `Next'
846pointer provides a link to the next section, and the `Previous' pointer
847provides a link to the previous section. This means that all the nodes
848that are at the level of sections within a chapter are linked together.
849Normally the order in this chain is the same as the order of the
850children in the parent's menu. Each child node records the parent node
851name as its `Up' pointer. The last child has no `Next' pointer, and the
852first child has the parent both as its `Previous' and as its `Up'
853pointer.@footnote{In some documents, the first child has no `Previous'
854pointer. Occasionally, the last child has the node name of the next
| 869
870All the children of any one parent are linked together in a
871bidirectional chain of `Next' and `Previous' pointers. The `Next'
872pointer provides a link to the next section, and the `Previous' pointer
873provides a link to the previous section. This means that all the nodes
874that are at the level of sections within a chapter are linked together.
875Normally the order in this chain is the same as the order of the
876children in the parent's menu. Each child node records the parent node
877name as its `Up' pointer. The last child has no `Next' pointer, and the
878first child has the parent both as its `Previous' and as its `Up'
879pointer.@footnote{In some documents, the first child has no `Previous'
880pointer. Occasionally, the last child has the node name of the next
|
855following higher level node as its `Next' pointer.}@refill
| 881following higher level node as its `Next' pointer.}
|
856
857The book-like structuring of an Info file into nodes that correspond
858to chapters, sections, and the like is a matter of convention, not a
859requirement. The `Up', `Previous', and `Next' pointers of a node can
860point to any other nodes, and a menu can contain any other nodes.
861Thus, the node structure can be any directed graph. But it is usually
862more comprehensible to follow a structure that corresponds to the
863structure of chapters and sections in a printed book or report.@refill
864
865In addition to menus and to `Next', `Previous', and `Up' pointers, Info
866provides pointers of another kind, called references, that can be
867sprinkled throughout the text. This is usually the best way to
868represent links that do not fit a hierarchical structure.@refill
869
870Usually, you will design a document so that its nodes match the
871structure of chapters and sections in the printed output. But
872occasionally there are times when this is not right for the material
873being discussed. Therefore, Texinfo uses separate commands to specify
874the node structure for the Info file and the section structure for the
875printed output.@refill
876
877Generally, you enter an Info file through a node that by convention is
878named `Top'. This node normally contains just a brief summary of the
879file's purpose, and a large menu through which the rest of the file is
880reached. From this node, you can either traverse the file
881systematically by going from node to node, or you can go to a specific
882node listed in the main menu, or you can search the index menus and then
883go directly to the node that has the information you want. Alternatively,
884with the standalone Info program, you can specify specific menu items on
885the command line (@pxref{Top,,, info, Info}).
886
887If you want to read through an Info file in sequence, as if it were a
888printed manual, you can hit @key{SPC} repeatedly, or you get the whole
889file with the advanced Info command @kbd{g *}. (@inforef{Expert,
890Advanced Info commands, info}.)@refill
891
892@c !!! dir file may be located in one of many places:
893@c /usr/local/emacs/info mentioned in info.c DEFAULT_INFOPATH
894@c /usr/local/lib/emacs/info mentioned in info.c DEFAULT_INFOPATH
895@c /usr/gnu/info mentioned in info.c DEFAULT_INFOPATH
896@c /usr/local/info
897@c /usr/local/lib/info
898The @file{dir} file in the @file{info} directory serves as the
899departure point for the whole Info system. From it, you can reach the
900`Top' nodes of each of the documents in a complete Info system.@refill
901
902@cindex URI syntax for Info
903If you wish to refer to an Info file in a URI, you can use the
904(unofficial) syntax exemplified in the following. This works with
905Emacs/W3, for example:
906@example
907info:///usr/info/emacs#Dissociated%20Press
908info:emacs#Dissociated%20Press
909info://localhost/usr/info/emacs#Dissociated%20Press
910@end example
911
912The @command{info} program itself does not follow URI's of any kind.
913
914
915@node Printed Books
916@section Printed Books
917@cindex Printed book and manual characteristics
918@cindex Manual characteristics, printed
919@cindex Book characteristics, printed
920@cindex Texinfo printed book characteristics
921@cindex Characteristics, printed books or manuals
922
923@cindex Knuth, Donald
924A Texinfo file can be formatted and typeset as a printed book or manual.
925To do this, you need @TeX{}, a powerful, sophisticated typesetting
926program written by Donald Knuth.@footnote{You can also use the
927@pindex texi2roff@r{, unsupported software}
928@uref{ftp://tug.org/texi2roff.tar.gz, @code{texi2roff}} program if you
929do not have @TeX{}; since Texinfo is designed for use with @TeX{},
930@code{texi2roff} is not described here. @code{texi2roff} is not part of
931the standard GNU distribution and is not maintained or up-to-date with
932all the Texinfo features described in this manual.}
933
934A Texinfo-based book is similar to any other typeset, printed work: it
935can have a title page, copyright page, table of contents, and preface,
936as well as chapters, numbered or unnumbered sections and subsections,
937page headers, cross references, footnotes, and indices.@refill
938
939You can use Texinfo to write a book without ever having the intention
940of converting it into online information. You can use Texinfo for
941writing a printed novel, and even to write a printed memo, although
942this latter application is not recommended since electronic mail is so
943much easier.@refill
944
945@TeX{} is a general purpose typesetting program. Texinfo provides a
946file @file{texinfo.tex} that contains information (definitions or
947@dfn{macros}) that @TeX{} uses when it typesets a Texinfo file.
948(@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands
949to @TeX{} commands, which @TeX{} can then process to create the typeset
950document.) @file{texinfo.tex} contains the specifications for printing
951a document. You can get the latest version of @file{texinfo.tex} from
952@uref{ftp://ftp.gnu.org/gnu/texinfo.tex}.
953
| 882
883The book-like structuring of an Info file into nodes that correspond
884to chapters, sections, and the like is a matter of convention, not a
885requirement. The `Up', `Previous', and `Next' pointers of a node can
886point to any other nodes, and a menu can contain any other nodes.
887Thus, the node structure can be any directed graph. But it is usually
888more comprehensible to follow a structure that corresponds to the
889structure of chapters and sections in a printed book or report.@refill
890
891In addition to menus and to `Next', `Previous', and `Up' pointers, Info
892provides pointers of another kind, called references, that can be
893sprinkled throughout the text. This is usually the best way to
894represent links that do not fit a hierarchical structure.@refill
895
896Usually, you will design a document so that its nodes match the
897structure of chapters and sections in the printed output. But
898occasionally there are times when this is not right for the material
899being discussed. Therefore, Texinfo uses separate commands to specify
900the node structure for the Info file and the section structure for the
901printed output.@refill
902
903Generally, you enter an Info file through a node that by convention is
904named `Top'. This node normally contains just a brief summary of the
905file's purpose, and a large menu through which the rest of the file is
906reached. From this node, you can either traverse the file
907systematically by going from node to node, or you can go to a specific
908node listed in the main menu, or you can search the index menus and then
909go directly to the node that has the information you want. Alternatively,
910with the standalone Info program, you can specify specific menu items on
911the command line (@pxref{Top,,, info, Info}).
912
913If you want to read through an Info file in sequence, as if it were a
914printed manual, you can hit @key{SPC} repeatedly, or you get the whole
915file with the advanced Info command @kbd{g *}. (@inforef{Expert,
916Advanced Info commands, info}.)@refill
917
918@c !!! dir file may be located in one of many places:
919@c /usr/local/emacs/info mentioned in info.c DEFAULT_INFOPATH
920@c /usr/local/lib/emacs/info mentioned in info.c DEFAULT_INFOPATH
921@c /usr/gnu/info mentioned in info.c DEFAULT_INFOPATH
922@c /usr/local/info
923@c /usr/local/lib/info
924The @file{dir} file in the @file{info} directory serves as the
925departure point for the whole Info system. From it, you can reach the
926`Top' nodes of each of the documents in a complete Info system.@refill
927
928@cindex URI syntax for Info
929If you wish to refer to an Info file in a URI, you can use the
930(unofficial) syntax exemplified in the following. This works with
931Emacs/W3, for example:
932@example
933info:///usr/info/emacs#Dissociated%20Press
934info:emacs#Dissociated%20Press
935info://localhost/usr/info/emacs#Dissociated%20Press
936@end example
937
938The @command{info} program itself does not follow URI's of any kind.
939
940
941@node Printed Books
942@section Printed Books
943@cindex Printed book and manual characteristics
944@cindex Manual characteristics, printed
945@cindex Book characteristics, printed
946@cindex Texinfo printed book characteristics
947@cindex Characteristics, printed books or manuals
948
949@cindex Knuth, Donald
950A Texinfo file can be formatted and typeset as a printed book or manual.
951To do this, you need @TeX{}, a powerful, sophisticated typesetting
952program written by Donald Knuth.@footnote{You can also use the
953@pindex texi2roff@r{, unsupported software}
954@uref{ftp://tug.org/texi2roff.tar.gz, @code{texi2roff}} program if you
955do not have @TeX{}; since Texinfo is designed for use with @TeX{},
956@code{texi2roff} is not described here. @code{texi2roff} is not part of
957the standard GNU distribution and is not maintained or up-to-date with
958all the Texinfo features described in this manual.}
959
960A Texinfo-based book is similar to any other typeset, printed work: it
961can have a title page, copyright page, table of contents, and preface,
962as well as chapters, numbered or unnumbered sections and subsections,
963page headers, cross references, footnotes, and indices.@refill
964
965You can use Texinfo to write a book without ever having the intention
966of converting it into online information. You can use Texinfo for
967writing a printed novel, and even to write a printed memo, although
968this latter application is not recommended since electronic mail is so
969much easier.@refill
970
971@TeX{} is a general purpose typesetting program. Texinfo provides a
972file @file{texinfo.tex} that contains information (definitions or
973@dfn{macros}) that @TeX{} uses when it typesets a Texinfo file.
974(@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands
975to @TeX{} commands, which @TeX{} can then process to create the typeset
976document.) @file{texinfo.tex} contains the specifications for printing
977a document. You can get the latest version of @file{texinfo.tex} from
978@uref{ftp://ftp.gnu.org/gnu/texinfo.tex}.
979
|
954Most often, documents are printed on 8.5 inch by 11 inch pages
955(216@dmn{mm} by 280@dmn{mm}; this is the default size), but you can also
956print for 7 inch by 9.25 inch pages (178@dmn{mm} by 235@dmn{mm}; the
957@code{@@smallbook} size) or on A4 or A5 size paper (@code{@@afourpaper},
958@code{@@afivepaper}). (@xref{smallbook, , Printing ``Small'' Books}.
959Also, see @ref{A4 Paper, ,Printing on A4 Paper}.)
| 980In the United States, documents are most often printed on 8.5 inch by 11
981inch pages (216@dmn{mm} by 280@dmn{mm}); this is the default size. But
982you can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by
983235@dmn{mm}, the @code{@@smallbook} size; or on A4 or A5 size paper
984(@code{@@afourpaper}, @code{@@afivepaper}). (@xref{smallbook, ,
985Printing ``Small'' Books}. Also, see @ref{A4 Paper, ,Printing on A4
986Paper}.)
|
960
961By changing the parameters in @file{texinfo.tex}, you can change the
962size of the printed document. In addition, you can change the style in
963which the printed document is formatted; for example, you can change the
964sizes and fonts used, the amount of indentation for each paragraph, the
965degree to which words are hyphenated, and the like. By changing the
966specifications, you can make a book look dignified, old and serious, or
| 987
988By changing the parameters in @file{texinfo.tex}, you can change the
989size of the printed document. In addition, you can change the style in
990which the printed document is formatted; for example, you can change the
991sizes and fonts used, the amount of indentation for each paragraph, the
992degree to which words are hyphenated, and the like. By changing the
993specifications, you can make a book look dignified, old and serious, or
|
967light-hearted, young and cheery.@refill
| 994light-hearted, young and cheery.
|
968
969@TeX{} is freely distributable. It is written in a superset of Pascal
970called WEB and can be compiled either in Pascal or (by using a
971conversion program that comes with the @TeX{} distribution) in C.
972(@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information
973about @TeX{}.)@refill
974
975@TeX{} is very powerful and has a great many features. Because a
976Texinfo file must be able to present information both on a
977character-only terminal in Info form and in a typeset book, the
| 995
996@TeX{} is freely distributable. It is written in a superset of Pascal
997called WEB and can be compiled either in Pascal or (by using a
998conversion program that comes with the @TeX{} distribution) in C.
999(@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information
1000about @TeX{}.)@refill
1001
1002@TeX{} is very powerful and has a great many features. Because a
1003Texinfo file must be able to present information both on a
1004character-only terminal in Info form and in a typeset book, the
|
978formatting commands that Texinfo supports are necessarily
979limited.@refill
| 1005formatting commands that Texinfo supports are necessarily limited.
|
980
981To get a copy of @TeX{}, see
982@ref{Obtaining TeX, , How to Obtain @TeX{}}.
983
984
| 1006
1007To get a copy of @TeX{}, see
1008@ref{Obtaining TeX, , How to Obtain @TeX{}}.
1009
1010
|
985@node Formatting Commands, Conventions, Printed Books, Overview
| 1011@node Formatting Commands
|
986@section @@-commands
987@cindex @@-commands
988@cindex Formatting commands
989
990In a Texinfo file, the commands that tell @TeX{} how to typeset the
991printed manual and tell @code{makeinfo} and
992@code{texinfo-format-buffer} how to create an Info file are preceded
993by @samp{@@}; they are called @dfn{@@-commands}. For example,
994@code{@@node} is the command to indicate a node and @code{@@chapter}
995is the command to indicate the start of a chapter.@refill
996
997@quotation
998@strong{Please note:} All the @@-commands, with the exception of the
| 1012@section @@-commands
1013@cindex @@-commands
1014@cindex Formatting commands
1015
1016In a Texinfo file, the commands that tell @TeX{} how to typeset the
1017printed manual and tell @code{makeinfo} and
1018@code{texinfo-format-buffer} how to create an Info file are preceded
1019by @samp{@@}; they are called @dfn{@@-commands}. For example,
1020@code{@@node} is the command to indicate a node and @code{@@chapter}
1021is the command to indicate the start of a chapter.@refill
1022
1023@quotation
1024@strong{Please note:} All the @@-commands, with the exception of the
|
999@code{@@TeX@{@}} command, must be written entirely in lower
1000case.@refill
| 1025@code{@@TeX@{@}} command, must be written entirely in lower case.
|
1001@end quotation
1002
1003The Texinfo @@-commands are a strictly limited set of constructs. The
1004strict limits make it possible for Texinfo files to be understood both
1005by @TeX{} and by the code that converts them into Info files. You can
1006display Info files on any terminal that displays alphabetic and
1007numeric characters. Similarly, you can print the output generated by
1008@TeX{} on a wide variety of printers.@refill
1009
1010Depending on what they do or what arguments@footnote{The word
1011@dfn{argument} comes from the way it is used in mathematics and does not
1012refer to a dispute between two people; it refers to the information
1013presented to the command. According to the @cite{Oxford English
1014Dictionary}, the word derives from the Latin for @dfn{to make clear,
1015prove}; thus it came to mean `the evidence offered as proof', which is
1016to say, `the information offered', which led to its mathematical
1017meaning. In its other thread of derivation, the word came to mean `to
1018assert in a manner against which others may make counter assertions',
1019which led to the meaning of `argument' as a dispute.} they take, you
1020need to write @@-commands on lines of their own or as part of
1021sentences:
1022
1023@itemize @bullet
1024@item
1025Write a command such as @code{@@noindent} at the beginning of a line as
1026the only text on the line. (@code{@@noindent} prevents the beginning of
1027the next line from being indented as the beginning of a
1028paragraph.)@refill
1029
1030@item
1031Write a command such as @code{@@chapter} at the beginning of a line
1032followed by the command's arguments, in this case the chapter title, on
1033the rest of the line. (@code{@@chapter} creates chapter titles.)@refill
1034
1035@item
1036Write a command such as @code{@@dots@{@}} wherever you wish but usually
1037within a sentence. (@code{@@dots@{@}} creates dots @dots{})@refill
1038
1039@item
1040Write a command such as @code{@@code@{@var{sample-code}@}} wherever you
1041wish (but usually within a sentence) with its argument,
1042@var{sample-code} in this example, between the braces. (@code{@@code}
1043marks text as being code.)@refill
1044
1045@item
1046Write a command such as @code{@@example} on a line of its own; write the
1047body-text on following lines; and write the matching @code{@@end}
1048command, @code{@@end example} in this case, at the on a line of its own
1049after the body-text. (@code{@@example} @dots{} @code{@@end example}
1050indents and typesets body-text as an example.) It's usually ok to
1051indent environment commands like this, but in complicated and
1052hard-to-define circumstances the extra spaces cause extra space to
1053appear in the output, so beware.
1054@end itemize
1055
1056@noindent
1057@cindex Braces, when to use
1058As a general rule, a command requires braces if it mingles among other
1059text; but it does not need braces if it starts a line of its own. The
1060non-alphabetic commands, such as @code{@@:}, are exceptions to the rule;
1061they do not need braces.@refill
1062
1063As you gain experience with Texinfo, you will rapidly learn how to
1064write the different commands: the different ways to write commands
1065make it easier to write and read Texinfo files than if all commands
1066followed exactly the same syntax. (For details about @@-command
1067syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill
1068
1069
| 1026@end quotation
1027
1028The Texinfo @@-commands are a strictly limited set of constructs. The
1029strict limits make it possible for Texinfo files to be understood both
1030by @TeX{} and by the code that converts them into Info files. You can
1031display Info files on any terminal that displays alphabetic and
1032numeric characters. Similarly, you can print the output generated by
1033@TeX{} on a wide variety of printers.@refill
1034
1035Depending on what they do or what arguments@footnote{The word
1036@dfn{argument} comes from the way it is used in mathematics and does not
1037refer to a dispute between two people; it refers to the information
1038presented to the command. According to the @cite{Oxford English
1039Dictionary}, the word derives from the Latin for @dfn{to make clear,
1040prove}; thus it came to mean `the evidence offered as proof', which is
1041to say, `the information offered', which led to its mathematical
1042meaning. In its other thread of derivation, the word came to mean `to
1043assert in a manner against which others may make counter assertions',
1044which led to the meaning of `argument' as a dispute.} they take, you
1045need to write @@-commands on lines of their own or as part of
1046sentences:
1047
1048@itemize @bullet
1049@item
1050Write a command such as @code{@@noindent} at the beginning of a line as
1051the only text on the line. (@code{@@noindent} prevents the beginning of
1052the next line from being indented as the beginning of a
1053paragraph.)@refill
1054
1055@item
1056Write a command such as @code{@@chapter} at the beginning of a line
1057followed by the command's arguments, in this case the chapter title, on
1058the rest of the line. (@code{@@chapter} creates chapter titles.)@refill
1059
1060@item
1061Write a command such as @code{@@dots@{@}} wherever you wish but usually
1062within a sentence. (@code{@@dots@{@}} creates dots @dots{})@refill
1063
1064@item
1065Write a command such as @code{@@code@{@var{sample-code}@}} wherever you
1066wish (but usually within a sentence) with its argument,
1067@var{sample-code} in this example, between the braces. (@code{@@code}
1068marks text as being code.)@refill
1069
1070@item
1071Write a command such as @code{@@example} on a line of its own; write the
1072body-text on following lines; and write the matching @code{@@end}
1073command, @code{@@end example} in this case, at the on a line of its own
1074after the body-text. (@code{@@example} @dots{} @code{@@end example}
1075indents and typesets body-text as an example.) It's usually ok to
1076indent environment commands like this, but in complicated and
1077hard-to-define circumstances the extra spaces cause extra space to
1078appear in the output, so beware.
1079@end itemize
1080
1081@noindent
1082@cindex Braces, when to use
1083As a general rule, a command requires braces if it mingles among other
1084text; but it does not need braces if it starts a line of its own. The
1085non-alphabetic commands, such as @code{@@:}, are exceptions to the rule;
1086they do not need braces.@refill
1087
1088As you gain experience with Texinfo, you will rapidly learn how to
1089write the different commands: the different ways to write commands
1090make it easier to write and read Texinfo files than if all commands
1091followed exactly the same syntax. (For details about @@-command
1092syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill
1093
1094
|
1070@node Conventions, Comments, Formatting Commands, Overview
| 1095@node Conventions
|
1071@section General Syntactic Conventions
1072@cindex General syntactic conventions
1073@cindex Syntactic conventions
1074@cindex Conventions, syntactic
1075
1076This section describes the general conventions used in all Texinfo documents.
1077
1078@itemize @bullet
1079@item
1080All printable @sc{ascii} characters except @samp{@@}, @samp{@{} and
1081@samp{@}} can appear in a Texinfo file and stand for themselves.
| 1096@section General Syntactic Conventions
1097@cindex General syntactic conventions
1098@cindex Syntactic conventions
1099@cindex Conventions, syntactic
1100
1101This section describes the general conventions used in all Texinfo documents.
1102
1103@itemize @bullet
1104@item
1105All printable @sc{ascii} characters except @samp{@@}, @samp{@{} and
1106@samp{@}} can appear in a Texinfo file and stand for themselves.
|
1082@samp{@@} is the escape character which introduces commands.
1083@samp{@{} and @samp{@}} should be used only to surround arguments to
1084certain commands. To put one of these special characters into the
1085document, put an @samp{@@} character in front of it, like this:
1086@samp{@@@@}, @samp{@@@{}, and @samp{@@@}}.@refill
| 1107@samp{@@} is the escape character which introduces commands, while
1108@samp{@{} and @samp{@}} are used to surround arguments to certain
1109commands. To put one of these special characters into the document, put
1110an @samp{@@} character in front of it, like this: @samp{@@@@},
1111@samp{@@@{}, and @samp{@@@}}.
|
1087
1088@item
| 1112
1113@item
|
1089@ifinfo
| |
1090It is customary in @TeX{} to use doubled single-quote characters to
| 1114It is customary in @TeX{} to use doubled single-quote characters to
|
1091begin and end quotations: ` ` and ' ' (but without a space between the
1092two single-quote characters). This convention should be followed in
1093Texinfo files. @TeX{} converts doubled single-quote characters to
1094left- and right-hand doubled quotation marks and Info converts doubled
1095single-quote characters to @sc{ascii} double-quotes: ` ` and ' ' to " .@refill
1096@end ifinfo
1097@iftex
1098It is customary in @TeX{} to use doubled single-quote characters to
1099begin and end quotations: @w{@t{ `` }} and @w{@t{ '' }}. This
| 1115begin and end quotations: @w{@t{`@w{}`@dots{}'@w{}'}}. This
|
1100convention should be followed in Texinfo files. @TeX{} converts
| 1116convention should be followed in Texinfo files. @TeX{} converts
|
1101doubled single-quote characters to left- and right-hand doubled
1102quotation marks, ``like this'', and Info converts doubled single-quote
1103characters to @sc{ascii} double-quotes: @w{@t{ `` }} and
1104@w{@t{ '' }} to @w{@t{ " }}.@refill
| 1117two single quotes to left- and right-hand doubled
1118quotation marks,
1119@c this comes out as "like this" in Info, of course, which is just confusing.
1120@iftex
1121``like this'',
|
1105@end iftex
| 1122@end iftex
|
| 1123and Info converts doubled single-quote characters to @sc{ascii}
1124double-quotes: @w{@t{`@w{}`@dots{}'@w{}'}} becomes @w{@t{"@dots{}"}}.
|
1106
1107@item
1108Use three hyphens in a row, @samp{---}, for a dash---like this. In
1109@TeX{}, a single or double hyphen produces a printed dash that is
1110shorter than the usual typeset dash. Info reduces three hyphens to two
1111for display on the screen.
1112
1113@item
1114To prevent a paragraph from being indented in the printed manual, put
1115the command @code{@@noindent} on a line by itself before the
| 1125
1126@item
1127Use three hyphens in a row, @samp{---}, for a dash---like this. In
1128@TeX{}, a single or double hyphen produces a printed dash that is
1129shorter than the usual typeset dash. Info reduces three hyphens to two
1130for display on the screen.
1131
1132@item
1133To prevent a paragraph from being indented in the printed manual, put
1134the command @code{@@noindent} on a line by itself before the
|
1116paragraph.@refill
| 1135paragraph.
|
1117
1118@item
1119If you mark off a region of the Texinfo file with the @code{@@iftex}
1120and @w{@code{@@end iftex}} commands, that region will appear only in
1121the printed copy; in that region, you can use certain commands
| 1136
1137@item
1138If you mark off a region of the Texinfo file with the @code{@@iftex}
1139and @w{@code{@@end iftex}} commands, that region will appear only in
1140the printed copy; in that region, you can use certain commands
|
1122borrowed from plain @TeX{} that you cannot use in Info. Likewise, if
1123you mark off a region with the @code{@@ifinfo} and @code{@@end ifinfo}
1124commands, that region will appear only in the Info file; in that
1125region, you can use Info commands that you cannot use in @TeX{}.
1126Similarly for @code{@@ifhtml @dots{} @@end ifhtml},
1127@code{@@ifnothtml @dots{} @@end ifnothtml},
1128@code{@@ifnotinfo @dots{} @@end ifnotinfo},
1129@code{@@ifnottex @dots{} @@end ifnottex}.
1130@xref{Conditionals}.
| 1141borrowed from plain @TeX{} that you cannot use in Info. Conversely,
1142text surrounded by @code{@@ifnottex} and @code{@@end ifnottex} will
1143appear in all output formats @emph{except} @TeX{}.
1144
1145Each of the other output formats (@code{html}, @code{info},
1146@code{plaintext}) have an analogous pair of commands. @xref{Conditionals}.
|
1131@end itemize
1132
1133@cindex Tabs; don't use!
1134@quotation
| 1147@end itemize
1148
1149@cindex Tabs; don't use!
1150@quotation
|
1135@strong{Caution:} Do not use tabs in a Texinfo file (except in verbatim
1136modes) ! @TeX{} uses variable-width fonts, which means that it is
1137impractical at best to define a tab to work in all circumstances.
| 1151@strong{Caution:} Do not use tab characters in a Texinfo file (except in
1152verbatim modes)! @TeX{} uses variable-width fonts, which means that it
1153is impractical at best to define a tab to work in all circumstances.
|
1138Consequently, @TeX{} treats tabs like single spaces, and that is not
1139what they look like. Furthermore, @code{makeinfo} does nothing special
1140with tabs, and thus a tab character in your input file may appear
| 1154Consequently, @TeX{} treats tabs like single spaces, and that is not
1155what they look like. Furthermore, @code{makeinfo} does nothing special
1156with tabs, and thus a tab character in your input file may appear
|
1141differently in the output, for example, in an indented example.
| 1157differently in the output, for example, in indented text.
|
1142
1143@noindent
1144To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple
1145spaces when you press the @key{TAB} key.
1146
1147@noindent
1148Also, you can run @code{untabify} in Emacs to convert tabs in a region
1149to multiple spaces.
1150@end quotation
1151
1152
| 1158
1159@noindent
1160To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple
1161spaces when you press the @key{TAB} key.
1162
1163@noindent
1164Also, you can run @code{untabify} in Emacs to convert tabs in a region
1165to multiple spaces.
1166@end quotation
1167
1168
|
1153@node Comments, Minimum, Conventions, Overview
| 1169@node Comments
|
1154@section Comments
1155
| 1170@section Comments
1171
|
| 1172@cindex Comments
1173@findex comment
1174@findex c @r{(comment)}
1175
|
1156You can write comments in a Texinfo file that will not appear in
1157either the Info file or the printed manual by using the
1158@code{@@comment} command (which may be abbreviated to @code{@@c}).
1159Such comments are for the person who revises the Texinfo file. All the
1160text on a line that follows either @code{@@comment} or @code{@@c} is a
1161comment; the rest of the line does not appear in either the Info file
| 1176You can write comments in a Texinfo file that will not appear in
1177either the Info file or the printed manual by using the
1178@code{@@comment} command (which may be abbreviated to @code{@@c}).
1179Such comments are for the person who revises the Texinfo file. All the
1180text on a line that follows either @code{@@comment} or @code{@@c} is a
1181comment; the rest of the line does not appear in either the Info file
|
1162or the printed manual. (Often, you can write the @code{@@comment} or
1163@code{@@c} in the middle of a line, and only the text that follows after
1164the @code{@@comment} or @code{@@c} command does not appear; but some
1165commands, such as @code{@@settitle} and @code{@@setfilename}, work on a
1166whole line. You cannot use @code{@@comment} or @code{@@c} in a line
1167beginning with such a command.)@refill
1168@cindex Comments
1169@findex comment
1170@findex c @r{(comment)}
| 1182or the printed manual.
|
1171
| 1183
|
| 1184Often, you can write the @code{@@comment} or @code{@@c} in the middle of
1185a line, and only the text that follows after the @code{@@comment} or
1186@code{@@c} command does not appear; but some commands, such as
1187@code{@@settitle} and @code{@@setfilename}, work on a whole line. You
1188cannot use @code{@@comment} or @code{@@c} in a line beginning with such
1189a command.
1190
1191@cindex Ignored text
1192@cindex Unprocessed text
1193@findex ignore
|
1172You can write long stretches of text that will not appear in either
1173the Info file or the printed manual by using the @code{@@ignore} and
1174@code{@@end ignore} commands. Write each of these commands on a line
1175of its own, starting each command at the beginning of the line. Text
1176between these two commands does not appear in the processed output.
1177You can use @code{@@ignore} and @code{@@end ignore} for writing
1178comments.
1179
| 1194You can write long stretches of text that will not appear in either
1195the Info file or the printed manual by using the @code{@@ignore} and
1196@code{@@end ignore} commands. Write each of these commands on a line
1197of its own, starting each command at the beginning of the line. Text
1198between these two commands does not appear in the processed output.
1199You can use @code{@@ignore} and @code{@@end ignore} for writing
1200comments.
1201
|
1180@cindex Ignored text
1181@cindex Unprocessed text
1182@findex ignore
1183@c !!! Perhaps include this comment about ignore and ifset:
1184@ignore
| |
1185Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or
1186@code{@@ifclear} conditions is ignored in the sense that it will not
1187contribute to the formatted output. However, @TeX{} and makeinfo must
| 1202Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or
1203@code{@@ifclear} conditions is ignored in the sense that it will not
1204contribute to the formatted output. However, @TeX{} and makeinfo must
|
1188still parse the ignored text, in order to understand when to
1189@emph{stop} ignoring text from the source file; that means that you
1190will still get error messages if you have invalid Texinfo markup
1191within ignored text.
1192@end ignore
| 1205still parse the ignored text, in order to understand when to @emph{stop}
1206ignoring text from the source file; that means that you may still get
1207error messages if you have invalid Texinfo commands within ignored text.
|
1193
1194
| 1208
1209
|
1195@node Minimum, Six Parts, Comments, Overview
| 1210@node Minimum
|
1196@section What a Texinfo File Must Have
1197@cindex Minimal Texinfo file (requirements)
1198@cindex Must have in Texinfo file
1199@cindex Required in Texinfo file
1200@cindex Texinfo file minimum
1201
| 1211@section What a Texinfo File Must Have
1212@cindex Minimal Texinfo file (requirements)
1213@cindex Must have in Texinfo file
1214@cindex Required in Texinfo file
1215@cindex Texinfo file minimum
1216
|
1202By convention, the names of Texinfo files end with one of the
1203extensions @file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}.
1204The longer extension is preferred since it describes more clearly to a
1205human reader the nature of the file. The shorter extensions are for
1206operating systems that cannot handle long file names.@refill
| 1217By convention, the namea of a Texinfo file ends with (in order of
1218preference) one of the extensions @file{.texinfo}, @file{.texi},
1219@file{.txi}, or @file{.tex}. The longer extensions are preferred since
1220they describe more clearly to a human reader the nature of the file.
1221The shorter extensions are for operating systems that cannot handle long
1222file names.
|
1207
1208In order to be made into a printed manual and an Info file, a Texinfo
| 1223
1224In order to be made into a printed manual and an Info file, a Texinfo
|
1209file @strong{must} begin with lines like this:@refill
| 1225file @strong{must} begin with lines like this:
|
1210
1211@example
1212@group
1213\input texinfo
1214@@setfilename @var{info-file-name}
1215@@settitle @var{name-of-manual}
1216@end group
1217@end example
1218
1219@noindent
| 1226
1227@example
1228@group
1229\input texinfo
1230@@setfilename @var{info-file-name}
1231@@settitle @var{name-of-manual}
1232@end group
1233@end example
1234
1235@noindent
|
1220The contents of the file follow this beginning, and then you @strong{must} end
1221a Texinfo file with a line like this:@refill
| 1236The contents of the file follow this beginning, and then you
1237@strong{must} end a Texinfo file with a line like this:
|
1222
1223@example
1224@@bye
1225@end example
1226
| 1238
1239@example
1240@@bye
1241@end example
1242
|
1227@findex input @r{(@TeX{} command)}
| 1243@findex \input @r{(raw @TeX{} startup)}
|
1228@noindent
| 1244@noindent
|
| 1245Here's an explanation:
1246
1247@itemize @bullet
1248@item
|
1229The @samp{\input texinfo} line tells @TeX{} to use the
1230@file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo
1231@@-commands into @TeX{} typesetting commands. (Note the use of the
| 1249The @samp{\input texinfo} line tells @TeX{} to use the
1250@file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo
1251@@-commands into @TeX{} typesetting commands. (Note the use of the
|
1232backslash, @samp{\}; this is correct for @TeX{}.) The
1233@samp{@@setfilename} line provides a name for the Info file and tells
1234@TeX{} to open auxiliary files. The @samp{@@settitle} line specifies a
1235title for the page headers (or footers) of the printed manual, and the
1236default document description title for the @samp{<head>} in HTML format.
| 1252backslash, @samp{\}; this is correct for @TeX{}.)
|
1237
| 1253
|
| 1254@item
1255The @code{@@setfilename} line provides a name for the Info file and
1256tells @TeX{} to open auxiliary files. @strong{All text before
1257@code{@@setfilename} is ignored!}
1258
1259@item
1260The @code{@@settitle} line specifies a title for the page headers (or
1261footers) of the printed manual, and the default document description for
1262the @samp{<head>} in HTML format. Strictly speaking, @code{@@settitle}
1263is optional---if you don't mind your document being titled `Untitled'.
1264
1265@item
|
1238The @code{@@bye} line at the end of the file on a line of its own tells
| 1266The @code{@@bye} line at the end of the file on a line of its own tells
|
1239the formatters that the file is ended and to stop formatting.@refill
| 1267the formatters that the file is ended and to stop formatting.
|
1240
| 1268
|
1241Usually, you will not use quite such a spare format, but will include
| 1269@end itemize
1270
1271Typically, you will not use quite such a spare format, but will include
|
1242mode setting and start-of-header and end-of-header lines at the
| 1272mode setting and start-of-header and end-of-header lines at the
|
1243beginning of a Texinfo file, like this:@refill
| 1273beginning of a Texinfo file, like this:
|
1244
1245@example
1246@group
1247\input texinfo @@c -*-texinfo-*-
1248@@c %**start of header
1249@@setfilename @var{info-file-name}
1250@@settitle @var{name-of-manual}
1251@@c %**end of header
1252@end group
1253@end example
1254
1255@noindent
1256In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into
1257Texinfo mode when you edit the file.
1258
| 1274
1275@example
1276@group
1277\input texinfo @@c -*-texinfo-*-
1278@@c %**start of header
1279@@setfilename @var{info-file-name}
1280@@settitle @var{name-of-manual}
1281@@c %**end of header
1282@end group
1283@end example
1284
1285@noindent
1286In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into
1287Texinfo mode when you edit the file.
1288
|
1259The @code{@@c} lines which surround the @samp{@@setfilename} and
1260@samp{@@settitle} lines are optional, but you need them in order to
1261run @TeX{} or Info on just part of the file. (@xref{Start of Header},
1262for more information.)@refill
| 1289The @code{@@c} lines which surround the @code{@@setfilename} and
1290@code{@@settitle} lines are optional, but you need them in order to
1291run @TeX{} or Info on just part of the file. (@xref{Start of Header}.)
|
1263
| 1292
|
1264Furthermore, you will usually provide a Texinfo file with a title
1265page, indices, and the like. But the minimum, which can be useful
1266for short documents, is just the three lines at the beginning and the
1267one line at the end.@refill
| 1293Furthermore, you will usually provide a Texinfo file with a title page,
1294indices, and the like, all of which are explained in this manual. But
1295the minimum, which can be useful for short documents, is just the three
1296lines at the beginning and the one line at the end.
|
1268
| 1297
|
1269@node Six Parts, Short Sample, Minimum, Overview
1270@comment node-name, next, previous, up
| 1298
1299@node Six Parts
|
1271@section Six Parts of a Texinfo File
1272
| 1300@section Six Parts of a Texinfo File
1301
|
1273Generally, a Texinfo file contains more than the minimal
1274beginning and end---it usually contains six parts:@refill
| 1302Generally, a Texinfo file contains more than the minimal beginning and
1303end described in the previous section---it usually contains the six
1304parts listed below. These are described fully in the following sections.
|
1275
1276@table @r
1277@item 1. Header
| 1305
1306@table @r
1307@item 1. Header
|
1278The @dfn{Header} names the file, tells @TeX{} which definitions' file to
1279use, and performs other ``housekeeping'' tasks.@refill
| 1308The @dfn{Header} names the file, tells @TeX{} which definitions file to
1309use, and other such housekeeping tasks.
|
1280
| 1310
|
1281@item 2. Summary Description and Copyright
1282The @dfn{Summary Description and Copyright} segment describes the document
1283and contains the copyright notice and copying permissions for the Info
1284file. The segment must be enclosed between @code{@@ifinfo} and
1285@code{@@end ifinfo} commands so that the formatters place it only in the Info
1286file.@refill
| 1311@item 2. Summary and Copyright
1312The @dfn{Summary and Copyright} segment describes the document and
1313contains the copyright notice and copying permissions. This is done
1314with the @code{@@copying} command.
|
1287
1288@item 3. Title and Copyright
| 1315
1316@item 3. Title and Copyright
|
1289The @dfn{Title and Copyright} segment contains the title and copyright pages
1290and copying permissions for the printed manual. The segment must be
1291enclosed between @code{@@titlepage} and @code{@@end titlepage} commands.
1292The title and copyright page appear only in the printed @w{manual}.@refill
| 1317The @dfn{Title and Copyright} segment contains the title and copyright
1318pages for the printed manual. The segment must be enclosed between
1319@code{@@titlepage} and @code{@@end titlepage} commands. The title and
1320copyright page appear only in the printed manual.
|
1293
1294@item 4. `Top' Node and Master Menu
| 1321
1322@item 4. `Top' Node and Master Menu
|
1295The @dfn{Master Menu} contains a complete menu of all the nodes in the whole
1296Info file. It appears only in the Info file, in the `Top' node.@refill
| 1323The `Top' node starts off the online output; it does not appear in the
1324printed manual. We recommend including the copying permissions here as
1325well as the segments above. And it contains at least a top-level menu
1326listing the chapters, and possibly a @dfn{Master Menu} listing all the
1327nodes in the entire document.
|
1297
1298@item 5. Body
| 1328
1329@item 5. Body
|
1299The @dfn{Body} of the document may be structured like a traditional book or
1300encyclopedia or it may be free form.@refill
| 1330The @dfn{Body} of the document is typically structured like a
1331traditional book or encyclopedia, but it may be free form.
|
1301
1302@item 6. End
| 1332
1333@item 6. End
|
1303The @dfn{End} contains commands for printing indices and generating
1304the table of contents, and the @code{@@bye} command on a line of its
1305own.@refill
| 1334The @dfn{End} segment contains commands for printing indices and
1335generating the table of contents, and the @code{@@bye} command on a line
1336of its own.
|
1306@end table
1307
| 1337@end table
1338
|
| 1339
|
1308@node Short Sample
1309@section A Short Sample Texinfo File
| 1340@node Short Sample
1341@section A Short Sample Texinfo File
|
1310@cindex Sample Texinfo file
| 1342@cindex Sample Texinfo file, with comments
|
1311
| 1343
|
1312Here is a complete but very short Texinfo file, in six parts. The first
1313three parts of the file, from @samp{\input texinfo} through to
1314@samp{@@end titlepage}, look more intimidating than they are. Most of
1315the material is standard boilerplate; when you write a manual, simply
1316insert the names for your own manual in this segment. (@xref{Beginning a
1317File}.)@refill
| 1344Here is a very short but complete Texinfo file, in the six conventional
1345parts enumerated in the previous section, so you can see how Texinfo
1346source appears in practice. The first three parts of the file, from
1347@samp{\input texinfo} through to @samp{@@end titlepage}, look more
1348intimidating than they are: most of the material is standard
1349boilerplate; when writing a manual, you simply change the names as
1350appropriate.
|
1318
| 1351
|
| 1352@xref{Beginning a File}, for full documentation on the commands listed
1353here. @xref{GNU Sample Texts}, for the full texts to be used in GNU manuals.
1354
|
1319In the following, the sample text is @emph{indented}; comments on it are
| 1355In the following, the sample text is @emph{indented}; comments on it are
|
1320not. The complete file, without any comments, is shown in
1321@ref{Sample Texinfo File}.
| 1356not. The complete file, without interspersed comments, is shown in
1357@ref{Short Sample Texinfo File}.
|
1322
1323@subheading Part 1: Header
1324
1325@noindent
1326The header does not appear in either the Info file or the
1327printed output. It sets various parameters, including the
1328name of the Info file and the title used in the header.
1329
1330@example
1331@group
1332\input texinfo @@c -*-texinfo-*-
1333@@c %**start of header
1334@@setfilename sample.info
| 1358
1359@subheading Part 1: Header
1360
1361@noindent
1362The header does not appear in either the Info file or the
1363printed output. It sets various parameters, including the
1364name of the Info file and the title used in the header.
1365
1366@example
1367@group
1368\input texinfo @@c -*-texinfo-*-
1369@@c %**start of header
1370@@setfilename sample.info
|
1335@@settitle Sample Document
1336@@setchapternewpage odd
| 1371@@settitle Sample Manual 1.0
|
1337@@c %**end of header
1338@end group
1339@end example
1340
1341@subheading Part 2: Summary Description and Copyright
1342
1343@noindent
| 1372@@c %**end of header
1373@end group
1374@end example
1375
1376@subheading Part 2: Summary Description and Copyright
1377
1378@noindent
|
1344The summary description and copyright segment does not
1345appear in the printed document.
| 1379A real manual includes more text here, according to the license under
1380which it is distributed. @xref{GNU Sample Texts}.
|
1346
1347@example
1348@group
| 1381
1382@example
1383@group
|
1349@@ifinfo
1350This is a short example of a complete Texinfo file.
| 1384@@copying
1385This is a short example of a complete Texinfo file, version 1.0.
|
1351
1352Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
| 1386
1387Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
|
1353@@end ifinfo
| 1388@@end copying
|
1354@end group
1355@end example
1356
| 1389@end group
1390@end example
1391
|
1357@subheading Part 3: Titlepage and Copyright
| 1392@subheading Part 3: Titlepage, Contents, Copyright
|
1358
1359@noindent
| 1393
1394@noindent
|
1360The titlepage segment does not appear in the Info file.
| 1395The titlepage segment does not appear in the online output, only in the
1396printed manual. We use the @code{@@insertcopying} command to
1397include the permission text from the previous section, instead of
1398writing it out again; it is output on the back of the title page. The
1399@code{@@contents} command generates a table of contents.
|
1361
1362@example
1363@group
| 1400
1401@example
1402@group
|
1364@@contents
| |
1365@@titlepage
| 1403@@titlepage
|
1366@@sp 10
| |
1367@@title Sample Title
1368@end group
1369
1370@group
1371@@c The following two commands start the copyright page.
1372@@page
1373@@vskip 0pt plus 1filll
| 1404@@title Sample Title
1405@end group
1406
1407@group
1408@@c The following two commands start the copyright page.
1409@@page
1410@@vskip 0pt plus 1filll
|
1374Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
| 1411@@insertcopying
|
1375@@end titlepage
1376@end group
| 1412@@end titlepage
1413@end group
|
| 1414
1415@@c Output the table of contents at the beginning.
1416@@contents
|
1377@end example
1378
1379@subheading Part 4: `Top' Node and Master Menu
1380
1381@noindent
| 1417@end example
1418
1419@subheading Part 4: `Top' Node and Master Menu
1420
1421@noindent
|
1382The `Top' node contains the master menu for the Info file.
1383Since a printed manual uses a table of contents rather than
1384a menu, the master menu appears only in online output.
| 1422The `Top' node contains the master menu for the Info file. Since a
1423printed manual uses a table of contents rather than a menu, the master
1424menu appears only in online output. We also include the copying text
1425again for the benefit of online readers. And since the copying text
1426begins with a brief description of the manual, no other text is needed.
|
1385
1386@example
1387@group
1388@@ifnottex
1389@@node Top
1390@@end ifnottex
1391@end group
1392@end example
1393
1394@example
1395@group
| 1427
1428@example
1429@group
1430@@ifnottex
1431@@node Top
1432@@end ifnottex
1433@end group
1434@end example
1435
1436@example
1437@group
|
| 1438@@insertcopying
1439
|
1396@@menu
1397* First Chapter:: The first chapter is the
| 1440@@menu
1441* First Chapter:: The first chapter is the
|
1398 only chapter in this sample.
1399* Concept Index:: This index has two entries.
| 1442 only chapter in this sample.
1443* Index:: Complete index.
|
1400@@end menu
1401@end group
1402@end example
1403
| 1444@@end menu
1445@end group
1446@end example
1447
|
1404@subheading Part 5: The Body of the Document
| |
1405
| 1448
|
| 1449@subheading Part 5: The Body of the Document
1450
|
1406@noindent
1407The body segment contains all the text of the document, but not the
1408indices or table of contents. This example illustrates a node and a
| 1451@noindent
1452The body segment contains all the text of the document, but not the
1453indices or table of contents. This example illustrates a node and a
|
1409chapter containing an enumerated list.@refill
| 1454chapter containing an enumerated list.
|
1410
1411@example
1412@group
1413@@node First Chapter
1414@@chapter First Chapter
| 1455
1456@example
1457@group
1458@@node First Chapter
1459@@chapter First Chapter
|
1415@@cindex Chapter, first
| 1460
1461@@cindex chapter, first
|
1416@end group
1417
1418@group
| 1462@end group
1463
1464@group
|
1419This is the contents of the first chapter.
1420@@cindex Another sample index entry
| 1465This is the first chapter.
1466@@cindex index entry, another
|
1421@end group
1422
1423@group
1424Here is a numbered list.
1425
1426@@enumerate
1427@@item
1428This is the first item.
1429
1430@@item
1431This is the second item.
1432@@end enumerate
1433@end group
| 1467@end group
1468
1469@group
1470Here is a numbered list.
1471
1472@@enumerate
1473@@item
1474This is the first item.
1475
1476@@item
1477This is the second item.
1478@@end enumerate
1479@end group
|
1434
1435@group
1436The @@code@{makeinfo@} command transforms a Texinfo file
1437such as this into an Info file or other output;
1438@@TeX@ typesets it for a printed manual.
1439@end group
| |
1440@end example
1441
| 1480@end example
1481
|
| 1482
|
1442@subheading Part 6: The End of the Document
1443
1444@noindent
1445The end segment contains commands for generating an index in a node and
| 1483@subheading Part 6: The End of the Document
1484
1485@noindent
1486The end segment contains commands for generating an index in a node and
|
1446unnumbered chapter of its own, (usually) for generating the table of
1447contents, and the @code{@@bye} command that marks the end of the
1448document.@refill
| 1487unnumbered chapter of its own, and the @code{@@bye} command that marks
1488the end of the document.
|
1449
1450@example
1451@group
| 1489
1490@example
1491@group
|
1452@@node Concept Index
1453@@unnumbered Concept Index
| 1492@@node Index
1493@@unnumbered Index
|
1454@end group
1455
1456@group
1457@@printindex cp
1458
1459@@bye
1460@end group
1461@end example
1462
| 1494@end group
1495
1496@group
1497@@printindex cp
1498
1499@@bye
1500@end group
1501@end example
1502
|
1463@subheading The Results
| |
1464
| 1503
|
| 1504@subheading Some Results
1505
|
1465Here is what the contents of the first chapter of the sample look like:
1466
1467@sp 1
1468@need 700
1469@quotation
| 1506Here is what the contents of the first chapter of the sample look like:
1507
1508@sp 1
1509@need 700
1510@quotation
|
1470This is the contents of the first chapter.
| 1511This is the first chapter.
|
1471
1472Here is a numbered list.
1473
1474@enumerate
1475@item
1476This is the first item.
1477
1478@item
1479This is the second item.
1480@end enumerate
| 1512
1513Here is a numbered list.
1514
1515@enumerate
1516@item
1517This is the first item.
1518
1519@item
1520This is the second item.
1521@end enumerate
|
1481
1482The @code{makeinfo} and @code{texinfo-format-buffer}
1483commands transform a Texinfo file such as this into
1484an Info file; and @TeX{} typesets it for a printed
1485manual.
| |
1486@end quotation
1487
1488
1489@node History
1490@section History
1491
1492@cindex Stallman, Richard M.
1493@cindex Chassell, Robert J.
| 1522@end quotation
1523
1524
1525@node History
1526@section History
1527
1528@cindex Stallman, Richard M.
1529@cindex Chassell, Robert J.
|
| 1530@cindex Fox, Brian
|
1494@cindex Berry, Karl
1495Richard M.@: Stallman invented the Texinfo format, wrote the initial
| 1531@cindex Berry, Karl
1532Richard M.@: Stallman invented the Texinfo format, wrote the initial
|
1496processors, and created Edition 1.0 of this manual. @w{Robert J.@:
1497Chassell} greatly revised and extended the manual, starting with Edition
| 1533processors, and created Edition 1.0 of this manual. @w{Robert J.@:}
1534Chassell greatly revised and extended the manual, starting with Edition
|
14981.1. Brian Fox was responsible for the standalone Texinfo distribution
1499until version 3.8, and wrote the standalone @command{makeinfo} and
| 15351.1. Brian Fox was responsible for the standalone Texinfo distribution
1536until version 3.8, and wrote the standalone @command{makeinfo} and
|
1500@command{info}. Karl Berry has made the updates since Texinfo 3.8 and
1501subsequent releases, starting with Edition 2.22 of the manual.
| 1537@command{info} programs. Karl Berry has continued maintenance since
1538Texinfo 3.8 (manual edition 2.22).
|
1502
1503@cindex Pinard, Fran@,{c}ois
1504@cindex Zuhn, David D.
1505@cindex Weisshaus, Melissa
1506@cindex Zaretskii, Eli
1507@cindex Schwab, Andreas
1508@cindex Weinberg, Zack
| 1539
1540@cindex Pinard, Fran@,{c}ois
1541@cindex Zuhn, David D.
1542@cindex Weisshaus, Melissa
1543@cindex Zaretskii, Eli
1544@cindex Schwab, Andreas
1545@cindex Weinberg, Zack
|
1509Our thanks go out to all who helped improve this work, particularly to
1510Fran@,{c}ois Pinard and @w{David D.@: Zuhn}, who tirelessly recorded and
1511reported mistakes and obscurities; our special thanks go to Melissa
1512Weisshaus for her frequent and often tedious reviews of nearly similar
1513editions. The indefatigable Eli Zaretskii and Andreas Schwab have
1514provided patches beyond counting. Zack Weinberg did the impossible by
1515implementing the macro syntax in @file{texinfo.tex}. Dozens of others
1516have contributed patches and suggestions, they are gratefully
1517acknowledged in the @file{ChangeLog} file. Our mistakes are our own.
| 1546Our thanks go out to all who helped improve this work, particularly the
1547indefatigable Eli Zaretskii and Andreas Schwab, who have provided
1548patches beyond counting. Fran@,{c}ois Pinard and @w{David D.@: Zuhn},
1549tirelessly recorded and reported mistakes and obscurities. Zack
1550Weinberg did the impossible by implementing the macro syntax in
1551@file{texinfo.tex}. Special thanks go to Melissa Weisshaus for her
1552frequent reviews of nearly similar editions. Dozens of others have
1553contributed patches and suggestions, they are gratefully acknowledged in
1554the @file{ChangeLog} file. Our mistakes are our own.
|
1518
1519@cindex Scribe
1520@cindex Reid, Brian
1521@cindex History of Texinfo
| 1555
1556@cindex Scribe
1557@cindex Reid, Brian
1558@cindex History of Texinfo
|
| 1559@cindex Texinfo history
|
1522A bit of history: in the 1970's at CMU, Brian Reid developed a program
1523and format named Scribe to mark up documents for printing. It used the
| 1560A bit of history: in the 1970's at CMU, Brian Reid developed a program
1561and format named Scribe to mark up documents for printing. It used the
|
1524@code{@@} character to introduce commands as Texinfo does and strived to
1525describe document contents rather than formatting.
| 1562@code{@@} character to introduce commands, as Texinfo does. Much more
1563consequentially, it strived to describe document contents rather than
1564formatting, an idea wholeheartedly adopted by Texinfo.
|
1526
1527@cindex Bolio
1528@cindex Bo@TeX{}
1529Meanwhile, people at MIT developed another, not too dissimilar format
1530called Bolio. This then was converted to using @TeX{} as its typesetting
| 1565
1566@cindex Bolio
1567@cindex Bo@TeX{}
1568Meanwhile, people at MIT developed another, not too dissimilar format
1569called Bolio. This then was converted to using @TeX{} as its typesetting
|
1531language: Bo@TeX{}.
| 1570language: Bo@TeX{}. The earliest Bo@TeX{} version seems to have been
15710.02 on October 31, 1984.
|
1532
1533Bo@TeX{} could only be used as a markup language for documents to be
1534printed, not for online documents. Richard Stallman (RMS) worked on
1535both Bolio and Bo@TeX{}. He also developed a nifty on-line help format
1536called Info, and then combined Bo@TeX{} and Info to create Texinfo, a
| 1572
1573Bo@TeX{} could only be used as a markup language for documents to be
1574printed, not for online documents. Richard Stallman (RMS) worked on
1575both Bolio and Bo@TeX{}. He also developed a nifty on-line help format
1576called Info, and then combined Bo@TeX{} and Info to create Texinfo, a
|
1537mark up language for text that is intended to be read both on line and
| 1577mark up language for text that is intended to be read both online and
|
1538as printed hard copy.
1539
1540
| 1578as printed hard copy.
1579
1580
|
1541
| |
1542@node Texinfo Mode
1543@chapter Using Texinfo Mode
1544@cindex Texinfo mode
1545@cindex Mode, using Texinfo
1546@cindex GNU Emacs
1547@cindex Emacs
1548
1549You may edit a Texinfo file with any text editor you choose. A Texinfo
1550file is no different from any other @sc{ascii} file. However, GNU Emacs
| 1581@node Texinfo Mode
1582@chapter Using Texinfo Mode
1583@cindex Texinfo mode
1584@cindex Mode, using Texinfo
1585@cindex GNU Emacs
1586@cindex Emacs
1587
1588You may edit a Texinfo file with any text editor you choose. A Texinfo
1589file is no different from any other @sc{ascii} file. However, GNU Emacs
|
1551comes with a special mode, called Texinfo
1552mode, that provides Emacs commands and tools to help ease your work.@refill
| 1590comes with a special mode, called Texinfo mode, that provides Emacs
1591commands and tools to help ease your work.
|
1553
1554This chapter describes features of GNU Emacs' Texinfo mode but not any
| 1592
1593This chapter describes features of GNU Emacs' Texinfo mode but not any
|
1555features of the Texinfo formatting language. If you are reading this
| 1594features of the Texinfo formatting language. So if you are reading this
|
1556manual straight through from the beginning, you may want to skim through
1557this chapter briefly and come back to it after reading succeeding
| 1595manual straight through from the beginning, you may want to skim through
1596this chapter briefly and come back to it after reading succeeding
|
1558chapters which describe the Texinfo formatting language in
1559detail.@refill
| 1597chapters which describe the Texinfo formatting language in detail.
|
1560
1561@menu
1562* Texinfo Mode Overview:: How Texinfo mode can help you.
1563* Emacs Editing:: Texinfo mode adds to GNU Emacs' general
1564 purpose editing features.
1565* Inserting:: How to insert frequently used @@-commands.
1566* Showing the Structure:: How to show the structure of a file.
1567* Updating Nodes and Menus:: How to update or create new nodes and menus.
1568* Info Formatting:: How to format for Info.
1569* Printing:: How to format and print part or all of a file.
1570* Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
1571@end menu
1572
1573@node Texinfo Mode Overview, Emacs Editing, Texinfo Mode, Texinfo Mode
1574@ifinfo
1575@heading Texinfo Mode Overview
1576@end ifinfo
1577
1578Texinfo mode provides special features for working with Texinfo
1579files.
1580You can:@refill
1581
1582@itemize @bullet
1583@item
1584Insert frequently used @@-commands. @refill
1585
1586@item
1587Automatically create @code{@@node} lines.
1588
1589@item
1590Show the structure of a Texinfo source file.@refill
1591
1592@item
1593Automatically create or update the `Next',
1594`Previous', and `Up' pointers of a node.
1595
1596@item
1597Automatically create or update menus.@refill
1598
1599@item
1600Automatically create a master menu.@refill
1601
1602@item
1603Format a part or all of a file for Info.@refill
1604
1605@item
1606Typeset and print part or all of a file.@refill
1607@end itemize
1608
1609Perhaps the two most helpful features are those for inserting frequently
1610used @@-commands and for creating node pointers and menus.@refill
1611
1612@node Emacs Editing, Inserting, Texinfo Mode Overview, Texinfo Mode
1613@section The Usual GNU Emacs Editing Commands
1614
1615In most cases, the usual Text mode commands work the same in Texinfo
1616mode as they do in Text mode. Texinfo mode adds new editing commands
1617and tools to GNU Emacs' general purpose editing features. The major
1618difference concerns filling. In Texinfo mode, the paragraph
1619separation variable and syntax table are redefined so that Texinfo
1620commands that should be on lines of their own are not inadvertently
1621included in paragraphs. Thus, the @kbd{M-q} (@code{fill-paragraph})
1622command will refill a paragraph but not mix an indexing command on a
1623line adjacent to it into the paragraph.@refill
1624
1625In addition, Texinfo mode sets the @code{page-delimiter} variable to
1626the value of @code{texinfo-chapter-level-regexp}; by default, this is
1627a regular expression matching the commands for chapters and their
1628equivalents, such as appendices. With this value for the page
1629delimiter, you can jump from chapter title to chapter title with the
1630@kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [}
1631(@code{backward-page}) commands and narrow to a chapter with the
1632@kbd{C-x p} (@code{narrow-to-page}) command. (@xref{Pages, , ,emacs,
1633The GNU Emacs Manual}, for details about the page commands.)@refill
1634
1635You may name a Texinfo file however you wish, but the convention is to
1636end a Texinfo file name with one of the extensions
1637@file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}. A longer
1638extension is preferred, since it is explicit, but a shorter extension
1639may be necessary for operating systems that limit the length of file
1640names. GNU Emacs automatically enters Texinfo mode when you visit a
1641file with a @file{.texinfo}, @file{.texi} or @file{.txi}
1642extension. Also, Emacs switches to Texinfo mode
1643when you visit a
1644file that has @samp{-*-texinfo-*-} in its first line. If ever you are
1645in another mode and wish to switch to Texinfo mode, type @code{M-x
1646texinfo-mode}.@refill
1647
1648Like all other Emacs features, you can customize or enhance Texinfo
1649mode as you wish. In particular, the keybindings are very easy to
1650change. The keybindings described here are the default or standard
1651ones.@refill
1652
1653@node Inserting, Showing the Structure, Emacs Editing, Texinfo Mode
1654@comment node-name, next, previous, up
1655@section Inserting Frequently Used Commands
1656@cindex Inserting frequently used commands
1657@cindex Frequently used commands, inserting
1658@cindex Commands, inserting them
1659
1660Texinfo mode provides commands to insert various frequently used
1661@@-commands into the buffer. You can use these commands to save
1662keystrokes.@refill
1663
1664The insert commands are invoked by typing @kbd{C-c} twice and then the
1665first letter of the @@-command:@refill
1666
1667@table @kbd
1668@item C-c C-c c
1669@itemx M-x texinfo-insert-@@code
1670@findex texinfo-insert-@@code
1671Insert @code{@@code@{@}} and put the
1672cursor between the braces.@refill
1673
1674@item C-c C-c d
1675@itemx M-x texinfo-insert-@@dfn
1676@findex texinfo-insert-@@dfn
1677Insert @code{@@dfn@{@}} and put the
1678cursor between the braces.@refill
1679
1680@item C-c C-c e
1681@itemx M-x texinfo-insert-@@end
1682@findex texinfo-insert-@@end
1683Insert @code{@@end} and attempt to insert the correct following word,
1684such as @samp{example} or @samp{table}. (This command does not handle
1685nested lists correctly, but inserts the word appropriate to the
1686immediately preceding list.)@refill
1687
1688@item C-c C-c i
1689@itemx M-x texinfo-insert-@@item
1690@findex texinfo-insert-@@item
1691Insert @code{@@item} and put the
1692cursor at the beginning of the next line.@refill
1693
1694@item C-c C-c k
1695@itemx M-x texinfo-insert-@@kbd
1696@findex texinfo-insert-@@kbd
1697Insert @code{@@kbd@{@}} and put the
1698cursor between the braces.@refill
1699
1700@item C-c C-c n
1701@itemx M-x texinfo-insert-@@node
1702@findex texinfo-insert-@@node
1703Insert @code{@@node} and a comment line
1704listing the sequence for the `Next',
1705`Previous', and `Up' nodes.
1706Leave point after the @code{@@node}.@refill
1707
1708@item C-c C-c o
1709@itemx M-x texinfo-insert-@@noindent
1710@findex texinfo-insert-@@noindent
1711Insert @code{@@noindent} and put the
1712cursor at the beginning of the next line.@refill
1713
1714@item C-c C-c s
1715@itemx M-x texinfo-insert-@@samp
1716@findex texinfo-insert-@@samp
1717Insert @code{@@samp@{@}} and put the
1718cursor between the braces.@refill
1719
1720@item C-c C-c t
1721@itemx M-x texinfo-insert-@@table
1722@findex texinfo-insert-@@table
1723Insert @code{@@table} followed by a @key{SPC}
1724and leave the cursor after the @key{SPC}.@refill
1725
1726@item C-c C-c v
1727@itemx M-x texinfo-insert-@@var
1728@findex texinfo-insert-@@var
1729Insert @code{@@var@{@}} and put the
1730cursor between the braces.@refill
1731
1732@item C-c C-c x
1733@itemx M-x texinfo-insert-@@example
1734@findex texinfo-insert-@@example
1735Insert @code{@@example} and put the
1736cursor at the beginning of the next line.@refill
1737
1738@c M-@{ was the binding for texinfo-insert-braces;
1739@c in Emacs 19, backward-paragraph will take this binding.
1740@item C-c C-c @{
1741@itemx M-x texinfo-insert-braces
1742@findex texinfo-insert-braces
1743Insert @code{@{@}} and put the cursor between the braces.@refill
1744
1745@item C-c C-c @}
1746@itemx C-c C-c ]
1747@itemx M-x up-list
1748@findex up-list
1749Move from between a pair of braces forward past the closing brace.
1750Typing @kbd{C-c C-c ]} is easier than typing @kbd{C-c C-c @}}, which
1751is, however, more mnemonic; hence the two keybindings. (Also, you can
1752move out from between braces by typing @kbd{C-f}.)@refill
1753@end table
1754
1755To put a command such as @w{@code{@@code@{@dots{}@}}} around an
1756@emph{existing} word, position the cursor in front of the word and type
1757@kbd{C-u 1 C-c C-c c}. This makes it easy to edit existing plain text.
1758The value of the prefix argument tells Emacs how many words following
1759point to include between braces---@samp{1} for one word, @samp{2} for
1760two words, and so on. Use a negative argument to enclose the previous
1761word or words. If you do not specify a prefix argument, Emacs inserts
1762the @@-command string and positions the cursor between the braces. This
1763feature works only for those @@-commands that operate on a word or words
1764within one line, such as @code{@@kbd} and @code{@@var}.@refill
1765
1766This set of insert commands was created after analyzing the frequency
1767with which different @@-commands are used in the @cite{GNU Emacs
1768Manual} and the @cite{GDB Manual}. If you wish to add your own insert
1769commands, you can bind a keyboard macro to a key, use abbreviations,
1770or extend the code in @file{texinfo.el}.@refill
1771
1772@findex texinfo-start-menu-description
1773@cindex Menu description, start
1774@cindex Description for menu, start
1775@kbd{C-c C-c C-d} (@code{texinfo-start-menu-description}) is an insert
1776command that works differently from the other insert commands. It
1777inserts a node's section or chapter title in the space for the
1778description in a menu entry line. (A menu entry has three parts, the
1779entry name, the node name, and the description. Only the node name is
1780required, but a description helps explain what the node is about.
1781@xref{Menu Parts, , The Parts of a Menu}.)@refill
1782
1783To use @code{texinfo-start-menu-description}, position point in a menu
1784entry line and type @kbd{C-c C-c C-d}. The command looks for and copies
1785the title that goes with the node name, and inserts the title as a
1786description; it positions point at beginning of the inserted text so you
1787can edit it. The function does not insert the title if the menu entry
1788line already contains a description.@refill
1789
1790This command is only an aid to writing descriptions; it does not do the
1791whole job. You must edit the inserted text since a title tends to use
1792the same words as a node name but a useful description uses different
1793words.@refill
1794
1795@node Showing the Structure, Updating Nodes and Menus, Inserting, Texinfo Mode
1796@comment node-name, next, previous, up
1797@section Showing the Section Structure of a File
1798@cindex Showing the section structure of a file
1799@cindex Section structure of a file, showing it
1800@cindex Structure of a file, showing it
1801@cindex Outline of file structure, showing it
1802@cindex Contents-like outline of file structure
1803@cindex File section structure, showing it
1804@cindex Texinfo file section structure, showing it
1805
1806You can show the section structure of a Texinfo file by using the
1807@kbd{C-c C-s} command (@code{texinfo-show-structure}). This command
1808shows the section structure of a Texinfo file by listing the lines
1809that begin with the @@-commands for @code{@@chapter},
1810@code{@@section}, and the like. It constructs what amounts
1811to a table of contents. These lines are displayed in another buffer
1812called the @samp{*Occur*} buffer. In that buffer, you can position
1813the cursor over one of the lines and use the @kbd{C-c C-c} command
1814(@code{occur-mode-goto-occurrence}), to jump to the corresponding spot
1815in the Texinfo file.@refill
1816
1817@table @kbd
1818@item C-c C-s
1819@itemx M-x texinfo-show-structure
1820@findex texinfo-show-structure
1821Show the @code{@@chapter}, @code{@@section}, and such lines of a
1822Texinfo file.@refill
1823
1824@item C-c C-c
1825@itemx M-x occur-mode-goto-occurrence
1826@findex occur-mode-goto-occurrence
1827Go to the line in the Texinfo file corresponding to the line under the
1828cursor in the @file{*Occur*} buffer.@refill
1829@end table
1830
1831If you call @code{texinfo-show-structure} with a prefix argument by
1832typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the
1833@@-commands for @code{@@chapter}, @code{@@section}, and the like, but
1834also the @code{@@node} lines. You can use @code{texinfo-show-structure}
1835with a prefix argument to check whether the `Next', `Previous', and `Up'
1836pointers of an @code{@@node} line are correct.
1837
1838Often, when you are working on a manual, you will be interested only
1839in the structure of the current chapter. In this case, you can mark
1840off the region of the buffer that you are interested in by using the
1841@kbd{C-x n n} (@code{narrow-to-region}) command and
1842@code{texinfo-show-structure} will work on only that region. To see
1843the whole buffer again, use @w{@kbd{C-x n w}} (@code{widen}).
1844(@xref{Narrowing, , , emacs, The GNU Emacs Manual}, for more
1845information about the narrowing commands.)@refill
1846
1847@vindex page-delimiter
1848@cindex Page delimiter in Texinfo mode
1849In addition to providing the @code{texinfo-show-structure} command,
1850Texinfo mode sets the value of the page delimiter variable to match
1851the chapter-level @@-commands. This enables you to use the @kbd{C-x
1852]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page})
1853commands to move forward and backward by chapter, and to use the
1854@kbd{C-x p} (@code{narrow-to-page}) command to narrow to a chapter.
1855@xref{Pages, , , emacs, The GNU Emacs Manual}, for more information
1856about the page commands.@refill
1857
1858@node Updating Nodes and Menus, Info Formatting, Showing the Structure, Texinfo Mode
1859@comment node-name, next, previous, up
1860@section Updating Nodes and Menus
1861@cindex Updating nodes and menus
1862@cindex Create nodes, menus automatically
1863@cindex Insert nodes, menus automatically
1864@cindex Automatically insert nodes, menus
1865
1866Texinfo mode provides commands for automatically creating or updating
1867menus and node pointers. The commands are called ``update'' commands
1868because their most frequent use is for updating a Texinfo file after you
1869have worked on it; but you can use them to insert the `Next',
1870`Previous', and `Up' pointers into an @code{@@node} line that has none
1871and to create menus in a file that has none.
1872
1873If you do not use the updating commands, you need to write menus and
1874node pointers by hand, which is a tedious task.@refill
1875
1876@menu
1877* Updating Commands:: Five major updating commands.
1878* Updating Requirements:: How to structure a Texinfo file for
1879 using the updating command.
1880* Other Updating Commands:: How to indent descriptions, insert
1881 missing nodes lines, and update
1882 nodes in sequence.
1883@end menu
1884
1885@node Updating Commands, Updating Requirements, Updating Nodes and Menus, Updating Nodes and Menus
1886@ifinfo
1887@subheading The Updating Commands
1888@end ifinfo
1889
1890You can use the updating commands to:@refill
1891
1892@itemize @bullet
1893@item
1894insert or update the `Next', `Previous', and `Up' pointers of a
1895node,@refill
1896
1897@item
1898insert or update the menu for a section, and@refill
1899
1900@item
1901create a master menu for a Texinfo source file.@refill
1902@end itemize
1903
1904You can also use the commands to update all the nodes and menus in a
1905region or in a whole Texinfo file.@refill
1906
1907The updating commands work only with conventional Texinfo files, which
1908are structured hierarchically like books. In such files, a structuring
1909command line must follow closely after each @code{@@node} line, except
1910for the `Top' @code{@@node} line. (A @dfn{structuring command line} is
1911a line beginning with @code{@@chapter}, @code{@@section}, or other
1912similar command.)
1913
1914You can write the structuring command line on the line that follows
1915immediately after an @code{@@node} line or else on the line that
1916follows after a single @code{@@comment} line or a single
1917@code{@@ifinfo} line. You cannot interpose more than one line between
1918the @code{@@node} line and the structuring command line; and you may
1919interpose only an @code{@@comment} line or an @code{@@ifinfo} line.
1920
1921Commands which work on a whole buffer require that the `Top' node be
1922followed by a node with an @code{@@chapter} or equivalent-level command.
1923The menu updating commands will not create a main or master menu for a
1924Texinfo file that has only @code{@@chapter}-level nodes! The menu
1925updating commands only create menus @emph{within} nodes for lower level
1926nodes. To create a menu of chapters, you must provide a `Top'
1927node.
1928
1929The menu updating commands remove menu entries that refer to other Info
1930files since they do not refer to nodes within the current buffer. This
1931is a deficiency. Rather than use menu entries, you can use cross
1932references to refer to other Info files. None of the updating commands
1933affect cross references.@refill
1934
1935Texinfo mode has five updating commands that are used most often: two
1936are for updating the node pointers or menu of a single node (or a
1937region); two are for updating every node pointer and menu in a file;
1938and one, the @code{texinfo-master-menu} command, is for creating a
1939master menu for a complete file, and optionally, for updating every
1940node and menu in the whole Texinfo file.@refill
1941
1942The @code{texinfo-master-menu} command is the primary command:@refill
1943
1944@table @kbd
1945@item C-c C-u m
1946@itemx M-x texinfo-master-menu
1947@findex texinfo-master-menu
1948Create or update a master menu that includes all the other menus
1949(incorporating the descriptions from pre-existing menus, if
1950any).@refill
1951
1952With an argument (prefix argument, @kbd{C-u,} if interactive), first create or
1953update all the nodes and all the regular menus in the buffer before
1954constructing the master menu. (@xref{The Top Node, , The Top Node and
1955Master Menu}, for more about a master menu.)@refill
1956
1957For @code{texinfo-master-menu} to work, the Texinfo file must have a
1958`Top' node and at least one subsequent node.@refill
1959
1960After extensively editing a Texinfo file, you can type the following:
1961
1962@example
1963C-u M-x texinfo-master-menu
1964@exdent or
1965C-u C-c C-u m
1966@end example
1967
1968@noindent
1969This updates all the nodes and menus completely and all at once.@refill
1970@end table
1971
1972The other major updating commands do smaller jobs and are designed for
1973the person who updates nodes and menus as he or she writes a Texinfo
1974file.@refill
1975
1976@need 1000
1977The commands are:@refill
1978
1979@table @kbd
1980@item C-c C-u C-n
1981@itemx M-x texinfo-update-node
1982@findex texinfo-update-node
1983Insert the `Next', `Previous', and `Up' pointers for the node that point is
1984within (i.e., for the @code{@@node} line preceding point). If the
1985@code{@@node} line has pre-existing `Next', `Previous', or `Up'
1986pointers in it, the old pointers are removed and new ones inserted.
1987With an argument (prefix argument, @kbd{C-u}, if interactive), this command
1988updates all @code{@@node} lines in the region (which is the text
1989between point and mark).@refill
1990
1991@item C-c C-u C-m
1992@itemx M-x texinfo-make-menu
1993@findex texinfo-make-menu
1994Create or update the menu in the node that point is within.
1995With an argument (@kbd{C-u} as prefix argument, if
1996interactive), the command makes or updates menus for the
1997nodes which are either within or a part of the
1998region.@refill
1999
2000Whenever @code{texinfo-make-menu} updates an existing menu, the
2001descriptions from that menu are incorporated into the new menu. This
2002is done by copying descriptions from the existing menu to the entries
2003in the new menu that have the same node names. If the node names are
2004different, the descriptions are not copied to the new menu.@refill
2005
2006@item C-c C-u C-e
2007@itemx M-x texinfo-every-node-update
2008@findex texinfo-every-node-update
2009Insert or update the `Next', `Previous', and `Up' pointers for every
2010node in the buffer.@refill
2011
2012@item C-c C-u C-a
2013@itemx M-x texinfo-all-menus-update
2014@findex texinfo-all-menus-update
2015Create or update all the menus in the buffer. With an argument
2016(@kbd{C-u} as prefix argument, if interactive), first insert
2017or update all the node
2018pointers before working on the menus.@refill
2019
2020If a master menu exists, the @code{texinfo-all-menus-update} command
2021updates it; but the command does not create a new master menu if none
2022already exists. (Use the @code{texinfo-master-menu} command for
2023that.)@refill
2024
2025When working on a document that does not merit a master menu, you can
2026type the following:
2027
2028@example
2029C-u C-c C-u C-a
2030@exdent or
2031C-u M-x texinfo-all-menus-update
2032@end example
2033
2034@noindent
2035This updates all the nodes and menus.@refill
2036@end table
2037
2038The @code{texinfo-column-for-description} variable specifies the
2039column to which menu descriptions are indented. By default, the value
2040is 32 although it is often useful to reduce it to as low as 24. You
2041can set the variable with the @kbd{M-x edit-options} command
2042(@pxref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs
2043Manual}) or with the @kbd{M-x set-variable} command (@pxref{Examining,
2044, Examining and Setting Variables, emacs, The GNU Emacs
2045Manual}).@refill
2046
2047Also, the @code{texinfo-indent-menu-description} command may be used to
2048indent existing menu descriptions to a specified column. Finally, if
2049you wish, you can use the @code{texinfo-insert-node-lines} command to
2050insert missing @code{@@node} lines into a file. (@xref{Other Updating
2051Commands}, for more information.)@refill
2052
| 1598
1599@menu
1600* Texinfo Mode Overview:: How Texinfo mode can help you.
1601* Emacs Editing:: Texinfo mode adds to GNU Emacs' general
1602 purpose editing features.
1603* Inserting:: How to insert frequently used @@-commands.
1604* Showing the Structure:: How to show the structure of a file.
1605* Updating Nodes and Menus:: How to update or create new nodes and menus.
1606* Info Formatting:: How to format for Info.
1607* Printing:: How to format and print part or all of a file.
1608* Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
1609@end menu
1610
1611@node Texinfo Mode Overview, Emacs Editing, Texinfo Mode, Texinfo Mode
1612@ifinfo
1613@heading Texinfo Mode Overview
1614@end ifinfo
1615
1616Texinfo mode provides special features for working with Texinfo
1617files.
1618You can:@refill
1619
1620@itemize @bullet
1621@item
1622Insert frequently used @@-commands. @refill
1623
1624@item
1625Automatically create @code{@@node} lines.
1626
1627@item
1628Show the structure of a Texinfo source file.@refill
1629
1630@item
1631Automatically create or update the `Next',
1632`Previous', and `Up' pointers of a node.
1633
1634@item
1635Automatically create or update menus.@refill
1636
1637@item
1638Automatically create a master menu.@refill
1639
1640@item
1641Format a part or all of a file for Info.@refill
1642
1643@item
1644Typeset and print part or all of a file.@refill
1645@end itemize
1646
1647Perhaps the two most helpful features are those for inserting frequently
1648used @@-commands and for creating node pointers and menus.@refill
1649
1650@node Emacs Editing, Inserting, Texinfo Mode Overview, Texinfo Mode
1651@section The Usual GNU Emacs Editing Commands
1652
1653In most cases, the usual Text mode commands work the same in Texinfo
1654mode as they do in Text mode. Texinfo mode adds new editing commands
1655and tools to GNU Emacs' general purpose editing features. The major
1656difference concerns filling. In Texinfo mode, the paragraph
1657separation variable and syntax table are redefined so that Texinfo
1658commands that should be on lines of their own are not inadvertently
1659included in paragraphs. Thus, the @kbd{M-q} (@code{fill-paragraph})
1660command will refill a paragraph but not mix an indexing command on a
1661line adjacent to it into the paragraph.@refill
1662
1663In addition, Texinfo mode sets the @code{page-delimiter} variable to
1664the value of @code{texinfo-chapter-level-regexp}; by default, this is
1665a regular expression matching the commands for chapters and their
1666equivalents, such as appendices. With this value for the page
1667delimiter, you can jump from chapter title to chapter title with the
1668@kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [}
1669(@code{backward-page}) commands and narrow to a chapter with the
1670@kbd{C-x p} (@code{narrow-to-page}) command. (@xref{Pages, , ,emacs,
1671The GNU Emacs Manual}, for details about the page commands.)@refill
1672
1673You may name a Texinfo file however you wish, but the convention is to
1674end a Texinfo file name with one of the extensions
1675@file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}. A longer
1676extension is preferred, since it is explicit, but a shorter extension
1677may be necessary for operating systems that limit the length of file
1678names. GNU Emacs automatically enters Texinfo mode when you visit a
1679file with a @file{.texinfo}, @file{.texi} or @file{.txi}
1680extension. Also, Emacs switches to Texinfo mode
1681when you visit a
1682file that has @samp{-*-texinfo-*-} in its first line. If ever you are
1683in another mode and wish to switch to Texinfo mode, type @code{M-x
1684texinfo-mode}.@refill
1685
1686Like all other Emacs features, you can customize or enhance Texinfo
1687mode as you wish. In particular, the keybindings are very easy to
1688change. The keybindings described here are the default or standard
1689ones.@refill
1690
1691@node Inserting, Showing the Structure, Emacs Editing, Texinfo Mode
1692@comment node-name, next, previous, up
1693@section Inserting Frequently Used Commands
1694@cindex Inserting frequently used commands
1695@cindex Frequently used commands, inserting
1696@cindex Commands, inserting them
1697
1698Texinfo mode provides commands to insert various frequently used
1699@@-commands into the buffer. You can use these commands to save
1700keystrokes.@refill
1701
1702The insert commands are invoked by typing @kbd{C-c} twice and then the
1703first letter of the @@-command:@refill
1704
1705@table @kbd
1706@item C-c C-c c
1707@itemx M-x texinfo-insert-@@code
1708@findex texinfo-insert-@@code
1709Insert @code{@@code@{@}} and put the
1710cursor between the braces.@refill
1711
1712@item C-c C-c d
1713@itemx M-x texinfo-insert-@@dfn
1714@findex texinfo-insert-@@dfn
1715Insert @code{@@dfn@{@}} and put the
1716cursor between the braces.@refill
1717
1718@item C-c C-c e
1719@itemx M-x texinfo-insert-@@end
1720@findex texinfo-insert-@@end
1721Insert @code{@@end} and attempt to insert the correct following word,
1722such as @samp{example} or @samp{table}. (This command does not handle
1723nested lists correctly, but inserts the word appropriate to the
1724immediately preceding list.)@refill
1725
1726@item C-c C-c i
1727@itemx M-x texinfo-insert-@@item
1728@findex texinfo-insert-@@item
1729Insert @code{@@item} and put the
1730cursor at the beginning of the next line.@refill
1731
1732@item C-c C-c k
1733@itemx M-x texinfo-insert-@@kbd
1734@findex texinfo-insert-@@kbd
1735Insert @code{@@kbd@{@}} and put the
1736cursor between the braces.@refill
1737
1738@item C-c C-c n
1739@itemx M-x texinfo-insert-@@node
1740@findex texinfo-insert-@@node
1741Insert @code{@@node} and a comment line
1742listing the sequence for the `Next',
1743`Previous', and `Up' nodes.
1744Leave point after the @code{@@node}.@refill
1745
1746@item C-c C-c o
1747@itemx M-x texinfo-insert-@@noindent
1748@findex texinfo-insert-@@noindent
1749Insert @code{@@noindent} and put the
1750cursor at the beginning of the next line.@refill
1751
1752@item C-c C-c s
1753@itemx M-x texinfo-insert-@@samp
1754@findex texinfo-insert-@@samp
1755Insert @code{@@samp@{@}} and put the
1756cursor between the braces.@refill
1757
1758@item C-c C-c t
1759@itemx M-x texinfo-insert-@@table
1760@findex texinfo-insert-@@table
1761Insert @code{@@table} followed by a @key{SPC}
1762and leave the cursor after the @key{SPC}.@refill
1763
1764@item C-c C-c v
1765@itemx M-x texinfo-insert-@@var
1766@findex texinfo-insert-@@var
1767Insert @code{@@var@{@}} and put the
1768cursor between the braces.@refill
1769
1770@item C-c C-c x
1771@itemx M-x texinfo-insert-@@example
1772@findex texinfo-insert-@@example
1773Insert @code{@@example} and put the
1774cursor at the beginning of the next line.@refill
1775
1776@c M-@{ was the binding for texinfo-insert-braces;
1777@c in Emacs 19, backward-paragraph will take this binding.
1778@item C-c C-c @{
1779@itemx M-x texinfo-insert-braces
1780@findex texinfo-insert-braces
1781Insert @code{@{@}} and put the cursor between the braces.@refill
1782
1783@item C-c C-c @}
1784@itemx C-c C-c ]
1785@itemx M-x up-list
1786@findex up-list
1787Move from between a pair of braces forward past the closing brace.
1788Typing @kbd{C-c C-c ]} is easier than typing @kbd{C-c C-c @}}, which
1789is, however, more mnemonic; hence the two keybindings. (Also, you can
1790move out from between braces by typing @kbd{C-f}.)@refill
1791@end table
1792
1793To put a command such as @w{@code{@@code@{@dots{}@}}} around an
1794@emph{existing} word, position the cursor in front of the word and type
1795@kbd{C-u 1 C-c C-c c}. This makes it easy to edit existing plain text.
1796The value of the prefix argument tells Emacs how many words following
1797point to include between braces---@samp{1} for one word, @samp{2} for
1798two words, and so on. Use a negative argument to enclose the previous
1799word or words. If you do not specify a prefix argument, Emacs inserts
1800the @@-command string and positions the cursor between the braces. This
1801feature works only for those @@-commands that operate on a word or words
1802within one line, such as @code{@@kbd} and @code{@@var}.@refill
1803
1804This set of insert commands was created after analyzing the frequency
1805with which different @@-commands are used in the @cite{GNU Emacs
1806Manual} and the @cite{GDB Manual}. If you wish to add your own insert
1807commands, you can bind a keyboard macro to a key, use abbreviations,
1808or extend the code in @file{texinfo.el}.@refill
1809
1810@findex texinfo-start-menu-description
1811@cindex Menu description, start
1812@cindex Description for menu, start
1813@kbd{C-c C-c C-d} (@code{texinfo-start-menu-description}) is an insert
1814command that works differently from the other insert commands. It
1815inserts a node's section or chapter title in the space for the
1816description in a menu entry line. (A menu entry has three parts, the
1817entry name, the node name, and the description. Only the node name is
1818required, but a description helps explain what the node is about.
1819@xref{Menu Parts, , The Parts of a Menu}.)@refill
1820
1821To use @code{texinfo-start-menu-description}, position point in a menu
1822entry line and type @kbd{C-c C-c C-d}. The command looks for and copies
1823the title that goes with the node name, and inserts the title as a
1824description; it positions point at beginning of the inserted text so you
1825can edit it. The function does not insert the title if the menu entry
1826line already contains a description.@refill
1827
1828This command is only an aid to writing descriptions; it does not do the
1829whole job. You must edit the inserted text since a title tends to use
1830the same words as a node name but a useful description uses different
1831words.@refill
1832
1833@node Showing the Structure, Updating Nodes and Menus, Inserting, Texinfo Mode
1834@comment node-name, next, previous, up
1835@section Showing the Section Structure of a File
1836@cindex Showing the section structure of a file
1837@cindex Section structure of a file, showing it
1838@cindex Structure of a file, showing it
1839@cindex Outline of file structure, showing it
1840@cindex Contents-like outline of file structure
1841@cindex File section structure, showing it
1842@cindex Texinfo file section structure, showing it
1843
1844You can show the section structure of a Texinfo file by using the
1845@kbd{C-c C-s} command (@code{texinfo-show-structure}). This command
1846shows the section structure of a Texinfo file by listing the lines
1847that begin with the @@-commands for @code{@@chapter},
1848@code{@@section}, and the like. It constructs what amounts
1849to a table of contents. These lines are displayed in another buffer
1850called the @samp{*Occur*} buffer. In that buffer, you can position
1851the cursor over one of the lines and use the @kbd{C-c C-c} command
1852(@code{occur-mode-goto-occurrence}), to jump to the corresponding spot
1853in the Texinfo file.@refill
1854
1855@table @kbd
1856@item C-c C-s
1857@itemx M-x texinfo-show-structure
1858@findex texinfo-show-structure
1859Show the @code{@@chapter}, @code{@@section}, and such lines of a
1860Texinfo file.@refill
1861
1862@item C-c C-c
1863@itemx M-x occur-mode-goto-occurrence
1864@findex occur-mode-goto-occurrence
1865Go to the line in the Texinfo file corresponding to the line under the
1866cursor in the @file{*Occur*} buffer.@refill
1867@end table
1868
1869If you call @code{texinfo-show-structure} with a prefix argument by
1870typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the
1871@@-commands for @code{@@chapter}, @code{@@section}, and the like, but
1872also the @code{@@node} lines. You can use @code{texinfo-show-structure}
1873with a prefix argument to check whether the `Next', `Previous', and `Up'
1874pointers of an @code{@@node} line are correct.
1875
1876Often, when you are working on a manual, you will be interested only
1877in the structure of the current chapter. In this case, you can mark
1878off the region of the buffer that you are interested in by using the
1879@kbd{C-x n n} (@code{narrow-to-region}) command and
1880@code{texinfo-show-structure} will work on only that region. To see
1881the whole buffer again, use @w{@kbd{C-x n w}} (@code{widen}).
1882(@xref{Narrowing, , , emacs, The GNU Emacs Manual}, for more
1883information about the narrowing commands.)@refill
1884
1885@vindex page-delimiter
1886@cindex Page delimiter in Texinfo mode
1887In addition to providing the @code{texinfo-show-structure} command,
1888Texinfo mode sets the value of the page delimiter variable to match
1889the chapter-level @@-commands. This enables you to use the @kbd{C-x
1890]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page})
1891commands to move forward and backward by chapter, and to use the
1892@kbd{C-x p} (@code{narrow-to-page}) command to narrow to a chapter.
1893@xref{Pages, , , emacs, The GNU Emacs Manual}, for more information
1894about the page commands.@refill
1895
1896@node Updating Nodes and Menus, Info Formatting, Showing the Structure, Texinfo Mode
1897@comment node-name, next, previous, up
1898@section Updating Nodes and Menus
1899@cindex Updating nodes and menus
1900@cindex Create nodes, menus automatically
1901@cindex Insert nodes, menus automatically
1902@cindex Automatically insert nodes, menus
1903
1904Texinfo mode provides commands for automatically creating or updating
1905menus and node pointers. The commands are called ``update'' commands
1906because their most frequent use is for updating a Texinfo file after you
1907have worked on it; but you can use them to insert the `Next',
1908`Previous', and `Up' pointers into an @code{@@node} line that has none
1909and to create menus in a file that has none.
1910
1911If you do not use the updating commands, you need to write menus and
1912node pointers by hand, which is a tedious task.@refill
1913
1914@menu
1915* Updating Commands:: Five major updating commands.
1916* Updating Requirements:: How to structure a Texinfo file for
1917 using the updating command.
1918* Other Updating Commands:: How to indent descriptions, insert
1919 missing nodes lines, and update
1920 nodes in sequence.
1921@end menu
1922
1923@node Updating Commands, Updating Requirements, Updating Nodes and Menus, Updating Nodes and Menus
1924@ifinfo
1925@subheading The Updating Commands
1926@end ifinfo
1927
1928You can use the updating commands to:@refill
1929
1930@itemize @bullet
1931@item
1932insert or update the `Next', `Previous', and `Up' pointers of a
1933node,@refill
1934
1935@item
1936insert or update the menu for a section, and@refill
1937
1938@item
1939create a master menu for a Texinfo source file.@refill
1940@end itemize
1941
1942You can also use the commands to update all the nodes and menus in a
1943region or in a whole Texinfo file.@refill
1944
1945The updating commands work only with conventional Texinfo files, which
1946are structured hierarchically like books. In such files, a structuring
1947command line must follow closely after each @code{@@node} line, except
1948for the `Top' @code{@@node} line. (A @dfn{structuring command line} is
1949a line beginning with @code{@@chapter}, @code{@@section}, or other
1950similar command.)
1951
1952You can write the structuring command line on the line that follows
1953immediately after an @code{@@node} line or else on the line that
1954follows after a single @code{@@comment} line or a single
1955@code{@@ifinfo} line. You cannot interpose more than one line between
1956the @code{@@node} line and the structuring command line; and you may
1957interpose only an @code{@@comment} line or an @code{@@ifinfo} line.
1958
1959Commands which work on a whole buffer require that the `Top' node be
1960followed by a node with an @code{@@chapter} or equivalent-level command.
1961The menu updating commands will not create a main or master menu for a
1962Texinfo file that has only @code{@@chapter}-level nodes! The menu
1963updating commands only create menus @emph{within} nodes for lower level
1964nodes. To create a menu of chapters, you must provide a `Top'
1965node.
1966
1967The menu updating commands remove menu entries that refer to other Info
1968files since they do not refer to nodes within the current buffer. This
1969is a deficiency. Rather than use menu entries, you can use cross
1970references to refer to other Info files. None of the updating commands
1971affect cross references.@refill
1972
1973Texinfo mode has five updating commands that are used most often: two
1974are for updating the node pointers or menu of a single node (or a
1975region); two are for updating every node pointer and menu in a file;
1976and one, the @code{texinfo-master-menu} command, is for creating a
1977master menu for a complete file, and optionally, for updating every
1978node and menu in the whole Texinfo file.@refill
1979
1980The @code{texinfo-master-menu} command is the primary command:@refill
1981
1982@table @kbd
1983@item C-c C-u m
1984@itemx M-x texinfo-master-menu
1985@findex texinfo-master-menu
1986Create or update a master menu that includes all the other menus
1987(incorporating the descriptions from pre-existing menus, if
1988any).@refill
1989
1990With an argument (prefix argument, @kbd{C-u,} if interactive), first create or
1991update all the nodes and all the regular menus in the buffer before
1992constructing the master menu. (@xref{The Top Node, , The Top Node and
1993Master Menu}, for more about a master menu.)@refill
1994
1995For @code{texinfo-master-menu} to work, the Texinfo file must have a
1996`Top' node and at least one subsequent node.@refill
1997
1998After extensively editing a Texinfo file, you can type the following:
1999
2000@example
2001C-u M-x texinfo-master-menu
2002@exdent or
2003C-u C-c C-u m
2004@end example
2005
2006@noindent
2007This updates all the nodes and menus completely and all at once.@refill
2008@end table
2009
2010The other major updating commands do smaller jobs and are designed for
2011the person who updates nodes and menus as he or she writes a Texinfo
2012file.@refill
2013
2014@need 1000
2015The commands are:@refill
2016
2017@table @kbd
2018@item C-c C-u C-n
2019@itemx M-x texinfo-update-node
2020@findex texinfo-update-node
2021Insert the `Next', `Previous', and `Up' pointers for the node that point is
2022within (i.e., for the @code{@@node} line preceding point). If the
2023@code{@@node} line has pre-existing `Next', `Previous', or `Up'
2024pointers in it, the old pointers are removed and new ones inserted.
2025With an argument (prefix argument, @kbd{C-u}, if interactive), this command
2026updates all @code{@@node} lines in the region (which is the text
2027between point and mark).@refill
2028
2029@item C-c C-u C-m
2030@itemx M-x texinfo-make-menu
2031@findex texinfo-make-menu
2032Create or update the menu in the node that point is within.
2033With an argument (@kbd{C-u} as prefix argument, if
2034interactive), the command makes or updates menus for the
2035nodes which are either within or a part of the
2036region.@refill
2037
2038Whenever @code{texinfo-make-menu} updates an existing menu, the
2039descriptions from that menu are incorporated into the new menu. This
2040is done by copying descriptions from the existing menu to the entries
2041in the new menu that have the same node names. If the node names are
2042different, the descriptions are not copied to the new menu.@refill
2043
2044@item C-c C-u C-e
2045@itemx M-x texinfo-every-node-update
2046@findex texinfo-every-node-update
2047Insert or update the `Next', `Previous', and `Up' pointers for every
2048node in the buffer.@refill
2049
2050@item C-c C-u C-a
2051@itemx M-x texinfo-all-menus-update
2052@findex texinfo-all-menus-update
2053Create or update all the menus in the buffer. With an argument
2054(@kbd{C-u} as prefix argument, if interactive), first insert
2055or update all the node
2056pointers before working on the menus.@refill
2057
2058If a master menu exists, the @code{texinfo-all-menus-update} command
2059updates it; but the command does not create a new master menu if none
2060already exists. (Use the @code{texinfo-master-menu} command for
2061that.)@refill
2062
2063When working on a document that does not merit a master menu, you can
2064type the following:
2065
2066@example
2067C-u C-c C-u C-a
2068@exdent or
2069C-u M-x texinfo-all-menus-update
2070@end example
2071
2072@noindent
2073This updates all the nodes and menus.@refill
2074@end table
2075
2076The @code{texinfo-column-for-description} variable specifies the
2077column to which menu descriptions are indented. By default, the value
2078is 32 although it is often useful to reduce it to as low as 24. You
2079can set the variable with the @kbd{M-x edit-options} command
2080(@pxref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs
2081Manual}) or with the @kbd{M-x set-variable} command (@pxref{Examining,
2082, Examining and Setting Variables, emacs, The GNU Emacs
2083Manual}).@refill
2084
2085Also, the @code{texinfo-indent-menu-description} command may be used to
2086indent existing menu descriptions to a specified column. Finally, if
2087you wish, you can use the @code{texinfo-insert-node-lines} command to
2088insert missing @code{@@node} lines into a file. (@xref{Other Updating
2089Commands}, for more information.)@refill
2090
|
2053@node Updating Requirements, Other Updating Commands, Updating Commands, Updating Nodes and Menus
2054@comment node-name, next, previous, up
| 2091@node Updating Requirements
|
2055@subsection Updating Requirements
2056@cindex Updating requirements
2057@cindex Requirements for updating commands
2058
2059To use the updating commands, you must organize the Texinfo file
2060hierarchically with chapters, sections, subsections, and the like.
2061When you construct the hierarchy of the manual, do not `jump down'
2062more than one level at a time: you can follow the `Top' node with a
2063chapter, but not with a section; you can follow a chapter with a
2064section, but not with a subsection. However, you may `jump up' any
2065number of levels at one time---for example, from a subsection to a
2066chapter.@refill
2067
2068Each @code{@@node} line, with the exception of the line for the `Top'
2069node, must be followed by a line with a structuring command such as
2070@code{@@chapter}, @code{@@section}, or
2071@code{@@unnumberedsubsec}.@refill
2072
2073Each @code{@@node} line/structuring-command line combination
| 2092@subsection Updating Requirements
2093@cindex Updating requirements
2094@cindex Requirements for updating commands
2095
2096To use the updating commands, you must organize the Texinfo file
2097hierarchically with chapters, sections, subsections, and the like.
2098When you construct the hierarchy of the manual, do not `jump down'
2099more than one level at a time: you can follow the `Top' node with a
2100chapter, but not with a section; you can follow a chapter with a
2101section, but not with a subsection. However, you may `jump up' any
2102number of levels at one time---for example, from a subsection to a
2103chapter.@refill
2104
2105Each @code{@@node} line, with the exception of the line for the `Top'
2106node, must be followed by a line with a structuring command such as
2107@code{@@chapter}, @code{@@section}, or
2108@code{@@unnumberedsubsec}.@refill
2109
2110Each @code{@@node} line/structuring-command line combination
|
2074must look either like this:@refill
| 2111must look either like this:
|
2075
2076@example
2077@group
2078@@node Comments, Minimum, Conventions, Overview
2079@@comment node-name, next, previous, up
2080@@section Comments
2081@end group
2082@end example
2083
2084or like this (without the @code{@@comment} line):
2085
2086@example
2087@group
2088@@node Comments, Minimum, Conventions, Overview
2089@@section Comments
2090@end group
2091@end example
2092
| 2112
2113@example
2114@group
2115@@node Comments, Minimum, Conventions, Overview
2116@@comment node-name, next, previous, up
2117@@section Comments
2118@end group
2119@end example
2120
2121or like this (without the @code{@@comment} line):
2122
2123@example
2124@group
2125@@node Comments, Minimum, Conventions, Overview
2126@@section Comments
2127@end group
2128@end example
2129
|
| 2130or like this (without the explicit node pointers):
2131
2132@example
2133@group
2134@@node Comments
2135@@section Comments
2136@end group
2137@end example
2138
|
2093@noindent
2094In this example, `Comments' is the name of both the node and the
2095section. The next node is called `Minimum' and the previous node is
2096called `Conventions'. The `Comments' section is within the `Overview'
2097node, which is specified by the `Up' pointer. (Instead of an
| 2139@noindent
2140In this example, `Comments' is the name of both the node and the
2141section. The next node is called `Minimum' and the previous node is
2142called `Conventions'. The `Comments' section is within the `Overview'
2143node, which is specified by the `Up' pointer. (Instead of an
|
2098@code{@@comment} line, you may also write an @code{@@ifinfo} line.)@refill
| 2144@code{@@comment} line, you may also write an @code{@@ifinfo} line.)
|
2099
2100If a file has a `Top' node, it must be called @samp{top} or @samp{Top}
| 2145
2146If a file has a `Top' node, it must be called @samp{top} or @samp{Top}
|
2101and be the first node in the file.@refill
| 2147and be the first node in the file.
|
2102
2103The menu updating commands create a menu of sections within a chapter,
2104a menu of subsections within a section, and so on. This means that
2105you must have a `Top' node if you want a menu of chapters.@refill
2106
2107Incidentally, the @code{makeinfo} command will create an Info file for a
2108hierarchically organized Texinfo file that lacks `Next', `Previous' and
2109`Up' pointers. Thus, if you can be sure that your Texinfo file will be
2110formatted with @code{makeinfo}, you have no need for the update node
2111commands. (@xref{Creating an Info File}, for more information about
2112@code{makeinfo}.) However, both @code{makeinfo} and the
2113@code{texinfo-format-@dots{}} commands require that you insert menus in
2114the file.
2115
| 2148
2149The menu updating commands create a menu of sections within a chapter,
2150a menu of subsections within a section, and so on. This means that
2151you must have a `Top' node if you want a menu of chapters.@refill
2152
2153Incidentally, the @code{makeinfo} command will create an Info file for a
2154hierarchically organized Texinfo file that lacks `Next', `Previous' and
2155`Up' pointers. Thus, if you can be sure that your Texinfo file will be
2156formatted with @code{makeinfo}, you have no need for the update node
2157commands. (@xref{Creating an Info File}, for more information about
2158@code{makeinfo}.) However, both @code{makeinfo} and the
2159@code{texinfo-format-@dots{}} commands require that you insert menus in
2160the file.
2161
|
2116@node Other Updating Commands, , Updating Requirements, Updating Nodes and Menus
2117@comment node-name, next, previous, up
| 2162
2163@node Other Updating Commands
|
2118@subsection Other Updating Commands
2119
2120In addition to the five major updating commands, Texinfo mode
2121possesses several less frequently used updating commands:@refill
2122
2123@table @kbd
2124@item M-x texinfo-insert-node-lines
2125@findex texinfo-insert-node-lines
2126Insert @code{@@node} lines before the @code{@@chapter},
2127@code{@@section}, and other sectioning commands wherever they are
2128missing throughout a region in a Texinfo file.@refill
2129
2130With an argument (@kbd{C-u} as prefix argument, if interactive), the
2131@code{texinfo-insert-node-lines} command not only inserts
2132@code{@@node} lines but also inserts the chapter or section titles as
2133the names of the corresponding nodes. In addition, it inserts the
2134titles as node names in pre-existing @code{@@node} lines that lack
2135names. Since node names should be more concise than section or
2136chapter titles, you must manually edit node names so inserted.@refill
2137
2138For example, the following marks a whole buffer as a region and inserts
2139@code{@@node} lines and titles throughout:@refill
2140
2141@example
2142C-x h C-u M-x texinfo-insert-node-lines
2143@end example
2144
2145This command inserts titles as node names in @code{@@node} lines; the
2146@code{texinfo-start-menu-description} command (@pxref{Inserting,
2147Inserting Frequently Used Commands}) inserts titles as descriptions in
2148menu entries, a different action. However, in both cases, you need to
2149edit the inserted text.
2150
2151@item M-x texinfo-multiple-files-update
2152@findex texinfo-multiple-files-update @r{(in brief)}
2153Update nodes and menus in a document built from several separate files.
2154With @kbd{C-u} as a prefix argument, create and insert a master menu in
2155the outer file. With a numeric prefix argument, such as @kbd{C-u 2}, first
2156update all the menus and all the `Next', `Previous', and `Up' pointers
2157of all the included files before creating and inserting a master menu in
2158the outer file. The @code{texinfo-multiple-files-update} command is
2159described in the appendix on @code{@@include} files.
2160@ifinfo
2161@xref{texinfo-multiple-files-update}.@refill
2162@end ifinfo
2163@iftex
2164@xref{texinfo-multiple-files-update, ,
2165@code{texinfo-multiple-files-update}}.@refill
2166@end iftex
2167
2168@item M-x texinfo-indent-menu-description
2169@findex texinfo-indent-menu-description
2170Indent every description in the menu following point to the specified
2171column. You can use this command to give yourself more space for
2172descriptions. With an argument (@kbd{C-u} as prefix argument, if
2173interactive), the @code{texinfo-indent-menu-description} command indents
2174every description in every menu in the region. However, this command
2175does not indent the second and subsequent lines of a multi-line
2176description.@refill
2177
2178@item M-x texinfo-sequential-node-update
2179@findex texinfo-sequential-node-update
2180Insert the names of the nodes immediately following and preceding the
2181current node as the `Next' or `Previous' pointers regardless of those
2182nodes' hierarchical level. This means that the `Next' node of a
2183subsection may well be the next chapter. Sequentially ordered nodes are
2184useful for novels and other documents that you read through
2185sequentially. (However, in Info, the @kbd{g *} command lets
2186you look through the file sequentially, so sequentially ordered nodes
2187are not strictly necessary.) With an argument (prefix argument, if
2188interactive), the @code{texinfo-sequential-node-update} command
2189sequentially updates all the nodes in the region.@refill
2190@end table
2191
2192@node Info Formatting, Printing, Updating Nodes and Menus, Texinfo Mode
2193@comment node-name, next, previous, up
2194@section Formatting for Info
2195@cindex Formatting for Info
2196@cindex Running an Info formatter
2197@cindex Info formatting
2198
2199Texinfo mode provides several commands for formatting part or all of a
2200Texinfo file for Info. Often, when you are writing a document, you
2201want to format only part of a file---that is, a region.@refill
2202
2203You can use either the @code{texinfo-format-region} or the
2204@code{makeinfo-region} command to format a region:@refill
2205
2206@table @kbd
2207@findex texinfo-format-region
2208@item C-c C-e C-r
2209@itemx M-x texinfo-format-region
2210@itemx C-c C-m C-r
2211@itemx M-x makeinfo-region
2212Format the current region for Info.@refill
2213@end table
2214
2215You can use either the @code{texinfo-format-buffer} or the
2216@code{makeinfo-buffer} command to format a whole buffer:@refill
2217
2218@table @kbd
2219@findex texinfo-format-buffer
2220@item C-c C-e C-b
2221@itemx M-x texinfo-format-buffer
2222@itemx C-c C-m C-b
2223@itemx M-x makeinfo-buffer
2224Format the current buffer for Info.@refill
2225@end table
2226
2227@need 1000
2228For example, after writing a Texinfo file, you can type the following:
2229
2230@example
2231C-u C-c C-u m
2232@exdent or
2233C-u M-x texinfo-master-menu
2234@end example
2235
2236@noindent
2237This updates all the nodes and menus. Then type the following to create
2238an Info file:
2239
2240@example
2241C-c C-m C-b
2242@exdent or
2243M-x makeinfo-buffer
2244@end example
2245
2246For @TeX{} or the Info formatting commands to work, the file @emph{must}
| 2164@subsection Other Updating Commands
2165
2166In addition to the five major updating commands, Texinfo mode
2167possesses several less frequently used updating commands:@refill
2168
2169@table @kbd
2170@item M-x texinfo-insert-node-lines
2171@findex texinfo-insert-node-lines
2172Insert @code{@@node} lines before the @code{@@chapter},
2173@code{@@section}, and other sectioning commands wherever they are
2174missing throughout a region in a Texinfo file.@refill
2175
2176With an argument (@kbd{C-u} as prefix argument, if interactive), the
2177@code{texinfo-insert-node-lines} command not only inserts
2178@code{@@node} lines but also inserts the chapter or section titles as
2179the names of the corresponding nodes. In addition, it inserts the
2180titles as node names in pre-existing @code{@@node} lines that lack
2181names. Since node names should be more concise than section or
2182chapter titles, you must manually edit node names so inserted.@refill
2183
2184For example, the following marks a whole buffer as a region and inserts
2185@code{@@node} lines and titles throughout:@refill
2186
2187@example
2188C-x h C-u M-x texinfo-insert-node-lines
2189@end example
2190
2191This command inserts titles as node names in @code{@@node} lines; the
2192@code{texinfo-start-menu-description} command (@pxref{Inserting,
2193Inserting Frequently Used Commands}) inserts titles as descriptions in
2194menu entries, a different action. However, in both cases, you need to
2195edit the inserted text.
2196
2197@item M-x texinfo-multiple-files-update
2198@findex texinfo-multiple-files-update @r{(in brief)}
2199Update nodes and menus in a document built from several separate files.
2200With @kbd{C-u} as a prefix argument, create and insert a master menu in
2201the outer file. With a numeric prefix argument, such as @kbd{C-u 2}, first
2202update all the menus and all the `Next', `Previous', and `Up' pointers
2203of all the included files before creating and inserting a master menu in
2204the outer file. The @code{texinfo-multiple-files-update} command is
2205described in the appendix on @code{@@include} files.
2206@ifinfo
2207@xref{texinfo-multiple-files-update}.@refill
2208@end ifinfo
2209@iftex
2210@xref{texinfo-multiple-files-update, ,
2211@code{texinfo-multiple-files-update}}.@refill
2212@end iftex
2213
2214@item M-x texinfo-indent-menu-description
2215@findex texinfo-indent-menu-description
2216Indent every description in the menu following point to the specified
2217column. You can use this command to give yourself more space for
2218descriptions. With an argument (@kbd{C-u} as prefix argument, if
2219interactive), the @code{texinfo-indent-menu-description} command indents
2220every description in every menu in the region. However, this command
2221does not indent the second and subsequent lines of a multi-line
2222description.@refill
2223
2224@item M-x texinfo-sequential-node-update
2225@findex texinfo-sequential-node-update
2226Insert the names of the nodes immediately following and preceding the
2227current node as the `Next' or `Previous' pointers regardless of those
2228nodes' hierarchical level. This means that the `Next' node of a
2229subsection may well be the next chapter. Sequentially ordered nodes are
2230useful for novels and other documents that you read through
2231sequentially. (However, in Info, the @kbd{g *} command lets
2232you look through the file sequentially, so sequentially ordered nodes
2233are not strictly necessary.) With an argument (prefix argument, if
2234interactive), the @code{texinfo-sequential-node-update} command
2235sequentially updates all the nodes in the region.@refill
2236@end table
2237
2238@node Info Formatting, Printing, Updating Nodes and Menus, Texinfo Mode
2239@comment node-name, next, previous, up
2240@section Formatting for Info
2241@cindex Formatting for Info
2242@cindex Running an Info formatter
2243@cindex Info formatting
2244
2245Texinfo mode provides several commands for formatting part or all of a
2246Texinfo file for Info. Often, when you are writing a document, you
2247want to format only part of a file---that is, a region.@refill
2248
2249You can use either the @code{texinfo-format-region} or the
2250@code{makeinfo-region} command to format a region:@refill
2251
2252@table @kbd
2253@findex texinfo-format-region
2254@item C-c C-e C-r
2255@itemx M-x texinfo-format-region
2256@itemx C-c C-m C-r
2257@itemx M-x makeinfo-region
2258Format the current region for Info.@refill
2259@end table
2260
2261You can use either the @code{texinfo-format-buffer} or the
2262@code{makeinfo-buffer} command to format a whole buffer:@refill
2263
2264@table @kbd
2265@findex texinfo-format-buffer
2266@item C-c C-e C-b
2267@itemx M-x texinfo-format-buffer
2268@itemx C-c C-m C-b
2269@itemx M-x makeinfo-buffer
2270Format the current buffer for Info.@refill
2271@end table
2272
2273@need 1000
2274For example, after writing a Texinfo file, you can type the following:
2275
2276@example
2277C-u C-c C-u m
2278@exdent or
2279C-u M-x texinfo-master-menu
2280@end example
2281
2282@noindent
2283This updates all the nodes and menus. Then type the following to create
2284an Info file:
2285
2286@example
2287C-c C-m C-b
2288@exdent or
2289M-x makeinfo-buffer
2290@end example
2291
2292For @TeX{} or the Info formatting commands to work, the file @emph{must}
|
2247include a line that has @code{@@setfilename} in its header.@refill
| 2293include a line that has @code{@@setfilename} in its header.
|
2248
2249@xref{Creating an Info File}, for details about Info formatting.@refill
2250
2251@node Printing, Texinfo Mode Summary, Info Formatting, Texinfo Mode
2252@comment node-name, next, previous, up
2253@section Formatting and Printing
2254@cindex Formatting for printing
2255@cindex Printing a region or buffer
2256@cindex Region formatting and printing
2257@cindex Buffer formatting and printing
2258@cindex Part of file formatting and printing
2259
2260Typesetting and printing a Texinfo file is a multi-step process in which
2261you first create a file for printing (called a DVI file), and then
2262print the file. Optionally, you may also create indices. To do this,
2263you must run the @code{texindex} command after first running the
2264@code{tex} typesetting command; and then you must run the @code{tex}
2265command again. Or else run the @code{texi2dvi} command which
2266automatically creates indices as needed (@pxref{Format with texi2dvi}).
2267
2268Often, when you are writing a document, you want to typeset and print
2269only part of a file to see what it will look like. You can use the
2270@code{texinfo-tex-region} and related commands for this purpose. Use
2271the @code{texinfo-tex-buffer} command to format all of a
2272buffer.@refill
2273
2274@table @kbd
2275@item C-c C-t C-b
2276@itemx M-x texinfo-tex-buffer
2277@findex texinfo-tex-buffer
2278Run @code{texi2dvi} on the buffer. In addition to running @TeX{} on the
2279buffer, this command automatically creates or updates indices as
2280needed.@refill
2281
2282@item C-c C-t C-r
2283@itemx M-x texinfo-tex-region
2284@findex texinfo-tex-region
2285Run @TeX{} on the region.@refill
2286
2287@item C-c C-t C-i
2288@itemx M-x texinfo-texindex
2289Run @code{texindex} to sort the indices of a Texinfo file formatted with
2290@code{texinfo-tex-region}. The @code{texinfo-tex-region} command does
2291not run @code{texindex} automatically; it only runs the @code{tex}
2292typesetting command. You must run the @code{texinfo-tex-region} command
2293a second time after sorting the raw index files with the @code{texindex}
2294command. (Usually, you do not format an index when you format a region,
2295only when you format a buffer. Now that the @code{texi2dvi} command
2296exists, there is little or no need for this command.)@refill
2297
2298@item C-c C-t C-p
2299@itemx M-x texinfo-tex-print
2300@findex texinfo-tex-print
2301Print the file (or the part of the file) previously formatted with
2302@code{texinfo-tex-buffer} or @code{texinfo-tex-region}.@refill
2303@end table
2304
2305For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the
2306file @emph{must} start with a @samp{\input texinfo} line and must
2307include an @code{@@settitle} line. The file must end with @code{@@bye}
2308on a line by itself. (When you use @code{texinfo-tex-region}, you must
2309surround the @code{@@settitle} line with start-of-header and
2310end-of-header lines.)@refill
2311
2312@xref{Hardcopy}, for a description of the other @TeX{} related
2313commands, such as @code{tex-show-print-queue}.@refill
2314
2315@node Texinfo Mode Summary, , Printing, Texinfo Mode
2316@comment node-name, next, previous, up
2317@section Texinfo Mode Summary
2318
2319In Texinfo mode, each set of commands has default keybindings that
2320begin with the same keys. All the commands that are custom-created
2321for Texinfo mode begin with @kbd{C-c}. The keys are somewhat
2322mnemonic.@refill
2323
2324@subheading Insert Commands
2325
2326The insert commands are invoked by typing @kbd{C-c} twice and then the
2327first letter of the @@-command to be inserted. (It might make more
2328sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but
2329@kbd{C-c C-c} is quick to type.)@refill
2330
2331@example
2332C-c C-c c @r{Insert} @samp{@@code}.
2333C-c C-c d @r{Insert} @samp{@@dfn}.
2334C-c C-c e @r{Insert} @samp{@@end}.
2335C-c C-c i @r{Insert} @samp{@@item}.
2336C-c C-c n @r{Insert} @samp{@@node}.
2337C-c C-c s @r{Insert} @samp{@@samp}.
2338C-c C-c v @r{Insert} @samp{@@var}.
2339C-c C-c @{ @r{Insert braces.}
2340C-c C-c ]
2341C-c C-c @} @r{Move out of enclosing braces.}
2342
2343@group
2344C-c C-c C-d @r{Insert a node's section title}
2345 @r{in the space for the description}
2346 @r{in a menu entry line.}
2347@end group
2348@end example
2349
2350@subheading Show Structure
2351
2352The @code{texinfo-show-structure} command is often used within a
2353narrowed region.@refill
2354
2355@example
2356C-c C-s @r{List all the headings.}
2357@end example
2358
2359@subheading The Master Update Command
2360
2361The @code{texinfo-master-menu} command creates a master menu; and can
2362be used to update every node and menu in a file as well.@refill
2363
2364@c Probably should use @tables in this section.
2365@example
2366@group
2367C-c C-u m
2368M-x texinfo-master-menu
2369 @r{Create or update a master menu.}
2370@end group
2371
2372@group
2373C-u C-c C-u m @r{With @kbd{C-u} as a prefix argument, first}
2374 @r{create or update all nodes and regular}
2375 @r{menus, and then create a master menu.}
2376@end group
2377@end example
2378
2379@subheading Update Pointers
2380
2381The update pointer commands are invoked by typing @kbd{C-c C-u} and
2382then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for
2383@code{texinfo-every-node-update}.@refill
2384
2385@example
2386C-c C-u C-n @r{Update a node.}
2387C-c C-u C-e @r{Update every node in the buffer.}
2388@end example
2389
2390@subheading Update Menus
2391
2392Invoke the update menu commands by typing @kbd{C-c C-u}
2393and then either @kbd{C-m} for @code{texinfo-make-menu} or
2394@kbd{C-a} for @code{texinfo-all-menus-update}. To update
2395both nodes and menus at the same time, precede @kbd{C-c C-u
2396C-a} with @kbd{C-u}.@refill
2397
2398@example
2399C-c C-u C-m @r{Make or update a menu.}
2400
2401@group
2402C-c C-u C-a @r{Make or update all}
2403 @r{menus in a buffer.}
2404@end group
2405
2406@group
2407C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,}
2408 @r{first create or update all nodes and}
2409 @r{then create or update all menus.}
2410@end group
2411@end example
2412
2413@subheading Format for Info
2414
2415The Info formatting commands that are written in Emacs Lisp are
2416invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region
2417or @kbd{C-b} for the whole buffer.@refill
2418
2419The Info formatting commands that are written in C and based on the
2420@code{makeinfo} program are invoked by typing @kbd{C-c C-m} and then
2421either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer.@refill
2422
2423@need 800
2424@noindent
2425Use the @code{texinfo-format@dots{}} commands:
2426
2427@example
2428@group
2429C-c C-e C-r @r{Format the region.}
2430C-c C-e C-b @r{Format the buffer.}
2431@end group
2432@end example
2433
2434@need 750
2435@noindent
2436Use @code{makeinfo}:
2437
2438@example
2439C-c C-m C-r @r{Format the region.}
2440C-c C-m C-b @r{Format the buffer.}
2441C-c C-m C-l @r{Recenter the @code{makeinfo} output buffer.}
2442C-c C-m C-k @r{Kill the @code{makeinfo} formatting job.}
2443@end example
2444
2445@subheading Typeset and Print
2446
2447The @TeX{} typesetting and printing commands are invoked by typing
2448@kbd{C-c C-t} and then another control command: @kbd{C-r} for
2449@code{texinfo-tex-region}, @kbd{C-b} for @code{texinfo-tex-buffer},
2450and so on.@refill
2451
2452@example
2453C-c C-t C-r @r{Run @TeX{} on the region.}
2454C-c C-t C-b @r{Run} @code{texi2dvi} @r{on the buffer.}
2455C-c C-t C-i @r{Run} @code{texindex}.
2456C-c C-t C-p @r{Print the DVI file.}
2457C-c C-t C-q @r{Show the print queue.}
2458C-c C-t C-d @r{Delete a job from the print queue.}
2459C-c C-t C-k @r{Kill the current @TeX{} formatting job.}
2460C-c C-t C-x @r{Quit a currently stopped @TeX{} formatting job.}
2461C-c C-t C-l @r{Recenter the output buffer.}
2462@end example
2463
2464@subheading Other Updating Commands
2465
2466The remaining updating commands do not have standard keybindings because
2467they are rarely used.
2468
2469@example
2470@group
2471M-x texinfo-insert-node-lines
2472 @r{Insert missing @code{@@node} lines in region.}
2473 @r{With @kbd{C-u} as a prefix argument,}
2474 @r{use section titles as node names.}
2475@end group
2476
2477@group
2478M-x texinfo-multiple-files-update
2479 @r{Update a multi-file document.}
2480 @r{With @kbd{C-u 2} as a prefix argument,}
2481 @r{create or update all nodes and menus}
2482 @r{in all included files first.}
2483@end group
2484
2485@group
2486M-x texinfo-indent-menu-description
2487 @r{Indent descriptions.}
2488@end group
2489
2490@group
2491M-x texinfo-sequential-node-update
2492 @r{Insert node pointers in strict sequence.}
2493@end group
2494@end example
2495
| 2294
2295@xref{Creating an Info File}, for details about Info formatting.@refill
2296
2297@node Printing, Texinfo Mode Summary, Info Formatting, Texinfo Mode
2298@comment node-name, next, previous, up
2299@section Formatting and Printing
2300@cindex Formatting for printing
2301@cindex Printing a region or buffer
2302@cindex Region formatting and printing
2303@cindex Buffer formatting and printing
2304@cindex Part of file formatting and printing
2305
2306Typesetting and printing a Texinfo file is a multi-step process in which
2307you first create a file for printing (called a DVI file), and then
2308print the file. Optionally, you may also create indices. To do this,
2309you must run the @code{texindex} command after first running the
2310@code{tex} typesetting command; and then you must run the @code{tex}
2311command again. Or else run the @code{texi2dvi} command which
2312automatically creates indices as needed (@pxref{Format with texi2dvi}).
2313
2314Often, when you are writing a document, you want to typeset and print
2315only part of a file to see what it will look like. You can use the
2316@code{texinfo-tex-region} and related commands for this purpose. Use
2317the @code{texinfo-tex-buffer} command to format all of a
2318buffer.@refill
2319
2320@table @kbd
2321@item C-c C-t C-b
2322@itemx M-x texinfo-tex-buffer
2323@findex texinfo-tex-buffer
2324Run @code{texi2dvi} on the buffer. In addition to running @TeX{} on the
2325buffer, this command automatically creates or updates indices as
2326needed.@refill
2327
2328@item C-c C-t C-r
2329@itemx M-x texinfo-tex-region
2330@findex texinfo-tex-region
2331Run @TeX{} on the region.@refill
2332
2333@item C-c C-t C-i
2334@itemx M-x texinfo-texindex
2335Run @code{texindex} to sort the indices of a Texinfo file formatted with
2336@code{texinfo-tex-region}. The @code{texinfo-tex-region} command does
2337not run @code{texindex} automatically; it only runs the @code{tex}
2338typesetting command. You must run the @code{texinfo-tex-region} command
2339a second time after sorting the raw index files with the @code{texindex}
2340command. (Usually, you do not format an index when you format a region,
2341only when you format a buffer. Now that the @code{texi2dvi} command
2342exists, there is little or no need for this command.)@refill
2343
2344@item C-c C-t C-p
2345@itemx M-x texinfo-tex-print
2346@findex texinfo-tex-print
2347Print the file (or the part of the file) previously formatted with
2348@code{texinfo-tex-buffer} or @code{texinfo-tex-region}.@refill
2349@end table
2350
2351For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the
2352file @emph{must} start with a @samp{\input texinfo} line and must
2353include an @code{@@settitle} line. The file must end with @code{@@bye}
2354on a line by itself. (When you use @code{texinfo-tex-region}, you must
2355surround the @code{@@settitle} line with start-of-header and
2356end-of-header lines.)@refill
2357
2358@xref{Hardcopy}, for a description of the other @TeX{} related
2359commands, such as @code{tex-show-print-queue}.@refill
2360
2361@node Texinfo Mode Summary, , Printing, Texinfo Mode
2362@comment node-name, next, previous, up
2363@section Texinfo Mode Summary
2364
2365In Texinfo mode, each set of commands has default keybindings that
2366begin with the same keys. All the commands that are custom-created
2367for Texinfo mode begin with @kbd{C-c}. The keys are somewhat
2368mnemonic.@refill
2369
2370@subheading Insert Commands
2371
2372The insert commands are invoked by typing @kbd{C-c} twice and then the
2373first letter of the @@-command to be inserted. (It might make more
2374sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but
2375@kbd{C-c C-c} is quick to type.)@refill
2376
2377@example
2378C-c C-c c @r{Insert} @samp{@@code}.
2379C-c C-c d @r{Insert} @samp{@@dfn}.
2380C-c C-c e @r{Insert} @samp{@@end}.
2381C-c C-c i @r{Insert} @samp{@@item}.
2382C-c C-c n @r{Insert} @samp{@@node}.
2383C-c C-c s @r{Insert} @samp{@@samp}.
2384C-c C-c v @r{Insert} @samp{@@var}.
2385C-c C-c @{ @r{Insert braces.}
2386C-c C-c ]
2387C-c C-c @} @r{Move out of enclosing braces.}
2388
2389@group
2390C-c C-c C-d @r{Insert a node's section title}
2391 @r{in the space for the description}
2392 @r{in a menu entry line.}
2393@end group
2394@end example
2395
2396@subheading Show Structure
2397
2398The @code{texinfo-show-structure} command is often used within a
2399narrowed region.@refill
2400
2401@example
2402C-c C-s @r{List all the headings.}
2403@end example
2404
2405@subheading The Master Update Command
2406
2407The @code{texinfo-master-menu} command creates a master menu; and can
2408be used to update every node and menu in a file as well.@refill
2409
2410@c Probably should use @tables in this section.
2411@example
2412@group
2413C-c C-u m
2414M-x texinfo-master-menu
2415 @r{Create or update a master menu.}
2416@end group
2417
2418@group
2419C-u C-c C-u m @r{With @kbd{C-u} as a prefix argument, first}
2420 @r{create or update all nodes and regular}
2421 @r{menus, and then create a master menu.}
2422@end group
2423@end example
2424
2425@subheading Update Pointers
2426
2427The update pointer commands are invoked by typing @kbd{C-c C-u} and
2428then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for
2429@code{texinfo-every-node-update}.@refill
2430
2431@example
2432C-c C-u C-n @r{Update a node.}
2433C-c C-u C-e @r{Update every node in the buffer.}
2434@end example
2435
2436@subheading Update Menus
2437
2438Invoke the update menu commands by typing @kbd{C-c C-u}
2439and then either @kbd{C-m} for @code{texinfo-make-menu} or
2440@kbd{C-a} for @code{texinfo-all-menus-update}. To update
2441both nodes and menus at the same time, precede @kbd{C-c C-u
2442C-a} with @kbd{C-u}.@refill
2443
2444@example
2445C-c C-u C-m @r{Make or update a menu.}
2446
2447@group
2448C-c C-u C-a @r{Make or update all}
2449 @r{menus in a buffer.}
2450@end group
2451
2452@group
2453C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,}
2454 @r{first create or update all nodes and}
2455 @r{then create or update all menus.}
2456@end group
2457@end example
2458
2459@subheading Format for Info
2460
2461The Info formatting commands that are written in Emacs Lisp are
2462invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region
2463or @kbd{C-b} for the whole buffer.@refill
2464
2465The Info formatting commands that are written in C and based on the
2466@code{makeinfo} program are invoked by typing @kbd{C-c C-m} and then
2467either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer.@refill
2468
2469@need 800
2470@noindent
2471Use the @code{texinfo-format@dots{}} commands:
2472
2473@example
2474@group
2475C-c C-e C-r @r{Format the region.}
2476C-c C-e C-b @r{Format the buffer.}
2477@end group
2478@end example
2479
2480@need 750
2481@noindent
2482Use @code{makeinfo}:
2483
2484@example
2485C-c C-m C-r @r{Format the region.}
2486C-c C-m C-b @r{Format the buffer.}
2487C-c C-m C-l @r{Recenter the @code{makeinfo} output buffer.}
2488C-c C-m C-k @r{Kill the @code{makeinfo} formatting job.}
2489@end example
2490
2491@subheading Typeset and Print
2492
2493The @TeX{} typesetting and printing commands are invoked by typing
2494@kbd{C-c C-t} and then another control command: @kbd{C-r} for
2495@code{texinfo-tex-region}, @kbd{C-b} for @code{texinfo-tex-buffer},
2496and so on.@refill
2497
2498@example
2499C-c C-t C-r @r{Run @TeX{} on the region.}
2500C-c C-t C-b @r{Run} @code{texi2dvi} @r{on the buffer.}
2501C-c C-t C-i @r{Run} @code{texindex}.
2502C-c C-t C-p @r{Print the DVI file.}
2503C-c C-t C-q @r{Show the print queue.}
2504C-c C-t C-d @r{Delete a job from the print queue.}
2505C-c C-t C-k @r{Kill the current @TeX{} formatting job.}
2506C-c C-t C-x @r{Quit a currently stopped @TeX{} formatting job.}
2507C-c C-t C-l @r{Recenter the output buffer.}
2508@end example
2509
2510@subheading Other Updating Commands
2511
2512The remaining updating commands do not have standard keybindings because
2513they are rarely used.
2514
2515@example
2516@group
2517M-x texinfo-insert-node-lines
2518 @r{Insert missing @code{@@node} lines in region.}
2519 @r{With @kbd{C-u} as a prefix argument,}
2520 @r{use section titles as node names.}
2521@end group
2522
2523@group
2524M-x texinfo-multiple-files-update
2525 @r{Update a multi-file document.}
2526 @r{With @kbd{C-u 2} as a prefix argument,}
2527 @r{create or update all nodes and menus}
2528 @r{in all included files first.}
2529@end group
2530
2531@group
2532M-x texinfo-indent-menu-description
2533 @r{Indent descriptions.}
2534@end group
2535
2536@group
2537M-x texinfo-sequential-node-update
2538 @r{Insert node pointers in strict sequence.}
2539@end group
2540@end example
2541
|
| 2542
|
2496@node Beginning a File
2497@chapter Beginning a Texinfo File
2498@cindex Beginning a Texinfo file
2499@cindex Texinfo file beginning
2500@cindex File beginning
2501
2502Certain pieces of information must be provided at the beginning of a
| 2543@node Beginning a File
2544@chapter Beginning a Texinfo File
2545@cindex Beginning a Texinfo file
2546@cindex Texinfo file beginning
2547@cindex File beginning
2548
2549Certain pieces of information must be provided at the beginning of a
|
2503Texinfo file, such as the name of the file and the title of the
2504document.@refill
| 2550Texinfo file, such as the name for the output file(s), the title of the
2551document, and the Top node.
|
2505
| 2552
|
| 2553This chapter expands on the minimal complete Texinfo source file
2554previously given (@pxref{Six Parts}).
2555
|
2506@menu
| 2556@menu
|
2507* Four Parts:: Four parts begin a Texinfo file.
2508* Sample Beginning:: Here is a sample beginning for a Texinfo file.
2509* Header:: The very beginning of a Texinfo file.
2510* Info Summary and Permissions:: Summary and copying permissions for Info.
| 2557* Sample Beginning:: A sample beginning for a Texinfo file.
2558* Texinfo File Header:: The first lines.
2559* Document Permissions:: Ensuring your manual is free.
|
2511* Titlepage & Copyright Page:: Creating the title and copyright pages.
2512* The Top Node:: Creating the `Top' node and master menu.
| 2560* Titlepage & Copyright Page:: Creating the title and copyright pages.
2561* The Top Node:: Creating the `Top' node and master menu.
|
| 2562* Global Document Commands:: Affecting formatting throughout.
|
2513* Software Copying Permissions:: Ensure that you and others continue to
| 2563* Software Copying Permissions:: Ensure that you and others continue to
|
2514 have the right to use and share software.
| 2564 have the right to use and share software.
|
2515@end menu
2516
| 2565@end menu
2566
|
2517@node Four Parts, Sample Beginning, Beginning a File, Beginning a File
2518@ifinfo
2519@heading Four Parts Begin a File
2520@end ifinfo
| |
2521
| 2567
|
2522Generally, the beginning of a Texinfo file has four parts:@refill
2523
2524@enumerate
2525@item
2526The header, delimited by special comment lines, that includes the
2527commands for naming the Texinfo file and telling @TeX{} what
2528definitions file to use when processing the Texinfo file.@refill
2529
2530@item
2531A short statement of what the file is about, with a copyright notice
2532and copying permissions. This is enclosed in @code{@@ifinfo} and
2533@code{@@end ifinfo} commands so that the formatters place it only
2534in the Info file.@refill
2535
2536@item
2537A title page and copyright page, with a copyright notice and copying
2538permissions. This is enclosed between @code{@@titlepage} and
2539@code{@@end titlepage} commands. The title and copyright page appear
2540only in the printed @w{manual}.@refill
2541
2542@item
2543The `Top' node that contains a menu for the whole Info file. The
2544contents of this node appear only in the Info file.@refill
2545@end enumerate
2546
2547Also, optionally, you may include the copying conditions for a program
2548and a warranty disclaimer. The copying section will be followed by an
2549introduction or else by the first chapter of the manual.@refill
2550
2551Since the copyright notice and copying permissions for the Texinfo
2552document (in contrast to the copying permissions for a program) are in
2553parts that appear only in the Info file or only in the printed manual,
2554this information must be given twice.@refill
2555
2556
| |
2557@node Sample Beginning
2558@section Sample Texinfo File Beginning
2559
| 2568@node Sample Beginning
2569@section Sample Texinfo File Beginning
2570
|
2560The following sample shows what is needed.@refill
| 2571@cindex Example beginning of Texinfo file
|
2561
| 2572
|
| 2573The following sample shows what is needed. The elements given here are
2574explained in more detail in the following sections. Other commands are
2575often included at the beginning of Texinfo files, but the ones here are
2576the most critical.
2577
2578@xref{GNU Sample Texts}, for the full texts to be used in GNU manuals.
2579
|
2562@example
2563\input texinfo @@c -*-texinfo-*-
2564@@c %**start of header
| 2580@example
2581\input texinfo @@c -*-texinfo-*-
2582@@c %**start of header
|
2565@@setfilename @var{name-of-info-file}
2566@@settitle @var{name-of-manual}
2567@@setchapternewpage odd
| 2583@@setfilename @var{infoname}.info
2584@@settitle @var{name-of-manual} @var{version}
|
2568@@c %**end of header
2569
| 2585@@c %**end of header
2586
|
2570@@ifinfo
2571This file documents @dots{}
| 2587@@copying
2588This manual is for @var{program}, version @var{version}.
|
2572
| 2589
|
2573Copyright @var{year} @var{copyright-owner}
| 2590Copyright @@copyright@{@} @var{years} @var{copyright-owner}.
|
2574
2575@group
| 2591
2592@group
|
| 2593@@quotation
|
2576Permission is granted to @dots{}
| 2594Permission is granted to @dots{}
|
2577@@end ifinfo
| 2595@@end quotation
2596@@end copying
|
2578@end group
2579
2580@group
| 2597@end group
2598
2599@group
|
2581@@c This title page illustrates only one of the
2582@@c two methods of forming a title page.
2583@end group
2584
2585@group
| |
2586@@titlepage
2587@@title @var{name-of-manual-when-printed}
2588@@subtitle @var{subtitle-if-any}
2589@@subtitle @var{second-subtitle}
2590@@author @var{author}
2591@end group
2592
2593@group
2594@@c The following two commands
2595@@c start the copyright page.
2596@@page
2597@@vskip 0pt plus 1filll
| 2600@@titlepage
2601@@title @var{name-of-manual-when-printed}
2602@@subtitle @var{subtitle-if-any}
2603@@subtitle @var{second-subtitle}
2604@@author @var{author}
2605@end group
2606
2607@group
2608@@c The following two commands
2609@@c start the copyright page.
2610@@page
2611@@vskip 0pt plus 1filll
|
2598Copyright @@copyright@{@} @var{year} @var{copyright-owner}
| 2612@@insertcopying
|
2599@end group
2600
2601Published by @dots{}
| 2613@end group
2614
2615Published by @dots{}
|
2602
2603Permission is granted to @dots{}
| |
2604@@end titlepage
2605
| 2616@@end titlepage
2617
|
| 2618@@c So the toc is printed in the right place.
2619@@contents
2620
|
2606@@ifnottex
2607@@node Top
2608@@top @var{title}
2609
| 2621@@ifnottex
2622@@node Top
2623@@top @var{title}
2624
|
2610This document describes @dots{}
2611
2612This document applies to version @dots{}
2613of the program named @dots{}
| 2625@@insertcopying
|
2614@@end ifnottex
2615
2616@group
2617@@menu
| 2626@@end ifnottex
2627
2628@group
2629@@menu
|
2618* Copying:: Your rights and freedoms.
| |
2619* First Chapter:: Getting started @dots{}
| 2630* First Chapter:: Getting started @dots{}
|
2620* Second Chapter:: @dots{}
| 2631* Second Chapter:: @dots{}
|
2621 @dots{}
| 2632 @dots{}
|
2622 @dots{}
| 2633* Copying:: Your rights and freedoms.
|
2623@@end menu
2624@end group
2625
2626@group
| 2634@@end menu
2635@end group
2636
2637@group
|
2627@@node First Chapter
| 2638@@node First Chapter
|
2628@@chapter First Chapter
| 2639@@chapter First Chapter
|
2629@@cindex Index entry for First Chapter
| 2640
2641@@cindex first chapter
2642@@cindex chapter, first
2643@dots{}
|
2630@end group
2631@end example
2632
2633
| 2644@end group
2645@end example
2646
2647
|
2634@node Header
2635@section The Texinfo File Header
| 2648@node Texinfo File Header
2649@section Texinfo File Header
|
2636@cindex Header for Texinfo files
2637@cindex Texinfo file header
2638
2639Texinfo files start with at least three lines that provide Info and
2640@TeX{} with necessary information. These are the @code{\input texinfo}
| 2650@cindex Header for Texinfo files
2651@cindex Texinfo file header
2652
2653Texinfo files start with at least three lines that provide Info and
2654@TeX{} with necessary information. These are the @code{\input texinfo}
|
2641line, the @code{@@settitle} line, and the @code{@@setfilename} line. If
2642you want to run @TeX{} on just a part of the Texinfo file, you must
| 2655line, the @code{@@settitle} line, and the @code{@@setfilename} line.
2656
2657Also, if you want to format just part of the Texinfo file, you must
|
2643write the @code{@@settitle} and @code{@@setfilename} lines between
| 2658write the @code{@@settitle} and @code{@@setfilename} lines between
|
2644start-of-header and end-of-header lines.
| 2659start-of-header and end-of-header lines. The start- and end-of-header
2660lines are optional, but they do no harm, so you might as well always
2661include them.
|
2645
| 2662
|
2646Thus, the beginning of a Texinfo file looks like this:
| 2663Any command that affects document formatting as a whole makes sense to
2664include in the header. @code{@@synindex} (@pxref{synindex}), for
2665instance, is another command often included in the header. @xref{GNU
2666Sample Texts}, for complete sample texts.
|
2647
| 2667
|
2648@example
2649@group
2650\input texinfo @@c -*-texinfo-*-
2651@@setfilename sample.info
2652@@settitle Sample Document
2653@end group
2654@end example
| 2668Thus, the beginning of a Texinfo file generally looks like this:
|
2655
| 2669
|
2656@noindent
2657or else like this:
2658
| |
2659@example
2660@group
2661\input texinfo @@c -*-texinfo-*-
2662@@c %**start of header
2663@@setfilename sample.info
| 2670@example
2671@group
2672\input texinfo @@c -*-texinfo-*-
2673@@c %**start of header
2674@@setfilename sample.info
|
2664@@settitle Sample Document
| 2675@@settitle Sample Manual 1.0
|
2665@@c %**end of header
2666@end group
2667@end example
2668
2669@menu
2670* First Line:: The first line of a Texinfo file.
2671* Start of Header:: Formatting a region requires this.
2672* setfilename:: Tell Info the name of the Info file.
2673* settitle:: Create a title for the printed work.
| 2676@@c %**end of header
2677@end group
2678@end example
2679
2680@menu
2681* First Line:: The first line of a Texinfo file.
2682* Start of Header:: Formatting a region requires this.
2683* setfilename:: Tell Info the name of the Info file.
2684* settitle:: Create a title for the printed work.
|
2674* documentdescription:: Document summary for the HTML output.
2675* setchapternewpage:: Start chapters on right-hand pages.
2676* paragraphindent:: Specify paragraph indentation.
2677* exampleindent:: Specify environment indentation.
| |
2678* End of Header:: Formatting a region requires this.
2679@end menu
2680
2681
2682@node First Line
2683@subsection The First Line of a Texinfo File
2684@cindex First line of a Texinfo file
2685@cindex Beginning line of a Texinfo file
2686@cindex Header of a Texinfo file
2687
2688Every Texinfo file that is to be the top-level input to @TeX{} must begin
| 2685* End of Header:: Formatting a region requires this.
2686@end menu
2687
2688
2689@node First Line
2690@subsection The First Line of a Texinfo File
2691@cindex First line of a Texinfo file
2692@cindex Beginning line of a Texinfo file
2693@cindex Header of a Texinfo file
2694
2695Every Texinfo file that is to be the top-level input to @TeX{} must begin
|
2689with a line that looks like this:@refill
| 2696with a line that looks like this:
|
2690
2691@example
2692\input texinfo @@c -*-texinfo-*-
2693@end example
2694
2695@noindent
2696This line serves two functions:
2697
2698@enumerate
2699@item
2700When the file is processed by @TeX{}, the @samp{\input texinfo} command
2701tells @TeX{} to load the macros needed for processing a Texinfo file.
| 2697
2698@example
2699\input texinfo @@c -*-texinfo-*-
2700@end example
2701
2702@noindent
2703This line serves two functions:
2704
2705@enumerate
2706@item
2707When the file is processed by @TeX{}, the @samp{\input texinfo} command
2708tells @TeX{} to load the macros needed for processing a Texinfo file.
|
2702These are in a file called @file{texinfo.tex}, which is usually located
2703in the @file{/usr/lib/tex/macros} directory. @TeX{} uses the backslash,
2704@samp{\}, to mark the beginning of a command, just as Texinfo uses
2705@samp{@@}. The @file{texinfo.tex} file causes the switch from @samp{\}
2706to @samp{@@}; before the switch occurs, @TeX{} requires @samp{\}, which
2707is why it appears at the beginning of the file.@refill
| 2709These are in a file called @file{texinfo.tex}, which should have been
2710installed on your system along with either the @TeX{} or Texinfo
2711software. @TeX{} uses the backslash, @samp{\}, to mark the beginning of
2712a command, exactly as Texinfo uses @samp{@@}. The @file{texinfo.tex}
2713file causes the switch from @samp{\} to @samp{@@}; before the switch
2714occurs, @TeX{} requires @samp{\}, which is why it appears at the
2715beginning of the file.
|
2708
2709@item
2710When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode
| 2716
2717@item
2718When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode
|
2711specification tells Emacs to use Texinfo mode.@refill
| 2719specification tells Emacs to use Texinfo mode.
|
2712@end enumerate
2713
2714
2715@node Start of Header
2716@subsection Start of Header
2717@cindex Start of header line
2718
| 2720@end enumerate
2721
2722
2723@node Start of Header
2724@subsection Start of Header
2725@cindex Start of header line
2726
|
2719Write a start-of-header line on the second line of a Texinfo file.
2720Follow the start-of-header line with @code{@@setfilename} and
2721@code{@@settitle} lines and, optionally, with other command lines, such
2722as @code{@@smallbook} or @code{@@footnotestyle}; and then by an
2723end-of-header line (@pxref{End of Header}).@refill
| 2727A start-of-header line is a Texinfo comment that looks like this:
|
2724
| 2728
|
2725With these lines, you can format part of a Texinfo file for Info or
2726typeset part for printing.@refill
2727
2728A start-of-header line looks like this:@refill
2729
| |
2730@example
2731@@c %**start of header
2732@end example
2733
| 2729@example
2730@@c %**start of header
2731@end example
2732
|
| 2733Write the start-of-header line on the second line of a Texinfo file.
2734Follow the start-of-header line with @code{@@setfilename} and
2735@code{@@settitle} lines and, optionally, with other commands that
2736globally affect the document formatting, such as @code{@@synindex} or
2737@code{@@footnotestyle}; and then by an end-of-header line (@pxref{End of
2738Header}).
2739
2740The start- and end-of-header lines allow you to format only part of a
2741Texinfo file for Info or printing. @xref{texinfo-format commands}.
2742
|
2734The odd string of characters, @samp{%**}, is to ensure that no other
| 2743The odd string of characters, @samp{%**}, is to ensure that no other
|
2735comment is accidentally taken for a start-of-header line.@refill
| 2744comment is accidentally taken for a start-of-header line. You can
2745change it if you wish by setting the @code{tex-start-of-header} and/or
2746@code{tex-end-of-header} Emacs variables. @xref{Texinfo Mode Printing}.
|
2736
| 2747
|
| 2748
|
2737@node setfilename
| 2749@node setfilename
|
2738@subsection @code{@@setfilename}
2739@cindex Info file requires @code{@@setfilename}
| 2750@subsection @code{@@setfilename}: Set the output file name
|
2740@findex setfilename
| 2751@findex setfilename
|
| 2752@cindex Texinfo requires @code{@@setfilename}
|
2741
2742In order to serve as the primary input file for either @code{makeinfo}
2743or @TeX{}, a Texinfo file must contain a line that looks like this:
2744
2745@example
2746@@setfilename @var{info-file-name}
2747@end example
2748
2749Write the @code{@@setfilename} command at the beginning of a line and
2750follow it on the same line by the Info file name. Do not write anything
2751else on the line; anything on the line after the command is considered
2752part of the file name, including what would otherwise be a
2753comment.
2754
| 2753
2754In order to serve as the primary input file for either @code{makeinfo}
2755or @TeX{}, a Texinfo file must contain a line that looks like this:
2756
2757@example
2758@@setfilename @var{info-file-name}
2759@end example
2760
2761Write the @code{@@setfilename} command at the beginning of a line and
2762follow it on the same line by the Info file name. Do not write anything
2763else on the line; anything on the line after the command is considered
2764part of the file name, including what would otherwise be a
2765comment.
2766
|
| 2767@cindex Ignored before @code{@@setfilename}
2768@cindex @samp{\input} source line ignored
2769The Info formatting commands ignore everything written before the
2770@code{@@setfilename} line, which is why the very first line of
2771the file (the @code{\input} line) does not show up in the output.
2772
|
2755The @code{@@setfilename} line specifies the name of the output file to
| 2773The @code{@@setfilename} line specifies the name of the output file to
|
2756be generated. This name should be different from the name of the
2757Texinfo file. There are two conventions for choosing the name: you can
2758either remove the extension (such as @samp{.texi}) from the input file
2759name, or replace it with the @samp{.info} extension. When producing
2760HTML output, @code{makeinfo} will replace any extension with
2761@samp{html}, or add @samp{.html} if the given name has no extension.
| 2774be generated. This name must be different from the name of the Texinfo
2775file. There are two conventions for choosing the name: you can either
2776remove the extension (such as @samp{.texi}) entirely from the input file
2777name, or, preferably, replace it with the @samp{.info} extension.
|
2762
| 2778
|
2763Some operating systems cannot handle long file names. You can run into
2764a problem even when the file name you specify is itself short enough.
| 2779@cindex Length of file names
2780@cindex File name collision
2781@cindex Info file name, choosing
2782Although an explicit @samp{.info} extension is preferable, some
2783operating systems cannot handle long file names. You can run into a
2784problem even when the file name you specify is itself short enough.
|
2765This occurs because the Info formatters split a long Info file into
2766short indirect subfiles, and name them by appending @samp{-1},
2767@samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original
| 2785This occurs because the Info formatters split a long Info file into
2786short indirect subfiles, and name them by appending @samp{-1},
2787@samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original
|
2768file name. (@xref{Tag and Split Files, , Tag Files and Split Files}.)
2769The subfile name @file{texinfo.info-10}, for example, is too long for
2770some systems; so the Info file name for this document is @file{texinfo}
2771rather than @file{texinfo.info}. When @code{makeinfo} is running on
2772operating systems such as MS-DOS which impose grave limits on file
2773names, it will sometimes remove some characters from the original file
2774name to leave enough space for the subfile suffix, thus producing files
2775named @file{texin-10}, @file{gcc.i12}, etc.
| 2788file name. (@xref{Tag and Split Files}.) The subfile name
2789@file{texinfo.info-10}, for example, is too long for old systems with a
279014-character limit on filenames; so the Info file name for this document
2791is @file{texinfo} rather than @file{texinfo.info}. When @code{makeinfo}
2792is running on operating systems such as MS-DOS which impose severe
2793limits on file names, it may remove some characters from the original
2794file name to leave enough space for the subfile suffix, thus producing
2795files named @file{texin-10}, @file{gcc.i12}, etc.
|
2776
| 2796
|
2777@cindex Ignored before @code{@@setfilename}
2778@cindex @samp{\input} source line ignored
2779The Info formatting commands ignore everything written before the
2780@code{@@setfilename} line, which is why the very first line of
2781the file (the @code{\input} line) does not show up in the output.
| 2797When producing HTML output, @code{makeinfo} will replace any extension
2798with @samp{html}, or add @samp{.html} if the given name has no
2799extension.
|
2782
2783@pindex texinfo.cnf
2784The @code{@@setfilename} line produces no output when you typeset a
2785manual with @TeX{}, but it is nevertheless essential: it opens the
2786index, cross-reference, and other auxiliary files used by Texinfo, and
2787also reads @file{texinfo.cnf} if that file is present on your system
2788(@pxref{Preparing for TeX,, Preparing for @TeX{}}).
2789
2790
2791@node settitle
2792@subsection @code{@@settitle}: Set the document title
2793@findex settitle
2794
2795In order to be made into a printed manual, a Texinfo file must contain
2796a line that looks like this:
2797
2798@example
2799@@settitle @var{title}
2800@end example
2801
| 2800
2801@pindex texinfo.cnf
2802The @code{@@setfilename} line produces no output when you typeset a
2803manual with @TeX{}, but it is nevertheless essential: it opens the
2804index, cross-reference, and other auxiliary files used by Texinfo, and
2805also reads @file{texinfo.cnf} if that file is present on your system
2806(@pxref{Preparing for TeX,, Preparing for @TeX{}}).
2807
2808
2809@node settitle
2810@subsection @code{@@settitle}: Set the document title
2811@findex settitle
2812
2813In order to be made into a printed manual, a Texinfo file must contain
2814a line that looks like this:
2815
2816@example
2817@@settitle @var{title}
2818@end example
2819
|
2802In the HTML file produced by @command{makeinfo}, @var{title} serves as
2803the default document description in the @samp{<head>} part; see
2804@ref{documentdescription}, for how to change that.
2805
| |
2806Write the @code{@@settitle} command at the beginning of a line and
| 2820Write the @code{@@settitle} command at the beginning of a line and
|
2807follow it on the same line by the title. This tells @TeX{} the title
2808to use in a header or footer. Do not write anything else on the line;
2809anything on the line after the command is considered part of the
2810title, including a comment.@refill
| 2821follow it on the same line by the title. This tells @TeX{} the title to
2822use in a header or footer. Do not write anything else on the line;
2823anything on the line after the command is considered part of the title,
2824including what would otherwise be a comment.
|
2811
| 2825
|
| 2826The @code{@@settitle} command should precede everything that generates
2827actual output in @TeX{}.
2828
2829@cindex <title> HTML tag
2830In the HTML file produced by @command{makeinfo}, @var{title} also serves
2831as the document @samp{<title>} and the default document description in
2832the @samp{<head>} part; see @ref{documentdescription}, for how to change
2833that.
2834
2835The title in the @code{@@settitle} command does not affect the title as
2836it appears on the title page. Thus, the two do not need not match
2837exactly. A practice we recommend is to include the version or edition
2838number of the manual in the @code{@@settitle} title; on the title page,
2839the version number generally appears as a @code{@@subtitle} so it would
2840be omitted from the @code{@@title}. (@xref{titlepage}.)
2841
|
2812Conventionally, when @TeX{} formats a Texinfo file for double-sided
2813output, the title is printed in the left-hand (even-numbered) page
2814headings and the current chapter title is printed in the right-hand
2815(odd-numbered) page headings. (@TeX{} learns the title of each chapter
| 2842Conventionally, when @TeX{} formats a Texinfo file for double-sided
2843output, the title is printed in the left-hand (even-numbered) page
2844headings and the current chapter title is printed in the right-hand
2845(odd-numbered) page headings. (@TeX{} learns the title of each chapter
|
2816from each @code{@@chapter} command.) Page footers are not
2817printed.@refill
| 2846from each @code{@@chapter} command.) By default, no page footer is
2847printed.
|
2818
2819Even if you are printing in a single-sided style, @TeX{} looks for an
2820@code{@@settitle} command line, in case you include the manual title
| 2848
2849Even if you are printing in a single-sided style, @TeX{} looks for an
2850@code{@@settitle} command line, in case you include the manual title
|
2821in the heading. @refill
| 2851in the heading.
|
2822
| 2852
|
2823The @code{@@settitle} command should precede everything that generates
2824actual output in @TeX{}.@refill
2825
2826Although the title in the @code{@@settitle} command is usually the
2827same as the title on the title page, it does not affect the title as
2828it appears on the title page. Thus, the two do not need not match
2829exactly; and the title in the @code{@@settitle} command can be a
2830shortened or expanded version of the title as it appears on the title
2831page. (@xref{titlepage, , @code{@@titlepage}}.)@refill
2832
| |
2833@TeX{} prints page headings only for that text that comes after the
2834@code{@@end titlepage} command in the Texinfo file, or that comes
2835after an @code{@@headings} command that turns on headings.
2836(@xref{headings on off, , The @code{@@headings} Command}, for more
| 2853@TeX{} prints page headings only for that text that comes after the
2854@code{@@end titlepage} command in the Texinfo file, or that comes
2855after an @code{@@headings} command that turns on headings.
2856(@xref{headings on off, , The @code{@@headings} Command}, for more
|
2837information.)@refill
| 2857information.)
|
2838
| 2858
|
2839You may, if you wish, create your own, customized headings and
2840footings. @xref{Headings, , Page Headings}, for a detailed discussion
2841of this process.@refill
| 2859You may, if you wish, create your own, customized headings and footings.
2860@xref{Headings}, for a detailed discussion of this.
|
2842
2843
| 2861
2862
|
2844@node documentdescription
2845@subsection @code{@@documentdescription}: Summary text
2846@cindex Document description
2847@cindex Description of document
2848@cindex Summary of document
2849@cindex <meta> HTML tag, and document description
| 2863@node End of Header
2864@subsection End of Header
2865@cindex End of header line
|
2850
| 2866
|
2851When producing HTML output for a document, @command{makeinfo} writes a
2852@samp{<meta>} element in the @samp{<head>} to give some idea of the
2853content of the document. By default, this @dfn{description} is the title
2854of the document, taken from the @code{@@settitle} command
2855(@pxref{settitle}). To change this, use the @code{@@documentdescription}
2856environment, as in:
| 2867Follow the header lines with an @w{end-of-header} line, which is a
2868Texinfo comment that looks like this:
|
2857
2858@example
| 2869
2870@example
|
2859@@documentdescription
2860descriptive text
2861@@end documendescription
| 2871@@c %**end of header
|
2862@end example
2863
| 2872@end example
2873
|
2864@noindent
2865This will produce the following output in the @samp{<head>} of the HTML:
| 2874@xref{Start of Header}.
|
2866
| 2875
|
2867@example
2868<meta name=description content="descriptive text">
2869@end example
| |
2870
| 2876
|
2871@code{@@documentdescription} must be specified before the first node of
2872the document.
| 2877@node Document Permissions
2878@section Document Permissions
2879@cindex Document Permissions
2880@cindex Copying Permissions
|
2873
| 2881
|
| 2882The copyright notice and copying permissions for a document need to
2883appear in several places in the various Texinfo output formats.
2884Therefore, Texinfo provides a command (@code{@@copying}) to declare
2885this text once, and another command (@code{@@insertcopying}) to
2886insert the text at appropriate points.
|
2874
| 2887
|
2875@findex documentdescription
2876@node setchapternewpage
2877@subsection @code{@@setchapternewpage}:
2878@cindex Starting chapters
2879@cindex Pages, starting odd
2880@findex setchapternewpage
| 2888@menu
2889* copying:: Declare the document's copying permissions.
2890* insertcopying:: Where to insert the permissions.
2891@end menu
|
2881
| 2892
|
2882In an officially bound book, text is usually printed on both sides of
2883the paper, chapters start on right-hand pages, and right-hand pages have
2884odd numbers. But in short reports, text often is printed only on one
2885side of the paper. Also in short reports, chapters sometimes do not
2886start on new pages, but are printed on the same page as the end of the
2887preceding chapter, after a small amount of vertical whitespace.
| |
2888
| 2893
|
2889You can use the @code{@@setchapternewpage} command with various
2890arguments to specify how @TeX{} should start chapters and whether it
2891should format headers for printing on one or both sides of the paper
2892(single-sided or double-sided printing).
| 2894@node copying
2895@subsection @code{@@copying}: Declare copying permissions
2896@findex copying
|
2893
| 2897
|
2894Write the @code{@@setchapternewpage} command at the beginning of a
2895line followed by its argument.
| 2898The @code{@@copying} command should be given very early in the document;
2899right after the header material (@pxref{Texinfo File Header}) is the
2900recommended location. It conventionally consists of a sentence or two
2901about what the program is, the legal copyright line, and the copying
2902permissions. Here is a skeletal example:
|
2896
| 2903
|
2897For example, you would write the following to cause each chapter to
2898start on a fresh odd-numbered page:
2899
| |
2900@example
| 2904@example
|
2901@@setchapternewpage odd
2902@end example
| 2905@@copying
2906This manual is for @var{program} (version @var{version}),
2907which @dots{}
|
2903
| 2908
|
2904You can specify one of three alternatives with the
2905@code{@@setchapternewpage} command:
| 2909Copyright @@copyright@{@} @var{years} @var{copyright-owner}.
|
2906
| 2910
|
2907@table @asis
2908
2909@item @code{@@setchapternewpage off}
2910Cause @TeX{} to typeset a new chapter on the same page as the last
2911chapter, after skipping some vertical whitespace. Also, cause @TeX{} to
2912format page headers for single-sided printing.
2913
2914@item @code{@@setchapternewpage on}
2915Cause @TeX{} to start new chapters on new pages and to format page
2916headers for single-sided printing. This is the form most often used for
2917short reports or personal printing. This is the default.
2918
2919@item @code{@@setchapternewpage odd}
2920Cause @TeX{} to start new chapters on new, odd-numbered pages
2921(right-handed pages) and to typeset for double-sided printing. This is
2922the form most often used for books and manuals.
2923@end table
2924
2925Texinfo does not have an @code{@@setchapternewpage even} command,
2926because there is no printing tradition of starting chapters or books on
2927an even-numbered page.
2928
2929If you don't like the default headers that @code{@@setchapternewpage}
2930sets, you can explicit control them with the @code{@@headings} command.
2931@xref{headings on off, , The @code{@@headings} Command}.
2932
2933At the beginning of a manual or book, pages are not numbered---for
2934example, the title and copyright pages of a book are not numbered. By
2935convention, table of contents and frontmatter pages are numbered with
2936roman numerals and not in sequence with the rest of the document.
2937
2938Since an Info file does not have pages, the @code{@@setchapternewpage}
2939command has no effect on it.
2940
2941We recommend not including any @code{@@setchapternewpage} command in
2942your manual sources at all, since the desired output is not intrinsic to
2943the document. Instead, if you don't want the default option (no blank
2944pages, same headers on all pages) use the @option{--texinfo} option to
2945@command{texi2dvi} to specify the output you want.
2946
2947
2948
2949@node paragraphindent
2950@subsection Paragraph Indenting
2951@cindex Indenting paragraphs
2952@cindex Paragraph indentation
2953@findex paragraphindent
2954
2955The Texinfo processors may insert whitespace at the beginning of the
2956first line of each paragraph, thereby indenting that paragraph. You can
2957use the @code{@@paragraphindent} command to specify this indentation.
2958Write an @code{@@paragraphindent} command at the beginning of a line
2959followed by either @samp{asis} or a number:
2960
2961@example
2962@@paragraphindent @var{indent}
| 2911@@quotation
2912Permission is granted to @dots{}
2913@@end quotation
2914@@end copying
|
2963@end example
2964
| 2915@end example
2916
|
2965The indentation is according to the value of @var{indent}:
| 2917The @code{@@quotation} has no legal significance; it's there to improve
2918readability in some contexts.
|
2966
| 2919
|
2967@table @asis
2968@item @code{asis}
2969Do not change the existing indentation (not implemented in @TeX{}).
| 2920@xref{GNU Sample Texts}, for the full text to be used in GNU manuals.
2921@xref{GNU Free Documentation License}, for the license itself under
2922which GNU and other free manuals are distributed.
|
2970
| 2923
|
2971@item 0
2972Omit all indentation.
| 2924The text of @code{@@copying} is output as a comment at the beginning of
2925Info, HTML, and XML output files. It is @emph{not} output implicitly in
2926plain text or @TeX{}; it's up to you to use @code{@@insertcopying} to
2927emit the copying information. See the next section for details.
|
2973
| 2928
|
2974@item @var{n}
2975Indent by @var{n} space characters in Info output, by @var{n} ems in
2976@TeX{}.
| 2929@findex copyright
2930In output formats that support it (print and HTML), the
2931@code{@@copyright@{@}} command generates a @samp{c} inside a circle. In
2932Info and plain text, it generates @samp{(C)}. The copyright notice
2933itself has the following legally defined sequence:
|
2977
| 2934
|
2978@end table
2979
2980The default value of @var{indent} is @samp{asis}.
2981@code{@@paragraphindent} is ignored for HTML output.
2982
2983Write the @code{@@paragraphindent} command before or shortly after the
2984end-of-header line at the beginning of a Texinfo file. (If you write
2985the command between the start-of-header and end-of-header lines, the
2986region formatting commands indent paragraphs as specified.)
2987
2988A peculiarity of the @code{texinfo-format-buffer} and
2989@code{texinfo-format-region} commands is that they do not indent (nor
2990fill) paragraphs that contain @code{@@w} or @code{@@*} commands.
2991@xref{Refilling Paragraphs}, for further information.
2992
2993
2994@node exampleindent
2995@subsection @code{@@exampleindent}: Environment Indenting
2996@cindex Indenting environments
2997@cindex Environment indentation
2998@cindex Example indentation
2999@findex exampleindent
3000
3001The Texinfo processors indent each line of @code{@@example} and similar
3002environments. You can use the @code{@@exampleindent} command to specify
3003this indentation. Write an @code{@@exampleindent} command at the
3004beginning of a line followed by either @samp{asis} or a number:
3005
| |
3006@example
| 2935@example
|
3007@@exampleindent @var{indent}
| 2936Copyright @copyright{} @var{years} @var{copyright-owner}.
|
3008@end example
3009
| 2937@end example
2938
|
3010The indentation is according to the value of @var{indent}:
| 2939@cindex Copyright word, always in English
2940The word `Copyright' must always be written in English, even if the
2941manual is otherwise in another language. This is due to international
2942law.
|
3011
| 2943
|
3012@table @asis
3013@item @code{asis}
3014Do not change the existing indentation (not implemented in @TeX{}).
| 2944@cindex Years, in copyright line
2945The list of years should include all years in which a version was
2946completed (even if it was released in a subsequent year). Ranges are
2947not allowed, each year must be written out individually, separated by
2948commas.
|
3015
| 2949
|
3016@item 0
3017Omit all indentation.
| 2950@cindex Copyright owner for FSF works
2951The copyright owner (or owners) is whoever holds legal copyright on the
2952work. In the case of works assigned to the FSF, the owner is `Free
2953Software Foundation, Inc.'.
|
3018
| 2954
|
3019@item @var{n}
3020Indent environments by @var{n} space characters in Info output, by
3021@var{n} ems in @TeX{}.
| 2955@xref{Copyright Notices,,,maintain,GNU Maintenance Instructions}, for
2956additional information.
|
3022
| 2957
|
3023@end table
| |
3024
| 2958
|
3025The default value of @var{indent} is 5. @code{@@exampleindent} is
3026ignored for HTML output.
| 2959@node insertcopying
2960@subsection @code{@@insertcopying}: Include permissions text
2961@findex insertcopying
2962@cindex Copying text, including
2963@cindex Permissions text, including
2964@cindex Including permissions text
|
3027
| 2965
|
3028Write the @code{@@exampleindent} command before or shortly after the
3029end-of-header line at the beginning of a Texinfo file. (If you write
3030the command between the start-of-header and end-of-header lines, the
3031region formatting commands indent examples as specified.)
| 2966The @code{@@insertcopying} command is simply written on a line by
2967itself, like this:
|
3032
| 2968
|
3033
3034@node End of Header
3035@subsection End of Header
3036@cindex End of header line
3037
3038Follow the header lines with an @w{end-of-header} line.
3039An end-of-header line looks like this:@refill
3040
| |
3041@example
| 2969@example
|
3042@@c %**end of header
| 2970@@insertcopying
|
3043@end example
3044
| 2971@end example
2972
|
3045If you include the @code{@@setchapternewpage} command between the
3046start-of-header and end-of-header lines, @TeX{} will typeset a region as
3047that command specifies. Similarly, if you include an @code{@@smallbook}
3048command between the start-of-header and end-of-header lines, @TeX{} will
3049typeset a region in the ``small'' book format.@refill
| 2973It inserts the text previously defined by @code{@@copying}. Legally, it
2974must be used on the copyright page in the printed manual
2975(@pxref{Copyright}).
|
3050
| 2976
|
3051@ifinfo
3052The reason for the odd string of characters (@samp{%**}) is so that the
3053@code{texinfo-tex-region} command does not accidentally find
3054something that it should not when it is looking for the header.@refill
| 2977Although it's not a legal requirement, we also strongly recommend using
2978@code{@@insertcopying} in the Top node of your manual (@pxref{The Top
2979Node}). Here's why:
|
3055
| 2980
|
3056The start-of-header line and the end-of-header line are Texinfo mode
3057variables that you can change.@refill
3058@end ifinfo
| 2981The @code{@@copying} command itself causes the permissions text to
2982appear in an Info file @emph{before} the first node. The text is also
2983copied into the beginning of each split Info output file, as is legally
2984necessary. This location implies a human reading the manual using Info
2985does @emph{not} see this text (except when using the advanced Info
2986command @kbd{g *}). Therefore, an explicit @code{@@insertcopying}
2987in the Top node makes it apparent to readers that the manual is free.
|
3059
| 2988
|
3060@iftex
3061@xref{Start of Header}.
3062@end iftex
| 2989Similarly, the @code{@@copying} text is automatically included at the
2990beginning of each HTML output file, as an HTML comment. Again, this
2991text is not visible (unless the reader views the HTML source). And
2992therefore again, the @code{@@insertcopying} in the Top node is valuable
2993because it makes the copying permissions visible and thus promotes
2994freedom.
|
3063
| 2995
|
| 2996The permissions text defined by @code{@@copying} also appears
2997automatically at the beginning of the XML output file.
|
3064
| 2998
|
3065@node Info Summary and Permissions
3066@section Summary and Copying Permissions for Info
| |
3067
| 2999
|
3068The title page and the copyright page appear only in the printed copy of
3069the manual; therefore, the same information must be inserted in a
3070section that appears only in the Info file. This section usually
3071contains a brief description of the contents of the Info file, a
3072copyright notice, and copying permissions.@refill
3073
3074The copyright notice should read:
3075
3076@example
3077Copyright @var{year} @var{copyright-owner}
3078@end example
3079
3080@noindent
3081and be put on a line by itself.
3082
3083Standard text for the copyright permissions of free manuals is contained
3084in an appendix to this manual (@pxref{Documentation Copying, , GNU Free
3085Documentation License}).
3086
3087The permissions text appears in an Info file @emph{before} the first
3088node. This mean that a reader does @emph{not} see this text when
3089reading the file using Info (except when using the advanced Info command
3090@kbd{g *}).
3091
3092
| |
3093@node Titlepage & Copyright Page
| 3000@node Titlepage & Copyright Page
|
3094@section The Title and Copyright Pages
| 3001@section Title and Copyright Pages
|
3095
| 3002
|
3096A manual's name and author are usually printed on a title page.
3097Sometimes copyright information is printed on the title page as well;
3098more often, copyright information is printed on the back of the title
3099page.
| 3003In hard copy output, the manual's name and author are usually printed on
3004a title page. Copyright information is usually printed on the back of
3005the title page.
|
3100
| 3006
|
3101The title and copyright pages appear in the printed manual, but not in the
3102Info file. Because of this, it is possible to use several slightly
| 3007The title and copyright pages appear in the printed manual, but not in
3008the Info file. Because of this, it is possible to use several slightly
|
3103obscure @TeX{} typesetting commands that cannot be used in an Info file.
| 3009obscure @TeX{} typesetting commands that cannot be used in an Info file.
|
3104In addition, this part of the beginning of a Texinfo file contains the text
3105of the copying permissions that will appear in the printed manual.@refill
| 3010In addition, this part of the beginning of a Texinfo file contains the
3011text of the copying permissions that appears in the printed manual.
|
3106
| 3012
|
3107@cindex Titlepage, for plain text
| 3013@cindex Title page, for plain text
3014@cindex Copyright page, for plain text
|
3108You may wish to include titlepage-like information for plain text
| 3015You may wish to include titlepage-like information for plain text
|
3109output. Simply place any such leading material between @code{@@ifinfo}
3110and @code{@@end ifinfo}; @command{makeinfo} includes this in its plain
3111text output. It will not show up in the Info readers.
| 3016output. Simply place any such leading material between
3017@code{@@ifplaintext} and @code{@@end ifplaintext}; @command{makeinfo}
3018includes this when writing plain text (@samp{--no-headers}), along with
3019an @code{@@insertcopying}.
|
3112
| 3020
|
3113@xref{Documentation Copying, , GNU Free Documentation License}, for the
3114standard text for the copyright permissions.
3115
| |
3116@menu
3117* titlepage:: Create a title for the printed document.
3118* titlefont center sp:: The @code{@@titlefont}, @code{@@center},
3119 and @code{@@sp} commands.
3120* title subtitle author:: The @code{@@title}, @code{@@subtitle},
3121 and @code{@@author} commands.
| 3021@menu
3022* titlepage:: Create a title for the printed document.
3023* titlefont center sp:: The @code{@@titlefont}, @code{@@center},
3024 and @code{@@sp} commands.
3025* title subtitle author:: The @code{@@title}, @code{@@subtitle},
3026 and @code{@@author} commands.
|
3122* Copyright & Permissions:: How to write the copyright notice and
| 3027* Copyright:: How to write the copyright notice and
|
3123 include copying permissions.
3124* end titlepage:: Turn on page headings after the title and
3125 copyright pages.
3126* headings on off:: An option for turning headings on and off
3127 and double or single sided printing.
3128@end menu
3129
3130
| 3028 include copying permissions.
3029* end titlepage:: Turn on page headings after the title and
3030 copyright pages.
3031* headings on off:: An option for turning headings on and off
3032 and double or single sided printing.
3033@end menu
3034
3035
|
3131@node titlepage, titlefont center sp, Titlepage & Copyright Page, Titlepage & Copyright Page
3132@comment node-name, next, previous, up
| 3036@node titlepage
|
3133@subsection @code{@@titlepage}
3134@cindex Title page
3135@findex titlepage
3136
3137Start the material for the title page and following copyright page
3138with @code{@@titlepage} on a line by itself and end it with
| 3037@subsection @code{@@titlepage}
3038@cindex Title page
3039@findex titlepage
3040
3041Start the material for the title page and following copyright page
3042with @code{@@titlepage} on a line by itself and end it with
|
3139@code{@@end titlepage} on a line by itself.@refill
| 3043@code{@@end titlepage} on a line by itself.
|
3140
3141The @code{@@end titlepage} command starts a new page and turns on page
3142numbering. (@xref{Headings, , Page Headings}, for details about how to
3143generate page headings.) All the material that you want to appear on
3144unnumbered pages should be put between the @code{@@titlepage} and
3145@code{@@end titlepage} commands. You can force the table of contents to
3146appear there with the @code{@@setcontentsaftertitlepage} command
3147(@pxref{Contents}).
3148
3149@findex page@r{, within @code{@@titlepage}}
3150By using the @code{@@page} command you can force a page break within the
3151region delineated by the @code{@@titlepage} and @code{@@end titlepage}
3152commands and thereby create more than one unnumbered page. This is how
3153the copyright page is produced. (The @code{@@titlepage} command might
3154perhaps have been better named the @code{@@titleandadditionalpages}
3155command, but that would have been rather long!)
3156
3157When you write a manual about a computer program, you should write the
3158version of the program to which the manual applies on the title page.
3159If the manual changes more frequently than the program or is independent
3160of it, you should also include an edition number@footnote{We have found
| 3044
3045The @code{@@end titlepage} command starts a new page and turns on page
3046numbering. (@xref{Headings, , Page Headings}, for details about how to
3047generate page headings.) All the material that you want to appear on
3048unnumbered pages should be put between the @code{@@titlepage} and
3049@code{@@end titlepage} commands. You can force the table of contents to
3050appear there with the @code{@@setcontentsaftertitlepage} command
3051(@pxref{Contents}).
3052
3053@findex page@r{, within @code{@@titlepage}}
3054By using the @code{@@page} command you can force a page break within the
3055region delineated by the @code{@@titlepage} and @code{@@end titlepage}
3056commands and thereby create more than one unnumbered page. This is how
3057the copyright page is produced. (The @code{@@titlepage} command might
3058perhaps have been better named the @code{@@titleandadditionalpages}
3059command, but that would have been rather long!)
3060
3061When you write a manual about a computer program, you should write the
3062version of the program to which the manual applies on the title page.
3063If the manual changes more frequently than the program or is independent
3064of it, you should also include an edition number@footnote{We have found
|
3161that it is helpful to refer to versions of manuals as `editions' and
3162versions of programs as `versions'; otherwise, we find we are liable to
3163confuse each other in conversation by referring to both the
3164documentation and the software with the same words.} for the manual.
| 3065that it is helpful to refer to versions of independent manuals as
3066`editions' and versions of programs as `versions'; otherwise, we find we
3067are liable to confuse each other in conversation by referring to both
3068the documentation and the software with the same words.} for the manual.
|
3165This helps readers keep track of which manual is for which version of
3166the program. (The `Top' node should also contain this information; see
| 3069This helps readers keep track of which manual is for which version of
3070the program. (The `Top' node should also contain this information; see
|
3167@ref{makeinfo top, , @code{@@top}}.)
| 3071@ref{The Top Node}.)
|
3168
3169Texinfo provides two main methods for creating a title page. One method
3170uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands
3171to generate a title page in which the words on the page are
3172centered.
3173
3174The second method uses the @code{@@title}, @code{@@subtitle}, and
3175@code{@@author} commands to create a title page with black rules under
3176the title and author lines and the subtitle text set flush to the
3177right hand side of the page. With this method, you do not specify any
3178of the actual formatting of the title page. You specify the text
3179you want, and Texinfo does the formatting.
3180
3181You may use either method, or you may combine them; see the examples in
3182the sections below.
3183
3184@findex shorttitlepage
3185@cindex Bastard title page
3186@cindex Title page, bastard
3187For extremely simple applications, and for the bastard title page in
3188traditional book front matter, Texinfo also provides a command
| 3072
3073Texinfo provides two main methods for creating a title page. One method
3074uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands
3075to generate a title page in which the words on the page are
3076centered.
3077
3078The second method uses the @code{@@title}, @code{@@subtitle}, and
3079@code{@@author} commands to create a title page with black rules under
3080the title and author lines and the subtitle text set flush to the
3081right hand side of the page. With this method, you do not specify any
3082of the actual formatting of the title page. You specify the text
3083you want, and Texinfo does the formatting.
3084
3085You may use either method, or you may combine them; see the examples in
3086the sections below.
3087
3088@findex shorttitlepage
3089@cindex Bastard title page
3090@cindex Title page, bastard
3091For extremely simple applications, and for the bastard title page in
3092traditional book front matter, Texinfo also provides a command
|
3189@code{@@shorttitlepage} which takes a single argument as the title. The
3190argument is typeset on a page by itself and followed by a blank page.
| 3093@code{@@shorttitlepage} which takes the rest of the line as the title.
3094The argument is typeset on a page by itself and followed by a blank
3095page.
|
3191
3192
3193@node titlefont center sp
3194@subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp}
3195@findex titlefont
3196@findex center
3197@findex sp @r{(titlepage line spacing)}
3198
3199You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center}
3200commands to create a title page for a printed document. (This is the
| 3096
3097
3098@node titlefont center sp
3099@subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp}
3100@findex titlefont
3101@findex center
3102@findex sp @r{(titlepage line spacing)}
3103
3104You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center}
3105commands to create a title page for a printed document. (This is the
|
3201first of the two methods for creating a title page in Texinfo.)@refill
| 3106first of the two methods for creating a title page in Texinfo.)
|
3202
3203Use the @code{@@titlefont} command to select a large font suitable for
3204the title itself. You can use @code{@@titlefont} more than once if you
3205have an especially long title.
3206
3207@need 700
3208For example:
3209
3210@example
3211@@titlefont@{Texinfo@}
3212@end example
3213
3214Use the @code{@@center} command at the beginning of a line to center
| 3107
3108Use the @code{@@titlefont} command to select a large font suitable for
3109the title itself. You can use @code{@@titlefont} more than once if you
3110have an especially long title.
3111
3112@need 700
3113For example:
3114
3115@example
3116@@titlefont@{Texinfo@}
3117@end example
3118
3119Use the @code{@@center} command at the beginning of a line to center
|
3215the remaining text on that line. Thus,@refill
| 3120the remaining text on that line. Thus,
|
3216
3217@example
3218@@center @@titlefont@{Texinfo@}
3219@end example
3220
3221@noindent
3222centers the title, which in this example is ``Texinfo'' printed
| 3121
3122@example
3123@@center @@titlefont@{Texinfo@}
3124@end example
3125
3126@noindent
3127centers the title, which in this example is ``Texinfo'' printed
|
3223in the title font.@refill
| 3128in the title font.
|
3224
| 3129
|
3225Use the @code{@@sp} command to insert vertical space. For example:@refill
| 3130Use the @code{@@sp} command to insert vertical space. For example:
|
3226
3227@example
3228@@sp 2
3229@end example
3230
3231@noindent
3232This inserts two blank lines on the printed page. (@xref{sp, ,
3233@code{@@sp}}, for more information about the @code{@@sp}
| 3131
3132@example
3133@@sp 2
3134@end example
3135
3136@noindent
3137This inserts two blank lines on the printed page. (@xref{sp, ,
3138@code{@@sp}}, for more information about the @code{@@sp}
|
3234command.)@refill
| 3139command.)
|
3235
| 3140
|
3236A template for this method looks like this:@refill
| 3141A template for this method looks like this:
|
3237
3238@example
3239@group
3240@@titlepage
3241@@sp 10
3242@@center @@titlefont@{@var{name-of-manual-when-printed}@}
3243@@sp 2
3244@@center @var{subtitle-if-any}
3245@@sp 2
3246@@center @var{author}
3247@dots{}
3248@@end titlepage
3249@end group
3250@end example
3251
| 3142
3143@example
3144@group
3145@@titlepage
3146@@sp 10
3147@@center @@titlefont@{@var{name-of-manual-when-printed}@}
3148@@sp 2
3149@@center @var{subtitle-if-any}
3150@@sp 2
3151@@center @var{author}
3152@dots{}
3153@@end titlepage
3154@end group
3155@end example
3156
|
3252The spacing of the example fits an 8.5 by 11 inch manual.@refill
| 3157The spacing of the example fits an 8.5 by 11 inch manual.
|
3253
3254
3255@node title subtitle author
3256@subsection @code{@@title}, @code{@@subtitle}, and @code{@@author}
3257@findex title
3258@findex subtitle
3259@findex author
3260
3261You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author}
3262commands to create a title page in which the vertical and horizontal
3263spacing is done for you automatically. This contrasts with the method
3264described in the previous section, in which the @code{@@sp} command is
3265needed to adjust vertical spacing.
3266
3267Write the @code{@@title}, @code{@@subtitle}, or @code{@@author}
3268commands at the beginning of a line followed by the title, subtitle,
| 3158
3159
3160@node title subtitle author
3161@subsection @code{@@title}, @code{@@subtitle}, and @code{@@author}
3162@findex title
3163@findex subtitle
3164@findex author
3165
3166You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author}
3167commands to create a title page in which the vertical and horizontal
3168spacing is done for you automatically. This contrasts with the method
3169described in the previous section, in which the @code{@@sp} command is
3170needed to adjust vertical spacing.
3171
3172Write the @code{@@title}, @code{@@subtitle}, or @code{@@author}
3173commands at the beginning of a line followed by the title, subtitle,
|
3269or author.@refill
| 3174or author.
|
3270
3271The @code{@@title} command produces a line in which the title is set
3272flush to the left-hand side of the page in a larger than normal font.
3273The title is underlined with a black rule. Only a single line is
3274allowed; the @code{@@*} command may not be used to break the title into
3275two lines. To handle very long titles, you may find it profitable to
3276use both @code{@@title} and @code{@@titlefont}; see the final example in
3277this section.
3278
3279The @code{@@subtitle} command sets subtitles in a normal-sized font
| 3175
3176The @code{@@title} command produces a line in which the title is set
3177flush to the left-hand side of the page in a larger than normal font.
3178The title is underlined with a black rule. Only a single line is
3179allowed; the @code{@@*} command may not be used to break the title into
3180two lines. To handle very long titles, you may find it profitable to
3181use both @code{@@title} and @code{@@titlefont}; see the final example in
3182this section.
3183
3184The @code{@@subtitle} command sets subtitles in a normal-sized font
|
3280flush to the right-hand side of the page.@refill
| 3185flush to the right-hand side of the page.
|
3281
3282The @code{@@author} command sets the names of the author or authors in
3283a middle-sized font flush to the left-hand side of the page on a line
3284near the bottom of the title page. The names are underlined with a
3285black rule that is thinner than the rule that underlines the title.
3286(The black rule only occurs if the @code{@@author} command line is
| 3186
3187The @code{@@author} command sets the names of the author or authors in
3188a middle-sized font flush to the left-hand side of the page on a line
3189near the bottom of the title page. The names are underlined with a
3190black rule that is thinner than the rule that underlines the title.
3191(The black rule only occurs if the @code{@@author} command line is
|
3287followed by an @code{@@page} command line.)@refill
| 3192followed by an @code{@@page} command line.)
|
3288
3289There are two ways to use the @code{@@author} command: you can write
3290the name or names on the remaining part of the line that starts with
| 3193
3194There are two ways to use the @code{@@author} command: you can write
3195the name or names on the remaining part of the line that starts with
|
3291an @code{@@author} command:@refill
| 3196an @code{@@author} command:
|
3292
3293@example
3294@@author by Jane Smith and John Doe
3295@end example
3296
3297@noindent
3298or you can write the names one above each other by using two (or more)
| 3197
3198@example
3199@@author by Jane Smith and John Doe
3200@end example
3201
3202@noindent
3203or you can write the names one above each other by using two (or more)
|
3299@code{@@author} commands:@refill
| 3204@code{@@author} commands:
|
3300
3301@example
3302@group
3303@@author Jane Smith
3304@@author John Doe
3305@end group
3306@end example
3307
3308@noindent
| 3205
3206@example
3207@group
3208@@author Jane Smith
3209@@author John Doe
3210@end group
3211@end example
3212
3213@noindent
|
3309(Only the bottom name is underlined with a black rule.)@refill
| 3214(Only the bottom name is underlined with a black rule.)
|
3310
3311@need 950
| 3215
3216@need 950
|
3312A template for this method looks like this:@refill
| 3217A template for this method looks like this:
|
3313
3314@example
3315@group
3316@@titlepage
3317@@title @var{name-of-manual-when-printed}
3318@@subtitle @var{subtitle-if-any}
3319@@subtitle @var{second-subtitle}
3320@@author @var{author}
3321@@page
3322@dots{}
3323@@end titlepage
3324@end group
3325@end example
3326
3327You may also combine the @code{@@titlefont} method described in the
3328previous section and @code{@@title} method described in this one. This
3329may be useful if you have a very long title. Here is a real-life example:
3330
3331@example
3332@group
3333@@titlepage
3334@@titlefont@{GNU Software@}
3335@@sp 1
3336@@title for MS-Windows and MS-DOS
3337@@subtitle Edition @@value@{e@} for Release @@value@{cde@}
3338@@author by Daniel Hagerty, Melissa Weisshaus
3339@@author and Eli Zaretskii
3340@end group
3341@end example
3342
3343@noindent
| 3218
3219@example
3220@group
3221@@titlepage
3222@@title @var{name-of-manual-when-printed}
3223@@subtitle @var{subtitle-if-any}
3224@@subtitle @var{second-subtitle}
3225@@author @var{author}
3226@@page
3227@dots{}
3228@@end titlepage
3229@end group
3230@end example
3231
3232You may also combine the @code{@@titlefont} method described in the
3233previous section and @code{@@title} method described in this one. This
3234may be useful if you have a very long title. Here is a real-life example:
3235
3236@example
3237@group
3238@@titlepage
3239@@titlefont@{GNU Software@}
3240@@sp 1
3241@@title for MS-Windows and MS-DOS
3242@@subtitle Edition @@value@{e@} for Release @@value@{cde@}
3243@@author by Daniel Hagerty, Melissa Weisshaus
3244@@author and Eli Zaretskii
3245@end group
3246@end example
3247
3248@noindent
|
3344(The use of @code{@@value} here is explained in @ref{value
3345Example,,@code{@@value} Example}.)
| 3249(The use of @code{@@value} here is explained in @ref{value Example}.
|
3346
3347
| 3250
3251
|
3348@node Copyright & Permissions
3349@subsection Copyright Page and Permissions
| 3252@node Copyright
3253@subsection Copyright Page
|
3350@cindex Copyright page
3351@cindex Printed permissions
3352@cindex Permissions, printed
3353
| 3254@cindex Copyright page
3255@cindex Printed permissions
3256@cindex Permissions, printed
3257
|
3354By international treaty, the copyright notice for a book should be
3355either on the title page or on the back of the title page. The
3356copyright notice should include the year followed by the name of the
3357organization or person who owns the copyright.@refill
| 3258By international treaty, the copyright notice for a book must be either
3259on the title page or on the back of the title page. When the copyright
3260notice is on the back of the title page, that page is customarily not
3261numbered. Therefore, in Texinfo, the information on the copyright page
3262should be within @code{@@titlepage} and @code{@@end titlepage}
3263commands.
|
3358
| 3264
|
3359When the copyright notice is on the back of the title page, that page
3360is customarily not numbered. Therefore, in Texinfo, the information
3361on the copyright page should be within @code{@@titlepage} and
3362@code{@@end titlepage} commands.@refill
3363
3364@findex vskip
3365@findex filll
3366@cindex Vertical whitespace (@samp{vskip})
| 3265@findex vskip @r{@TeX{} vertical skip}
3266@findex filll @r{@TeX{} dimension}
|
3367Use the @code{@@page} command to cause a page break. To push the
3368copyright notice and the other text on the copyright page towards the
| 3267Use the @code{@@page} command to cause a page break. To push the
3268copyright notice and the other text on the copyright page towards the
|
3369bottom of the page, you can write a somewhat mysterious line after the
3370@code{@@page} command that reads like this:@refill
| 3269bottom of the page, use the following incantantion after @code{@@page}:
|
3371
3372@example
3373@@vskip 0pt plus 1filll
3374@end example
3375
3376@noindent
3377This is a @TeX{} command that is not supported by the Info formatting
| 3270
3271@example
3272@@vskip 0pt plus 1filll
3273@end example
3274
3275@noindent
3276This is a @TeX{} command that is not supported by the Info formatting
|
3378commands. The @code{@@vskip} command inserts whitespace. The
3379@samp{0pt plus 1filll} means to put in zero points of mandatory whitespace,
3380and as much optional whitespace as needed to push the
3381following text to the bottom of the page. Note the use of three
3382@samp{l}s in the word @samp{filll}; this is the correct usage in
3383@TeX{}.@refill
| 3277commands. The @code{@@vskip} command inserts whitespace. The @samp{0pt
3278plus 1filll} means to put in zero points of mandatory whitespace, and as
3279much optional whitespace as needed to push the following text to the
3280bottom of the page. Note the use of three @samp{l}s in the word
3281@samp{filll}; this is correct.
|
3384
| 3282
|
3385@findex copyright
3386In a printed manual, the @code{@@copyright@{@}} command generates a
3387@samp{c} inside a circle. (In Info, it generates @samp{(C)}.) The
3388copyright notice itself has the following legally defined sequence:@refill
| 3283To insert the copyright text itself, write @code{@@insertcopying}
3284next (@pxref{Document Permissions}):
|
3389
3390@example
| 3285
3286@example
|
3391Copyright @copyright{} @var{year} @var{copyright-owner}
| 3287@@insertcopying
|
3392@end example
3393
| 3288@end example
3289
|
3394It is customary to put information on how to get a manual after the
3395copyright notice, followed by the copying permissions for the manual.
| 3290Follow the copying text by the publisher, ISBN numbers, cover art
3291credits, and other such information.
|
3396
| 3292
|
3397Permissions must be given here as well as in the summary segment within
3398@code{@@ifinfo} and @code{@@end ifinfo} that immediately follows the
3399header since this text appears only in the printed manual and the
3400@samp{ifinfo} text appears only in the Info file.
| 3293Here is an example putting all this together:
|
3401
| 3294
|
3402@xref{Documentation Copying,,GNU Free Documentation License}, for the
3403standard text.
| 3295@example
3296@@titlepage
3297@dots{}
3298@@page
3299@@vskip 0pt plus 1filll
3300@@insertcopying
|
3404
| 3301
|
| 3302Published by @dots{}
|
3405
| 3303
|
| 3304Cover art by @dots{}
3305@@end titlepage
3306@end example
3307
3308
|
3406@node end titlepage
3407@subsection Heading Generation
3408@findex end titlepage
3409@cindex Headings, page, begin to appear
3410@cindex Titlepage end starts headings
3411@cindex End titlepage starts headings
3412
| 3309@node end titlepage
3310@subsection Heading Generation
3311@findex end titlepage
3312@cindex Headings, page, begin to appear
3313@cindex Titlepage end starts headings
3314@cindex End titlepage starts headings
3315
|
3413An @code{@@end titlepage} command on a line by itself not only marks
3414the end of the title and copyright pages, but also causes @TeX{} to start
3415generating page headings and page numbers.
| 3316The @code{@@end titlepage} command must be written on a line by itself.
3317It not only marks the end of the title and copyright pages, but also
3318causes @TeX{} to start generating page headings and page numbers.
|
3416
3417To repeat what is said elsewhere, Texinfo has two standard page heading
3418formats, one for documents which are printed on one side of each sheet of paper
3419(single-sided printing), and the other for documents which are printed on both
3420sides of each sheet (double-sided printing).
| 3319
3320To repeat what is said elsewhere, Texinfo has two standard page heading
3321formats, one for documents which are printed on one side of each sheet of paper
3322(single-sided printing), and the other for documents which are printed on both
3323sides of each sheet (double-sided printing).
|
3421(@xref{setchapternewpage, ,@code{@@setchapternewpage}}.)
3422You can specify these formats in different ways:@refill
| 3324You can specify these formats in different ways:
|
3423
3424@itemize @bullet
3425@item
3426The conventional way is to write an @code{@@setchapternewpage} command
3427before the title page commands, and then have the @code{@@end
3428titlepage} command start generating page headings in the manner desired.
| 3325
3326@itemize @bullet
3327@item
3328The conventional way is to write an @code{@@setchapternewpage} command
3329before the title page commands, and then have the @code{@@end
3330titlepage} command start generating page headings in the manner desired.
|
3429(@xref{setchapternewpage, , @code{@@setchapternewpage}}.)@refill
| 3331(@xref{setchapternewpage}.)
|
3430
3431@item
3432Alternatively, you can use the @code{@@headings} command to prevent page
3433headings from being generated or to start them for either single or
3434double-sided printing. (Write an @code{@@headings} command immediately
3435after the @code{@@end titlepage} command. @xref{headings on off, , The
3436@code{@@headings} Command}, for more information.)@refill
3437
3438@item
3439Or, you may specify your own page heading and footing format.
3440@xref{Headings, , Page Headings}, for detailed
| 3332
3333@item
3334Alternatively, you can use the @code{@@headings} command to prevent page
3335headings from being generated or to start them for either single or
3336double-sided printing. (Write an @code{@@headings} command immediately
3337after the @code{@@end titlepage} command. @xref{headings on off, , The
3338@code{@@headings} Command}, for more information.)@refill
3339
3340@item
3341Or, you may specify your own page heading and footing format.
3342@xref{Headings, , Page Headings}, for detailed
|
3441information about page headings and footings.@refill
| 3343information about page headings and footings.
|
3442@end itemize
3443
3444Most documents are formatted with the standard single-sided or
3445double-sided format, using @code{@@setchapternewpage odd} for
3446double-sided printing and no @code{@@setchapternewpage} command for
| 3344@end itemize
3345
3346Most documents are formatted with the standard single-sided or
3347double-sided format, using @code{@@setchapternewpage odd} for
3348double-sided printing and no @code{@@setchapternewpage} command for
|
3447single-sided printing.@refill
| 3349single-sided printing.
|
3448
| 3350
|
3449@node headings on off, , end titlepage, Titlepage & Copyright Page
3450@comment node-name, next, previous, up
| 3351
3352@node headings on off
|
3451@subsection The @code{@@headings} Command
3452@findex headings
3453
3454The @code{@@headings} command is rarely used. It specifies what kind of
3455page headings and footings to print on each page. Usually, this is
3456controlled by the @code{@@setchapternewpage} command. You need the
3457@code{@@headings} command only if the @code{@@setchapternewpage} command
3458does not do what you want, or if you want to turn off pre-defined page
3459headings prior to defining your own. Write an @code{@@headings} command
3460immediately after the @code{@@end titlepage} command.@refill
3461
3462You can use @code{@@headings} as follows:@refill
3463
3464@table @code
3465@item @@headings off
3466Turn off printing of page headings.@refill
3467
3468@item @@headings single
3469Turn on page headings appropriate for single-sided printing.
3470@refill
3471
3472@item @@headings double
3473@itemx @@headings on
3474Turn on page headings appropriate for double-sided printing. The two
3475commands, @code{@@headings on} and @code{@@headings double}, are
3476synonymous.@refill
3477
3478@item @@headings singleafter
3479@itemx @@headings doubleafter
3480Turn on @code{single} or @code{double} headings, respectively, after the
3481current page is output.
3482
3483@item @@headings on
3484Turn on page headings: @code{single} if @samp{@@setchapternewpage
3485on}, @code{double} otherwise.
3486@end table
3487
3488For example, suppose you write @code{@@setchapternewpage off} before the
3489@code{@@titlepage} command to tell @TeX{} to start a new chapter on the
3490same page as the end of the last chapter. This command also causes
3491@TeX{} to typeset page headers for single-sided printing. To cause
3492@TeX{} to typeset for double sided printing, write @code{@@headings
3493double} after the @code{@@end titlepage} command.
3494
3495You can stop @TeX{} from generating any page headings at all by
3496writing @code{@@headings off} on a line of its own immediately after the
3497line containing the @code{@@end titlepage} command, like this:@refill
3498
3499@example
3500@@end titlepage
3501@@headings off
3502@end example
3503
3504@noindent
3505The @code{@@headings off} command overrides the @code{@@end titlepage}
3506command, which would otherwise cause @TeX{} to print page
3507headings.@refill
3508
3509You can also specify your own style of page heading and footing.
3510@xref{Headings, , Page Headings}, for more information.@refill
3511
3512
3513@node The Top Node
3514@section The `Top' Node and Master Menu
| 3353@subsection The @code{@@headings} Command
3354@findex headings
3355
3356The @code{@@headings} command is rarely used. It specifies what kind of
3357page headings and footings to print on each page. Usually, this is
3358controlled by the @code{@@setchapternewpage} command. You need the
3359@code{@@headings} command only if the @code{@@setchapternewpage} command
3360does not do what you want, or if you want to turn off pre-defined page
3361headings prior to defining your own. Write an @code{@@headings} command
3362immediately after the @code{@@end titlepage} command.@refill
3363
3364You can use @code{@@headings} as follows:@refill
3365
3366@table @code
3367@item @@headings off
3368Turn off printing of page headings.@refill
3369
3370@item @@headings single
3371Turn on page headings appropriate for single-sided printing.
3372@refill
3373
3374@item @@headings double
3375@itemx @@headings on
3376Turn on page headings appropriate for double-sided printing. The two
3377commands, @code{@@headings on} and @code{@@headings double}, are
3378synonymous.@refill
3379
3380@item @@headings singleafter
3381@itemx @@headings doubleafter
3382Turn on @code{single} or @code{double} headings, respectively, after the
3383current page is output.
3384
3385@item @@headings on
3386Turn on page headings: @code{single} if @samp{@@setchapternewpage
3387on}, @code{double} otherwise.
3388@end table
3389
3390For example, suppose you write @code{@@setchapternewpage off} before the
3391@code{@@titlepage} command to tell @TeX{} to start a new chapter on the
3392same page as the end of the last chapter. This command also causes
3393@TeX{} to typeset page headers for single-sided printing. To cause
3394@TeX{} to typeset for double sided printing, write @code{@@headings
3395double} after the @code{@@end titlepage} command.
3396
3397You can stop @TeX{} from generating any page headings at all by
3398writing @code{@@headings off} on a line of its own immediately after the
3399line containing the @code{@@end titlepage} command, like this:@refill
3400
3401@example
3402@@end titlepage
3403@@headings off
3404@end example
3405
3406@noindent
3407The @code{@@headings off} command overrides the @code{@@end titlepage}
3408command, which would otherwise cause @TeX{} to print page
3409headings.@refill
3410
3411You can also specify your own style of page heading and footing.
3412@xref{Headings, , Page Headings}, for more information.@refill
3413
3414
3415@node The Top Node
3416@section The `Top' Node and Master Menu
|
3515@cindex @samp{@r{Top}} node
3516@cindex Master menu
| 3417@cindex Top node
|
3517@cindex Node, `Top'
3518
| 3418@cindex Node, `Top'
3419
|
3519The `Top' node is the node from which you enter an Info file.@refill
| 3420The `Top' node is the node in which a reader enters an Info manual. As
3421such, it should begin with the @code{@@insertcopying} command
3422(@pxref{Document Permissions}) to provide a brief description of the
3423manual (including the version number) and copying permissions, and end
3424with a master menu for the whole manual. Of course you should include
3425any other general information you feel a reader would find helpful.
|
3520
| 3426
|
3521A `Top' node should contain a brief description of the Info file and an
3522extensive, master menu for the whole Info file.
3523This helps the reader understand what the Info file is
3524about. Also, you should write the version number of the program to
3525which the Info file applies; or, at least, the edition number.@refill
| 3427@findex top
3428It is also conventional to write an @code{@@top} sectioning command line
3429containing the title of the document immediately after the @code{@@node
3430Top} line (@pxref{makeinfo top command, , The @code{@@top} Sectioning
3431Command}).
|
3526
| 3432
|
3527The contents of the `Top' node should appear only in the Info file; none
3528of it should appear in printed output, so enclose it between
3529@code{@@ifinfo} and @code{@@end ifinfo} commands. (@TeX{} does not
| 3433The contents of the `Top' node should appear only in the online output;
3434none of it should appear in printed output, so enclose it between
3435@code{@@ifnottex} and @code{@@end ifnottex} commands. (@TeX{} does not
|
3530print either an @code{@@node} line or a menu; they appear only in Info;
3531strictly speaking, you are not required to enclose these parts between
| 3436print either an @code{@@node} line or a menu; they appear only in Info;
3437strictly speaking, you are not required to enclose these parts between
|
3532@code{@@ifinfo} and @code{@@end ifinfo}, but it is simplest to do so.
3533@xref{Conditionals, , Conditionally Visible Text}.)@refill
| 3438@code{@@ifnottex} and @code{@@end ifnottext}, but it is simplest to do
3439so. @xref{Conditionals, , Conditionally Visible Text}.)
|
3534
3535@menu
| 3440
3441@menu
|
3536* Title of Top Node:: Sketch what the file is about.
3537* Master Menu Parts:: A master menu has three or more parts.
| 3442* Top Node Example::
3443* Master Menu Parts::
|
3538@end menu
3539
3540
| 3444@end menu
3445
3446
|
3541@node Title of Top Node
3542@subsection `Top' Node Title
| 3447@node Top Node Example
3448@subsection Top Node Example
|
3543
| 3449
|
3544Sometimes, you will want to place an @code{@@top} sectioning command
3545line containing the title of the document immediately after the
3546@code{@@node Top} line (@pxref{makeinfo top command, , The @code{@@top}
3547Sectioning Command}, for more information).@refill
| 3450@cindex Top node example
|
3548
| 3451
|
3549For example, the beginning of the Top node of this manual contains an
3550@code{@@top} sectioning command, a short description, and edition and
3551version information. It looks like this:@refill
| 3452Here is an example of a Top node.
|
3552
3553@example
3554@group
| 3453
3454@example
3455@group
|
3555@dots{}
3556@@end titlepage
3557
| |
3558@@ifnottex
| 3456@@ifnottex
|
3559@@node Top, Copying, , (dir)
3560@@top Texinfo
| 3457@@node Top
3458@@top Sample Title
|
3561
| 3459
|
3562Texinfo is a documentation system@dots{}
| 3460@@insertcopying
|
3563@end group
3564
| 3461@end group
3462
|
3565@group
3566This is edition@dots{}
3567@dots{}
3568@@end ifnottex
3569@end group
| 3463Additional general information.
|
3570
3571@group
3572@@menu
| 3464
3465@group
3466@@menu
|
3573* Copying:: Texinfo is freely
3574 redistributable.
3575* Overview:: What is Texinfo?
| 3467* First Chapter::
3468* Second Chapter::
|
3576@dots{}
| 3469@dots{}
|
| 3470* Index::
|
3577@end group
3578@@end menu
3579@end example
3580
| 3471@end group
3472@@end menu
3473@end example
3474
|
3581In a `Top' node, the `Previous', and `Up' nodes usually refer to the top
3582level directory of the whole Info system, which is called @samp{(dir)}.
3583The `Next' node refers to the first node that follows the main or master
3584menu, which is usually the copying permissions, introduction, or first
3585chapter.@refill
| |
3586
| 3475
|
3587@node Master Menu Parts, , Title of Top Node, The Top Node
| 3476@node Master Menu Parts
|
3588@subsection Parts of a Master Menu
| 3477@subsection Parts of a Master Menu
|
3589@cindex Master menu parts
| 3478@cindex Master menu
3479@cindex Menu, master
|
3590@cindex Parts of a master menu
3591
3592A @dfn{master menu} is a detailed main menu listing all the nodes in a
3593file.
3594
3595A master menu is enclosed in @code{@@menu} and @code{@@end menu}
| 3480@cindex Parts of a master menu
3481
3482A @dfn{master menu} is a detailed main menu listing all the nodes in a
3483file.
3484
3485A master menu is enclosed in @code{@@menu} and @code{@@end menu}
|
3596commands and does not appear in the printed document.@refill
| 3486commands and does not appear in the printed document.
|
3597
| 3487
|
3598Generally, a master menu is divided into parts.@refill
| 3488Generally, a master menu is divided into parts.
|
3599
3600@itemize @bullet
3601@item
3602The first part contains the major nodes in the Texinfo file: the nodes
| 3489
3490@itemize @bullet
3491@item
3492The first part contains the major nodes in the Texinfo file: the nodes
|
3603for the chapters, chapter-like sections, and the appendices.@refill
| 3493for the chapters, chapter-like sections, and the appendices.
|
3604
3605@item
| 3494
3495@item
|
3606The second part contains nodes for the indices.@refill
| 3496The second part contains nodes for the indices.
|
3607
3608@item
3609The third and subsequent parts contain a listing of the other, lower
3610level nodes, often ordered by chapter. This way, rather than go
3611through an intermediary menu, an inquirer can go directly to a
3612particular node when searching for specific information. These menu
3613items are not required; add them if you think they are a
3614convenience. If you do use them, put @code{@@detailmenu} before the
3615first one, and @code{@@end detailmenu} after the last; otherwise,
3616@code{makeinfo} will get confused.
3617@end itemize
3618
3619Each section in the menu can be introduced by a descriptive line. So
3620long as the line does not begin with an asterisk, it will not be
3621treated as a menu entry. (@xref{Writing a Menu}, for more
| 3497
3498@item
3499The third and subsequent parts contain a listing of the other, lower
3500level nodes, often ordered by chapter. This way, rather than go
3501through an intermediary menu, an inquirer can go directly to a
3502particular node when searching for specific information. These menu
3503items are not required; add them if you think they are a
3504convenience. If you do use them, put @code{@@detailmenu} before the
3505first one, and @code{@@end detailmenu} after the last; otherwise,
3506@code{makeinfo} will get confused.
3507@end itemize
3508
3509Each section in the menu can be introduced by a descriptive line. So
3510long as the line does not begin with an asterisk, it will not be
3511treated as a menu entry. (@xref{Writing a Menu}, for more
|
3622information.)@refill
| 3512information.)
|
3623
3624For example, the master menu for this manual looks like the following
| 3513
3514For example, the master menu for this manual looks like the following
|
3625(but has many more entries):@refill
| 3515(but has many more entries):
|
3626
3627@example
3628@group
3629@@menu
| 3516
3517@example
3518@group
3519@@menu
|
3630* Copying:: Texinfo is freely
3631 redistributable.
3632* Overview:: What is Texinfo?
3633* Texinfo Mode:: Special features in GNU Emacs.
| 3520* Copying Conditions:: Your rights.
3521* Overview:: Texinfo in brief.
|
3634@dots{}
| 3522@dots{}
|
3635@dots{}
| |
3636@end group
3637@group
3638* Command and Variable Index::
| 3523@end group
3524@group
3525* Command and Variable Index::
|
3639 An entry for each @@-command.
3640* Concept Index:: An entry for each concept.
| 3526* Concept Index::
|
3641@end group
3642
3643@group
3644@@detailmenu
3645 --- The Detailed Node Listing ---
3646
3647Overview of Texinfo
3648
| 3527@end group
3528
3529@group
3530@@detailmenu
3531 --- The Detailed Node Listing ---
3532
3533Overview of Texinfo
3534
|
3649* Info Files:: What is an Info file?
3650* Printed Manuals:: Characteristics of
3651 a printed manual.
| 3535* Reporting Bugs:: @dots{}
|
3652@dots{}
| 3536@dots{}
|
3653@dots{}
| |
3654@end group
3655
3656@group
| 3537@end group
3538
3539@group
|
3657Using Texinfo Mode
| 3540Beginning a Texinfo File
|
3658
| 3541
|
3659* Info on a Region:: Formatting part of a file
3660 for Info.
| 3542* Sample Beginning:: @dots{}
|
3661@dots{}
| 3543@dots{}
|
3662@dots{}
| |
3663@@end detailmenu
3664@@end menu
3665@end group
3666@end example
3667
| 3544@@end detailmenu
3545@@end menu
3546@end group
3547@end example
3548
|
| 3549
3550@node Global Document Commands
3551@section Global Document Commands
3552@cindex Global Document Commands
3553
3554Besides the basic commands mentioned in the previous sections, here are
3555additional commands which affect the document as a whole. They are
3556generally all given before the Top node, if they are given at all.
3557
3558@menu
3559* documentdescription:: Document summary for the HTML output.
3560* setchapternewpage:: Start chapters on right-hand pages.
3561* paragraphindent:: Specify paragraph indentation.
3562* exampleindent:: Specify environment indentation.
3563@end menu
3564
3565
3566@node documentdescription
3567@subsection @code{@@documentdescription}: Summary text
3568@cindex Document description
3569@cindex Description of document
3570@cindex Summary of document
3571@cindex Abstract of document
3572@cindex <meta> HTML tag, and document description
3573@findex documentdescription
3574
3575When producing HTML output for a document, @command{makeinfo} writes a
3576@samp{<meta>} element in the @samp{<head>} to give some idea of the
3577content of the document. By default, this @dfn{description} is the title
3578of the document, taken from the @code{@@settitle} command
3579(@pxref{settitle}). To change this, use the @code{@@documentdescription}
3580environment, as in:
3581
3582@example
3583@@documentdescription
3584descriptive text.
3585@@end documentdescription
3586@end example
3587
3588@noindent
3589This will produce the following output in the @samp{<head>} of the HTML:
3590
3591@example
3592<meta name=description content="descriptive text.">
3593@end example
3594
3595@code{@@documentdescription} must be specified before the first node of
3596the document.
3597
3598
3599@node setchapternewpage
3600@subsection @code{@@setchapternewpage}:
3601@cindex Starting chapters
3602@cindex Pages, starting odd
3603@findex setchapternewpage
3604
3605In an officially bound book, text is usually printed on both sides of
3606the paper, chapters start on right-hand pages, and right-hand pages have
3607odd numbers. But in short reports, text often is printed only on one
3608side of the paper. Also in short reports, chapters sometimes do not
3609start on new pages, but are printed on the same page as the end of the
3610preceding chapter, after a small amount of vertical whitespace.
3611
3612You can use the @code{@@setchapternewpage} command with various
3613arguments to specify how @TeX{} should start chapters and whether it
3614should format headers for printing on one or both sides of the paper
3615(single-sided or double-sided printing).
3616
3617Write the @code{@@setchapternewpage} command at the beginning of a
3618line followed by its argument.
3619
3620For example, you would write the following to cause each chapter to
3621start on a fresh odd-numbered page:
3622
3623@example
3624@@setchapternewpage odd
3625@end example
3626
3627You can specify one of three alternatives with the
3628@code{@@setchapternewpage} command:
3629
3630@table @asis
3631
3632@item @code{@@setchapternewpage off}
3633Cause @TeX{} to typeset a new chapter on the same page as the last
3634chapter, after skipping some vertical whitespace. Also, cause @TeX{} to
3635format page headers for single-sided printing.
3636
3637@item @code{@@setchapternewpage on}
3638Cause @TeX{} to start new chapters on new pages and to format page
3639headers for single-sided printing. This is the form most often used for
3640short reports or personal printing. This is the default.
3641
3642@item @code{@@setchapternewpage odd}
3643Cause @TeX{} to start new chapters on new, odd-numbered pages
3644(right-handed pages) and to typeset for double-sided printing. This is
3645the form most often used for books and manuals.
3646@end table
3647
3648Texinfo does not have an @code{@@setchapternewpage even} command,
3649because there is no printing tradition of starting chapters or books on
3650an even-numbered page.
3651
3652If you don't like the default headers that @code{@@setchapternewpage}
3653sets, you can explicit control them with the @code{@@headings} command.
3654@xref{headings on off, , The @code{@@headings} Command}.
3655
3656At the beginning of a manual or book, pages are not numbered---for
3657example, the title and copyright pages of a book are not numbered. By
3658convention, table of contents and frontmatter pages are numbered with
3659roman numerals and not in sequence with the rest of the document.
3660
3661Since an Info file does not have pages, the @code{@@setchapternewpage}
3662command has no effect on it.
3663
3664We recommend not including any @code{@@setchapternewpage} command in
3665your manual sources at all, since the desired output is not intrinsic to
3666the document. For a particular hard copy run, if you don't want the
3667default option (no blank pages, same headers on all pages) use the
3668@option{--texinfo} option to @command{texi2dvi} to specify the output
3669you want.
3670
3671
3672@node paragraphindent
3673@subsection Paragraph Indenting
3674@cindex Indenting paragraphs, control of
3675@cindex Paragraph indentation control
3676@findex paragraphindent
3677
3678The Texinfo processors may insert whitespace at the beginning of the
3679first line of each paragraph, thereby indenting that paragraph. You can
3680use the @code{@@paragraphindent} command to specify this indentation.
3681Write an @code{@@paragraphindent} command at the beginning of a line
3682followed by either @samp{asis} or a number:
3683
3684@example
3685@@paragraphindent @var{indent}
3686@end example
3687
3688The indentation is according to the value of @var{indent}:
3689
3690@table @asis
3691@item @code{asis}
3692Do not change the existing indentation (not implemented in @TeX{}).
3693
3694@item @code{none}
3695@itemx 0
3696Omit all indentation.
3697
3698@item @var{n}
3699Indent by @var{n} space characters in Info output, by @var{n} ems in
3700@TeX{}.
3701
3702@end table
3703
3704The default value of @var{indent} is 3. @code{@@paragraphindent} is
3705ignored for HTML output.
3706
3707It is best to write the @code{@@paragraphindent} command before the
3708end-of-header line at the beginning of a Texinfo file, so the region
3709formatting commands indent paragraphs as specified. @xref{Start of
3710Header}.
3711
3712A peculiarity of the @code{texinfo-format-buffer} and
3713@code{texinfo-format-region} commands is that they do not indent (nor
3714fill) paragraphs that contain @code{@@w} or @code{@@*} commands.
3715@xref{Refilling Paragraphs}, for further information.
3716
3717
3718@node exampleindent
3719@subsection @code{@@exampleindent}: Environment Indenting
3720@cindex Indenting environments
3721@cindex Environment indentation
3722@cindex Example indentation
3723@findex exampleindent
3724
3725The Texinfo processors indent each line of @code{@@example} and similar
3726environments. You can use the @code{@@exampleindent} command to specify
3727this indentation. Write an @code{@@exampleindent} command at the
3728beginning of a line followed by either @samp{asis} or a number:
3729
3730@example
3731@@exampleindent @var{indent}
3732@end example
3733
3734The indentation is according to the value of @var{indent}:
3735
3736@table @asis
3737@item @code{asis}
3738Do not change the existing indentation (not implemented in @TeX{}).
3739
3740@item 0
3741Omit all indentation.
3742
3743@item @var{n}
3744Indent environments by @var{n} space characters in Info output, by
3745@var{n} ems in @TeX{}.
3746
3747@end table
3748
3749The default value of @var{indent} is 5. @code{@@exampleindent} is
3750ignored for HTML output.
3751
3752It is best to write the @code{@@exampleindent} command before the
3753end-of-header line at the beginning of a Texinfo file, so the region
3754formatting commands indent paragraphs as specified. @xref{Start of
3755Header}.
3756
3757
|
3668@node Software Copying Permissions
| 3758@node Software Copying Permissions
|
3669@comment node-name, next, previous, up
| |
3670@section Software Copying Permissions
3671@cindex Software copying permissions
3672@cindex Copying software
3673@cindex Distribution
3674@cindex License agreement
3675
3676If the Texinfo file has a section containing the ``General Public
| 3759@section Software Copying Permissions
3760@cindex Software copying permissions
3761@cindex Copying software
3762@cindex Distribution
3763@cindex License agreement
3764
3765If the Texinfo file has a section containing the ``General Public
|
3677License'' and the distribution information and a warranty disclaimer
3678for the software that is documented, this section usually follows the
3679`Top' node. The General Public License is very important to Project
| 3766License'' and the distribution information and a warranty disclaimer for
3767the software that is documented, we recommend placing this right after
3768the `Top' node. The General Public License is very important to Project
|
3680GNU software. It ensures that you and others will continue to have a
| 3769GNU software. It ensures that you and others will continue to have a
|
3681right to use and share the software.@refill
| 3770right to use and share the software.
|
3682
3683The copying and distribution information and the disclaimer are followed
| 3771
3772The copying and distribution information and the disclaimer are followed
|
3684by an introduction or else by the first chapter of the manual.@refill
| 3773by an introduction or else by the first chapter of the manual.
|
3685
3686@cindex Introduction, as part of file
3687Although an introduction is not a required part of a Texinfo file, it
3688is very helpful. Ideally, it should state clearly and concisely what
3689the file is about and who would be interested in reading it. In
3690general, an introduction would follow the licensing and distribution
3691information, although sometimes people put it earlier in the document.
| 3774
3775@cindex Introduction, as part of file
3776Although an introduction is not a required part of a Texinfo file, it
3777is very helpful. Ideally, it should state clearly and concisely what
3778the file is about and who would be interested in reading it. In
3779general, an introduction would follow the licensing and distribution
3780information, although sometimes people put it earlier in the document.
|
3692Usually, an introduction is put in an @code{@@unnumbered} section.
3693(@xref{unnumbered & appendix, , The @code{@@unnumbered} and
3694@code{@@appendix} Commands}.)@refill
| |
3695
| 3781
|
3696@node Ending a File, Structuring, Beginning a File, Top
3697@comment node-name, next, previous, up
| 3782
3783@node Ending a File
|
3698@chapter Ending a Texinfo File
3699@cindex Ending a Texinfo file
3700@cindex Texinfo file ending
3701@cindex File ending
3702@findex bye
3703
3704The end of a Texinfo file should include commands to create indices and
| 3784@chapter Ending a Texinfo File
3785@cindex Ending a Texinfo file
3786@cindex Texinfo file ending
3787@cindex File ending
3788@findex bye
3789
3790The end of a Texinfo file should include commands to create indices and
|
3705(usually) to generate detailed and summary tables of contents. And it
3706must include the @code{@@bye} command that marks the last line processed
3707by @TeX{}.@refill
| 3791(perhaps) to generate both the full and summary tables of contents.
3792Finally, it must include the @code{@@bye} command that marks the last
3793line to be processed.
|
3708
3709@need 700
3710For example:
3711
3712@example
| 3794
3795@need 700
3796For example:
3797
3798@example
|
3713@@node Concept Index, , Variables Index, Top
3714@@c node-name, next, previous, up
3715@@unnumbered Concept Index
| 3799@@node Index
3800@@unnumbered Index
|
3716
3717@@printindex cp
3718
| 3801
3802@@printindex cp
3803
|
| 3804@@shortcontents
|
3719@@contents
| 3805@@contents
|
| 3806
|
3720@@bye
3721@end example
3722
3723@menu
3724* Printing Indices & Menus:: How to print an index in hardcopy and
3725 generate index menus in Info.
3726* Contents:: How to create a table of contents.
3727* File End:: How to mark the end of a file.
3728@end menu
3729
| 3807@@bye
3808@end example
3809
3810@menu
3811* Printing Indices & Menus:: How to print an index in hardcopy and
3812 generate index menus in Info.
3813* Contents:: How to create a table of contents.
3814* File End:: How to mark the end of a file.
3815@end menu
3816
|
3730@node Printing Indices & Menus, Contents, Ending a File, Ending a File
3731@comment node-name, next, previous, up
3732@section Index Menus and Printing an Index
| 3817
3818@node Printing Indices & Menus
3819@section Printing Indices and Menus
|
3733@findex printindex
3734@cindex Printing an index
3735@cindex Indices, printing and menus
3736@cindex Generating menus with indices
3737@cindex Menus generated with indices
3738
| 3820@findex printindex
3821@cindex Printing an index
3822@cindex Indices, printing and menus
3823@cindex Generating menus with indices
3824@cindex Menus generated with indices
3825
|
3739To print an index means to include it as part of a manual or Info
3740file. This does not happen automatically just because you use
3741@code{@@cindex} or other index-entry generating commands in the
3742Texinfo file; those just cause the raw data for the index to be
3743accumulated. To generate an index, you must include the
3744@code{@@printindex} command at the place in the document where you
3745want the index to appear. Also, as part of the process of creating a
3746printed manual, you must run a program called @code{texindex}
3747(@pxref{Hardcopy}) to sort the raw data to produce a sorted
3748index file. The sorted index file is what is actually used to
3749print the index.@refill
| 3826To print an index means to include it as part of a manual or Info file.
3827This does not happen automatically just because you use @code{@@cindex}
3828or other index-entry generating commands in the Texinfo file; those just
3829cause the raw data for the index to be accumulated. To generate an
3830index, you must include the @code{@@printindex} command at the place in
3831the document where you want the index to appear. Also, as part of the
3832process of creating a printed manual, you must run a program called
3833@code{texindex} (@pxref{Hardcopy}) to sort the raw data to produce a
3834sorted index file. The sorted index file is what is actually used to
3835print the index.
|
3750
| 3836
|
3751Texinfo offers six different types of predefined index: the concept
3752index, the function index, the variables index, the keystroke index, the
3753program index, and the data type index (@pxref{Predefined Indices}). Each
3754index type has a two-letter name: @samp{cp}, @samp{fn}, @samp{vr},
3755@samp{ky}, @samp{pg}, and @samp{tp}. You may merge indices, or put them
3756into separate sections (@pxref{Combining Indices}); or you may define
3757your own indices (@pxref{New Indices, , Defining New Indices}).@refill
| 3837Texinfo offers six separate types of predefined index, each with a
3838two-letter abbreviation, as illustrated in the following table.
3839However, you may merge indices (@pxref{Combining Indices}) or define
3840your own indices (@pxref{New Indices}).
|
3758
| 3841
|
3759The @code{@@printindex} command takes a two-letter index name, reads
3760the corresponding sorted index file and formats it appropriately into
3761an index.@refill
| 3842Here are the predefined indices, their abbreviations, and the
3843corresponding index entry commands:
|
3762
| 3844
|
3763@ignore
3764The two-letter index names are:
3765
| |
3766@table @samp
3767@item cp
| 3845@table @samp
3846@item cp
|
3768concept index
| 3847concept index (@code{@@cindex})
|
3769@item fn
| 3848@item fn
|
3770function index
| 3849function index (@code{@@findex})
|
3771@item vr
| 3850@item vr
|
3772variable index
| 3851variable index (@code{@@index})
|
3773@item ky
| 3852@item ky
|
3774key index
| 3853key index (@code{@@kindex})
|
3775@item pg
| 3854@item pg
|
3776program index
| 3855program index (@code{@@pindex})
|
3777@item tp
| 3856@item tp
|
3778data type index
| 3857data type index (@code{@@tindex})
|
3779@end table
| 3858@end table
|
3780@end ignore
3781The @code{@@printindex} command does not generate a chapter heading
3782for the index. Consequently, you should precede the
3783@code{@@printindex} command with a suitable section or chapter command
3784(usually @code{@@unnumbered}) to supply the chapter heading and put
3785the index into the table of contents. Precede the @code{@@unnumbered}
3786command with an @code{@@node} line.@refill
| |
3787
| 3859
|
3788@need 1200
| 3860The @code{@@printindex} command takes a two-letter index abbreviation,
3861reads the corresponding sorted index file and formats it appropriately
3862into an index.
3863
3864The @code{@@printindex} command does not generate a chapter heading for
3865the index. Consequently, you should precede the @code{@@printindex}
3866command with a suitable section or chapter command (usually
3867@code{@@appendix} or @code{@@unnumbered}) to supply the chapter heading
3868and put the index into the table of contents. Precede the
3869@code{@@unnumbered} command with an @code{@@node} line.
3870
|
3789For example:
3790
3791@smallexample
3792@group
| 3871For example:
3872
3873@smallexample
3874@group
|
3793@@node Variable Index, Concept Index, Function Index, Top
3794@@comment node-name, next, previous, up
| 3875@@node Variable Index
|
3795@@unnumbered Variable Index
3796
3797@@printindex vr
3798@end group
3799
3800@group
| 3876@@unnumbered Variable Index
3877
3878@@printindex vr
3879@end group
3880
3881@group
|
3801@@node Concept Index, , Variable Index, Top
3802@@comment node-name, next, previous, up
| 3882@@node Concept Index
|
3803@@unnumbered Concept Index
3804
3805@@printindex cp
3806@end group
3807@end smallexample
3808
3809@noindent
| 3883@@unnumbered Concept Index
3884
3885@@printindex cp
3886@end group
3887@end smallexample
3888
3889@noindent
|
3810Readers often prefer that the concept index come last in a book,
3811since that makes it easiest to find. Having just one index helps
3812readers also, since then they have only one place to look
3813(@pxref{synindex}).
| |
3814
| 3890
|
| 3891We recommend placing the concept index last, since that makes it easiest
3892to find. We also recommend having a single index whenever possible,
3893since then readers have only one place to look (@pxref{Combining Indices}).
|
3815
| 3894
|
| 3895
|
3816@node Contents
3817@section Generating a Table of Contents
3818@cindex Table of contents
3819@cindex Contents, Table of
3820@cindex Short table of contents
3821@findex contents
3822@findex summarycontents
3823@findex shortcontents
3824
3825The @code{@@chapter}, @code{@@section}, and other structuring commands
3826supply the information to make up a table of contents, but they do not
3827cause an actual table to appear in the manual. To do this, you must use
3828the @code{@@contents} and/or @code{@@summarycontents} command(s).
3829
3830@table @code
3831@item @@contents
3832Generate a table of contents in a printed manual, including all
3833chapters, sections, subsections, etc., as well as appendices and
| 3896@node Contents
3897@section Generating a Table of Contents
3898@cindex Table of contents
3899@cindex Contents, Table of
3900@cindex Short table of contents
3901@findex contents
3902@findex summarycontents
3903@findex shortcontents
3904
3905The @code{@@chapter}, @code{@@section}, and other structuring commands
3906supply the information to make up a table of contents, but they do not
3907cause an actual table to appear in the manual. To do this, you must use
3908the @code{@@contents} and/or @code{@@summarycontents} command(s).
3909
3910@table @code
3911@item @@contents
3912Generate a table of contents in a printed manual, including all
3913chapters, sections, subsections, etc., as well as appendices and
|
3834unnumbered chapters. (Headings generated by the @code{@@heading}
3835series of commands do not appear in the table of contents.)
| 3914unnumbered chapters. Headings generated by the @code{@@heading}
3915series of commands do not appear in the table of contents.
|
3836
3837@item @@shortcontents
3838@itemx @@summarycontents
| 3916
3917@item @@shortcontents
3918@itemx @@summarycontents
|
3839(@code{@@summarycontents} is a synonym for @code{@@shortcontents}; the
3840two commands are exactly the same.)@refill
| 3919(@code{@@summarycontents} is a synonym for @code{@@shortcontents}.)
|
3841
3842Generate a short or summary table of contents that lists only the
| 3920
3921Generate a short or summary table of contents that lists only the
|
3843chapters (and appendices and unnumbered chapters). Omit sections, subsections
3844and subsubsections. Only a long manual needs a short table
3845of contents in addition to the full table of contents.@refill
| 3922chapters, appendices, and unnumbered chapters. Sections, subsections
3923and subsubsections are omitted. Only a long manual needs a short table
3924of contents in addition to the full table of contents.
|
3846
3847@end table
3848
3849Both contents commands should be written on a line by themselves.
3850The contents commands automatically generate a chapter-like heading at
3851the top of the first table of contents page, so don't include any
3852sectioning command such as @code{@@unnumbered} before them.
3853
3854Since an Info file uses menus instead of tables of contents, the Info
3855formatting commands ignore the contents commands. But the contents are
3856included in plain text output (generated by @code{makeinfo
3857--no-headers}), unless @code{makeinfo} is writing its output to standard
3858output.
3859
3860When @code{makeinfo} writes a short table of contents while producing
3861html output, the links in the short table of contents point to
3862corresponding entries in the full table of contents rather than the text
3863of the document. The links in the full table of contents point to the
3864main text of the document.
3865
3866The contents commands can be placed either at the very end of the file,
3867after any indices (see the previous section) and just before the
3868@code{@@bye} (see the next section), or near the beginning of the file,
3869after the @code{@@end titlepage} (@pxref{titlepage}). The advantage to
3870the former is that then the contents output is always up to date,
3871because it reflects the processing just done. The advantage to the
3872latter is that the contents are printed in the proper place, thus you do
3873not need to rearrange the DVI file with @command{dviselect} or shuffle
3874paper.
3875
3876@findex setcontentsaftertitlepage
3877@findex setshortcontentsaftertitlepage
3878@cindex Contents, after title page
3879@cindex Table of contents, after title page
3880As an author, you can put the contents commands wherever you prefer.
3881But if you are a user simply printing a manual, you may wish to print
3882the contents after the title page even if the author put the contents
3883commands at the end of the document (as is the case in most existing
| 3925
3926@end table
3927
3928Both contents commands should be written on a line by themselves.
3929The contents commands automatically generate a chapter-like heading at
3930the top of the first table of contents page, so don't include any
3931sectioning command such as @code{@@unnumbered} before them.
3932
3933Since an Info file uses menus instead of tables of contents, the Info
3934formatting commands ignore the contents commands. But the contents are
3935included in plain text output (generated by @code{makeinfo
3936--no-headers}), unless @code{makeinfo} is writing its output to standard
3937output.
3938
3939When @code{makeinfo} writes a short table of contents while producing
3940html output, the links in the short table of contents point to
3941corresponding entries in the full table of contents rather than the text
3942of the document. The links in the full table of contents point to the
3943main text of the document.
3944
3945The contents commands can be placed either at the very end of the file,
3946after any indices (see the previous section) and just before the
3947@code{@@bye} (see the next section), or near the beginning of the file,
3948after the @code{@@end titlepage} (@pxref{titlepage}). The advantage to
3949the former is that then the contents output is always up to date,
3950because it reflects the processing just done. The advantage to the
3951latter is that the contents are printed in the proper place, thus you do
3952not need to rearrange the DVI file with @command{dviselect} or shuffle
3953paper.
3954
3955@findex setcontentsaftertitlepage
3956@findex setshortcontentsaftertitlepage
3957@cindex Contents, after title page
3958@cindex Table of contents, after title page
3959As an author, you can put the contents commands wherever you prefer.
3960But if you are a user simply printing a manual, you may wish to print
3961the contents after the title page even if the author put the contents
3962commands at the end of the document (as is the case in most existing
|
3884Texinfo documents). You can do this by specifying
| 3963Texinfo documents, at this writing). You can do this by specifying
|
3885@code{@@setcontentsaftertitlepage} and/or
3886@code{@@setshortcontentsaftertitlepage}. The first prints only the main
3887contents after the @code{@@end titlepage}; the second prints both the
3888short contents and the main contents. In either case, any subsequent
3889@code{@@contents} or @code{@@shortcontents} is ignored (unless no
3890@code{@@end titlepage} is ever encountered).
3891
3892You need to include the @code{@@set@dots{}contentsaftertitlepage}
3893commands early in the document (just after @code{@@setfilename}, for
| 3964@code{@@setcontentsaftertitlepage} and/or
3965@code{@@setshortcontentsaftertitlepage}. The first prints only the main
3966contents after the @code{@@end titlepage}; the second prints both the
3967short contents and the main contents. In either case, any subsequent
3968@code{@@contents} or @code{@@shortcontents} is ignored (unless no
3969@code{@@end titlepage} is ever encountered).
3970
3971You need to include the @code{@@set@dots{}contentsaftertitlepage}
3972commands early in the document (just after @code{@@setfilename}, for
|
3894example). Or, if you're using @command{texi2dvi} (@pxref{Format with
3895texi2dvi}), you can use its @option{--texinfo} option to specify this
3896without altering the source file at all. For example:
| 3973example). We recommend using @command{texi2dvi} (@pxref{Format with
3974texi2dvi}) to specify this without altering the source file at all. For
3975example:
|
3897@example
| 3976@example
|
3898texi2dvi --texinfo=@@setshortcontentsaftertitlepage foo.texi
| 3977texi2dvi --texinfo=@@setcontentsaftertitlepage foo.texi
|
3899@end example
3900
3901
3902@node File End
3903@section @code{@@bye} File Ending
3904@findex bye
3905
3906An @code{@@bye} command terminates @TeX{} or Info formatting. None of
| 3978@end example
3979
3980
3981@node File End
3982@section @code{@@bye} File Ending
3983@findex bye
3984
3985An @code{@@bye} command terminates @TeX{} or Info formatting. None of
|
3907the formatting commands see any of the file following @code{@@bye}.
3908The @code{@@bye} command should be on a line by itself.@refill
| 3986the formatting commands reading anything following @code{@@bye}. The
3987@code{@@bye} command should be on a line by itself.
|
3909
| 3988
|
3910If you wish, you may follow the @code{@@bye} line with notes. These notes
3911will not be formatted and will not appear in either Info or a printed
3912manual; it is as if text after @code{@@bye} were within @code{@@ignore}
3913@dots{} @code{@@end ignore}. Also, you may follow the @code{@@bye} line
3914with a local variables list. @xref{Compile-Command, , Using Local
3915Variables and the Compile Command}, for more information.@refill
| 3989If you wish, you may follow the @code{@@bye} line with notes. These
3990notes will not be formatted and will not appear in either Info or a
3991printed manual; it is as if text after @code{@@bye} were within
3992@code{@@ignore} @dots{} @code{@@end ignore}. Also, you may follow the
3993@code{@@bye} line with a local variables list for Emacs.
3994@xref{Compile-Command, , Using Local Variables and the Compile Command},
3995for more information.
|
3916
3917
3918@node Structuring
3919@chapter Chapter Structuring
3920@cindex Chapter structuring
3921@cindex Structuring of chapters
3922
3923The @dfn{chapter structuring} commands divide a document into a hierarchy of
3924chapters, sections, subsections, and subsubsections. These commands
3925generate large headings; they also provide information for the table
3926of contents of a printed manual (@pxref{Contents, , Generating a Table
3927of Contents}).@refill
3928
3929The chapter structuring commands do not create an Info node structure,
3930so normally you should put an @code{@@node} command immediately before
3931each chapter structuring command (@pxref{Nodes}). The only time you
3932are likely to use the chapter structuring commands without using the
3933node structuring commands is if you are writing a document that
3934contains no cross references and will never be transformed into Info
3935format.@refill
3936
3937It is unlikely that you will ever write a Texinfo file that is
3938intended only as an Info file and not as a printable document. If you
3939do, you might still use chapter structuring commands to create a
3940heading at the top of each node---but you don't need to.@refill
3941
3942@menu
3943* Tree Structuring:: A manual is like an upside down tree @dots{}
3944* Structuring Command Types:: How to divide a manual into parts.
3945* makeinfo top:: The @code{@@top} command, part of the `Top' node.
3946* chapter::
3947* unnumbered & appendix::
3948* majorheading & chapheading::
3949* section::
3950* unnumberedsec appendixsec heading::
3951* subsection::
3952* unnumberedsubsec appendixsubsec subheading::
3953* subsubsection:: Commands for the lowest level sections.
3954* Raise/lower sections:: How to change commands' hierarchical level.
3955@end menu
3956
3957
3958@node Tree Structuring
3959@section Tree Structure of Sections
3960@cindex Tree structuring
3961
3962A Texinfo file is usually structured like a book with chapters,
3963sections, subsections, and the like. This structure can be visualized
3964as a tree (or rather as an upside-down tree) with the root at the top
3965and the levels corresponding to chapters, sections, subsection, and
3966subsubsections.@refill
3967
3968Here is a diagram that shows a Texinfo file with three chapters,
3969each of which has two sections.@refill
3970
3971@example
3972@group
3973 Top
3974 |
3975 -------------------------------------
3976 | | |
3977 Chapter 1 Chapter 2 Chapter 3
3978 | | |
3979 -------- -------- --------
3980 | | | | | |
3981 Section Section Section Section Section Section
3982 1.1 1.2 2.1 2.2 3.1 3.2
3983
3984@end group
3985@end example
3986
3987In a Texinfo file that has this structure, the beginning of Chapter 2
3988looks like this:@refill
3989
3990@example
3991@group
3992@@node Chapter 2, Chapter 3, Chapter 1, top
3993@@chapter Chapter 2
3994@end group
3995@end example
3996
3997The chapter structuring commands are described in the sections that
3998follow; the @code{@@node} and @code{@@menu} commands are described in
3999following chapters. (@xref{Nodes}, and see @ref{Menus}.)@refill
4000
4001
4002@node Structuring Command Types
4003@section Structuring Command Types
4004
4005The chapter structuring commands fall into four groups or series, each
4006of which contains structuring commands corresponding to the
4007hierarchical levels of chapters, sections, subsections, and
4008subsubsections.@refill
4009
4010The four groups are the @code{@@chapter} series, the
4011@code{@@unnumbered} series, the @code{@@appendix} series, and the
4012@code{@@heading} series.@refill
4013
4014Each command produces titles that have a different appearance on the
4015printed page or Info file; only some of the commands produce
4016titles that are listed in the table of contents of a printed book or
4017manual.@refill
4018
4019@itemize @bullet
4020@item
4021The @code{@@chapter} and @code{@@appendix} series of commands produce
4022numbered or lettered entries both in the body of a printed work and in
4023its table of contents.@refill
4024
4025@item
4026The @code{@@unnumbered} series of commands produce unnumbered entries
4027both in the body of a printed work and in its table of contents. The
4028@code{@@top} command, which has a special use, is a member of this
4029series (@pxref{makeinfo top, , @code{@@top}}).@refill
4030
4031@item
4032The @code{@@heading} series of commands produce unnumbered headings
4033that do not appear in a table of contents. The heading commands never
4034start a new page.@refill
4035
4036@item
4037The @code{@@majorheading} command produces results similar to using
4038the @code{@@chapheading} command but generates a larger vertical
4039whitespace before the heading.@refill
4040
4041@item
4042When an @code{@@setchapternewpage} command says to do so, the
4043@code{@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands
4044start new pages in the printed manual; the @code{@@heading} commands
4045do not.@refill
4046@end itemize
4047
4048Here are the four groups of chapter structuring commands:
4049
4050@tex
4051{\globaldefs = 1 \smallfonts}
4052@end tex
4053
4054@multitable @columnfractions .19 .30 .29 .22
4055@item @tab @tab @tab No new page
4056@item @i{Numbered} @tab @i{Unnumbered} @tab @i{Lettered/numbered} @tab @i{Unnumbered}
4057@item In contents @tab In contents @tab In contents @tab Omitted from@*contents
4058@item @tab @code{@@top} @tab @tab @code{@@majorheading}
4059@item @code{@@chapter} @tab @code{@@unnumbered} @tab @code{@@appendix} @tab @code{@@chapheading}
4060@item @code{@@section} @tab @code{@@unnumberedsec} @tab @code{@@appendixsec} @tab @code{@@heading}
4061@item @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab @code{@@appendixsubsec} @tab @code{@@subheading}
4062@item @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab @code{@@appendixsubsubsec} @tab @code{@@subsubheading}
4063@end multitable
4064@tex
4065{\globaldefs = 1 \textfonts}
4066@end tex
4067
4068
4069@node makeinfo top
4070@section @code{@@top}
4071
4072The @code{@@top} command is a special sectioning command that you use
4073only after an @samp{@@node Top} line at the beginning of a Texinfo file.
4074The @code{@@top} command tells the @code{makeinfo} formatter which node
4075is the `Top' node, so it can use it as the root of the node tree if your
4076manual uses implicit pointers. It has the same typesetting effect as
4077@code{@@unnumbered} (@pxref{unnumbered & appendix, , @code{@@unnumbered}
4078and @code{@@appendix}}). For detailed information, see @ref{makeinfo
4079top command, , The @code{@@top} Command}.
4080
4081The @code{@@top} node and its menu (if any) is conventionally wrapped in
4082an @code{@@ifnottex} conditional so that it will appear only in Info and
4083HTML output, not @TeX{}.
4084
4085
4086@node chapter, unnumbered & appendix, makeinfo top, Structuring
4087@comment node-name, next, previous, up
4088@section @code{@@chapter}
4089@findex chapter
4090
4091@code{@@chapter} identifies a chapter in the document. Write the
4092command at the beginning of a line and follow it on the same line by
4093the title of the chapter.@refill
4094
4095For example, this chapter in this manual is entitled ``Chapter
4096Structuring''; the @code{@@chapter} line looks like this:@refill
4097
4098@example
4099@@chapter Chapter Structuring
4100@end example
4101
4102In @TeX{}, the @code{@@chapter} command creates a chapter in the
4103document, specifying the chapter title. The chapter is numbered
4104automatically.@refill
4105
4106In Info, the @code{@@chapter} command causes the title to appear on a
4107line by itself, with a line of asterisks inserted underneath. Thus,
4108in Info, the above example produces the following output:@refill
4109
4110@example
4111Chapter Structuring
4112*******************
4113@end example
4114
4115@findex centerchap
4116Texinfo also provides a command @code{@@centerchap}, which is analogous
4117to @code{@@unnumbered}, but centers its argument in the printed output.
4118This kind of stylistic choice is not usually offered by Texinfo.
4119@c but the Hacker's Dictionary wanted it ...
4120
4121
4122@node unnumbered & appendix
4123@section @code{@@unnumbered} and @code{@@appendix}
4124@findex unnumbered
4125@findex appendix
4126
4127Use the @code{@@unnumbered} command to create a chapter that appears
4128in a printed manual without chapter numbers of any kind. Use the
4129@code{@@appendix} command to create an appendix in a printed manual
4130that is labelled by letter instead of by number.@refill
4131
4132For Info file output, the @code{@@unnumbered} and @code{@@appendix}
4133commands are equivalent to @code{@@chapter}: the title is printed on a
4134line by itself with a line of asterisks underneath. (@xref{chapter, ,
4135@code{@@chapter}}.)@refill
4136
4137To create an appendix or an unnumbered chapter, write an
4138@code{@@appendix} or @code{@@unnumbered} command at the beginning of a
4139line and follow it on the same line by the title, as you would if you
4140were creating a chapter.@refill
4141
4142
4143@node majorheading & chapheading, section, unnumbered & appendix, Structuring
4144@section @code{@@majorheading}, @code{@@chapheading}
4145@findex majorheading
4146@findex chapheading
4147
4148The @code{@@majorheading} and @code{@@chapheading} commands put
4149chapter-like headings in the body of a document.@refill
4150
4151However, neither command causes @TeX{} to produce a numbered heading
4152or an entry in the table of contents; and neither command causes
4153@TeX{} to start a new page in a printed manual.@refill
4154
4155In @TeX{}, an @code{@@majorheading} command generates a larger vertical
4156whitespace before the heading than an @code{@@chapheading} command but
4157is otherwise the same.@refill
4158
4159In Info,
4160the @code{@@majorheading} and
4161@code{@@chapheading} commands are equivalent to
4162@code{@@chapter}: the title is printed on a line by itself with a line
4163of asterisks underneath. (@xref{chapter, , @code{@@chapter}}.)@refill
4164
4165@node section, unnumberedsec appendixsec heading, majorheading & chapheading, Structuring
4166@comment node-name, next, previous, up
4167@section @code{@@section}
4168@findex section
4169
4170In a printed manual, an @code{@@section} command identifies a
4171numbered section within a chapter. The section title appears in the
4172table of contents. In Info, an @code{@@section} command provides a
4173title for a segment of text, underlined with @samp{=}.@refill
4174
4175This section is headed with an @code{@@section} command and looks like
4176this in the Texinfo file:@refill
4177
4178@example
4179@@section @@code@{@@@@section@}
4180@end example
4181
4182To create a section, write the @code{@@section} command at the
4183beginning of a line and follow it on the same line by the section
4184title.@refill
4185
4186Thus,
4187
4188@example
4189@@section This is a section
4190@end example
4191
4192@noindent
4193produces
4194
4195@example
4196@group
4197This is a section
4198=================
4199@end group
4200@end example
4201
4202@noindent
4203in Info.
4204
4205@node unnumberedsec appendixsec heading, subsection, section, Structuring
4206@comment node-name, next, previous, up
4207@section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
4208@findex unnumberedsec
4209@findex appendixsec
4210@findex heading
4211
4212The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading}
4213commands are, respectively, the unnumbered, appendix-like, and
4214heading-like equivalents of the @code{@@section} command.
4215(@xref{section, , @code{@@section}}.)@refill
4216
4217@table @code
4218@item @@unnumberedsec
4219The @code{@@unnumberedsec} command may be used within an
4220unnumbered chapter or within a regular chapter or appendix to
4221provide an unnumbered section.@refill
4222
4223@item @@appendixsec
4224@itemx @@appendixsection
4225@code{@@appendixsection} is a longer spelling of the
4226@code{@@appendixsec} command; the two are synonymous.@refill
4227@findex appendixsection
4228
4229Conventionally, the @code{@@appendixsec} or @code{@@appendixsection}
4230command is used only within appendices.@refill
4231
4232@item @@heading
4233You may use the @code{@@heading} command anywhere you wish for a
4234section-style heading that will not appear in the table of contents.@refill
4235@end table
4236
4237@node subsection, unnumberedsubsec appendixsubsec subheading, unnumberedsec appendixsec heading, Structuring
4238@comment node-name, next, previous, up
4239@section The @code{@@subsection} Command
4240@findex subsection
4241
4242Subsections are to sections as sections are to chapters.
4243(@xref{section, , @code{@@section}}.) In Info, subsection titles are
4244underlined with @samp{-}. For example,@refill
4245
4246@example
4247@@subsection This is a subsection
4248@end example
4249
4250@noindent
4251produces
4252
4253@example
4254@group
4255This is a subsection
4256--------------------
4257@end group
4258@end example
4259
4260In a printed manual, subsections are listed in the table of contents
4261and are numbered three levels deep.@refill
4262
4263@node unnumberedsubsec appendixsubsec subheading, subsubsection, subsection, Structuring
4264@comment node-name, next, previous, up
4265@section The @code{@@subsection}-like Commands
4266@cindex Subsection-like commands
4267@findex unnumberedsubsec
4268@findex appendixsubsec
4269@findex subheading
4270
4271The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and
4272@code{@@subheading} commands are, respectively, the unnumbered,
4273appendix-like, and heading-like equivalents of the @code{@@subsection}
4274command. (@xref{subsection, , @code{@@subsection}}.)@refill
4275
4276In Info, the @code{@@subsection}-like commands generate a title
4277underlined with hyphens. In a printed manual, an @code{@@subheading}
4278command produces a heading like that of a subsection except that it is
4279not numbered and does not appear in the table of contents. Similarly,
4280an @code{@@unnumberedsubsec} command produces an unnumbered heading like
4281that of a subsection and an @code{@@appendixsubsec} command produces a
4282subsection-like heading labelled with a letter and numbers; both of
4283these commands produce headings that appear in the table of
4284contents.@refill
4285
4286@node subsubsection, Raise/lower sections, unnumberedsubsec appendixsubsec subheading, Structuring
4287@comment node-name, next, previous, up
4288@section The `subsub' Commands
4289@cindex Subsub commands
4290@findex subsubsection
4291@findex unnumberedsubsubsec
4292@findex appendixsubsubsec
4293@findex subsubheading
4294
4295The fourth and lowest level sectioning commands in Texinfo are the
4296`subsub' commands. They are:@refill
4297
4298@table @code
4299@item @@subsubsection
4300Subsubsections are to subsections as subsections are to sections.
4301(@xref{subsection, , @code{@@subsection}}.) In a printed manual,
4302subsubsection titles appear in the table of contents and are numbered
4303four levels deep.@refill
4304
4305@item @@unnumberedsubsubsec
4306Unnumbered subsubsection titles appear in the table of contents of a
4307printed manual, but lack numbers. Otherwise, unnumbered
4308subsubsections are the same as subsubsections. In Info, unnumbered
4309subsubsections look exactly like ordinary subsubsections.@refill
4310
4311@item @@appendixsubsubsec
4312Conventionally, appendix commands are used only for appendices and are
4313lettered and numbered appropriately in a printed manual. They also
4314appear in the table of contents. In Info, appendix subsubsections look
4315exactly like ordinary subsubsections.@refill
4316
4317@item @@subsubheading
4318The @code{@@subsubheading} command may be used anywhere that you need
4319a small heading that will not appear in the table of contents. In
4320Info, subsubheadings look exactly like ordinary subsubsection
4321headings.@refill
4322@end table
4323
4324In Info, `subsub' titles are underlined with periods.
4325For example,@refill
4326
4327@example
4328@@subsubsection This is a subsubsection
4329@end example
4330
4331@noindent
4332produces
4333
4334@example
4335@group
4336This is a subsubsection
4337.......................
4338@end group
4339@end example
4340
4341@node Raise/lower sections, , subsubsection, Structuring
4342@comment node-name, next, previous, up
4343@section @code{@@raisesections} and @code{@@lowersections}
4344@findex raisesections
4345@findex lowersections
4346@cindex Raising and lowering sections
4347@cindex Sections, raising and lowering
4348
4349The @code{@@raisesections} and @code{@@lowersections} commands raise and
4350lower the hierarchical level of chapters, sections, subsections and the
4351like. The @code{@@raisesections} command changes sections to chapters,
4352subsections to sections, and so on. The @code{@@lowersections} command
4353changes chapters to sections, sections to subsections, and so on.
4354
4355@cindex Include files, and section levels
4356An @code{@@lowersections} command is useful if you wish to include text
4357that is written as an outer or standalone Texinfo file in another
4358Texinfo file as an inner, included file. If you write the command at
4359the beginning of the file, all your @code{@@chapter} commands are
4360formatted as if they were @code{@@section} commands, all your
4361@code{@@section} command are formatted as if they were
4362@code{@@subsection} commands, and so on.
4363
4364@need 1000
4365@code{@@raisesections} raises a command one level in the chapter
4366structuring hierarchy:@refill
4367
4368@example
4369@group
4370 @r{Change} @r{To}
4371
4372@@subsection @@section,
4373@@section @@chapter,
4374@@heading @@chapheading,
4375 @r{etc.}
4376@end group
4377@end example
4378
4379@need 1000
4380@code{@@lowersections} lowers a command one level in the chapter
4381structuring hierarchy:@refill
4382
4383@example
4384@group
4385 @r{Change} @r{To}
4386
4387@@chapter @@section,
4388@@subsection @@subsubsection,
4389@@heading @@subheading,
4390 @r{etc.}
4391@end group
4392@end example
4393
4394An @code{@@raisesections} or @code{@@lowersections} command changes only
4395those structuring commands that follow the command in the Texinfo file.
4396Write an @code{@@raisesections} or @code{@@lowersections} command on a
4397line of its own.
4398
4399An @code{@@lowersections} command cancels an @code{@@raisesections}
4400command, and vice versa. Typically, the commands are used like this:
4401
4402@example
4403@@lowersections
4404@@include somefile.texi
4405@@raisesections
4406@end example
4407
4408Without the @code{@@raisesections}, all the subsequent sections in your
4409document will be lowered.
4410
4411Repeated use of the commands continue to raise or lower the hierarchical
4412level a step at a time.
4413
4414An attempt to raise above `chapters' reproduces chapter commands; an
4415attempt to lower below `subsubsections' reproduces subsubsection
4416commands.
4417
4418@node Nodes
4419@chapter Nodes
4420
4421@dfn{Nodes} are the primary segments of a Texinfo file. They do not
4422themselves impose a hierarchical or any other kind of structure on a file.
4423Nodes contain @dfn{node pointers} that name other nodes, and can contain
4424@dfn{menus} which are lists of nodes. In Info, the movement commands
4425can carry you to a pointed-to node or to a node listed in a menu. Node
4426pointers and menus provide structure for Info files just as chapters,
4427sections, subsections, and the like, provide structure for printed
4428books.@refill
4429
4430@menu
4431* Two Paths:: Different commands to structure
4432 Info output and printed output.
4433* Node Menu Illustration:: A diagram, and sample nodes and menus.
4434* node:: Creating nodes, in detail.
4435* makeinfo Pointer Creation:: Letting makeinfo determine node pointers.
4436* anchor:: Defining arbitrary cross-reference targets.
4437@end menu
4438
4439
4440@node Two Paths
4441@section Two Paths
4442
4443The node and menu commands and the chapter structuring commands are
4444technically independent of each other:
4445
4446@itemize @bullet
4447@item
4448In Info, node and menu commands provide structure. The chapter
4449structuring commands generate headings with different kinds of
4450underlining---asterisks for chapters, hyphens for sections, and so on;
4451they do nothing else.@refill
4452
4453@item
4454In @TeX{}, the chapter structuring commands generate chapter and section
4455numbers and tables of contents. The node and menu commands provide
4456information for cross references; they do nothing else.@refill
4457@end itemize
4458
4459You can use node pointers and menus to structure an Info file any way
4460you want; and you can write a Texinfo file so that its Info output has a
4461different structure than its printed output. However, virtually all
4462Texinfo files are written such that the structure for the Info output
4463corresponds to the structure for the printed output. It is neither
4464convenient nor understandable to the reader to do otherwise.@refill
4465
4466Generally, printed output is structured in a tree-like hierarchy in
4467which the chapters are the major limbs from which the sections branch
4468out. Similarly, node pointers and menus are organized to create a
4469matching structure in the Info output.@refill
4470
4471
4472@node Node Menu Illustration
4473@section Node and Menu Illustration
4474
4475Here is a copy of the diagram shown earlier that illustrates a Texinfo
4476file with three chapters, each of which contains two sections.@refill
4477
4478The ``root'' is at the top of the diagram and the ``leaves'' are at the
4479bottom. This is how such a diagram is drawn conventionally; it
4480illustrates an upside-down tree. For this reason, the root node is
4481called the `Top' node, and `Up' node pointers carry you closer to the
4482root.@refill
4483
4484@example
4485@group
4486 Top
4487 |
4488 -------------------------------------
4489 | | |
4490 Chapter 1 Chapter 2 Chapter 3
4491 | | |
4492 -------- -------- --------
4493 | | | | | |
4494 Section Section Section Section Section Section
4495 1.1 1.2 2.1 2.2 3.1 3.2
4496@end group
4497@end example
4498
4499The fully-written command to start Chapter 2 would be this:
4500
4501@example
4502@group
4503@@node Chapter 2, Chapter 3, Chapter 1, Top
4504@@comment node-name, next, previous, up
4505@end group
4506@end example
4507
4508@noindent
4509This @code{@@node} line says that the name of this node is ``Chapter
45102'', the name of the `Next' node is ``Chapter 3'', the name of the
4511`Previous' node is ``Chapter 1'', and the name of the `Up' node is
4512``Top''. You can omit writing out these node names if your document is
4513hierarchically organized (@pxref{makeinfo Pointer Creation}), but the
4514pointer relationships still obtain.
4515
4516@quotation
4517@strong{Please Note:} `Next' refers to the next node at the same
4518hierarchical level in the manual, not necessarily to the next node
4519within the Texinfo file. In the Texinfo file, the subsequent node may
4520be at a lower level---a section-level node most often follows a
4521chapter-level node, for example. `Next' and `Previous' refer to nodes
4522at the @emph{same} hierarchical level. (The `Top' node contains the
4523exception to this rule. Since the `Top' node is the only node at that
4524level, `Next' refers to the first following node, which is almost always
4525a chapter or chapter-level node.)@refill
4526@end quotation
4527
4528To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter
45292. (@xref{Menus}.) You would write the menu just
4530before the beginning of Section 2.1, like this:@refill
4531
4532@example
4533@group
4534 @@menu
4535 * Sect. 2.1:: Description of this section.
4536 * Sect. 2.2::
4537 @@end menu
4538@end group
4539@end example
4540
4541Write the node for Sect. 2.1 like this:@refill
4542
4543@example
4544@group
4545 @@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
4546 @@comment node-name, next, previous, up
4547@end group
4548@end example
4549
4550In Info format, the `Next' and `Previous' pointers of a node usually
4551lead to other nodes at the same level---from chapter to chapter or from
4552section to section (sometimes, as shown, the `Previous' pointer points
4553up); an `Up' pointer usually leads to a node at the level above (closer
4554to the `Top' node); and a `Menu' leads to nodes at a level below (closer
4555to `leaves'). (A cross reference can point to a node at any level;
4556see @ref{Cross References}.)@refill
4557
4558Usually, an @code{@@node} command and a chapter structuring command are
4559used in sequence, along with indexing commands. (You may follow the
4560@code{@@node} line with a comment line that reminds you which pointer is
4561which.)@refill
4562
4563Here is the beginning of the chapter in this manual called ``Ending a
4564Texinfo File''. This shows an @code{@@node} line followed by a comment
4565line, an @code{@@chapter} line, and then by indexing lines.@refill
4566
4567@example
4568@group
4569@@node Ending a File, Structuring, Beginning a File, Top
4570@@comment node-name, next, previous, up
4571@@chapter Ending a Texinfo File
4572@@cindex Ending a Texinfo file
4573@@cindex Texinfo file ending
4574@@cindex File ending
4575@end group
4576@end example
4577
4578
4579@node node
4580@section The @code{@@node} Command
4581
4582@cindex Node, defined
4583@findex node
4584
4585A @dfn{node} is a segment of text that begins at an @code{@@node}
4586command and continues until the next @code{@@node} command. The
4587definition of node is different from that for chapter or section. A
4588chapter may contain sections and a section may contain subsections;
4589but a node cannot contain subnodes; the text of a node continues only
4590until the next @code{@@node} command in the file. A node usually
4591contains only one chapter structuring command, the one that follows
4592the @code{@@node} line. On the other hand, in printed output nodes
4593are used only for cross references, so a chapter or section may
4594contain any number of nodes. Indeed, a chapter usually contains
4595several nodes, one for each section, subsection, and
4596subsubsection.@refill
4597
4598To create a node, write an @code{@@node} command at the beginning of a
4599line, and follow it with up to four arguments, separated by commas, on
4600the rest of the same line. The first argument is required; it is the
4601name of this node. The subsequent arguments are the names of the
4602`Next', `Previous', and `Up' pointers, in that order, and may be omitted
4603if your Texinfo document is hierarchically organized (@pxref{makeinfo
4604Pointer Creation}).
4605
4606You may insert spaces before each name if you wish; the spaces are
4607ignored. You must write the name of the node and the names of the
4608`Next', `Previous', and `Up' pointers all on the same line. Otherwise,
4609the formatters fail. (@inforef{Top, info, info}, for more information
4610about nodes in Info.)
4611
4612Usually, you write one of the chapter-structuring command lines
4613immediately after an @code{@@node} line---for example, an
4614@code{@@section} or @code{@@subsection} line. (@xref{Structuring
4615Command Types}.)
4616
4617@quotation
4618@strong{Please note:} The GNU Emacs Texinfo mode updating commands work
4619only with Texinfo files in which @code{@@node} lines are followed by chapter
4620structuring lines. @xref{Updating Requirements}.@refill
4621@end quotation
4622
4623@TeX{} uses @code{@@node} lines to identify the names to use for cross
4624references. For this reason, you must write @code{@@node} lines in a
4625Texinfo file that you intend to format for printing, even if you do not
4626intend to format it for Info. (Cross references, such as the one at the
4627end of this sentence, are made with @code{@@xref} and related commands;
4628see @ref{Cross References}.)@refill
4629
4630@menu
4631* Node Names:: How to choose node and pointer names.
4632* Writing a Node:: How to write an @code{@@node} line.
4633* Node Line Tips:: Keep names short.
4634* Node Line Requirements:: Keep names unique, without @@-commands.
4635* First Node:: How to write a `Top' node.
4636* makeinfo top command:: How to use the @code{@@top} command.
| 3996
3997
3998@node Structuring
3999@chapter Chapter Structuring
4000@cindex Chapter structuring
4001@cindex Structuring of chapters
4002
4003The @dfn{chapter structuring} commands divide a document into a hierarchy of
4004chapters, sections, subsections, and subsubsections. These commands
4005generate large headings; they also provide information for the table
4006of contents of a printed manual (@pxref{Contents, , Generating a Table
4007of Contents}).@refill
4008
4009The chapter structuring commands do not create an Info node structure,
4010so normally you should put an @code{@@node} command immediately before
4011each chapter structuring command (@pxref{Nodes}). The only time you
4012are likely to use the chapter structuring commands without using the
4013node structuring commands is if you are writing a document that
4014contains no cross references and will never be transformed into Info
4015format.@refill
4016
4017It is unlikely that you will ever write a Texinfo file that is
4018intended only as an Info file and not as a printable document. If you
4019do, you might still use chapter structuring commands to create a
4020heading at the top of each node---but you don't need to.@refill
4021
4022@menu
4023* Tree Structuring:: A manual is like an upside down tree @dots{}
4024* Structuring Command Types:: How to divide a manual into parts.
4025* makeinfo top:: The @code{@@top} command, part of the `Top' node.
4026* chapter::
4027* unnumbered & appendix::
4028* majorheading & chapheading::
4029* section::
4030* unnumberedsec appendixsec heading::
4031* subsection::
4032* unnumberedsubsec appendixsubsec subheading::
4033* subsubsection:: Commands for the lowest level sections.
4034* Raise/lower sections:: How to change commands' hierarchical level.
4035@end menu
4036
4037
4038@node Tree Structuring
4039@section Tree Structure of Sections
4040@cindex Tree structuring
4041
4042A Texinfo file is usually structured like a book with chapters,
4043sections, subsections, and the like. This structure can be visualized
4044as a tree (or rather as an upside-down tree) with the root at the top
4045and the levels corresponding to chapters, sections, subsection, and
4046subsubsections.@refill
4047
4048Here is a diagram that shows a Texinfo file with three chapters,
4049each of which has two sections.@refill
4050
4051@example
4052@group
4053 Top
4054 |
4055 -------------------------------------
4056 | | |
4057 Chapter 1 Chapter 2 Chapter 3
4058 | | |
4059 -------- -------- --------
4060 | | | | | |
4061 Section Section Section Section Section Section
4062 1.1 1.2 2.1 2.2 3.1 3.2
4063
4064@end group
4065@end example
4066
4067In a Texinfo file that has this structure, the beginning of Chapter 2
4068looks like this:@refill
4069
4070@example
4071@group
4072@@node Chapter 2, Chapter 3, Chapter 1, top
4073@@chapter Chapter 2
4074@end group
4075@end example
4076
4077The chapter structuring commands are described in the sections that
4078follow; the @code{@@node} and @code{@@menu} commands are described in
4079following chapters. (@xref{Nodes}, and see @ref{Menus}.)@refill
4080
4081
4082@node Structuring Command Types
4083@section Structuring Command Types
4084
4085The chapter structuring commands fall into four groups or series, each
4086of which contains structuring commands corresponding to the
4087hierarchical levels of chapters, sections, subsections, and
4088subsubsections.@refill
4089
4090The four groups are the @code{@@chapter} series, the
4091@code{@@unnumbered} series, the @code{@@appendix} series, and the
4092@code{@@heading} series.@refill
4093
4094Each command produces titles that have a different appearance on the
4095printed page or Info file; only some of the commands produce
4096titles that are listed in the table of contents of a printed book or
4097manual.@refill
4098
4099@itemize @bullet
4100@item
4101The @code{@@chapter} and @code{@@appendix} series of commands produce
4102numbered or lettered entries both in the body of a printed work and in
4103its table of contents.@refill
4104
4105@item
4106The @code{@@unnumbered} series of commands produce unnumbered entries
4107both in the body of a printed work and in its table of contents. The
4108@code{@@top} command, which has a special use, is a member of this
4109series (@pxref{makeinfo top, , @code{@@top}}).@refill
4110
4111@item
4112The @code{@@heading} series of commands produce unnumbered headings
4113that do not appear in a table of contents. The heading commands never
4114start a new page.@refill
4115
4116@item
4117The @code{@@majorheading} command produces results similar to using
4118the @code{@@chapheading} command but generates a larger vertical
4119whitespace before the heading.@refill
4120
4121@item
4122When an @code{@@setchapternewpage} command says to do so, the
4123@code{@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands
4124start new pages in the printed manual; the @code{@@heading} commands
4125do not.@refill
4126@end itemize
4127
4128Here are the four groups of chapter structuring commands:
4129
4130@tex
4131{\globaldefs = 1 \smallfonts}
4132@end tex
4133
4134@multitable @columnfractions .19 .30 .29 .22
4135@item @tab @tab @tab No new page
4136@item @i{Numbered} @tab @i{Unnumbered} @tab @i{Lettered/numbered} @tab @i{Unnumbered}
4137@item In contents @tab In contents @tab In contents @tab Omitted from@*contents
4138@item @tab @code{@@top} @tab @tab @code{@@majorheading}
4139@item @code{@@chapter} @tab @code{@@unnumbered} @tab @code{@@appendix} @tab @code{@@chapheading}
4140@item @code{@@section} @tab @code{@@unnumberedsec} @tab @code{@@appendixsec} @tab @code{@@heading}
4141@item @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab @code{@@appendixsubsec} @tab @code{@@subheading}
4142@item @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab @code{@@appendixsubsubsec} @tab @code{@@subsubheading}
4143@end multitable
4144@tex
4145{\globaldefs = 1 \textfonts}
4146@end tex
4147
4148
4149@node makeinfo top
4150@section @code{@@top}
4151
4152The @code{@@top} command is a special sectioning command that you use
4153only after an @samp{@@node Top} line at the beginning of a Texinfo file.
4154The @code{@@top} command tells the @code{makeinfo} formatter which node
4155is the `Top' node, so it can use it as the root of the node tree if your
4156manual uses implicit pointers. It has the same typesetting effect as
4157@code{@@unnumbered} (@pxref{unnumbered & appendix, , @code{@@unnumbered}
4158and @code{@@appendix}}). For detailed information, see @ref{makeinfo
4159top command, , The @code{@@top} Command}.
4160
4161The @code{@@top} node and its menu (if any) is conventionally wrapped in
4162an @code{@@ifnottex} conditional so that it will appear only in Info and
4163HTML output, not @TeX{}.
4164
4165
4166@node chapter, unnumbered & appendix, makeinfo top, Structuring
4167@comment node-name, next, previous, up
4168@section @code{@@chapter}
4169@findex chapter
4170
4171@code{@@chapter} identifies a chapter in the document. Write the
4172command at the beginning of a line and follow it on the same line by
4173the title of the chapter.@refill
4174
4175For example, this chapter in this manual is entitled ``Chapter
4176Structuring''; the @code{@@chapter} line looks like this:@refill
4177
4178@example
4179@@chapter Chapter Structuring
4180@end example
4181
4182In @TeX{}, the @code{@@chapter} command creates a chapter in the
4183document, specifying the chapter title. The chapter is numbered
4184automatically.@refill
4185
4186In Info, the @code{@@chapter} command causes the title to appear on a
4187line by itself, with a line of asterisks inserted underneath. Thus,
4188in Info, the above example produces the following output:@refill
4189
4190@example
4191Chapter Structuring
4192*******************
4193@end example
4194
4195@findex centerchap
4196Texinfo also provides a command @code{@@centerchap}, which is analogous
4197to @code{@@unnumbered}, but centers its argument in the printed output.
4198This kind of stylistic choice is not usually offered by Texinfo.
4199@c but the Hacker's Dictionary wanted it ...
4200
4201
4202@node unnumbered & appendix
4203@section @code{@@unnumbered} and @code{@@appendix}
4204@findex unnumbered
4205@findex appendix
4206
4207Use the @code{@@unnumbered} command to create a chapter that appears
4208in a printed manual without chapter numbers of any kind. Use the
4209@code{@@appendix} command to create an appendix in a printed manual
4210that is labelled by letter instead of by number.@refill
4211
4212For Info file output, the @code{@@unnumbered} and @code{@@appendix}
4213commands are equivalent to @code{@@chapter}: the title is printed on a
4214line by itself with a line of asterisks underneath. (@xref{chapter, ,
4215@code{@@chapter}}.)@refill
4216
4217To create an appendix or an unnumbered chapter, write an
4218@code{@@appendix} or @code{@@unnumbered} command at the beginning of a
4219line and follow it on the same line by the title, as you would if you
4220were creating a chapter.@refill
4221
4222
4223@node majorheading & chapheading, section, unnumbered & appendix, Structuring
4224@section @code{@@majorheading}, @code{@@chapheading}
4225@findex majorheading
4226@findex chapheading
4227
4228The @code{@@majorheading} and @code{@@chapheading} commands put
4229chapter-like headings in the body of a document.@refill
4230
4231However, neither command causes @TeX{} to produce a numbered heading
4232or an entry in the table of contents; and neither command causes
4233@TeX{} to start a new page in a printed manual.@refill
4234
4235In @TeX{}, an @code{@@majorheading} command generates a larger vertical
4236whitespace before the heading than an @code{@@chapheading} command but
4237is otherwise the same.@refill
4238
4239In Info,
4240the @code{@@majorheading} and
4241@code{@@chapheading} commands are equivalent to
4242@code{@@chapter}: the title is printed on a line by itself with a line
4243of asterisks underneath. (@xref{chapter, , @code{@@chapter}}.)@refill
4244
4245@node section, unnumberedsec appendixsec heading, majorheading & chapheading, Structuring
4246@comment node-name, next, previous, up
4247@section @code{@@section}
4248@findex section
4249
4250In a printed manual, an @code{@@section} command identifies a
4251numbered section within a chapter. The section title appears in the
4252table of contents. In Info, an @code{@@section} command provides a
4253title for a segment of text, underlined with @samp{=}.@refill
4254
4255This section is headed with an @code{@@section} command and looks like
4256this in the Texinfo file:@refill
4257
4258@example
4259@@section @@code@{@@@@section@}
4260@end example
4261
4262To create a section, write the @code{@@section} command at the
4263beginning of a line and follow it on the same line by the section
4264title.@refill
4265
4266Thus,
4267
4268@example
4269@@section This is a section
4270@end example
4271
4272@noindent
4273produces
4274
4275@example
4276@group
4277This is a section
4278=================
4279@end group
4280@end example
4281
4282@noindent
4283in Info.
4284
4285@node unnumberedsec appendixsec heading, subsection, section, Structuring
4286@comment node-name, next, previous, up
4287@section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
4288@findex unnumberedsec
4289@findex appendixsec
4290@findex heading
4291
4292The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading}
4293commands are, respectively, the unnumbered, appendix-like, and
4294heading-like equivalents of the @code{@@section} command.
4295(@xref{section, , @code{@@section}}.)@refill
4296
4297@table @code
4298@item @@unnumberedsec
4299The @code{@@unnumberedsec} command may be used within an
4300unnumbered chapter or within a regular chapter or appendix to
4301provide an unnumbered section.@refill
4302
4303@item @@appendixsec
4304@itemx @@appendixsection
4305@code{@@appendixsection} is a longer spelling of the
4306@code{@@appendixsec} command; the two are synonymous.@refill
4307@findex appendixsection
4308
4309Conventionally, the @code{@@appendixsec} or @code{@@appendixsection}
4310command is used only within appendices.@refill
4311
4312@item @@heading
4313You may use the @code{@@heading} command anywhere you wish for a
4314section-style heading that will not appear in the table of contents.@refill
4315@end table
4316
4317@node subsection, unnumberedsubsec appendixsubsec subheading, unnumberedsec appendixsec heading, Structuring
4318@comment node-name, next, previous, up
4319@section The @code{@@subsection} Command
4320@findex subsection
4321
4322Subsections are to sections as sections are to chapters.
4323(@xref{section, , @code{@@section}}.) In Info, subsection titles are
4324underlined with @samp{-}. For example,@refill
4325
4326@example
4327@@subsection This is a subsection
4328@end example
4329
4330@noindent
4331produces
4332
4333@example
4334@group
4335This is a subsection
4336--------------------
4337@end group
4338@end example
4339
4340In a printed manual, subsections are listed in the table of contents
4341and are numbered three levels deep.@refill
4342
4343@node unnumberedsubsec appendixsubsec subheading, subsubsection, subsection, Structuring
4344@comment node-name, next, previous, up
4345@section The @code{@@subsection}-like Commands
4346@cindex Subsection-like commands
4347@findex unnumberedsubsec
4348@findex appendixsubsec
4349@findex subheading
4350
4351The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and
4352@code{@@subheading} commands are, respectively, the unnumbered,
4353appendix-like, and heading-like equivalents of the @code{@@subsection}
4354command. (@xref{subsection, , @code{@@subsection}}.)@refill
4355
4356In Info, the @code{@@subsection}-like commands generate a title
4357underlined with hyphens. In a printed manual, an @code{@@subheading}
4358command produces a heading like that of a subsection except that it is
4359not numbered and does not appear in the table of contents. Similarly,
4360an @code{@@unnumberedsubsec} command produces an unnumbered heading like
4361that of a subsection and an @code{@@appendixsubsec} command produces a
4362subsection-like heading labelled with a letter and numbers; both of
4363these commands produce headings that appear in the table of
4364contents.@refill
4365
4366@node subsubsection, Raise/lower sections, unnumberedsubsec appendixsubsec subheading, Structuring
4367@comment node-name, next, previous, up
4368@section The `subsub' Commands
4369@cindex Subsub commands
4370@findex subsubsection
4371@findex unnumberedsubsubsec
4372@findex appendixsubsubsec
4373@findex subsubheading
4374
4375The fourth and lowest level sectioning commands in Texinfo are the
4376`subsub' commands. They are:@refill
4377
4378@table @code
4379@item @@subsubsection
4380Subsubsections are to subsections as subsections are to sections.
4381(@xref{subsection, , @code{@@subsection}}.) In a printed manual,
4382subsubsection titles appear in the table of contents and are numbered
4383four levels deep.@refill
4384
4385@item @@unnumberedsubsubsec
4386Unnumbered subsubsection titles appear in the table of contents of a
4387printed manual, but lack numbers. Otherwise, unnumbered
4388subsubsections are the same as subsubsections. In Info, unnumbered
4389subsubsections look exactly like ordinary subsubsections.@refill
4390
4391@item @@appendixsubsubsec
4392Conventionally, appendix commands are used only for appendices and are
4393lettered and numbered appropriately in a printed manual. They also
4394appear in the table of contents. In Info, appendix subsubsections look
4395exactly like ordinary subsubsections.@refill
4396
4397@item @@subsubheading
4398The @code{@@subsubheading} command may be used anywhere that you need
4399a small heading that will not appear in the table of contents. In
4400Info, subsubheadings look exactly like ordinary subsubsection
4401headings.@refill
4402@end table
4403
4404In Info, `subsub' titles are underlined with periods.
4405For example,@refill
4406
4407@example
4408@@subsubsection This is a subsubsection
4409@end example
4410
4411@noindent
4412produces
4413
4414@example
4415@group
4416This is a subsubsection
4417.......................
4418@end group
4419@end example
4420
4421@node Raise/lower sections, , subsubsection, Structuring
4422@comment node-name, next, previous, up
4423@section @code{@@raisesections} and @code{@@lowersections}
4424@findex raisesections
4425@findex lowersections
4426@cindex Raising and lowering sections
4427@cindex Sections, raising and lowering
4428
4429The @code{@@raisesections} and @code{@@lowersections} commands raise and
4430lower the hierarchical level of chapters, sections, subsections and the
4431like. The @code{@@raisesections} command changes sections to chapters,
4432subsections to sections, and so on. The @code{@@lowersections} command
4433changes chapters to sections, sections to subsections, and so on.
4434
4435@cindex Include files, and section levels
4436An @code{@@lowersections} command is useful if you wish to include text
4437that is written as an outer or standalone Texinfo file in another
4438Texinfo file as an inner, included file. If you write the command at
4439the beginning of the file, all your @code{@@chapter} commands are
4440formatted as if they were @code{@@section} commands, all your
4441@code{@@section} command are formatted as if they were
4442@code{@@subsection} commands, and so on.
4443
4444@need 1000
4445@code{@@raisesections} raises a command one level in the chapter
4446structuring hierarchy:@refill
4447
4448@example
4449@group
4450 @r{Change} @r{To}
4451
4452@@subsection @@section,
4453@@section @@chapter,
4454@@heading @@chapheading,
4455 @r{etc.}
4456@end group
4457@end example
4458
4459@need 1000
4460@code{@@lowersections} lowers a command one level in the chapter
4461structuring hierarchy:@refill
4462
4463@example
4464@group
4465 @r{Change} @r{To}
4466
4467@@chapter @@section,
4468@@subsection @@subsubsection,
4469@@heading @@subheading,
4470 @r{etc.}
4471@end group
4472@end example
4473
4474An @code{@@raisesections} or @code{@@lowersections} command changes only
4475those structuring commands that follow the command in the Texinfo file.
4476Write an @code{@@raisesections} or @code{@@lowersections} command on a
4477line of its own.
4478
4479An @code{@@lowersections} command cancels an @code{@@raisesections}
4480command, and vice versa. Typically, the commands are used like this:
4481
4482@example
4483@@lowersections
4484@@include somefile.texi
4485@@raisesections
4486@end example
4487
4488Without the @code{@@raisesections}, all the subsequent sections in your
4489document will be lowered.
4490
4491Repeated use of the commands continue to raise or lower the hierarchical
4492level a step at a time.
4493
4494An attempt to raise above `chapters' reproduces chapter commands; an
4495attempt to lower below `subsubsections' reproduces subsubsection
4496commands.
4497
4498@node Nodes
4499@chapter Nodes
4500
4501@dfn{Nodes} are the primary segments of a Texinfo file. They do not
4502themselves impose a hierarchical or any other kind of structure on a file.
4503Nodes contain @dfn{node pointers} that name other nodes, and can contain
4504@dfn{menus} which are lists of nodes. In Info, the movement commands
4505can carry you to a pointed-to node or to a node listed in a menu. Node
4506pointers and menus provide structure for Info files just as chapters,
4507sections, subsections, and the like, provide structure for printed
4508books.@refill
4509
4510@menu
4511* Two Paths:: Different commands to structure
4512 Info output and printed output.
4513* Node Menu Illustration:: A diagram, and sample nodes and menus.
4514* node:: Creating nodes, in detail.
4515* makeinfo Pointer Creation:: Letting makeinfo determine node pointers.
4516* anchor:: Defining arbitrary cross-reference targets.
4517@end menu
4518
4519
4520@node Two Paths
4521@section Two Paths
4522
4523The node and menu commands and the chapter structuring commands are
4524technically independent of each other:
4525
4526@itemize @bullet
4527@item
4528In Info, node and menu commands provide structure. The chapter
4529structuring commands generate headings with different kinds of
4530underlining---asterisks for chapters, hyphens for sections, and so on;
4531they do nothing else.@refill
4532
4533@item
4534In @TeX{}, the chapter structuring commands generate chapter and section
4535numbers and tables of contents. The node and menu commands provide
4536information for cross references; they do nothing else.@refill
4537@end itemize
4538
4539You can use node pointers and menus to structure an Info file any way
4540you want; and you can write a Texinfo file so that its Info output has a
4541different structure than its printed output. However, virtually all
4542Texinfo files are written such that the structure for the Info output
4543corresponds to the structure for the printed output. It is neither
4544convenient nor understandable to the reader to do otherwise.@refill
4545
4546Generally, printed output is structured in a tree-like hierarchy in
4547which the chapters are the major limbs from which the sections branch
4548out. Similarly, node pointers and menus are organized to create a
4549matching structure in the Info output.@refill
4550
4551
4552@node Node Menu Illustration
4553@section Node and Menu Illustration
4554
4555Here is a copy of the diagram shown earlier that illustrates a Texinfo
4556file with three chapters, each of which contains two sections.@refill
4557
4558The ``root'' is at the top of the diagram and the ``leaves'' are at the
4559bottom. This is how such a diagram is drawn conventionally; it
4560illustrates an upside-down tree. For this reason, the root node is
4561called the `Top' node, and `Up' node pointers carry you closer to the
4562root.@refill
4563
4564@example
4565@group
4566 Top
4567 |
4568 -------------------------------------
4569 | | |
4570 Chapter 1 Chapter 2 Chapter 3
4571 | | |
4572 -------- -------- --------
4573 | | | | | |
4574 Section Section Section Section Section Section
4575 1.1 1.2 2.1 2.2 3.1 3.2
4576@end group
4577@end example
4578
4579The fully-written command to start Chapter 2 would be this:
4580
4581@example
4582@group
4583@@node Chapter 2, Chapter 3, Chapter 1, Top
4584@@comment node-name, next, previous, up
4585@end group
4586@end example
4587
4588@noindent
4589This @code{@@node} line says that the name of this node is ``Chapter
45902'', the name of the `Next' node is ``Chapter 3'', the name of the
4591`Previous' node is ``Chapter 1'', and the name of the `Up' node is
4592``Top''. You can omit writing out these node names if your document is
4593hierarchically organized (@pxref{makeinfo Pointer Creation}), but the
4594pointer relationships still obtain.
4595
4596@quotation
4597@strong{Please Note:} `Next' refers to the next node at the same
4598hierarchical level in the manual, not necessarily to the next node
4599within the Texinfo file. In the Texinfo file, the subsequent node may
4600be at a lower level---a section-level node most often follows a
4601chapter-level node, for example. `Next' and `Previous' refer to nodes
4602at the @emph{same} hierarchical level. (The `Top' node contains the
4603exception to this rule. Since the `Top' node is the only node at that
4604level, `Next' refers to the first following node, which is almost always
4605a chapter or chapter-level node.)@refill
4606@end quotation
4607
4608To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter
46092. (@xref{Menus}.) You would write the menu just
4610before the beginning of Section 2.1, like this:@refill
4611
4612@example
4613@group
4614 @@menu
4615 * Sect. 2.1:: Description of this section.
4616 * Sect. 2.2::
4617 @@end menu
4618@end group
4619@end example
4620
4621Write the node for Sect. 2.1 like this:@refill
4622
4623@example
4624@group
4625 @@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
4626 @@comment node-name, next, previous, up
4627@end group
4628@end example
4629
4630In Info format, the `Next' and `Previous' pointers of a node usually
4631lead to other nodes at the same level---from chapter to chapter or from
4632section to section (sometimes, as shown, the `Previous' pointer points
4633up); an `Up' pointer usually leads to a node at the level above (closer
4634to the `Top' node); and a `Menu' leads to nodes at a level below (closer
4635to `leaves'). (A cross reference can point to a node at any level;
4636see @ref{Cross References}.)@refill
4637
4638Usually, an @code{@@node} command and a chapter structuring command are
4639used in sequence, along with indexing commands. (You may follow the
4640@code{@@node} line with a comment line that reminds you which pointer is
4641which.)@refill
4642
4643Here is the beginning of the chapter in this manual called ``Ending a
4644Texinfo File''. This shows an @code{@@node} line followed by a comment
4645line, an @code{@@chapter} line, and then by indexing lines.@refill
4646
4647@example
4648@group
4649@@node Ending a File, Structuring, Beginning a File, Top
4650@@comment node-name, next, previous, up
4651@@chapter Ending a Texinfo File
4652@@cindex Ending a Texinfo file
4653@@cindex Texinfo file ending
4654@@cindex File ending
4655@end group
4656@end example
4657
4658
4659@node node
4660@section The @code{@@node} Command
4661
4662@cindex Node, defined
4663@findex node
4664
4665A @dfn{node} is a segment of text that begins at an @code{@@node}
4666command and continues until the next @code{@@node} command. The
4667definition of node is different from that for chapter or section. A
4668chapter may contain sections and a section may contain subsections;
4669but a node cannot contain subnodes; the text of a node continues only
4670until the next @code{@@node} command in the file. A node usually
4671contains only one chapter structuring command, the one that follows
4672the @code{@@node} line. On the other hand, in printed output nodes
4673are used only for cross references, so a chapter or section may
4674contain any number of nodes. Indeed, a chapter usually contains
4675several nodes, one for each section, subsection, and
4676subsubsection.@refill
4677
4678To create a node, write an @code{@@node} command at the beginning of a
4679line, and follow it with up to four arguments, separated by commas, on
4680the rest of the same line. The first argument is required; it is the
4681name of this node. The subsequent arguments are the names of the
4682`Next', `Previous', and `Up' pointers, in that order, and may be omitted
4683if your Texinfo document is hierarchically organized (@pxref{makeinfo
4684Pointer Creation}).
4685
4686You may insert spaces before each name if you wish; the spaces are
4687ignored. You must write the name of the node and the names of the
4688`Next', `Previous', and `Up' pointers all on the same line. Otherwise,
4689the formatters fail. (@inforef{Top, info, info}, for more information
4690about nodes in Info.)
4691
4692Usually, you write one of the chapter-structuring command lines
4693immediately after an @code{@@node} line---for example, an
4694@code{@@section} or @code{@@subsection} line. (@xref{Structuring
4695Command Types}.)
4696
4697@quotation
4698@strong{Please note:} The GNU Emacs Texinfo mode updating commands work
4699only with Texinfo files in which @code{@@node} lines are followed by chapter
4700structuring lines. @xref{Updating Requirements}.@refill
4701@end quotation
4702
4703@TeX{} uses @code{@@node} lines to identify the names to use for cross
4704references. For this reason, you must write @code{@@node} lines in a
4705Texinfo file that you intend to format for printing, even if you do not
4706intend to format it for Info. (Cross references, such as the one at the
4707end of this sentence, are made with @code{@@xref} and related commands;
4708see @ref{Cross References}.)@refill
4709
4710@menu
4711* Node Names:: How to choose node and pointer names.
4712* Writing a Node:: How to write an @code{@@node} line.
4713* Node Line Tips:: Keep names short.
4714* Node Line Requirements:: Keep names unique, without @@-commands.
4715* First Node:: How to write a `Top' node.
4716* makeinfo top command:: How to use the @code{@@top} command.
|
4637* Top Node Summary:: Write a brief description for readers.
| |
4638@end menu
4639
4640
4641@node Node Names
4642@subsection Choosing Node and Pointer Names
4643
4644@cindex Node names, choosing
4645The name of a node identifies the node. The pointers enable
4646you to reach other nodes and consist of the names of those nodes.@refill
4647
4648Normally, a node's `Up' pointer contains the name of the node whose menu
4649mentions that node. The node's `Next' pointer contains the name of the
4650node that follows that node in that menu and its `Previous' pointer
4651contains the name of the node that precedes it in that menu. When a
4652node's `Previous' node is the same as its `Up' node, both node pointers
4653name the same node.@refill
4654
4655Usually, the first node of a Texinfo file is the `Top' node, and its
4656`Up' and `Previous' pointers point to the @file{dir} file, which
4657contains the main menu for all of Info.@refill
4658
4659The `Top' node itself contains the main or master menu for the manual.
4660Also, it is helpful to include a brief description of the manual in the
4661`Top' node. @xref{First Node}, for information on how to write the
4662first node of a Texinfo file.@refill
4663
4664Even when you explicitly specify all pointers, that does not mean you
4665can write the nodes in the Texinfo source file in an arbitrary order!
4666Because @TeX{} processes the file sequentially, irrespective of node
4667pointers, you must write the nodes in the order you wish them to appear
4668in the printed output.
4669
4670
4671@node Writing a Node
4672@subsection How to Write an @code{@@node} Line
4673@cindex Writing an @code{@@node} line
4674@cindex @code{@@node} line writing
4675@cindex Node line writing
4676
4677The easiest way to write an @code{@@node} line is to write @code{@@node}
4678at the beginning of a line and then the name of the node, like
4679this:@refill
4680
4681@example
4682@@node @var{node-name}
4683@end example
4684
4685If you are using GNU Emacs, you can use the update node commands
4686provided by Texinfo mode to insert the names of the pointers; or you
4687can leave the pointers out of the Texinfo file and let @code{makeinfo}
4688insert node pointers into the Info file it creates. (@xref{Texinfo
4689Mode}, and @ref{makeinfo Pointer Creation}.)@refill
4690
4691Alternatively, you can insert the `Next', `Previous', and `Up'
4692pointers yourself. If you do this, you may find it helpful to use the
4693Texinfo mode keyboard command @kbd{C-c C-c n}. This command inserts
4694@samp{@@node} and a comment line listing the names of the pointers in
4695their proper order. The comment line helps you keep track of which
4696arguments are for which pointers. This comment line is especially useful
4697if you are not familiar with Texinfo.@refill
4698
4699The template for a fully-written-out node line with `Next', `Previous',
4700and `Up' pointers looks like this:@refill
4701
4702@example
4703@@node @var{node-name}, @var{next}, @var{previous}, @var{up}
4704@end example
4705
4706If you wish, you can ignore @code{@@node} lines altogether in your first
4707draft and then use the @code{texinfo-insert-node-lines} command to
4708create @code{@@node} lines for you. However, we do not recommend this
4709practice. It is better to name the node itself at the same time that
4710you write a segment so you can easily make cross references. A large
4711number of cross references are an especially important feature of a good
4712Info file.
4713
4714After you have inserted an @code{@@node} line, you should immediately
4715write an @@-command for the chapter or section and insert its name.
4716Next (and this is important!), put in several index entries. Usually,
4717you will find at least two and often as many as four or five ways of
4718referring to the node in the index. Use them all. This will make it
4719much easier for people to find the node.
4720
4721
4722@node Node Line Tips
4723@subsection @code{@@node} Line Tips
4724
4725Here are three suggestions:
4726
4727@itemize @bullet
4728@item
4729Try to pick node names that are informative but short.@refill
4730
4731In the Info file, the file name, node name, and pointer names are all
4732inserted on one line, which may run into the right edge of the window.
4733(This does not cause a problem with Info, but is ugly.)@refill
4734
4735@item
4736Try to pick node names that differ from each other near the beginnings
4737of their names. This way, it is easy to use automatic name completion in
4738Info.@refill
4739
4740@item
4741By convention, node names are capitalized just as they would be for
4742section or chapter titles---initial and significant words are
4743capitalized; others are not.@refill
4744@end itemize
4745
4746
4747@node Node Line Requirements, First Node, Node Line Tips, node
4748@subsection @code{@@node} Line Requirements
4749
4750@cindex Node line requirements
4751@cindex Restrictions on node names
4752Here are several requirements for @code{@@node} lines:
4753
4754@itemize @bullet
4755@cindex Unique nodename requirement
4756@cindex Node name must be unique
4757@item
4758All the node names for a single Info file must be unique.@refill
4759
4760Duplicates confuse the Info movement commands. This means, for
4761example, that if you end every chapter with a summary, you must name
4762each summary node differently. You cannot just call each one
4763``Summary''. You may, however, duplicate the titles of chapters, sections,
4764and the like. Thus you can end each chapter in a book with a section
4765called ``Summary'', so long as the node names for those sections are all
4766different.@refill
4767
4768@item
4769A pointer name must be the name of a node.@refill
4770
4771The node to which a pointer points may come before or after the
4772node containing the pointer.
4773
4774@cindex @@-commands in nodename
4775@cindex Node name, should not contain @@-commands
4776@item
4777@w{@@-commands} used in node names generally confuse Info, so you
4778should avoid them. This includes punctuation characters that are
4779escaped with a @samp{@@}, such as @code{@@} and @code{@{}. For a few
4780rare cases when this is useful, Texinfo has limited support for using
4781@w{@@-commands} in node names; see @ref{Pointer Validation}.
4782
4783@need 750
4784Thus, the beginning of the section called @code{@@chapter} looks like
4785this:@refill
4786
4787@smallexample
4788@group
4789@@node chapter, unnumbered & appendix, makeinfo top, Structuring
4790@@comment node-name, next, previous, up
4791@@section @@code@{@@@@chapter@}
4792@@findex chapter
4793@end group
4794@end smallexample
4795
4796@item
4797@cindex Parentheses in nodename
4798You cannot use parentheses in node names, because a node name such as
4799@samp{(foo)bar} is interpreted by the Info readers as a node
4800@samp{bar} in an Info file @file{foo}.
4801
4802@item
4803@cindex Apostrophe in nodename
4804@cindex Colon in nodename
4805@cindex Comma in nodename
4806@cindex Period in nodename
4807@cindex Characters, invalid in node name
4808@cindex Invalid characters in node names
4809Unfortunately, you cannot use periods, commas, colons or apostrophes
4810within a node name; these confuse @TeX{} or the Info formatters.
4811
4812@need 700
4813For example, the following is a section title:
4814
4815@smallexample
4816@@code@{@@@@unnumberedsec@}, @@code@{@@@@appendixsec@}, @@code@{@@@@heading@}
4817@end smallexample
4818
4819@noindent
4820The corresponding node name is:
4821
4822@smallexample
4823unnumberedsec appendixsec heading
4824@end smallexample
4825
| 4717@end menu
4718
4719
4720@node Node Names
4721@subsection Choosing Node and Pointer Names
4722
4723@cindex Node names, choosing
4724The name of a node identifies the node. The pointers enable
4725you to reach other nodes and consist of the names of those nodes.@refill
4726
4727Normally, a node's `Up' pointer contains the name of the node whose menu
4728mentions that node. The node's `Next' pointer contains the name of the
4729node that follows that node in that menu and its `Previous' pointer
4730contains the name of the node that precedes it in that menu. When a
4731node's `Previous' node is the same as its `Up' node, both node pointers
4732name the same node.@refill
4733
4734Usually, the first node of a Texinfo file is the `Top' node, and its
4735`Up' and `Previous' pointers point to the @file{dir} file, which
4736contains the main menu for all of Info.@refill
4737
4738The `Top' node itself contains the main or master menu for the manual.
4739Also, it is helpful to include a brief description of the manual in the
4740`Top' node. @xref{First Node}, for information on how to write the
4741first node of a Texinfo file.@refill
4742
4743Even when you explicitly specify all pointers, that does not mean you
4744can write the nodes in the Texinfo source file in an arbitrary order!
4745Because @TeX{} processes the file sequentially, irrespective of node
4746pointers, you must write the nodes in the order you wish them to appear
4747in the printed output.
4748
4749
4750@node Writing a Node
4751@subsection How to Write an @code{@@node} Line
4752@cindex Writing an @code{@@node} line
4753@cindex @code{@@node} line writing
4754@cindex Node line writing
4755
4756The easiest way to write an @code{@@node} line is to write @code{@@node}
4757at the beginning of a line and then the name of the node, like
4758this:@refill
4759
4760@example
4761@@node @var{node-name}
4762@end example
4763
4764If you are using GNU Emacs, you can use the update node commands
4765provided by Texinfo mode to insert the names of the pointers; or you
4766can leave the pointers out of the Texinfo file and let @code{makeinfo}
4767insert node pointers into the Info file it creates. (@xref{Texinfo
4768Mode}, and @ref{makeinfo Pointer Creation}.)@refill
4769
4770Alternatively, you can insert the `Next', `Previous', and `Up'
4771pointers yourself. If you do this, you may find it helpful to use the
4772Texinfo mode keyboard command @kbd{C-c C-c n}. This command inserts
4773@samp{@@node} and a comment line listing the names of the pointers in
4774their proper order. The comment line helps you keep track of which
4775arguments are for which pointers. This comment line is especially useful
4776if you are not familiar with Texinfo.@refill
4777
4778The template for a fully-written-out node line with `Next', `Previous',
4779and `Up' pointers looks like this:@refill
4780
4781@example
4782@@node @var{node-name}, @var{next}, @var{previous}, @var{up}
4783@end example
4784
4785If you wish, you can ignore @code{@@node} lines altogether in your first
4786draft and then use the @code{texinfo-insert-node-lines} command to
4787create @code{@@node} lines for you. However, we do not recommend this
4788practice. It is better to name the node itself at the same time that
4789you write a segment so you can easily make cross references. A large
4790number of cross references are an especially important feature of a good
4791Info file.
4792
4793After you have inserted an @code{@@node} line, you should immediately
4794write an @@-command for the chapter or section and insert its name.
4795Next (and this is important!), put in several index entries. Usually,
4796you will find at least two and often as many as four or five ways of
4797referring to the node in the index. Use them all. This will make it
4798much easier for people to find the node.
4799
4800
4801@node Node Line Tips
4802@subsection @code{@@node} Line Tips
4803
4804Here are three suggestions:
4805
4806@itemize @bullet
4807@item
4808Try to pick node names that are informative but short.@refill
4809
4810In the Info file, the file name, node name, and pointer names are all
4811inserted on one line, which may run into the right edge of the window.
4812(This does not cause a problem with Info, but is ugly.)@refill
4813
4814@item
4815Try to pick node names that differ from each other near the beginnings
4816of their names. This way, it is easy to use automatic name completion in
4817Info.@refill
4818
4819@item
4820By convention, node names are capitalized just as they would be for
4821section or chapter titles---initial and significant words are
4822capitalized; others are not.@refill
4823@end itemize
4824
4825
4826@node Node Line Requirements, First Node, Node Line Tips, node
4827@subsection @code{@@node} Line Requirements
4828
4829@cindex Node line requirements
4830@cindex Restrictions on node names
4831Here are several requirements for @code{@@node} lines:
4832
4833@itemize @bullet
4834@cindex Unique nodename requirement
4835@cindex Node name must be unique
4836@item
4837All the node names for a single Info file must be unique.@refill
4838
4839Duplicates confuse the Info movement commands. This means, for
4840example, that if you end every chapter with a summary, you must name
4841each summary node differently. You cannot just call each one
4842``Summary''. You may, however, duplicate the titles of chapters, sections,
4843and the like. Thus you can end each chapter in a book with a section
4844called ``Summary'', so long as the node names for those sections are all
4845different.@refill
4846
4847@item
4848A pointer name must be the name of a node.@refill
4849
4850The node to which a pointer points may come before or after the
4851node containing the pointer.
4852
4853@cindex @@-commands in nodename
4854@cindex Node name, should not contain @@-commands
4855@item
4856@w{@@-commands} used in node names generally confuse Info, so you
4857should avoid them. This includes punctuation characters that are
4858escaped with a @samp{@@}, such as @code{@@} and @code{@{}. For a few
4859rare cases when this is useful, Texinfo has limited support for using
4860@w{@@-commands} in node names; see @ref{Pointer Validation}.
4861
4862@need 750
4863Thus, the beginning of the section called @code{@@chapter} looks like
4864this:@refill
4865
4866@smallexample
4867@group
4868@@node chapter, unnumbered & appendix, makeinfo top, Structuring
4869@@comment node-name, next, previous, up
4870@@section @@code@{@@@@chapter@}
4871@@findex chapter
4872@end group
4873@end smallexample
4874
4875@item
4876@cindex Parentheses in nodename
4877You cannot use parentheses in node names, because a node name such as
4878@samp{(foo)bar} is interpreted by the Info readers as a node
4879@samp{bar} in an Info file @file{foo}.
4880
4881@item
4882@cindex Apostrophe in nodename
4883@cindex Colon in nodename
4884@cindex Comma in nodename
4885@cindex Period in nodename
4886@cindex Characters, invalid in node name
4887@cindex Invalid characters in node names
4888Unfortunately, you cannot use periods, commas, colons or apostrophes
4889within a node name; these confuse @TeX{} or the Info formatters.
4890
4891@need 700
4892For example, the following is a section title:
4893
4894@smallexample
4895@@code@{@@@@unnumberedsec@}, @@code@{@@@@appendixsec@}, @@code@{@@@@heading@}
4896@end smallexample
4897
4898@noindent
4899The corresponding node name is:
4900
4901@smallexample
4902unnumberedsec appendixsec heading
4903@end smallexample
4904
|
4826@cindex Case in nodename
| 4905@cindex Case in node name
|
4827@item
4828Case is significant.
4829@end itemize
4830
4831
| 4906@item
4907Case is significant.
4908@end itemize
4909
4910
|
4832@node First Node, makeinfo top command, Node Line Requirements, node
4833@comment node-name, next, previous, up
| 4911@node First Node
|
4834@subsection The First Node
4835@cindex Top node is first
4836@cindex First node
4837
4838The first node of a Texinfo file is the @dfn{Top} node, except in an
| 4912@subsection The First Node
4913@cindex Top node is first
4914@cindex First node
4915
4916The first node of a Texinfo file is the @dfn{Top} node, except in an
|
4839included file (@pxref{Include Files}). The Top node contains the main
4840or master menu for the document, and a short summary of the document
4841(@pxref{Top Node Summary}).
| 4917included file (@pxref{Include Files}). The Top node should contain a
4918short summary, copying permissions, and a master menu. @xref{The Top
4919Node}, for more information on the Top node contents and examples.
|
4842
| 4920
|
| 4921Here is a description of the node pointers to be used in the Top node:
4922
4923@itemize @bullet
4924
4925@item
|
4843@cindex Up node of Top node
4844@cindex (dir) as Up node of Top node
4845The Top node (which must be named @samp{top} or @samp{Top}) should have
4846as its `Up' node the name of a node in another file, where there is a
| 4926@cindex Up node of Top node
4927@cindex (dir) as Up node of Top node
4928The Top node (which must be named @samp{top} or @samp{Top}) should have
4929as its `Up' node the name of a node in another file, where there is a
|
4847menu that leads to this file. Specify the file name in parentheses. If
4848the file is to be installed directly in the Info directory file, use
4849@samp{(dir)} as the parent of the Top node; this is short for
4850@samp{(dir)top}, and specifies the Top node in the @file{dir} file,
4851which contains the main menu for the Info system as a whole. For
4852example, the @code{@@node Top} line of this manual looks like this:
| 4930menu that leads to this file. Specify the file name in parentheses.
|
4853
| 4931
|
4854@example
4855@@node Top, Copying, , (dir)
4856@end example
| 4932Usually, all Info files are installed in the same Info directory tree;
4933in this case, use @samp{(dir)} as the parent of the Top node; this is
4934short for @samp{(dir)top}, and specifies the Top node in the @file{dir}
4935file, which contains the main menu for the Info system as a whole.
|
4857
| 4936
|
4858@noindent
4859(You can use the Texinfo updating commands or the @code{makeinfo}
4860utility to insert these pointers automatically.)
4861
| 4937@item
|
4862@cindex Previous node of Top node
| 4938@cindex Previous node of Top node
|
4863Do not define the `Previous' node of the Top node to be @samp{(dir)}, as
4864it causes confusing behavior for users: if you are in the Top node and
4865hits @key{DEL} to go backwards, you wind up in the middle of the
4866some other entry in the @file{dir} file, which has nothing to do with
4867what you were reading.
| 4939On the other hand, do not define the `Previous' node of the Top node to
4940be @samp{(dir)}, as it causes confusing behavior for users: if you are
4941in the Top node and hits @key{DEL} to go backwards, you wind up in the
4942middle of the some other entry in the @file{dir} file, which has nothing
4943to do with what you were reading.
|
4868
| 4944
|
| 4945@item
4946@cindex Next node of Top node
4947The `Next' node of the Top node should be the first chapter in your
4948document.
4949
4950@end itemize
4951
|
4869@xref{Installing an Info File}, for more information about installing
4870an Info file in the @file{info} directory.
4871
| 4952@xref{Installing an Info File}, for more information about installing
4953an Info file in the @file{info} directory.
4954
|
| 4955For concreteness, here is an example with explicit pointers (which you
4956can maintain automatically with the texinfo mode commands):
|
4872
| 4957
|
4873@node makeinfo top command, Top Node Summary, First Node, node
4874@comment node-name, next, previous, up
| 4958Or you can leave the pointers off entirely and let the tools implicitly
4959define them. This is recommended. Thus:
4960
4961@example
4962@@node Top
4963@end example
4964
4965
4966@node makeinfo top command
|
4875@subsection The @code{@@top} Sectioning Command
4876@findex top @r{(@@-command)}
4877
| 4967@subsection The @code{@@top} Sectioning Command
4968@findex top @r{(@@-command)}
4969
|
4878A special sectioning command, @code{@@top}, has been created for use
4879with the @code{@@node Top} line. The @code{@@top} sectioning command tells
| 4970A special sectioning command, @code{@@top} should be used with the
4971@code{@@node Top} line. The @code{@@top} sectioning command tells
|
4880@code{makeinfo} that it marks the `Top' node in the file. It provides
| 4972@code{makeinfo} that it marks the `Top' node in the file. It provides
|
4881the information that @code{makeinfo} needs to insert node
4882pointers automatically. Write the @code{@@top} command at the
4883beginning of the line immediately following the @code{@@node Top}
4884line. Write the title on the remaining part of the same line as the
4885@code{@@top} command.@refill
| 4973the information that @code{makeinfo} needs to insert node pointers
4974automatically. Write the @code{@@top} command at the beginning of the
4975line immediately following the @code{@@node Top} line. Write the title
4976on the remaining part of the same line as the @code{@@top} command.
|
4886
| 4977
|
4887In Info, the @code{@@top} sectioning command causes the title to appear on a
4888line by itself, with a line of asterisks inserted underneath.@refill
| 4978In Info, the @code{@@top} sectioning command causes the title to appear
4979on a line by itself, with a line of asterisks inserted underneath, as
4980other sectioning commands do.
|
4889
4890In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
4891sectioning command is merely a synonym for @code{@@unnumbered}.
4892Neither of these formatters require an @code{@@top} command, and do
4893nothing special with it. You can use @code{@@chapter} or
4894@code{@@unnumbered} after the @code{@@node Top} line when you use
4895these formatters. Also, you can use @code{@@chapter} or
4896@code{@@unnumbered} when you use the Texinfo updating commands to
| 4981
4982In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
4983sectioning command is merely a synonym for @code{@@unnumbered}.
4984Neither of these formatters require an @code{@@top} command, and do
4985nothing special with it. You can use @code{@@chapter} or
4986@code{@@unnumbered} after the @code{@@node Top} line when you use
4987these formatters. Also, you can use @code{@@chapter} or
4988@code{@@unnumbered} when you use the Texinfo updating commands to
|
4897create or update pointers and menus.@refill
| 4989create or update pointers and menus.
|
4898
| 4990
|
| 4991Thus, in practice, a Top node starts like this:
|
4899
| 4992
|
4900@node Top Node Summary, , makeinfo top command, node
4901@subsection The `Top' Node Summary
4902@cindex @samp{@r{Top}} node summary
| 4993@example
4994@@node Top
4995@@top Your Manual Title
4996@end example
|
4903
| 4997
|
4904You can help readers by writing a summary in the `Top' node, after the
4905@code{@@top} line, before the main or master menu. The summary should
4906briefly describe the document. In Info, this summary will appear just
4907before the master menu. In a printed manual, this summary will appear
4908on a page of its own.@refill
| |
4909
| 4998
|
4910If you do not want the summary to appear on a page of its own in a
4911printed manual, you can enclose the whole of the `Top' node, including
4912the @code{@@node Top} line and the @code{@@top} sectioning command line
4913or other sectioning command line between @code{@@ifinfo} and @code{@@end
4914ifinfo}. This prevents any of the text from appearing in the printed
4915output. (@pxref{Conditionals, , Conditionally Visible Text}). You can
4916repeat the brief description from the `Top' node within @code{@@iftex}
4917@dots{} @code{@@end iftex} at the beginning of the first chapter, for
4918those who read the printed manual. This saves paper and may look
4919neater.@refill
4920
4921You should write the version number of the program to which the manual
4922applies in the summary. This helps the reader keep track of which
4923manual is for which version of the program. If the manual changes more
4924frequently than the program or is independent of it, you should also
4925include an edition number for the manual. (The title page should also
4926contain this information: see @ref{titlepage, ,
4927@code{@@titlepage}}.)@refill
4928
4929
| |
4930@node makeinfo Pointer Creation
4931@section Creating Pointers with @code{makeinfo}
4932@cindex Creating pointers with @code{makeinfo}
4933@cindex Pointer creation with @code{makeinfo}
4934@cindex Automatic pointer creation with @code{makeinfo}
4935
4936The @code{makeinfo} program has a feature for automatically defining
4937node pointers for a hierarchically organized file.
4938
4939When you take advantage of this feature, you do not need to write the
4940`Next', `Previous', and `Up' pointers after the name of a node.
4941However, you must write a sectioning command, such as @code{@@chapter}
4942or @code{@@section}, on the line immediately following each truncated
4943@code{@@node} line (except that comment lines may intervene).
4944
4945In addition, you must follow the `Top' @code{@@node} line with a line
4946beginning with @code{@@top} to mark the `Top' node in the
4947file. @xref{makeinfo top, , @code{@@top}}.
4948
4949Finally, you must write the name of each node (except for the `Top'
4950node) in a menu that is one or more hierarchical levels above the
4951node's hierarchical level.
4952
4953This node pointer insertion feature in @code{makeinfo} relieves you from
4954the need to update menus and pointers manually or with Texinfo mode
4955commands. (@xref{Updating Nodes and Menus}.)
4956
4957In most cases, you will want to take advantage of this feature and not
4958redundantly specify node pointers. However, Texinfo documents are not
4959required to be organized hierarchically or in fact contain sectioning
4960commands at all. For example, if you never intend the document to be
4961printed. In those cases, you will need to explicitly specify the pointers.
4962
4963
4964@node anchor
4965@section @code{@@anchor}: Defining Arbitrary Cross-reference Targets
4966
4967@findex anchor
4968@cindex Anchors
4969@cindex Cross-reference targets, arbitrary
4970@cindex Targets for cross-references, arbitrary
4971
4972An @dfn{anchor} is a position in your document, labeled so that
4973cross-references can refer to it, just as they can to nodes. You create
4974an anchor with the @code{@@anchor} command, and give the label as a
4975normal brace-delimited argument. For example:
4976
4977@example
4978This marks the @@anchor@{x-spot@}spot.
4979@dots{}
4980@@xref@{x-spot,,the spot@}.
4981@end example
4982
4983@noindent produces:
4984
4985@example
4986This marks the spot.
4987@dots{}
4988See [the spot], page 1.
4989@end example
4990
4991As you can see, the @code{@@anchor} command itself produces no output.
4992This example defines an anchor `x-spot' just before the word `spot'.
4993You can refer to it later with an @code{@@xref} or other cross-reference
4994command, as shown. @xref{Cross References}, for details on the
4995cross-reference commands.
4996
4997It is best to put @code{@@anchor} commands just before the position you
4998wish to refer to; that way, the reader's eye is led on to the correct
4999text when they jump to the anchor. You can put the @code{@@anchor}
5000command on a line by itself if that helps readability of the source.
5001Spaces are always ignored after @code{@@anchor}.
5002
5003Anchor names and node names may not conflict. Anchors and nodes are
5004given similar treatment in some ways; for example, the @code{goto-node}
5005command in standalone Info takes either an anchor name or a node name as
5006an argument. (@xref{goto-node,,,info-stnd,GNU Info}.)
5007
5008
5009@node Menus
5010@chapter Menus
5011@cindex Menus
5012@findex menu
5013
5014@dfn{Menus} contain pointers to subordinate nodes.@footnote{Menus can
5015carry you to any node, regardless of the hierarchical structure; even to
5016nodes in a different Info file. However, the GNU Emacs Texinfo mode
5017updating commands work only to create menus of subordinate nodes.
5018Conventionally, cross references are used to refer to other nodes.} In
5019Info, you use menus to go to such nodes. Menus have no effect in
5020printed manuals and do not appear in them.
5021
5022By convention, a menu is put at the end of a node since a reader who
5023uses the menu may not see text that follows it. Furthermore, a node
5024that has a menu should not contain much text. If you have a lot of text
5025and a menu, move most of the text into a new subnode---all but a few
5026lines. Otherwise, a reader with a terminal that displays only a few
5027lines may miss the menu and its associated text. As a practical matter,
5028you should locate a menu within 20 lines of the beginning of the
5029node.
5030
5031@menu
5032* Menu Location:: Put a menu in a short node.
5033* Writing a Menu:: What is a menu?
5034* Menu Parts:: A menu entry has three parts.
5035* Less Cluttered Menu Entry:: Two part menu entry.
5036* Menu Example:: Two and three part menu entries.
5037* Other Info Files:: How to refer to a different Info file.
5038@end menu
5039
5040
5041@node Menu Location, Writing a Menu, Menus, Menus
5042@ifinfo
5043@heading Menus Need Short Nodes
5044@end ifinfo
5045@cindex Menu location
5046@cindex Location of menus
5047@cindex Nodes for menus are short
5048@cindex Short nodes for menus
5049
5050The short text before a menu may look awkward in a printed manual. To
5051avoid this, you can write a menu near the beginning of its node and
5052follow the menu by an @code{@@node} line, and then an @code{@@heading}
5053line located within @code{@@ifinfo} and @code{@@end ifinfo}. This way,
5054the menu, @code{@@node} line, and title appear only in the Info file,
| 4999@node makeinfo Pointer Creation
5000@section Creating Pointers with @code{makeinfo}
5001@cindex Creating pointers with @code{makeinfo}
5002@cindex Pointer creation with @code{makeinfo}
5003@cindex Automatic pointer creation with @code{makeinfo}
5004
5005The @code{makeinfo} program has a feature for automatically defining
5006node pointers for a hierarchically organized file.
5007
5008When you take advantage of this feature, you do not need to write the
5009`Next', `Previous', and `Up' pointers after the name of a node.
5010However, you must write a sectioning command, such as @code{@@chapter}
5011or @code{@@section}, on the line immediately following each truncated
5012@code{@@node} line (except that comment lines may intervene).
5013
5014In addition, you must follow the `Top' @code{@@node} line with a line
5015beginning with @code{@@top} to mark the `Top' node in the
5016file. @xref{makeinfo top, , @code{@@top}}.
5017
5018Finally, you must write the name of each node (except for the `Top'
5019node) in a menu that is one or more hierarchical levels above the
5020node's hierarchical level.
5021
5022This node pointer insertion feature in @code{makeinfo} relieves you from
5023the need to update menus and pointers manually or with Texinfo mode
5024commands. (@xref{Updating Nodes and Menus}.)
5025
5026In most cases, you will want to take advantage of this feature and not
5027redundantly specify node pointers. However, Texinfo documents are not
5028required to be organized hierarchically or in fact contain sectioning
5029commands at all. For example, if you never intend the document to be
5030printed. In those cases, you will need to explicitly specify the pointers.
5031
5032
5033@node anchor
5034@section @code{@@anchor}: Defining Arbitrary Cross-reference Targets
5035
5036@findex anchor
5037@cindex Anchors
5038@cindex Cross-reference targets, arbitrary
5039@cindex Targets for cross-references, arbitrary
5040
5041An @dfn{anchor} is a position in your document, labeled so that
5042cross-references can refer to it, just as they can to nodes. You create
5043an anchor with the @code{@@anchor} command, and give the label as a
5044normal brace-delimited argument. For example:
5045
5046@example
5047This marks the @@anchor@{x-spot@}spot.
5048@dots{}
5049@@xref@{x-spot,,the spot@}.
5050@end example
5051
5052@noindent produces:
5053
5054@example
5055This marks the spot.
5056@dots{}
5057See [the spot], page 1.
5058@end example
5059
5060As you can see, the @code{@@anchor} command itself produces no output.
5061This example defines an anchor `x-spot' just before the word `spot'.
5062You can refer to it later with an @code{@@xref} or other cross-reference
5063command, as shown. @xref{Cross References}, for details on the
5064cross-reference commands.
5065
5066It is best to put @code{@@anchor} commands just before the position you
5067wish to refer to; that way, the reader's eye is led on to the correct
5068text when they jump to the anchor. You can put the @code{@@anchor}
5069command on a line by itself if that helps readability of the source.
5070Spaces are always ignored after @code{@@anchor}.
5071
5072Anchor names and node names may not conflict. Anchors and nodes are
5073given similar treatment in some ways; for example, the @code{goto-node}
5074command in standalone Info takes either an anchor name or a node name as
5075an argument. (@xref{goto-node,,,info-stnd,GNU Info}.)
5076
5077
5078@node Menus
5079@chapter Menus
5080@cindex Menus
5081@findex menu
5082
5083@dfn{Menus} contain pointers to subordinate nodes.@footnote{Menus can
5084carry you to any node, regardless of the hierarchical structure; even to
5085nodes in a different Info file. However, the GNU Emacs Texinfo mode
5086updating commands work only to create menus of subordinate nodes.
5087Conventionally, cross references are used to refer to other nodes.} In
5088Info, you use menus to go to such nodes. Menus have no effect in
5089printed manuals and do not appear in them.
5090
5091By convention, a menu is put at the end of a node since a reader who
5092uses the menu may not see text that follows it. Furthermore, a node
5093that has a menu should not contain much text. If you have a lot of text
5094and a menu, move most of the text into a new subnode---all but a few
5095lines. Otherwise, a reader with a terminal that displays only a few
5096lines may miss the menu and its associated text. As a practical matter,
5097you should locate a menu within 20 lines of the beginning of the
5098node.
5099
5100@menu
5101* Menu Location:: Put a menu in a short node.
5102* Writing a Menu:: What is a menu?
5103* Menu Parts:: A menu entry has three parts.
5104* Less Cluttered Menu Entry:: Two part menu entry.
5105* Menu Example:: Two and three part menu entries.
5106* Other Info Files:: How to refer to a different Info file.
5107@end menu
5108
5109
5110@node Menu Location, Writing a Menu, Menus, Menus
5111@ifinfo
5112@heading Menus Need Short Nodes
5113@end ifinfo
5114@cindex Menu location
5115@cindex Location of menus
5116@cindex Nodes for menus are short
5117@cindex Short nodes for menus
5118
5119The short text before a menu may look awkward in a printed manual. To
5120avoid this, you can write a menu near the beginning of its node and
5121follow the menu by an @code{@@node} line, and then an @code{@@heading}
5122line located within @code{@@ifinfo} and @code{@@end ifinfo}. This way,
5123the menu, @code{@@node} line, and title appear only in the Info file,
|
5055not the printed document.@refill
| 5124not the printed document.
|
5056
5057For example, the preceding two paragraphs follow an Info-only menu,
| 5125
5126For example, the preceding two paragraphs follow an Info-only menu,
|
5058@code{@@node} line, and heading, and look like this:@refill
| 5127@code{@@node} line, and heading, and look like this:
|
5059
5060@example
5061@group
5062@@menu
5063* Menu Location:: Put a menu in a short node.
5064* Writing a Menu:: What is a menu?
5065* Menu Parts:: A menu entry has three parts.
5066* Less Cluttered Menu Entry:: Two part menu entry.
5067* Menu Example:: Two and three part entries.
5068* Other Info Files:: How to refer to a different
5069 Info file.
5070@@end menu
5071
5072@@node Menu Location, Writing a Menu, , Menus
5073@@ifinfo
5074@@heading Menus Need Short Nodes
5075@@end ifinfo
5076@end group
5077@end example
5078
| 5128
5129@example
5130@group
5131@@menu
5132* Menu Location:: Put a menu in a short node.
5133* Writing a Menu:: What is a menu?
5134* Menu Parts:: A menu entry has three parts.
5135* Less Cluttered Menu Entry:: Two part menu entry.
5136* Menu Example:: Two and three part entries.
5137* Other Info Files:: How to refer to a different
5138 Info file.
5139@@end menu
5140
5141@@node Menu Location, Writing a Menu, , Menus
5142@@ifinfo
5143@@heading Menus Need Short Nodes
5144@@end ifinfo
5145@end group
5146@end example
5147
|
5079The Texinfo file for this document contains more than a dozen
5080examples of this procedure. One is at the beginning of this chapter;
5081another is at the beginning of @ref{Cross References}. @refill
| 5148The Texinfo file for this document contains a number of
5149examples of this procedure; one is at the beginning of this chapter.
|
5082
5083
5084@node Writing a Menu, Menu Parts, Menu Location, Menus
5085@section Writing a Menu
5086@cindex Writing a menu
5087@cindex Menu writing
5088
5089A menu consists of an @code{@@menu} command on a line by
5090itself followed by menu entry lines or menu comment lines
5091and then by an @code{@@end menu} command on a line by
5092itself.@refill
5093
5094A menu looks like this:@refill
5095
5096@example
5097@group
5098@@menu
5099Larger Units of Text
5100
5101* Files:: All about handling files.
5102* Multiples: Buffers. Multiple buffers; editing
5103 several files at once.
5104@@end menu
5105@end group
5106@end example
5107
5108In a menu, every line that begins with an @w{@samp{* }} is a @dfn{menu
5109entry}. (Note the space after the asterisk.) A line that does not
5110start with an @w{@samp{* }} may also appear in a menu. Such a line is
5111not a menu entry but is a menu comment line that appears in the Info
5112file. In the example above, the line @samp{Larger Units of Text} is a
5113menu comment line; the two lines starting with @w{@samp{* }} are menu
5114@cindex Spaces, in menus
5115entries. Space characters in a menu are preserved as-is; this allows
5116you to format the menu as you wish.
5117
5118
5119@node Menu Parts, Less Cluttered Menu Entry, Writing a Menu, Menus
5120@section The Parts of a Menu
5121@cindex Parts of a menu
5122@cindex Menu parts
5123@cindex @code{@@menu} parts
5124
5125A menu entry has three parts, only the second of which is required:
5126
5127@enumerate
5128@item
5129The menu entry name (optional).
5130
5131@item
5132The name of the node (required).
5133
5134@item
5135A description of the item (optional).
5136@end enumerate
5137
5138The template for a menu entry looks like this:@refill
5139
5140@example
5141* @var{menu-entry-name}: @var{node-name}. @var{description}
5142@end example
5143
5144Follow the menu entry name with a single colon and follow the node name
5145with tab, comma, period, or newline.@refill
5146
5147In Info, a user selects a node with the @kbd{m} (@code{Info-menu})
5148command. The menu entry name is what the user types after the @kbd{m}
5149command.@refill
5150
5151The third part of a menu entry is a descriptive phrase or sentence.
5152Menu entry names and node names are often short; the description
5153explains to the reader what the node is about. A useful description
5154complements the node name rather than repeats it. The description,
5155which is optional, can spread over two or more lines; if it does, some
5156authors prefer to indent the second line while others prefer to align it
5157with the first (and all others). It's up to you.
5158
5159
5160@node Less Cluttered Menu Entry, Menu Example, Menu Parts, Menus
5161@comment node-name, next, previous, up
5162@section Less Cluttered Menu Entry
5163@cindex Two part menu entry
5164@cindex Double-colon menu entries
5165@cindex Menu entries with two colons
5166@cindex Less cluttered menu entry
5167@cindex Uncluttered menu entry
5168
5169When the menu entry name and node name are the same, you can write
5170the name immediately after the asterisk and space at the beginning of
5171the line and follow the name with two colons.@refill
5172
5173@need 800
5174For example, write
5175
5176@example
5177* Name:: @var{description}
5178@end example
5179
5180@need 800
5181@noindent
5182instead of
5183
5184@example
5185* Name: Name. @var{description}
5186@end example
5187
5188You should use the node name for the menu entry name whenever possible,
5189since it reduces visual clutter in the menu.@refill
5190
5191@node Menu Example, Other Info Files, Less Cluttered Menu Entry, Menus
5192@comment node-name, next, previous, up
5193@section A Menu Example
5194@cindex Menu example
5195@cindex Example menu
5196
5197A menu looks like this in Texinfo:@refill
5198
5199@example
5200@group
5201@@menu
5202* menu entry name: Node name. A short description.
5203* Node name:: This form is preferred.
5204@@end menu
5205@end group
5206@end example
5207
5208@need 800
5209@noindent
5210This produces:
5211
5212@example
5213@group
5214* menu:
5215
5216* menu entry name: Node name. A short description.
5217* Node name:: This form is preferred.
5218@end group
5219@end example
5220
5221@need 700
5222Here is an example as you might see it in a Texinfo file:@refill
5223
5224@example
5225@group
5226@@menu
5227Larger Units of Text
5228
5229* Files:: All about handling files.
5230* Multiples: Buffers. Multiple buffers; editing
5231 several files at once.
5232@@end menu
5233@end group
5234@end example
5235
5236@need 800
5237@noindent
5238This produces:
5239
5240@example
5241@group
5242* menu:
5243Larger Units of Text
5244
5245* Files:: All about handling files.
5246* Multiples: Buffers. Multiple buffers; editing
5247 several files at once.
5248@end group
5249@end example
5250
5251In this example, the menu has two entries. @samp{Files} is both a menu
5252entry name and the name of the node referred to by that name.
5253@samp{Multiples} is the menu entry name; it refers to the node named
5254@samp{Buffers}. The line @samp{Larger Units of Text} is a comment; it
5255appears in the menu, but is not an entry.@refill
5256
5257Since no file name is specified with either @samp{Files} or
5258@samp{Buffers}, they must be the names of nodes in the same Info file
5259(@pxref{Other Info Files, , Referring to Other Info Files}).@refill
5260
5261@node Other Info Files, , Menu Example, Menus
5262@comment node-name, next, previous, up
5263@section Referring to Other Info Files
5264@cindex Referring to other Info files
5265@cindex Nodes in other Info files
5266@cindex Other Info files' nodes
5267@cindex Going to other Info files' nodes
5268@cindex Info; other files' nodes
5269
5270You can create a menu entry that enables a reader in Info to go to a
5271node in another Info file by writing the file name in parentheses just
5272before the node name. In this case, you should use the three-part menu
5273entry format, which saves the reader from having to type the file
5274name.@refill
5275
5276@need 800
5277The format looks like this:@refill
5278
5279@example
5280@group
5281@@menu
5282* @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description}
5283* @var{second-entry-name}:(@var{filename})@var{second-node}. @var{description}
5284@@end menu
5285@end group
5286@end example
5287
5288For example, to refer directly to the @samp{Outlining} and
5289@samp{Rebinding} nodes in the @cite{Emacs Manual}, you would write a
5290menu like this:@refill
5291
5292@example
5293@group
5294@@menu
5295* Outlining: (emacs)Outline Mode. The major mode for
5296 editing outlines.
5297* Rebinding: (emacs)Rebinding. How to redefine the
5298 meaning of a key.
5299@@end menu
5300@end group
5301@end example
5302
5303If you do not list the node name, but only name the file, then Info
5304presumes that you are referring to the `Top' node.@refill
5305
5306The @file{dir} file that contains the main menu for Info has menu
5307entries that list only file names. These take you directly to the `Top'
5308nodes of each Info document. (@xref{Installing an Info File}.)
5309
5310@need 700
5311For example:
5312
5313@example
5314@group
5315* Info: (info). Documentation browsing system.
5316* Emacs: (emacs). The extensible, self-documenting
5317 text editor.
5318@end group
5319@end example
5320
5321@noindent
5322(The @file{dir} top level directory for the Info system is an Info file,
5323not a Texinfo file, but a menu entry looks the same in both types of
5324file.)@refill
5325
5326The GNU Emacs Texinfo mode menu updating commands only work with nodes
5327within the current buffer, so you cannot use them to create menus that
5328refer to other files. You must write such menus by hand.
5329
5330
5331@node Cross References
5332@chapter Cross References
5333@cindex Making cross references
5334@cindex Cross references
5335@cindex References
5336
5337@dfn{Cross references} are used to refer the reader to other parts of the
5338same or different Texinfo files. In Texinfo, nodes and anchors are the
5339places to which cross references can refer.
5340
5341@menu
5342* References:: What cross references are for.
5343* Cross Reference Commands:: A summary of the different commands.
5344* Cross Reference Parts:: A cross reference has several parts.
5345* xref:: Begin a reference with `See' @dots{}
5346* Top Node Naming:: How to refer to the beginning of another file.
5347* ref:: A reference for the last part of a sentence.
5348* pxref:: How to write a parenthetical cross reference.
5349* inforef:: How to refer to an Info-only file.
5350* uref:: How to refer to a uniform resource locator.
5351@end menu
5352
5353@node References, Cross Reference Commands, Cross References, Cross References
5354@ifinfo
5355@heading What References Are For
5356@end ifinfo
5357
5358Often, but not always, a printed document should be designed so that
5359it can be read sequentially. People tire of flipping back and forth
5360to find information that should be presented to them as they need
5361it.@refill
5362
5363However, in any document, some information will be too detailed for
5364the current context, or incidental to it; use cross references to
5365provide access to such information. Also, an online help system or a
5366reference manual is not like a novel; few read such documents in
5367sequence from beginning to end. Instead, people look up what they
5368need. For this reason, such creations should contain many cross
5369references to help readers find other information that they may not
5370have read.@refill
5371
5372In a printed manual, a cross reference results in a page reference,
5373unless it is to another manual altogether, in which case the cross
5374reference names that manual.@refill
5375
5376In Info, a cross reference results in an entry that you can follow using
5377the Info @samp{f} command. (@inforef{Help-Adv, Some advanced Info
5378commands, info}.)@refill
5379
5380The various cross reference commands use nodes (or anchors,
5381@pxref{anchor,,@code{@@anchor}}) to define cross reference locations.
5382This is evident in Info, in which a cross reference takes you to the
5383specified location. @TeX{} also uses nodes to define cross reference
5384locations, but the action is less obvious. When @TeX{} generates a DVI
5385file, it records each node's page number and uses the page numbers in making
5386references. Thus, if you are writing a manual that will only be
5387printed, and will not be used online, you must nonetheless write
5388@code{@@node} lines to name the places to which you make cross
5389references.@refill
5390
5391@need 800
5392@node Cross Reference Commands, Cross Reference Parts, References, Cross References
5393@comment node-name, next, previous, up
5394@section Different Cross Reference Commands
5395@cindex Different cross reference commands
5396
5397There are four different cross reference commands:@refill
5398
5399@table @code
5400@item @@xref
5401Used to start a sentence in the printed manual saying @w{`See @dots{}'}
5402or an Info cross-reference saying @samp{*Note @var{name}: @var{node}.}.
5403
5404@item @@ref
5405Used within or, more often, at the end of a sentence; same as
5406@code{@@xref} for Info; produces just the reference in the printed
5407manual without a preceding `See'.@refill
5408
5409@item @@pxref
5410Used within parentheses to make a reference that suits both an Info
5411file and a printed book. Starts with a lower case `see' within the
5412printed manual. (@samp{p} is for `parenthesis'.)@refill
5413
5414@item @@inforef
5415Used to make a reference to an Info file for which there is no printed
5416manual.@refill
5417@end table
5418
5419@noindent
5420(The @code{@@cite} command is used to make references to books and
5421manuals for which there is no corresponding Info file and, therefore,
5422no node to which to point. @xref{cite, , @code{@@cite}}.)@refill
5423
5424@node Cross Reference Parts, xref, Cross Reference Commands, Cross References
5425@comment node-name, next, previous, up
5426@section Parts of a Cross Reference
5427@cindex Cross reference parts
5428@cindex Parts of a cross reference
5429
5430A cross reference command requires only one argument, which is the
5431name of the node to which it refers. But a cross reference command
5432may contain up to four additional arguments. By using these
5433arguments, you can provide a cross reference name for Info, a topic
5434description or section title for the printed output, the name of a
5435different Info file, and the name of a different printed
5436manual.@refill
5437
5438Here is a simple cross reference example:@refill
5439
5440@example
5441@@xref@{Node name@}.
5442@end example
5443
5444@noindent
5445which produces
5446
5447@example
5448*Note Node name::.
5449@end example
5450
5451@noindent
5452and
5453
5454@quotation
5455See Section @var{nnn} [Node name], page @var{ppp}.
5456@end quotation
5457
5458@need 700
5459Here is an example of a full five-part cross reference:@refill
5460
5461@example
5462@group
5463@@xref@{Node name, Cross Reference Name, Particular Topic,
5464info-file-name, A Printed Manual@}, for details.
5465@end group
5466@end example
5467
5468@noindent
5469which produces
5470
5471@example
5472*Note Cross Reference Name: (info-file-name)Node name,
5473for details.
5474@end example
5475
5476@noindent
5477in Info and
5478
5479@quotation
5480See section ``Particular Topic'' in @i{A Printed Manual}, for details.
5481@end quotation
5482
5483@noindent
5484in a printed book.
5485
5486The five possible arguments for a cross reference are:@refill
5487
5488@enumerate
5489@item
5490The node or anchor name (required). This is the location to which the
5491cross reference takes you. In a printed document, the location of the
5492node provides the page reference only for references within the same
5493document.@refill
5494
5495@item
5496The cross reference name for the Info reference, if it is to be different
5497from the node name. If you include this argument, it becomes
5498the first part of the cross reference. It is usually omitted.@refill
5499
5500@item
5501A topic description or section name. Often, this is the title of the
5502section. This is used as the name of the reference in the printed
5503manual. If omitted, the node name is used.@refill
5504
5505@item
5506The name of the Info file in which the reference is located, if it is
5507different from the current file. You need not include any @samp{.info}
5508suffix on the file name, since Info readers try appending it
5509automatically.
5510
5511@item
5512The name of a printed manual from a different Texinfo file.@refill
5513@end enumerate
5514
5515The template for a full five argument cross reference looks like
5516this:@refill
5517
5518@example
5519@group
5520@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic},
5521@var{info-file-name}, @var{printed-manual-title}@}.
5522@end group
5523@end example
5524
5525Cross references with one, two, three, four, and five arguments are
5526described separately following the description of @code{@@xref}.@refill
5527
5528Write a node name in a cross reference in exactly the same way as in
5529the @code{@@node} line, including the same capitalization; otherwise, the
5530formatters may not find the reference.@refill
5531
5532You can write cross reference commands within a paragraph, but note
5533how Info and @TeX{} format the output of each of the various commands:
5534write @code{@@xref} at the beginning of a sentence; write
5535@code{@@pxref} only within parentheses, and so on.@refill
5536
5537@node xref, Top Node Naming, Cross Reference Parts, Cross References
5538@comment node-name, next, previous, up
5539@section @code{@@xref}
5540@findex xref
5541@cindex Cross references using @code{@@xref}
5542@cindex References using @code{@@xref}
5543
5544The @code{@@xref} command generates a cross reference for the
5545beginning of a sentence. The Info formatting commands convert it into
5546an Info cross reference, which the Info @samp{f} command can use to
5547bring you directly to another node. The @TeX{} typesetting commands
5548convert it into a page reference, or a reference to another book or
5549manual.@refill
5550
5551@menu
5552* Reference Syntax:: What a reference looks like and requires.
5553* One Argument:: @code{@@xref} with one argument.
5554* Two Arguments:: @code{@@xref} with two arguments.
5555* Three Arguments:: @code{@@xref} with three arguments.
5556* Four and Five Arguments:: @code{@@xref} with four and five arguments.
5557@end menu
5558
5559@node Reference Syntax, One Argument, xref, xref
5560@ifinfo
5561@subheading What a Reference Looks Like and Requires
5562@end ifinfo
5563
5564Most often, an Info cross reference looks like this:@refill
5565
5566@example
5567*Note @var{node-name}::.
5568@end example
5569
5570@noindent
5571or like this
5572
5573@example
5574*Note @var{cross-reference-name}: @var{node-name}.
5575@end example
5576
5577@noindent
5578In @TeX{}, a cross reference looks like this:
5579
5580@quotation
5581See Section @var{section-number} [@var{node-name}], page @var{page}.
5582@end quotation
5583
5584@noindent
5585or like this
5586
5587@quotation
5588See Section @var{section-number} [@var{title-or-topic}], page @var{page}.
5589@end quotation
5590
5591The @code{@@xref} command does not generate a period or comma to end
5592the cross reference in either the Info file or the printed output.
5593You must write that period or comma yourself; otherwise, Info will not
5594recognize the end of the reference. (The @code{@@pxref} command works
5595differently. @xref{pxref, , @code{@@pxref}}.)@refill
5596
5597@quotation
5598@strong{Please note:} A period or comma @strong{must} follow the closing
5599brace of an @code{@@xref}. It is required to terminate the cross
5600reference. This period or comma will appear in the output, both in
5601the Info file and in the printed manual.@refill
5602@end quotation
5603
5604@code{@@xref} must refer to an Info node by name. Use @code{@@node}
5605to define the node (@pxref{Writing a Node}).@refill
5606
5607@code{@@xref} is followed by several arguments inside braces, separated by
5608commas. Whitespace before and after these commas is ignored.@refill
5609
5610A cross reference requires only the name of a node; but it may contain
5611up to four additional arguments. Each of these variations produces a
5612cross reference that looks somewhat different.@refill
5613
5614@quotation
5615@strong{Please note:} Commas separate arguments in a cross reference;
5616avoid including them in the title or other part lest the formatters
5617mistake them for separators.@refill
5618@end quotation
5619
5620@node One Argument, Two Arguments, Reference Syntax, xref
5621@subsection @code{@@xref} with One Argument
5622
5623The simplest form of @code{@@xref} takes one argument, the name of
5624another node in the same Info file. The Info formatters produce
5625output that the Info readers can use to jump to the reference; @TeX{}
5626produces output that specifies the page and section number for you.@refill
5627
5628@need 700
5629@noindent
5630For example,
5631
5632@example
5633@@xref@{Tropical Storms@}.
5634@end example
5635
5636@noindent
5637produces
5638
5639@example
5640*Note Tropical Storms::.
5641@end example
5642
5643@noindent
5644and
5645
5646@quotation
5647See Section 3.1 [Tropical Storms], page 24.
5648@end quotation
5649
5650@noindent
5651(Note that in the preceding example the closing brace is followed by a
5652period.)@refill
5653
5654You can write a clause after the cross reference, like this:@refill
5655
5656@example
5657@@xref@{Tropical Storms@}, for more info.
5658@end example
5659
5660@noindent
5661which produces
5662
5663@example
5664*Note Tropical Storms::, for more info.
5665@end example
5666
5667@noindent
5668and
5669
5670@quotation
5671See Section 3.1 [Tropical Storms], page 24, for more info.
5672@end quotation
5673
5674@noindent
5675(Note that in the preceding example the closing brace is followed by a
5676comma, and then by the clause, which is followed by a period.)@refill
5677
5678@node Two Arguments, Three Arguments, One Argument, xref
5679@subsection @code{@@xref} with Two Arguments
5680
5681With two arguments, the second is used as the name of the Info cross
5682reference, while the first is still the name of the node to which the
5683cross reference points.@refill
5684
5685@need 750
5686@noindent
5687The template is like this:
5688
5689@example
5690@@xref@{@var{node-name}, @var{cross-reference-name}@}.
5691@end example
5692
5693@need 700
5694@noindent
5695For example,
5696
5697@example
5698@@xref@{Electrical Effects, Lightning@}.
5699@end example
5700
5701@noindent
5702produces:
5703
5704@example
5705*Note Lightning: Electrical Effects.
5706@end example
5707
5708@noindent
5709and
5710
5711@quotation
5712See Section 5.2 [Electrical Effects], page 57.
5713@end quotation
5714
5715@noindent
5716(Note that in the preceding example the closing brace is followed by a
5717period; and that the node name is printed, not the cross reference name.)
5718
5719You can write a clause after the cross reference, like this:@refill
5720
5721@example
5722@@xref@{Electrical Effects, Lightning@}, for more info.
5723@end example
5724
5725@noindent
5726which produces
5727@example
5728*Note Lightning: Electrical Effects, for more info.
5729@end example
5730
5731@noindent
5732and
5733
5734@quotation
5735See Section 5.2 [Electrical Effects], page 57, for more info.
5736@end quotation
5737
5738@noindent
5739(Note that in the preceding example the closing brace is followed by a
5740comma, and then by the clause, which is followed by a period.)@refill
5741
5742@node Three Arguments, Four and Five Arguments, Two Arguments, xref
5743@subsection @code{@@xref} with Three Arguments
5744
5745A third argument replaces the node name in the @TeX{} output. The third
5746argument should be the name of the section in the printed output, or
5747else state the topic discussed by that section. Often, you will want to
5748use initial upper case letters so it will be easier to read when the
5749reference is printed. Use a third argument when the node name is
5750unsuitable because of syntax or meaning.@refill
5751
5752Remember to avoid placing a comma within the title or topic section of
5753a cross reference, or within any other section. The formatters divide
5754cross references into arguments according to the commas; a comma
5755within a title or other section will divide it into two arguments. In
5756a reference, you need to write a title such as ``Clouds, Mist, and
5757Fog'' without the commas.@refill
5758
5759Also, remember to write a comma or period after the closing brace of an
5760@code{@@xref} to terminate the cross reference. In the following
5761examples, a clause follows a terminating comma.@refill
5762
5763
5764@need 750
5765@noindent
5766The template is like this:
5767
5768@example
5769@group
5770@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}@}.
5771@end group
5772@end example
5773
5774@need 700
5775@noindent
5776For example,
5777
5778@example
5779@group
5780@@xref@{Electrical Effects, Lightning, Thunder and Lightning@},
5781for details.
5782@end group
5783@end example
5784
5785@noindent
5786produces
5787
5788@example
5789*Note Lightning: Electrical Effects, for details.
5790@end example
5791
5792@noindent
5793and
5794
5795@quotation
5796See Section 5.2 [Thunder and Lightning], page 57, for details.
5797@end quotation
5798
5799If a third argument is given and the second one is empty, then the
5800third argument serves both. (Note how two commas, side by side, mark
5801the empty second argument.)@refill
5802
5803@example
5804@group
5805@@xref@{Electrical Effects, , Thunder and Lightning@},
5806for details.
5807@end group
5808@end example
5809
5810@noindent
5811produces
5812
5813@example
5814*Note Thunder and Lightning: Electrical Effects, for details.
5815@end example
5816
5817@noindent
5818and
5819
5820@quotation
5821See Section 5.2 [Thunder and Lightning], page 57, for details.
5822@end quotation
5823
5824As a practical matter, it is often best to write cross references with
5825just the first argument if the node name and the section title are the
5826same, and with the first and third arguments if the node name and title
5827are different.@refill
5828
5829Here are several examples from @cite{The GNU Awk User's Guide}:@refill
5830
5831@smallexample
5832@@xref@{Sample Program@}.
5833@@xref@{Glossary@}.
5834@@xref@{Case-sensitivity, ,Case-sensitivity in Matching@}.
5835@@xref@{Close Output, , Closing Output Files and Pipes@},
5836 for more information.
5837@@xref@{Regexp, , Regular Expressions as Patterns@}.
5838@end smallexample
5839
5840@node Four and Five Arguments, , Three Arguments, xref
5841@subsection @code{@@xref} with Four and Five Arguments
5842
5843In a cross reference, a fourth argument specifies the name of another
5844Info file, different from the file in which the reference appears, and
5845a fifth argument specifies its title as a printed manual.@refill
5846
5847Remember that a comma or period must follow the closing brace of an
5848@code{@@xref} command to terminate the cross reference. In the
5849following examples, a clause follows a terminating comma.@refill
5850
5851@need 800
5852@noindent
5853The template is:
5854
5855@example
5856@group
5857@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic},
5858@var{info-file-name}, @var{printed-manual-title}@}.
5859@end group
5860@end example
5861
5862@need 700
5863@noindent
5864For example,
5865
5866@example
5867@@xref@{Electrical Effects, Lightning, Thunder and Lightning,
5868weather, An Introduction to Meteorology@}, for details.
5869@end example
5870
5871@noindent
5872produces
5873
5874@example
5875*Note Lightning: (weather)Electrical Effects, for details.
5876@end example
5877
5878@noindent
5879The name of the Info file is enclosed in parentheses and precedes
5880the name of the node.
5881
5882@noindent
5883In a printed manual, the reference looks like this:@refill
5884
5885@quotation
5886See section ``Thunder and Lightning'' in @i{An Introduction to
5887Meteorology}, for details.
5888@end quotation
5889
5890@noindent
5891The title of the printed manual is typeset in italics; and the
5892reference lacks a page number since @TeX{} cannot know to which page a
5893reference refers when that reference is to another manual.@refill
5894
5895Often, you will leave out the second argument when you use the long
5896version of @code{@@xref}. In this case, the third argument, the topic
5897description, will be used as the cross reference name in Info.@refill
5898
5899@noindent
5900The template looks like this:
5901
5902@example
5903@@xref@{@var{node-name}, , @var{title-or-topic}, @var{info-file-name},
5904@var{printed-manual-title}@}, for details.
5905@end example
5906
5907@noindent
5908which produces
5909
5910@example
5911*Note @var{title-or-topic}: (@var{info-file-name})@var{node-name}, for details.
5912@end example
5913
5914@noindent
5915and
5916
5917@quotation
5918See section @var{title-or-topic} in @var{printed-manual-title}, for details.
5919@end quotation
5920
5921@need 700
5922@noindent
5923For example,
5924
5925@example
5926@@xref@{Electrical Effects, , Thunder and Lightning,
5927weather, An Introduction to Meteorology@}, for details.
5928@end example
5929
5930@noindent
5931produces
5932
5933@example
5934@group
5935*Note Thunder and Lightning: (weather)Electrical Effects,
5936for details.
5937@end group
5938@end example
5939
5940@noindent
5941and
5942
5943@quotation
5944See section ``Thunder and Lightning'' in @i{An Introduction to
5945Meteorology}, for details.
5946@end quotation
5947
5948On rare occasions, you may want to refer to another Info file that
5949is within a single printed manual---when multiple Texinfo files are
5950incorporated into the same @TeX{} run but make separate Info files.
5951In this case, you need to specify only the fourth argument, and not
5952the fifth.@refill
5953
5954@node Top Node Naming, ref, xref, Cross References
5955@section Naming a `Top' Node
5956@cindex Naming a `Top' Node in references
5957@cindex @samp{@r{Top}} node naming for references
5958
5959In a cross reference, you must always name a node. This means that in
5960order to refer to a whole manual, you must identify the `Top' node by
5961writing it as the first argument to the @code{@@xref} command. (This
5962is different from the way you write a menu entry; see @ref{Other Info
5963Files, , Referring to Other Info Files}.) At the same time, to
5964provide a meaningful section topic or title in the printed cross
5965reference (instead of the word `Top'), you must write an appropriate
5966entry for the third argument to the @code{@@xref} command.
5967@refill
5968
5969@noindent
5970Thus, to make a cross reference to @cite{The GNU Make Manual},
5971write:@refill
5972
5973@example
5974@@xref@{Top, , Overview, make, The GNU Make Manual@}.
5975@end example
5976
5977@noindent
5978which produces
5979
5980@example
5981*Note Overview: (make)Top.
5982@end example
5983
5984@noindent
5985and
5986
5987@quotation
5988See section ``Overview'' in @i{The GNU Make Manual}.
5989@end quotation
5990
5991@noindent
5992In this example, @samp{Top} is the name of the first node, and
5993@samp{Overview} is the name of the first section of the manual.@refill
5994@node ref, pxref, Top Node Naming, Cross References
5995@comment node-name, next, previous, up
5996@section @code{@@ref}
5997@cindex Cross references using @code{@@ref}
5998@cindex References using @code{@@ref}
5999@findex ref
6000
6001@code{@@ref} is nearly the same as @code{@@xref} except that it does
6002not generate a `See' in the printed output, just the reference itself.
6003This makes it useful as the last part of a sentence.@refill
6004
6005@need 700
6006@noindent
6007For example,
6008
6009@cindex Hurricanes
6010@example
6011For more information, see @@ref@{Hurricanes@}.
6012@end example
6013
6014@noindent
6015produces
6016
6017@example
6018For more information, see *Note Hurricanes::.
6019@end example
6020
6021@noindent
6022and
6023
6024@quotation
6025For more information, see Section 8.2 [Hurricanes], page 123.
6026@end quotation
6027
6028The @code{@@ref} command sometimes leads writers to express themselves
6029in a manner that is suitable for a printed manual but looks awkward
6030in the Info format. Bear in mind that your audience will be using
6031both the printed and the Info format.@refill
6032
6033@need 800
6034@noindent
6035For example,
6036
6037@cindex Sea surges
6038@example
6039@group
6040Sea surges are described in @@ref@{Hurricanes@}.
6041@end group
6042@end example
6043
6044@need 800
6045@noindent
6046produces
6047
6048@quotation
6049Sea surges are described in Section 6.7 [Hurricanes], page 72.
6050@end quotation
6051
6052@need 800
6053@noindent
6054in a printed document, and the following in Info:
6055
6056@example
6057Sea surges are described in *Note Hurricanes::.
6058@end example
6059
6060@quotation
6061@strong{Caution:} You @emph{must} write a period, comma, or right
6062parenthesis immediately after an @code{@@ref} command with two or more
6063arguments. Otherwise, Info will not find the end of the cross reference
6064entry and its attempt to follow the cross reference will fail. As a
6065general rule, you should write a period or comma after every
6066@code{@@ref} command. This looks best in both the printed and the Info
6067output.@refill
6068@end quotation
6069
6070@node pxref, inforef, ref, Cross References
6071@comment node-name, next, previous, up
6072@section @code{@@pxref}
6073@cindex Cross references using @code{@@pxref}
6074@cindex References using @code{@@pxref}
6075@findex pxref
6076
6077The parenthetical reference command, @code{@@pxref}, is nearly the
6078same as @code{@@xref}, but you use it @emph{only} inside parentheses
6079and you do @emph{not} type a comma or period after the command's
6080closing brace. The command differs from @code{@@xref} in two
6081ways:@refill
6082
6083@enumerate
6084@item
6085@TeX{} typesets the reference for the printed manual with a lower case
6086`see' rather than an upper case `See'.@refill
6087
6088@item
6089The Info formatting commands automatically end the reference with a
6090closing colon or period.@refill
6091@end enumerate
6092
6093Because one type of formatting automatically inserts closing
6094punctuation and the other does not, you should use @code{@@pxref}
6095@emph{only} inside parentheses as part of another sentence. Also, you
6096yourself should not insert punctuation after the reference, as you do
6097with @code{@@xref}.@refill
6098
6099@code{@@pxref} is designed so that the output looks right and works
6100right between parentheses both in printed output and in an Info file.
6101In a printed manual, a closing comma or period should not follow a
6102cross reference within parentheses; such punctuation is wrong. But in
6103an Info file, suitable closing punctuation must follow the cross
6104reference so Info can recognize its end. @code{@@pxref} spares you
6105the need to use complicated methods to put a terminator into one form
6106of the output and not the other.@refill
6107
6108@noindent
6109With one argument, a parenthetical cross reference looks like
6110this:@refill
6111
6112@cindex Flooding
6113@example
6114@dots{} storms cause flooding (@@pxref@{Hurricanes@}) @dots{}
6115@end example
6116
6117@need 800
6118@noindent
6119which produces
6120
6121@example
6122@group
6123@dots{} storms cause flooding (*Note Hurricanes::) @dots{}
6124@end group
6125@end example
6126
6127@noindent
6128and
6129
6130@quotation
6131@dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{}
6132@end quotation
6133
6134With two arguments, a parenthetical cross reference has this
6135template:@refill
6136
6137@example
6138@dots{} (@@pxref@{@var{node-name}, @var{cross-reference-name}@}) @dots{}
6139@end example
6140
6141@noindent
6142which produces
6143
6144@example
6145@dots{} (*Note @var{cross-reference-name}: @var{node-name}.) @dots{}
6146@end example
6147
6148@noindent
6149and
6150
6151@need 1500
6152@quotation
6153@dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{}
6154@end quotation
6155
6156@code{@@pxref} can be used with up to five arguments just like
6157@code{@@xref} (@pxref{xref, , @code{@@xref}}).@refill
6158
6159@quotation
6160@strong{Please note:} Use @code{@@pxref} only as a parenthetical
6161reference. Do not try to use @code{@@pxref} as a clause in a sentence.
6162It will look bad in either the Info file, the printed output, or
6163both.@refill
6164
6165Also, parenthetical cross references look best at the ends of sentences.
6166Although you may write them in the middle of a sentence, that location
6167breaks up the flow of text.@refill
6168@end quotation
6169
6170@node inforef, uref, pxref, Cross References
6171@section @code{@@inforef}
6172@cindex Cross references using @code{@@inforef}
6173@cindex References using @code{@@inforef}
6174@findex inforef
6175
6176@code{@@inforef} is used for cross references to Info files for which
6177there are no printed manuals. Even in a printed manual,
6178@code{@@inforef} generates a reference directing the user to look in
6179an Info file.@refill
6180
6181The command takes either two or three arguments, in the following
6182order:@refill
6183
6184@enumerate
6185@item
6186The node name.
6187
6188@item
6189The cross reference name (optional).
6190
6191@item
6192The Info file name.
6193@end enumerate
6194
6195@noindent
6196Separate the arguments with commas, as with @code{@@xref}. Also, you
6197must terminate the reference with a comma or period after the
6198@samp{@}}, as you do with @code{@@xref}.@refill
6199
6200@noindent
6201The template is:
6202
6203@example
6204@@inforef@{@var{node-name}, @var{cross-reference-name}, @var{info-file-name}@},
6205@end example
6206
6207@need 800
6208@noindent
6209Thus,
6210
6211@example
6212@group
6213@@inforef@{Expert, Advanced Info commands, info@},
6214for more information.
6215@end group
6216@end example
6217
6218@need 800
6219@noindent
6220produces
6221
6222@example
6223@group
6224*Note Advanced Info commands: (info)Expert,
6225for more information.
6226@end group
6227@end example
6228
6229@need 800
6230@noindent
6231and
6232
6233@quotation
6234See Info file @file{info}, node @samp{Expert}, for more information.
6235@end quotation
6236
6237@need 800
6238@noindent
6239Similarly,
6240
6241@example
6242@group
6243@@inforef@{Expert, , info@}, for more information.
6244@end group
6245@end example
6246
6247@need 800
6248@noindent
6249produces
6250
6251@example
6252*Note (info)Expert::, for more information.
6253@end example
6254
6255@need 800
6256@noindent
6257and
6258
6259@quotation
6260See Info file @file{info}, node @samp{Expert}, for more information.
6261@end quotation
6262
6263The converse of @code{@@inforef} is @code{@@cite}, which is used to
6264refer to printed works for which no Info form exists. @xref{cite, ,
6265@code{@@cite}}.@refill
6266
6267
6268@node uref
6269@section @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}}
6270@findex uref
6271@cindex Uniform resource locator, referring to
6272@cindex URL, referring to
6273
6274@cindex @code{href}, producing HTML
6275@code{@@uref} produces a reference to a uniform resource locator (url).
6276It takes one mandatory argument, the url, and two optional arguments
6277which control the text that is displayed. In HTML output, @code{@@uref}
6278produces a link you can follow.
6279
6280The second argument, if specified, is the text to display (the default
6281is the url itself); in Info and DVI output, but not in HTML output, the
6282url is also output.
6283
6284@cindex Man page, reference to
6285The third argument, on the other hand, if specified is also the text to
6286display, but the url is @emph{not} output in any format. This is useful
6287when the text is already sufficiently referential, as in a man page. If
6288the third argument is given, the second argument is ignored.
6289
6290The simple one argument form, where the url is both the target and the
6291text of the link:
6292
6293@example
6294The official GNU ftp site is @@uref@{ftp://ftp.gnu.org/gnu@}.
6295@end example
6296
6297@noindent produces:
6298@display
6299The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}.
6300@end display
6301
6302
6303An example of the two-argument form:
6304@example
6305The official @@uref@{ftp://ftp.gnu.org/gnu, GNU ftp site@}
6306holds programs and texts.
6307@end example
6308
6309@noindent produces:
6310@display
6311The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site}
6312holds programs and texts.
6313@end display
6314
6315@noindent that is, the Info output is this:
6316@example
6317The official GNU ftp site (ftp://ftp.gnu.org/gnu)
6318holds programs and texts.
6319@end example
6320
6321@noindent and the HTML output is this:
6322@example
6323The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a>
6324holds programs and texts.
6325@end example
6326
6327
6328An example of the three-argument form:
6329@example
6330The @@uref@{/man.cgi/1/ls,,ls(1)@} program @dots{}
6331@end example
6332
6333@noindent produces:
6334@display
6335The @uref{/man.cgi/1/ls,,ls(1)} program @dots{}
6336@end display
6337
6338@noindent but with HTML:
6339@example
6340The <a href="/man.cgi/1/ls">ls(1)</a> program @dots{}
6341@end example
6342
6343To merely indicate a url without creating a link people can follow, use
6344@code{@@url} (@pxref{url, @code{@@url}}).
6345
6346Some people prefer to display url's in the unambiguous format:
6347
6348@display
6349<URL:http://@var{host}/@var{path}>
6350@end display
6351
6352@noindent
6353@cindex <URL convention, not used
6354You can use this form in the input file if you wish. We feel it's not
6355necessary to clutter up the output with the extra @samp{<URL:} and
6356@samp{>}, since any software that tries to detect url's in text already
6357has to detect them without the @samp{<URL:} to be useful.
6358
6359
6360@node Marking Text
6361@chapter Marking Words and Phrases
6362@cindex Paragraph, marking text within
6363@cindex Marking words and phrases
6364@cindex Words and phrases, marking them
6365@cindex Marking text within a paragraph
6366@cindex Text, marking up
6367
6368In Texinfo, you can mark words and phrases in a variety of ways.
6369The Texinfo formatters use this information to determine how to
6370highlight the text.
6371You can specify, for example, whether a word or phrase is a
6372defining occurrence, a metasyntactic variable, or a symbol used in a
6373program. Also, you can emphasize text, in several different ways.
6374
6375@menu
6376* Indicating:: How to indicate definitions, files, etc.
6377* Emphasis:: How to emphasize text.
6378@end menu
6379
6380
6381@node Indicating, Emphasis, Marking Text, Marking Text
6382@section Indicating Definitions, Commands, etc.
6383@cindex Highlighting text
6384@cindex Indicating commands, definitions, etc.
6385
6386Texinfo has commands for indicating just what kind of object a piece of
6387text refers to. For example, metasyntactic variables are marked by
6388@code{@@var}, and code by @code{@@code}. Since the pieces of text are
6389labelled by commands that tell what kind of object they are, it is easy
6390to change the way the Texinfo formatters prepare such text. (Texinfo is
6391an @emph{intentional} formatting language rather than a @emph{typesetting}
6392formatting language.)@refill
6393
6394For example, in a printed manual,
6395code is usually illustrated in a typewriter font;
6396@code{@@code} tells @TeX{} to typeset this text in this font. But it
6397would be easy to change the way @TeX{} highlights code to use another
6398font, and this change would not affect how keystroke examples are
6399highlighted. If straight typesetting commands were used in the body
6400of the file and you wanted to make a change, you would need to check
6401every single occurrence to make sure that you were changing code and
6402not something else that should not be changed.@refill
6403
6404@menu
6405* Useful Highlighting:: Highlighting provides useful information.
6406* code:: Indicating program code.
6407* kbd:: Showing keyboard input.
6408* key:: Specifying keys.
6409* samp:: A literal sequence of characters.
| 5150
5151
5152@node Writing a Menu, Menu Parts, Menu Location, Menus
5153@section Writing a Menu
5154@cindex Writing a menu
5155@cindex Menu writing
5156
5157A menu consists of an @code{@@menu} command on a line by
5158itself followed by menu entry lines or menu comment lines
5159and then by an @code{@@end menu} command on a line by
5160itself.@refill
5161
5162A menu looks like this:@refill
5163
5164@example
5165@group
5166@@menu
5167Larger Units of Text
5168
5169* Files:: All about handling files.
5170* Multiples: Buffers. Multiple buffers; editing
5171 several files at once.
5172@@end menu
5173@end group
5174@end example
5175
5176In a menu, every line that begins with an @w{@samp{* }} is a @dfn{menu
5177entry}. (Note the space after the asterisk.) A line that does not
5178start with an @w{@samp{* }} may also appear in a menu. Such a line is
5179not a menu entry but is a menu comment line that appears in the Info
5180file. In the example above, the line @samp{Larger Units of Text} is a
5181menu comment line; the two lines starting with @w{@samp{* }} are menu
5182@cindex Spaces, in menus
5183entries. Space characters in a menu are preserved as-is; this allows
5184you to format the menu as you wish.
5185
5186
5187@node Menu Parts, Less Cluttered Menu Entry, Writing a Menu, Menus
5188@section The Parts of a Menu
5189@cindex Parts of a menu
5190@cindex Menu parts
5191@cindex @code{@@menu} parts
5192
5193A menu entry has three parts, only the second of which is required:
5194
5195@enumerate
5196@item
5197The menu entry name (optional).
5198
5199@item
5200The name of the node (required).
5201
5202@item
5203A description of the item (optional).
5204@end enumerate
5205
5206The template for a menu entry looks like this:@refill
5207
5208@example
5209* @var{menu-entry-name}: @var{node-name}. @var{description}
5210@end example
5211
5212Follow the menu entry name with a single colon and follow the node name
5213with tab, comma, period, or newline.@refill
5214
5215In Info, a user selects a node with the @kbd{m} (@code{Info-menu})
5216command. The menu entry name is what the user types after the @kbd{m}
5217command.@refill
5218
5219The third part of a menu entry is a descriptive phrase or sentence.
5220Menu entry names and node names are often short; the description
5221explains to the reader what the node is about. A useful description
5222complements the node name rather than repeats it. The description,
5223which is optional, can spread over two or more lines; if it does, some
5224authors prefer to indent the second line while others prefer to align it
5225with the first (and all others). It's up to you.
5226
5227
5228@node Less Cluttered Menu Entry, Menu Example, Menu Parts, Menus
5229@comment node-name, next, previous, up
5230@section Less Cluttered Menu Entry
5231@cindex Two part menu entry
5232@cindex Double-colon menu entries
5233@cindex Menu entries with two colons
5234@cindex Less cluttered menu entry
5235@cindex Uncluttered menu entry
5236
5237When the menu entry name and node name are the same, you can write
5238the name immediately after the asterisk and space at the beginning of
5239the line and follow the name with two colons.@refill
5240
5241@need 800
5242For example, write
5243
5244@example
5245* Name:: @var{description}
5246@end example
5247
5248@need 800
5249@noindent
5250instead of
5251
5252@example
5253* Name: Name. @var{description}
5254@end example
5255
5256You should use the node name for the menu entry name whenever possible,
5257since it reduces visual clutter in the menu.@refill
5258
5259@node Menu Example, Other Info Files, Less Cluttered Menu Entry, Menus
5260@comment node-name, next, previous, up
5261@section A Menu Example
5262@cindex Menu example
5263@cindex Example menu
5264
5265A menu looks like this in Texinfo:@refill
5266
5267@example
5268@group
5269@@menu
5270* menu entry name: Node name. A short description.
5271* Node name:: This form is preferred.
5272@@end menu
5273@end group
5274@end example
5275
5276@need 800
5277@noindent
5278This produces:
5279
5280@example
5281@group
5282* menu:
5283
5284* menu entry name: Node name. A short description.
5285* Node name:: This form is preferred.
5286@end group
5287@end example
5288
5289@need 700
5290Here is an example as you might see it in a Texinfo file:@refill
5291
5292@example
5293@group
5294@@menu
5295Larger Units of Text
5296
5297* Files:: All about handling files.
5298* Multiples: Buffers. Multiple buffers; editing
5299 several files at once.
5300@@end menu
5301@end group
5302@end example
5303
5304@need 800
5305@noindent
5306This produces:
5307
5308@example
5309@group
5310* menu:
5311Larger Units of Text
5312
5313* Files:: All about handling files.
5314* Multiples: Buffers. Multiple buffers; editing
5315 several files at once.
5316@end group
5317@end example
5318
5319In this example, the menu has two entries. @samp{Files} is both a menu
5320entry name and the name of the node referred to by that name.
5321@samp{Multiples} is the menu entry name; it refers to the node named
5322@samp{Buffers}. The line @samp{Larger Units of Text} is a comment; it
5323appears in the menu, but is not an entry.@refill
5324
5325Since no file name is specified with either @samp{Files} or
5326@samp{Buffers}, they must be the names of nodes in the same Info file
5327(@pxref{Other Info Files, , Referring to Other Info Files}).@refill
5328
5329@node Other Info Files, , Menu Example, Menus
5330@comment node-name, next, previous, up
5331@section Referring to Other Info Files
5332@cindex Referring to other Info files
5333@cindex Nodes in other Info files
5334@cindex Other Info files' nodes
5335@cindex Going to other Info files' nodes
5336@cindex Info; other files' nodes
5337
5338You can create a menu entry that enables a reader in Info to go to a
5339node in another Info file by writing the file name in parentheses just
5340before the node name. In this case, you should use the three-part menu
5341entry format, which saves the reader from having to type the file
5342name.@refill
5343
5344@need 800
5345The format looks like this:@refill
5346
5347@example
5348@group
5349@@menu
5350* @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description}
5351* @var{second-entry-name}:(@var{filename})@var{second-node}. @var{description}
5352@@end menu
5353@end group
5354@end example
5355
5356For example, to refer directly to the @samp{Outlining} and
5357@samp{Rebinding} nodes in the @cite{Emacs Manual}, you would write a
5358menu like this:@refill
5359
5360@example
5361@group
5362@@menu
5363* Outlining: (emacs)Outline Mode. The major mode for
5364 editing outlines.
5365* Rebinding: (emacs)Rebinding. How to redefine the
5366 meaning of a key.
5367@@end menu
5368@end group
5369@end example
5370
5371If you do not list the node name, but only name the file, then Info
5372presumes that you are referring to the `Top' node.@refill
5373
5374The @file{dir} file that contains the main menu for Info has menu
5375entries that list only file names. These take you directly to the `Top'
5376nodes of each Info document. (@xref{Installing an Info File}.)
5377
5378@need 700
5379For example:
5380
5381@example
5382@group
5383* Info: (info). Documentation browsing system.
5384* Emacs: (emacs). The extensible, self-documenting
5385 text editor.
5386@end group
5387@end example
5388
5389@noindent
5390(The @file{dir} top level directory for the Info system is an Info file,
5391not a Texinfo file, but a menu entry looks the same in both types of
5392file.)@refill
5393
5394The GNU Emacs Texinfo mode menu updating commands only work with nodes
5395within the current buffer, so you cannot use them to create menus that
5396refer to other files. You must write such menus by hand.
5397
5398
5399@node Cross References
5400@chapter Cross References
5401@cindex Making cross references
5402@cindex Cross references
5403@cindex References
5404
5405@dfn{Cross references} are used to refer the reader to other parts of the
5406same or different Texinfo files. In Texinfo, nodes and anchors are the
5407places to which cross references can refer.
5408
5409@menu
5410* References:: What cross references are for.
5411* Cross Reference Commands:: A summary of the different commands.
5412* Cross Reference Parts:: A cross reference has several parts.
5413* xref:: Begin a reference with `See' @dots{}
5414* Top Node Naming:: How to refer to the beginning of another file.
5415* ref:: A reference for the last part of a sentence.
5416* pxref:: How to write a parenthetical cross reference.
5417* inforef:: How to refer to an Info-only file.
5418* uref:: How to refer to a uniform resource locator.
5419@end menu
5420
5421@node References, Cross Reference Commands, Cross References, Cross References
5422@ifinfo
5423@heading What References Are For
5424@end ifinfo
5425
5426Often, but not always, a printed document should be designed so that
5427it can be read sequentially. People tire of flipping back and forth
5428to find information that should be presented to them as they need
5429it.@refill
5430
5431However, in any document, some information will be too detailed for
5432the current context, or incidental to it; use cross references to
5433provide access to such information. Also, an online help system or a
5434reference manual is not like a novel; few read such documents in
5435sequence from beginning to end. Instead, people look up what they
5436need. For this reason, such creations should contain many cross
5437references to help readers find other information that they may not
5438have read.@refill
5439
5440In a printed manual, a cross reference results in a page reference,
5441unless it is to another manual altogether, in which case the cross
5442reference names that manual.@refill
5443
5444In Info, a cross reference results in an entry that you can follow using
5445the Info @samp{f} command. (@inforef{Help-Adv, Some advanced Info
5446commands, info}.)@refill
5447
5448The various cross reference commands use nodes (or anchors,
5449@pxref{anchor,,@code{@@anchor}}) to define cross reference locations.
5450This is evident in Info, in which a cross reference takes you to the
5451specified location. @TeX{} also uses nodes to define cross reference
5452locations, but the action is less obvious. When @TeX{} generates a DVI
5453file, it records each node's page number and uses the page numbers in making
5454references. Thus, if you are writing a manual that will only be
5455printed, and will not be used online, you must nonetheless write
5456@code{@@node} lines to name the places to which you make cross
5457references.@refill
5458
5459@need 800
5460@node Cross Reference Commands, Cross Reference Parts, References, Cross References
5461@comment node-name, next, previous, up
5462@section Different Cross Reference Commands
5463@cindex Different cross reference commands
5464
5465There are four different cross reference commands:@refill
5466
5467@table @code
5468@item @@xref
5469Used to start a sentence in the printed manual saying @w{`See @dots{}'}
5470or an Info cross-reference saying @samp{*Note @var{name}: @var{node}.}.
5471
5472@item @@ref
5473Used within or, more often, at the end of a sentence; same as
5474@code{@@xref} for Info; produces just the reference in the printed
5475manual without a preceding `See'.@refill
5476
5477@item @@pxref
5478Used within parentheses to make a reference that suits both an Info
5479file and a printed book. Starts with a lower case `see' within the
5480printed manual. (@samp{p} is for `parenthesis'.)@refill
5481
5482@item @@inforef
5483Used to make a reference to an Info file for which there is no printed
5484manual.@refill
5485@end table
5486
5487@noindent
5488(The @code{@@cite} command is used to make references to books and
5489manuals for which there is no corresponding Info file and, therefore,
5490no node to which to point. @xref{cite, , @code{@@cite}}.)@refill
5491
5492@node Cross Reference Parts, xref, Cross Reference Commands, Cross References
5493@comment node-name, next, previous, up
5494@section Parts of a Cross Reference
5495@cindex Cross reference parts
5496@cindex Parts of a cross reference
5497
5498A cross reference command requires only one argument, which is the
5499name of the node to which it refers. But a cross reference command
5500may contain up to four additional arguments. By using these
5501arguments, you can provide a cross reference name for Info, a topic
5502description or section title for the printed output, the name of a
5503different Info file, and the name of a different printed
5504manual.@refill
5505
5506Here is a simple cross reference example:@refill
5507
5508@example
5509@@xref@{Node name@}.
5510@end example
5511
5512@noindent
5513which produces
5514
5515@example
5516*Note Node name::.
5517@end example
5518
5519@noindent
5520and
5521
5522@quotation
5523See Section @var{nnn} [Node name], page @var{ppp}.
5524@end quotation
5525
5526@need 700
5527Here is an example of a full five-part cross reference:@refill
5528
5529@example
5530@group
5531@@xref@{Node name, Cross Reference Name, Particular Topic,
5532info-file-name, A Printed Manual@}, for details.
5533@end group
5534@end example
5535
5536@noindent
5537which produces
5538
5539@example
5540*Note Cross Reference Name: (info-file-name)Node name,
5541for details.
5542@end example
5543
5544@noindent
5545in Info and
5546
5547@quotation
5548See section ``Particular Topic'' in @i{A Printed Manual}, for details.
5549@end quotation
5550
5551@noindent
5552in a printed book.
5553
5554The five possible arguments for a cross reference are:@refill
5555
5556@enumerate
5557@item
5558The node or anchor name (required). This is the location to which the
5559cross reference takes you. In a printed document, the location of the
5560node provides the page reference only for references within the same
5561document.@refill
5562
5563@item
5564The cross reference name for the Info reference, if it is to be different
5565from the node name. If you include this argument, it becomes
5566the first part of the cross reference. It is usually omitted.@refill
5567
5568@item
5569A topic description or section name. Often, this is the title of the
5570section. This is used as the name of the reference in the printed
5571manual. If omitted, the node name is used.@refill
5572
5573@item
5574The name of the Info file in which the reference is located, if it is
5575different from the current file. You need not include any @samp{.info}
5576suffix on the file name, since Info readers try appending it
5577automatically.
5578
5579@item
5580The name of a printed manual from a different Texinfo file.@refill
5581@end enumerate
5582
5583The template for a full five argument cross reference looks like
5584this:@refill
5585
5586@example
5587@group
5588@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic},
5589@var{info-file-name}, @var{printed-manual-title}@}.
5590@end group
5591@end example
5592
5593Cross references with one, two, three, four, and five arguments are
5594described separately following the description of @code{@@xref}.@refill
5595
5596Write a node name in a cross reference in exactly the same way as in
5597the @code{@@node} line, including the same capitalization; otherwise, the
5598formatters may not find the reference.@refill
5599
5600You can write cross reference commands within a paragraph, but note
5601how Info and @TeX{} format the output of each of the various commands:
5602write @code{@@xref} at the beginning of a sentence; write
5603@code{@@pxref} only within parentheses, and so on.@refill
5604
5605@node xref, Top Node Naming, Cross Reference Parts, Cross References
5606@comment node-name, next, previous, up
5607@section @code{@@xref}
5608@findex xref
5609@cindex Cross references using @code{@@xref}
5610@cindex References using @code{@@xref}
5611
5612The @code{@@xref} command generates a cross reference for the
5613beginning of a sentence. The Info formatting commands convert it into
5614an Info cross reference, which the Info @samp{f} command can use to
5615bring you directly to another node. The @TeX{} typesetting commands
5616convert it into a page reference, or a reference to another book or
5617manual.@refill
5618
5619@menu
5620* Reference Syntax:: What a reference looks like and requires.
5621* One Argument:: @code{@@xref} with one argument.
5622* Two Arguments:: @code{@@xref} with two arguments.
5623* Three Arguments:: @code{@@xref} with three arguments.
5624* Four and Five Arguments:: @code{@@xref} with four and five arguments.
5625@end menu
5626
5627@node Reference Syntax, One Argument, xref, xref
5628@ifinfo
5629@subheading What a Reference Looks Like and Requires
5630@end ifinfo
5631
5632Most often, an Info cross reference looks like this:@refill
5633
5634@example
5635*Note @var{node-name}::.
5636@end example
5637
5638@noindent
5639or like this
5640
5641@example
5642*Note @var{cross-reference-name}: @var{node-name}.
5643@end example
5644
5645@noindent
5646In @TeX{}, a cross reference looks like this:
5647
5648@quotation
5649See Section @var{section-number} [@var{node-name}], page @var{page}.
5650@end quotation
5651
5652@noindent
5653or like this
5654
5655@quotation
5656See Section @var{section-number} [@var{title-or-topic}], page @var{page}.
5657@end quotation
5658
5659The @code{@@xref} command does not generate a period or comma to end
5660the cross reference in either the Info file or the printed output.
5661You must write that period or comma yourself; otherwise, Info will not
5662recognize the end of the reference. (The @code{@@pxref} command works
5663differently. @xref{pxref, , @code{@@pxref}}.)@refill
5664
5665@quotation
5666@strong{Please note:} A period or comma @strong{must} follow the closing
5667brace of an @code{@@xref}. It is required to terminate the cross
5668reference. This period or comma will appear in the output, both in
5669the Info file and in the printed manual.@refill
5670@end quotation
5671
5672@code{@@xref} must refer to an Info node by name. Use @code{@@node}
5673to define the node (@pxref{Writing a Node}).@refill
5674
5675@code{@@xref} is followed by several arguments inside braces, separated by
5676commas. Whitespace before and after these commas is ignored.@refill
5677
5678A cross reference requires only the name of a node; but it may contain
5679up to four additional arguments. Each of these variations produces a
5680cross reference that looks somewhat different.@refill
5681
5682@quotation
5683@strong{Please note:} Commas separate arguments in a cross reference;
5684avoid including them in the title or other part lest the formatters
5685mistake them for separators.@refill
5686@end quotation
5687
5688@node One Argument, Two Arguments, Reference Syntax, xref
5689@subsection @code{@@xref} with One Argument
5690
5691The simplest form of @code{@@xref} takes one argument, the name of
5692another node in the same Info file. The Info formatters produce
5693output that the Info readers can use to jump to the reference; @TeX{}
5694produces output that specifies the page and section number for you.@refill
5695
5696@need 700
5697@noindent
5698For example,
5699
5700@example
5701@@xref@{Tropical Storms@}.
5702@end example
5703
5704@noindent
5705produces
5706
5707@example
5708*Note Tropical Storms::.
5709@end example
5710
5711@noindent
5712and
5713
5714@quotation
5715See Section 3.1 [Tropical Storms], page 24.
5716@end quotation
5717
5718@noindent
5719(Note that in the preceding example the closing brace is followed by a
5720period.)@refill
5721
5722You can write a clause after the cross reference, like this:@refill
5723
5724@example
5725@@xref@{Tropical Storms@}, for more info.
5726@end example
5727
5728@noindent
5729which produces
5730
5731@example
5732*Note Tropical Storms::, for more info.
5733@end example
5734
5735@noindent
5736and
5737
5738@quotation
5739See Section 3.1 [Tropical Storms], page 24, for more info.
5740@end quotation
5741
5742@noindent
5743(Note that in the preceding example the closing brace is followed by a
5744comma, and then by the clause, which is followed by a period.)@refill
5745
5746@node Two Arguments, Three Arguments, One Argument, xref
5747@subsection @code{@@xref} with Two Arguments
5748
5749With two arguments, the second is used as the name of the Info cross
5750reference, while the first is still the name of the node to which the
5751cross reference points.@refill
5752
5753@need 750
5754@noindent
5755The template is like this:
5756
5757@example
5758@@xref@{@var{node-name}, @var{cross-reference-name}@}.
5759@end example
5760
5761@need 700
5762@noindent
5763For example,
5764
5765@example
5766@@xref@{Electrical Effects, Lightning@}.
5767@end example
5768
5769@noindent
5770produces:
5771
5772@example
5773*Note Lightning: Electrical Effects.
5774@end example
5775
5776@noindent
5777and
5778
5779@quotation
5780See Section 5.2 [Electrical Effects], page 57.
5781@end quotation
5782
5783@noindent
5784(Note that in the preceding example the closing brace is followed by a
5785period; and that the node name is printed, not the cross reference name.)
5786
5787You can write a clause after the cross reference, like this:@refill
5788
5789@example
5790@@xref@{Electrical Effects, Lightning@}, for more info.
5791@end example
5792
5793@noindent
5794which produces
5795@example
5796*Note Lightning: Electrical Effects, for more info.
5797@end example
5798
5799@noindent
5800and
5801
5802@quotation
5803See Section 5.2 [Electrical Effects], page 57, for more info.
5804@end quotation
5805
5806@noindent
5807(Note that in the preceding example the closing brace is followed by a
5808comma, and then by the clause, which is followed by a period.)@refill
5809
5810@node Three Arguments, Four and Five Arguments, Two Arguments, xref
5811@subsection @code{@@xref} with Three Arguments
5812
5813A third argument replaces the node name in the @TeX{} output. The third
5814argument should be the name of the section in the printed output, or
5815else state the topic discussed by that section. Often, you will want to
5816use initial upper case letters so it will be easier to read when the
5817reference is printed. Use a third argument when the node name is
5818unsuitable because of syntax or meaning.@refill
5819
5820Remember to avoid placing a comma within the title or topic section of
5821a cross reference, or within any other section. The formatters divide
5822cross references into arguments according to the commas; a comma
5823within a title or other section will divide it into two arguments. In
5824a reference, you need to write a title such as ``Clouds, Mist, and
5825Fog'' without the commas.@refill
5826
5827Also, remember to write a comma or period after the closing brace of an
5828@code{@@xref} to terminate the cross reference. In the following
5829examples, a clause follows a terminating comma.@refill
5830
5831
5832@need 750
5833@noindent
5834The template is like this:
5835
5836@example
5837@group
5838@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}@}.
5839@end group
5840@end example
5841
5842@need 700
5843@noindent
5844For example,
5845
5846@example
5847@group
5848@@xref@{Electrical Effects, Lightning, Thunder and Lightning@},
5849for details.
5850@end group
5851@end example
5852
5853@noindent
5854produces
5855
5856@example
5857*Note Lightning: Electrical Effects, for details.
5858@end example
5859
5860@noindent
5861and
5862
5863@quotation
5864See Section 5.2 [Thunder and Lightning], page 57, for details.
5865@end quotation
5866
5867If a third argument is given and the second one is empty, then the
5868third argument serves both. (Note how two commas, side by side, mark
5869the empty second argument.)@refill
5870
5871@example
5872@group
5873@@xref@{Electrical Effects, , Thunder and Lightning@},
5874for details.
5875@end group
5876@end example
5877
5878@noindent
5879produces
5880
5881@example
5882*Note Thunder and Lightning: Electrical Effects, for details.
5883@end example
5884
5885@noindent
5886and
5887
5888@quotation
5889See Section 5.2 [Thunder and Lightning], page 57, for details.
5890@end quotation
5891
5892As a practical matter, it is often best to write cross references with
5893just the first argument if the node name and the section title are the
5894same, and with the first and third arguments if the node name and title
5895are different.@refill
5896
5897Here are several examples from @cite{The GNU Awk User's Guide}:@refill
5898
5899@smallexample
5900@@xref@{Sample Program@}.
5901@@xref@{Glossary@}.
5902@@xref@{Case-sensitivity, ,Case-sensitivity in Matching@}.
5903@@xref@{Close Output, , Closing Output Files and Pipes@},
5904 for more information.
5905@@xref@{Regexp, , Regular Expressions as Patterns@}.
5906@end smallexample
5907
5908@node Four and Five Arguments, , Three Arguments, xref
5909@subsection @code{@@xref} with Four and Five Arguments
5910
5911In a cross reference, a fourth argument specifies the name of another
5912Info file, different from the file in which the reference appears, and
5913a fifth argument specifies its title as a printed manual.@refill
5914
5915Remember that a comma or period must follow the closing brace of an
5916@code{@@xref} command to terminate the cross reference. In the
5917following examples, a clause follows a terminating comma.@refill
5918
5919@need 800
5920@noindent
5921The template is:
5922
5923@example
5924@group
5925@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic},
5926@var{info-file-name}, @var{printed-manual-title}@}.
5927@end group
5928@end example
5929
5930@need 700
5931@noindent
5932For example,
5933
5934@example
5935@@xref@{Electrical Effects, Lightning, Thunder and Lightning,
5936weather, An Introduction to Meteorology@}, for details.
5937@end example
5938
5939@noindent
5940produces
5941
5942@example
5943*Note Lightning: (weather)Electrical Effects, for details.
5944@end example
5945
5946@noindent
5947The name of the Info file is enclosed in parentheses and precedes
5948the name of the node.
5949
5950@noindent
5951In a printed manual, the reference looks like this:@refill
5952
5953@quotation
5954See section ``Thunder and Lightning'' in @i{An Introduction to
5955Meteorology}, for details.
5956@end quotation
5957
5958@noindent
5959The title of the printed manual is typeset in italics; and the
5960reference lacks a page number since @TeX{} cannot know to which page a
5961reference refers when that reference is to another manual.@refill
5962
5963Often, you will leave out the second argument when you use the long
5964version of @code{@@xref}. In this case, the third argument, the topic
5965description, will be used as the cross reference name in Info.@refill
5966
5967@noindent
5968The template looks like this:
5969
5970@example
5971@@xref@{@var{node-name}, , @var{title-or-topic}, @var{info-file-name},
5972@var{printed-manual-title}@}, for details.
5973@end example
5974
5975@noindent
5976which produces
5977
5978@example
5979*Note @var{title-or-topic}: (@var{info-file-name})@var{node-name}, for details.
5980@end example
5981
5982@noindent
5983and
5984
5985@quotation
5986See section @var{title-or-topic} in @var{printed-manual-title}, for details.
5987@end quotation
5988
5989@need 700
5990@noindent
5991For example,
5992
5993@example
5994@@xref@{Electrical Effects, , Thunder and Lightning,
5995weather, An Introduction to Meteorology@}, for details.
5996@end example
5997
5998@noindent
5999produces
6000
6001@example
6002@group
6003*Note Thunder and Lightning: (weather)Electrical Effects,
6004for details.
6005@end group
6006@end example
6007
6008@noindent
6009and
6010
6011@quotation
6012See section ``Thunder and Lightning'' in @i{An Introduction to
6013Meteorology}, for details.
6014@end quotation
6015
6016On rare occasions, you may want to refer to another Info file that
6017is within a single printed manual---when multiple Texinfo files are
6018incorporated into the same @TeX{} run but make separate Info files.
6019In this case, you need to specify only the fourth argument, and not
6020the fifth.@refill
6021
6022@node Top Node Naming, ref, xref, Cross References
6023@section Naming a `Top' Node
6024@cindex Naming a `Top' Node in references
6025@cindex @samp{@r{Top}} node naming for references
6026
6027In a cross reference, you must always name a node. This means that in
6028order to refer to a whole manual, you must identify the `Top' node by
6029writing it as the first argument to the @code{@@xref} command. (This
6030is different from the way you write a menu entry; see @ref{Other Info
6031Files, , Referring to Other Info Files}.) At the same time, to
6032provide a meaningful section topic or title in the printed cross
6033reference (instead of the word `Top'), you must write an appropriate
6034entry for the third argument to the @code{@@xref} command.
6035@refill
6036
6037@noindent
6038Thus, to make a cross reference to @cite{The GNU Make Manual},
6039write:@refill
6040
6041@example
6042@@xref@{Top, , Overview, make, The GNU Make Manual@}.
6043@end example
6044
6045@noindent
6046which produces
6047
6048@example
6049*Note Overview: (make)Top.
6050@end example
6051
6052@noindent
6053and
6054
6055@quotation
6056See section ``Overview'' in @i{The GNU Make Manual}.
6057@end quotation
6058
6059@noindent
6060In this example, @samp{Top} is the name of the first node, and
6061@samp{Overview} is the name of the first section of the manual.@refill
6062@node ref, pxref, Top Node Naming, Cross References
6063@comment node-name, next, previous, up
6064@section @code{@@ref}
6065@cindex Cross references using @code{@@ref}
6066@cindex References using @code{@@ref}
6067@findex ref
6068
6069@code{@@ref} is nearly the same as @code{@@xref} except that it does
6070not generate a `See' in the printed output, just the reference itself.
6071This makes it useful as the last part of a sentence.@refill
6072
6073@need 700
6074@noindent
6075For example,
6076
6077@cindex Hurricanes
6078@example
6079For more information, see @@ref@{Hurricanes@}.
6080@end example
6081
6082@noindent
6083produces
6084
6085@example
6086For more information, see *Note Hurricanes::.
6087@end example
6088
6089@noindent
6090and
6091
6092@quotation
6093For more information, see Section 8.2 [Hurricanes], page 123.
6094@end quotation
6095
6096The @code{@@ref} command sometimes leads writers to express themselves
6097in a manner that is suitable for a printed manual but looks awkward
6098in the Info format. Bear in mind that your audience will be using
6099both the printed and the Info format.@refill
6100
6101@need 800
6102@noindent
6103For example,
6104
6105@cindex Sea surges
6106@example
6107@group
6108Sea surges are described in @@ref@{Hurricanes@}.
6109@end group
6110@end example
6111
6112@need 800
6113@noindent
6114produces
6115
6116@quotation
6117Sea surges are described in Section 6.7 [Hurricanes], page 72.
6118@end quotation
6119
6120@need 800
6121@noindent
6122in a printed document, and the following in Info:
6123
6124@example
6125Sea surges are described in *Note Hurricanes::.
6126@end example
6127
6128@quotation
6129@strong{Caution:} You @emph{must} write a period, comma, or right
6130parenthesis immediately after an @code{@@ref} command with two or more
6131arguments. Otherwise, Info will not find the end of the cross reference
6132entry and its attempt to follow the cross reference will fail. As a
6133general rule, you should write a period or comma after every
6134@code{@@ref} command. This looks best in both the printed and the Info
6135output.@refill
6136@end quotation
6137
6138@node pxref, inforef, ref, Cross References
6139@comment node-name, next, previous, up
6140@section @code{@@pxref}
6141@cindex Cross references using @code{@@pxref}
6142@cindex References using @code{@@pxref}
6143@findex pxref
6144
6145The parenthetical reference command, @code{@@pxref}, is nearly the
6146same as @code{@@xref}, but you use it @emph{only} inside parentheses
6147and you do @emph{not} type a comma or period after the command's
6148closing brace. The command differs from @code{@@xref} in two
6149ways:@refill
6150
6151@enumerate
6152@item
6153@TeX{} typesets the reference for the printed manual with a lower case
6154`see' rather than an upper case `See'.@refill
6155
6156@item
6157The Info formatting commands automatically end the reference with a
6158closing colon or period.@refill
6159@end enumerate
6160
6161Because one type of formatting automatically inserts closing
6162punctuation and the other does not, you should use @code{@@pxref}
6163@emph{only} inside parentheses as part of another sentence. Also, you
6164yourself should not insert punctuation after the reference, as you do
6165with @code{@@xref}.@refill
6166
6167@code{@@pxref} is designed so that the output looks right and works
6168right between parentheses both in printed output and in an Info file.
6169In a printed manual, a closing comma or period should not follow a
6170cross reference within parentheses; such punctuation is wrong. But in
6171an Info file, suitable closing punctuation must follow the cross
6172reference so Info can recognize its end. @code{@@pxref} spares you
6173the need to use complicated methods to put a terminator into one form
6174of the output and not the other.@refill
6175
6176@noindent
6177With one argument, a parenthetical cross reference looks like
6178this:@refill
6179
6180@cindex Flooding
6181@example
6182@dots{} storms cause flooding (@@pxref@{Hurricanes@}) @dots{}
6183@end example
6184
6185@need 800
6186@noindent
6187which produces
6188
6189@example
6190@group
6191@dots{} storms cause flooding (*Note Hurricanes::) @dots{}
6192@end group
6193@end example
6194
6195@noindent
6196and
6197
6198@quotation
6199@dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{}
6200@end quotation
6201
6202With two arguments, a parenthetical cross reference has this
6203template:@refill
6204
6205@example
6206@dots{} (@@pxref@{@var{node-name}, @var{cross-reference-name}@}) @dots{}
6207@end example
6208
6209@noindent
6210which produces
6211
6212@example
6213@dots{} (*Note @var{cross-reference-name}: @var{node-name}.) @dots{}
6214@end example
6215
6216@noindent
6217and
6218
6219@need 1500
6220@quotation
6221@dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{}
6222@end quotation
6223
6224@code{@@pxref} can be used with up to five arguments just like
6225@code{@@xref} (@pxref{xref, , @code{@@xref}}).@refill
6226
6227@quotation
6228@strong{Please note:} Use @code{@@pxref} only as a parenthetical
6229reference. Do not try to use @code{@@pxref} as a clause in a sentence.
6230It will look bad in either the Info file, the printed output, or
6231both.@refill
6232
6233Also, parenthetical cross references look best at the ends of sentences.
6234Although you may write them in the middle of a sentence, that location
6235breaks up the flow of text.@refill
6236@end quotation
6237
6238@node inforef, uref, pxref, Cross References
6239@section @code{@@inforef}
6240@cindex Cross references using @code{@@inforef}
6241@cindex References using @code{@@inforef}
6242@findex inforef
6243
6244@code{@@inforef} is used for cross references to Info files for which
6245there are no printed manuals. Even in a printed manual,
6246@code{@@inforef} generates a reference directing the user to look in
6247an Info file.@refill
6248
6249The command takes either two or three arguments, in the following
6250order:@refill
6251
6252@enumerate
6253@item
6254The node name.
6255
6256@item
6257The cross reference name (optional).
6258
6259@item
6260The Info file name.
6261@end enumerate
6262
6263@noindent
6264Separate the arguments with commas, as with @code{@@xref}. Also, you
6265must terminate the reference with a comma or period after the
6266@samp{@}}, as you do with @code{@@xref}.@refill
6267
6268@noindent
6269The template is:
6270
6271@example
6272@@inforef@{@var{node-name}, @var{cross-reference-name}, @var{info-file-name}@},
6273@end example
6274
6275@need 800
6276@noindent
6277Thus,
6278
6279@example
6280@group
6281@@inforef@{Expert, Advanced Info commands, info@},
6282for more information.
6283@end group
6284@end example
6285
6286@need 800
6287@noindent
6288produces
6289
6290@example
6291@group
6292*Note Advanced Info commands: (info)Expert,
6293for more information.
6294@end group
6295@end example
6296
6297@need 800
6298@noindent
6299and
6300
6301@quotation
6302See Info file @file{info}, node @samp{Expert}, for more information.
6303@end quotation
6304
6305@need 800
6306@noindent
6307Similarly,
6308
6309@example
6310@group
6311@@inforef@{Expert, , info@}, for more information.
6312@end group
6313@end example
6314
6315@need 800
6316@noindent
6317produces
6318
6319@example
6320*Note (info)Expert::, for more information.
6321@end example
6322
6323@need 800
6324@noindent
6325and
6326
6327@quotation
6328See Info file @file{info}, node @samp{Expert}, for more information.
6329@end quotation
6330
6331The converse of @code{@@inforef} is @code{@@cite}, which is used to
6332refer to printed works for which no Info form exists. @xref{cite, ,
6333@code{@@cite}}.@refill
6334
6335
6336@node uref
6337@section @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}}
6338@findex uref
6339@cindex Uniform resource locator, referring to
6340@cindex URL, referring to
6341
6342@cindex @code{href}, producing HTML
6343@code{@@uref} produces a reference to a uniform resource locator (url).
6344It takes one mandatory argument, the url, and two optional arguments
6345which control the text that is displayed. In HTML output, @code{@@uref}
6346produces a link you can follow.
6347
6348The second argument, if specified, is the text to display (the default
6349is the url itself); in Info and DVI output, but not in HTML output, the
6350url is also output.
6351
6352@cindex Man page, reference to
6353The third argument, on the other hand, if specified is also the text to
6354display, but the url is @emph{not} output in any format. This is useful
6355when the text is already sufficiently referential, as in a man page. If
6356the third argument is given, the second argument is ignored.
6357
6358The simple one argument form, where the url is both the target and the
6359text of the link:
6360
6361@example
6362The official GNU ftp site is @@uref@{ftp://ftp.gnu.org/gnu@}.
6363@end example
6364
6365@noindent produces:
6366@display
6367The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}.
6368@end display
6369
6370
6371An example of the two-argument form:
6372@example
6373The official @@uref@{ftp://ftp.gnu.org/gnu, GNU ftp site@}
6374holds programs and texts.
6375@end example
6376
6377@noindent produces:
6378@display
6379The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site}
6380holds programs and texts.
6381@end display
6382
6383@noindent that is, the Info output is this:
6384@example
6385The official GNU ftp site (ftp://ftp.gnu.org/gnu)
6386holds programs and texts.
6387@end example
6388
6389@noindent and the HTML output is this:
6390@example
6391The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a>
6392holds programs and texts.
6393@end example
6394
6395
6396An example of the three-argument form:
6397@example
6398The @@uref@{/man.cgi/1/ls,,ls(1)@} program @dots{}
6399@end example
6400
6401@noindent produces:
6402@display
6403The @uref{/man.cgi/1/ls,,ls(1)} program @dots{}
6404@end display
6405
6406@noindent but with HTML:
6407@example
6408The <a href="/man.cgi/1/ls">ls(1)</a> program @dots{}
6409@end example
6410
6411To merely indicate a url without creating a link people can follow, use
6412@code{@@url} (@pxref{url, @code{@@url}}).
6413
6414Some people prefer to display url's in the unambiguous format:
6415
6416@display
6417<URL:http://@var{host}/@var{path}>
6418@end display
6419
6420@noindent
6421@cindex <URL convention, not used
6422You can use this form in the input file if you wish. We feel it's not
6423necessary to clutter up the output with the extra @samp{<URL:} and
6424@samp{>}, since any software that tries to detect url's in text already
6425has to detect them without the @samp{<URL:} to be useful.
6426
6427
6428@node Marking Text
6429@chapter Marking Words and Phrases
6430@cindex Paragraph, marking text within
6431@cindex Marking words and phrases
6432@cindex Words and phrases, marking them
6433@cindex Marking text within a paragraph
6434@cindex Text, marking up
6435
6436In Texinfo, you can mark words and phrases in a variety of ways.
6437The Texinfo formatters use this information to determine how to
6438highlight the text.
6439You can specify, for example, whether a word or phrase is a
6440defining occurrence, a metasyntactic variable, or a symbol used in a
6441program. Also, you can emphasize text, in several different ways.
6442
6443@menu
6444* Indicating:: How to indicate definitions, files, etc.
6445* Emphasis:: How to emphasize text.
6446@end menu
6447
6448
6449@node Indicating, Emphasis, Marking Text, Marking Text
6450@section Indicating Definitions, Commands, etc.
6451@cindex Highlighting text
6452@cindex Indicating commands, definitions, etc.
6453
6454Texinfo has commands for indicating just what kind of object a piece of
6455text refers to. For example, metasyntactic variables are marked by
6456@code{@@var}, and code by @code{@@code}. Since the pieces of text are
6457labelled by commands that tell what kind of object they are, it is easy
6458to change the way the Texinfo formatters prepare such text. (Texinfo is
6459an @emph{intentional} formatting language rather than a @emph{typesetting}
6460formatting language.)@refill
6461
6462For example, in a printed manual,
6463code is usually illustrated in a typewriter font;
6464@code{@@code} tells @TeX{} to typeset this text in this font. But it
6465would be easy to change the way @TeX{} highlights code to use another
6466font, and this change would not affect how keystroke examples are
6467highlighted. If straight typesetting commands were used in the body
6468of the file and you wanted to make a change, you would need to check
6469every single occurrence to make sure that you were changing code and
6470not something else that should not be changed.@refill
6471
6472@menu
6473* Useful Highlighting:: Highlighting provides useful information.
6474* code:: Indicating program code.
6475* kbd:: Showing keyboard input.
6476* key:: Specifying keys.
6477* samp:: A literal sequence of characters.
|
6410* verb:: A verbatim sequence of characters.
| 6478* verb:: A verbatim sequence of characters.
|
6411* var:: Indicating metasyntactic variables.
6412* env:: Indicating environment variables.
6413* file:: Indicating file names.
6414* command:: Indicating command names.
6415* option:: Indicating option names.
6416* dfn:: Specifying definitions.
6417* cite:: Referring to books not in the Info system.
6418* acronym:: Indicating acronyms.
6419* url:: Indicating a World Wide Web reference.
6420* email:: Indicating an electronic mail address.
6421@end menu
6422
6423
6424@node Useful Highlighting, code, Indicating, Indicating
6425@ifinfo
6426@subheading Highlighting Commands are Useful
6427@end ifinfo
6428
6429The highlighting commands can be used to extract useful information
6430from the file, such as lists of functions or file names. It is
6431possible, for example, to write a program in Emacs Lisp (or a keyboard
6432macro) to insert an index entry after every paragraph that contains
6433words or phrases marked by a specified command. You could do this to
6434construct an index of functions if you had not already made the
6435entries.@refill
6436
6437The commands serve a variety of purposes:@refill
6438
6439@table @code
6440@item @@code@{@var{sample-code}@}
6441Indicate text that is a literal example of a piece of a program.@refill
6442
6443@item @@kbd@{@var{keyboard-characters}@}
6444Indicate keyboard input.@refill
6445
6446@item @@key@{@var{key-name}@}
6447Indicate the conventional name for a key on a keyboard.@refill
6448
6449@item @@samp@{@var{text}@}
6450Indicate text that is a literal example of a sequence of characters.@refill
6451
6452@item @@var@{@var{metasyntactic-variable}@}
6453Indicate a metasyntactic variable.@refill
6454
6455@item @@env@{@var{environment-variable}@}
6456Indicate an environment variable.@refill
6457
6458@item @@file@{@var{file-name}@}
6459Indicate the name of a file.@refill
6460
6461@item @@command@{@var{command-name}@}
6462Indicate the name of a command.@refill
6463
6464@item @@option@{@var{option}@}
6465Indicate a command-line option.@refill
6466
6467@item @@dfn@{@var{term}@}
6468Indicate the introductory or defining use of a term.@refill
6469
6470@item @@cite@{@var{reference}@}
6471Indicate the name of a book.@refill
6472
6473@item @@acronym@{@var{acronym}@}
6474Indicate an acronym.@refill
6475
6476@item @@url@{@var{uniform-resource-locator}@}
6477Indicate a uniform resource locator for the World Wide Web.
6478
6479@item @@email@{@var{email-address}[, @var{displayed-text}]@}
6480Indicate an electronic mail address.
6481
6482@ignore
6483@item @@ctrl@{@var{ctrl-char}@}
6484Use for an @sc{ascii} control character.@refill
6485@end ignore
6486@end table
6487
6488
6489@node code
6490@subsection @code{@@code}@{@var{sample-code}@}
6491@findex code
6492
6493@cindex Syntactic tokens, indicating
6494Use the @code{@@code} command to indicate text that is a piece of a
6495program and which consists of entire syntactic tokens. Enclose the
6496text in braces.
6497
6498@cindex Expressions in a program, indicating
6499@cindex Keywords, indicating
6500@cindex Reserved words, indicating
6501Thus, you should use @code{@@code} for an expression in a program, for
6502the name of a variable or function used in a program, or for a
6503keyword in a programming language.
6504
6505Use @code{@@code} for command names in languages that resemble
6506programming languages, such as Texinfo. For example, @code{@@code} and
6507@code{@@samp} are produced by writing @samp{@@code@{@@@@code@}} and
6508@samp{@@code@{@@@@samp@}} in the Texinfo source, respectively.
6509
6510@cindex Case, not altering in @code{@@code}
6511It is incorrect to alter the case of a word inside an @code{@@code}
6512command when it appears at the beginning of a sentence. Most computer
6513languages are case sensitive. In C, for example, @code{Printf} is
6514different from the identifier @code{printf}, and most likely is a
6515misspelling of it. Even in languages which are not case sensitive, it
6516is confusing to a human reader to see identifiers spelled in different
6517ways. Pick one spelling and always use that. If you do not want to
6518start a sentence with a command name written all in lower case, you
6519should rearrange the sentence.
6520
6521In the printed manual, @code{@@code} causes @TeX{} to typeset the
6522argument in a typewriter face. In the Info file, it causes the Info
6523formatting commands to use single quotation marks around the text.
6524
6525@need 700
6526For example,
6527
6528@example
6529The function returns @@code@{nil@}.
6530@end example
6531
6532@noindent
6533produces this in the printed manual:
6534
6535@quotation
6536The function returns @code{nil}.
6537@end quotation
6538
6539@iftex
6540@noindent
6541and this in the Info file:
6542@example
6543The function returns `nil'.
6544@end example
6545@end iftex
6546
6547Here are some cases for which it is preferable not to use @code{@@code}:
6548
6549@itemize @bullet
6550@item
6551For shell command names such as @command{ls} (use @code{@@command}).
6552
6553@item
6554For shell options such as @samp{-c} when such options stand alone (use
6555@code{@@option}).
6556
6557@item
6558Also, an entire shell command often looks better if written using
6559@code{@@samp} rather than @code{@@code}. In this case, the rule is to
6560choose the more pleasing format.
6561
6562@item
6563For environment variable such as @env{TEXINPUTS} (use @code{@@env}).
6564
6565@item
6566For a string of characters shorter than a syntactic token. For example,
6567if you are writing about @samp{goto-ch}, which is just a part of the
6568name for the @code{goto-char} Emacs Lisp function, you should use
6569@code{@@samp}.
6570
6571@item
6572In general, when writing about the characters used in a token; for
6573example, do not use @code{@@code} when you are explaining what letters
6574or printable symbols can be used in the names of functions. (Use
6575@code{@@samp}.) Also, you should not use @code{@@code} to mark text
6576that is considered input to programs unless the input is written in a
6577language that is like a programming language. For example, you should
6578not use @code{@@code} for the keystroke commands of GNU Emacs (use
6579@code{@@kbd} instead) although you may use @code{@@code} for the names
6580of the Emacs Lisp functions that the keystroke commands invoke.
6581
6582@end itemize
6583
6584Since @code{@@command}, @code{@@option}, and @code{@@env} were
6585introduced relatively recently, it is acceptable to use @code{@@code} or
6586@code{@@samp} for command names, options, and environment variables.
6587The new commands allow you to express the markup more precisely, but
6588there is no real harm in using the older commands, and of course the
6589long-standing manuals do so.
6590
6591
6592@node kbd
6593@subsection @code{@@kbd}@{@var{keyboard-characters}@}
6594@findex kbd
6595@cindex Keyboard input
6596
6597Use the @code{@@kbd} command for characters of input to be typed by
6598users. For example, to refer to the characters @kbd{M-a},
6599write@refill
6600
6601@example
6602@@kbd@{M-a@}
6603@end example
6604
6605@noindent
6606and to refer to the characters @kbd{M-x shell}, write@refill
6607
6608@example
6609@@kbd@{M-x shell@}
6610@end example
6611
6612@cindex user input
6613@cindex slanted typewriter font, for @code{@@kbd}
6614The @code{@@kbd} command has the same effect as @code{@@code} in Info,
6615but by default produces a different font (slanted typewriter instead of
6616normal typewriter) in the printed manual, so users can distinguish the
6617characters they are supposed to type from those the computer outputs.
6618
6619@findex kbdinputstyle
6620Since the usage of @code{@@kbd} varies from manual to manual, you can
6621control the font switching with the @code{@@kbdinputstyle} command.
6622This command has no effect on Info output. Write this command at the
6623beginning of a line with a single word as an argument, one of the
6624following:
6625@vindex distinct@r{, arg to @@kbdinputstyle}
6626@vindex example@r{, arg to @@kbdinputstyle}
6627@vindex code@r{, arg to @@kbdinputstyle}
6628@table @samp
6629@item code
6630Always use the same font for @code{@@kbd} as @code{@@code}.
6631@item example
6632Use the distinguishing font for @code{@@kbd} only in @code{@@example}
6633and similar environments.
6634@item distinct
6635(the default) Always use the distinguishing font for @code{@@kbd}.
6636@end table
6637
6638You can embed another @@-command inside the braces of an @code{@@kbd}
6639command. Here, for example, is the way to describe a command that
6640would be described more verbosely as ``press an @samp{r} and then
6641press the @key{RET} key'':@refill
6642
6643@example
6644@@kbd@{r @@key@{RET@}@}
6645@end example
6646
6647@noindent
6648This produces: @kbd{r @key{RET}}
6649
6650You also use the @code{@@kbd} command if you are spelling out the letters
6651you type; for example:@refill
6652
6653@example
6654To give the @@code@{logout@} command,
6655type the characters @@kbd@{l o g o u t @@key@{RET@}@}.
6656@end example
6657
6658@noindent
6659This produces:
6660
6661@quotation
6662To give the @code{logout} command,
6663type the characters @kbd{l o g o u t @key{RET}}.
6664@end quotation
6665
6666(Also, this example shows that you can add spaces for clarity. If you
6667really want to mention a space character as one of the characters of
6668input, write @kbd{@@key@{SPC@}} for it.)@refill
6669
6670
6671@node key, samp, kbd, Indicating
6672@comment node-name, next, previous, up
6673@subsection @code{@@key}@{@var{key-name}@}
6674@findex key
6675
6676Use the @code{@@key} command for the conventional name for a key on a
6677keyboard, as in:@refill
6678
6679@example
6680@@key@{RET@}
6681@end example
6682
6683You can use the @code{@@key} command within the argument of an
6684@code{@@kbd} command when the sequence of characters to be typed
6685includes one or more keys that are described by name.@refill
6686
6687@need 700
6688For example, to produce @kbd{C-x @key{ESC}} you would type:@refill
6689
6690@example
6691@@kbd@{C-x @@key@{ESC@}@}
6692@end example
6693
6694Here is a list of the recommended names for keys:
6695@cindex Recommended names for keys
6696@cindex Keys, recommended names
6697@cindex Names recommended for keys
6698@cindex Abbreviations for keys
6699
6700@quotation
6701@table @t
6702@item SPC
6703Space
6704@item RET
6705Return
6706@item LFD
6707Linefeed (however, since most keyboards nowadays do not have a Linefeed key,
6708it might be better to call this character @kbd{C-j}.
6709@item TAB
6710Tab
6711@item BS
6712Backspace
6713@item ESC
6714Escape
6715@item DEL
6716Delete
6717@item SHIFT
6718Shift
6719@item CTRL
6720Control
6721@item META
6722Meta
6723@end table
6724@end quotation
6725
6726@cindex META key
6727There are subtleties to handling words like `meta' or `ctrl' that are
6728names of modifier keys. When mentioning a character in which the
6729modifier key is used, such as @kbd{Meta-a}, use the @code{@@kbd} command
6730alone; do not use the @code{@@key} command; but when you are referring
6731to the modifier key in isolation, use the @code{@@key} command. For
6732example, write @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and
6733@samp{@@key@{META@}} to produce @key{META}.
6734
6735@c I don't think this is a good explanation.
6736@c I think it will puzzle readers more than it clarifies matters. -- rms.
6737@c In other words, use @code{@@kbd} for what you do, and use @code{@@key}
6738@c for what you talk about: ``Press @code{@@kbd@{M-a@}} to move point to
6739@c the beginning of the sentence. The @code{@@key@{META@}} key is often in
6740@c the lower left of the keyboard.''@refill
6741
6742@node samp
6743@subsection @code{@@samp}@{@var{text}@}
6744@findex samp
6745
6746Use the @code{@@samp} command to indicate text that is a literal example
6747or `sample' of a sequence of characters in a file, string, pattern, etc.
6748Enclose the text in braces. The argument appears within single
6749quotation marks in both the Info file and the printed manual; in
6750addition, it is printed in a fixed-width font.@refill
6751
6752@example
6753To match @@samp@{foo@} at the end of the line,
6754use the regexp @@samp@{foo$@}.
6755@end example
6756
6757@noindent
6758produces
6759
6760@quotation
6761To match @samp{foo} at the end of the line, use the regexp
6762@samp{foo$}.@refill
6763@end quotation
6764
6765Any time you are referring to single characters, you should use
6766@code{@@samp} unless @code{@@kbd} or @code{@@key} is more appropriate.
6767Also, you may use @code{@@samp} for entire statements in C and for entire
6768shell commands---in this case, @code{@@samp} often looks better than
6769@code{@@code}. Basically, @code{@@samp} is a catchall for whatever is
6770not covered by @code{@@code}, @code{@@kbd}, or @code{@@key}.@refill
6771
6772Only include punctuation marks within braces if they are part of the
6773string you are specifying. Write punctuation marks outside the braces
6774if those punctuation marks are part of the English text that surrounds
6775the string. In the following sentence, for example, the commas and
6776period are outside of the braces:@refill
6777
6778@example
6779@group
6780In English, the vowels are @@samp@{a@}, @@samp@{e@},
6781@@samp@{i@}, @@samp@{o@}, @@samp@{u@}, and sometimes
6782@@samp@{y@}.
6783@end group
6784@end example
6785
6786@noindent
6787This produces:
6788
6789@quotation
6790In English, the vowels are @samp{a}, @samp{e},
6791@samp{i}, @samp{o}, @samp{u}, and sometimes
6792@samp{y}.
6793@end quotation
6794
6795
6796@node verb
6797@subsection @code{@@verb}@{<char>@var{text}<char>@}
6798@findex verb
6799@cindex Verbatim in-line text
6800
6801@cindex Delimiter character, for verbatim
6802Use the @code{@@verb} command to print a verbatim sequence of
6803characters.
6804
6805Like La@TeX{}'s @code{\verb} command, the verbatim text can be quoted using
6806any unique delimiter character. Enclose the verbatim text, including the
6807delimiters, in braces. Text is printed in a fixed-width font:
6808
6809@example
6810How many @@verb@{|@@|@}-escapes does one need to print this
6811@@verb@{.@@a @@b @@c.@} string or @@verb@{+@@'e@?`@!`@{@}\+@} this?
6812@end example
6813
6814@noindent
6815produces
6816
6817@example
6818How many @verb{|@|}-escapes does one need to print this
6819@verb{.@a @b @c.} string or these @verb{+@'e?`{}!`\+} this?
6820@end example
6821
6822This is in contrast to @code{@@samp} (see the previous
6823section), whose argument is normal Texinfo text, where the characters
6824@code{@@@{@}} are special; with @code{@@verb}, nothing is special except
6825the delimiter character you choose.
6826
6827
6828@node var
6829@subsection @code{@@var}@{@var{metasyntactic-variable}@}
6830@findex var
6831
6832Use the @code{@@var} command to indicate metasyntactic variables. A
6833@dfn{metasyntactic variable} is something that stands for another piece of
6834text. For example, you should use a metasyntactic variable in the
6835documentation of a function to describe the arguments that are passed
6836to that function.@refill
6837
6838Do not use @code{@@var} for the names of particular variables in
6839programming languages. These are specific names from a program, so
6840@code{@@code} is correct for them (@pxref{code}). For example, the
6841Emacs Lisp variable @code{texinfo-tex-command} is not a metasyntactic
6842variable; it is properly formatted using @code{@@code}.
6843
6844Do not use @code{@@var} for environment variables either; @code{@@env}
6845is correct for them (see the next section).
6846
6847The effect of @code{@@var} in the Info file is to change the case of the
6848argument to all upper case. In the printed manual and HTML output, the
6849argument is printed in slanted type.
6850
6851@need 700
6852For example,
6853
6854@example
6855To delete file @@var@{filename@},
6856type @@samp@{rm @@var@{filename@}@}.
6857@end example
6858
6859@noindent
6860produces
6861
6862@quotation
6863To delete file @var{filename}, type @samp{rm @var{filename}}.
6864@end quotation
6865
6866@noindent
6867(Note that @code{@@var} may appear inside @code{@@code},
6868@code{@@samp}, @code{@@file}, etc.)@refill
6869
6870Write a metasyntactic variable all in lower case without spaces, and
6871use hyphens to make it more readable. Thus, the Texinfo source for
6872the illustration of how to begin a Texinfo manual looks like
6873this:@refill
6874
6875@example
6876@group
6877\input texinfo
6878@@@@setfilename @@var@{info-file-name@}
6879@@@@settitle @@var@{name-of-manual@}
6880@end group
6881@end example
6882
6883@noindent
6884This produces:
6885
6886@example
6887@group
6888\input texinfo
6889@@setfilename @var{info-file-name}
6890@@settitle @var{name-of-manual}
6891@end group
6892@end example
6893
6894In some documentation styles, metasyntactic variables are shown with
6895angle brackets, for example:@refill
6896
6897@example
6898@dots{}, type rm <filename>
6899@end example
6900
6901@noindent
6902However, that is not the style that Texinfo uses. (You can, of
6903course, modify the sources to @file{texinfo.tex} and the Info formatting commands
6904to output the @code{<@dots{}>} format if you wish.)@refill
6905
6906
6907@node env
6908@subsection @code{@@env}@{@var{environment-variable}@}
6909@findex env
6910
6911Use the @code{@@env} command to indicate environment variables, as used
6912by many operating systems, including GNU. Do not use it for
6913metasyntactic variables; use @code{@@var} instead (see the previous
6914section).
6915
6916@code{@@env} is equivalent to @code{@@code} in its effects.
6917For example:
6918
6919@example
6920The @@env@{PATH@} environment variable @dots{}
6921@end example
6922@noindent produces
6923@quotation
6924The @env{PATH} environment variable @dots{}
6925@end quotation
6926
6927
6928@node file
6929@subsection @code{@@file}@{@var{file-name}@}
6930@findex file
6931
6932Use the @code{@@file} command to indicate text that is the name of a
6933file, buffer, or directory, or is the name of a node in Info. You can
6934also use the command for file name suffixes. Do not use @code{@@file}
6935for symbols in a programming language; use @code{@@code}.
6936
6937Currently, @code{@@file} is equivalent to @code{@@samp} in its effects.
6938For example,@refill
6939
6940@example
6941The @@file@{.el@} files are in
6942the @@file@{/usr/local/emacs/lisp@} directory.
6943@end example
6944
6945@noindent
6946produces
6947
6948@quotation
6949The @file{.el} files are in
6950the @file{/usr/local/emacs/lisp} directory.
6951@end quotation
6952
6953
6954@node command
6955@subsection @code{@@command}@{@var{command-name}@}
6956@findex command
6957@cindex Command names, indicating
6958@cindex Program names, indicating
6959
6960Use the @code{@@command} command to indicate command names, such as
6961@command{ls} or @command{cc}.
6962
6963@code{@@command} is equivalent to @code{@@code} in its effects.
6964For example:
6965
6966@example
6967The command @@command@{ls@} lists directory contents.
6968@end example
6969@noindent produces
6970@quotation
6971The command @command{ls} lists directory contents.
6972@end quotation
6973
6974You should write the name of a program in the ordinary text font, rather
6975than using @code{@@command}, if you regard it as a new English word,
6976such as `Emacs' or `Bison'.
6977
6978When writing an entire shell command invocation, as in @samp{ls -l},
6979you should use either @code{@@samp} or @code{@@code} at your discretion.
6980
6981
6982@node option
6983@subsection @code{@@option}@{@var{option-name}@}
6984@findex option
6985
6986Use the @code{@@option} command to indicate a command-line option; for
6987example, @option{-l} or @option{--version} or
6988@option{--output=@var{filename}}.
6989
6990@code{@@option} is equivalent to @code{@@samp} in its effects.
6991For example:
6992
6993@example
6994The option @@option@{-l@} produces a long listing.
6995@end example
6996@noindent produces
6997@quotation
6998The option @option{-l} produces a long listing.
6999@end quotation
7000
7001In tables, putting options inside @code{@@code} produces a
7002more pleasing effect.
7003
7004@node dfn
7005@comment node-name, next, previous, up
7006@subsection @code{@@dfn}@{@var{term}@}
7007@findex dfn
7008
7009Use the @code{@@dfn} command to identify the introductory or defining
7010use of a technical term. Use the command only in passages whose
7011purpose is to introduce a term which will be used again or which the
7012reader ought to know. Mere passing mention of a term for the first
7013time does not deserve @code{@@dfn}. The command generates italics in
7014the printed manual, and double quotation marks in the Info file. For
7015example:@refill
7016
7017@example
7018Getting rid of a file is called @@dfn@{deleting@} it.
7019@end example
7020
7021@noindent
7022produces
7023
7024@quotation
7025Getting rid of a file is called @dfn{deleting} it.
7026@end quotation
7027
7028As a general rule, a sentence containing the defining occurrence of a
7029term should be a definition of the term. The sentence does not need
7030to say explicitly that it is a definition, but it should contain the
7031information of a definition---it should make the meaning clear.
7032
7033@node cite
7034@subsection @code{@@cite}@{@var{reference}@}
7035@findex cite
7036
7037Use the @code{@@cite} command for the name of a book that lacks a
7038companion Info file. The command produces italics in the printed
7039manual, and quotation marks in the Info file.
7040
7041If a book is written in Texinfo, it is better to use a cross reference
7042command since a reader can easily follow such a reference in Info.
7043@xref{xref, , @code{@@xref}}.
7044
7045
7046@ignore
7047@c node ctrl, , cite, Indicating
7048@comment node-name, next, previous, up
7049@c subsection @code{@@ctrl}@{@var{ctrl-char}@}
7050@findex ctrl
7051
7052The @code{@@ctrl} command is seldom used. It describes an @sc{ascii}
7053control character by inserting the actual character into the Info
7054file.
7055
7056Usually, in Texinfo, you talk what you type as keyboard entry by
7057describing it with @code{@@kbd}: thus, @samp{@@kbd@{C-a@}} for
7058@kbd{C-a}. Use @code{@@kbd} in this way when talking about a control
7059character that is typed on the keyboard by the user. When talking
7060about a control character appearing in a file or a string, do not use
7061@code{@@kbd} since the control character is not typed. Also, do not
7062use @samp{C-} but spell out @code{control-}, as in @samp{control-a},
7063to make it easier for a reader to understand.@refill
7064
7065@code{@@ctrl} is an idea from the beginnings of Texinfo which may not
7066really fit in to the scheme of things. But there may be times when
7067you want to use the command. The pattern is
7068@code{@@ctrl@{@var{ch}@}}, where @var{ch} is an @sc{ascii} character
7069whose control-equivalent is wanted. For example, to specify
7070@samp{control-f}, you would enter@refill
7071
7072@example
7073@@ctrl@{f@}
7074@end example
7075
7076@noindent
7077produces
7078
7079@quotation
7080@ctrl{f}
7081@end quotation
7082
7083In the Info file, this generates the specified control character, output
7084literally into the file. This is done so a user can copy the specified
7085control character (along with whatever else he or she wants) into another
7086Emacs buffer and use it. Since the `control-h',`control-i', and
7087`control-j' characters are formatting characters, they should not be
7088indicated with @code{@@ctrl}.@refill
7089
7090In a printed manual, @code{@@ctrl} generates text to describe or
7091identify that control character: an uparrow followed by the character
7092@var{ch}.@refill
7093@end ignore
7094
7095
7096@node acronym
7097@subsection @code{@@acronym}@{@var{acronym}@}
7098@findex acronym
7099
7100@cindex NASA, as acronym
7101@cindex F.B.I., as acronym
7102@cindex Abbreviations, tagging
7103@cindex Acronyms, tagging
7104Use the @code{@@acronym} command for abbreviations written in all
7105capital letters, such as `@acronym{NASA}'. The abbreviation is given as
7106the single argument in braces, as in @samp{@@acronym@{NASA@}}. As
7107a matter of style, or for particular abbreviations, you may prefer to
7108use periods, as in @samp{@@acronym@{F.B.I.@}}.
7109
7110In @TeX{} and HTML, the argument is printed in a slightly smaller font
7111size. In Info or plain text output, this command changes nothing.
7112
7113
7114@node url
7115@subsection @code{@@url}@{@var{uniform-resource-locator}@}
7116@findex url
7117@cindex Uniform resource locator, indicating
7118@cindex URL, indicating
7119
7120Use the @code{@@url} command to indicate a uniform resource locator on
7121the World Wide Web. This is analogous to @code{@@file}, @code{@@var},
7122etc., and is purely for markup purposes. It does not produce a link you
7123can follow in HTML output (use the @code{@@uref} command for that,
7124@pxref{uref,, @code{@@uref}}). It is useful for url's which do
7125not actually exist. For example:
7126
7127@c Two lines because one is too long for smallbook format.
7128@example
7129For example, the url might be @@url@{http://example.org/path@}.
7130@end example
7131
7132@noindent which produces:
7133
7134@display
7135For example, the url might be @url{http://example.org/path}.
7136@end display
7137
7138
7139@node email
7140@subsection @code{@@email}@{@var{email-address}[, @var{displayed-text}]@}
7141@findex email
7142
7143Use the @code{@@email} command to indicate an electronic mail address.
7144It takes one mandatory argument, the address, and one optional argument, the
7145text to display (the default is the address itself).
7146
7147@cindex mailto link
7148In Info and @TeX{}, the address is shown in angle brackets, preceded by
7149the text to display if any. In HTML output, @code{@@email} produces a
7150@samp{mailto} link that usually brings up a mail composition window.
7151For example:
7152
7153@example
7154Send bug reports to @@email@{bug-texinfo@@@@gnu.org@},
7155suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}.
7156@end example
7157@noindent produces
7158@display
7159Send bug reports to @email{bug-texinfo@@gnu.org},
7160suggestions to the @email{bug-texinfo@@gnu.org, same place}.
7161@end display
7162
7163
7164@node Emphasis
7165@comment node-name, next, previous, up
7166@section Emphasizing Text
7167@cindex Emphasizing text
7168
7169Usually, Texinfo changes the font to mark words in the text according to
7170what category the words belong to; an example is the @code{@@code} command.
7171Most often, this is the best way to mark words.
7172However, sometimes you will want to emphasize text without indicating a
7173category. Texinfo has two commands to do this. Also, Texinfo has
7174several commands that specify the font in which @TeX{} will typeset
7175text. These commands have no effect on Info and only one of them,
7176the @code{@@r} command, has any regular use.@refill
7177
7178@menu
7179* emph & strong:: How to emphasize text in Texinfo.
7180* Smallcaps:: How to use the small caps font.
7181* Fonts:: Various font commands for printed output.
7182@end menu
7183
7184@node emph & strong
7185@subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@}
7186@cindex Emphasizing text, font for
7187@findex emph
7188@findex strong
7189
7190The @code{@@emph} and @code{@@strong} commands are for emphasis;
7191@code{@@strong} is stronger. In printed output, @code{@@emph} produces
7192@emph{italics} and @code{@@strong} produces @strong{bold}.
7193
7194@need 800
7195For example,
7196
7197@example
7198@group
7199@@quotation
7200@@strong@{Caution:@} @@samp@{rm * .[^.]*@} removes @@emph@{all@}
7201files in the directory.
7202@@end quotation
7203@end group
7204@end example
7205
7206@iftex
7207@noindent
7208produces the following in printed output:
7209
7210@quotation
7211@strong{Caution}: @samp{rm * .[^.]*} removes @emph{all}
7212files in the directory.
7213@end quotation
7214
7215@noindent
7216and the following in Info:
7217@end iftex
7218@ifinfo
7219@noindent
7220produces:
7221@end ifinfo
7222
7223@example
7224 *Caution*: `rm * .[^.]*' removes _all_
7225 files in the directory.
7226@end example
7227
7228The @code{@@strong} command is seldom used except to mark what is, in
7229effect, a typographical element, such as the word `Caution' in the
7230preceding example.
7231
7232In the Info output, @code{@@emph} surrounds the text with underscores
7233(@samp{_}), and @code{@@strong} puts asterisks around the text.
7234
7235@quotation
7236@strong{Caution:} Do not use @code{@@strong} with the word @samp{Note};
7237Info will mistake the combination for a cross reference. Use a phrase
7238such as @strong{Please note} or @strong{Caution} instead.
7239@end quotation
7240
7241
7242@node Smallcaps
7243@subsection @code{@@sc}@{@var{text}@}: The Small Caps Font
7244@cindex Small caps font
7245@findex sc @r{(small caps font)}
7246
7247Use the @samp{@@sc} command to set text in the printed and the HTML
7248output in @sc{a small caps font} and set text in the Info file in upper
7249case letters. Write the text you want to be in small caps (where
7250possible) between braces in lower case, like this:
7251
7252@example
7253The @@sc@{acm@} and @@sc@{ieee@} are technical societies.
7254@end example
7255
7256@noindent
7257This produces:
7258
7259@display
7260The @sc{acm} and @sc{ieee} are technical societies.
7261@end display
7262
7263@TeX{} typesets the small caps font in a manner that prevents the
7264letters from `jumping out at you on the page'. This makes small caps
7265text easier to read than text in all upper case---but it's usually
7266better to use regular mixed case anyway. The Info formatting commands
7267set all small caps text in upper case. In HTML, the text is upper-cased
7268and a smaller font is used to render it.
7269
7270If the text between the braces of an @code{@@sc} command is uppercase,
7271@TeX{} typesets in FULL-SIZE CAPITALS. Use full-size capitals
7272sparingly, if ever, and since it's redundant to mark all-uppercase text
7273with @code{@@sc}, @command{makeinfo} warns about such usage.
7274
7275You may also use the small caps font for a jargon word such as
7276@sc{ato} (a @sc{nasa} word meaning `abort to orbit').
7277
7278There are subtleties to using the small caps font with a jargon word
7279such as @sc{cdr}, a word used in Lisp programming. In this case, you
7280should use the small caps font when the word refers to the second and
7281subsequent elements of a list (the @sc{cdr} of the list), but you
7282should use @samp{@@code} when the word refers to the Lisp function of
7283the same spelling.
7284
7285
7286@node Fonts
7287@subsection Fonts for Printing, Not Info
7288@cindex Fonts for printing, not for Info
7289@findex i @r{(italic font)}
7290@findex b @r{(bold font)}
7291@findex t @r{(typewriter font)}
7292@findex r @r{(Roman font)}
7293
7294Texinfo provides four font commands that specify font changes in the
7295printed manual but have no effect in the Info file. @code{@@i}
7296requests @i{italic} font (in some versions of @TeX{}, a slanted font
7297is used), @code{@@b} requests @b{bold} face, @code{@@t} requests the
7298@t{fixed-width}, typewriter-style font used by @code{@@code}, and @code{@@r} requests a
7299@r{roman} font, which is the usual font in which text is printed. All
7300four commands apply to an argument that follows, surrounded by
7301braces.@refill
7302
7303Only the @code{@@r} command has much use: in example programs, you
7304can use the @code{@@r} command to convert code comments from the
7305fixed-width font to a roman font. This looks better in printed
7306output.@refill
7307
7308@need 700
7309For example,
7310
7311@example
7312@group
7313@@lisp
7314(+ 2 2) ; @@r@{Add two plus two.@}
7315@@end lisp
7316@end group
7317@end example
7318
7319@noindent
7320produces
7321
7322@lisp
7323(+ 2 2) ; @r{Add two plus two.}
7324@end lisp
7325
7326If possible, you should avoid using the other three font commands. If
7327you need to use one, it probably indicates a gap in the Texinfo
7328language.
7329
7330
7331@node Quotations and Examples
7332@chapter Quotations and Examples
7333
7334Quotations and examples are blocks of text consisting of one or more
7335whole paragraphs that are set off from the bulk of the text and
7336treated differently. They are usually indented.@refill
7337
7338In Texinfo, you always begin a quotation or example by writing an
7339@@-command at the beginning of a line by itself, and end it by writing
7340an @code{@@end} command that is also at the beginning of a line by
7341itself. For instance, you begin an example by writing @code{@@example}
7342by itself at the beginning of a line and end the example by writing
7343@code{@@end example} on a line by itself, at the beginning of that
7344line.
7345@findex end
7346
7347@menu
7348* Block Enclosing Commands:: Different constructs for different purposes.
7349* quotation:: Writing a quotation.
7350* example:: Writing an example in a fixed-width font.
7351* verbatim:: Writing a verbatim example.
| 6479* var:: Indicating metasyntactic variables.
6480* env:: Indicating environment variables.
6481* file:: Indicating file names.
6482* command:: Indicating command names.
6483* option:: Indicating option names.
6484* dfn:: Specifying definitions.
6485* cite:: Referring to books not in the Info system.
6486* acronym:: Indicating acronyms.
6487* url:: Indicating a World Wide Web reference.
6488* email:: Indicating an electronic mail address.
6489@end menu
6490
6491
6492@node Useful Highlighting, code, Indicating, Indicating
6493@ifinfo
6494@subheading Highlighting Commands are Useful
6495@end ifinfo
6496
6497The highlighting commands can be used to extract useful information
6498from the file, such as lists of functions or file names. It is
6499possible, for example, to write a program in Emacs Lisp (or a keyboard
6500macro) to insert an index entry after every paragraph that contains
6501words or phrases marked by a specified command. You could do this to
6502construct an index of functions if you had not already made the
6503entries.@refill
6504
6505The commands serve a variety of purposes:@refill
6506
6507@table @code
6508@item @@code@{@var{sample-code}@}
6509Indicate text that is a literal example of a piece of a program.@refill
6510
6511@item @@kbd@{@var{keyboard-characters}@}
6512Indicate keyboard input.@refill
6513
6514@item @@key@{@var{key-name}@}
6515Indicate the conventional name for a key on a keyboard.@refill
6516
6517@item @@samp@{@var{text}@}
6518Indicate text that is a literal example of a sequence of characters.@refill
6519
6520@item @@var@{@var{metasyntactic-variable}@}
6521Indicate a metasyntactic variable.@refill
6522
6523@item @@env@{@var{environment-variable}@}
6524Indicate an environment variable.@refill
6525
6526@item @@file@{@var{file-name}@}
6527Indicate the name of a file.@refill
6528
6529@item @@command@{@var{command-name}@}
6530Indicate the name of a command.@refill
6531
6532@item @@option@{@var{option}@}
6533Indicate a command-line option.@refill
6534
6535@item @@dfn@{@var{term}@}
6536Indicate the introductory or defining use of a term.@refill
6537
6538@item @@cite@{@var{reference}@}
6539Indicate the name of a book.@refill
6540
6541@item @@acronym@{@var{acronym}@}
6542Indicate an acronym.@refill
6543
6544@item @@url@{@var{uniform-resource-locator}@}
6545Indicate a uniform resource locator for the World Wide Web.
6546
6547@item @@email@{@var{email-address}[, @var{displayed-text}]@}
6548Indicate an electronic mail address.
6549
6550@ignore
6551@item @@ctrl@{@var{ctrl-char}@}
6552Use for an @sc{ascii} control character.@refill
6553@end ignore
6554@end table
6555
6556
6557@node code
6558@subsection @code{@@code}@{@var{sample-code}@}
6559@findex code
6560
6561@cindex Syntactic tokens, indicating
6562Use the @code{@@code} command to indicate text that is a piece of a
6563program and which consists of entire syntactic tokens. Enclose the
6564text in braces.
6565
6566@cindex Expressions in a program, indicating
6567@cindex Keywords, indicating
6568@cindex Reserved words, indicating
6569Thus, you should use @code{@@code} for an expression in a program, for
6570the name of a variable or function used in a program, or for a
6571keyword in a programming language.
6572
6573Use @code{@@code} for command names in languages that resemble
6574programming languages, such as Texinfo. For example, @code{@@code} and
6575@code{@@samp} are produced by writing @samp{@@code@{@@@@code@}} and
6576@samp{@@code@{@@@@samp@}} in the Texinfo source, respectively.
6577
6578@cindex Case, not altering in @code{@@code}
6579It is incorrect to alter the case of a word inside an @code{@@code}
6580command when it appears at the beginning of a sentence. Most computer
6581languages are case sensitive. In C, for example, @code{Printf} is
6582different from the identifier @code{printf}, and most likely is a
6583misspelling of it. Even in languages which are not case sensitive, it
6584is confusing to a human reader to see identifiers spelled in different
6585ways. Pick one spelling and always use that. If you do not want to
6586start a sentence with a command name written all in lower case, you
6587should rearrange the sentence.
6588
6589In the printed manual, @code{@@code} causes @TeX{} to typeset the
6590argument in a typewriter face. In the Info file, it causes the Info
6591formatting commands to use single quotation marks around the text.
6592
6593@need 700
6594For example,
6595
6596@example
6597The function returns @@code@{nil@}.
6598@end example
6599
6600@noindent
6601produces this in the printed manual:
6602
6603@quotation
6604The function returns @code{nil}.
6605@end quotation
6606
6607@iftex
6608@noindent
6609and this in the Info file:
6610@example
6611The function returns `nil'.
6612@end example
6613@end iftex
6614
6615Here are some cases for which it is preferable not to use @code{@@code}:
6616
6617@itemize @bullet
6618@item
6619For shell command names such as @command{ls} (use @code{@@command}).
6620
6621@item
6622For shell options such as @samp{-c} when such options stand alone (use
6623@code{@@option}).
6624
6625@item
6626Also, an entire shell command often looks better if written using
6627@code{@@samp} rather than @code{@@code}. In this case, the rule is to
6628choose the more pleasing format.
6629
6630@item
6631For environment variable such as @env{TEXINPUTS} (use @code{@@env}).
6632
6633@item
6634For a string of characters shorter than a syntactic token. For example,
6635if you are writing about @samp{goto-ch}, which is just a part of the
6636name for the @code{goto-char} Emacs Lisp function, you should use
6637@code{@@samp}.
6638
6639@item
6640In general, when writing about the characters used in a token; for
6641example, do not use @code{@@code} when you are explaining what letters
6642or printable symbols can be used in the names of functions. (Use
6643@code{@@samp}.) Also, you should not use @code{@@code} to mark text
6644that is considered input to programs unless the input is written in a
6645language that is like a programming language. For example, you should
6646not use @code{@@code} for the keystroke commands of GNU Emacs (use
6647@code{@@kbd} instead) although you may use @code{@@code} for the names
6648of the Emacs Lisp functions that the keystroke commands invoke.
6649
6650@end itemize
6651
6652Since @code{@@command}, @code{@@option}, and @code{@@env} were
6653introduced relatively recently, it is acceptable to use @code{@@code} or
6654@code{@@samp} for command names, options, and environment variables.
6655The new commands allow you to express the markup more precisely, but
6656there is no real harm in using the older commands, and of course the
6657long-standing manuals do so.
6658
6659
6660@node kbd
6661@subsection @code{@@kbd}@{@var{keyboard-characters}@}
6662@findex kbd
6663@cindex Keyboard input
6664
6665Use the @code{@@kbd} command for characters of input to be typed by
6666users. For example, to refer to the characters @kbd{M-a},
6667write@refill
6668
6669@example
6670@@kbd@{M-a@}
6671@end example
6672
6673@noindent
6674and to refer to the characters @kbd{M-x shell}, write@refill
6675
6676@example
6677@@kbd@{M-x shell@}
6678@end example
6679
6680@cindex user input
6681@cindex slanted typewriter font, for @code{@@kbd}
6682The @code{@@kbd} command has the same effect as @code{@@code} in Info,
6683but by default produces a different font (slanted typewriter instead of
6684normal typewriter) in the printed manual, so users can distinguish the
6685characters they are supposed to type from those the computer outputs.
6686
6687@findex kbdinputstyle
6688Since the usage of @code{@@kbd} varies from manual to manual, you can
6689control the font switching with the @code{@@kbdinputstyle} command.
6690This command has no effect on Info output. Write this command at the
6691beginning of a line with a single word as an argument, one of the
6692following:
6693@vindex distinct@r{, arg to @@kbdinputstyle}
6694@vindex example@r{, arg to @@kbdinputstyle}
6695@vindex code@r{, arg to @@kbdinputstyle}
6696@table @samp
6697@item code
6698Always use the same font for @code{@@kbd} as @code{@@code}.
6699@item example
6700Use the distinguishing font for @code{@@kbd} only in @code{@@example}
6701and similar environments.
6702@item distinct
6703(the default) Always use the distinguishing font for @code{@@kbd}.
6704@end table
6705
6706You can embed another @@-command inside the braces of an @code{@@kbd}
6707command. Here, for example, is the way to describe a command that
6708would be described more verbosely as ``press an @samp{r} and then
6709press the @key{RET} key'':@refill
6710
6711@example
6712@@kbd@{r @@key@{RET@}@}
6713@end example
6714
6715@noindent
6716This produces: @kbd{r @key{RET}}
6717
6718You also use the @code{@@kbd} command if you are spelling out the letters
6719you type; for example:@refill
6720
6721@example
6722To give the @@code@{logout@} command,
6723type the characters @@kbd@{l o g o u t @@key@{RET@}@}.
6724@end example
6725
6726@noindent
6727This produces:
6728
6729@quotation
6730To give the @code{logout} command,
6731type the characters @kbd{l o g o u t @key{RET}}.
6732@end quotation
6733
6734(Also, this example shows that you can add spaces for clarity. If you
6735really want to mention a space character as one of the characters of
6736input, write @kbd{@@key@{SPC@}} for it.)@refill
6737
6738
6739@node key, samp, kbd, Indicating
6740@comment node-name, next, previous, up
6741@subsection @code{@@key}@{@var{key-name}@}
6742@findex key
6743
6744Use the @code{@@key} command for the conventional name for a key on a
6745keyboard, as in:@refill
6746
6747@example
6748@@key@{RET@}
6749@end example
6750
6751You can use the @code{@@key} command within the argument of an
6752@code{@@kbd} command when the sequence of characters to be typed
6753includes one or more keys that are described by name.@refill
6754
6755@need 700
6756For example, to produce @kbd{C-x @key{ESC}} you would type:@refill
6757
6758@example
6759@@kbd@{C-x @@key@{ESC@}@}
6760@end example
6761
6762Here is a list of the recommended names for keys:
6763@cindex Recommended names for keys
6764@cindex Keys, recommended names
6765@cindex Names recommended for keys
6766@cindex Abbreviations for keys
6767
6768@quotation
6769@table @t
6770@item SPC
6771Space
6772@item RET
6773Return
6774@item LFD
6775Linefeed (however, since most keyboards nowadays do not have a Linefeed key,
6776it might be better to call this character @kbd{C-j}.
6777@item TAB
6778Tab
6779@item BS
6780Backspace
6781@item ESC
6782Escape
6783@item DEL
6784Delete
6785@item SHIFT
6786Shift
6787@item CTRL
6788Control
6789@item META
6790Meta
6791@end table
6792@end quotation
6793
6794@cindex META key
6795There are subtleties to handling words like `meta' or `ctrl' that are
6796names of modifier keys. When mentioning a character in which the
6797modifier key is used, such as @kbd{Meta-a}, use the @code{@@kbd} command
6798alone; do not use the @code{@@key} command; but when you are referring
6799to the modifier key in isolation, use the @code{@@key} command. For
6800example, write @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and
6801@samp{@@key@{META@}} to produce @key{META}.
6802
6803@c I don't think this is a good explanation.
6804@c I think it will puzzle readers more than it clarifies matters. -- rms.
6805@c In other words, use @code{@@kbd} for what you do, and use @code{@@key}
6806@c for what you talk about: ``Press @code{@@kbd@{M-a@}} to move point to
6807@c the beginning of the sentence. The @code{@@key@{META@}} key is often in
6808@c the lower left of the keyboard.''@refill
6809
6810@node samp
6811@subsection @code{@@samp}@{@var{text}@}
6812@findex samp
6813
6814Use the @code{@@samp} command to indicate text that is a literal example
6815or `sample' of a sequence of characters in a file, string, pattern, etc.
6816Enclose the text in braces. The argument appears within single
6817quotation marks in both the Info file and the printed manual; in
6818addition, it is printed in a fixed-width font.@refill
6819
6820@example
6821To match @@samp@{foo@} at the end of the line,
6822use the regexp @@samp@{foo$@}.
6823@end example
6824
6825@noindent
6826produces
6827
6828@quotation
6829To match @samp{foo} at the end of the line, use the regexp
6830@samp{foo$}.@refill
6831@end quotation
6832
6833Any time you are referring to single characters, you should use
6834@code{@@samp} unless @code{@@kbd} or @code{@@key} is more appropriate.
6835Also, you may use @code{@@samp} for entire statements in C and for entire
6836shell commands---in this case, @code{@@samp} often looks better than
6837@code{@@code}. Basically, @code{@@samp} is a catchall for whatever is
6838not covered by @code{@@code}, @code{@@kbd}, or @code{@@key}.@refill
6839
6840Only include punctuation marks within braces if they are part of the
6841string you are specifying. Write punctuation marks outside the braces
6842if those punctuation marks are part of the English text that surrounds
6843the string. In the following sentence, for example, the commas and
6844period are outside of the braces:@refill
6845
6846@example
6847@group
6848In English, the vowels are @@samp@{a@}, @@samp@{e@},
6849@@samp@{i@}, @@samp@{o@}, @@samp@{u@}, and sometimes
6850@@samp@{y@}.
6851@end group
6852@end example
6853
6854@noindent
6855This produces:
6856
6857@quotation
6858In English, the vowels are @samp{a}, @samp{e},
6859@samp{i}, @samp{o}, @samp{u}, and sometimes
6860@samp{y}.
6861@end quotation
6862
6863
6864@node verb
6865@subsection @code{@@verb}@{<char>@var{text}<char>@}
6866@findex verb
6867@cindex Verbatim in-line text
6868
6869@cindex Delimiter character, for verbatim
6870Use the @code{@@verb} command to print a verbatim sequence of
6871characters.
6872
6873Like La@TeX{}'s @code{\verb} command, the verbatim text can be quoted using
6874any unique delimiter character. Enclose the verbatim text, including the
6875delimiters, in braces. Text is printed in a fixed-width font:
6876
6877@example
6878How many @@verb@{|@@|@}-escapes does one need to print this
6879@@verb@{.@@a @@b @@c.@} string or @@verb@{+@@'e@?`@!`@{@}\+@} this?
6880@end example
6881
6882@noindent
6883produces
6884
6885@example
6886How many @verb{|@|}-escapes does one need to print this
6887@verb{.@a @b @c.} string or these @verb{+@'e?`{}!`\+} this?
6888@end example
6889
6890This is in contrast to @code{@@samp} (see the previous
6891section), whose argument is normal Texinfo text, where the characters
6892@code{@@@{@}} are special; with @code{@@verb}, nothing is special except
6893the delimiter character you choose.
6894
6895
6896@node var
6897@subsection @code{@@var}@{@var{metasyntactic-variable}@}
6898@findex var
6899
6900Use the @code{@@var} command to indicate metasyntactic variables. A
6901@dfn{metasyntactic variable} is something that stands for another piece of
6902text. For example, you should use a metasyntactic variable in the
6903documentation of a function to describe the arguments that are passed
6904to that function.@refill
6905
6906Do not use @code{@@var} for the names of particular variables in
6907programming languages. These are specific names from a program, so
6908@code{@@code} is correct for them (@pxref{code}). For example, the
6909Emacs Lisp variable @code{texinfo-tex-command} is not a metasyntactic
6910variable; it is properly formatted using @code{@@code}.
6911
6912Do not use @code{@@var} for environment variables either; @code{@@env}
6913is correct for them (see the next section).
6914
6915The effect of @code{@@var} in the Info file is to change the case of the
6916argument to all upper case. In the printed manual and HTML output, the
6917argument is printed in slanted type.
6918
6919@need 700
6920For example,
6921
6922@example
6923To delete file @@var@{filename@},
6924type @@samp@{rm @@var@{filename@}@}.
6925@end example
6926
6927@noindent
6928produces
6929
6930@quotation
6931To delete file @var{filename}, type @samp{rm @var{filename}}.
6932@end quotation
6933
6934@noindent
6935(Note that @code{@@var} may appear inside @code{@@code},
6936@code{@@samp}, @code{@@file}, etc.)@refill
6937
6938Write a metasyntactic variable all in lower case without spaces, and
6939use hyphens to make it more readable. Thus, the Texinfo source for
6940the illustration of how to begin a Texinfo manual looks like
6941this:@refill
6942
6943@example
6944@group
6945\input texinfo
6946@@@@setfilename @@var@{info-file-name@}
6947@@@@settitle @@var@{name-of-manual@}
6948@end group
6949@end example
6950
6951@noindent
6952This produces:
6953
6954@example
6955@group
6956\input texinfo
6957@@setfilename @var{info-file-name}
6958@@settitle @var{name-of-manual}
6959@end group
6960@end example
6961
6962In some documentation styles, metasyntactic variables are shown with
6963angle brackets, for example:@refill
6964
6965@example
6966@dots{}, type rm <filename>
6967@end example
6968
6969@noindent
6970However, that is not the style that Texinfo uses. (You can, of
6971course, modify the sources to @file{texinfo.tex} and the Info formatting commands
6972to output the @code{<@dots{}>} format if you wish.)@refill
6973
6974
6975@node env
6976@subsection @code{@@env}@{@var{environment-variable}@}
6977@findex env
6978
6979Use the @code{@@env} command to indicate environment variables, as used
6980by many operating systems, including GNU. Do not use it for
6981metasyntactic variables; use @code{@@var} instead (see the previous
6982section).
6983
6984@code{@@env} is equivalent to @code{@@code} in its effects.
6985For example:
6986
6987@example
6988The @@env@{PATH@} environment variable @dots{}
6989@end example
6990@noindent produces
6991@quotation
6992The @env{PATH} environment variable @dots{}
6993@end quotation
6994
6995
6996@node file
6997@subsection @code{@@file}@{@var{file-name}@}
6998@findex file
6999
7000Use the @code{@@file} command to indicate text that is the name of a
7001file, buffer, or directory, or is the name of a node in Info. You can
7002also use the command for file name suffixes. Do not use @code{@@file}
7003for symbols in a programming language; use @code{@@code}.
7004
7005Currently, @code{@@file} is equivalent to @code{@@samp} in its effects.
7006For example,@refill
7007
7008@example
7009The @@file@{.el@} files are in
7010the @@file@{/usr/local/emacs/lisp@} directory.
7011@end example
7012
7013@noindent
7014produces
7015
7016@quotation
7017The @file{.el} files are in
7018the @file{/usr/local/emacs/lisp} directory.
7019@end quotation
7020
7021
7022@node command
7023@subsection @code{@@command}@{@var{command-name}@}
7024@findex command
7025@cindex Command names, indicating
7026@cindex Program names, indicating
7027
7028Use the @code{@@command} command to indicate command names, such as
7029@command{ls} or @command{cc}.
7030
7031@code{@@command} is equivalent to @code{@@code} in its effects.
7032For example:
7033
7034@example
7035The command @@command@{ls@} lists directory contents.
7036@end example
7037@noindent produces
7038@quotation
7039The command @command{ls} lists directory contents.
7040@end quotation
7041
7042You should write the name of a program in the ordinary text font, rather
7043than using @code{@@command}, if you regard it as a new English word,
7044such as `Emacs' or `Bison'.
7045
7046When writing an entire shell command invocation, as in @samp{ls -l},
7047you should use either @code{@@samp} or @code{@@code} at your discretion.
7048
7049
7050@node option
7051@subsection @code{@@option}@{@var{option-name}@}
7052@findex option
7053
7054Use the @code{@@option} command to indicate a command-line option; for
7055example, @option{-l} or @option{--version} or
7056@option{--output=@var{filename}}.
7057
7058@code{@@option} is equivalent to @code{@@samp} in its effects.
7059For example:
7060
7061@example
7062The option @@option@{-l@} produces a long listing.
7063@end example
7064@noindent produces
7065@quotation
7066The option @option{-l} produces a long listing.
7067@end quotation
7068
7069In tables, putting options inside @code{@@code} produces a
7070more pleasing effect.
7071
7072@node dfn
7073@comment node-name, next, previous, up
7074@subsection @code{@@dfn}@{@var{term}@}
7075@findex dfn
7076
7077Use the @code{@@dfn} command to identify the introductory or defining
7078use of a technical term. Use the command only in passages whose
7079purpose is to introduce a term which will be used again or which the
7080reader ought to know. Mere passing mention of a term for the first
7081time does not deserve @code{@@dfn}. The command generates italics in
7082the printed manual, and double quotation marks in the Info file. For
7083example:@refill
7084
7085@example
7086Getting rid of a file is called @@dfn@{deleting@} it.
7087@end example
7088
7089@noindent
7090produces
7091
7092@quotation
7093Getting rid of a file is called @dfn{deleting} it.
7094@end quotation
7095
7096As a general rule, a sentence containing the defining occurrence of a
7097term should be a definition of the term. The sentence does not need
7098to say explicitly that it is a definition, but it should contain the
7099information of a definition---it should make the meaning clear.
7100
7101@node cite
7102@subsection @code{@@cite}@{@var{reference}@}
7103@findex cite
7104
7105Use the @code{@@cite} command for the name of a book that lacks a
7106companion Info file. The command produces italics in the printed
7107manual, and quotation marks in the Info file.
7108
7109If a book is written in Texinfo, it is better to use a cross reference
7110command since a reader can easily follow such a reference in Info.
7111@xref{xref, , @code{@@xref}}.
7112
7113
7114@ignore
7115@c node ctrl, , cite, Indicating
7116@comment node-name, next, previous, up
7117@c subsection @code{@@ctrl}@{@var{ctrl-char}@}
7118@findex ctrl
7119
7120The @code{@@ctrl} command is seldom used. It describes an @sc{ascii}
7121control character by inserting the actual character into the Info
7122file.
7123
7124Usually, in Texinfo, you talk what you type as keyboard entry by
7125describing it with @code{@@kbd}: thus, @samp{@@kbd@{C-a@}} for
7126@kbd{C-a}. Use @code{@@kbd} in this way when talking about a control
7127character that is typed on the keyboard by the user. When talking
7128about a control character appearing in a file or a string, do not use
7129@code{@@kbd} since the control character is not typed. Also, do not
7130use @samp{C-} but spell out @code{control-}, as in @samp{control-a},
7131to make it easier for a reader to understand.@refill
7132
7133@code{@@ctrl} is an idea from the beginnings of Texinfo which may not
7134really fit in to the scheme of things. But there may be times when
7135you want to use the command. The pattern is
7136@code{@@ctrl@{@var{ch}@}}, where @var{ch} is an @sc{ascii} character
7137whose control-equivalent is wanted. For example, to specify
7138@samp{control-f}, you would enter@refill
7139
7140@example
7141@@ctrl@{f@}
7142@end example
7143
7144@noindent
7145produces
7146
7147@quotation
7148@ctrl{f}
7149@end quotation
7150
7151In the Info file, this generates the specified control character, output
7152literally into the file. This is done so a user can copy the specified
7153control character (along with whatever else he or she wants) into another
7154Emacs buffer and use it. Since the `control-h',`control-i', and
7155`control-j' characters are formatting characters, they should not be
7156indicated with @code{@@ctrl}.@refill
7157
7158In a printed manual, @code{@@ctrl} generates text to describe or
7159identify that control character: an uparrow followed by the character
7160@var{ch}.@refill
7161@end ignore
7162
7163
7164@node acronym
7165@subsection @code{@@acronym}@{@var{acronym}@}
7166@findex acronym
7167
7168@cindex NASA, as acronym
7169@cindex F.B.I., as acronym
7170@cindex Abbreviations, tagging
7171@cindex Acronyms, tagging
7172Use the @code{@@acronym} command for abbreviations written in all
7173capital letters, such as `@acronym{NASA}'. The abbreviation is given as
7174the single argument in braces, as in @samp{@@acronym@{NASA@}}. As
7175a matter of style, or for particular abbreviations, you may prefer to
7176use periods, as in @samp{@@acronym@{F.B.I.@}}.
7177
7178In @TeX{} and HTML, the argument is printed in a slightly smaller font
7179size. In Info or plain text output, this command changes nothing.
7180
7181
7182@node url
7183@subsection @code{@@url}@{@var{uniform-resource-locator}@}
7184@findex url
7185@cindex Uniform resource locator, indicating
7186@cindex URL, indicating
7187
7188Use the @code{@@url} command to indicate a uniform resource locator on
7189the World Wide Web. This is analogous to @code{@@file}, @code{@@var},
7190etc., and is purely for markup purposes. It does not produce a link you
7191can follow in HTML output (use the @code{@@uref} command for that,
7192@pxref{uref,, @code{@@uref}}). It is useful for url's which do
7193not actually exist. For example:
7194
7195@c Two lines because one is too long for smallbook format.
7196@example
7197For example, the url might be @@url@{http://example.org/path@}.
7198@end example
7199
7200@noindent which produces:
7201
7202@display
7203For example, the url might be @url{http://example.org/path}.
7204@end display
7205
7206
7207@node email
7208@subsection @code{@@email}@{@var{email-address}[, @var{displayed-text}]@}
7209@findex email
7210
7211Use the @code{@@email} command to indicate an electronic mail address.
7212It takes one mandatory argument, the address, and one optional argument, the
7213text to display (the default is the address itself).
7214
7215@cindex mailto link
7216In Info and @TeX{}, the address is shown in angle brackets, preceded by
7217the text to display if any. In HTML output, @code{@@email} produces a
7218@samp{mailto} link that usually brings up a mail composition window.
7219For example:
7220
7221@example
7222Send bug reports to @@email@{bug-texinfo@@@@gnu.org@},
7223suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}.
7224@end example
7225@noindent produces
7226@display
7227Send bug reports to @email{bug-texinfo@@gnu.org},
7228suggestions to the @email{bug-texinfo@@gnu.org, same place}.
7229@end display
7230
7231
7232@node Emphasis
7233@comment node-name, next, previous, up
7234@section Emphasizing Text
7235@cindex Emphasizing text
7236
7237Usually, Texinfo changes the font to mark words in the text according to
7238what category the words belong to; an example is the @code{@@code} command.
7239Most often, this is the best way to mark words.
7240However, sometimes you will want to emphasize text without indicating a
7241category. Texinfo has two commands to do this. Also, Texinfo has
7242several commands that specify the font in which @TeX{} will typeset
7243text. These commands have no effect on Info and only one of them,
7244the @code{@@r} command, has any regular use.@refill
7245
7246@menu
7247* emph & strong:: How to emphasize text in Texinfo.
7248* Smallcaps:: How to use the small caps font.
7249* Fonts:: Various font commands for printed output.
7250@end menu
7251
7252@node emph & strong
7253@subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@}
7254@cindex Emphasizing text, font for
7255@findex emph
7256@findex strong
7257
7258The @code{@@emph} and @code{@@strong} commands are for emphasis;
7259@code{@@strong} is stronger. In printed output, @code{@@emph} produces
7260@emph{italics} and @code{@@strong} produces @strong{bold}.
7261
7262@need 800
7263For example,
7264
7265@example
7266@group
7267@@quotation
7268@@strong@{Caution:@} @@samp@{rm * .[^.]*@} removes @@emph@{all@}
7269files in the directory.
7270@@end quotation
7271@end group
7272@end example
7273
7274@iftex
7275@noindent
7276produces the following in printed output:
7277
7278@quotation
7279@strong{Caution}: @samp{rm * .[^.]*} removes @emph{all}
7280files in the directory.
7281@end quotation
7282
7283@noindent
7284and the following in Info:
7285@end iftex
7286@ifinfo
7287@noindent
7288produces:
7289@end ifinfo
7290
7291@example
7292 *Caution*: `rm * .[^.]*' removes _all_
7293 files in the directory.
7294@end example
7295
7296The @code{@@strong} command is seldom used except to mark what is, in
7297effect, a typographical element, such as the word `Caution' in the
7298preceding example.
7299
7300In the Info output, @code{@@emph} surrounds the text with underscores
7301(@samp{_}), and @code{@@strong} puts asterisks around the text.
7302
7303@quotation
7304@strong{Caution:} Do not use @code{@@strong} with the word @samp{Note};
7305Info will mistake the combination for a cross reference. Use a phrase
7306such as @strong{Please note} or @strong{Caution} instead.
7307@end quotation
7308
7309
7310@node Smallcaps
7311@subsection @code{@@sc}@{@var{text}@}: The Small Caps Font
7312@cindex Small caps font
7313@findex sc @r{(small caps font)}
7314
7315Use the @samp{@@sc} command to set text in the printed and the HTML
7316output in @sc{a small caps font} and set text in the Info file in upper
7317case letters. Write the text you want to be in small caps (where
7318possible) between braces in lower case, like this:
7319
7320@example
7321The @@sc@{acm@} and @@sc@{ieee@} are technical societies.
7322@end example
7323
7324@noindent
7325This produces:
7326
7327@display
7328The @sc{acm} and @sc{ieee} are technical societies.
7329@end display
7330
7331@TeX{} typesets the small caps font in a manner that prevents the
7332letters from `jumping out at you on the page'. This makes small caps
7333text easier to read than text in all upper case---but it's usually
7334better to use regular mixed case anyway. The Info formatting commands
7335set all small caps text in upper case. In HTML, the text is upper-cased
7336and a smaller font is used to render it.
7337
7338If the text between the braces of an @code{@@sc} command is uppercase,
7339@TeX{} typesets in FULL-SIZE CAPITALS. Use full-size capitals
7340sparingly, if ever, and since it's redundant to mark all-uppercase text
7341with @code{@@sc}, @command{makeinfo} warns about such usage.
7342
7343You may also use the small caps font for a jargon word such as
7344@sc{ato} (a @sc{nasa} word meaning `abort to orbit').
7345
7346There are subtleties to using the small caps font with a jargon word
7347such as @sc{cdr}, a word used in Lisp programming. In this case, you
7348should use the small caps font when the word refers to the second and
7349subsequent elements of a list (the @sc{cdr} of the list), but you
7350should use @samp{@@code} when the word refers to the Lisp function of
7351the same spelling.
7352
7353
7354@node Fonts
7355@subsection Fonts for Printing, Not Info
7356@cindex Fonts for printing, not for Info
7357@findex i @r{(italic font)}
7358@findex b @r{(bold font)}
7359@findex t @r{(typewriter font)}
7360@findex r @r{(Roman font)}
7361
7362Texinfo provides four font commands that specify font changes in the
7363printed manual but have no effect in the Info file. @code{@@i}
7364requests @i{italic} font (in some versions of @TeX{}, a slanted font
7365is used), @code{@@b} requests @b{bold} face, @code{@@t} requests the
7366@t{fixed-width}, typewriter-style font used by @code{@@code}, and @code{@@r} requests a
7367@r{roman} font, which is the usual font in which text is printed. All
7368four commands apply to an argument that follows, surrounded by
7369braces.@refill
7370
7371Only the @code{@@r} command has much use: in example programs, you
7372can use the @code{@@r} command to convert code comments from the
7373fixed-width font to a roman font. This looks better in printed
7374output.@refill
7375
7376@need 700
7377For example,
7378
7379@example
7380@group
7381@@lisp
7382(+ 2 2) ; @@r@{Add two plus two.@}
7383@@end lisp
7384@end group
7385@end example
7386
7387@noindent
7388produces
7389
7390@lisp
7391(+ 2 2) ; @r{Add two plus two.}
7392@end lisp
7393
7394If possible, you should avoid using the other three font commands. If
7395you need to use one, it probably indicates a gap in the Texinfo
7396language.
7397
7398
7399@node Quotations and Examples
7400@chapter Quotations and Examples
7401
7402Quotations and examples are blocks of text consisting of one or more
7403whole paragraphs that are set off from the bulk of the text and
7404treated differently. They are usually indented.@refill
7405
7406In Texinfo, you always begin a quotation or example by writing an
7407@@-command at the beginning of a line by itself, and end it by writing
7408an @code{@@end} command that is also at the beginning of a line by
7409itself. For instance, you begin an example by writing @code{@@example}
7410by itself at the beginning of a line and end the example by writing
7411@code{@@end example} on a line by itself, at the beginning of that
7412line.
7413@findex end
7414
7415@menu
7416* Block Enclosing Commands:: Different constructs for different purposes.
7417* quotation:: Writing a quotation.
7418* example:: Writing an example in a fixed-width font.
7419* verbatim:: Writing a verbatim example.
|
7352* verbatiminclude:: Including a file verbatim.
| 7420* verbatiminclude:: Including a file verbatim.
|
7353* lisp:: Illustrating Lisp code.
7354* small:: Forms for @code{@@smallbook}.
7355* display:: Writing an example in the current font.
7356* format:: Writing an example without narrowed margins.
7357* exdent:: Undo indentation on a line.
7358* flushleft & flushright:: Pushing text flush left or flush right.
7359* noindent:: Preventing paragraph indentation.
7360* cartouche:: Drawing rounded rectangles around examples.
7361@end menu
7362
7363
7364@node Block Enclosing Commands
7365@section Block Enclosing Commands
7366
7367Here are commands for quotations and examples, explained further in the
7368following sections:
7369
7370@table @code
7371@item @@quotation
7372Indicate text that is quoted. The text is filled, indented, and
7373printed in a roman font by default.
7374
7375@item @@example
7376Illustrate code, commands, and the like. The text is printed
7377in a fixed-width font, and indented but not filled.
7378
7379@item @@verbatim
7380Mark a piece of text that is to be printed verbatim; no character
7381substitutions are made and all commands are ignored, until the next
7382@code{@@end verbatim}. The text is printed in a fixed-width font,
7383and not indented or filled. Extra spaces and blank lines are
7384significant, and tabs are expanded.
7385
7386@item @@smallexample
7387Same as @code{@@example}, except that in @TeX{} this command typesets
7388text in a smaller font.
7389
7390@item @@lisp
7391Like @code{@@example}, but specifically for illustrating Lisp code. The
7392text is printed in a fixed-width font, and indented but not filled.
7393
7394@item @@smalllisp
7395Is to @code{@@lisp} as @code{@@smallexample} is to @code{@@example}.
7396
7397@item @@display
7398Display illustrative text. The text is indented but not filled, and
7399no font is selected (so, by default, the font is roman).@refill
7400
7401@item @@smalldisplay
7402Is to @code{@@display} as @code{@@smallexample} is to @code{@@example}.
7403
7404@item @@format
7405Like @code{@@display} (the text is not filled and no font is selected),
7406but the text is not indented.
7407
7408@item @@smallformat
7409Is to @code{@@format} as @code{@@smallexample} is to @code{@@example}.
7410@end table
7411
7412The @code{@@exdent} command is used within the above constructs to
7413undo the indentation of a line.
7414
7415The @code{@@flushleft} and @code{@@flushright} commands are used to line
7416up the left or right margins of unfilled text.@refill
7417
7418The @code{@@noindent} command may be used after one of the above
7419constructs to prevent the following text from being indented as a new
7420paragraph.
7421
7422You can use the @code{@@cartouche} command within one of the above
7423constructs to highlight the example or quotation by drawing a box with
7424rounded corners around it. @xref{cartouche, , Drawing Cartouches Around
7425Examples}.
7426
7427
7428@node quotation
7429@section @code{@@quotation}
7430@cindex Quotations
7431@findex quotation
7432
7433The text of a quotation is processed normally except that:
7434
7435@itemize @bullet
7436@item
7437the margins are closer to the center of the page, so the whole of the
7438quotation is indented;@refill
7439
7440@item
7441the first lines of paragraphs are indented no more than other
7442lines;@refill
7443
7444@item
7445in the printed output, interparagraph spacing is reduced.@refill
7446@end itemize
7447
7448@quotation
7449This is an example of text written between an @code{@@quotation}
7450command and an @code{@@end quotation} command. An @code{@@quotation}
7451command is most often used to indicate text that is excerpted from
7452another (real or hypothetical) printed work.@refill
7453@end quotation
7454
7455Write an @code{@@quotation} command as text on a line by itself. This
7456line will disappear from the output. Mark the end of the quotation
7457with a line beginning with and containing only @code{@@end quotation}.
7458The @code{@@end quotation} line will likewise disappear from the
7459output. Thus, the following,@refill
7460
7461@example
7462@@quotation
7463This is
7464a foo.
7465@@end quotation
7466@end example
7467
7468@noindent
7469produces
7470
7471@quotation
7472This is a foo.
7473@end quotation
7474
7475
7476@node example
7477@section @code{@@example}: Example Text
7478@cindex Examples, formatting them
7479@cindex Formatting examples
7480@findex example
7481
7482The @code{@@example} command is used to indicate an example that is
7483not part of the running text, such as computer input or output.
7484
7485@example
7486@group
7487This is an example of text written between an
7488@code{@@example} command
7489and an @code{@@end example} command.
7490The text is indented but not filled.
7491@end group
7492
7493@group
7494In the printed manual, the text is typeset in a
7495fixed-width font, and extra spaces and blank lines are
7496significant. In the Info file, an analogous result is
7497obtained by indenting each line with five spaces.
7498@end group
7499@end example
7500
7501Write an @code{@@example} command at the beginning of a line by itself.
7502Mark the end of the example
7503with an @code{@@end example} command, also written at the beginning of a
7504line by itself.@refill
7505
7506@need 700
7507For example,
7508
7509@example
7510@@example
7511mv foo bar
7512@@end example
7513@end example
7514
7515@noindent
7516produces
7517
7518@example
7519mv foo bar
7520@end example
7521
7522The lines containing @code{@@example} and @code{@@end example}
7523will disappear from the output.
7524To make the output look good,
7525you should put a blank line before the
7526@code{@@example} and another blank line after the @code{@@end example}.
7527Note that blank lines inside the beginning
7528@code{@@example} and the ending @code{@@end example} will appear in
7529the output.@refill
7530
7531@quotation
7532@strong{Caution:} Do not use tabs in the lines of an example or anywhere
7533else in Texinfo (except in verbatim environments)! The @TeX{}
7534implementation of Texinfo treats tabs as single spaces, and that is not
7535what they look like. (If necessary, in Emacs, you can use @kbd{M-x
7536untabify} to convert tabs in a region to multiple spaces.)@refill
7537@end quotation
7538
7539Examples are often, logically speaking, ``in the middle'' of a
7540paragraph, and the text that continues after an example should not be
7541indented. The @code{@@noindent} command prevents a piece of text from
7542being indented as if it were a new paragraph.
7543@ifinfo
7544(@xref{noindent}.)
7545@end ifinfo
7546
7547(The @code{@@code} command is used for examples of code that are
7548embedded within sentences, not set off from preceding and following
7549text. @xref{code, , @code{@@code}}.)
7550
7551
7552@node verbatim
7553@section @code{@@verbatim}: Literal Text
7554@findex verbatim
7555@cindex Verbatim environment
7556
7557Use the @code{@@verbatim} environment for printing of text that may
7558contain special characters or commands that should not be interpreted,
7559such as computer input or output (@code{@@example} interprets its text
7560as regular Texinfo commands). This is especially useful for including
7561automatically generated output in a Texinfo manual. Here is an example;
7562the output you see is just the same as the input, with a line
7563@code{@@verbatim} before and a line @code{@@end verbatim} after.
7564
7565@verbatim
7566This is an example of text written in a @verbatim
| 7421* lisp:: Illustrating Lisp code.
7422* small:: Forms for @code{@@smallbook}.
7423* display:: Writing an example in the current font.
7424* format:: Writing an example without narrowed margins.
7425* exdent:: Undo indentation on a line.
7426* flushleft & flushright:: Pushing text flush left or flush right.
7427* noindent:: Preventing paragraph indentation.
7428* cartouche:: Drawing rounded rectangles around examples.
7429@end menu
7430
7431
7432@node Block Enclosing Commands
7433@section Block Enclosing Commands
7434
7435Here are commands for quotations and examples, explained further in the
7436following sections:
7437
7438@table @code
7439@item @@quotation
7440Indicate text that is quoted. The text is filled, indented, and
7441printed in a roman font by default.
7442
7443@item @@example
7444Illustrate code, commands, and the like. The text is printed
7445in a fixed-width font, and indented but not filled.
7446
7447@item @@verbatim
7448Mark a piece of text that is to be printed verbatim; no character
7449substitutions are made and all commands are ignored, until the next
7450@code{@@end verbatim}. The text is printed in a fixed-width font,
7451and not indented or filled. Extra spaces and blank lines are
7452significant, and tabs are expanded.
7453
7454@item @@smallexample
7455Same as @code{@@example}, except that in @TeX{} this command typesets
7456text in a smaller font.
7457
7458@item @@lisp
7459Like @code{@@example}, but specifically for illustrating Lisp code. The
7460text is printed in a fixed-width font, and indented but not filled.
7461
7462@item @@smalllisp
7463Is to @code{@@lisp} as @code{@@smallexample} is to @code{@@example}.
7464
7465@item @@display
7466Display illustrative text. The text is indented but not filled, and
7467no font is selected (so, by default, the font is roman).@refill
7468
7469@item @@smalldisplay
7470Is to @code{@@display} as @code{@@smallexample} is to @code{@@example}.
7471
7472@item @@format
7473Like @code{@@display} (the text is not filled and no font is selected),
7474but the text is not indented.
7475
7476@item @@smallformat
7477Is to @code{@@format} as @code{@@smallexample} is to @code{@@example}.
7478@end table
7479
7480The @code{@@exdent} command is used within the above constructs to
7481undo the indentation of a line.
7482
7483The @code{@@flushleft} and @code{@@flushright} commands are used to line
7484up the left or right margins of unfilled text.@refill
7485
7486The @code{@@noindent} command may be used after one of the above
7487constructs to prevent the following text from being indented as a new
7488paragraph.
7489
7490You can use the @code{@@cartouche} command within one of the above
7491constructs to highlight the example or quotation by drawing a box with
7492rounded corners around it. @xref{cartouche, , Drawing Cartouches Around
7493Examples}.
7494
7495
7496@node quotation
7497@section @code{@@quotation}
7498@cindex Quotations
7499@findex quotation
7500
7501The text of a quotation is processed normally except that:
7502
7503@itemize @bullet
7504@item
7505the margins are closer to the center of the page, so the whole of the
7506quotation is indented;@refill
7507
7508@item
7509the first lines of paragraphs are indented no more than other
7510lines;@refill
7511
7512@item
7513in the printed output, interparagraph spacing is reduced.@refill
7514@end itemize
7515
7516@quotation
7517This is an example of text written between an @code{@@quotation}
7518command and an @code{@@end quotation} command. An @code{@@quotation}
7519command is most often used to indicate text that is excerpted from
7520another (real or hypothetical) printed work.@refill
7521@end quotation
7522
7523Write an @code{@@quotation} command as text on a line by itself. This
7524line will disappear from the output. Mark the end of the quotation
7525with a line beginning with and containing only @code{@@end quotation}.
7526The @code{@@end quotation} line will likewise disappear from the
7527output. Thus, the following,@refill
7528
7529@example
7530@@quotation
7531This is
7532a foo.
7533@@end quotation
7534@end example
7535
7536@noindent
7537produces
7538
7539@quotation
7540This is a foo.
7541@end quotation
7542
7543
7544@node example
7545@section @code{@@example}: Example Text
7546@cindex Examples, formatting them
7547@cindex Formatting examples
7548@findex example
7549
7550The @code{@@example} command is used to indicate an example that is
7551not part of the running text, such as computer input or output.
7552
7553@example
7554@group
7555This is an example of text written between an
7556@code{@@example} command
7557and an @code{@@end example} command.
7558The text is indented but not filled.
7559@end group
7560
7561@group
7562In the printed manual, the text is typeset in a
7563fixed-width font, and extra spaces and blank lines are
7564significant. In the Info file, an analogous result is
7565obtained by indenting each line with five spaces.
7566@end group
7567@end example
7568
7569Write an @code{@@example} command at the beginning of a line by itself.
7570Mark the end of the example
7571with an @code{@@end example} command, also written at the beginning of a
7572line by itself.@refill
7573
7574@need 700
7575For example,
7576
7577@example
7578@@example
7579mv foo bar
7580@@end example
7581@end example
7582
7583@noindent
7584produces
7585
7586@example
7587mv foo bar
7588@end example
7589
7590The lines containing @code{@@example} and @code{@@end example}
7591will disappear from the output.
7592To make the output look good,
7593you should put a blank line before the
7594@code{@@example} and another blank line after the @code{@@end example}.
7595Note that blank lines inside the beginning
7596@code{@@example} and the ending @code{@@end example} will appear in
7597the output.@refill
7598
7599@quotation
7600@strong{Caution:} Do not use tabs in the lines of an example or anywhere
7601else in Texinfo (except in verbatim environments)! The @TeX{}
7602implementation of Texinfo treats tabs as single spaces, and that is not
7603what they look like. (If necessary, in Emacs, you can use @kbd{M-x
7604untabify} to convert tabs in a region to multiple spaces.)@refill
7605@end quotation
7606
7607Examples are often, logically speaking, ``in the middle'' of a
7608paragraph, and the text that continues after an example should not be
7609indented. The @code{@@noindent} command prevents a piece of text from
7610being indented as if it were a new paragraph.
7611@ifinfo
7612(@xref{noindent}.)
7613@end ifinfo
7614
7615(The @code{@@code} command is used for examples of code that are
7616embedded within sentences, not set off from preceding and following
7617text. @xref{code, , @code{@@code}}.)
7618
7619
7620@node verbatim
7621@section @code{@@verbatim}: Literal Text
7622@findex verbatim
7623@cindex Verbatim environment
7624
7625Use the @code{@@verbatim} environment for printing of text that may
7626contain special characters or commands that should not be interpreted,
7627such as computer input or output (@code{@@example} interprets its text
7628as regular Texinfo commands). This is especially useful for including
7629automatically generated output in a Texinfo manual. Here is an example;
7630the output you see is just the same as the input, with a line
7631@code{@@verbatim} before and a line @code{@@end verbatim} after.
7632
7633@verbatim
7634This is an example of text written in a @verbatim
|
7567block. No character substitutions are made all commands
7568are ignored, until the next 'end verbatim' command.
| 7635block. No character substitutions are made. All commands
7636are ignored, until `<at>end verbatim'.
|
7569
7570In the printed manual, the text is typeset in a
7571fixed-width font, and not indented or filled. All
7572spaces and blank lines are significant, including tabs.
7573@end verbatim
7574
7575Write a @code{@@verbatim} command at the beginning of a line by itself.
7576This line will disappear from the output. Mark the end of the verbatim
7577block with a @code{@@end verbatim} command, also written at the
7578beginning of a line by itself. The @code{@@end verbatim} will also
7579disappear from the output.
7580
7581For example:
| 7637
7638In the printed manual, the text is typeset in a
7639fixed-width font, and not indented or filled. All
7640spaces and blank lines are significant, including tabs.
7641@end verbatim
7642
7643Write a @code{@@verbatim} command at the beginning of a line by itself.
7644This line will disappear from the output. Mark the end of the verbatim
7645block with a @code{@@end verbatim} command, also written at the
7646beginning of a line by itself. The @code{@@end verbatim} will also
7647disappear from the output.
7648
7649For example:
|
7582@c urg: got to trick this a bit: can't use @end verbatim inside @verbatim
| 7650@c oops, got to trick this a bit: can't use @end verbatim inside @verbatim
|
7583
7584@example
7585@exdent @@verbatim
7586@exdent @{
7587@exdent <tab>@@command with strange characters: @@'e
7588@exdent expand<tab>me
7589@exdent @}
7590@exdent @@end verbatim
7591@end example
7592
7593@noindent
7594produces
7595
7596@verbatim
7597{
7598 @command with strange characters: @'e
7599expand me
7600}
7601@end verbatim
7602
7603Since the lines containing @code{@@verbatim} and @code{@@end verbatim}
| 7651
7652@example
7653@exdent @@verbatim
7654@exdent @{
7655@exdent <tab>@@command with strange characters: @@'e
7656@exdent expand<tab>me
7657@exdent @}
7658@exdent @@end verbatim
7659@end example
7660
7661@noindent
7662produces
7663
7664@verbatim
7665{
7666 @command with strange characters: @'e
7667expand me
7668}
7669@end verbatim
7670
7671Since the lines containing @code{@@verbatim} and @code{@@end verbatim}
|
7604will disappear, tyically you should put a blank line before the
| 7672produce no output, tyically you should put a blank line before the
|
7605@code{@@verbatim} and another blank line after the @code{@@end
7606verbatim}. Blank lines between the beginning @code{@@verbatim} and the
| 7673@code{@@verbatim} and another blank line after the @code{@@end
7674verbatim}. Blank lines between the beginning @code{@@verbatim} and the
|
7607ending @code{@@end verbatim} will appear in the output.)
| 7675ending @code{@@end verbatim} will appear in the output.
|
7608
7609
7610@node verbatiminclude
7611@section @code{@@verbatiminclude} @var{file}: Include a File Verbatim
7612@cindex Verbatim, include file
7613@cindex Including a file verbatim
7614@findex verbatiminclude
7615
7616You can include the exact contents of a file in the document with the
7617@code{@@verbatiminclude} command:
7618
7619@example
7620@@verbatiminclude @var{filename}
7621@end example
7622
7623The contents of @var{filename} is printed in a verbatim environment
7624(@pxref{verbatim,,@code{@@verbatim}}). Generally, the file is printed
7625exactly as it is, with all special characters and white space retained.
7626
7627
7628@node lisp
7629@section @code{@@lisp}: Marking a Lisp Example
7630@findex lisp
7631@cindex Lisp example
7632
7633The @code{@@lisp} command is used for Lisp code. It is synonymous
7634with the @code{@@example} command.
7635
7636@lisp
7637This is an example of text written between an
7638@code{@@lisp} command and an @code{@@end lisp} command.
7639@end lisp
7640
7641Use @code{@@lisp} instead of @code{@@example} to preserve information
7642regarding the nature of the example. This is useful, for example, if
7643you write a function that evaluates only and all the Lisp code in a
7644Texinfo file. Then you can use the Texinfo file as a Lisp
7645library.@footnote{It would be straightforward to extend Texinfo to work
7646in a similar fashion for C, Fortran, or other languages.}
7647
7648Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by
7649itself.@refill
7650
7651
7652@node small
7653@section @code{@@small@dots{}} Block Commands
7654@cindex Small examples
7655@cindex Examples in smaller fonts
7656@cindex Lisp examples in smaller fonts
7657@findex smalldisplay
7658@findex smallexample
7659@findex smallformat
7660@findex smalllisp
7661
7662In addition to the regular @code{@@example} and @code{@@lisp} commands,
7663Texinfo has ``small'' example-style commands. These are
7664@code{@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat}, and
7665@code{@@smalllisp}.
7666
7667In @TeX{}, the @code{@@small@dots{}} commands typeset text in a smaller
7668font than the non-small example commands. Consequently, many examples
7669containing long lines fit on a page without needing to be shortened.
7670
7671In Info, the @code{@@small@dots{}} commands are equivalent to their
7672non-small companion commands.
7673
7674Mark the end of an @code{@@small@dots{}} block with a corresponding
7675@code{@@end small@dots{}}. For example, pair @code{@@smallexample} with
7676@code{@@end smallexample}.
7677
7678@iftex
7679Here is an example written in the small font used by the
7680@code{@@smallexample} and @code{@@smalllisp} commands:
7681
7682@ifclear smallbook
7683@display
7684@tex
7685% Remove extra vskip; this is a kludge to counter the effect of display
7686\vskip-3\baselineskip
7687{\smalltt
7688\dots{} to make sure that you have the freedom to
7689distribute copies of free software (and charge for
7690this service if you wish), that you receive source
7691code or can get it if you want it, that you can
7692change the software or use pieces of it in new free
7693programs; and that you know you can do these things.}
7694@end tex
7695@end display
7696@end ifclear
7697@end iftex
7698@ifset smallbook
7699@iftex
7700@smallexample
7701This is an example of text written between @code{@@smallexample} and
7702@code{@@end smallexample}. In Info this text appears in its normal size;
7703but in printed manuals, this text appears in a smaller font.
7704@end smallexample
7705@end iftex
7706@end ifset
7707@ifinfo
7708@smallexample
7709This is an example of text written between @code{@@smallexample} and
7710@code{@@end smallexample}. In Info this text appears in its normal size;
7711but in a 7 by 9.25 inch manual, this text appears in a smaller font.
7712@end smallexample
7713@end ifinfo
7714
7715The @code{@@small@dots{}} commands make it easier to prepare manuals
7716without forcing you to edit examples by hand to fit them onto narrower
7717pages.
7718
7719As a general rule, a printed document looks better if you use only one
7720of (for example) @code{@@example} or in @code{@@smallexample}
7721consistently within a chapter. Only occasionally should you mix the two
7722formats.
7723
7724@xref{smallbook, , Printing ``Small'' Books}, for more information
7725about the @code{@@smallbook} command.
7726
7727
7728@node display
7729@section @code{@@display} and @code{@@smalldisplay}
7730@cindex Display formatting
7731@findex display
7732
7733The @code{@@display} command begins a kind of example. It is like the
7734@code{@@example} command
7735except that, in
7736a printed manual, @code{@@display} does not select the fixed-width
7737font. In fact, it does not specify the font at all, so that the text
7738appears in the same font it would have appeared in without the
7739@code{@@display} command.@refill
7740
7741@display
7742This is an example of text written between an @code{@@display} command
7743and an @code{@@end display} command. The @code{@@display} command
7744indents the text, but does not fill it.
7745@end display
7746
7747@findex smalldisplay
7748Texinfo also provides a command @code{@@smalldisplay}, which is like
7749@code{@@display} but uses a smaller font in @code{@@smallbook} format.
7750@xref{small}.
7751
7752
7753@node format
7754@section @code{@@format} and @code{@@smallformat}
7755@findex format
7756
7757The @code{@@format} command is similar to @code{@@example} except
7758that, in the printed manual, @code{@@format} does not select the
7759fixed-width font and does not narrow the margins.@refill
7760
7761@format
7762This is an example of text written between an @code{@@format} command
7763and an @code{@@end format} command. As you can see
7764from this example,
7765the @code{@@format} command does not fill the text.
7766@end format
7767
7768@findex smallformat
7769Texinfo also provides a command @code{@@smallformat}, which is like
7770@code{@@format} but uses a smaller font in @code{@@smallbook} format.
7771@xref{small}.
7772
7773
7774
7775@node exdent
7776@section @code{@@exdent}: Undoing a Line's Indentation
7777@cindex Indentation undoing
7778@findex exdent
7779
7780The @code{@@exdent} command removes any indentation a line might have.
7781The command is written at the beginning of a line and applies only to
7782the text that follows the command that is on the same line. Do not use
7783braces around the text. In a printed manual, the text on an
7784@code{@@exdent} line is printed in the roman font.@refill
7785
7786@code{@@exdent} is usually used within examples. Thus,@refill
7787
7788@example
7789@group
7790@@example
7791This line follows an @@@@example command.
7792@@exdent This line is exdented.
7793This line follows the exdented line.
7794The @@@@end example comes on the next line.
7795@@end group
7796@end group
7797@end example
7798
7799@noindent
7800produces
7801
7802@example
7803@group
7804This line follows an @@example command.
7805@exdent This line is exdented.
7806This line follows the exdented line.
7807The @@end example comes on the next line.
7808@end group
7809@end example
7810
7811In practice, the @code{@@exdent} command is rarely used.
7812Usually, you un-indent text by ending the example and
7813returning the page to its normal width.@refill
7814
7815
7816@node flushleft & flushright
7817@section @code{@@flushleft} and @code{@@flushright}
7818@findex flushleft
7819@findex flushright
7820@cindex ragged right
7821@cindex ragged left
7822
7823The @code{@@flushleft} and @code{@@flushright} commands line up the
7824ends of lines on the left and right margins of a page,
7825but do not fill the text. The commands are written on lines of their
7826own, without braces. The @code{@@flushleft} and @code{@@flushright}
7827commands are ended by @code{@@end flushleft} and @code{@@end
7828flushright} commands on lines of their own.@refill
7829
7830@need 1500
7831For example,
7832
7833@example
7834@group
7835@@flushleft
7836This text is
7837written flushleft.
7838@@end flushleft
7839@end group
7840@end example
7841
7842@noindent
7843produces
7844
7845@quotation
7846@flushleft
7847This text is
7848written flushleft.
7849@end flushleft
7850@end quotation
7851
7852
7853@code{@@flushright} produces the type of indentation often used in the
7854return address of letters. For example,
7855
7856@example
7857@group
7858@@flushright
7859Here is an example of text written
7860flushright. The @@code@{@@flushright@} command
7861right justifies every line but leaves the
7862left end ragged.
7863@@end flushright
7864@end group
7865@end example
7866
7867@noindent
7868produces
7869
7870@flushright
7871Here is an example of text written
7872flushright. The @code{@@flushright} command
7873right justifies every line but leaves the
7874left end ragged.
7875@end flushright
7876
7877
7878@node noindent
7879@section @code{@@noindent}: Omitting Indentation
7880@findex noindent
7881
7882An example or other inclusion can break a paragraph into segments.
7883Ordinarily, the formatters indent text that follows an example as a new
7884paragraph. However, you can prevent this by writing @code{@@noindent}
7885at the beginning of a line by itself preceding the continuation
7886text.@refill
7887
7888@need 1500
7889For example:
7890
7891@example
7892@group
7893@@example
7894This is an example
7895@@end example
7896
7897@@noindent
7898This line is not indented. As you can see, the
7899beginning of the line is fully flush left with the line
7900that follows after it. (This whole example is between
7901@@code@{@@@@display@} and @@code@{@@@@end display@}.)
7902@end group
7903@end example
7904
7905@noindent
7906produces
7907
7908@display
7909@example
7910This is an example
7911@end example
7912@tex
7913% Remove extra vskip; this is a kludge to counter the effect of display
7914\vskip-3.5\baselineskip
7915@end tex
7916
7917@noindent
7918This line is not indented. As you can see, the
7919beginning of the line is fully flush left with the line
7920that follows after it. (This whole example is between
7921@code{@@display} and @code{@@end display}.)
7922@end display
7923
7924To adjust the number of blank lines properly in the Info file output,
7925remember that the line containing @code{@@noindent} does not generate a
7926blank line, and neither does the @code{@@end example} line.@refill
7927
7928In the Texinfo source file for this manual, each line that says
7929`produces' is preceded by a line containing @code{@@noindent}.@refill
7930
7931Do not put braces after an @code{@@noindent} command; they are not
7932necessary, since @code{@@noindent} is a command used outside of
7933paragraphs (@pxref{Command Syntax}).@refill
7934
7935
7936@node cartouche
7937@section @code{@@cartouche}: Rounded Rectangles Around Examples
7938@findex cartouche
7939@cindex Box with rounded corners
7940@cindex Rounded rectangles, around examples
7941
7942In a printed manual, the @code{@@cartouche} command draws a box with
7943rounded corners around its contents. You can use this command to
7944further highlight an example or quotation. For instance, you could
7945write a manual in which one type of example is surrounded by a cartouche
7946for emphasis.
7947
7948@code{@@cartouche} affects only the printed manual; it has no effect in
7949other output files.
7950
7951@need 1500
7952For example,
7953
7954@example
7955@group
7956@@example
7957@@cartouche
7958% pwd
7959/usr/local/share/emacs
7960@@end cartouche
7961@@end example
7962@end group
7963@end example
7964
7965@noindent
7966surrounds the two-line example with a box with rounded corners, in the
7967printed manual.
7968
7969@iftex
7970In a printed manual, the example looks like this:@refill
7971
7972@example
7973@group
7974@cartouche
7975% pwd
7976/usr/local/lib/emacs/info
7977@end cartouche
7978@end group
7979@end example
7980@end iftex
7981
7982
7983@node Lists and Tables
7984@chapter Lists and Tables
7985@cindex Making lists and tables
7986@cindex Lists and tables, making
7987@cindex Tables and lists, making
7988
7989Texinfo has several ways of making lists and tables. Lists can be
7990bulleted or numbered; two-column tables can highlight the items in
7991the first column; multi-column tables are also supported.
7992
7993@menu
7994* Introducing Lists:: Texinfo formats lists for you.
7995* itemize:: How to construct a simple list.
7996* enumerate:: How to construct a numbered list.
7997* Two-column Tables:: How to construct a two-column table.
7998* Multi-column Tables:: How to construct generalized tables.
7999@end menu
8000
8001@node Introducing Lists, itemize, Lists and Tables, Lists and Tables
8002@ifinfo
8003@heading Introducing Lists
8004@end ifinfo
8005
8006Texinfo automatically indents the text in lists or tables, and numbers
8007an enumerated list. This last feature is useful if you modify the
8008list, since you do not need to renumber it yourself.@refill
8009
8010Numbered lists and tables begin with the appropriate @@-command at the
8011beginning of a line, and end with the corresponding @code{@@end}
8012command on a line by itself. The table and itemized-list commands
8013also require that you write formatting information on the same line as
8014the beginning @@-command.@refill
8015
8016Begin an enumerated list, for example, with an @code{@@enumerate}
8017command and end the list with an @code{@@end enumerate} command.
8018Begin an itemized list with an @code{@@itemize} command, followed on
8019the same line by a formatting command such as @code{@@bullet}, and end
8020the list with an @code{@@end itemize} command.@refill
8021@findex end
8022
8023Precede each element of a list with an @code{@@item} or @code{@@itemx}
8024command.@refill
8025
8026@sp 1
8027@noindent
8028Here is an itemized list of the different kinds of table and lists:@refill
8029
8030@itemize @bullet
8031@item
8032Itemized lists with and without bullets.
8033
8034@item
8035Enumerated lists, using numbers or letters.
8036
8037@item
8038Two-column tables with highlighting.
8039@end itemize
8040
8041@sp 1
8042@noindent
8043Here is an enumerated list with the same items:@refill
8044
8045@enumerate
8046@item
8047Itemized lists with and without bullets.
8048
8049@item
8050Enumerated lists, using numbers or letters.
8051
8052@item
8053Two-column tables with highlighting.
8054@end enumerate
8055
8056@sp 1
8057@noindent
8058And here is a two-column table with the same items and their
8059@w{@@-commands}:@refill
8060
8061@table @code
8062@item @@itemize
8063Itemized lists with and without bullets.
8064
8065@item @@enumerate
8066Enumerated lists, using numbers or letters.
8067
8068@item @@table
8069@itemx @@ftable
8070@itemx @@vtable
8071Two-column tables, optionally with indexing.
8072@end table
8073
8074
8075@node itemize
8076@section @code{@@itemize}: Making an Itemized List
8077@cindex Itemization
8078@findex itemize
8079
8080The @code{@@itemize} command produces sequences of indented
8081paragraphs, with a bullet or other mark inside the left margin
8082at the beginning of each paragraph for which such a mark is desired.@refill
8083
8084@cindex @code{@@w}, for blank items
8085Begin an itemized list by writing @code{@@itemize} at the beginning of
8086a line. Follow the command, on the same line, with a character or a
8087Texinfo command that generates a mark. Usually, you will write
8088@code{@@bullet} after @code{@@itemize}, but you can use
8089@code{@@minus}, or any command or character that results in a single
8090character in the Info file. If you don't want any mark at all, use
8091@code{@@w}. (When you write the mark command such as
8092@code{@@bullet} after an @code{@@itemize} command, you may omit the
8093@samp{@{@}}.) If you don't specify a mark command, the default is
8094@code{@@bullet}.
8095
8096Write the text of the indented paragraphs themselves after the
8097@code{@@itemize}, up to another line that says @code{@@end
8098itemize}.@refill
8099
8100@findex item
8101Before each paragraph for which a mark in the margin is desired, write a
8102line that says just @code{@@item}. It is ok to have text following the
8103@code{@@item}.
8104
8105Usually, you should put a blank line before an @code{@@item}. This
8106puts a blank line in the Info file. (@TeX{} inserts the proper
8107interline whitespace in either case.) Except when the entries are
8108very brief, these blank lines make the list look better.@refill
8109
8110Here is an example of the use of @code{@@itemize}, followed by the
8111output it produces. @code{@@bullet} produces an @samp{*} in Info and a
8112round dot in @TeX{}.
8113
8114@example
8115@group
8116@@itemize @@bullet
8117@@item
8118Some text for foo.
8119
8120@@item
8121Some text
8122for bar.
8123@@end itemize
8124@end group
8125@end example
8126
8127@noindent
8128This produces:
8129
8130@quotation
8131@itemize @bullet
8132@item
8133Some text for foo.
8134
8135@item
8136Some text
8137for bar.
8138@end itemize
8139@end quotation
8140
8141Itemized lists may be embedded within other itemized lists. Here is a
8142list marked with dashes embedded in a list marked with bullets:@refill
8143
8144@example
8145@group
8146@@itemize @@bullet
8147@@item
8148First item.
8149
8150@@itemize @@minus
8151@@item
8152Inner item.
8153
8154@@item
8155Second inner item.
8156@@end itemize
8157
8158@@item
8159Second outer item.
8160@@end itemize
8161@end group
8162@end example
8163
8164@noindent
8165This produces:
8166
8167@quotation
8168@itemize @bullet
8169@item
8170First item.
8171
8172@itemize @minus
8173@item
8174Inner item.
8175
8176@item
8177Second inner item.
8178@end itemize
8179
8180@item
8181Second outer item.
8182@end itemize
8183@end quotation
8184
8185
8186@node enumerate
8187@section @code{@@enumerate}: Making a Numbered or Lettered List
8188@cindex Enumeration
8189@findex enumerate
8190
8191@code{@@enumerate} is like @code{@@itemize} (@pxref{itemize,,
8192@code{@@itemize}}), except that the labels on the items are
8193successive integers or letters instead of bullets.
8194
8195Write the @code{@@enumerate} command at the beginning of a line. The
8196command does not require an argument, but accepts either a number or a
8197letter as an option. Without an argument, @code{@@enumerate} starts the
8198list with the number @samp{1}. With a numeric argument, such as
8199@samp{3}, the command starts the list with that number. With an upper
8200or lower case letter, such as @samp{a} or @samp{A}, the command starts
8201the list with that letter.
8202
8203Write the text of the enumerated list in the same way you write an
8204itemized list: put @code{@@item} on a line of its own before the start
8205of each paragraph that you want enumerated. Do not write any other text
8206on the line beginning with @code{@@item}.
8207
8208You should put a blank line between entries in the list.
8209This generally makes it easier to read the Info file.
8210
8211@need 1500
8212Here is an example of @code{@@enumerate} without an argument:
8213
8214@example
8215@group
8216@@enumerate
8217@@item
8218Underlying causes.
8219
8220@@item
8221Proximate causes.
8222@@end enumerate
8223@end group
8224@end example
8225
8226@noindent
8227This produces:
8228
8229@enumerate
8230@item
8231Underlying causes.
8232
8233@item
8234Proximate causes.
8235@end enumerate
8236@sp 1
8237Here is an example with an argument of @kbd{3}:@refill
8238@sp 1
8239@example
8240@group
8241@@enumerate 3
8242@@item
8243Predisposing causes.
8244
8245@@item
8246Precipitating causes.
8247
8248@@item
8249Perpetuating causes.
8250@@end enumerate
8251@end group
8252@end example
8253
8254@noindent
8255This produces:
8256
8257@enumerate 3
8258@item
8259Predisposing causes.
8260
8261@item
8262Precipitating causes.
8263
8264@item
8265Perpetuating causes.
8266@end enumerate
8267@sp 1
8268Here is a brief summary of the alternatives. The summary is constructed
8269using @code{@@enumerate} with an argument of @kbd{a}.@refill
8270@sp 1
8271@enumerate a
8272@item
8273@code{@@enumerate}
8274
8275Without an argument, produce a numbered list, starting with the number
82761.@refill
8277
8278@item
8279@code{@@enumerate @var{positive-integer}}
8280
8281With a (positive) numeric argument, start a numbered list with that
8282number. You can use this to continue a list that you interrupted with
8283other text.@refill
8284
8285@item
8286@code{@@enumerate @var{upper-case-letter}}
8287
8288With an upper case letter as argument, start a list
8289in which each item is marked
8290by a letter, beginning with that upper case letter.@refill
8291
8292@item
8293@code{@@enumerate @var{lower-case-letter}}
8294
8295With a lower case letter as argument, start a list
8296in which each item is marked by
8297a letter, beginning with that lower case letter.@refill
8298@end enumerate
8299
8300You can also nest enumerated lists, as in an outline.@refill
8301
8302@node Two-column Tables, Multi-column Tables, enumerate, Lists and Tables
8303@section Making a Two-column Table
8304@cindex Tables, making two-column
8305@findex table
8306
8307@code{@@table} is similar to @code{@@itemize} (@pxref{itemize,,
8308@code{@@itemize}}), but allows you to specify a name or heading line for
8309each item. The @code{@@table} command is used to produce two-column
8310tables, and is especially useful for glossaries, explanatory
8311exhibits, and command-line option summaries.
8312
8313@menu
8314* table:: How to construct a two-column table.
8315* ftable vtable:: Automatic indexing for two-column tables.
8316* itemx:: How to put more entries in the first column.
8317@end menu
8318
8319@node table, ftable vtable, Two-column Tables, Two-column Tables
8320@ifinfo
8321@subheading Using the @code{@@table} Command
8322
8323Use the @code{@@table} command to produce two-column tables.@refill
8324@end ifinfo
8325
8326Write the @code{@@table} command at the beginning of a line and follow
8327it on the same line with an argument that is a Texinfo ``indicating''
8328command such as @code{@@code}, @code{@@samp}, @code{@@var}, or
8329@code{@@kbd} (@pxref{Indicating}). Although these commands are usually
8330followed by arguments in braces, in this case you use the command name
8331without an argument because @code{@@item} will supply the argument.
8332This command will be applied to the text that goes into the first column
8333of each item and determines how it will be highlighted. For example,
8334@code{@@code} will cause the text in the first column to be highlighted
8335with an @code{@@code} command. (We recommend @code{@@code} for
8336@code{@@table}'s of command-line options.)
8337
8338@findex asis
8339You may also choose to use the @code{@@asis} command as an argument to
8340@code{@@table}. @code{@@asis} is a command that does nothing; if you
8341use this command after @code{@@table}, @TeX{} and the Info formatting
8342commands output the first column entries without added highlighting
8343(``as is'').@refill
8344
8345(The @code{@@table} command may work with other commands besides those
8346listed here. However, you can only use commands that normally take
8347arguments in braces.)@refill
8348
8349@findex item
8350Begin each table entry with an @code{@@item} command at the beginning
8351of a line. Write the first column text on the same line as the
8352@code{@@item} command. Write the second column text on the line
8353following the @code{@@item} line and on subsequent lines. (You do not
8354need to type anything for an empty second column entry.) You may
8355write as many lines of supporting text as you wish, even several
8356paragraphs. But only text on the same line as the @code{@@item} will
8357be placed in the first column, including any footnote.
8358
8359Normally, you should put a blank line before an @code{@@item} line.
8360This puts a blank like in the Info file. Except when the entries are
8361very brief, a blank line looks better.@refill
8362
8363@need 1500
8364The following table, for example, highlights the text in the first
8365column with an @code{@@samp} command:@refill
8366
8367@example
8368@group
8369@@table @@samp
8370@@item foo
8371This is the text for
8372@@samp@{foo@}.
8373
8374@@item bar
8375Text for @@samp@{bar@}.
8376@@end table
8377@end group
8378@end example
8379
8380@noindent
8381This produces:
8382
8383@table @samp
8384@item foo
8385This is the text for
8386@samp{foo}.
8387@item bar
8388Text for @samp{bar}.
8389@end table
8390
8391If you want to list two or more named items with a single block of
8392text, use the @code{@@itemx} command. (@xref{itemx, ,
8393@code{@@itemx}}.)@refill
8394
8395
8396@node ftable vtable
8397@subsection @code{@@ftable} and @code{@@vtable}
8398@cindex Tables with indexes
8399@cindex Indexing table entries automatically
8400@findex ftable
8401@findex vtable
8402
8403The @code{@@ftable} and @code{@@vtable} commands are the same as the
8404@code{@@table} command except that @code{@@ftable} automatically enters
8405each of the items in the first column of the table into the index of
8406functions and @code{@@vtable} automatically enters each of the items in
8407the first column of the table into the index of variables. This
8408simplifies the task of creating indices. Only the items on the same
8409line as the @code{@@item} commands are indexed, and they are indexed in
8410exactly the form that they appear on that line. @xref{Indices},
8411for more information about indices.@refill
8412
8413Begin a two-column table using @code{@@ftable} or @code{@@vtable} by
8414writing the @@-command at the beginning of a line, followed on the same
8415line by an argument that is a Texinfo command such as @code{@@code},
8416exactly as you would for an @code{@@table} command; and end the table
8417with an @code{@@end ftable} or @code{@@end vtable} command on a line by
8418itself.
8419
8420See the example for @code{@@table} in the previous section.
8421
8422@node itemx
8423@subsection @code{@@itemx}
8424@cindex Two named items for @code{@@table}
8425@findex itemx
8426
8427Use the @code{@@itemx} command inside a table when you have two or more
8428first column entries for the same item, each of which should appear on a
8429line of its own. Use @code{@@itemx} for all but the first entry;
8430@code{@@itemx} should always follow an @code{@@item} command. The
8431@code{@@itemx} command works exactly like @code{@@item} except that it
8432does not generate extra vertical space above the first column text.
8433
8434For example,
8435
8436@example
8437@group
8438@@table @@code
8439@@item upcase
8440@@itemx downcase
8441These two functions accept a character or a string as
8442argument, and return the corresponding upper case (lower
8443case) character or string.
8444@@end table
8445@end group
8446@end example
8447
8448@noindent
8449This produces:
8450
8451@table @code
8452@item upcase
8453@itemx downcase
8454These two functions accept a character or a string as
8455argument, and return the corresponding upper case (lower
8456case) character or string.@refill
8457@end table
8458
8459@noindent
8460(Note also that this example illustrates multi-line supporting text in
8461a two-column table.)@refill
8462
8463
8464@node Multi-column Tables, , Two-column Tables, Lists and Tables
8465@section Multi-column Tables
8466@cindex Tables, making multi-column
8467@findex multitable
8468
8469@code{@@multitable} allows you to construct tables with any number of
8470columns, with each column having any width you like.
8471
8472You define the column widths on the @code{@@multitable} line itself, and
8473write each row of the actual table following an @code{@@item} command,
8474with columns separated by an @code{@@tab} command. Finally, @code{@@end
8475multitable} completes the table. Details in the sections below.
8476
8477@menu
8478* Multitable Column Widths:: Defining multitable column widths.
8479* Multitable Rows:: Defining multitable rows, with examples.
8480@end menu
8481
8482@node Multitable Column Widths
8483@subsection Multitable Column Widths
8484@cindex Multitable column widths
8485@cindex Column widths, defining for multitables
8486@cindex Widths, defining multitable column
8487
8488You can define the column widths for a multitable in two ways: as
8489fractions of the line length; or with a prototype row. Mixing the two
8490methods is not supported. In either case, the widths are defined
8491entirely on the same line as the @code{@@multitable} command.
8492
8493@enumerate
8494@item
8495@findex columnfractions
8496@cindex Line length, column widths as fraction of
8497To specify column widths as fractions of the line length, write
8498@code{@@columnfractions} and the decimal numbers (presumably less than
84991) after the @code{@@multitable} command, as in:
8500
8501@example
8502@@multitable @@columnfractions .33 .33 .33
8503@end example
8504
8505@noindent The fractions need not add up exactly to 1.0, as these do
8506not. This allows you to produce tables that do not need the full line
8507length. You can use a leading zero if you wish.
8508
8509@item
8510@cindex Prototype row, column widths defined by
8511To specify a prototype row, write the longest entry for each column
8512enclosed in braces after the @code{@@multitable} command. For example:
8513
8514@example
8515@@multitable @{some text for column one@} @{for column two@}
8516@end example
8517
8518@noindent
8519The first column will then have the width of the typeset `some text for
8520column one', and the second column the width of `for column two'.
8521
8522The prototype entries need not appear in the table itself.
8523
8524Although we used simple text in this example, the prototype entries can
8525contain Texinfo commands; markup commands such as @code{@@code} are
8526particularly likely to be useful.
8527
8528@end enumerate
8529
8530
8531@node Multitable Rows, , Multitable Column Widths, Multi-column Tables
8532@subsection Multitable Rows
8533@cindex Multitable rows
8534@cindex Rows, of a multitable
8535
8536@findex item
8537@findex tab
8538After the @code{@@multitable} command defining the column widths (see
8539the previous section), you begin each row in the body of a multitable
8540with @code{@@item}, and separate the column entries with @code{@@tab}.
8541Line breaks are not special within the table body, and you may break
8542input lines in your source file as necessary.
8543
8544Here is a complete example of a multi-column table (the text is from
8545@cite{The GNU Emacs Manual}, @pxref{Split Window,, Splitting Windows,
8546emacs, The GNU Emacs Manual}):
8547
8548@example
8549@@multitable @@columnfractions .15 .45 .4
8550@@item Key @@tab Command @@tab Description
8551@@item C-x 2
8552@@tab @@code@{split-window-vertically@}
8553@@tab Split the selected window into two windows,
8554with one above the other.
8555@@item C-x 3
8556@@tab @@code@{split-window-horizontally@}
8557@@tab Split the selected window into two windows
8558positioned side by side.
8559@@item C-Mouse-2
8560@@tab
8561@@tab In the mode line or scroll bar of a window,
8562split that window.
8563@@end multitable
8564@end example
8565
8566@noindent produces:
8567
8568@multitable @columnfractions .15 .45 .4
8569@item Key @tab Command @tab Description
8570@item C-x 2
8571@tab @code{split-window-vertically}
8572@tab Split the selected window into two windows,
8573with one above the other.
8574@item C-x 3
8575@tab @code{split-window-horizontally}
8576@tab Split the selected window into two windows
8577positioned side by side.
8578@item C-Mouse-2
8579@tab
8580@tab In the mode line or scroll bar of a window,
8581split that window.
8582@end multitable
8583
8584
8585@node Indices, Insertions, Lists and Tables, Top
8586@comment node-name, next, previous, up
8587@chapter Indices
8588@cindex Indices
8589
8590Using Texinfo, you can generate indices without having to sort and
8591collate entries manually. In an index, the entries are listed in
8592alphabetical order, together with information on how to find the
8593discussion of each entry. In a printed manual, this information
8594consists of page numbers. In an Info file, this information is a menu
8595entry leading to the first node referenced.@refill
8596
8597Texinfo provides several predefined kinds of index: an index
8598for functions, an index for variables, an index for concepts, and so
8599on. You can combine indices or use them for other than their
8600canonical purpose. If you wish, you can define your own indices.@refill
8601
8602@menu
8603* Index Entries:: Choose different words for index entries.
8604* Predefined Indices:: Use different indices for different kinds
8605 of entry.
8606* Indexing Commands:: How to make an index entry.
8607* Combining Indices:: How to combine indices.
8608* New Indices:: How to define your own indices.
8609@end menu
8610
8611@node Index Entries, Predefined Indices, Indices, Indices
8612@comment node-name, next, previous, up
8613@section Making Index Entries
8614@cindex Index entries, making
8615@cindex Entries, making index
8616
8617When you are making index entries, it is good practice to think of the
8618different ways people may look for something. Different people
8619@emph{do not} think of the same words when they look something up. A
8620helpful index will have items indexed under all the different words
8621that people may use. For example, one reader may think it obvious that
8622the two-letter names for indices should be listed under ``Indices,
8623two-letter names'', since the word ``Index'' is the general concept.
8624But another reader may remember the specific concept of two-letter
8625names and search for the entry listed as ``Two letter names for
8626indices''. A good index will have both entries and will help both
8627readers.@refill
8628
8629Like typesetting, the construction of an index is a highly skilled,
8630professional art, the subtleties of which are not appreciated until you
8631need to do it yourself.@refill
8632
8633@xref{Printing Indices & Menus}, for information about printing an index
8634at the end of a book or creating an index menu in an Info file.@refill
8635
8636@node Predefined Indices, Indexing Commands, Index Entries, Indices
8637@comment node-name, next, previous, up
8638@section Predefined Indices
8639
8640Texinfo provides six predefined indices:@refill
8641
8642@itemize @bullet
8643@item
8644A @dfn{concept index} listing concepts that are discussed.@refill
8645
8646@item
8647A @dfn{function index} listing functions (such as entry points of
8648libraries).@refill
8649
8650@item
8651A @dfn{variables index} listing variables (such as global variables
8652of libraries).@refill
8653
8654@item
8655A @dfn{keystroke index} listing keyboard commands.@refill
8656
8657@item
8658A @dfn{program index} listing names of programs.@refill
8659
8660@item
8661A @dfn{data type index} listing data types (such as structures defined in
8662header files).@refill
8663@end itemize
8664
8665@noindent
8666Not every manual needs all of these, and most manuals use two or three
8667of them. This manual has two indices: a
8668concept index and an @@-command index (that is actually the function
8669index but is called a command index in the chapter heading). Two or
8670more indices can be combined into one using the @code{@@synindex} or
8671@code{@@syncodeindex} commands. @xref{Combining Indices}.@refill
8672
8673@node Indexing Commands, Combining Indices, Predefined Indices, Indices
8674@comment node-name, next, previous, up
8675@section Defining the Entries of an Index
8676@cindex Defining indexing entries
8677@cindex Index entries
8678@cindex Entries for an index
8679@cindex Specifying index entries
8680@cindex Creating index entries
8681
8682The data to make an index come from many individual indexing commands
8683scattered throughout the Texinfo source file. Each command says to add
8684one entry to a particular index; after formatting, the index will give
8685the current page number or node name as the reference.@refill
8686
8687An index entry consists of an indexing command at the beginning of a
8688line followed, on the rest of the line, by the entry.@refill
8689
8690For example, this section begins with the following five entries for
8691the concept index:@refill
8692
8693@example
8694@@cindex Defining indexing entries
8695@@cindex Index entries
8696@@cindex Entries for an index
8697@@cindex Specifying index entries
8698@@cindex Creating index entries
8699@end example
8700
8701Each predefined index has its own indexing command---@code{@@cindex}
8702for the concept index, @code{@@findex} for the function index, and so
8703on.@refill
8704
8705@cindex Writing index entries
8706@cindex Index entry writing
8707Concept index entries consist of text. The best way to write an index
8708is to choose entries that are terse yet clear. If you can do this,
8709the index often looks better if the entries are not capitalized, but
8710written just as they would appear in the middle of a sentence.
8711(Capitalize proper names and acronyms that always call for upper case
8712letters.) This is the case convention we use in most GNU manuals'
8713indices.
8714
8715If you don't see how to make an entry terse yet clear, make it longer
8716and clear---not terse and confusing. If many of the entries are several
8717words long, the index may look better if you use a different convention:
8718to capitalize the first word of each entry. But do not capitalize a
8719case-sensitive name such as a C or Lisp function name or a shell
8720command; that would be a spelling error.
8721
8722Whichever case convention you use, please use it consistently!
8723
8724Entries in indices other than the concept index are symbol names in
8725programming languages, or program names; these names are usually
8726case-sensitive, so use upper and lower case as required for them.
8727
8728By default, entries for a concept index are printed in a small roman
8729font and entries for the other indices are printed in a small
8730@code{@@code} font. You may change the way part of an entry is
8731printed with the usual Texinfo commands, such as @code{@@file} for
8732file names and @code{@@emph} for emphasis (@pxref{Marking
8733Text}).@refill
8734@cindex Index font types
8735
8736@cindex Predefined indexing commands
8737@cindex Indexing commands, predefined
8738The six indexing commands for predefined indices are:
8739
8740@table @code
8741@item @@cindex @var{concept}
8742@findex cindex
8743Make an entry in the concept index for @var{concept}.@refill
8744
8745@item @@findex @var{function}
8746@findex findex
8747Make an entry in the function index for @var{function}.@refill
8748
8749@item @@vindex @var{variable}
8750@findex vindex
8751Make an entry in the variable index for @var{variable}.@refill
8752
8753@item @@kindex @var{keystroke}
8754@findex kindex
8755Make an entry in the key index for @var{keystroke}.@refill
8756
8757@item @@pindex @var{program}
8758@findex pindex
8759Make an entry in the program index for @var{program}.@refill
8760
8761@item @@tindex @var{data type}
8762@findex tindex
8763Make an entry in the data type index for @var{data type}.@refill
8764@end table
8765
8766@quotation
8767@strong{Caution:} Do not use a colon in an index entry. In Info, a
8768colon separates the menu entry name from the node name, so a colon in
8769the entry itself confuses Info. @xref{Menu Parts, , The Parts of a
8770Menu}, for more information about the structure of a menu entry.
8771@end quotation
8772
8773You are not actually required to use the predefined indices for their
8774canonical purposes. For example, suppose you wish to index some C
8775preprocessor macros. You could put them in the function index along
8776with actual functions, just by writing @code{@@findex} commands for
8777them; then, when you print the ``Function Index'' as an unnumbered
8778chapter, you could give it the title `Function and Macro Index' and
8779all will be consistent for the reader. Or you could put the macros in
8780with the data types by writing @code{@@tindex} commands for them, and
8781give that index a suitable title so the reader will understand.
8782(@xref{Printing Indices & Menus}.)@refill
8783
8784@node Combining Indices, New Indices, Indexing Commands, Indices
8785@comment node-name, next, previous, up
8786@section Combining Indices
8787@cindex Combining indices
8788@cindex Indices, combining them
8789
8790Sometimes you will want to combine two disparate indices such as functions
8791and concepts, perhaps because you have few enough of one of them that
8792a separate index for them would look silly.@refill
8793
8794You could put functions into the concept index by writing
8795@code{@@cindex} commands for them instead of @code{@@findex} commands,
8796and produce a consistent manual by printing the concept index with the
8797title `Function and Concept Index' and not printing the `Function
8798Index' at all; but this is not a robust procedure. It works only if
8799your document is never included as part of another
8800document that is designed to have a separate function index; if your
8801document were to be included with such a document, the functions from
8802your document and those from the other would not end up together.
8803Also, to make your function names appear in the right font in the
8804concept index, you would need to enclose every one of them between
8805the braces of @code{@@code}.@refill
8806
8807@menu
8808* syncodeindex:: How to merge two indices, using @code{@@code}
8809 font for the merged-from index.
8810* synindex:: How to merge two indices, using the
8811 default font of the merged-to index.
8812@end menu
8813
| 7676
7677
7678@node verbatiminclude
7679@section @code{@@verbatiminclude} @var{file}: Include a File Verbatim
7680@cindex Verbatim, include file
7681@cindex Including a file verbatim
7682@findex verbatiminclude
7683
7684You can include the exact contents of a file in the document with the
7685@code{@@verbatiminclude} command:
7686
7687@example
7688@@verbatiminclude @var{filename}
7689@end example
7690
7691The contents of @var{filename} is printed in a verbatim environment
7692(@pxref{verbatim,,@code{@@verbatim}}). Generally, the file is printed
7693exactly as it is, with all special characters and white space retained.
7694
7695
7696@node lisp
7697@section @code{@@lisp}: Marking a Lisp Example
7698@findex lisp
7699@cindex Lisp example
7700
7701The @code{@@lisp} command is used for Lisp code. It is synonymous
7702with the @code{@@example} command.
7703
7704@lisp
7705This is an example of text written between an
7706@code{@@lisp} command and an @code{@@end lisp} command.
7707@end lisp
7708
7709Use @code{@@lisp} instead of @code{@@example} to preserve information
7710regarding the nature of the example. This is useful, for example, if
7711you write a function that evaluates only and all the Lisp code in a
7712Texinfo file. Then you can use the Texinfo file as a Lisp
7713library.@footnote{It would be straightforward to extend Texinfo to work
7714in a similar fashion for C, Fortran, or other languages.}
7715
7716Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by
7717itself.@refill
7718
7719
7720@node small
7721@section @code{@@small@dots{}} Block Commands
7722@cindex Small examples
7723@cindex Examples in smaller fonts
7724@cindex Lisp examples in smaller fonts
7725@findex smalldisplay
7726@findex smallexample
7727@findex smallformat
7728@findex smalllisp
7729
7730In addition to the regular @code{@@example} and @code{@@lisp} commands,
7731Texinfo has ``small'' example-style commands. These are
7732@code{@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat}, and
7733@code{@@smalllisp}.
7734
7735In @TeX{}, the @code{@@small@dots{}} commands typeset text in a smaller
7736font than the non-small example commands. Consequently, many examples
7737containing long lines fit on a page without needing to be shortened.
7738
7739In Info, the @code{@@small@dots{}} commands are equivalent to their
7740non-small companion commands.
7741
7742Mark the end of an @code{@@small@dots{}} block with a corresponding
7743@code{@@end small@dots{}}. For example, pair @code{@@smallexample} with
7744@code{@@end smallexample}.
7745
7746@iftex
7747Here is an example written in the small font used by the
7748@code{@@smallexample} and @code{@@smalllisp} commands:
7749
7750@ifclear smallbook
7751@display
7752@tex
7753% Remove extra vskip; this is a kludge to counter the effect of display
7754\vskip-3\baselineskip
7755{\smalltt
7756\dots{} to make sure that you have the freedom to
7757distribute copies of free software (and charge for
7758this service if you wish), that you receive source
7759code or can get it if you want it, that you can
7760change the software or use pieces of it in new free
7761programs; and that you know you can do these things.}
7762@end tex
7763@end display
7764@end ifclear
7765@end iftex
7766@ifset smallbook
7767@iftex
7768@smallexample
7769This is an example of text written between @code{@@smallexample} and
7770@code{@@end smallexample}. In Info this text appears in its normal size;
7771but in printed manuals, this text appears in a smaller font.
7772@end smallexample
7773@end iftex
7774@end ifset
7775@ifinfo
7776@smallexample
7777This is an example of text written between @code{@@smallexample} and
7778@code{@@end smallexample}. In Info this text appears in its normal size;
7779but in a 7 by 9.25 inch manual, this text appears in a smaller font.
7780@end smallexample
7781@end ifinfo
7782
7783The @code{@@small@dots{}} commands make it easier to prepare manuals
7784without forcing you to edit examples by hand to fit them onto narrower
7785pages.
7786
7787As a general rule, a printed document looks better if you use only one
7788of (for example) @code{@@example} or in @code{@@smallexample}
7789consistently within a chapter. Only occasionally should you mix the two
7790formats.
7791
7792@xref{smallbook, , Printing ``Small'' Books}, for more information
7793about the @code{@@smallbook} command.
7794
7795
7796@node display
7797@section @code{@@display} and @code{@@smalldisplay}
7798@cindex Display formatting
7799@findex display
7800
7801The @code{@@display} command begins a kind of example. It is like the
7802@code{@@example} command
7803except that, in
7804a printed manual, @code{@@display} does not select the fixed-width
7805font. In fact, it does not specify the font at all, so that the text
7806appears in the same font it would have appeared in without the
7807@code{@@display} command.@refill
7808
7809@display
7810This is an example of text written between an @code{@@display} command
7811and an @code{@@end display} command. The @code{@@display} command
7812indents the text, but does not fill it.
7813@end display
7814
7815@findex smalldisplay
7816Texinfo also provides a command @code{@@smalldisplay}, which is like
7817@code{@@display} but uses a smaller font in @code{@@smallbook} format.
7818@xref{small}.
7819
7820
7821@node format
7822@section @code{@@format} and @code{@@smallformat}
7823@findex format
7824
7825The @code{@@format} command is similar to @code{@@example} except
7826that, in the printed manual, @code{@@format} does not select the
7827fixed-width font and does not narrow the margins.@refill
7828
7829@format
7830This is an example of text written between an @code{@@format} command
7831and an @code{@@end format} command. As you can see
7832from this example,
7833the @code{@@format} command does not fill the text.
7834@end format
7835
7836@findex smallformat
7837Texinfo also provides a command @code{@@smallformat}, which is like
7838@code{@@format} but uses a smaller font in @code{@@smallbook} format.
7839@xref{small}.
7840
7841
7842
7843@node exdent
7844@section @code{@@exdent}: Undoing a Line's Indentation
7845@cindex Indentation undoing
7846@findex exdent
7847
7848The @code{@@exdent} command removes any indentation a line might have.
7849The command is written at the beginning of a line and applies only to
7850the text that follows the command that is on the same line. Do not use
7851braces around the text. In a printed manual, the text on an
7852@code{@@exdent} line is printed in the roman font.@refill
7853
7854@code{@@exdent} is usually used within examples. Thus,@refill
7855
7856@example
7857@group
7858@@example
7859This line follows an @@@@example command.
7860@@exdent This line is exdented.
7861This line follows the exdented line.
7862The @@@@end example comes on the next line.
7863@@end group
7864@end group
7865@end example
7866
7867@noindent
7868produces
7869
7870@example
7871@group
7872This line follows an @@example command.
7873@exdent This line is exdented.
7874This line follows the exdented line.
7875The @@end example comes on the next line.
7876@end group
7877@end example
7878
7879In practice, the @code{@@exdent} command is rarely used.
7880Usually, you un-indent text by ending the example and
7881returning the page to its normal width.@refill
7882
7883
7884@node flushleft & flushright
7885@section @code{@@flushleft} and @code{@@flushright}
7886@findex flushleft
7887@findex flushright
7888@cindex ragged right
7889@cindex ragged left
7890
7891The @code{@@flushleft} and @code{@@flushright} commands line up the
7892ends of lines on the left and right margins of a page,
7893but do not fill the text. The commands are written on lines of their
7894own, without braces. The @code{@@flushleft} and @code{@@flushright}
7895commands are ended by @code{@@end flushleft} and @code{@@end
7896flushright} commands on lines of their own.@refill
7897
7898@need 1500
7899For example,
7900
7901@example
7902@group
7903@@flushleft
7904This text is
7905written flushleft.
7906@@end flushleft
7907@end group
7908@end example
7909
7910@noindent
7911produces
7912
7913@quotation
7914@flushleft
7915This text is
7916written flushleft.
7917@end flushleft
7918@end quotation
7919
7920
7921@code{@@flushright} produces the type of indentation often used in the
7922return address of letters. For example,
7923
7924@example
7925@group
7926@@flushright
7927Here is an example of text written
7928flushright. The @@code@{@@flushright@} command
7929right justifies every line but leaves the
7930left end ragged.
7931@@end flushright
7932@end group
7933@end example
7934
7935@noindent
7936produces
7937
7938@flushright
7939Here is an example of text written
7940flushright. The @code{@@flushright} command
7941right justifies every line but leaves the
7942left end ragged.
7943@end flushright
7944
7945
7946@node noindent
7947@section @code{@@noindent}: Omitting Indentation
7948@findex noindent
7949
7950An example or other inclusion can break a paragraph into segments.
7951Ordinarily, the formatters indent text that follows an example as a new
7952paragraph. However, you can prevent this by writing @code{@@noindent}
7953at the beginning of a line by itself preceding the continuation
7954text.@refill
7955
7956@need 1500
7957For example:
7958
7959@example
7960@group
7961@@example
7962This is an example
7963@@end example
7964
7965@@noindent
7966This line is not indented. As you can see, the
7967beginning of the line is fully flush left with the line
7968that follows after it. (This whole example is between
7969@@code@{@@@@display@} and @@code@{@@@@end display@}.)
7970@end group
7971@end example
7972
7973@noindent
7974produces
7975
7976@display
7977@example
7978This is an example
7979@end example
7980@tex
7981% Remove extra vskip; this is a kludge to counter the effect of display
7982\vskip-3.5\baselineskip
7983@end tex
7984
7985@noindent
7986This line is not indented. As you can see, the
7987beginning of the line is fully flush left with the line
7988that follows after it. (This whole example is between
7989@code{@@display} and @code{@@end display}.)
7990@end display
7991
7992To adjust the number of blank lines properly in the Info file output,
7993remember that the line containing @code{@@noindent} does not generate a
7994blank line, and neither does the @code{@@end example} line.@refill
7995
7996In the Texinfo source file for this manual, each line that says
7997`produces' is preceded by a line containing @code{@@noindent}.@refill
7998
7999Do not put braces after an @code{@@noindent} command; they are not
8000necessary, since @code{@@noindent} is a command used outside of
8001paragraphs (@pxref{Command Syntax}).@refill
8002
8003
8004@node cartouche
8005@section @code{@@cartouche}: Rounded Rectangles Around Examples
8006@findex cartouche
8007@cindex Box with rounded corners
8008@cindex Rounded rectangles, around examples
8009
8010In a printed manual, the @code{@@cartouche} command draws a box with
8011rounded corners around its contents. You can use this command to
8012further highlight an example or quotation. For instance, you could
8013write a manual in which one type of example is surrounded by a cartouche
8014for emphasis.
8015
8016@code{@@cartouche} affects only the printed manual; it has no effect in
8017other output files.
8018
8019@need 1500
8020For example,
8021
8022@example
8023@group
8024@@example
8025@@cartouche
8026% pwd
8027/usr/local/share/emacs
8028@@end cartouche
8029@@end example
8030@end group
8031@end example
8032
8033@noindent
8034surrounds the two-line example with a box with rounded corners, in the
8035printed manual.
8036
8037@iftex
8038In a printed manual, the example looks like this:@refill
8039
8040@example
8041@group
8042@cartouche
8043% pwd
8044/usr/local/lib/emacs/info
8045@end cartouche
8046@end group
8047@end example
8048@end iftex
8049
8050
8051@node Lists and Tables
8052@chapter Lists and Tables
8053@cindex Making lists and tables
8054@cindex Lists and tables, making
8055@cindex Tables and lists, making
8056
8057Texinfo has several ways of making lists and tables. Lists can be
8058bulleted or numbered; two-column tables can highlight the items in
8059the first column; multi-column tables are also supported.
8060
8061@menu
8062* Introducing Lists:: Texinfo formats lists for you.
8063* itemize:: How to construct a simple list.
8064* enumerate:: How to construct a numbered list.
8065* Two-column Tables:: How to construct a two-column table.
8066* Multi-column Tables:: How to construct generalized tables.
8067@end menu
8068
8069@node Introducing Lists, itemize, Lists and Tables, Lists and Tables
8070@ifinfo
8071@heading Introducing Lists
8072@end ifinfo
8073
8074Texinfo automatically indents the text in lists or tables, and numbers
8075an enumerated list. This last feature is useful if you modify the
8076list, since you do not need to renumber it yourself.@refill
8077
8078Numbered lists and tables begin with the appropriate @@-command at the
8079beginning of a line, and end with the corresponding @code{@@end}
8080command on a line by itself. The table and itemized-list commands
8081also require that you write formatting information on the same line as
8082the beginning @@-command.@refill
8083
8084Begin an enumerated list, for example, with an @code{@@enumerate}
8085command and end the list with an @code{@@end enumerate} command.
8086Begin an itemized list with an @code{@@itemize} command, followed on
8087the same line by a formatting command such as @code{@@bullet}, and end
8088the list with an @code{@@end itemize} command.@refill
8089@findex end
8090
8091Precede each element of a list with an @code{@@item} or @code{@@itemx}
8092command.@refill
8093
8094@sp 1
8095@noindent
8096Here is an itemized list of the different kinds of table and lists:@refill
8097
8098@itemize @bullet
8099@item
8100Itemized lists with and without bullets.
8101
8102@item
8103Enumerated lists, using numbers or letters.
8104
8105@item
8106Two-column tables with highlighting.
8107@end itemize
8108
8109@sp 1
8110@noindent
8111Here is an enumerated list with the same items:@refill
8112
8113@enumerate
8114@item
8115Itemized lists with and without bullets.
8116
8117@item
8118Enumerated lists, using numbers or letters.
8119
8120@item
8121Two-column tables with highlighting.
8122@end enumerate
8123
8124@sp 1
8125@noindent
8126And here is a two-column table with the same items and their
8127@w{@@-commands}:@refill
8128
8129@table @code
8130@item @@itemize
8131Itemized lists with and without bullets.
8132
8133@item @@enumerate
8134Enumerated lists, using numbers or letters.
8135
8136@item @@table
8137@itemx @@ftable
8138@itemx @@vtable
8139Two-column tables, optionally with indexing.
8140@end table
8141
8142
8143@node itemize
8144@section @code{@@itemize}: Making an Itemized List
8145@cindex Itemization
8146@findex itemize
8147
8148The @code{@@itemize} command produces sequences of indented
8149paragraphs, with a bullet or other mark inside the left margin
8150at the beginning of each paragraph for which such a mark is desired.@refill
8151
8152@cindex @code{@@w}, for blank items
8153Begin an itemized list by writing @code{@@itemize} at the beginning of
8154a line. Follow the command, on the same line, with a character or a
8155Texinfo command that generates a mark. Usually, you will write
8156@code{@@bullet} after @code{@@itemize}, but you can use
8157@code{@@minus}, or any command or character that results in a single
8158character in the Info file. If you don't want any mark at all, use
8159@code{@@w}. (When you write the mark command such as
8160@code{@@bullet} after an @code{@@itemize} command, you may omit the
8161@samp{@{@}}.) If you don't specify a mark command, the default is
8162@code{@@bullet}.
8163
8164Write the text of the indented paragraphs themselves after the
8165@code{@@itemize}, up to another line that says @code{@@end
8166itemize}.@refill
8167
8168@findex item
8169Before each paragraph for which a mark in the margin is desired, write a
8170line that says just @code{@@item}. It is ok to have text following the
8171@code{@@item}.
8172
8173Usually, you should put a blank line before an @code{@@item}. This
8174puts a blank line in the Info file. (@TeX{} inserts the proper
8175interline whitespace in either case.) Except when the entries are
8176very brief, these blank lines make the list look better.@refill
8177
8178Here is an example of the use of @code{@@itemize}, followed by the
8179output it produces. @code{@@bullet} produces an @samp{*} in Info and a
8180round dot in @TeX{}.
8181
8182@example
8183@group
8184@@itemize @@bullet
8185@@item
8186Some text for foo.
8187
8188@@item
8189Some text
8190for bar.
8191@@end itemize
8192@end group
8193@end example
8194
8195@noindent
8196This produces:
8197
8198@quotation
8199@itemize @bullet
8200@item
8201Some text for foo.
8202
8203@item
8204Some text
8205for bar.
8206@end itemize
8207@end quotation
8208
8209Itemized lists may be embedded within other itemized lists. Here is a
8210list marked with dashes embedded in a list marked with bullets:@refill
8211
8212@example
8213@group
8214@@itemize @@bullet
8215@@item
8216First item.
8217
8218@@itemize @@minus
8219@@item
8220Inner item.
8221
8222@@item
8223Second inner item.
8224@@end itemize
8225
8226@@item
8227Second outer item.
8228@@end itemize
8229@end group
8230@end example
8231
8232@noindent
8233This produces:
8234
8235@quotation
8236@itemize @bullet
8237@item
8238First item.
8239
8240@itemize @minus
8241@item
8242Inner item.
8243
8244@item
8245Second inner item.
8246@end itemize
8247
8248@item
8249Second outer item.
8250@end itemize
8251@end quotation
8252
8253
8254@node enumerate
8255@section @code{@@enumerate}: Making a Numbered or Lettered List
8256@cindex Enumeration
8257@findex enumerate
8258
8259@code{@@enumerate} is like @code{@@itemize} (@pxref{itemize,,
8260@code{@@itemize}}), except that the labels on the items are
8261successive integers or letters instead of bullets.
8262
8263Write the @code{@@enumerate} command at the beginning of a line. The
8264command does not require an argument, but accepts either a number or a
8265letter as an option. Without an argument, @code{@@enumerate} starts the
8266list with the number @samp{1}. With a numeric argument, such as
8267@samp{3}, the command starts the list with that number. With an upper
8268or lower case letter, such as @samp{a} or @samp{A}, the command starts
8269the list with that letter.
8270
8271Write the text of the enumerated list in the same way you write an
8272itemized list: put @code{@@item} on a line of its own before the start
8273of each paragraph that you want enumerated. Do not write any other text
8274on the line beginning with @code{@@item}.
8275
8276You should put a blank line between entries in the list.
8277This generally makes it easier to read the Info file.
8278
8279@need 1500
8280Here is an example of @code{@@enumerate} without an argument:
8281
8282@example
8283@group
8284@@enumerate
8285@@item
8286Underlying causes.
8287
8288@@item
8289Proximate causes.
8290@@end enumerate
8291@end group
8292@end example
8293
8294@noindent
8295This produces:
8296
8297@enumerate
8298@item
8299Underlying causes.
8300
8301@item
8302Proximate causes.
8303@end enumerate
8304@sp 1
8305Here is an example with an argument of @kbd{3}:@refill
8306@sp 1
8307@example
8308@group
8309@@enumerate 3
8310@@item
8311Predisposing causes.
8312
8313@@item
8314Precipitating causes.
8315
8316@@item
8317Perpetuating causes.
8318@@end enumerate
8319@end group
8320@end example
8321
8322@noindent
8323This produces:
8324
8325@enumerate 3
8326@item
8327Predisposing causes.
8328
8329@item
8330Precipitating causes.
8331
8332@item
8333Perpetuating causes.
8334@end enumerate
8335@sp 1
8336Here is a brief summary of the alternatives. The summary is constructed
8337using @code{@@enumerate} with an argument of @kbd{a}.@refill
8338@sp 1
8339@enumerate a
8340@item
8341@code{@@enumerate}
8342
8343Without an argument, produce a numbered list, starting with the number
83441.@refill
8345
8346@item
8347@code{@@enumerate @var{positive-integer}}
8348
8349With a (positive) numeric argument, start a numbered list with that
8350number. You can use this to continue a list that you interrupted with
8351other text.@refill
8352
8353@item
8354@code{@@enumerate @var{upper-case-letter}}
8355
8356With an upper case letter as argument, start a list
8357in which each item is marked
8358by a letter, beginning with that upper case letter.@refill
8359
8360@item
8361@code{@@enumerate @var{lower-case-letter}}
8362
8363With a lower case letter as argument, start a list
8364in which each item is marked by
8365a letter, beginning with that lower case letter.@refill
8366@end enumerate
8367
8368You can also nest enumerated lists, as in an outline.@refill
8369
8370@node Two-column Tables, Multi-column Tables, enumerate, Lists and Tables
8371@section Making a Two-column Table
8372@cindex Tables, making two-column
8373@findex table
8374
8375@code{@@table} is similar to @code{@@itemize} (@pxref{itemize,,
8376@code{@@itemize}}), but allows you to specify a name or heading line for
8377each item. The @code{@@table} command is used to produce two-column
8378tables, and is especially useful for glossaries, explanatory
8379exhibits, and command-line option summaries.
8380
8381@menu
8382* table:: How to construct a two-column table.
8383* ftable vtable:: Automatic indexing for two-column tables.
8384* itemx:: How to put more entries in the first column.
8385@end menu
8386
8387@node table, ftable vtable, Two-column Tables, Two-column Tables
8388@ifinfo
8389@subheading Using the @code{@@table} Command
8390
8391Use the @code{@@table} command to produce two-column tables.@refill
8392@end ifinfo
8393
8394Write the @code{@@table} command at the beginning of a line and follow
8395it on the same line with an argument that is a Texinfo ``indicating''
8396command such as @code{@@code}, @code{@@samp}, @code{@@var}, or
8397@code{@@kbd} (@pxref{Indicating}). Although these commands are usually
8398followed by arguments in braces, in this case you use the command name
8399without an argument because @code{@@item} will supply the argument.
8400This command will be applied to the text that goes into the first column
8401of each item and determines how it will be highlighted. For example,
8402@code{@@code} will cause the text in the first column to be highlighted
8403with an @code{@@code} command. (We recommend @code{@@code} for
8404@code{@@table}'s of command-line options.)
8405
8406@findex asis
8407You may also choose to use the @code{@@asis} command as an argument to
8408@code{@@table}. @code{@@asis} is a command that does nothing; if you
8409use this command after @code{@@table}, @TeX{} and the Info formatting
8410commands output the first column entries without added highlighting
8411(``as is'').@refill
8412
8413(The @code{@@table} command may work with other commands besides those
8414listed here. However, you can only use commands that normally take
8415arguments in braces.)@refill
8416
8417@findex item
8418Begin each table entry with an @code{@@item} command at the beginning
8419of a line. Write the first column text on the same line as the
8420@code{@@item} command. Write the second column text on the line
8421following the @code{@@item} line and on subsequent lines. (You do not
8422need to type anything for an empty second column entry.) You may
8423write as many lines of supporting text as you wish, even several
8424paragraphs. But only text on the same line as the @code{@@item} will
8425be placed in the first column, including any footnote.
8426
8427Normally, you should put a blank line before an @code{@@item} line.
8428This puts a blank like in the Info file. Except when the entries are
8429very brief, a blank line looks better.@refill
8430
8431@need 1500
8432The following table, for example, highlights the text in the first
8433column with an @code{@@samp} command:@refill
8434
8435@example
8436@group
8437@@table @@samp
8438@@item foo
8439This is the text for
8440@@samp@{foo@}.
8441
8442@@item bar
8443Text for @@samp@{bar@}.
8444@@end table
8445@end group
8446@end example
8447
8448@noindent
8449This produces:
8450
8451@table @samp
8452@item foo
8453This is the text for
8454@samp{foo}.
8455@item bar
8456Text for @samp{bar}.
8457@end table
8458
8459If you want to list two or more named items with a single block of
8460text, use the @code{@@itemx} command. (@xref{itemx, ,
8461@code{@@itemx}}.)@refill
8462
8463
8464@node ftable vtable
8465@subsection @code{@@ftable} and @code{@@vtable}
8466@cindex Tables with indexes
8467@cindex Indexing table entries automatically
8468@findex ftable
8469@findex vtable
8470
8471The @code{@@ftable} and @code{@@vtable} commands are the same as the
8472@code{@@table} command except that @code{@@ftable} automatically enters
8473each of the items in the first column of the table into the index of
8474functions and @code{@@vtable} automatically enters each of the items in
8475the first column of the table into the index of variables. This
8476simplifies the task of creating indices. Only the items on the same
8477line as the @code{@@item} commands are indexed, and they are indexed in
8478exactly the form that they appear on that line. @xref{Indices},
8479for more information about indices.@refill
8480
8481Begin a two-column table using @code{@@ftable} or @code{@@vtable} by
8482writing the @@-command at the beginning of a line, followed on the same
8483line by an argument that is a Texinfo command such as @code{@@code},
8484exactly as you would for an @code{@@table} command; and end the table
8485with an @code{@@end ftable} or @code{@@end vtable} command on a line by
8486itself.
8487
8488See the example for @code{@@table} in the previous section.
8489
8490@node itemx
8491@subsection @code{@@itemx}
8492@cindex Two named items for @code{@@table}
8493@findex itemx
8494
8495Use the @code{@@itemx} command inside a table when you have two or more
8496first column entries for the same item, each of which should appear on a
8497line of its own. Use @code{@@itemx} for all but the first entry;
8498@code{@@itemx} should always follow an @code{@@item} command. The
8499@code{@@itemx} command works exactly like @code{@@item} except that it
8500does not generate extra vertical space above the first column text.
8501
8502For example,
8503
8504@example
8505@group
8506@@table @@code
8507@@item upcase
8508@@itemx downcase
8509These two functions accept a character or a string as
8510argument, and return the corresponding upper case (lower
8511case) character or string.
8512@@end table
8513@end group
8514@end example
8515
8516@noindent
8517This produces:
8518
8519@table @code
8520@item upcase
8521@itemx downcase
8522These two functions accept a character or a string as
8523argument, and return the corresponding upper case (lower
8524case) character or string.@refill
8525@end table
8526
8527@noindent
8528(Note also that this example illustrates multi-line supporting text in
8529a two-column table.)@refill
8530
8531
8532@node Multi-column Tables, , Two-column Tables, Lists and Tables
8533@section Multi-column Tables
8534@cindex Tables, making multi-column
8535@findex multitable
8536
8537@code{@@multitable} allows you to construct tables with any number of
8538columns, with each column having any width you like.
8539
8540You define the column widths on the @code{@@multitable} line itself, and
8541write each row of the actual table following an @code{@@item} command,
8542with columns separated by an @code{@@tab} command. Finally, @code{@@end
8543multitable} completes the table. Details in the sections below.
8544
8545@menu
8546* Multitable Column Widths:: Defining multitable column widths.
8547* Multitable Rows:: Defining multitable rows, with examples.
8548@end menu
8549
8550@node Multitable Column Widths
8551@subsection Multitable Column Widths
8552@cindex Multitable column widths
8553@cindex Column widths, defining for multitables
8554@cindex Widths, defining multitable column
8555
8556You can define the column widths for a multitable in two ways: as
8557fractions of the line length; or with a prototype row. Mixing the two
8558methods is not supported. In either case, the widths are defined
8559entirely on the same line as the @code{@@multitable} command.
8560
8561@enumerate
8562@item
8563@findex columnfractions
8564@cindex Line length, column widths as fraction of
8565To specify column widths as fractions of the line length, write
8566@code{@@columnfractions} and the decimal numbers (presumably less than
85671) after the @code{@@multitable} command, as in:
8568
8569@example
8570@@multitable @@columnfractions .33 .33 .33
8571@end example
8572
8573@noindent The fractions need not add up exactly to 1.0, as these do
8574not. This allows you to produce tables that do not need the full line
8575length. You can use a leading zero if you wish.
8576
8577@item
8578@cindex Prototype row, column widths defined by
8579To specify a prototype row, write the longest entry for each column
8580enclosed in braces after the @code{@@multitable} command. For example:
8581
8582@example
8583@@multitable @{some text for column one@} @{for column two@}
8584@end example
8585
8586@noindent
8587The first column will then have the width of the typeset `some text for
8588column one', and the second column the width of `for column two'.
8589
8590The prototype entries need not appear in the table itself.
8591
8592Although we used simple text in this example, the prototype entries can
8593contain Texinfo commands; markup commands such as @code{@@code} are
8594particularly likely to be useful.
8595
8596@end enumerate
8597
8598
8599@node Multitable Rows, , Multitable Column Widths, Multi-column Tables
8600@subsection Multitable Rows
8601@cindex Multitable rows
8602@cindex Rows, of a multitable
8603
8604@findex item
8605@findex tab
8606After the @code{@@multitable} command defining the column widths (see
8607the previous section), you begin each row in the body of a multitable
8608with @code{@@item}, and separate the column entries with @code{@@tab}.
8609Line breaks are not special within the table body, and you may break
8610input lines in your source file as necessary.
8611
8612Here is a complete example of a multi-column table (the text is from
8613@cite{The GNU Emacs Manual}, @pxref{Split Window,, Splitting Windows,
8614emacs, The GNU Emacs Manual}):
8615
8616@example
8617@@multitable @@columnfractions .15 .45 .4
8618@@item Key @@tab Command @@tab Description
8619@@item C-x 2
8620@@tab @@code@{split-window-vertically@}
8621@@tab Split the selected window into two windows,
8622with one above the other.
8623@@item C-x 3
8624@@tab @@code@{split-window-horizontally@}
8625@@tab Split the selected window into two windows
8626positioned side by side.
8627@@item C-Mouse-2
8628@@tab
8629@@tab In the mode line or scroll bar of a window,
8630split that window.
8631@@end multitable
8632@end example
8633
8634@noindent produces:
8635
8636@multitable @columnfractions .15 .45 .4
8637@item Key @tab Command @tab Description
8638@item C-x 2
8639@tab @code{split-window-vertically}
8640@tab Split the selected window into two windows,
8641with one above the other.
8642@item C-x 3
8643@tab @code{split-window-horizontally}
8644@tab Split the selected window into two windows
8645positioned side by side.
8646@item C-Mouse-2
8647@tab
8648@tab In the mode line or scroll bar of a window,
8649split that window.
8650@end multitable
8651
8652
8653@node Indices, Insertions, Lists and Tables, Top
8654@comment node-name, next, previous, up
8655@chapter Indices
8656@cindex Indices
8657
8658Using Texinfo, you can generate indices without having to sort and
8659collate entries manually. In an index, the entries are listed in
8660alphabetical order, together with information on how to find the
8661discussion of each entry. In a printed manual, this information
8662consists of page numbers. In an Info file, this information is a menu
8663entry leading to the first node referenced.@refill
8664
8665Texinfo provides several predefined kinds of index: an index
8666for functions, an index for variables, an index for concepts, and so
8667on. You can combine indices or use them for other than their
8668canonical purpose. If you wish, you can define your own indices.@refill
8669
8670@menu
8671* Index Entries:: Choose different words for index entries.
8672* Predefined Indices:: Use different indices for different kinds
8673 of entry.
8674* Indexing Commands:: How to make an index entry.
8675* Combining Indices:: How to combine indices.
8676* New Indices:: How to define your own indices.
8677@end menu
8678
8679@node Index Entries, Predefined Indices, Indices, Indices
8680@comment node-name, next, previous, up
8681@section Making Index Entries
8682@cindex Index entries, making
8683@cindex Entries, making index
8684
8685When you are making index entries, it is good practice to think of the
8686different ways people may look for something. Different people
8687@emph{do not} think of the same words when they look something up. A
8688helpful index will have items indexed under all the different words
8689that people may use. For example, one reader may think it obvious that
8690the two-letter names for indices should be listed under ``Indices,
8691two-letter names'', since the word ``Index'' is the general concept.
8692But another reader may remember the specific concept of two-letter
8693names and search for the entry listed as ``Two letter names for
8694indices''. A good index will have both entries and will help both
8695readers.@refill
8696
8697Like typesetting, the construction of an index is a highly skilled,
8698professional art, the subtleties of which are not appreciated until you
8699need to do it yourself.@refill
8700
8701@xref{Printing Indices & Menus}, for information about printing an index
8702at the end of a book or creating an index menu in an Info file.@refill
8703
8704@node Predefined Indices, Indexing Commands, Index Entries, Indices
8705@comment node-name, next, previous, up
8706@section Predefined Indices
8707
8708Texinfo provides six predefined indices:@refill
8709
8710@itemize @bullet
8711@item
8712A @dfn{concept index} listing concepts that are discussed.@refill
8713
8714@item
8715A @dfn{function index} listing functions (such as entry points of
8716libraries).@refill
8717
8718@item
8719A @dfn{variables index} listing variables (such as global variables
8720of libraries).@refill
8721
8722@item
8723A @dfn{keystroke index} listing keyboard commands.@refill
8724
8725@item
8726A @dfn{program index} listing names of programs.@refill
8727
8728@item
8729A @dfn{data type index} listing data types (such as structures defined in
8730header files).@refill
8731@end itemize
8732
8733@noindent
8734Not every manual needs all of these, and most manuals use two or three
8735of them. This manual has two indices: a
8736concept index and an @@-command index (that is actually the function
8737index but is called a command index in the chapter heading). Two or
8738more indices can be combined into one using the @code{@@synindex} or
8739@code{@@syncodeindex} commands. @xref{Combining Indices}.@refill
8740
8741@node Indexing Commands, Combining Indices, Predefined Indices, Indices
8742@comment node-name, next, previous, up
8743@section Defining the Entries of an Index
8744@cindex Defining indexing entries
8745@cindex Index entries
8746@cindex Entries for an index
8747@cindex Specifying index entries
8748@cindex Creating index entries
8749
8750The data to make an index come from many individual indexing commands
8751scattered throughout the Texinfo source file. Each command says to add
8752one entry to a particular index; after formatting, the index will give
8753the current page number or node name as the reference.@refill
8754
8755An index entry consists of an indexing command at the beginning of a
8756line followed, on the rest of the line, by the entry.@refill
8757
8758For example, this section begins with the following five entries for
8759the concept index:@refill
8760
8761@example
8762@@cindex Defining indexing entries
8763@@cindex Index entries
8764@@cindex Entries for an index
8765@@cindex Specifying index entries
8766@@cindex Creating index entries
8767@end example
8768
8769Each predefined index has its own indexing command---@code{@@cindex}
8770for the concept index, @code{@@findex} for the function index, and so
8771on.@refill
8772
8773@cindex Writing index entries
8774@cindex Index entry writing
8775Concept index entries consist of text. The best way to write an index
8776is to choose entries that are terse yet clear. If you can do this,
8777the index often looks better if the entries are not capitalized, but
8778written just as they would appear in the middle of a sentence.
8779(Capitalize proper names and acronyms that always call for upper case
8780letters.) This is the case convention we use in most GNU manuals'
8781indices.
8782
8783If you don't see how to make an entry terse yet clear, make it longer
8784and clear---not terse and confusing. If many of the entries are several
8785words long, the index may look better if you use a different convention:
8786to capitalize the first word of each entry. But do not capitalize a
8787case-sensitive name such as a C or Lisp function name or a shell
8788command; that would be a spelling error.
8789
8790Whichever case convention you use, please use it consistently!
8791
8792Entries in indices other than the concept index are symbol names in
8793programming languages, or program names; these names are usually
8794case-sensitive, so use upper and lower case as required for them.
8795
8796By default, entries for a concept index are printed in a small roman
8797font and entries for the other indices are printed in a small
8798@code{@@code} font. You may change the way part of an entry is
8799printed with the usual Texinfo commands, such as @code{@@file} for
8800file names and @code{@@emph} for emphasis (@pxref{Marking
8801Text}).@refill
8802@cindex Index font types
8803
8804@cindex Predefined indexing commands
8805@cindex Indexing commands, predefined
8806The six indexing commands for predefined indices are:
8807
8808@table @code
8809@item @@cindex @var{concept}
8810@findex cindex
8811Make an entry in the concept index for @var{concept}.@refill
8812
8813@item @@findex @var{function}
8814@findex findex
8815Make an entry in the function index for @var{function}.@refill
8816
8817@item @@vindex @var{variable}
8818@findex vindex
8819Make an entry in the variable index for @var{variable}.@refill
8820
8821@item @@kindex @var{keystroke}
8822@findex kindex
8823Make an entry in the key index for @var{keystroke}.@refill
8824
8825@item @@pindex @var{program}
8826@findex pindex
8827Make an entry in the program index for @var{program}.@refill
8828
8829@item @@tindex @var{data type}
8830@findex tindex
8831Make an entry in the data type index for @var{data type}.@refill
8832@end table
8833
8834@quotation
8835@strong{Caution:} Do not use a colon in an index entry. In Info, a
8836colon separates the menu entry name from the node name, so a colon in
8837the entry itself confuses Info. @xref{Menu Parts, , The Parts of a
8838Menu}, for more information about the structure of a menu entry.
8839@end quotation
8840
8841You are not actually required to use the predefined indices for their
8842canonical purposes. For example, suppose you wish to index some C
8843preprocessor macros. You could put them in the function index along
8844with actual functions, just by writing @code{@@findex} commands for
8845them; then, when you print the ``Function Index'' as an unnumbered
8846chapter, you could give it the title `Function and Macro Index' and
8847all will be consistent for the reader. Or you could put the macros in
8848with the data types by writing @code{@@tindex} commands for them, and
8849give that index a suitable title so the reader will understand.
8850(@xref{Printing Indices & Menus}.)@refill
8851
8852@node Combining Indices, New Indices, Indexing Commands, Indices
8853@comment node-name, next, previous, up
8854@section Combining Indices
8855@cindex Combining indices
8856@cindex Indices, combining them
8857
8858Sometimes you will want to combine two disparate indices such as functions
8859and concepts, perhaps because you have few enough of one of them that
8860a separate index for them would look silly.@refill
8861
8862You could put functions into the concept index by writing
8863@code{@@cindex} commands for them instead of @code{@@findex} commands,
8864and produce a consistent manual by printing the concept index with the
8865title `Function and Concept Index' and not printing the `Function
8866Index' at all; but this is not a robust procedure. It works only if
8867your document is never included as part of another
8868document that is designed to have a separate function index; if your
8869document were to be included with such a document, the functions from
8870your document and those from the other would not end up together.
8871Also, to make your function names appear in the right font in the
8872concept index, you would need to enclose every one of them between
8873the braces of @code{@@code}.@refill
8874
8875@menu
8876* syncodeindex:: How to merge two indices, using @code{@@code}
8877 font for the merged-from index.
8878* synindex:: How to merge two indices, using the
8879 default font of the merged-to index.
8880@end menu
8881
|
8814@node syncodeindex, synindex, Combining Indices, Combining Indices
| 8882@node syncodeindex
|
8815@subsection @code{@@syncodeindex}
8816@findex syncodeindex
8817
8818When you want to combine functions and concepts into one index, you
8819should index the functions with @code{@@findex} and index the concepts
8820with @code{@@cindex}, and use the @code{@@syncodeindex} command to
8821redirect the function index entries into the concept index.@refill
8822@findex syncodeindex
8823
8824The @code{@@syncodeindex} command takes two arguments; they are the name
8825of the index to redirect, and the name of the index to redirect it to.
8826The template looks like this:@refill
8827
8828@example
8829@@syncodeindex @var{from} @var{to}
8830@end example
8831
8832@cindex Predefined names for indices
8833@cindex Two letter names for indices
8834@cindex Indices, two letter names
8835@cindex Names for indices
8836For this purpose, the indices are given two-letter names:@refill
8837
8838@table @samp
8839@item cp
8840concept index
8841@item fn
8842function index
8843@item vr
8844variable index
8845@item ky
8846key index
8847@item pg
8848program index
8849@item tp
8850data type index
8851@end table
8852
8853Write an @code{@@syncodeindex} command before or shortly after the
8854end-of-header line at the beginning of a Texinfo file. For example,
8855to merge a function index with a concept index, write the
8856following:@refill
8857
8858@example
8859@@syncodeindex fn cp
8860@end example
8861
8862@noindent
8863This will cause all entries designated for the function index to merge
8864in with the concept index instead.@refill
8865
8866To merge both a variables index and a function index into a concept
8867index, write the following:@refill
8868
8869@example
8870@group
8871@@syncodeindex vr cp
8872@@syncodeindex fn cp
8873@end group
8874@end example
8875
8876@cindex Fonts for indices
8877The @code{@@syncodeindex} command puts all the entries from the `from'
8878index (the redirected index) into the @code{@@code} font, overriding
8879whatever default font is used by the index to which the entries are
8880now directed. This way, if you direct function names from a function
8881index into a concept index, all the function names are printed in the
8882@code{@@code} font as you would expect.@refill
8883
8884@node synindex, , syncodeindex, Combining Indices
8885@subsection @code{@@synindex}
8886@findex synindex
8887
8888The @code{@@synindex} command is nearly the same as the
8889@code{@@syncodeindex} command, except that it does not put the
8890`from' index entries into the @code{@@code} font; rather it puts
8891them in the roman font. Thus, you use @code{@@synindex} when you
8892merge a concept index into a function index.@refill
8893
8894@xref{Printing Indices & Menus}, for information about printing an index
8895at the end of a book or creating an index menu in an Info file.@refill
8896
8897@node New Indices, , Combining Indices, Indices
8898@section Defining New Indices
8899@cindex Defining new indices
8900@cindex Indices, defining new
8901@cindex New index defining
8902@findex defindex
8903@findex defcodeindex
8904
8905In addition to the predefined indices, you may use the
8906@code{@@defindex} and @code{@@defcodeindex} commands to define new
8907indices. These commands create new indexing @@-commands with which
8908you mark index entries. The @code{@@defindex }command is used like
8909this:@refill
8910
8911@example
8912@@defindex @var{name}
8913@end example
8914
8915The name of an index should be a two letter word, such as @samp{au}.
8916For example:@refill
8917
8918@example
8919@@defindex au
8920@end example
8921
8922This defines a new index, called the @samp{au} index. At the same
8923time, it creates a new indexing command, @code{@@auindex}, that you
8924can use to make index entries. Use the new indexing command just as
8925you would use a predefined indexing command.@refill
8926
8927For example, here is a section heading followed by a concept index
8928entry and two @samp{au} index entries.@refill
8929
8930@example
8931@@section Cognitive Semantics
8932@@cindex kinesthetic image schemas
8933@@auindex Johnson, Mark
8934@@auindex Lakoff, George
8935@end example
8936
8937@noindent
8938(Evidently, @samp{au} serves here as an abbreviation for ``author''.)
8939Texinfo constructs the new indexing command by concatenating the name
8940of the index with @samp{index}; thus, defining an @samp{au} index
8941leads to the automatic creation of an @code{@@auindex} command.@refill
8942
8943Use the @code{@@printindex} command to print the index, as you do with
8944the predefined indices. For example:@refill
8945
8946@example
8947@group
8948@@node Author Index, Subject Index, , Top
8949@@unnumbered Author Index
8950
8951@@printindex au
8952@end group
8953@end example
8954
8955The @code{@@defcodeindex} is like the @code{@@defindex} command, except
8956that, in the printed output, it prints entries in an @code{@@code} font
8957instead of a roman font. Thus, it parallels the @code{@@findex} command
8958rather than the @code{@@cindex} command.@refill
8959
8960You should define new indices within or right after the end-of-header
8961line of a Texinfo file, before any @code{@@synindex} or
| 8883@subsection @code{@@syncodeindex}
8884@findex syncodeindex
8885
8886When you want to combine functions and concepts into one index, you
8887should index the functions with @code{@@findex} and index the concepts
8888with @code{@@cindex}, and use the @code{@@syncodeindex} command to
8889redirect the function index entries into the concept index.@refill
8890@findex syncodeindex
8891
8892The @code{@@syncodeindex} command takes two arguments; they are the name
8893of the index to redirect, and the name of the index to redirect it to.
8894The template looks like this:@refill
8895
8896@example
8897@@syncodeindex @var{from} @var{to}
8898@end example
8899
8900@cindex Predefined names for indices
8901@cindex Two letter names for indices
8902@cindex Indices, two letter names
8903@cindex Names for indices
8904For this purpose, the indices are given two-letter names:@refill
8905
8906@table @samp
8907@item cp
8908concept index
8909@item fn
8910function index
8911@item vr
8912variable index
8913@item ky
8914key index
8915@item pg
8916program index
8917@item tp
8918data type index
8919@end table
8920
8921Write an @code{@@syncodeindex} command before or shortly after the
8922end-of-header line at the beginning of a Texinfo file. For example,
8923to merge a function index with a concept index, write the
8924following:@refill
8925
8926@example
8927@@syncodeindex fn cp
8928@end example
8929
8930@noindent
8931This will cause all entries designated for the function index to merge
8932in with the concept index instead.@refill
8933
8934To merge both a variables index and a function index into a concept
8935index, write the following:@refill
8936
8937@example
8938@group
8939@@syncodeindex vr cp
8940@@syncodeindex fn cp
8941@end group
8942@end example
8943
8944@cindex Fonts for indices
8945The @code{@@syncodeindex} command puts all the entries from the `from'
8946index (the redirected index) into the @code{@@code} font, overriding
8947whatever default font is used by the index to which the entries are
8948now directed. This way, if you direct function names from a function
8949index into a concept index, all the function names are printed in the
8950@code{@@code} font as you would expect.@refill
8951
8952@node synindex, , syncodeindex, Combining Indices
8953@subsection @code{@@synindex}
8954@findex synindex
8955
8956The @code{@@synindex} command is nearly the same as the
8957@code{@@syncodeindex} command, except that it does not put the
8958`from' index entries into the @code{@@code} font; rather it puts
8959them in the roman font. Thus, you use @code{@@synindex} when you
8960merge a concept index into a function index.@refill
8961
8962@xref{Printing Indices & Menus}, for information about printing an index
8963at the end of a book or creating an index menu in an Info file.@refill
8964
8965@node New Indices, , Combining Indices, Indices
8966@section Defining New Indices
8967@cindex Defining new indices
8968@cindex Indices, defining new
8969@cindex New index defining
8970@findex defindex
8971@findex defcodeindex
8972
8973In addition to the predefined indices, you may use the
8974@code{@@defindex} and @code{@@defcodeindex} commands to define new
8975indices. These commands create new indexing @@-commands with which
8976you mark index entries. The @code{@@defindex }command is used like
8977this:@refill
8978
8979@example
8980@@defindex @var{name}
8981@end example
8982
8983The name of an index should be a two letter word, such as @samp{au}.
8984For example:@refill
8985
8986@example
8987@@defindex au
8988@end example
8989
8990This defines a new index, called the @samp{au} index. At the same
8991time, it creates a new indexing command, @code{@@auindex}, that you
8992can use to make index entries. Use the new indexing command just as
8993you would use a predefined indexing command.@refill
8994
8995For example, here is a section heading followed by a concept index
8996entry and two @samp{au} index entries.@refill
8997
8998@example
8999@@section Cognitive Semantics
9000@@cindex kinesthetic image schemas
9001@@auindex Johnson, Mark
9002@@auindex Lakoff, George
9003@end example
9004
9005@noindent
9006(Evidently, @samp{au} serves here as an abbreviation for ``author''.)
9007Texinfo constructs the new indexing command by concatenating the name
9008of the index with @samp{index}; thus, defining an @samp{au} index
9009leads to the automatic creation of an @code{@@auindex} command.@refill
9010
9011Use the @code{@@printindex} command to print the index, as you do with
9012the predefined indices. For example:@refill
9013
9014@example
9015@group
9016@@node Author Index, Subject Index, , Top
9017@@unnumbered Author Index
9018
9019@@printindex au
9020@end group
9021@end example
9022
9023The @code{@@defcodeindex} is like the @code{@@defindex} command, except
9024that, in the printed output, it prints entries in an @code{@@code} font
9025instead of a roman font. Thus, it parallels the @code{@@findex} command
9026rather than the @code{@@cindex} command.@refill
9027
9028You should define new indices within or right after the end-of-header
9029line of a Texinfo file, before any @code{@@synindex} or
|
8962@code{@@syncodeindex} commands (@pxref{Header}).@refill
| 9030@code{@@syncodeindex} commands (@pxref{Texinfo File Header}).
|
8963
| 9031
|
| 9032
|
8964@node Insertions
8965@chapter Special Insertions
8966@cindex Inserting special characters and symbols
8967@cindex Special insertions
8968
8969Texinfo provides several commands for inserting characters that have
8970special meaning in Texinfo, such as braces, and for other graphic
8971elements that do not correspond to simple characters you can type.
8972
8973@iftex
8974These are:
8975
8976@itemize @bullet
8977@item Braces and @samp{@@}.
8978@item Whitespace within and around a sentence.
8979@item Accents.
8980@item Dots and bullets.
8981@item The @TeX{} logo and the copyright symbol.
8982@item The pounds currency symbol.
8983@item The minus sign.
8984@item Mathematical expressions.
8985@item Glyphs for evaluation, macros, errors, etc.
8986@item Footnotes.
8987@item Images.
8988@end itemize
8989@end iftex
8990
8991@menu
8992* Braces Atsigns:: How to insert braces, @samp{@@}.
8993* Inserting Space:: How to insert the right amount of space
8994 within a sentence.
8995* Inserting Accents:: How to insert accents and special characters.
8996* Dots Bullets:: How to insert dots and bullets.
8997* TeX and copyright:: How to insert the @TeX{} logo
8998 and the copyright symbol.
8999* pounds:: How to insert the pounds currency symbol.
9000* minus:: How to insert a minus sign.
9001* math:: How to format a mathematical expression.
9002* Glyphs:: How to indicate results of evaluation,
9003 expansion of macros, errors, etc.
9004* Footnotes:: How to include footnotes.
9005* Images:: How to include graphics.
9006@end menu
9007
9008
9009@node Braces Atsigns, Inserting Space, Insertions, Insertions
9010@section Inserting @@ and Braces
9011@cindex Inserting @@, braces
9012@cindex Braces, inserting
9013@cindex Special characters, commands to insert
9014@cindex Commands to insert special characters
9015
9016@samp{@@} and curly braces are special characters in Texinfo. To insert
9017these characters so they appear in text, you must put an @samp{@@} in
9018front of these characters to prevent Texinfo from misinterpreting
9019them.
9020
9021Do not put braces after any of these commands; they are not
9022necessary.
9023
9024@menu
9025* Inserting An Atsign:: How to insert @samp{@@}.
9026* Inserting Braces:: How to insert @samp{@{} and @samp{@}}.
9027@end menu
9028
9029@node Inserting An Atsign, Inserting Braces, Braces Atsigns, Braces Atsigns
9030@subsection Inserting @samp{@@} with @@@@
| 9033@node Insertions
9034@chapter Special Insertions
9035@cindex Inserting special characters and symbols
9036@cindex Special insertions
9037
9038Texinfo provides several commands for inserting characters that have
9039special meaning in Texinfo, such as braces, and for other graphic
9040elements that do not correspond to simple characters you can type.
9041
9042@iftex
9043These are:
9044
9045@itemize @bullet
9046@item Braces and @samp{@@}.
9047@item Whitespace within and around a sentence.
9048@item Accents.
9049@item Dots and bullets.
9050@item The @TeX{} logo and the copyright symbol.
9051@item The pounds currency symbol.
9052@item The minus sign.
9053@item Mathematical expressions.
9054@item Glyphs for evaluation, macros, errors, etc.
9055@item Footnotes.
9056@item Images.
9057@end itemize
9058@end iftex
9059
9060@menu
9061* Braces Atsigns:: How to insert braces, @samp{@@}.
9062* Inserting Space:: How to insert the right amount of space
9063 within a sentence.
9064* Inserting Accents:: How to insert accents and special characters.
9065* Dots Bullets:: How to insert dots and bullets.
9066* TeX and copyright:: How to insert the @TeX{} logo
9067 and the copyright symbol.
9068* pounds:: How to insert the pounds currency symbol.
9069* minus:: How to insert a minus sign.
9070* math:: How to format a mathematical expression.
9071* Glyphs:: How to indicate results of evaluation,
9072 expansion of macros, errors, etc.
9073* Footnotes:: How to include footnotes.
9074* Images:: How to include graphics.
9075@end menu
9076
9077
9078@node Braces Atsigns, Inserting Space, Insertions, Insertions
9079@section Inserting @@ and Braces
9080@cindex Inserting @@, braces
9081@cindex Braces, inserting
9082@cindex Special characters, commands to insert
9083@cindex Commands to insert special characters
9084
9085@samp{@@} and curly braces are special characters in Texinfo. To insert
9086these characters so they appear in text, you must put an @samp{@@} in
9087front of these characters to prevent Texinfo from misinterpreting
9088them.
9089
9090Do not put braces after any of these commands; they are not
9091necessary.
9092
9093@menu
9094* Inserting An Atsign:: How to insert @samp{@@}.
9095* Inserting Braces:: How to insert @samp{@{} and @samp{@}}.
9096@end menu
9097
9098@node Inserting An Atsign, Inserting Braces, Braces Atsigns, Braces Atsigns
9099@subsection Inserting @samp{@@} with @@@@
|
9031@findex @@ @r{(single @samp{@@})}
| 9100@findex @@ @r{(literal @samp{@@})}
|
9032
9033@code{@@@@} stands for a single @samp{@@} in either printed or Info
9034output.
9035
9036Do not put braces after an @code{@@@@} command.
9037
9038
9039@node Inserting Braces
9040@subsection Inserting @samp{@{} and @samp{@}}with @@@{ and @@@}
| 9101
9102@code{@@@@} stands for a single @samp{@@} in either printed or Info
9103output.
9104
9105Do not put braces after an @code{@@@@} command.
9106
9107
9108@node Inserting Braces
9109@subsection Inserting @samp{@{} and @samp{@}}with @@@{ and @@@}
|
9041@findex @{ @r{(single @samp{@{})}
9042@findex @} @r{(single @samp{@}})}
| 9110@findex @{ @r{(literal @samp{@{})}
9111@findex @} @r{(literal @samp{@}})}
|
9043
9044@code{@@@{} stands for a single @samp{@{} in either printed or Info
9045output.
9046
9047@code{@@@}} stands for a single @samp{@}} in either printed or Info
9048output.
9049
9050Do not put braces after either an @code{@@@{} or an @code{@@@}}
9051command.
9052
9053
9054@node Inserting Space
9055@section Inserting Space
9056
9057@cindex Inserting space
9058@cindex Spacing, inserting
9059The following sections describe commands that control spacing of various
9060kinds within and after sentences.
9061
9062@menu
9063* Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
9064* Ending a Sentence:: Sometimes it does.
9065* Multiple Spaces:: Inserting multiple spaces.
9066* dmn:: How to format a dimension.
9067@end menu
9068
9069
9070@node Not Ending a Sentence
9071@subsection Not Ending a Sentence
9072
9073@cindex Not ending a sentence
9074@cindex Sentence non-ending punctuation
9075@cindex Periods, inserting
9076Depending on whether a period or exclamation point or question mark is
9077inside or at the end of a sentence, less or more space is inserted after
9078a period in a typeset manual. Since it is not always possible
9079to determine when a period ends a sentence and when it is used
9080in an abbreviation, special commands are needed in some circumstances.
9081Usually, Texinfo can guess how to handle periods, so you do not need to
9082use the special commands; you just enter a period as you would if you
9083were using a typewriter, which means you put two spaces after the
9084period, question mark, or exclamation mark that ends a sentence.
9085
9086@findex <colon> @r{(suppress widening)}
9087Use the @code{@@:}@: command after a period, question mark,
9088exclamation mark, or colon that should not be followed by extra space.
9089For example, use @code{@@:}@: after periods that end abbreviations
9090which are not at the ends of sentences.
9091
9092For example,
9093
9094@example
9095The s.o.p.@@: has three parts @dots{}
9096The s.o.p. has three parts @dots{}
9097@end example
9098
9099@noindent
9100@ifinfo
9101produces
9102@end ifinfo
9103@iftex
9104produces the following. If you look carefully at this printed output,
9105you will see a little more whitespace after @samp{s.o.p.} in the second
9106line.@refill
9107@end iftex
9108
9109@quotation
9110The s.o.p.@: has three parts @dots{}@*
9111The s.o.p. has three parts @dots{}
9112@end quotation
9113
9114@noindent
9115(Incidentally, @samp{s.o.p.} is an abbreviation for ``Standard Operating
9116Procedure''.)
9117
9118@code{@@:} has no effect on the Info output. Do not put braces after
9119@code{@@:}.
9120
9121
9122@node Ending a Sentence, Multiple Spaces, Not Ending a Sentence, Inserting Space
9123@subsection Ending a Sentence
9124
9125@cindex Ending a Sentence
9126@cindex Sentence ending punctuation
9127
9128@findex . @r{(end of sentence)}
9129@findex ! @r{(end of sentence)}
9130@findex ? @r{(end of sentence)}
9131Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an
9132exclamation point, and @code{@@?}@: instead of a question mark at the end
9133of a sentence that ends with a single capital letter. Otherwise, @TeX{}
9134will think the letter is an abbreviation and will not insert the correct
9135end-of-sentence spacing. Here is an example:
9136
9137@example
9138Give it to M.I.B. and to M.E.W@@. Also, give it to R.J.C@@.
9139Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
9140@end example
9141
9142@noindent
9143@ifinfo
9144produces
9145@end ifinfo
9146@iftex
9147produces the following. If you look carefully at this printed output,
9148you will see a little more whitespace after the @samp{W} in the first
9149line.
9150@end iftex
9151
9152@quotation
9153Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@.@*
9154Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
9155@end quotation
9156
9157In the Info file output, @code{@@.}@: is equivalent to a simple
9158@samp{.}; likewise for @code{@@!}@: and @code{@@?}@:.
9159
9160The meanings of @code{@@:} and @code{@@.}@: in Texinfo are designed to
9161work well with the Emacs sentence motion commands (@pxref{Sentences,,,
9162emacs, The GNU Emacs Manual}).
9163
9164Do not put braces after any of these commands.
9165
9166
9167@node Multiple Spaces, dmn, Ending a Sentence, Inserting Space
9168@subsection Multiple Spaces
9169
9170@cindex Multiple spaces
9171@cindex Whitespace, inserting
9172@cindex Space, inserting horizontal
9173@findex (space)
9174@findex (tab)
9175@findex (newline)
9176
9177Ordinarily, @TeX{} collapses multiple whitespace characters (space, tab,
9178and newline) into a single space. Info output, on the other hand,
9179preserves whitespace as you type it, except for changing a newline into
9180a space; this is why it is important to put two spaces at the end of
9181sentences in Texinfo documents.
9182
9183Occasionally, you may want to actually insert several consecutive
9184spaces, either for purposes of example (what your program does with
9185multiple spaces as input), or merely for purposes of appearance in
9186headings or lists. Texinfo supports three commands:
9187@code{@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all of
9188which insert a single space into the output. (Here,
9189@code{@@@kbd{SPACE}} represents an @samp{@@} character followed by a
9190space, i.e., @samp{@@ }, and @kbd{TAB} and @kbd{NL} represent the tab
9191character and end-of-line, i.e., when @samp{@@} is the last character on
9192a line.)
9193
9194For example,
9195@example
9196Spacey@@ @@ @@ @@
9197example.
9198@end example
9199
9200@noindent produces
9201
9202@example
9203Spacey@ @ @ @
9204example.
9205@end example
9206
9207Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by
9208@code{@@multitable} (@pxref{Multi-column Tables}).
9209
9210Do not follow any of these commands with braces.
9211
9212To produce a non-breakable space, see @ref{w, non-breakable space}.
9213
9214
9215@node dmn
9216@subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension
9217@cindex Thin space between number, dimension
9218@cindex Dimension formatting
9219@cindex Format a dimension
9220@findex dmn
9221
9222At times, you may want to write @samp{12@dmn{pt}} or
9223@samp{8.5@dmn{in}} with little or no space between the number and the
9224abbreviation for the dimension. You can use the @code{@@dmn} command
9225to do this. On seeing the command, @TeX{} inserts just enough space
9226for proper typesetting; the Info formatting commands insert no space
9227at all, since the Info file does not require it.
9228
9229To use the @code{@@dmn} command, write the number and then follow it
9230immediately, with no intervening space, by @code{@@dmn}, and then by
9231the dimension within braces. For example,
9232
9233@example
9234A4 paper is 8.27@@dmn@{in@} wide.
9235@end example
9236
9237@noindent
9238produces
9239
9240@quotation
9241A4 paper is 8.27@dmn{in} wide.
9242@end quotation
9243
9244Not everyone uses this style. Some people prefer @w{@samp{8.27 in.@@:}}
9245or @w{@samp{8.27 inches}} to @samp{8.27@@dmn@{in@}} in the Texinfo file.
9246In these cases, however, the formatters may insert a line break between
9247the number and the dimension, so use @code{@@w} (@pxref{w}). Also, if
9248you write a period after an abbreviation within a sentence, you should
9249write @samp{@@:} after the period to prevent @TeX{} from inserting extra
9250whitespace, as shown here. @xref{Not Ending a Sentence}.
9251
9252
9253@node Inserting Accents
9254@section Inserting Accents
9255
9256@cindex Inserting accents
9257@cindex Accents, inserting
9258@cindex Floating accents, inserting
9259
9260Here is a table with the commands Texinfo provides for inserting
9261floating accents. The commands with non-alphabetic names do not take
9262braces around their argument (which is taken to be the next character).
9263(Exception: @code{@@,} @emph{does} take braces around its argument.)
9264This is so as to make the source as convenient to type and read as
9265possible, since accented characters are very common in some languages.
9266
| 9112
9113@code{@@@{} stands for a single @samp{@{} in either printed or Info
9114output.
9115
9116@code{@@@}} stands for a single @samp{@}} in either printed or Info
9117output.
9118
9119Do not put braces after either an @code{@@@{} or an @code{@@@}}
9120command.
9121
9122
9123@node Inserting Space
9124@section Inserting Space
9125
9126@cindex Inserting space
9127@cindex Spacing, inserting
9128The following sections describe commands that control spacing of various
9129kinds within and after sentences.
9130
9131@menu
9132* Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
9133* Ending a Sentence:: Sometimes it does.
9134* Multiple Spaces:: Inserting multiple spaces.
9135* dmn:: How to format a dimension.
9136@end menu
9137
9138
9139@node Not Ending a Sentence
9140@subsection Not Ending a Sentence
9141
9142@cindex Not ending a sentence
9143@cindex Sentence non-ending punctuation
9144@cindex Periods, inserting
9145Depending on whether a period or exclamation point or question mark is
9146inside or at the end of a sentence, less or more space is inserted after
9147a period in a typeset manual. Since it is not always possible
9148to determine when a period ends a sentence and when it is used
9149in an abbreviation, special commands are needed in some circumstances.
9150Usually, Texinfo can guess how to handle periods, so you do not need to
9151use the special commands; you just enter a period as you would if you
9152were using a typewriter, which means you put two spaces after the
9153period, question mark, or exclamation mark that ends a sentence.
9154
9155@findex <colon> @r{(suppress widening)}
9156Use the @code{@@:}@: command after a period, question mark,
9157exclamation mark, or colon that should not be followed by extra space.
9158For example, use @code{@@:}@: after periods that end abbreviations
9159which are not at the ends of sentences.
9160
9161For example,
9162
9163@example
9164The s.o.p.@@: has three parts @dots{}
9165The s.o.p. has three parts @dots{}
9166@end example
9167
9168@noindent
9169@ifinfo
9170produces
9171@end ifinfo
9172@iftex
9173produces the following. If you look carefully at this printed output,
9174you will see a little more whitespace after @samp{s.o.p.} in the second
9175line.@refill
9176@end iftex
9177
9178@quotation
9179The s.o.p.@: has three parts @dots{}@*
9180The s.o.p. has three parts @dots{}
9181@end quotation
9182
9183@noindent
9184(Incidentally, @samp{s.o.p.} is an abbreviation for ``Standard Operating
9185Procedure''.)
9186
9187@code{@@:} has no effect on the Info output. Do not put braces after
9188@code{@@:}.
9189
9190
9191@node Ending a Sentence, Multiple Spaces, Not Ending a Sentence, Inserting Space
9192@subsection Ending a Sentence
9193
9194@cindex Ending a Sentence
9195@cindex Sentence ending punctuation
9196
9197@findex . @r{(end of sentence)}
9198@findex ! @r{(end of sentence)}
9199@findex ? @r{(end of sentence)}
9200Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an
9201exclamation point, and @code{@@?}@: instead of a question mark at the end
9202of a sentence that ends with a single capital letter. Otherwise, @TeX{}
9203will think the letter is an abbreviation and will not insert the correct
9204end-of-sentence spacing. Here is an example:
9205
9206@example
9207Give it to M.I.B. and to M.E.W@@. Also, give it to R.J.C@@.
9208Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
9209@end example
9210
9211@noindent
9212@ifinfo
9213produces
9214@end ifinfo
9215@iftex
9216produces the following. If you look carefully at this printed output,
9217you will see a little more whitespace after the @samp{W} in the first
9218line.
9219@end iftex
9220
9221@quotation
9222Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@.@*
9223Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
9224@end quotation
9225
9226In the Info file output, @code{@@.}@: is equivalent to a simple
9227@samp{.}; likewise for @code{@@!}@: and @code{@@?}@:.
9228
9229The meanings of @code{@@:} and @code{@@.}@: in Texinfo are designed to
9230work well with the Emacs sentence motion commands (@pxref{Sentences,,,
9231emacs, The GNU Emacs Manual}).
9232
9233Do not put braces after any of these commands.
9234
9235
9236@node Multiple Spaces, dmn, Ending a Sentence, Inserting Space
9237@subsection Multiple Spaces
9238
9239@cindex Multiple spaces
9240@cindex Whitespace, inserting
9241@cindex Space, inserting horizontal
9242@findex (space)
9243@findex (tab)
9244@findex (newline)
9245
9246Ordinarily, @TeX{} collapses multiple whitespace characters (space, tab,
9247and newline) into a single space. Info output, on the other hand,
9248preserves whitespace as you type it, except for changing a newline into
9249a space; this is why it is important to put two spaces at the end of
9250sentences in Texinfo documents.
9251
9252Occasionally, you may want to actually insert several consecutive
9253spaces, either for purposes of example (what your program does with
9254multiple spaces as input), or merely for purposes of appearance in
9255headings or lists. Texinfo supports three commands:
9256@code{@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all of
9257which insert a single space into the output. (Here,
9258@code{@@@kbd{SPACE}} represents an @samp{@@} character followed by a
9259space, i.e., @samp{@@ }, and @kbd{TAB} and @kbd{NL} represent the tab
9260character and end-of-line, i.e., when @samp{@@} is the last character on
9261a line.)
9262
9263For example,
9264@example
9265Spacey@@ @@ @@ @@
9266example.
9267@end example
9268
9269@noindent produces
9270
9271@example
9272Spacey@ @ @ @
9273example.
9274@end example
9275
9276Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by
9277@code{@@multitable} (@pxref{Multi-column Tables}).
9278
9279Do not follow any of these commands with braces.
9280
9281To produce a non-breakable space, see @ref{w, non-breakable space}.
9282
9283
9284@node dmn
9285@subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension
9286@cindex Thin space between number, dimension
9287@cindex Dimension formatting
9288@cindex Format a dimension
9289@findex dmn
9290
9291At times, you may want to write @samp{12@dmn{pt}} or
9292@samp{8.5@dmn{in}} with little or no space between the number and the
9293abbreviation for the dimension. You can use the @code{@@dmn} command
9294to do this. On seeing the command, @TeX{} inserts just enough space
9295for proper typesetting; the Info formatting commands insert no space
9296at all, since the Info file does not require it.
9297
9298To use the @code{@@dmn} command, write the number and then follow it
9299immediately, with no intervening space, by @code{@@dmn}, and then by
9300the dimension within braces. For example,
9301
9302@example
9303A4 paper is 8.27@@dmn@{in@} wide.
9304@end example
9305
9306@noindent
9307produces
9308
9309@quotation
9310A4 paper is 8.27@dmn{in} wide.
9311@end quotation
9312
9313Not everyone uses this style. Some people prefer @w{@samp{8.27 in.@@:}}
9314or @w{@samp{8.27 inches}} to @samp{8.27@@dmn@{in@}} in the Texinfo file.
9315In these cases, however, the formatters may insert a line break between
9316the number and the dimension, so use @code{@@w} (@pxref{w}). Also, if
9317you write a period after an abbreviation within a sentence, you should
9318write @samp{@@:} after the period to prevent @TeX{} from inserting extra
9319whitespace, as shown here. @xref{Not Ending a Sentence}.
9320
9321
9322@node Inserting Accents
9323@section Inserting Accents
9324
9325@cindex Inserting accents
9326@cindex Accents, inserting
9327@cindex Floating accents, inserting
9328
9329Here is a table with the commands Texinfo provides for inserting
9330floating accents. The commands with non-alphabetic names do not take
9331braces around their argument (which is taken to be the next character).
9332(Exception: @code{@@,} @emph{does} take braces around its argument.)
9333This is so as to make the source as convenient to type and read as
9334possible, since accented characters are very common in some languages.
9335
|
9267@findex "
| 9336@findex " @r{(umlaut accent)}
|
9268@cindex Umlaut accent
| 9337@cindex Umlaut accent
|
9269@findex '
| 9338@findex ' @r{(umlaut accent)}
|
9270@cindex Acute accent
| 9339@cindex Acute accent
|
9271@findex =
| 9340@findex = @r{(macron accent)}
|
9272@cindex Macron accent
| 9341@cindex Macron accent
|
9273@findex ^
| 9342@findex ^ @r{(circumflex accent)}
|
9274@cindex Circumflex accent
| 9343@cindex Circumflex accent
|
9275@findex `
| 9344@findex ` @r{(grave accent)}
|
9276@cindex Grave accent
| 9345@cindex Grave accent
|
9277@findex ~
| 9346@findex ~ @r{(tilde accent)}
|
9278@cindex Tilde accent
| 9347@cindex Tilde accent
|
9279@findex ,
| 9348@findex , @r{(cedilla accent)}
|
9280@cindex Cedilla accent
9281@findex dotaccent
9282@cindex Dot accent
| 9349@cindex Cedilla accent
9350@findex dotaccent
9351@cindex Dot accent
|
9283@findex H
| 9352@findex H @r{(Hungarian umlaut accent)}
|
9284@cindex Hungarian umlaut accent
9285@findex ringaccent
9286@cindex Ring accent
9287@findex tieaccent
9288@cindex Tie-after accent
| 9353@cindex Hungarian umlaut accent
9354@findex ringaccent
9355@cindex Ring accent
9356@findex tieaccent
9357@cindex Tie-after accent
|
9289@findex u
| 9358@findex u @r{(breve accent)}
|
9290@cindex Breve accent
9291@findex ubaraccent
9292@cindex Underbar accent
9293@findex udotaccent
9294@cindex Underdot accent
| 9359@cindex Breve accent
9360@findex ubaraccent
9361@cindex Underbar accent
9362@findex udotaccent
9363@cindex Underdot accent
|
9295@findex v
| 9364@findex v @r{(check accent)}
|
9296@cindex Check accent
9297@multitable {@@questiondown@{@}} {Output} {macron/overbar accent}
9298@item Command @tab Output @tab What
9299@item @t{@@"o} @tab @"o @tab umlaut accent
9300@item @t{@@'o} @tab @'o @tab acute accent
9301@item @t{@@,@{c@}} @tab @,{c} @tab cedilla accent
9302@item @t{@@=o} @tab @=o @tab macron/overbar accent
9303@item @t{@@^o} @tab @^o @tab circumflex accent
9304@item @t{@@`o} @tab @`o @tab grave accent
9305@item @t{@@~o} @tab @~o @tab tilde accent
9306@item @t{@@dotaccent@{o@}} @tab @dotaccent{o} @tab overdot accent
9307@item @t{@@H@{o@}} @tab @H{o} @tab long Hungarian umlaut
9308@item @t{@@ringaccent@{o@}} @tab @ringaccent{o} @tab ring accent
9309@item @t{@@tieaccent@{oo@}} @tab @tieaccent{oo} @tab tie-after accent
9310@item @t{@@u@{o@}} @tab @u{o} @tab breve accent
9311@item @t{@@ubaraccent@{o@}} @tab @ubaraccent{o} @tab underbar accent
9312@item @t{@@udotaccent@{o@}} @tab @udotaccent{o} @tab underdot accent
9313@item @t{@@v@{o@}} @tab @v{o} @tab hacek or check accent
9314@end multitable
9315
9316This table lists the Texinfo commands for inserting other characters
9317commonly used in languages other than English.
9318
9319@findex questiondown
9320@cindex @questiondown{}
9321@findex exclamdown
9322@cindex @exclamdown{}
9323@findex aa
9324@cindex @aa{}
9325@findex AA
9326@cindex @AA{}
9327@findex ae
9328@cindex @ae{}
9329@findex AE
9330@cindex @AE{}
9331@findex dotless
9332@cindex @dotless{i}
9333@cindex @dotless{j}
9334@cindex Dotless i, j
9335@findex l
9336@cindex @l{}
9337@findex L
9338@cindex @L{}
9339@findex o
9340@cindex @o{}
9341@findex O
9342@cindex @O{}
9343@findex oe
9344@cindex @oe{}
9345@findex OE
9346@cindex @OE{}
9347@findex ss
9348@cindex @ss{}
9349@cindex Es-zet
9350@cindex Sharp S
9351@cindex German S
9352@multitable {x@@questiondown@{@}} {oe,OE} {es-zet or sharp S}
9353@item @t{@@exclamdown@{@}} @tab @exclamdown{} @tab upside-down !
9354@item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ?
9355@item @t{@@aa@{@},@@AA@{@}} @tab @aa{},@AA{} @tab a,A with circle
9356@item @t{@@ae@{@},@@AE@{@}} @tab @ae{},@AE{} @tab ae,AE ligatures
9357@item @t{@@dotless@{i@}} @tab @dotless{i} @tab dotless i
9358@item @t{@@dotless@{j@}} @tab @dotless{j} @tab dotless j
9359@item @t{@@l@{@},@@L@{@}} @tab @l{},@L{} @tab suppressed-L,l
9360@item @t{@@o@{@},@@O@{@}} @tab @o{},@O{} @tab O,o with slash
9361@item @t{@@oe@{@},@@OE@{@}} @tab @oe{},@OE{} @tab oe,OE ligatures
9362@item @t{@@ss@{@}} @tab @ss{} @tab es-zet or sharp S
9363@end multitable
9364
9365
9366@node Dots Bullets
9367@section Inserting Ellipsis and Bullets
9368@cindex Dots, inserting
9369@cindex Bullets, inserting
9370@cindex Ellipsis, inserting
9371@cindex Inserting ellipsis
9372@cindex Inserting dots
9373@cindex Special typesetting commands
9374@cindex Typesetting commands for dots, etc.
9375
9376An @dfn{ellipsis} (a line of dots) is not typeset as a string of
9377periods, so a special command is used for ellipsis in Texinfo. The
9378@code{@@bullet} command is special, too. Each of these commands is
9379followed by a pair of braces, @samp{@{@}}, without any whitespace
9380between the name of the command and the braces. (You need to use braces
9381with these commands because you can use them next to other text; without
9382the braces, the formatters would be confused. @xref{Command Syntax, ,
9383@@-Command Syntax}, for further information.)@refill
9384
9385@menu
9386* dots:: How to insert dots @dots{}
9387* bullet:: How to insert a bullet.
9388@end menu
9389
9390
9391@node dots
9392@subsection @code{@@dots}@{@} (@dots{}) and @code{@@enddots}@{@} (@enddots{})
9393@findex dots
9394@findex enddots
9395@cindex Inserting dots
9396@cindex Dots, inserting
9397
9398Use the @code{@@dots@{@}} command to generate an ellipsis, which is
9399three dots in a row, appropriately spaced, like this: `@dots{}'. Do
9400not simply write three periods in the input file; that would work for
9401the Info file output, but would produce the wrong amount of space
9402between the periods in the printed manual.
9403
9404Similarly, the @code{@@enddots@{@}} command generates an
9405end-of-sentence ellipsis (four dots) @enddots{}
9406
9407@iftex
9408Here is an ellipsis: @dots{}
9409Here are three periods in a row: ...
9410
9411In printed output, the three periods in a row are closer together than
9412the dots in the ellipsis.
9413@end iftex
9414
9415
9416@node bullet
9417@subsection @code{@@bullet}@{@} (@bullet{})
9418@findex bullet
9419
9420Use the @code{@@bullet@{@}} command to generate a large round dot, or
9421the closest possible thing to one. In Info, an asterisk is used.@refill
9422
9423Here is a bullet: @bullet{}
9424
9425When you use @code{@@bullet} in @code{@@itemize}, you do not need to
9426type the braces, because @code{@@itemize} supplies them.
9427(@xref{itemize, , @code{@@itemize}}.)@refill
9428
9429
9430@node TeX and copyright, pounds, Dots Bullets, Insertions
9431@section Inserting @TeX{} and the Copyright Symbol
9432
9433The logo `@TeX{}' is typeset in a special fashion and it needs an
9434@@-command. The copyright symbol, `@copyright{}', is also special.
9435Each of these commands is followed by a pair of braces, @samp{@{@}},
9436without any whitespace between the name of the command and the
9437braces.@refill
9438
9439@menu
9440* tex:: How to insert the @TeX{} logo.
9441* copyright symbol:: How to use @code{@@copyright}@{@}.
9442@end menu
9443
9444
9445@node tex
9446@subsection @code{@@TeX}@{@} (@TeX{})
9447@findex tex (command)
9448
9449Use the @code{@@TeX@{@}} command to generate `@TeX{}'. In a printed
9450manual, this is a special logo that is different from three ordinary
9451letters. In Info, it just looks like @samp{TeX}. The
9452@code{@@TeX@{@}} command is unique among Texinfo commands in that the
9453@samp{T} and the @samp{X} are in upper case.@refill
9454
9455
9456@node copyright symbol
9457@subsection @code{@@copyright}@{@} (@copyright{})
9458@findex copyright
9459
9460Use the @code{@@copyright@{@}} command to generate `@copyright{}'. In
9461a printed manual, this is a @samp{c} inside a circle, and in Info,
9462this is @samp{(C)}.@refill
9463
9464
9465@node pounds, minus, TeX and copyright, Insertions
9466@section @code{@@pounds}@{@} (@pounds{}): Pounds Sterling
9467@findex pounds
9468
9469Use the @code{@@pounds@{@}} command to generate `@pounds{}'. In a
9470printed manual, this is the symbol for the currency pounds sterling.
9471In Info, it is a @samp{#}. Other currency symbols are unfortunately not
9472available.
9473
9474
9475@node minus, math, pounds, Insertions
9476@section @code{@@minus}@{@} (@minus{}): Inserting a Minus Sign
9477@findex minus
9478
9479@cindex em-dash
9480@cindex hyphen
9481Use the @code{@@minus@{@}} command to generate a minus sign. In a
9482fixed-width font, this is a single hyphen, but in a proportional font,
9483the symbol is the customary length for a minus sign---a little longer
9484than a hyphen, shorter than an em-dash:
9485
9486@display
9487@samp{@minus{}} is a minus sign generated with @samp{@@minus@{@}},
9488
9489`-' is a hyphen generated with the character @samp{-},
9490
9491`---' is an em-dash for text.
9492@end display
9493
9494@noindent
9495In the fixed-width font used by Info, @code{@@minus@{@}} is the same
9496as a hyphen.
9497
9498You should not use @code{@@minus@{@}} inside @code{@@code} or
9499@code{@@example} because the width distinction is not made in the
9500fixed-width font they use.
9501
9502When you use @code{@@minus} to specify the mark beginning each entry in
9503an itemized list, you do not need to type the braces
9504(@pxref{itemize, , @code{@@itemize}}.)
9505
9506
9507@node math
9508@section @code{@@math}: Inserting Mathematical Expressions
9509@findex math
9510@cindex Mathematical expressions
9511@cindex Formulas, mathematical
9512
9513You can write a short mathematical expression with the @code{@@math}
9514command. Write the mathematical expression between braces, like this:
9515
9516@example
9517@@math@{(a + b)(a + b) = a^2 + 2ab + b^2@}
9518@end example
9519
9520@iftex
9521@noindent This produces the following in @TeX{}:
9522
9523@display
9524@math{(a + b)(a + b) = a^2 + 2ab + b^2}
9525@end display
9526
9527@noindent and the following in Info:
9528@end iftex
9529@ifinfo
9530@noindent This produces the following in Info:
9531@end ifinfo
9532
9533@example
9534(a + b)(a + b) = a^2 + 2ab + b^2
9535@end example
9536
9537Thus, the @code{@@math} command has no effect on the Info output.
9538
9539@code{@@math} implies @code{@@tex}. This not only makes it possible to
9540write superscripts and subscripts (as in the above example), but also
9541allows you to use any of the plain @TeX{} math control sequences. It's
| 9365@cindex Check accent
9366@multitable {@@questiondown@{@}} {Output} {macron/overbar accent}
9367@item Command @tab Output @tab What
9368@item @t{@@"o} @tab @"o @tab umlaut accent
9369@item @t{@@'o} @tab @'o @tab acute accent
9370@item @t{@@,@{c@}} @tab @,{c} @tab cedilla accent
9371@item @t{@@=o} @tab @=o @tab macron/overbar accent
9372@item @t{@@^o} @tab @^o @tab circumflex accent
9373@item @t{@@`o} @tab @`o @tab grave accent
9374@item @t{@@~o} @tab @~o @tab tilde accent
9375@item @t{@@dotaccent@{o@}} @tab @dotaccent{o} @tab overdot accent
9376@item @t{@@H@{o@}} @tab @H{o} @tab long Hungarian umlaut
9377@item @t{@@ringaccent@{o@}} @tab @ringaccent{o} @tab ring accent
9378@item @t{@@tieaccent@{oo@}} @tab @tieaccent{oo} @tab tie-after accent
9379@item @t{@@u@{o@}} @tab @u{o} @tab breve accent
9380@item @t{@@ubaraccent@{o@}} @tab @ubaraccent{o} @tab underbar accent
9381@item @t{@@udotaccent@{o@}} @tab @udotaccent{o} @tab underdot accent
9382@item @t{@@v@{o@}} @tab @v{o} @tab hacek or check accent
9383@end multitable
9384
9385This table lists the Texinfo commands for inserting other characters
9386commonly used in languages other than English.
9387
9388@findex questiondown
9389@cindex @questiondown{}
9390@findex exclamdown
9391@cindex @exclamdown{}
9392@findex aa
9393@cindex @aa{}
9394@findex AA
9395@cindex @AA{}
9396@findex ae
9397@cindex @ae{}
9398@findex AE
9399@cindex @AE{}
9400@findex dotless
9401@cindex @dotless{i}
9402@cindex @dotless{j}
9403@cindex Dotless i, j
9404@findex l
9405@cindex @l{}
9406@findex L
9407@cindex @L{}
9408@findex o
9409@cindex @o{}
9410@findex O
9411@cindex @O{}
9412@findex oe
9413@cindex @oe{}
9414@findex OE
9415@cindex @OE{}
9416@findex ss
9417@cindex @ss{}
9418@cindex Es-zet
9419@cindex Sharp S
9420@cindex German S
9421@multitable {x@@questiondown@{@}} {oe,OE} {es-zet or sharp S}
9422@item @t{@@exclamdown@{@}} @tab @exclamdown{} @tab upside-down !
9423@item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ?
9424@item @t{@@aa@{@},@@AA@{@}} @tab @aa{},@AA{} @tab a,A with circle
9425@item @t{@@ae@{@},@@AE@{@}} @tab @ae{},@AE{} @tab ae,AE ligatures
9426@item @t{@@dotless@{i@}} @tab @dotless{i} @tab dotless i
9427@item @t{@@dotless@{j@}} @tab @dotless{j} @tab dotless j
9428@item @t{@@l@{@},@@L@{@}} @tab @l{},@L{} @tab suppressed-L,l
9429@item @t{@@o@{@},@@O@{@}} @tab @o{},@O{} @tab O,o with slash
9430@item @t{@@oe@{@},@@OE@{@}} @tab @oe{},@OE{} @tab oe,OE ligatures
9431@item @t{@@ss@{@}} @tab @ss{} @tab es-zet or sharp S
9432@end multitable
9433
9434
9435@node Dots Bullets
9436@section Inserting Ellipsis and Bullets
9437@cindex Dots, inserting
9438@cindex Bullets, inserting
9439@cindex Ellipsis, inserting
9440@cindex Inserting ellipsis
9441@cindex Inserting dots
9442@cindex Special typesetting commands
9443@cindex Typesetting commands for dots, etc.
9444
9445An @dfn{ellipsis} (a line of dots) is not typeset as a string of
9446periods, so a special command is used for ellipsis in Texinfo. The
9447@code{@@bullet} command is special, too. Each of these commands is
9448followed by a pair of braces, @samp{@{@}}, without any whitespace
9449between the name of the command and the braces. (You need to use braces
9450with these commands because you can use them next to other text; without
9451the braces, the formatters would be confused. @xref{Command Syntax, ,
9452@@-Command Syntax}, for further information.)@refill
9453
9454@menu
9455* dots:: How to insert dots @dots{}
9456* bullet:: How to insert a bullet.
9457@end menu
9458
9459
9460@node dots
9461@subsection @code{@@dots}@{@} (@dots{}) and @code{@@enddots}@{@} (@enddots{})
9462@findex dots
9463@findex enddots
9464@cindex Inserting dots
9465@cindex Dots, inserting
9466
9467Use the @code{@@dots@{@}} command to generate an ellipsis, which is
9468three dots in a row, appropriately spaced, like this: `@dots{}'. Do
9469not simply write three periods in the input file; that would work for
9470the Info file output, but would produce the wrong amount of space
9471between the periods in the printed manual.
9472
9473Similarly, the @code{@@enddots@{@}} command generates an
9474end-of-sentence ellipsis (four dots) @enddots{}
9475
9476@iftex
9477Here is an ellipsis: @dots{}
9478Here are three periods in a row: ...
9479
9480In printed output, the three periods in a row are closer together than
9481the dots in the ellipsis.
9482@end iftex
9483
9484
9485@node bullet
9486@subsection @code{@@bullet}@{@} (@bullet{})
9487@findex bullet
9488
9489Use the @code{@@bullet@{@}} command to generate a large round dot, or
9490the closest possible thing to one. In Info, an asterisk is used.@refill
9491
9492Here is a bullet: @bullet{}
9493
9494When you use @code{@@bullet} in @code{@@itemize}, you do not need to
9495type the braces, because @code{@@itemize} supplies them.
9496(@xref{itemize, , @code{@@itemize}}.)@refill
9497
9498
9499@node TeX and copyright, pounds, Dots Bullets, Insertions
9500@section Inserting @TeX{} and the Copyright Symbol
9501
9502The logo `@TeX{}' is typeset in a special fashion and it needs an
9503@@-command. The copyright symbol, `@copyright{}', is also special.
9504Each of these commands is followed by a pair of braces, @samp{@{@}},
9505without any whitespace between the name of the command and the
9506braces.@refill
9507
9508@menu
9509* tex:: How to insert the @TeX{} logo.
9510* copyright symbol:: How to use @code{@@copyright}@{@}.
9511@end menu
9512
9513
9514@node tex
9515@subsection @code{@@TeX}@{@} (@TeX{})
9516@findex tex (command)
9517
9518Use the @code{@@TeX@{@}} command to generate `@TeX{}'. In a printed
9519manual, this is a special logo that is different from three ordinary
9520letters. In Info, it just looks like @samp{TeX}. The
9521@code{@@TeX@{@}} command is unique among Texinfo commands in that the
9522@samp{T} and the @samp{X} are in upper case.@refill
9523
9524
9525@node copyright symbol
9526@subsection @code{@@copyright}@{@} (@copyright{})
9527@findex copyright
9528
9529Use the @code{@@copyright@{@}} command to generate `@copyright{}'. In
9530a printed manual, this is a @samp{c} inside a circle, and in Info,
9531this is @samp{(C)}.@refill
9532
9533
9534@node pounds, minus, TeX and copyright, Insertions
9535@section @code{@@pounds}@{@} (@pounds{}): Pounds Sterling
9536@findex pounds
9537
9538Use the @code{@@pounds@{@}} command to generate `@pounds{}'. In a
9539printed manual, this is the symbol for the currency pounds sterling.
9540In Info, it is a @samp{#}. Other currency symbols are unfortunately not
9541available.
9542
9543
9544@node minus, math, pounds, Insertions
9545@section @code{@@minus}@{@} (@minus{}): Inserting a Minus Sign
9546@findex minus
9547
9548@cindex em-dash
9549@cindex hyphen
9550Use the @code{@@minus@{@}} command to generate a minus sign. In a
9551fixed-width font, this is a single hyphen, but in a proportional font,
9552the symbol is the customary length for a minus sign---a little longer
9553than a hyphen, shorter than an em-dash:
9554
9555@display
9556@samp{@minus{}} is a minus sign generated with @samp{@@minus@{@}},
9557
9558`-' is a hyphen generated with the character @samp{-},
9559
9560`---' is an em-dash for text.
9561@end display
9562
9563@noindent
9564In the fixed-width font used by Info, @code{@@minus@{@}} is the same
9565as a hyphen.
9566
9567You should not use @code{@@minus@{@}} inside @code{@@code} or
9568@code{@@example} because the width distinction is not made in the
9569fixed-width font they use.
9570
9571When you use @code{@@minus} to specify the mark beginning each entry in
9572an itemized list, you do not need to type the braces
9573(@pxref{itemize, , @code{@@itemize}}.)
9574
9575
9576@node math
9577@section @code{@@math}: Inserting Mathematical Expressions
9578@findex math
9579@cindex Mathematical expressions
9580@cindex Formulas, mathematical
9581
9582You can write a short mathematical expression with the @code{@@math}
9583command. Write the mathematical expression between braces, like this:
9584
9585@example
9586@@math@{(a + b)(a + b) = a^2 + 2ab + b^2@}
9587@end example
9588
9589@iftex
9590@noindent This produces the following in @TeX{}:
9591
9592@display
9593@math{(a + b)(a + b) = a^2 + 2ab + b^2}
9594@end display
9595
9596@noindent and the following in Info:
9597@end iftex
9598@ifinfo
9599@noindent This produces the following in Info:
9600@end ifinfo
9601
9602@example
9603(a + b)(a + b) = a^2 + 2ab + b^2
9604@end example
9605
9606Thus, the @code{@@math} command has no effect on the Info output.
9607
9608@code{@@math} implies @code{@@tex}. This not only makes it possible to
9609write superscripts and subscripts (as in the above example), but also
9610allows you to use any of the plain @TeX{} math control sequences. It's
|
9542simplest to use @samp{\} instead of @samp{@@} for these commands. As
9543in:
| 9611conventional to use @samp{\} instead of @samp{@@} for these commands.
9612As in:
|
9544@example
9545@@math@{\sin 2\pi \equiv \cos 3\pi@}
9546@end example
9547
9548@iftex
9549@noindent which looks like this in @TeX{}:
9550@display
9551@math{\sin 2\pi \equiv \cos 3\pi}
9552@end display
9553
9554@noindent and
9555@end iftex
9556@noindent which looks like the input in Info and HTML:
9557@example
9558\sin 2\pi \equiv \cos 3\pi
9559@end example
9560
| 9613@example
9614@@math@{\sin 2\pi \equiv \cos 3\pi@}
9615@end example
9616
9617@iftex
9618@noindent which looks like this in @TeX{}:
9619@display
9620@math{\sin 2\pi \equiv \cos 3\pi}
9621@end display
9622
9623@noindent and
9624@end iftex
9625@noindent which looks like the input in Info and HTML:
9626@example
9627\sin 2\pi \equiv \cos 3\pi
9628@end example
9629
|
| 9630@findex \ @r{(literal \ in @code{@@math})}
9631Since @samp{\} is an escape character inside @code{@@math}, you can use
9632@code{@@\} to get a literal backslash (@code{\\} will work in @TeX{},
9633but you'll get the literal @samp{\\} in Info). @code{@@\} is not
9634defined outside of @code{@@math}, since a @samp{\} ordinarily produces a
9635literal @samp{\}.
9636
9637
|
9561@cindex Displayed equations
9562@cindex Equations, displayed
9563For displayed equations, you must at present use @TeX{} directly
9564(@pxref{Raw Formatter Commands}).
9565
9566
9567@node Glyphs
9568@section Glyphs for Examples
9569@cindex Glyphs
9570@cindex Examples, glyphs for
9571
9572In Texinfo, code is often illustrated in examples that are delimited
9573by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and
9574@code{@@end lisp}. In such examples, you can indicate the results of
9575evaluation or an expansion using @samp{@result{}} or
9576@samp{@expansion{}}. Likewise, there are commands to insert glyphs
9577to indicate
9578printed output, error messages, equivalence of expressions, and the
9579location of point.@refill
9580
9581The glyph-insertion commands do not need to be used within an example, but
9582most often they are. Every glyph-insertion command is followed by a pair of
9583left- and right-hand braces.@refill
9584
9585@menu
9586* Glyphs Summary::
9587* result:: How to show the result of expression.
9588* expansion:: How to indicate an expansion.
9589* Print Glyph:: How to indicate printed output.
9590* Error Glyph:: How to indicate an error message.
9591* Equivalence:: How to indicate equivalence.
9592* Point Glyph:: How to indicate the location of point.
9593@end menu
9594
9595
9596@node Glyphs Summary
9597@subsection Glyphs Summary
9598
9599Here are the different glyph commands:@refill
9600
9601@table @asis
9602@item @result{}
9603@code{@@result@{@}} points to the result of an expression.@refill
9604
9605@item @expansion{}
9606@code{@@expansion@{@}} shows the results of a macro expansion.@refill
9607
9608@item @print{}
9609@code{@@print@{@}} indicates printed output.@refill
9610
9611@item @error{}
9612@code{@@error@{@}} indicates that the following text is an error
9613message.@refill
9614
9615@item @equiv{}
9616@code{@@equiv@{@}} indicates the exact equivalence of two forms.@refill
9617
9618@item @point{}
9619@code{@@point@{@}} shows the location of point.@refill
9620@end table
9621
9622@menu
9623* result::
9624* expansion::
9625* Print Glyph::
9626* Error Glyph::
9627* Equivalence::
9628* Point Glyph::
9629@end menu
9630
9631
9632@node result
9633@subsection @code{@@result@{@}} (@result{}): Indicating Evaluation
9634@cindex Result of an expression
9635@cindex Indicating evaluation
9636@cindex Evaluation glyph
9637@cindex Value of an expression, indicating
9638@findex result
9639
9640Use the @code{@@result@{@}} command to indicate the result of
9641evaluating an expression.@refill
9642
9643@iftex
9644The @code{@@result@{@}} command is displayed as @samp{=>} in Info and
9645as @samp{@result{}} in the printed output.
9646@end iftex
9647@ifinfo
9648The @code{@@result@{@}} command is displayed as @samp{@result{}} in Info
9649and as a double stemmed arrow in the printed output.@refill
9650@end ifinfo
9651
9652Thus, the following,
9653
9654@lisp
9655(cdr '(1 2 3))
9656 @result{} (2 3)
9657@end lisp
9658
9659@noindent
9660may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''.
9661
9662
9663@node expansion, Print Glyph, result, Glyphs
9664@subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion
9665@cindex Expansion, indicating it
9666@findex expansion
9667
9668When an expression is a macro call, it expands into a new expression.
9669You can indicate the result of the expansion with the
9670@code{@@expansion@{@}} command.@refill
9671
9672@iftex
9673The @code{@@expansion@{@}} command is displayed as @samp{==>} in Info and
9674as @samp{@expansion{}} in the printed output.
9675@end iftex
9676@ifinfo
9677The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}}
9678in Info and as a long arrow with a flat base in the printed output.@refill
9679@end ifinfo
9680
9681@need 700
9682For example, the following
9683
9684@example
9685@group
9686@@lisp
9687(third '(a b c))
9688 @@expansion@{@} (car (cdr (cdr '(a b c))))
9689 @@result@{@} c
9690@@end lisp
9691@end group
9692@end example
9693
9694@noindent
9695produces
9696
9697@lisp
9698@group
9699(third '(a b c))
9700 @expansion{} (car (cdr (cdr '(a b c))))
9701 @result{} c
9702@end group
9703@end lisp
9704
9705@noindent
9706which may be read as:
9707
9708@quotation
9709@code{(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))};
9710the result of evaluating the expression is @code{c}.
9711@end quotation
9712
9713@noindent
9714Often, as in this case, an example looks better if the
9715@code{@@expansion@{@}} and @code{@@result@{@}} commands are indented
9716five spaces.@refill
9717
9718
9719@node Print Glyph, Error Glyph, expansion, Glyphs
9720@subsection @code{@@print@{@}} (@print{}): Indicating Printed Output
9721@cindex Printed output, indicating it
9722@findex print
9723
9724Sometimes an expression will print output during its execution. You
9725can indicate the printed output with the @code{@@print@{@}} command.@refill
9726
9727@iftex
9728The @code{@@print@{@}} command is displayed as @samp{-|} in Info and
9729as @samp{@print{}} in the printed output.
9730@end iftex
9731@ifinfo
9732The @code{@@print@{@}} command is displayed as @samp{@print{}} in Info
9733and similarly, as a horizontal dash butting against a vertical bar, in
9734the printed output.@refill
9735@end ifinfo
9736
9737In the following example, the printed text is indicated with
9738@samp{@print{}}, and the value of the expression follows on the
9739last line.@refill
9740
9741@lisp
9742@group
9743(progn (print 'foo) (print 'bar))
9744 @print{} foo
9745 @print{} bar
9746 @result{} bar
9747@end group
9748@end lisp
9749
9750@noindent
9751In a Texinfo source file, this example is written as follows:
9752
9753@lisp
9754@group
9755@@lisp
9756(progn (print 'foo) (print 'bar))
9757 @@print@{@} foo
9758 @@print@{@} bar
9759 @@result@{@} bar
9760@@end lisp
9761@end group
9762@end lisp
9763
9764
9765@node Error Glyph, Equivalence, Print Glyph, Glyphs
9766@subsection @code{@@error@{@}} (@error{}): Indicating an Error Message
9767@cindex Error message, indicating it
9768@findex error
9769
9770A piece of code may cause an error when you evaluate it. You can
9771designate the error message with the @code{@@error@{@}} command.@refill
9772
9773@iftex
9774The @code{@@error@{@}} command is displayed as @samp{error-->} in Info
9775and as @samp{@error{}} in the printed output.
9776@end iftex
9777@ifinfo
9778The @code{@@error@{@}} command is displayed as @samp{@error{}} in Info
9779and as the word `error' in a box in the printed output.@refill
9780@end ifinfo
9781
9782@need 700
9783Thus,
9784
9785@example
9786@@lisp
9787(+ 23 'x)
9788@@error@{@} Wrong type argument: integer-or-marker-p, x
9789@@end lisp
9790@end example
9791
9792@noindent
9793produces
9794
9795@lisp
9796(+ 23 'x)
9797@error{} Wrong type argument: integer-or-marker-p, x
9798@end lisp
9799
9800@noindent
9801This indicates that the following error message is printed
9802when you evaluate the expression:
9803
9804@lisp
9805Wrong type argument: integer-or-marker-p, x
9806@end lisp
9807
9808@samp{@error{}} itself is not part of the error message.
9809
9810
9811@node Equivalence, Point Glyph, Error Glyph, Glyphs
9812@subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence
9813@cindex Equivalence, indicating it
9814@findex equiv
9815
9816Sometimes two expressions produce identical results. You can indicate the
9817exact equivalence of two forms with the @code{@@equiv@{@}} command.@refill
9818
9819@iftex
9820The @code{@@equiv@{@}} command is displayed as @samp{==} in Info and
9821as @samp{@equiv{}} in the printed output.
9822@end iftex
9823@ifinfo
9824The @code{@@equiv@{@}} command is displayed as @samp{@equiv{}} in Info
9825and as a three parallel horizontal lines in the printed output.@refill
9826@end ifinfo
9827
9828Thus,
9829
9830@example
9831@@lisp
9832(make-sparse-keymap) @@equiv@{@} (list 'keymap)
9833@@end lisp
9834@end example
9835
9836@noindent
9837produces
9838
9839@lisp
9840(make-sparse-keymap) @equiv{} (list 'keymap)
9841@end lisp
9842
9843@noindent
9844This indicates that evaluating @code{(make-sparse-keymap)} produces
9845identical results to evaluating @code{(list 'keymap)}.
9846
9847
9848@node Point Glyph
9849@subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer
9850@cindex Point, indicating in a buffer
9851@findex point
9852
9853Sometimes you need to show an example of text in an Emacs buffer. In
9854such examples, the convention is to include the entire contents of the
9855buffer in question between two lines of dashes containing the buffer
9856name.@refill
9857
9858You can use the @samp{@@point@{@}} command to show the location of point
9859in the text in the buffer. (The symbol for point, of course, is not
9860part of the text in the buffer; it indicates the place @emph{between}
9861two characters where point is located.)@refill
9862
9863@iftex
9864The @code{@@point@{@}} command is displayed as @samp{-!-} in Info and
9865as @samp{@point{}} in the printed output.
9866@end iftex
9867@ifinfo
9868The @code{@@point@{@}} command is displayed as @samp{@point{}} in Info
9869and as a small five pointed star in the printed output.@refill
9870@end ifinfo
9871
9872The following example shows the contents of buffer @file{foo} before
9873and after evaluating a Lisp command to insert the word @code{changed}.@refill
9874
9875@example
9876@group
9877---------- Buffer: foo ----------
9878This is the @point{}contents of foo.
9879---------- Buffer: foo ----------
9880
9881@end group
9882@end example
9883
9884@example
9885@group
9886(insert "changed ")
9887 @result{} nil
9888---------- Buffer: foo ----------
9889This is the changed @point{}contents of foo.
9890---------- Buffer: foo ----------
9891
9892@end group
9893@end example
9894
9895In a Texinfo source file, the example is written like this:@refill
9896
9897@example
9898@@example
9899---------- Buffer: foo ----------
9900This is the @@point@{@}contents of foo.
9901---------- Buffer: foo ----------
9902
9903(insert "changed ")
9904 @@result@{@} nil
9905---------- Buffer: foo ----------
9906This is the changed @@point@{@}contents of foo.
9907---------- Buffer: foo ----------
9908@@end example
9909@end example
9910
9911
9912@node Footnotes
9913@section Footnotes
9914@cindex Footnotes
9915@findex footnote
9916
9917A @dfn{footnote} is for a reference that documents or elucidates the
9918primary text.@footnote{A footnote should complement or expand upon
9919the primary text, but a reader should not need to read a footnote to
9920understand the primary text. For a thorough discussion of footnotes,
9921see @cite{The Chicago Manual of Style}, which is published by the
9922University of Chicago Press.}
9923
9924@menu
9925* Footnote Commands:: How to write a footnote in Texinfo.
9926* Footnote Styles:: Controlling how footnotes appear in Info.
9927@end menu
9928
9929
9930@node Footnote Commands
9931@subsection Footnote Commands
9932
9933In Texinfo, footnotes are created with the @code{@@footnote} command.
9934This command is followed immediately by a left brace, then by the text
9935of the footnote, and then by a terminating right brace. Footnotes may
9936be of any length (they will be broken across pages if necessary), but
9937are usually short. The template is:
9938
9939@example
9940ordinary text@@footnote@{@var{text of footnote}@}
9941@end example
9942
9943As shown here, the @code{@@footnote} command should come right after the
9944text being footnoted, with no intervening space; otherwise, the footnote
9945marker might end up starting a line.
9946
9947For example, this clause is followed by a sample footnote@footnote{Here
9948is the sample footnote.}; in the Texinfo source, it looks like
9949this:
9950
9951@example
9952@dots{}a sample footnote@@footnote@{Here is the sample
9953footnote.@}; in the Texinfo source@dots{}
9954@end example
9955
9956As you can see, the source includes two punctuation marks next to each
9957other; in this case, @samp{.@};} is the sequence. This is normal (the
9958first ends the footnote and the second belongs to the sentence being
9959footnoted), so don't worry that it looks odd.
9960
9961In a printed manual or book, the reference mark for a footnote is a
9962small, superscripted number; the text of the footnote appears at the
9963bottom of the page, below a horizontal line.
9964
9965In Info, the reference mark for a footnote is a pair of parentheses
9966with the footnote number between them, like this: @samp{(1)}. The
9967reference mark is followed by a cross-reference link to the footnote's
9968text.
9969
9970In the HTML output, footnote references are marked with a small,
9971superscripted number which is rendered as a hypertext link to the
9972footnote text.
9973
9974By the way, footnotes in the argument of an @code{@@item} command for a
9975@code{@@table} must be on the same line as the @code{@@item}
9976(as usual). @xref{Two-column Tables}.
9977
9978
9979@node Footnote Styles
9980@subsection Footnote Styles
9981
9982Info has two footnote styles, which determine where the text of the
9983footnote is located:@refill
9984
9985@itemize @bullet
9986@cindex @samp{@r{End}} node footnote style
9987@item
9988In the `End' node style, all the footnotes for a single node
9989are placed at the end of that node. The footnotes are separated from
9990the rest of the node by a line of dashes with the word
9991@samp{Footnotes} within it. Each footnote begins with an
9992@samp{(@var{n})} reference mark.@refill
9993
9994@need 700
9995@noindent
9996Here is an example of a single footnote in the end of node style:@refill
9997
9998@example
9999@group
10000 --------- Footnotes ---------
10001
10002(1) Here is a sample footnote.
10003@end group
10004@end example
10005
10006@cindex @samp{@r{Separate}} footnote style
10007@item
10008In the `Separate' node style, all the footnotes for a single
10009node are placed in an automatically constructed node of
10010their own. In this style, a ``footnote reference'' follows
10011each @samp{(@var{n})} reference mark in the body of the
10012node. The footnote reference is actually a cross reference
10013which you use to reach the footnote node.@refill
10014
10015The name of the node with the footnotes is constructed
10016by appending @w{@samp{-Footnotes}} to the name of the node
10017that contains the footnotes. (Consequently, the footnotes'
10018node for the @file{Footnotes} node is
10019@w{@file{Footnotes-Footnotes}}!) The footnotes' node has an
10020`Up' node pointer that leads back to its parent node.@refill
10021
10022@noindent
10023Here is how the first footnote in this manual looks after being
10024formatted for Info in the separate node style:@refill
10025
10026@smallexample
10027@group
10028File: texinfo.info Node: Overview-Footnotes, Up: Overview
10029
10030(1) The first syllable of "Texinfo" is pronounced like "speck", not
10031"hex". @dots{}
10032@end group
10033@end smallexample
10034@end itemize
10035
10036A Texinfo file may be formatted into an Info file with either footnote
10037style.@refill
10038
10039@findex footnotestyle
10040Use the @code{@@footnotestyle} command to specify an Info file's
10041footnote style. Write this command at the beginning of a line followed
10042by an argument, either @samp{end} for the end node style or
10043@samp{separate} for the separate node style.
10044
10045@need 700
10046For example,
10047
10048@example
10049@@footnotestyle end
10050@end example
10051@noindent
10052or
10053@example
10054@@footnotestyle separate
10055@end example
10056
10057Write an @code{@@footnotestyle} command before or shortly after the
10058end-of-header line at the beginning of a Texinfo file. (If you
10059include the @code{@@footnotestyle} command between the start-of-header
10060and end-of-header lines, the region formatting commands will format
10061footnotes as specified.)@refill
10062
10063If you do not specify a footnote style, the formatting commands use
10064their default style. Currently, @code{texinfo-format-buffer} and
10065@code{texinfo-format-region} use the `separate' style and
10066@code{makeinfo} uses the `end' style.@refill
10067
10068@c !!! note: makeinfo's --footnote-style option overrides footnotestyle
10069@ignore
10070If you use @code{makeinfo} to create the Info file, the
10071@samp{--footnote-style} option determines which style is used,
10072@samp{end} for the end of node style or @samp{separate} for the
10073separate node style. Thus, to format the Texinfo manual in the
10074separate node style, you would use the following shell command:@refill
10075
10076@example
10077makeinfo --footnote-style=separate texinfo.texi
10078@end example
10079
10080@noindent
10081To format the Texinfo manual in the end of node style, you would
10082type:@refill
10083
10084@example
10085makeinfo --footnote-style=end texinfo.texi
10086@end example
10087@end ignore
10088@ignore
10089If you use @code{texinfo-format-buffer} or
10090@code{texinfo-format-region} to create the Info file, the value of the
10091@code{texinfo-footnote-style} variable controls the footnote style.
10092It can be either @samp{"separate"} for the separate node style or
10093@samp{"end"} for the end of node style. (You can change the value of
10094this variable with the @kbd{M-x edit-options} command (@pxref{Edit
10095Options, , Editing Variable Values, emacs, The GNU Emacs Manual}), or
10096with the @kbd{M-x set-variable} command (@pxref{Examining, , Examining
10097and Setting Variables, emacs, The GNU Emacs Manual}).@refill
10098
10099The @code{texinfo-footnote-style} variable also controls the style if
10100you use the @kbd{M-x makeinfo-region} or @kbd{M-x makeinfo-buffer}
10101command in Emacs.@refill
10102@end ignore
10103@ifinfo
10104This chapter contains two footnotes.@refill
10105@end ifinfo
10106
10107
10108@c this should be described with figures when we have them
10109@c perhaps in the quotation/example chapter.
10110@node Images
10111@section Inserting Images
10112
10113@cindex Images, inserting
10114@cindex Pictures, inserting
10115@findex image
10116
10117You can insert an image given in an external file with the
10118@code{@@image} command:
10119
10120@example
10121@@image@{@var{filename}, @r{[}@var{width}@r{]}, @r{[}@var{height}@r{]}, @r{[}@var{alttext}@r{]}, @r{[}@var{extension}@r{]}@}
10122@end example
10123
10124@cindex Formats for images
10125@cindex Image formats
10126The @var{filename} argument is mandatory, and must not have an
10127extension, because the different processors support different formats:
10128@itemize @bullet
10129@item
10130@TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript
10131format).
10132@item
10133@pindex pdftex@r{, and images}
10134PDF@TeX{} reads @file{@var{filename}.pdf} (Adobe's Portable Document Format).
10135@item
10136@code{makeinfo} uses @file{@var{filename}.txt} verbatim for
10137Info output (more or less as if it was an @code{@@example}).
10138@item
10139@code{makeinfo}
10140uses the optional fifth argument to @code{@@image} for the extension if
10141you supply it. For example:
10142
10143@pindex XPM image format
10144@example
10145@@image@{foo,,,,xpm@}
10146@end example
10147
10148@noindent
10149will cause @samp{makeinfo --html} to try @file{foo.xpm}.
10150
10151@cindex GIF, unsupported due to patents
10152@cindex PNG image format
10153@cindex JPG image format
10154If you do not supply the optional fifth argument, @samp{makeinfo
10155---html} first tries @file{@var{filename}.png}; if that does not exist,
10156it tries @file{@var{filename}.jpg}. If that does not exist either, it
10157complains. (We cannot support GIF format directly due to software
10158patents.)
10159@end itemize
10160
10161@cindex Width of images
10162@cindex Height of images
10163@cindex Aspect ratio of images
10164@cindex Distorting images
10165The optional @var{width} and @var{height} arguments specify the size to
10166scale the image to (they are ignored for Info output). If neither is
10167specified, the image is presented in its natural size (given in the
10168file); if only one is specified, the other is scaled proportionately;
10169and if both are specified, both are respected, thus possibly distorting
10170the original image by changing its aspect ratio.
10171
10172@cindex Dimensions and image sizes
10173The @var{width} and @var{height} may be specified using any valid @TeX{}
10174dimension, namely:
10175
10176@table @asis
10177@item pt
10178@cindex Points (dimension)
10179point (72.27pt = 1in)
10180@item pc
10181@cindex Picas
10182pica (1pc = 12pt)
10183@item bp
10184@cindex Big points
10185big point (72bp = 1in)
10186@item in
10187@cindex Inches
10188inch
10189@item cm
10190@cindex Centimeters
10191centimeter (2.54cm = 1in)
10192@item mm
10193@cindex Millimeters
10194millimeter (10mm = 1cm)
10195@item dd
10196@cindex Did@^ot points
10197did@^ot point (1157dd = 1238pt)
10198@item cc
10199@cindex Ciceros
10200cicero (1cc = 12dd)
10201@item sp
10202@cindex Scaled points
10203scaled point (65536sp = 1pt)
10204@end table
10205
10206@pindex ridt.eps
10207For example, the following will scale a file @file{ridt.eps} to one
10208inch vertically, with the width scaled proportionately:
10209
10210@example
10211@@image@{ridt,,1in@}
10212@end example
10213
10214@pindex epsf.tex
10215For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be
10216installed somewhere that @TeX{} can find it. (The standard location is
10217@file{@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a
10218root of your @TeX{} directory tree.) This file is included in the
10219Texinfo distribution and is also available from
10220@uref{ftp://tug.org/tex/epsf.tex}, among other places.
10221
10222@code{@@image} can be used within a line as well as for displayed
10223figures. Therefore, if you intend it to be displayed, be sure to leave
10224a blank line before the command, or the output will run into the
10225preceding text.
10226
10227@cindex alt attribute for images
10228@cindex alternate text for images
10229When producing html, @code{makeinfo} sets the @dfn{alt attribute} for
10230inline images to the optional fourth argument to @code{@@image}, if
10231supplied. If not supplied, @code{makeinfo} uses the full file name of
10232the image being displayed.
10233
10234
10235@node Breaks
10236@chapter Making and Preventing Breaks
10237@cindex Making line and page breaks
10238@cindex Preventing line and page breaks
10239
10240@cindex Line breaks
10241Usually, a Texinfo file is processed both by @TeX{} and by one of the
10242Info formatting commands. Line, paragraph, or page breaks sometimes
10243occur in the `wrong' place in one or other form of output. You must
10244ensure that text looks right both in the printed manual and in the
10245Info file.
10246
10247@cindex White space, excessive
10248@cindex Page breaks
10249For example, in a printed manual, page breaks may occur awkwardly in
10250the middle of an example; to prevent this, you can hold text together
10251using a grouping command that keeps the text from being split across
10252two pages. Conversely, you may want to force a page break where none
10253would occur normally. Fortunately, problems like these do not often
10254arise. When they do, use the break, break prevention, or pagination
10255commands.
10256
10257@menu
10258* Break Commands:: Cause and prevent splits.
10259* Line Breaks:: How to force a single line to use two lines.
10260* - and hyphenation:: How to tell @TeX{} about hyphenation points.
10261* w:: How to prevent unwanted line breaks.
10262* sp:: How to insert blank lines.
10263* page:: How to force the start of a new page.
10264* group:: How to prevent unwanted page breaks.
10265* need:: Another way to prevent unwanted page breaks.
10266@end menu
10267
10268
10269@node Break Commands, Line Breaks, Breaks, Breaks
10270@ifinfo
10271@heading Break Commands
10272@end ifinfo
10273
10274The break commands create or allow line and paragraph breaks:@refill
10275
10276@table @code
10277@item @@*
10278Force a line break.
10279
10280@item @@sp @var{n}
10281Skip @var{n} blank lines.@refill
10282
10283@item @@-
10284Insert a discretionary hyphen.
10285
10286@item @@hyphenation@{@var{hy-phen-a-ted words}@}
10287Define hyphen points in @var{hy-phen-a-ted words}.
10288@end table
10289
10290The line-break-prevention command holds text together all on one
10291line:@refill
10292
10293@table @code
10294@item @@w@{@var{text}@}
10295Prevent @var{text} from being split and hyphenated across two lines.@refill
10296@end table
10297@iftex
10298@sp 1
10299@end iftex
10300
10301The pagination commands apply only to printed output, since Info
10302files do not have pages.@refill
10303
10304@table @code
10305@item @@page
10306Start a new page in the printed manual.@refill
10307
10308@item @@group
10309Hold text together that must appear on one printed page.@refill
10310
10311@item @@need @var{mils}
10312Start a new printed page if not enough space on this one.@refill
10313@end table
10314
10315@node Line Breaks
10316@section @code{@@*}: Generate Line Breaks
10317@findex * @r{(force line break)}
10318@cindex Line breaks
10319@cindex Breaks in a line
10320
10321The @code{@@*} command forces a line break in both the printed manual and
10322in Info.@refill
10323
10324@need 700
10325For example,
10326
10327@example
10328This line @@* is broken @@*in two places.
10329@end example
10330
10331@noindent
10332produces
10333
10334@example
10335@group
10336This line
10337 is broken
10338in two places.
10339@end group
10340@end example
10341
10342@noindent
10343(Note that the space after the first @code{@@*} command is faithfully
10344carried down to the next line.)@refill
10345
10346@need 800
10347The @code{@@*} command is often used in a file's copyright page:@refill
10348
10349@example
10350@group
10351This is edition 2.0 of the Texinfo documentation,@@*
10352and is for @dots{}
10353@end group
10354@end example
10355
10356@noindent
10357In this case, the @code{@@*} command keeps @TeX{} from stretching the
10358line across the whole page in an ugly manner.@refill
10359
10360@quotation
10361@strong{Please note:} Do not write braces after an @code{@@*} command;
10362they are not needed.@refill
10363
10364Do not write an @code{@@refill} command at the end of a paragraph
10365containing an @code{@@*} command; it will cause the paragraph to be
10366refilled after the line break occurs, negating the effect of the line
10367break.@refill
10368@end quotation
10369
10370
10371@node - and hyphenation
10372@section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} hyphenate
10373
| 9638@cindex Displayed equations
9639@cindex Equations, displayed
9640For displayed equations, you must at present use @TeX{} directly
9641(@pxref{Raw Formatter Commands}).
9642
9643
9644@node Glyphs
9645@section Glyphs for Examples
9646@cindex Glyphs
9647@cindex Examples, glyphs for
9648
9649In Texinfo, code is often illustrated in examples that are delimited
9650by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and
9651@code{@@end lisp}. In such examples, you can indicate the results of
9652evaluation or an expansion using @samp{@result{}} or
9653@samp{@expansion{}}. Likewise, there are commands to insert glyphs
9654to indicate
9655printed output, error messages, equivalence of expressions, and the
9656location of point.@refill
9657
9658The glyph-insertion commands do not need to be used within an example, but
9659most often they are. Every glyph-insertion command is followed by a pair of
9660left- and right-hand braces.@refill
9661
9662@menu
9663* Glyphs Summary::
9664* result:: How to show the result of expression.
9665* expansion:: How to indicate an expansion.
9666* Print Glyph:: How to indicate printed output.
9667* Error Glyph:: How to indicate an error message.
9668* Equivalence:: How to indicate equivalence.
9669* Point Glyph:: How to indicate the location of point.
9670@end menu
9671
9672
9673@node Glyphs Summary
9674@subsection Glyphs Summary
9675
9676Here are the different glyph commands:@refill
9677
9678@table @asis
9679@item @result{}
9680@code{@@result@{@}} points to the result of an expression.@refill
9681
9682@item @expansion{}
9683@code{@@expansion@{@}} shows the results of a macro expansion.@refill
9684
9685@item @print{}
9686@code{@@print@{@}} indicates printed output.@refill
9687
9688@item @error{}
9689@code{@@error@{@}} indicates that the following text is an error
9690message.@refill
9691
9692@item @equiv{}
9693@code{@@equiv@{@}} indicates the exact equivalence of two forms.@refill
9694
9695@item @point{}
9696@code{@@point@{@}} shows the location of point.@refill
9697@end table
9698
9699@menu
9700* result::
9701* expansion::
9702* Print Glyph::
9703* Error Glyph::
9704* Equivalence::
9705* Point Glyph::
9706@end menu
9707
9708
9709@node result
9710@subsection @code{@@result@{@}} (@result{}): Indicating Evaluation
9711@cindex Result of an expression
9712@cindex Indicating evaluation
9713@cindex Evaluation glyph
9714@cindex Value of an expression, indicating
9715@findex result
9716
9717Use the @code{@@result@{@}} command to indicate the result of
9718evaluating an expression.@refill
9719
9720@iftex
9721The @code{@@result@{@}} command is displayed as @samp{=>} in Info and
9722as @samp{@result{}} in the printed output.
9723@end iftex
9724@ifinfo
9725The @code{@@result@{@}} command is displayed as @samp{@result{}} in Info
9726and as a double stemmed arrow in the printed output.@refill
9727@end ifinfo
9728
9729Thus, the following,
9730
9731@lisp
9732(cdr '(1 2 3))
9733 @result{} (2 3)
9734@end lisp
9735
9736@noindent
9737may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''.
9738
9739
9740@node expansion, Print Glyph, result, Glyphs
9741@subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion
9742@cindex Expansion, indicating it
9743@findex expansion
9744
9745When an expression is a macro call, it expands into a new expression.
9746You can indicate the result of the expansion with the
9747@code{@@expansion@{@}} command.@refill
9748
9749@iftex
9750The @code{@@expansion@{@}} command is displayed as @samp{==>} in Info and
9751as @samp{@expansion{}} in the printed output.
9752@end iftex
9753@ifinfo
9754The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}}
9755in Info and as a long arrow with a flat base in the printed output.@refill
9756@end ifinfo
9757
9758@need 700
9759For example, the following
9760
9761@example
9762@group
9763@@lisp
9764(third '(a b c))
9765 @@expansion@{@} (car (cdr (cdr '(a b c))))
9766 @@result@{@} c
9767@@end lisp
9768@end group
9769@end example
9770
9771@noindent
9772produces
9773
9774@lisp
9775@group
9776(third '(a b c))
9777 @expansion{} (car (cdr (cdr '(a b c))))
9778 @result{} c
9779@end group
9780@end lisp
9781
9782@noindent
9783which may be read as:
9784
9785@quotation
9786@code{(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))};
9787the result of evaluating the expression is @code{c}.
9788@end quotation
9789
9790@noindent
9791Often, as in this case, an example looks better if the
9792@code{@@expansion@{@}} and @code{@@result@{@}} commands are indented
9793five spaces.@refill
9794
9795
9796@node Print Glyph, Error Glyph, expansion, Glyphs
9797@subsection @code{@@print@{@}} (@print{}): Indicating Printed Output
9798@cindex Printed output, indicating it
9799@findex print
9800
9801Sometimes an expression will print output during its execution. You
9802can indicate the printed output with the @code{@@print@{@}} command.@refill
9803
9804@iftex
9805The @code{@@print@{@}} command is displayed as @samp{-|} in Info and
9806as @samp{@print{}} in the printed output.
9807@end iftex
9808@ifinfo
9809The @code{@@print@{@}} command is displayed as @samp{@print{}} in Info
9810and similarly, as a horizontal dash butting against a vertical bar, in
9811the printed output.@refill
9812@end ifinfo
9813
9814In the following example, the printed text is indicated with
9815@samp{@print{}}, and the value of the expression follows on the
9816last line.@refill
9817
9818@lisp
9819@group
9820(progn (print 'foo) (print 'bar))
9821 @print{} foo
9822 @print{} bar
9823 @result{} bar
9824@end group
9825@end lisp
9826
9827@noindent
9828In a Texinfo source file, this example is written as follows:
9829
9830@lisp
9831@group
9832@@lisp
9833(progn (print 'foo) (print 'bar))
9834 @@print@{@} foo
9835 @@print@{@} bar
9836 @@result@{@} bar
9837@@end lisp
9838@end group
9839@end lisp
9840
9841
9842@node Error Glyph, Equivalence, Print Glyph, Glyphs
9843@subsection @code{@@error@{@}} (@error{}): Indicating an Error Message
9844@cindex Error message, indicating it
9845@findex error
9846
9847A piece of code may cause an error when you evaluate it. You can
9848designate the error message with the @code{@@error@{@}} command.@refill
9849
9850@iftex
9851The @code{@@error@{@}} command is displayed as @samp{error-->} in Info
9852and as @samp{@error{}} in the printed output.
9853@end iftex
9854@ifinfo
9855The @code{@@error@{@}} command is displayed as @samp{@error{}} in Info
9856and as the word `error' in a box in the printed output.@refill
9857@end ifinfo
9858
9859@need 700
9860Thus,
9861
9862@example
9863@@lisp
9864(+ 23 'x)
9865@@error@{@} Wrong type argument: integer-or-marker-p, x
9866@@end lisp
9867@end example
9868
9869@noindent
9870produces
9871
9872@lisp
9873(+ 23 'x)
9874@error{} Wrong type argument: integer-or-marker-p, x
9875@end lisp
9876
9877@noindent
9878This indicates that the following error message is printed
9879when you evaluate the expression:
9880
9881@lisp
9882Wrong type argument: integer-or-marker-p, x
9883@end lisp
9884
9885@samp{@error{}} itself is not part of the error message.
9886
9887
9888@node Equivalence, Point Glyph, Error Glyph, Glyphs
9889@subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence
9890@cindex Equivalence, indicating it
9891@findex equiv
9892
9893Sometimes two expressions produce identical results. You can indicate the
9894exact equivalence of two forms with the @code{@@equiv@{@}} command.@refill
9895
9896@iftex
9897The @code{@@equiv@{@}} command is displayed as @samp{==} in Info and
9898as @samp{@equiv{}} in the printed output.
9899@end iftex
9900@ifinfo
9901The @code{@@equiv@{@}} command is displayed as @samp{@equiv{}} in Info
9902and as a three parallel horizontal lines in the printed output.@refill
9903@end ifinfo
9904
9905Thus,
9906
9907@example
9908@@lisp
9909(make-sparse-keymap) @@equiv@{@} (list 'keymap)
9910@@end lisp
9911@end example
9912
9913@noindent
9914produces
9915
9916@lisp
9917(make-sparse-keymap) @equiv{} (list 'keymap)
9918@end lisp
9919
9920@noindent
9921This indicates that evaluating @code{(make-sparse-keymap)} produces
9922identical results to evaluating @code{(list 'keymap)}.
9923
9924
9925@node Point Glyph
9926@subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer
9927@cindex Point, indicating in a buffer
9928@findex point
9929
9930Sometimes you need to show an example of text in an Emacs buffer. In
9931such examples, the convention is to include the entire contents of the
9932buffer in question between two lines of dashes containing the buffer
9933name.@refill
9934
9935You can use the @samp{@@point@{@}} command to show the location of point
9936in the text in the buffer. (The symbol for point, of course, is not
9937part of the text in the buffer; it indicates the place @emph{between}
9938two characters where point is located.)@refill
9939
9940@iftex
9941The @code{@@point@{@}} command is displayed as @samp{-!-} in Info and
9942as @samp{@point{}} in the printed output.
9943@end iftex
9944@ifinfo
9945The @code{@@point@{@}} command is displayed as @samp{@point{}} in Info
9946and as a small five pointed star in the printed output.@refill
9947@end ifinfo
9948
9949The following example shows the contents of buffer @file{foo} before
9950and after evaluating a Lisp command to insert the word @code{changed}.@refill
9951
9952@example
9953@group
9954---------- Buffer: foo ----------
9955This is the @point{}contents of foo.
9956---------- Buffer: foo ----------
9957
9958@end group
9959@end example
9960
9961@example
9962@group
9963(insert "changed ")
9964 @result{} nil
9965---------- Buffer: foo ----------
9966This is the changed @point{}contents of foo.
9967---------- Buffer: foo ----------
9968
9969@end group
9970@end example
9971
9972In a Texinfo source file, the example is written like this:@refill
9973
9974@example
9975@@example
9976---------- Buffer: foo ----------
9977This is the @@point@{@}contents of foo.
9978---------- Buffer: foo ----------
9979
9980(insert "changed ")
9981 @@result@{@} nil
9982---------- Buffer: foo ----------
9983This is the changed @@point@{@}contents of foo.
9984---------- Buffer: foo ----------
9985@@end example
9986@end example
9987
9988
9989@node Footnotes
9990@section Footnotes
9991@cindex Footnotes
9992@findex footnote
9993
9994A @dfn{footnote} is for a reference that documents or elucidates the
9995primary text.@footnote{A footnote should complement or expand upon
9996the primary text, but a reader should not need to read a footnote to
9997understand the primary text. For a thorough discussion of footnotes,
9998see @cite{The Chicago Manual of Style}, which is published by the
9999University of Chicago Press.}
10000
10001@menu
10002* Footnote Commands:: How to write a footnote in Texinfo.
10003* Footnote Styles:: Controlling how footnotes appear in Info.
10004@end menu
10005
10006
10007@node Footnote Commands
10008@subsection Footnote Commands
10009
10010In Texinfo, footnotes are created with the @code{@@footnote} command.
10011This command is followed immediately by a left brace, then by the text
10012of the footnote, and then by a terminating right brace. Footnotes may
10013be of any length (they will be broken across pages if necessary), but
10014are usually short. The template is:
10015
10016@example
10017ordinary text@@footnote@{@var{text of footnote}@}
10018@end example
10019
10020As shown here, the @code{@@footnote} command should come right after the
10021text being footnoted, with no intervening space; otherwise, the footnote
10022marker might end up starting a line.
10023
10024For example, this clause is followed by a sample footnote@footnote{Here
10025is the sample footnote.}; in the Texinfo source, it looks like
10026this:
10027
10028@example
10029@dots{}a sample footnote@@footnote@{Here is the sample
10030footnote.@}; in the Texinfo source@dots{}
10031@end example
10032
10033As you can see, the source includes two punctuation marks next to each
10034other; in this case, @samp{.@};} is the sequence. This is normal (the
10035first ends the footnote and the second belongs to the sentence being
10036footnoted), so don't worry that it looks odd.
10037
10038In a printed manual or book, the reference mark for a footnote is a
10039small, superscripted number; the text of the footnote appears at the
10040bottom of the page, below a horizontal line.
10041
10042In Info, the reference mark for a footnote is a pair of parentheses
10043with the footnote number between them, like this: @samp{(1)}. The
10044reference mark is followed by a cross-reference link to the footnote's
10045text.
10046
10047In the HTML output, footnote references are marked with a small,
10048superscripted number which is rendered as a hypertext link to the
10049footnote text.
10050
10051By the way, footnotes in the argument of an @code{@@item} command for a
10052@code{@@table} must be on the same line as the @code{@@item}
10053(as usual). @xref{Two-column Tables}.
10054
10055
10056@node Footnote Styles
10057@subsection Footnote Styles
10058
10059Info has two footnote styles, which determine where the text of the
10060footnote is located:@refill
10061
10062@itemize @bullet
10063@cindex @samp{@r{End}} node footnote style
10064@item
10065In the `End' node style, all the footnotes for a single node
10066are placed at the end of that node. The footnotes are separated from
10067the rest of the node by a line of dashes with the word
10068@samp{Footnotes} within it. Each footnote begins with an
10069@samp{(@var{n})} reference mark.@refill
10070
10071@need 700
10072@noindent
10073Here is an example of a single footnote in the end of node style:@refill
10074
10075@example
10076@group
10077 --------- Footnotes ---------
10078
10079(1) Here is a sample footnote.
10080@end group
10081@end example
10082
10083@cindex @samp{@r{Separate}} footnote style
10084@item
10085In the `Separate' node style, all the footnotes for a single
10086node are placed in an automatically constructed node of
10087their own. In this style, a ``footnote reference'' follows
10088each @samp{(@var{n})} reference mark in the body of the
10089node. The footnote reference is actually a cross reference
10090which you use to reach the footnote node.@refill
10091
10092The name of the node with the footnotes is constructed
10093by appending @w{@samp{-Footnotes}} to the name of the node
10094that contains the footnotes. (Consequently, the footnotes'
10095node for the @file{Footnotes} node is
10096@w{@file{Footnotes-Footnotes}}!) The footnotes' node has an
10097`Up' node pointer that leads back to its parent node.@refill
10098
10099@noindent
10100Here is how the first footnote in this manual looks after being
10101formatted for Info in the separate node style:@refill
10102
10103@smallexample
10104@group
10105File: texinfo.info Node: Overview-Footnotes, Up: Overview
10106
10107(1) The first syllable of "Texinfo" is pronounced like "speck", not
10108"hex". @dots{}
10109@end group
10110@end smallexample
10111@end itemize
10112
10113A Texinfo file may be formatted into an Info file with either footnote
10114style.@refill
10115
10116@findex footnotestyle
10117Use the @code{@@footnotestyle} command to specify an Info file's
10118footnote style. Write this command at the beginning of a line followed
10119by an argument, either @samp{end} for the end node style or
10120@samp{separate} for the separate node style.
10121
10122@need 700
10123For example,
10124
10125@example
10126@@footnotestyle end
10127@end example
10128@noindent
10129or
10130@example
10131@@footnotestyle separate
10132@end example
10133
10134Write an @code{@@footnotestyle} command before or shortly after the
10135end-of-header line at the beginning of a Texinfo file. (If you
10136include the @code{@@footnotestyle} command between the start-of-header
10137and end-of-header lines, the region formatting commands will format
10138footnotes as specified.)@refill
10139
10140If you do not specify a footnote style, the formatting commands use
10141their default style. Currently, @code{texinfo-format-buffer} and
10142@code{texinfo-format-region} use the `separate' style and
10143@code{makeinfo} uses the `end' style.@refill
10144
10145@c !!! note: makeinfo's --footnote-style option overrides footnotestyle
10146@ignore
10147If you use @code{makeinfo} to create the Info file, the
10148@samp{--footnote-style} option determines which style is used,
10149@samp{end} for the end of node style or @samp{separate} for the
10150separate node style. Thus, to format the Texinfo manual in the
10151separate node style, you would use the following shell command:@refill
10152
10153@example
10154makeinfo --footnote-style=separate texinfo.texi
10155@end example
10156
10157@noindent
10158To format the Texinfo manual in the end of node style, you would
10159type:@refill
10160
10161@example
10162makeinfo --footnote-style=end texinfo.texi
10163@end example
10164@end ignore
10165@ignore
10166If you use @code{texinfo-format-buffer} or
10167@code{texinfo-format-region} to create the Info file, the value of the
10168@code{texinfo-footnote-style} variable controls the footnote style.
10169It can be either @samp{"separate"} for the separate node style or
10170@samp{"end"} for the end of node style. (You can change the value of
10171this variable with the @kbd{M-x edit-options} command (@pxref{Edit
10172Options, , Editing Variable Values, emacs, The GNU Emacs Manual}), or
10173with the @kbd{M-x set-variable} command (@pxref{Examining, , Examining
10174and Setting Variables, emacs, The GNU Emacs Manual}).@refill
10175
10176The @code{texinfo-footnote-style} variable also controls the style if
10177you use the @kbd{M-x makeinfo-region} or @kbd{M-x makeinfo-buffer}
10178command in Emacs.@refill
10179@end ignore
10180@ifinfo
10181This chapter contains two footnotes.@refill
10182@end ifinfo
10183
10184
10185@c this should be described with figures when we have them
10186@c perhaps in the quotation/example chapter.
10187@node Images
10188@section Inserting Images
10189
10190@cindex Images, inserting
10191@cindex Pictures, inserting
10192@findex image
10193
10194You can insert an image given in an external file with the
10195@code{@@image} command:
10196
10197@example
10198@@image@{@var{filename}, @r{[}@var{width}@r{]}, @r{[}@var{height}@r{]}, @r{[}@var{alttext}@r{]}, @r{[}@var{extension}@r{]}@}
10199@end example
10200
10201@cindex Formats for images
10202@cindex Image formats
10203The @var{filename} argument is mandatory, and must not have an
10204extension, because the different processors support different formats:
10205@itemize @bullet
10206@item
10207@TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript
10208format).
10209@item
10210@pindex pdftex@r{, and images}
10211PDF@TeX{} reads @file{@var{filename}.pdf} (Adobe's Portable Document Format).
10212@item
10213@code{makeinfo} uses @file{@var{filename}.txt} verbatim for
10214Info output (more or less as if it was an @code{@@example}).
10215@item
10216@code{makeinfo}
10217uses the optional fifth argument to @code{@@image} for the extension if
10218you supply it. For example:
10219
10220@pindex XPM image format
10221@example
10222@@image@{foo,,,,xpm@}
10223@end example
10224
10225@noindent
10226will cause @samp{makeinfo --html} to try @file{foo.xpm}.
10227
10228@cindex GIF, unsupported due to patents
10229@cindex PNG image format
10230@cindex JPG image format
10231If you do not supply the optional fifth argument, @samp{makeinfo
10232---html} first tries @file{@var{filename}.png}; if that does not exist,
10233it tries @file{@var{filename}.jpg}. If that does not exist either, it
10234complains. (We cannot support GIF format directly due to software
10235patents.)
10236@end itemize
10237
10238@cindex Width of images
10239@cindex Height of images
10240@cindex Aspect ratio of images
10241@cindex Distorting images
10242The optional @var{width} and @var{height} arguments specify the size to
10243scale the image to (they are ignored for Info output). If neither is
10244specified, the image is presented in its natural size (given in the
10245file); if only one is specified, the other is scaled proportionately;
10246and if both are specified, both are respected, thus possibly distorting
10247the original image by changing its aspect ratio.
10248
10249@cindex Dimensions and image sizes
10250The @var{width} and @var{height} may be specified using any valid @TeX{}
10251dimension, namely:
10252
10253@table @asis
10254@item pt
10255@cindex Points (dimension)
10256point (72.27pt = 1in)
10257@item pc
10258@cindex Picas
10259pica (1pc = 12pt)
10260@item bp
10261@cindex Big points
10262big point (72bp = 1in)
10263@item in
10264@cindex Inches
10265inch
10266@item cm
10267@cindex Centimeters
10268centimeter (2.54cm = 1in)
10269@item mm
10270@cindex Millimeters
10271millimeter (10mm = 1cm)
10272@item dd
10273@cindex Did@^ot points
10274did@^ot point (1157dd = 1238pt)
10275@item cc
10276@cindex Ciceros
10277cicero (1cc = 12dd)
10278@item sp
10279@cindex Scaled points
10280scaled point (65536sp = 1pt)
10281@end table
10282
10283@pindex ridt.eps
10284For example, the following will scale a file @file{ridt.eps} to one
10285inch vertically, with the width scaled proportionately:
10286
10287@example
10288@@image@{ridt,,1in@}
10289@end example
10290
10291@pindex epsf.tex
10292For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be
10293installed somewhere that @TeX{} can find it. (The standard location is
10294@file{@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a
10295root of your @TeX{} directory tree.) This file is included in the
10296Texinfo distribution and is also available from
10297@uref{ftp://tug.org/tex/epsf.tex}, among other places.
10298
10299@code{@@image} can be used within a line as well as for displayed
10300figures. Therefore, if you intend it to be displayed, be sure to leave
10301a blank line before the command, or the output will run into the
10302preceding text.
10303
10304@cindex alt attribute for images
10305@cindex alternate text for images
10306When producing html, @code{makeinfo} sets the @dfn{alt attribute} for
10307inline images to the optional fourth argument to @code{@@image}, if
10308supplied. If not supplied, @code{makeinfo} uses the full file name of
10309the image being displayed.
10310
10311
10312@node Breaks
10313@chapter Making and Preventing Breaks
10314@cindex Making line and page breaks
10315@cindex Preventing line and page breaks
10316
10317@cindex Line breaks
10318Usually, a Texinfo file is processed both by @TeX{} and by one of the
10319Info formatting commands. Line, paragraph, or page breaks sometimes
10320occur in the `wrong' place in one or other form of output. You must
10321ensure that text looks right both in the printed manual and in the
10322Info file.
10323
10324@cindex White space, excessive
10325@cindex Page breaks
10326For example, in a printed manual, page breaks may occur awkwardly in
10327the middle of an example; to prevent this, you can hold text together
10328using a grouping command that keeps the text from being split across
10329two pages. Conversely, you may want to force a page break where none
10330would occur normally. Fortunately, problems like these do not often
10331arise. When they do, use the break, break prevention, or pagination
10332commands.
10333
10334@menu
10335* Break Commands:: Cause and prevent splits.
10336* Line Breaks:: How to force a single line to use two lines.
10337* - and hyphenation:: How to tell @TeX{} about hyphenation points.
10338* w:: How to prevent unwanted line breaks.
10339* sp:: How to insert blank lines.
10340* page:: How to force the start of a new page.
10341* group:: How to prevent unwanted page breaks.
10342* need:: Another way to prevent unwanted page breaks.
10343@end menu
10344
10345
10346@node Break Commands, Line Breaks, Breaks, Breaks
10347@ifinfo
10348@heading Break Commands
10349@end ifinfo
10350
10351The break commands create or allow line and paragraph breaks:@refill
10352
10353@table @code
10354@item @@*
10355Force a line break.
10356
10357@item @@sp @var{n}
10358Skip @var{n} blank lines.@refill
10359
10360@item @@-
10361Insert a discretionary hyphen.
10362
10363@item @@hyphenation@{@var{hy-phen-a-ted words}@}
10364Define hyphen points in @var{hy-phen-a-ted words}.
10365@end table
10366
10367The line-break-prevention command holds text together all on one
10368line:@refill
10369
10370@table @code
10371@item @@w@{@var{text}@}
10372Prevent @var{text} from being split and hyphenated across two lines.@refill
10373@end table
10374@iftex
10375@sp 1
10376@end iftex
10377
10378The pagination commands apply only to printed output, since Info
10379files do not have pages.@refill
10380
10381@table @code
10382@item @@page
10383Start a new page in the printed manual.@refill
10384
10385@item @@group
10386Hold text together that must appear on one printed page.@refill
10387
10388@item @@need @var{mils}
10389Start a new printed page if not enough space on this one.@refill
10390@end table
10391
10392@node Line Breaks
10393@section @code{@@*}: Generate Line Breaks
10394@findex * @r{(force line break)}
10395@cindex Line breaks
10396@cindex Breaks in a line
10397
10398The @code{@@*} command forces a line break in both the printed manual and
10399in Info.@refill
10400
10401@need 700
10402For example,
10403
10404@example
10405This line @@* is broken @@*in two places.
10406@end example
10407
10408@noindent
10409produces
10410
10411@example
10412@group
10413This line
10414 is broken
10415in two places.
10416@end group
10417@end example
10418
10419@noindent
10420(Note that the space after the first @code{@@*} command is faithfully
10421carried down to the next line.)@refill
10422
10423@need 800
10424The @code{@@*} command is often used in a file's copyright page:@refill
10425
10426@example
10427@group
10428This is edition 2.0 of the Texinfo documentation,@@*
10429and is for @dots{}
10430@end group
10431@end example
10432
10433@noindent
10434In this case, the @code{@@*} command keeps @TeX{} from stretching the
10435line across the whole page in an ugly manner.@refill
10436
10437@quotation
10438@strong{Please note:} Do not write braces after an @code{@@*} command;
10439they are not needed.@refill
10440
10441Do not write an @code{@@refill} command at the end of a paragraph
10442containing an @code{@@*} command; it will cause the paragraph to be
10443refilled after the line break occurs, negating the effect of the line
10444break.@refill
10445@end quotation
10446
10447
10448@node - and hyphenation
10449@section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} hyphenate
10450
|
10374@findex -
| 10451@findex - @r{(discretionary hyphen)}
|
10375@findex hyphenation
10376@cindex Hyphenation, helping @TeX{} do
10377@cindex Fine-tuning, and hyphenation
10378
10379Although @TeX{}'s hyphenation algorithm is generally pretty good, it
10380does miss useful hyphenation points from time to time. (Or, far more
10381rarely, insert an incorrect hyphenation.) So, for documents with an
10382unusual vocabulary or when fine-tuning for a printed edition, you may
10383wish to help @TeX{} out. Texinfo supports two commands for this:
10384
10385@table @code
10386@item @@-
10387Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does
| 10452@findex hyphenation
10453@cindex Hyphenation, helping @TeX{} do
10454@cindex Fine-tuning, and hyphenation
10455
10456Although @TeX{}'s hyphenation algorithm is generally pretty good, it
10457does miss useful hyphenation points from time to time. (Or, far more
10458rarely, insert an incorrect hyphenation.) So, for documents with an
10459unusual vocabulary or when fine-tuning for a printed edition, you may
10460wish to help @TeX{} out. Texinfo supports two commands for this:
10461
10462@table @code
10463@item @@-
10464Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does
|
10388not have to) hyphenate. This is especially useful when you notice
10389an overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull
10390hboxes}). @TeX{} will not insert any hyphenation points in a word
10391containing @code{@@-}.
| 10465not have to) hyphenate. This is especially useful when you notice an
10466overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull
10467hboxes}). @TeX{} will not insert any hyphenation points itself into a
10468word containing @code{@@-}.
|
10392
10393@item @@hyphenation@{@var{hy-phen-a-ted words}@}
10394Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you
10395put a @samp{-} at each hyphenation point. For example:
10396@example
10397@@hyphenation@{man-u-script man-u-scripts@}
10398@end example
10399@noindent @TeX{} only uses the specified hyphenation points when the
10400words match exactly, so give all necessary variants.
10401@end table
10402
10403Info output is not hyphenated, so these commands have no effect there.
10404
10405@node w
10406@section @code{@@w}@{@var{text}@}: Prevent Line Breaks
10407@findex w @r{(prevent line break)}
10408@cindex Line breaks, preventing
10409@cindex Hyphenation, preventing
10410
10411@code{@@w@{@var{text}@}} outputs @var{text} and prohibits line breaks
10412within @var{text}.@refill
10413
10414You can use the @code{@@w} command to prevent @TeX{} from automatically
10415hyphenating a long name or phrase that happens to fall near the end of a
10416line. For example:
10417
10418@example
10419You can copy GNU software from @@w@{@@samp@{ftp.gnu.org@}@}.
10420@end example
10421
10422@noindent
10423produces
10424
10425@quotation
10426You can copy GNU software from @w{@samp{ftp.gnu.org}}.
10427@end quotation
10428
10429@cindex Non-breakable space
10430@cindex Unbreakable space
10431@cindex Tied space
10432You can also use @code{@@w} to produce a non-breakable space:
10433
10434@example
10435None of the formatters will break at this@@w@{ @}space.
10436@end example
10437
10438
10439@node sp
10440@section @code{@@sp} @var{n}: Insert Blank Lines
10441@findex sp @r{(line spacing)}
10442@cindex Space, inserting vertical
10443@cindex Blank lines
10444@cindex Line spacing
10445
10446A line beginning with and containing only @code{@@sp @var{n}}
10447generates @var{n} blank lines of space in both the printed manual and
10448the Info file. @code{@@sp} also forces a paragraph break. For
10449example,
10450
10451@example
10452@@sp 2
10453@end example
10454
10455@noindent
10456generates two blank lines.
10457
10458The @code{@@sp} command is most often used in the title page.@refill
10459
10460@ignore
10461@c node br, page, sp, Breaks
10462@comment node-name, next, previous, up
10463@c section @code{@@br}: Generate Paragraph Breaks
10464@findex br @r{(paragraph breaks)}
10465@cindex Paragraph breaks
10466@cindex Breaks in a paragraph
10467
10468The @code{@@br} command forces a paragraph break. It inserts a blank
10469line. You can use the command within or at the end of a line. If
10470used within a line, the @code{@@br@{@}} command must be followed by
10471left and right braces (as shown here) to mark the end of the
10472command.@refill
10473
10474@need 700
10475For example,
10476
10477@example
10478@group
10479This line @@br@{@}contains and is ended by paragraph breaks@@br
10480and is followed by another line.
10481@end group
10482@end example
10483
10484@noindent
10485produces
10486
10487@example
10488@group
10489This line
10490
10491contains and is ended by paragraph breaks
10492
10493and is followed by another line.
10494@end group
10495@end example
10496
10497The @code{@@br} command is seldom used.
10498@end ignore
10499
10500
10501@node page
10502@section @code{@@page}: Start a New Page
10503@cindex Page breaks
10504@findex page
10505
10506A line containing only @code{@@page} starts a new page in a printed
10507manual. The command has no effect on Info files since they are not
10508paginated. An @code{@@page} command is often used in the @code{@@titlepage}
10509section of a Texinfo file to start the copyright page.
10510
10511
10512@node group, need, page, Breaks
10513@comment node-name, next, previous, up
10514@section @code{@@group}: Prevent Page Breaks
10515@cindex Group (hold text together vertically)
10516@cindex Holding text together vertically
10517@cindex Vertically holding text together
10518@findex group
10519
10520The @code{@@group} command (on a line by itself) is used inside an
10521@code{@@example} or similar construct to begin an unsplittable vertical
10522group, which will appear entirely on one page in the printed output.
10523The group is terminated by a line containing only @code{@@end group}.
10524These two lines produce no output of their own, and in the Info file
10525output they have no effect at all.@refill
10526
10527@c Once said that these environments
10528@c turn off vertical spacing between ``paragraphs''.
10529@c Also, quotation used to work, but doesn't in texinfo-2.72
10530Although @code{@@group} would make sense conceptually in a wide
10531variety of contexts, its current implementation works reliably only
10532within @code{@@example} and variants, and within @code{@@display},
10533@code{@@format}, @code{@@flushleft} and @code{@@flushright}.
10534@xref{Quotations and Examples}. (What all these commands have in
10535common is that each line of input produces a line of output.) In
10536other contexts, @code{@@group} can cause anomalous vertical
10537spacing.@refill
10538
10539@need 750
10540This formatting requirement means that you should write:
10541
10542@example
10543@group
10544@@example
10545@@group
10546@dots{}
10547@@end group
10548@@end example
10549@end group
10550@end example
10551
10552@noindent
10553with the @code{@@group} and @code{@@end group} commands inside the
10554@code{@@example} and @code{@@end example} commands.
10555
10556The @code{@@group} command is most often used to hold an example
10557together on one page. In this Texinfo manual, more than 100 examples
10558contain text that is enclosed between @code{@@group} and @code{@@end
10559group}.
10560
10561If you forget to end a group, you may get strange and unfathomable
10562error messages when you run @TeX{}. This is because @TeX{} keeps
10563trying to put the rest of the Texinfo file onto the one page and does
10564not start to generate error messages until it has processed
10565considerable text. It is a good rule of thumb to look for a missing
10566@code{@@end group} if you get incomprehensible error messages in
10567@TeX{}.@refill
10568
10569@node need, , group, Breaks
10570@comment node-name, next, previous, up
10571@section @code{@@need @var{mils}}: Prevent Page Breaks
10572@cindex Need space at page bottom
10573@findex need
10574
10575A line containing only @code{@@need @var{n}} starts
10576a new page in a printed manual if fewer than @var{n} mils (thousandths
10577of an inch) remain on the current page. Do not use
10578braces around the argument @var{n}. The @code{@@need} command has no
10579effect on Info files since they are not paginated.@refill
10580
10581@need 800
10582This paragraph is preceded by an @code{@@need} command that tells
10583@TeX{} to start a new page if fewer than 800 mils (eight-tenths
10584inch) remain on the page. It looks like this:@refill
10585
10586@example
10587@group
10588@@need 800
10589This paragraph is preceded by @dots{}
10590@end group
10591@end example
10592
10593The @code{@@need} command is useful for preventing orphans (single
10594lines at the bottoms of printed pages).@refill
10595
10596
10597@node Definition Commands
10598@chapter Definition Commands
10599@cindex Definition commands
10600
10601The @code{@@deffn} command and the other @dfn{definition commands}
10602enable you to describe functions, variables, macros, commands, user
10603options, special forms and other such artifacts in a uniform
10604format.@refill
10605
10606In the Info file, a definition causes the entity
10607category---`Function', `Variable', or whatever---to appear at the
10608beginning of the first line of the definition, followed by the
10609entity's name and arguments. In the printed manual, the command
10610causes @TeX{} to print the entity's name and its arguments on the left
10611margin and print the category next to the right margin. In both
10612output formats, the body of the definition is indented. Also, the
10613name of the entity is entered into the appropriate index:
10614@code{@@deffn} enters the name into the index of functions,
10615@code{@@defvr} enters it into the index of variables, and so
10616on.@refill
10617
10618A manual need not and should not contain more than one definition for
10619a given name. An appendix containing a summary should use
10620@code{@@table} rather than the definition commands.@refill
10621
10622@menu
10623* Def Cmd Template:: How to structure a description using a
10624 definition command.
10625* Optional Arguments:: How to handle optional and repeated arguments.
10626* deffnx:: How to group two or more `first' lines.
10627* Def Cmds in Detail:: All the definition commands.
10628* Def Cmd Conventions:: Conventions for writing definitions.
10629* Sample Function Definition::
10630@end menu
10631
10632@node Def Cmd Template, Optional Arguments, Definition Commands, Definition Commands
10633@section The Template for a Definition
10634@cindex Definition template
10635@cindex Template for a definition
10636
10637The @code{@@deffn} command is used for definitions of entities that
10638resemble functions. To write a definition using the @code{@@deffn}
10639command, write the @code{@@deffn} command at the beginning of a line
10640and follow it on the same line by the category of the entity, the name
10641of the entity itself, and its arguments (if any). Then write the body
10642of the definition on succeeding lines. (You may embed examples in the
10643body.) Finally, end the definition with an @code{@@end deffn} command
10644written on a line of its own. (The other definition commands follow
10645the same format.)@refill
10646
10647The template for a definition looks like this:
10648
10649@example
10650@group
10651@@deffn @var{category} @var{name} @var{arguments}@dots{}
10652@var{body-of-definition}
10653@@end deffn
10654@end group
10655@end example
10656
10657@need 700
10658@noindent
10659For example,
10660
10661@example
10662@group
10663@@deffn Command forward-word count
10664This command moves point forward @@var@{count@} words
10665(or backward if @@var@{count@} is negative). @dots{}
10666@@end deffn
10667@end group
10668@end example
10669
10670@noindent
10671produces
10672
10673@quotation
10674@deffn Command forward-word count
10675This function moves point forward @var{count} words
10676(or backward if @var{count} is negative). @dots{}
10677@end deffn
10678@end quotation
10679
10680Capitalize the category name like a title. If the name of the
10681category contains spaces, as in the phrase `Interactive Command',
10682write braces around it. For example:@refill
10683
10684@example
10685@group
10686@@deffn @{Interactive Command@} isearch-forward
10687@dots{}
10688@@end deffn
10689@end group
10690@end example
10691
10692@noindent
10693Otherwise, the second word will be mistaken for the name of the
10694entity.@refill
10695
10696Some of the definition commands are more general than others. The
10697@code{@@deffn} command, for example, is the general definition command
10698for functions and the like---for entities that may take arguments. When
10699you use this command, you specify the category to which the entity
10700belongs. The @code{@@deffn} command possesses three predefined,
10701specialized variations, @code{@@defun}, @code{@@defmac}, and
10702@code{@@defspec}, that specify the category for you: ``Function'',
10703``Macro'', and ``Special Form'' respectively. (In Lisp, a special form
10704is an entity much like a function.) The @code{@@defvr} command also is
10705accompanied by several predefined, specialized variations for describing
10706particular kinds of variables.@refill
10707
10708The template for a specialized definition, such as @code{@@defun}, is
10709similar to the template for a generalized definition, except that you
10710do not need to specify the category:@refill
10711
10712@example
10713@group
10714@@defun @var{name} @var{arguments}@dots{}
10715@var{body-of-definition}
10716@@end defun
10717@end group
10718@end example
10719
10720@noindent
10721Thus,
10722
10723@example
10724@group
10725@@defun buffer-end flag
10726This function returns @@code@{(point-min)@} if @@var@{flag@}
10727is less than 1, @@code@{(point-max)@} otherwise.
10728@dots{}
10729@@end defun
10730@end group
10731@end example
10732
10733@noindent
10734produces
10735
10736@quotation
10737@defun buffer-end flag
10738This function returns @code{(point-min)} if @var{flag} is less than 1,
10739@code{(point-max)} otherwise. @dots{}
10740@end defun
10741@end quotation
10742
10743@noindent
10744@xref{Sample Function Definition, Sample Function Definition, A Sample
10745Function Definition}, for a more detailed example of a function
10746definition, including the use of @code{@@example} inside the
10747definition.@refill
10748
10749The other specialized commands work like @code{@@defun}.@refill
10750
10751@cindex Macros in definition commands
10752Note that, due to implementation difficulties, macros are not expanded
10753in @code{@@deffn} and all the other definition commands.
10754
10755@node Optional Arguments, deffnx, Def Cmd Template, Definition Commands
10756@section Optional and Repeated Arguments
10757@cindex Optional and repeated arguments
10758@cindex Repeated and optional arguments
10759@cindex Arguments, repeated and optional
10760@cindex Syntax, optional & repeated arguments
10761@cindex Meta-syntactic chars for arguments
10762
10763Some entities take optional or repeated arguments, which may be
10764specified by a distinctive glyph that uses square brackets and
10765ellipses. For @w{example}, a special form often breaks its argument list
10766into separate arguments in more complicated ways than a
10767straightforward function.@refill
10768
10769@iftex
10770An argument enclosed within square brackets is optional.
10771Thus, the phrase
10772@samp{@code{@r{[}@var{optional-arg}@r{]}}} means that
10773@var{optional-arg} is optional.
10774An argument followed by an ellipsis is optional
10775and may be repeated more than once.
10776@c This is consistent with Emacs Lisp Reference manual
10777Thus, @samp{@var{repeated-args}@dots{}} stands for zero or more arguments.
10778Parentheses are used when several arguments are grouped
10779into additional levels of list structure in Lisp.
10780@end iftex
10781@c The following looks better in Info (no `r', `samp' and `code'):
10782@ifinfo
10783An argument enclosed within square brackets is optional.
10784Thus, [@var{optional-arg}] means that @var{optional-arg} is optional.
10785An argument followed by an ellipsis is optional
10786and may be repeated more than once.
10787@c This is consistent with Emacs Lisp Reference manual
10788Thus, @var{repeated-args}@dots{} stands for zero or more arguments.
10789Parentheses are used when several arguments are grouped
10790into additional levels of list structure in Lisp.
10791@end ifinfo
10792
10793Here is the @code{@@defspec} line of an example of an imaginary
10794special form:@refill
10795
10796@quotation
10797@defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{}
10798@end defspec
10799@tex
10800\vskip \parskip
10801@end tex
10802@end quotation
10803
10804@noindent
10805In this example, the arguments @var{from} and @var{to} are optional,
10806but must both be present or both absent. If they are present,
10807@var{inc} may optionally be specified as well. These arguments are
10808grouped with the argument @var{var} into a list, to distinguish them
10809from @var{body}, which includes all remaining elements of the
10810form.@refill
10811
10812In a Texinfo source file, this @code{@@defspec} line is written like
10813this (except it would not be split over two lines, as it is in this
10814example).@refill
10815
10816@example
10817@group
10818@@defspec foobar (@@var@{var@} [@@var@{from@} @@var@{to@}
10819 [@@var@{inc@}]]) @@var@{body@}@@dots@{@}
10820@end group
10821@end example
10822
10823@noindent
10824The function is listed in the Command and Variable Index under
10825@samp{foobar}.@refill
10826
10827@node deffnx, Def Cmds in Detail, Optional Arguments, Definition Commands
10828@section Two or More `First' Lines
10829@cindex Two `First' Lines for @code{@@deffn}
10830@cindex Grouping two definitions together
10831@cindex Definitions grouped together
10832@findex deffnx
10833
10834To create two or more `first' or header lines for a definition, follow
10835the first @code{@@deffn} line by a line beginning with @code{@@deffnx}.
10836The @code{@@deffnx} command works exactly like @code{@@deffn}
10837except that it does not generate extra vertical white space between it
10838and the preceding line.@refill
10839
10840@need 1000
10841For example,
10842
10843@example
10844@group
10845@@deffn @{Interactive Command@} isearch-forward
10846@@deffnx @{Interactive Command@} isearch-backward
10847These two search commands are similar except @dots{}
10848@@end deffn
10849@end group
10850@end example
10851
10852@noindent
10853produces
10854
10855@deffn {Interactive Command} isearch-forward
10856@deffnx {Interactive Command} isearch-backward
10857These two search commands are similar except @dots{}
10858@end deffn
10859
10860Each definition command has an `x' form: @code{@@defunx},
10861@code{@@defvrx}, @code{@@deftypefunx}, etc.
10862
10863The `x' forms work just like @code{@@itemx}; see @ref{itemx, , @code{@@itemx}}.
10864
10865@node Def Cmds in Detail, Def Cmd Conventions, deffnx, Definition Commands
10866@section The Definition Commands
10867
10868Texinfo provides more than a dozen definition commands, all of which
10869are described in this section.@refill
10870
10871The definition commands automatically enter the name of the entity in
10872the appropriate index: for example, @code{@@deffn}, @code{@@defun},
10873and @code{@@defmac} enter function names in the index of functions;
10874@code{@@defvr} and @code{@@defvar} enter variable names in the index
10875of variables.@refill
10876
10877Although the examples that follow mostly illustrate Lisp, the commands
10878can be used for other programming languages.@refill
10879
10880@menu
10881* Functions Commands:: Commands for functions and similar entities.
10882* Variables Commands:: Commands for variables and similar entities.
10883* Typed Functions:: Commands for functions in typed languages.
10884* Typed Variables:: Commands for variables in typed languages.
10885* Abstract Objects:: Commands for object-oriented programming.
10886* Data Types:: The definition command for data types.
10887@end menu
10888
10889@node Functions Commands, Variables Commands, Def Cmds in Detail, Def Cmds in Detail
10890@subsection Functions and Similar Entities
10891
10892This section describes the commands for describing functions and similar
10893entities:@refill
10894
10895@table @code
10896@findex deffn
10897@item @@deffn @var{category} @var{name} @var{arguments}@dots{}
10898The @code{@@deffn} command is the general definition command for
10899functions, interactive commands, and similar entities that may take
10900arguments. You must choose a term to describe the category of entity
10901being defined; for example, ``Function'' could be used if the entity is
10902a function. The @code{@@deffn} command is written at the beginning of a
10903line and is followed on the same line by the category of entity being
10904described, the name of this particular entity, and its arguments, if
10905any. Terminate the definition with @code{@@end deffn} on a line of its
10906own.@refill
10907
10908@need 750
10909For example, here is a definition:
10910
10911@example
10912@group
10913@@deffn Command forward-char nchars
10914Move point forward @@var@{nchars@} characters.
10915@@end deffn
10916@end group
10917@end example
10918
10919@noindent
10920This shows a rather terse definition for a ``command'' named
10921@code{forward-char} with one argument, @var{nchars}.
10922
10923@code{@@deffn} prints argument names such as @var{nchars} in italics or
10924upper case, as if @code{@@var} had been used, because we think of these
10925names as metasyntactic variables---they stand for the actual argument
10926values. Within the text of the description, write an argument name
10927explicitly with @code{@@var} to refer to the value of the argument. In
10928the example above, we used @samp{@@var@{nchars@}} in this way.
10929
10930The template for @code{@@deffn} is:
10931
10932@example
10933@group
10934@@deffn @var{category} @var{name} @var{arguments}@dots{}
10935@var{body-of-definition}
10936@@end deffn
10937@end group
10938@end example
10939
10940@findex defun
10941@item @@defun @var{name} @var{arguments}@dots{}
10942The @code{@@defun} command is the definition command for functions.
10943@code{@@defun} is equivalent to @samp{@@deffn Function
10944@dots{}}.@refill
10945
10946@need 800
10947@noindent
10948For example,
10949
10950@example
10951@group
10952@@defun set symbol new-value
10953Change the value of the symbol @@var@{symbol@}
10954to @@var@{new-value@}.
10955@@end defun
10956@end group
10957@end example
10958
10959@noindent
10960shows a rather terse definition for a function @code{set} whose
10961arguments are @var{symbol} and @var{new-value}. The argument names on
10962the @code{@@defun} line automatically appear in italics or upper case as
10963if they were enclosed in @code{@@var}. Terminate the definition with
10964@code{@@end defun} on a line of its own.@refill
10965
10966The template is:
10967
10968@example
10969@group
10970@@defun @var{function-name} @var{arguments}@dots{}
10971@var{body-of-definition}
10972@@end defun
10973@end group
10974@end example
10975
10976@code{@@defun} creates an entry in the index of functions.
10977
10978@findex defmac
10979@item @@defmac @var{name} @var{arguments}@dots{}
10980The @code{@@defmac} command is the definition command for macros.
10981@code{@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and
10982works like @code{@@defun}.@refill
10983
10984@findex defspec
10985@item @@defspec @var{name} @var{arguments}@dots{}
10986The @code{@@defspec} command is the definition command for special
10987forms. (In Lisp, a special form is an entity much like a function,
10988@pxref{Special Forms,,, elisp, GNU Emacs Lisp Reference Manual}.)
10989@code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@}
10990@dots{}} and works like @code{@@defun}.@refill
10991@end table
10992
10993@node Variables Commands, Typed Functions, Functions Commands, Def Cmds in Detail
10994@subsection Variables and Similar Entities
10995
10996Here are the commands for defining variables and similar
10997entities:@refill
10998
10999@table @code
11000@findex defvr
11001@item @@defvr @var{category} @var{name}
11002The @code{@@defvr} command is a general definition command for
11003something like a variable---an entity that records a value. You must
11004choose a term to describe the category of entity being defined; for
11005example, ``Variable'' could be used if the entity is a variable.
11006Write the @code{@@defvr} command at the beginning of a line and
11007follow it on the same line by the category of the entity and the
11008name of the entity.
11009
11010Capitalize the category name like a title. If the name of the category
11011contains spaces, as in the name ``User Option'', enclose it in braces.
11012Otherwise, the second word will be mistaken for the name of the entity.
11013For example,
11014
11015@example
11016@group
11017@@defvr @{User Option@} fill-column
11018This buffer-local variable specifies
11019the maximum width of filled lines.
11020@dots{}
11021@@end defvr
11022@end group
11023@end example
11024
11025Terminate the definition with @code{@@end defvr} on a line of its
11026own.@refill
11027
11028The template is:
11029
11030@example
11031@group
11032@@defvr @var{category} @var{name}
11033@var{body-of-definition}
11034@@end defvr
11035@end group
11036@end example
11037
11038@code{@@defvr} creates an entry in the index of variables for @var{name}.
11039
11040@findex defvar
11041@item @@defvar @var{name}
11042The @code{@@defvar} command is the definition command for variables.
11043@code{@@defvar} is equivalent to @samp{@@defvr Variable
11044@dots{}}.@refill
11045
11046@need 750
11047For example:
11048
11049@example
11050@group
11051@@defvar kill-ring
11052@dots{}
11053@@end defvar
11054@end group
11055@end example
11056
11057The template is:
11058
11059@example
11060@group
11061@@defvar @var{name}
11062@var{body-of-definition}
11063@@end defvar
11064@end group
11065@end example
11066
11067@code{@@defvar} creates an entry in the index of variables for
11068@var{name}.@refill
11069
11070@findex defopt
11071@item @@defopt @var{name}
11072@cindex User options, marking
11073The @code{@@defopt} command is the definition command for @dfn{user
11074options}, i.e., variables intended for users to change according to
11075taste; Emacs has many such (@pxref{Variables,,, emacs, The GNU Emacs
11076Manual}). @code{@@defopt} is equivalent to @samp{@@defvr @{User
11077Option@} @dots{}} and works like @code{@@defvar}.@refill
11078@end table
11079
11080
11081@node Typed Functions, Typed Variables, Variables Commands, Def Cmds in Detail
11082@subsection Functions in Typed Languages
11083
11084The @code{@@deftypefn} command and its variations are for describing
11085functions in languages in which you must declare types of variables and
11086functions, such as C and C++.
11087
11088@table @code
11089@findex deftypefn
11090@item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{}
11091The @code{@@deftypefn} command is the general definition command for
11092functions and similar entities that may take arguments and that are
11093typed. The @code{@@deftypefn} command is written at the beginning of
11094a line and is followed on the same line by the category of entity
11095being described, the type of the returned value, the name of this
11096particular entity, and its arguments, if any.@refill
11097
11098@need 800
11099@noindent
11100For example,
11101
11102@example
11103@group
11104@@deftypefn @{Library Function@} int foobar
11105 (int @@var@{foo@}, float @@var@{bar@})
11106@dots{}
11107@@end deftypefn
11108@end group
11109@end example
11110
11111@need 1000
11112@noindent
11113(where the text before the ``@dots{}'', shown above as two lines, would
11114actually be a single line in a real Texinfo file) produces the following
11115in Info:
11116
11117@smallexample
11118@group
11119-- Library Function: int foobar (int FOO, float BAR)
11120@dots{}
11121@end group
11122@end smallexample
11123@iftex
11124
11125In a printed manual, it produces:
11126
11127@quotation
11128@deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar})
11129@dots{}
11130@end deftypefn
11131@end quotation
11132@end iftex
11133
11134This means that @code{foobar} is a ``library function'' that returns an
11135@code{int}, and its arguments are @var{foo} (an @code{int}) and
11136@var{bar} (a @code{float}).@refill
11137
11138The argument names that you write in @code{@@deftypefn} are not subject
11139to an implicit @code{@@var}---since the actual names of the arguments in
11140@code{@@deftypefn} are typically scattered among data type names and
11141keywords, Texinfo cannot find them without help. Instead, you must write
11142@code{@@var} explicitly around the argument names. In the example
11143above, the argument names are @samp{foo} and @samp{bar}.@refill
11144
11145The template for @code{@@deftypefn} is:@refill
11146
11147@example
11148@group
11149@@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{}
11150@var{body-of-description}
11151@@end deftypefn
11152@end group
11153@end example
11154
11155@noindent
11156Note that if the @var{category} or @var{data type} is more than one
11157word then it must be enclosed in braces to make it a single argument.@refill
11158
11159If you are describing a procedure in a language that has packages,
11160such as Ada, you might consider using @code{@@deftypefn} in a manner
11161somewhat contrary to the convention described in the preceding
11162paragraphs.@refill
11163
11164@need 800
11165@noindent
11166For example:
11167
11168@example
11169@group
11170@@deftypefn stacks private push
11171 (@@var@{s@}:in out stack;
11172 @@var@{n@}:in integer)
11173@dots{}
11174@@end deftypefn
11175@end group
11176@end example
11177
11178@noindent
11179(The @code{@@deftypefn} arguments are shown split into three lines, but
11180would be a single line in a real Texinfo file.)
11181
11182In this instance, the procedure is classified as belonging to the
11183package @code{stacks} rather than classified as a `procedure' and its
11184data type is described as @code{private}. (The name of the procedure
11185is @code{push}, and its arguments are @var{s} and @var{n}.)@refill
11186
11187@code{@@deftypefn} creates an entry in the index of functions for
11188@var{name}.@refill
11189
11190@item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{}
11191@findex deftypefun
11192The @code{@@deftypefun} command is the specialized definition command
11193for functions in typed languages. The command is equivalent to
11194@samp{@@deftypefn Function @dots{}}.@refill
11195
11196@need 800
11197@noindent
11198Thus,
11199
11200@smallexample
11201@group
11202@@deftypefun int foobar (int @@var@{foo@}, float @@var@{bar@})
11203@dots{}
11204@@end deftypefun
11205@end group
11206@end smallexample
11207
11208@noindent
11209produces the following in Info:
11210
11211@example
11212@group
11213-- Function: int foobar (int FOO, float BAR)
11214@dots{}
11215@end group
11216@end example
11217@iftex
11218
11219@need 800
11220@noindent
11221and the following in a printed manual:
11222
11223@quotation
11224@deftypefun int foobar (int @var{foo}, float @var{bar})
11225@dots{}
11226@end deftypefun
11227@end quotation
11228@end iftex
11229
11230@need 800
11231The template is:
11232
11233@example
11234@group
11235@@deftypefun @var{type} @var{name} @var{arguments}@dots{}
11236@var{body-of-description}
11237@@end deftypefun
11238@end group
11239@end example
11240
11241@code{@@deftypefun} creates an entry in the index of functions for
11242@var{name}.@refill
11243
11244@end table
11245
11246
11247@node Typed Variables, Abstract Objects, Typed Functions, Def Cmds in Detail
11248@subsection Variables in Typed Languages
11249
11250Variables in typed languages are handled in a manner similar to
11251functions in typed languages. @xref{Typed Functions}. The general
11252definition command @code{@@deftypevr} corresponds to
11253@code{@@deftypefn} and the specialized definition command
11254@code{@@deftypevar} corresponds to @code{@@deftypefun}.@refill
11255
11256@table @code
11257@findex deftypevr
11258@item @@deftypevr @var{category} @var{data-type} @var{name}
11259The @code{@@deftypevr} command is the general definition command for
11260something like a variable in a typed language---an entity that records
11261a value. You must choose a term to describe the category of the
11262entity being defined; for example, ``Variable'' could be used if the
11263entity is a variable.@refill
11264
11265The @code{@@deftypevr} command is written at the beginning of a line
11266and is followed on the same line by the category of the entity
11267being described, the data type, and the name of this particular
11268entity.@refill
11269
11270@need 800
11271@noindent
11272For example:
11273
11274@example
11275@group
11276@@deftypevr @{Global Flag@} int enable
11277@dots{}
11278@@end deftypevr
11279@end group
11280@end example
11281
11282@noindent
11283produces the following in Info:
11284
11285@example
11286@group
11287-- Global Flag: int enable
11288@dots{}
11289@end group
11290@end example
11291@iftex
11292
11293@noindent
11294and the following in a printed manual:
11295
11296@quotation
11297@deftypevr {Global Flag} int enable
11298@dots{}
11299@end deftypevr
11300@end quotation
11301@end iftex
11302
11303@need 800
11304The template is:
11305
11306@example
11307@@deftypevr @var{category} @var{data-type} @var{name}
11308@var{body-of-description}
11309@@end deftypevr
11310@end example
11311
11312@code{@@deftypevr} creates an entry in the index of variables for
11313@var{name}.@refill
11314
11315@findex deftypevar
11316@item @@deftypevar @var{data-type} @var{name}
11317The @code{@@deftypevar} command is the specialized definition command
11318for variables in typed languages. @code{@@deftypevar} is equivalent
11319to @samp{@@deftypevr Variable @dots{}}.@refill
11320
11321@need 800
11322@noindent
11323For example:
11324
11325@example
11326@group
11327@@deftypevar int fubar
11328@dots{}
11329@@end deftypevar
11330@end group
11331@end example
11332
11333@noindent
11334produces the following in Info:
11335
11336@example
11337@group
11338-- Variable: int fubar
11339@dots{}
11340@end group
11341@end example
11342@iftex
11343
11344@need 800
11345@noindent
11346and the following in a printed manual:
11347
11348@quotation
11349@deftypevar int fubar
11350@dots{}
11351@end deftypevar
11352@end quotation
11353@end iftex
11354
11355@need 800
11356@noindent
11357The template is:
11358
11359@example
11360@group
11361@@deftypevar @var{data-type} @var{name}
11362@var{body-of-description}
11363@@end deftypevar
11364@end group
11365@end example
11366
11367@code{@@deftypevar} creates an entry in the index of variables for
11368@var{name}.@refill
11369@end table
11370
11371@node Abstract Objects
11372@subsection Object-Oriented Programming
11373
11374Here are the commands for formatting descriptions about abstract
11375objects, such as are used in object-oriented programming. A class is
11376a defined type of abstract object. An instance of a class is a
11377particular object that has the type of the class. An instance
11378variable is a variable that belongs to the class but for which each
11379instance has its own value.@refill
11380
11381In a definition, if the name of a class is truly a name defined in the
11382programming system for a class, then you should write an @code{@@code}
11383around it. Otherwise, it is printed in the usual text font.@refill
11384
11385@table @code
11386@findex defcv
11387@item @@defcv @var{category} @var{class} @var{name}
11388The @code{@@defcv} command is the general definition command for
11389variables associated with classes in object-oriented programming. The
11390@code{@@defcv} command is followed by three arguments: the category of
11391thing being defined, the class to which it belongs, and its
11392name. Thus,@refill
11393
11394@example
11395@group
11396@@defcv @{Class Option@} Window border-pattern
11397@dots{}
11398@@end defcv
11399@end group
11400@end example
11401
11402@noindent
11403illustrates how you would write the first line of a definition of the
11404@code{border-pattern} class option of the class @code{Window}.@refill
11405
11406The template is:
11407@example
11408@group
11409@@defcv @var{category} @var{class} @var{name}
11410@dots{}
11411@@end defcv
11412@end group
11413@end example
11414
11415@code{@@defcv} creates an entry in the index of variables.
11416
11417@findex defivar
11418@item @@defivar @var{class} @var{name}
11419The @code{@@defivar} command is the definition command for instance
11420variables in object-oriented programming. @code{@@defivar} is
11421equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}@refill
11422
11423The template is:
11424@example
11425@group
11426@@defivar @var{class} @var{instance-variable-name}
11427@var{body-of-definition}
11428@@end defivar
11429@end group
11430@end example
11431
11432@code{@@defivar} creates an entry in the index of variables.
11433
11434@findex deftypeivar
11435@item @@deftypeivar @var{class} @var{data-type} @var{name}
11436The @code{@@deftypeivar} command is the definition command for typed
11437instance variables in object-oriented programming. It is similar to
11438@code{@@defivar} with the addition of the @var{data-type} parameter to
11439specify the type of the instance variable. @code{@@deftypeivar} creates an
11440entry in the index of variables.
11441
11442@findex defop
11443@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
11444The @code{@@defop} command is the general definition command for
11445entities that may resemble methods in object-oriented programming.
11446These entities take arguments, as functions do, but are associated with
11447particular classes of objects.@refill
11448
11449For example, some systems have constructs called @dfn{wrappers} that
11450are associated with classes as methods are, but that act more like
11451macros than like functions. You could use @code{@@defop Wrapper} to
11452describe one of these.@refill
11453
11454Sometimes it is useful to distinguish methods and @dfn{operations}.
11455You can think of an operation as the specification for a method.
11456Thus, a window system might specify that all window classes have a
11457method named @code{expose}; we would say that this window system
11458defines an @code{expose} operation on windows in general. Typically,
11459the operation has a name and also specifies the pattern of arguments;
11460all methods that implement the operation must accept the same
11461arguments, since applications that use the operation do so without
11462knowing which method will implement it.@refill
11463
11464Often it makes more sense to document operations than methods. For
11465example, window application developers need to know about the
11466@code{expose} operation, but need not be concerned with whether a
11467given class of windows has its own method to implement this operation.
11468To describe this operation, you would write:@refill
11469
11470@example
11471@@defop Operation windows expose
11472@end example
11473
11474The @code{@@defop} command is written at the beginning of a line and
11475is followed on the same line by the overall name of the category of
11476operation, the name of the class of the operation, the name of the
11477operation, and its arguments, if any.@refill
11478
11479The template is:
11480@example
11481@group
11482@@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
11483@var{body-of-definition}
11484@@end defop
11485@end group
11486@end example
11487
11488@code{@@defop} creates an entry, such as `@code{expose} on
11489@code{windows}', in the index of functions.@refill
11490
11491@findex deftypeop
11492@item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
11493The @code{@@deftypeop} command is the definition command for typed
11494operations in object-oriented programming. It is similar to
11495@code{@@defop} with the addition of the @var{data-type} parameter to
11496specify the return type of the method. @code{@@deftypeop} creates an
11497entry in the index of functions.
11498
11499@item @@defmethod @var{class} @var{name} @var{arguments}@dots{}
11500@findex defmethod
11501The @code{@@defmethod} command is the definition command for methods
11502in object-oriented programming. A method is a kind of function that
11503implements an operation for a particular class of objects and its
11504subclasses.
11505@ignore
11506@c ADR: Who cares?!?
11507@c KB: Oh, I don't know, I think this info is crucial!
11508In the Lisp Machine, methods actually were functions, but
11509they were usually defined with @code{defmethod}.
11510@end ignore
11511
11512@code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}.
11513The command is written at the beginning of a line and is followed by
11514the name of the class of the method, the name of the method, and its
11515arguments, if any.@refill
11516
11517@noindent
11518For example:
11519@example
11520@group
11521@@defmethod @code{bar-class} bar-method argument
11522@dots{}
11523@@end defmethod
11524@end group
11525@end example
11526
11527@noindent
11528illustrates the definition for a method called @code{bar-method} of
11529the class @code{bar-class}. The method takes an argument.@refill
11530
11531The template is:
11532
11533@example
11534@group
11535@@defmethod @var{class} @var{method-name} @var{arguments}@dots{}
11536@var{body-of-definition}
11537@@end defmethod
11538@end group
11539@end example
11540
11541@code{@@defmethod} creates an entry, such as `@code{bar-method} on
11542@code{bar-class}', in the index of functions.@refill
11543
11544
11545@item @@deftypemethod @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
11546@findex defmethod
11547The @code{@@deftypemethod} command is the definition command for methods
11548in object-oriented typed languages, such as C++ and Java. It is similar
11549to the @code{@@defmethod} command with the addition of the
11550@var{data-type} parameter to specify the return type of the method.
11551
11552@end table
11553
11554
11555@node Data Types
11556@subsection Data Types
11557
11558Here is the command for data types:@refill
11559
11560@table @code
11561@findex deftp
11562@item @@deftp @var{category} @var{name} @var{attributes}@dots{}
11563The @code{@@deftp} command is the generic definition command for data
11564types. The command is written at the beginning of a line and is
11565followed on the same line by the category, by the name of the type
11566(which is a word like @code{int} or @code{float}), and then by names of
11567attributes of objects of that type. Thus, you could use this command
11568for describing @code{int} or @code{float}, in which case you could use
11569@code{data type} as the category. (A data type is a category of
11570certain objects for purposes of deciding which operations can be
11571performed on them.)@refill
11572
11573In Lisp, for example, @dfn{pair} names a particular data
11574type, and an object of that type has two slots called the
11575@sc{car} and the @sc{cdr}. Here is how you would write the first line
11576of a definition of @code{pair}.@refill
11577
11578@example
11579@group
11580@@deftp @{Data type@} pair car cdr
11581@dots{}
11582@@end deftp
11583@end group
11584@end example
11585
11586@need 950
11587The template is:
11588
11589@example
11590@group
11591@@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
11592@var{body-of-definition}
11593@@end deftp
11594@end group
11595@end example
11596
11597@code{@@deftp} creates an entry in the index of data types.
11598@end table
11599
11600@node Def Cmd Conventions, Sample Function Definition, Def Cmds in Detail, Definition Commands
11601@section Conventions for Writing Definitions
11602@cindex Definition conventions
11603@cindex Conventions for writing definitions
11604
11605When you write a definition using @code{@@deffn}, @code{@@defun}, or
11606one of the other definition commands, please take care to use
11607arguments that indicate the meaning, as with the @var{count} argument
11608to the @code{forward-word} function. Also, if the name of an argument
11609contains the name of a type, such as @var{integer}, take care that the
11610argument actually is of that type.@refill
11611
11612@node Sample Function Definition, , Def Cmd Conventions, Definition Commands
11613@section A Sample Function Definition
11614@cindex Function definitions
11615@cindex Command definitions
11616@cindex Macro definitions
11617@cindex Sample function definition
11618
11619A function definition uses the @code{@@defun} and @code{@@end defun}
11620commands. The name of the function follows immediately after the
11621@code{@@defun} command and it is followed, on the same line, by the
11622parameter list.@refill
11623
11624Here is a definition from @ref{Calling Functions,,, elisp, The GNU Emacs
11625Lisp Reference Manual}.
11626
11627@quotation
11628@defun apply function &rest arguments
11629@code{apply} calls @var{function} with @var{arguments}, just
11630like @code{funcall} but with one difference: the last of
11631@var{arguments} is a list of arguments to give to
11632@var{function}, rather than a single argument. We also say
11633that this list is @dfn{appended} to the other arguments.
11634
11635@code{apply} returns the result of calling @var{function}.
11636As with @code{funcall}, @var{function} must either be a Lisp
11637function or a primitive function; special forms and macros
11638do not make sense in @code{apply}.
11639
11640@example
11641(setq f 'list)
11642 @result{} list
11643(apply f 'x 'y 'z)
11644@error{} Wrong type argument: listp, z
11645(apply '+ 1 2 '(3 4))
11646 @result{} 10
11647(apply '+ '(1 2 3 4))
11648 @result{} 10
11649
11650(apply 'append '((a b c) nil (x y z) nil))
11651 @result{} (a b c x y z)
11652@end example
11653
11654An interesting example of using @code{apply} is found in the description
11655of @code{mapcar}.@refill
11656@end defun
11657@end quotation
11658
11659@need 1200
11660In the Texinfo source file, this example looks like this:
11661
11662@example
11663@group
11664@@defun apply function &rest arguments
11665@@code@{apply@} calls @@var@{function@} with
11666@@var@{arguments@}, just like @@code@{funcall@} but with one
11667difference: the last of @@var@{arguments@} is a list of
11668arguments to give to @@var@{function@}, rather than a single
11669argument. We also say that this list is @@dfn@{appended@}
11670to the other arguments.
11671@end group
11672
11673@group
11674@@code@{apply@} returns the result of calling
11675@@var@{function@}. As with @@code@{funcall@},
11676@@var@{function@} must either be a Lisp function or a
11677primitive function; special forms and macros do not make
11678sense in @@code@{apply@}.
11679@end group
11680
11681@group
11682@@example
11683(setq f 'list)
11684 @@result@{@} list
11685(apply f 'x 'y 'z)
11686@@error@{@} Wrong type argument: listp, z
11687(apply '+ 1 2 '(3 4))
11688 @@result@{@} 10
11689(apply '+ '(1 2 3 4))
11690 @@result@{@} 10
11691
11692(apply 'append '((a b c) nil (x y z) nil))
11693 @@result@{@} (a b c x y z)
11694@@end example
11695@end group
11696
11697@group
11698An interesting example of using @@code@{apply@} is found
11699in the description of @@code@{mapcar@}.
11700@@end defun
11701@end group
11702@end example
11703
11704@noindent
11705In this manual, this function is listed in the Command and Variable
11706Index under @code{apply}.@refill
11707
11708Ordinary variables and user options are described using a format like
11709that for functions except that variables do not take arguments.
11710
11711
11712@node Conditionals
11713@chapter Conditionally Visible Text
11714@cindex Conditionally visible text
11715@cindex Text, conditionally visible
11716@cindex Visibility of conditional text
11717@cindex If text conditionally visible
11718
11719Sometimes it is good to use different text for different output formats.
11720For example, you can use the @dfn{conditional commands} to specify
11721different text for the printed manual and the Info output.
11722
11723Conditional commands may not be nested.
11724
11725The conditional commands comprise the following categories.
11726
11727@itemize @bullet
11728@item Commands for HTML, Info, or @TeX{}.
11729@item Commands for not HTML, Info, or @TeX{}.
11730@item Raw @TeX{} or HTML commands.
11731@item
11732Substituting text for all formats, and testing if a flag is set or clear.
11733@end itemize
11734
11735@menu
11736* Conditional Commands:: Specifying text for HTML, Info, or @TeX{}.
11737* Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}.
11738* Raw Formatter Commands:: Using raw @TeX{} or HTML commands.
11739* set clear value:: Designating which text to format (for
11740 all output formats); and how to set a
11741 flag to a string that you can insert.
11742@end menu
11743
11744
11745@node Conditional Commands
11746@section Conditional Commands
11747
| 10469
10470@item @@hyphenation@{@var{hy-phen-a-ted words}@}
10471Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you
10472put a @samp{-} at each hyphenation point. For example:
10473@example
10474@@hyphenation@{man-u-script man-u-scripts@}
10475@end example
10476@noindent @TeX{} only uses the specified hyphenation points when the
10477words match exactly, so give all necessary variants.
10478@end table
10479
10480Info output is not hyphenated, so these commands have no effect there.
10481
10482@node w
10483@section @code{@@w}@{@var{text}@}: Prevent Line Breaks
10484@findex w @r{(prevent line break)}
10485@cindex Line breaks, preventing
10486@cindex Hyphenation, preventing
10487
10488@code{@@w@{@var{text}@}} outputs @var{text} and prohibits line breaks
10489within @var{text}.@refill
10490
10491You can use the @code{@@w} command to prevent @TeX{} from automatically
10492hyphenating a long name or phrase that happens to fall near the end of a
10493line. For example:
10494
10495@example
10496You can copy GNU software from @@w@{@@samp@{ftp.gnu.org@}@}.
10497@end example
10498
10499@noindent
10500produces
10501
10502@quotation
10503You can copy GNU software from @w{@samp{ftp.gnu.org}}.
10504@end quotation
10505
10506@cindex Non-breakable space
10507@cindex Unbreakable space
10508@cindex Tied space
10509You can also use @code{@@w} to produce a non-breakable space:
10510
10511@example
10512None of the formatters will break at this@@w@{ @}space.
10513@end example
10514
10515
10516@node sp
10517@section @code{@@sp} @var{n}: Insert Blank Lines
10518@findex sp @r{(line spacing)}
10519@cindex Space, inserting vertical
10520@cindex Blank lines
10521@cindex Line spacing
10522
10523A line beginning with and containing only @code{@@sp @var{n}}
10524generates @var{n} blank lines of space in both the printed manual and
10525the Info file. @code{@@sp} also forces a paragraph break. For
10526example,
10527
10528@example
10529@@sp 2
10530@end example
10531
10532@noindent
10533generates two blank lines.
10534
10535The @code{@@sp} command is most often used in the title page.@refill
10536
10537@ignore
10538@c node br, page, sp, Breaks
10539@comment node-name, next, previous, up
10540@c section @code{@@br}: Generate Paragraph Breaks
10541@findex br @r{(paragraph breaks)}
10542@cindex Paragraph breaks
10543@cindex Breaks in a paragraph
10544
10545The @code{@@br} command forces a paragraph break. It inserts a blank
10546line. You can use the command within or at the end of a line. If
10547used within a line, the @code{@@br@{@}} command must be followed by
10548left and right braces (as shown here) to mark the end of the
10549command.@refill
10550
10551@need 700
10552For example,
10553
10554@example
10555@group
10556This line @@br@{@}contains and is ended by paragraph breaks@@br
10557and is followed by another line.
10558@end group
10559@end example
10560
10561@noindent
10562produces
10563
10564@example
10565@group
10566This line
10567
10568contains and is ended by paragraph breaks
10569
10570and is followed by another line.
10571@end group
10572@end example
10573
10574The @code{@@br} command is seldom used.
10575@end ignore
10576
10577
10578@node page
10579@section @code{@@page}: Start a New Page
10580@cindex Page breaks
10581@findex page
10582
10583A line containing only @code{@@page} starts a new page in a printed
10584manual. The command has no effect on Info files since they are not
10585paginated. An @code{@@page} command is often used in the @code{@@titlepage}
10586section of a Texinfo file to start the copyright page.
10587
10588
10589@node group, need, page, Breaks
10590@comment node-name, next, previous, up
10591@section @code{@@group}: Prevent Page Breaks
10592@cindex Group (hold text together vertically)
10593@cindex Holding text together vertically
10594@cindex Vertically holding text together
10595@findex group
10596
10597The @code{@@group} command (on a line by itself) is used inside an
10598@code{@@example} or similar construct to begin an unsplittable vertical
10599group, which will appear entirely on one page in the printed output.
10600The group is terminated by a line containing only @code{@@end group}.
10601These two lines produce no output of their own, and in the Info file
10602output they have no effect at all.@refill
10603
10604@c Once said that these environments
10605@c turn off vertical spacing between ``paragraphs''.
10606@c Also, quotation used to work, but doesn't in texinfo-2.72
10607Although @code{@@group} would make sense conceptually in a wide
10608variety of contexts, its current implementation works reliably only
10609within @code{@@example} and variants, and within @code{@@display},
10610@code{@@format}, @code{@@flushleft} and @code{@@flushright}.
10611@xref{Quotations and Examples}. (What all these commands have in
10612common is that each line of input produces a line of output.) In
10613other contexts, @code{@@group} can cause anomalous vertical
10614spacing.@refill
10615
10616@need 750
10617This formatting requirement means that you should write:
10618
10619@example
10620@group
10621@@example
10622@@group
10623@dots{}
10624@@end group
10625@@end example
10626@end group
10627@end example
10628
10629@noindent
10630with the @code{@@group} and @code{@@end group} commands inside the
10631@code{@@example} and @code{@@end example} commands.
10632
10633The @code{@@group} command is most often used to hold an example
10634together on one page. In this Texinfo manual, more than 100 examples
10635contain text that is enclosed between @code{@@group} and @code{@@end
10636group}.
10637
10638If you forget to end a group, you may get strange and unfathomable
10639error messages when you run @TeX{}. This is because @TeX{} keeps
10640trying to put the rest of the Texinfo file onto the one page and does
10641not start to generate error messages until it has processed
10642considerable text. It is a good rule of thumb to look for a missing
10643@code{@@end group} if you get incomprehensible error messages in
10644@TeX{}.@refill
10645
10646@node need, , group, Breaks
10647@comment node-name, next, previous, up
10648@section @code{@@need @var{mils}}: Prevent Page Breaks
10649@cindex Need space at page bottom
10650@findex need
10651
10652A line containing only @code{@@need @var{n}} starts
10653a new page in a printed manual if fewer than @var{n} mils (thousandths
10654of an inch) remain on the current page. Do not use
10655braces around the argument @var{n}. The @code{@@need} command has no
10656effect on Info files since they are not paginated.@refill
10657
10658@need 800
10659This paragraph is preceded by an @code{@@need} command that tells
10660@TeX{} to start a new page if fewer than 800 mils (eight-tenths
10661inch) remain on the page. It looks like this:@refill
10662
10663@example
10664@group
10665@@need 800
10666This paragraph is preceded by @dots{}
10667@end group
10668@end example
10669
10670The @code{@@need} command is useful for preventing orphans (single
10671lines at the bottoms of printed pages).@refill
10672
10673
10674@node Definition Commands
10675@chapter Definition Commands
10676@cindex Definition commands
10677
10678The @code{@@deffn} command and the other @dfn{definition commands}
10679enable you to describe functions, variables, macros, commands, user
10680options, special forms and other such artifacts in a uniform
10681format.@refill
10682
10683In the Info file, a definition causes the entity
10684category---`Function', `Variable', or whatever---to appear at the
10685beginning of the first line of the definition, followed by the
10686entity's name and arguments. In the printed manual, the command
10687causes @TeX{} to print the entity's name and its arguments on the left
10688margin and print the category next to the right margin. In both
10689output formats, the body of the definition is indented. Also, the
10690name of the entity is entered into the appropriate index:
10691@code{@@deffn} enters the name into the index of functions,
10692@code{@@defvr} enters it into the index of variables, and so
10693on.@refill
10694
10695A manual need not and should not contain more than one definition for
10696a given name. An appendix containing a summary should use
10697@code{@@table} rather than the definition commands.@refill
10698
10699@menu
10700* Def Cmd Template:: How to structure a description using a
10701 definition command.
10702* Optional Arguments:: How to handle optional and repeated arguments.
10703* deffnx:: How to group two or more `first' lines.
10704* Def Cmds in Detail:: All the definition commands.
10705* Def Cmd Conventions:: Conventions for writing definitions.
10706* Sample Function Definition::
10707@end menu
10708
10709@node Def Cmd Template, Optional Arguments, Definition Commands, Definition Commands
10710@section The Template for a Definition
10711@cindex Definition template
10712@cindex Template for a definition
10713
10714The @code{@@deffn} command is used for definitions of entities that
10715resemble functions. To write a definition using the @code{@@deffn}
10716command, write the @code{@@deffn} command at the beginning of a line
10717and follow it on the same line by the category of the entity, the name
10718of the entity itself, and its arguments (if any). Then write the body
10719of the definition on succeeding lines. (You may embed examples in the
10720body.) Finally, end the definition with an @code{@@end deffn} command
10721written on a line of its own. (The other definition commands follow
10722the same format.)@refill
10723
10724The template for a definition looks like this:
10725
10726@example
10727@group
10728@@deffn @var{category} @var{name} @var{arguments}@dots{}
10729@var{body-of-definition}
10730@@end deffn
10731@end group
10732@end example
10733
10734@need 700
10735@noindent
10736For example,
10737
10738@example
10739@group
10740@@deffn Command forward-word count
10741This command moves point forward @@var@{count@} words
10742(or backward if @@var@{count@} is negative). @dots{}
10743@@end deffn
10744@end group
10745@end example
10746
10747@noindent
10748produces
10749
10750@quotation
10751@deffn Command forward-word count
10752This function moves point forward @var{count} words
10753(or backward if @var{count} is negative). @dots{}
10754@end deffn
10755@end quotation
10756
10757Capitalize the category name like a title. If the name of the
10758category contains spaces, as in the phrase `Interactive Command',
10759write braces around it. For example:@refill
10760
10761@example
10762@group
10763@@deffn @{Interactive Command@} isearch-forward
10764@dots{}
10765@@end deffn
10766@end group
10767@end example
10768
10769@noindent
10770Otherwise, the second word will be mistaken for the name of the
10771entity.@refill
10772
10773Some of the definition commands are more general than others. The
10774@code{@@deffn} command, for example, is the general definition command
10775for functions and the like---for entities that may take arguments. When
10776you use this command, you specify the category to which the entity
10777belongs. The @code{@@deffn} command possesses three predefined,
10778specialized variations, @code{@@defun}, @code{@@defmac}, and
10779@code{@@defspec}, that specify the category for you: ``Function'',
10780``Macro'', and ``Special Form'' respectively. (In Lisp, a special form
10781is an entity much like a function.) The @code{@@defvr} command also is
10782accompanied by several predefined, specialized variations for describing
10783particular kinds of variables.@refill
10784
10785The template for a specialized definition, such as @code{@@defun}, is
10786similar to the template for a generalized definition, except that you
10787do not need to specify the category:@refill
10788
10789@example
10790@group
10791@@defun @var{name} @var{arguments}@dots{}
10792@var{body-of-definition}
10793@@end defun
10794@end group
10795@end example
10796
10797@noindent
10798Thus,
10799
10800@example
10801@group
10802@@defun buffer-end flag
10803This function returns @@code@{(point-min)@} if @@var@{flag@}
10804is less than 1, @@code@{(point-max)@} otherwise.
10805@dots{}
10806@@end defun
10807@end group
10808@end example
10809
10810@noindent
10811produces
10812
10813@quotation
10814@defun buffer-end flag
10815This function returns @code{(point-min)} if @var{flag} is less than 1,
10816@code{(point-max)} otherwise. @dots{}
10817@end defun
10818@end quotation
10819
10820@noindent
10821@xref{Sample Function Definition, Sample Function Definition, A Sample
10822Function Definition}, for a more detailed example of a function
10823definition, including the use of @code{@@example} inside the
10824definition.@refill
10825
10826The other specialized commands work like @code{@@defun}.@refill
10827
10828@cindex Macros in definition commands
10829Note that, due to implementation difficulties, macros are not expanded
10830in @code{@@deffn} and all the other definition commands.
10831
10832@node Optional Arguments, deffnx, Def Cmd Template, Definition Commands
10833@section Optional and Repeated Arguments
10834@cindex Optional and repeated arguments
10835@cindex Repeated and optional arguments
10836@cindex Arguments, repeated and optional
10837@cindex Syntax, optional & repeated arguments
10838@cindex Meta-syntactic chars for arguments
10839
10840Some entities take optional or repeated arguments, which may be
10841specified by a distinctive glyph that uses square brackets and
10842ellipses. For @w{example}, a special form often breaks its argument list
10843into separate arguments in more complicated ways than a
10844straightforward function.@refill
10845
10846@iftex
10847An argument enclosed within square brackets is optional.
10848Thus, the phrase
10849@samp{@code{@r{[}@var{optional-arg}@r{]}}} means that
10850@var{optional-arg} is optional.
10851An argument followed by an ellipsis is optional
10852and may be repeated more than once.
10853@c This is consistent with Emacs Lisp Reference manual
10854Thus, @samp{@var{repeated-args}@dots{}} stands for zero or more arguments.
10855Parentheses are used when several arguments are grouped
10856into additional levels of list structure in Lisp.
10857@end iftex
10858@c The following looks better in Info (no `r', `samp' and `code'):
10859@ifinfo
10860An argument enclosed within square brackets is optional.
10861Thus, [@var{optional-arg}] means that @var{optional-arg} is optional.
10862An argument followed by an ellipsis is optional
10863and may be repeated more than once.
10864@c This is consistent with Emacs Lisp Reference manual
10865Thus, @var{repeated-args}@dots{} stands for zero or more arguments.
10866Parentheses are used when several arguments are grouped
10867into additional levels of list structure in Lisp.
10868@end ifinfo
10869
10870Here is the @code{@@defspec} line of an example of an imaginary
10871special form:@refill
10872
10873@quotation
10874@defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{}
10875@end defspec
10876@tex
10877\vskip \parskip
10878@end tex
10879@end quotation
10880
10881@noindent
10882In this example, the arguments @var{from} and @var{to} are optional,
10883but must both be present or both absent. If they are present,
10884@var{inc} may optionally be specified as well. These arguments are
10885grouped with the argument @var{var} into a list, to distinguish them
10886from @var{body}, which includes all remaining elements of the
10887form.@refill
10888
10889In a Texinfo source file, this @code{@@defspec} line is written like
10890this (except it would not be split over two lines, as it is in this
10891example).@refill
10892
10893@example
10894@group
10895@@defspec foobar (@@var@{var@} [@@var@{from@} @@var@{to@}
10896 [@@var@{inc@}]]) @@var@{body@}@@dots@{@}
10897@end group
10898@end example
10899
10900@noindent
10901The function is listed in the Command and Variable Index under
10902@samp{foobar}.@refill
10903
10904@node deffnx, Def Cmds in Detail, Optional Arguments, Definition Commands
10905@section Two or More `First' Lines
10906@cindex Two `First' Lines for @code{@@deffn}
10907@cindex Grouping two definitions together
10908@cindex Definitions grouped together
10909@findex deffnx
10910
10911To create two or more `first' or header lines for a definition, follow
10912the first @code{@@deffn} line by a line beginning with @code{@@deffnx}.
10913The @code{@@deffnx} command works exactly like @code{@@deffn}
10914except that it does not generate extra vertical white space between it
10915and the preceding line.@refill
10916
10917@need 1000
10918For example,
10919
10920@example
10921@group
10922@@deffn @{Interactive Command@} isearch-forward
10923@@deffnx @{Interactive Command@} isearch-backward
10924These two search commands are similar except @dots{}
10925@@end deffn
10926@end group
10927@end example
10928
10929@noindent
10930produces
10931
10932@deffn {Interactive Command} isearch-forward
10933@deffnx {Interactive Command} isearch-backward
10934These two search commands are similar except @dots{}
10935@end deffn
10936
10937Each definition command has an `x' form: @code{@@defunx},
10938@code{@@defvrx}, @code{@@deftypefunx}, etc.
10939
10940The `x' forms work just like @code{@@itemx}; see @ref{itemx, , @code{@@itemx}}.
10941
10942@node Def Cmds in Detail, Def Cmd Conventions, deffnx, Definition Commands
10943@section The Definition Commands
10944
10945Texinfo provides more than a dozen definition commands, all of which
10946are described in this section.@refill
10947
10948The definition commands automatically enter the name of the entity in
10949the appropriate index: for example, @code{@@deffn}, @code{@@defun},
10950and @code{@@defmac} enter function names in the index of functions;
10951@code{@@defvr} and @code{@@defvar} enter variable names in the index
10952of variables.@refill
10953
10954Although the examples that follow mostly illustrate Lisp, the commands
10955can be used for other programming languages.@refill
10956
10957@menu
10958* Functions Commands:: Commands for functions and similar entities.
10959* Variables Commands:: Commands for variables and similar entities.
10960* Typed Functions:: Commands for functions in typed languages.
10961* Typed Variables:: Commands for variables in typed languages.
10962* Abstract Objects:: Commands for object-oriented programming.
10963* Data Types:: The definition command for data types.
10964@end menu
10965
10966@node Functions Commands, Variables Commands, Def Cmds in Detail, Def Cmds in Detail
10967@subsection Functions and Similar Entities
10968
10969This section describes the commands for describing functions and similar
10970entities:@refill
10971
10972@table @code
10973@findex deffn
10974@item @@deffn @var{category} @var{name} @var{arguments}@dots{}
10975The @code{@@deffn} command is the general definition command for
10976functions, interactive commands, and similar entities that may take
10977arguments. You must choose a term to describe the category of entity
10978being defined; for example, ``Function'' could be used if the entity is
10979a function. The @code{@@deffn} command is written at the beginning of a
10980line and is followed on the same line by the category of entity being
10981described, the name of this particular entity, and its arguments, if
10982any. Terminate the definition with @code{@@end deffn} on a line of its
10983own.@refill
10984
10985@need 750
10986For example, here is a definition:
10987
10988@example
10989@group
10990@@deffn Command forward-char nchars
10991Move point forward @@var@{nchars@} characters.
10992@@end deffn
10993@end group
10994@end example
10995
10996@noindent
10997This shows a rather terse definition for a ``command'' named
10998@code{forward-char} with one argument, @var{nchars}.
10999
11000@code{@@deffn} prints argument names such as @var{nchars} in italics or
11001upper case, as if @code{@@var} had been used, because we think of these
11002names as metasyntactic variables---they stand for the actual argument
11003values. Within the text of the description, write an argument name
11004explicitly with @code{@@var} to refer to the value of the argument. In
11005the example above, we used @samp{@@var@{nchars@}} in this way.
11006
11007The template for @code{@@deffn} is:
11008
11009@example
11010@group
11011@@deffn @var{category} @var{name} @var{arguments}@dots{}
11012@var{body-of-definition}
11013@@end deffn
11014@end group
11015@end example
11016
11017@findex defun
11018@item @@defun @var{name} @var{arguments}@dots{}
11019The @code{@@defun} command is the definition command for functions.
11020@code{@@defun} is equivalent to @samp{@@deffn Function
11021@dots{}}.@refill
11022
11023@need 800
11024@noindent
11025For example,
11026
11027@example
11028@group
11029@@defun set symbol new-value
11030Change the value of the symbol @@var@{symbol@}
11031to @@var@{new-value@}.
11032@@end defun
11033@end group
11034@end example
11035
11036@noindent
11037shows a rather terse definition for a function @code{set} whose
11038arguments are @var{symbol} and @var{new-value}. The argument names on
11039the @code{@@defun} line automatically appear in italics or upper case as
11040if they were enclosed in @code{@@var}. Terminate the definition with
11041@code{@@end defun} on a line of its own.@refill
11042
11043The template is:
11044
11045@example
11046@group
11047@@defun @var{function-name} @var{arguments}@dots{}
11048@var{body-of-definition}
11049@@end defun
11050@end group
11051@end example
11052
11053@code{@@defun} creates an entry in the index of functions.
11054
11055@findex defmac
11056@item @@defmac @var{name} @var{arguments}@dots{}
11057The @code{@@defmac} command is the definition command for macros.
11058@code{@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and
11059works like @code{@@defun}.@refill
11060
11061@findex defspec
11062@item @@defspec @var{name} @var{arguments}@dots{}
11063The @code{@@defspec} command is the definition command for special
11064forms. (In Lisp, a special form is an entity much like a function,
11065@pxref{Special Forms,,, elisp, GNU Emacs Lisp Reference Manual}.)
11066@code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@}
11067@dots{}} and works like @code{@@defun}.@refill
11068@end table
11069
11070@node Variables Commands, Typed Functions, Functions Commands, Def Cmds in Detail
11071@subsection Variables and Similar Entities
11072
11073Here are the commands for defining variables and similar
11074entities:@refill
11075
11076@table @code
11077@findex defvr
11078@item @@defvr @var{category} @var{name}
11079The @code{@@defvr} command is a general definition command for
11080something like a variable---an entity that records a value. You must
11081choose a term to describe the category of entity being defined; for
11082example, ``Variable'' could be used if the entity is a variable.
11083Write the @code{@@defvr} command at the beginning of a line and
11084follow it on the same line by the category of the entity and the
11085name of the entity.
11086
11087Capitalize the category name like a title. If the name of the category
11088contains spaces, as in the name ``User Option'', enclose it in braces.
11089Otherwise, the second word will be mistaken for the name of the entity.
11090For example,
11091
11092@example
11093@group
11094@@defvr @{User Option@} fill-column
11095This buffer-local variable specifies
11096the maximum width of filled lines.
11097@dots{}
11098@@end defvr
11099@end group
11100@end example
11101
11102Terminate the definition with @code{@@end defvr} on a line of its
11103own.@refill
11104
11105The template is:
11106
11107@example
11108@group
11109@@defvr @var{category} @var{name}
11110@var{body-of-definition}
11111@@end defvr
11112@end group
11113@end example
11114
11115@code{@@defvr} creates an entry in the index of variables for @var{name}.
11116
11117@findex defvar
11118@item @@defvar @var{name}
11119The @code{@@defvar} command is the definition command for variables.
11120@code{@@defvar} is equivalent to @samp{@@defvr Variable
11121@dots{}}.@refill
11122
11123@need 750
11124For example:
11125
11126@example
11127@group
11128@@defvar kill-ring
11129@dots{}
11130@@end defvar
11131@end group
11132@end example
11133
11134The template is:
11135
11136@example
11137@group
11138@@defvar @var{name}
11139@var{body-of-definition}
11140@@end defvar
11141@end group
11142@end example
11143
11144@code{@@defvar} creates an entry in the index of variables for
11145@var{name}.@refill
11146
11147@findex defopt
11148@item @@defopt @var{name}
11149@cindex User options, marking
11150The @code{@@defopt} command is the definition command for @dfn{user
11151options}, i.e., variables intended for users to change according to
11152taste; Emacs has many such (@pxref{Variables,,, emacs, The GNU Emacs
11153Manual}). @code{@@defopt} is equivalent to @samp{@@defvr @{User
11154Option@} @dots{}} and works like @code{@@defvar}.@refill
11155@end table
11156
11157
11158@node Typed Functions, Typed Variables, Variables Commands, Def Cmds in Detail
11159@subsection Functions in Typed Languages
11160
11161The @code{@@deftypefn} command and its variations are for describing
11162functions in languages in which you must declare types of variables and
11163functions, such as C and C++.
11164
11165@table @code
11166@findex deftypefn
11167@item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{}
11168The @code{@@deftypefn} command is the general definition command for
11169functions and similar entities that may take arguments and that are
11170typed. The @code{@@deftypefn} command is written at the beginning of
11171a line and is followed on the same line by the category of entity
11172being described, the type of the returned value, the name of this
11173particular entity, and its arguments, if any.@refill
11174
11175@need 800
11176@noindent
11177For example,
11178
11179@example
11180@group
11181@@deftypefn @{Library Function@} int foobar
11182 (int @@var@{foo@}, float @@var@{bar@})
11183@dots{}
11184@@end deftypefn
11185@end group
11186@end example
11187
11188@need 1000
11189@noindent
11190(where the text before the ``@dots{}'', shown above as two lines, would
11191actually be a single line in a real Texinfo file) produces the following
11192in Info:
11193
11194@smallexample
11195@group
11196-- Library Function: int foobar (int FOO, float BAR)
11197@dots{}
11198@end group
11199@end smallexample
11200@iftex
11201
11202In a printed manual, it produces:
11203
11204@quotation
11205@deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar})
11206@dots{}
11207@end deftypefn
11208@end quotation
11209@end iftex
11210
11211This means that @code{foobar} is a ``library function'' that returns an
11212@code{int}, and its arguments are @var{foo} (an @code{int}) and
11213@var{bar} (a @code{float}).@refill
11214
11215The argument names that you write in @code{@@deftypefn} are not subject
11216to an implicit @code{@@var}---since the actual names of the arguments in
11217@code{@@deftypefn} are typically scattered among data type names and
11218keywords, Texinfo cannot find them without help. Instead, you must write
11219@code{@@var} explicitly around the argument names. In the example
11220above, the argument names are @samp{foo} and @samp{bar}.@refill
11221
11222The template for @code{@@deftypefn} is:@refill
11223
11224@example
11225@group
11226@@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{}
11227@var{body-of-description}
11228@@end deftypefn
11229@end group
11230@end example
11231
11232@noindent
11233Note that if the @var{category} or @var{data type} is more than one
11234word then it must be enclosed in braces to make it a single argument.@refill
11235
11236If you are describing a procedure in a language that has packages,
11237such as Ada, you might consider using @code{@@deftypefn} in a manner
11238somewhat contrary to the convention described in the preceding
11239paragraphs.@refill
11240
11241@need 800
11242@noindent
11243For example:
11244
11245@example
11246@group
11247@@deftypefn stacks private push
11248 (@@var@{s@}:in out stack;
11249 @@var@{n@}:in integer)
11250@dots{}
11251@@end deftypefn
11252@end group
11253@end example
11254
11255@noindent
11256(The @code{@@deftypefn} arguments are shown split into three lines, but
11257would be a single line in a real Texinfo file.)
11258
11259In this instance, the procedure is classified as belonging to the
11260package @code{stacks} rather than classified as a `procedure' and its
11261data type is described as @code{private}. (The name of the procedure
11262is @code{push}, and its arguments are @var{s} and @var{n}.)@refill
11263
11264@code{@@deftypefn} creates an entry in the index of functions for
11265@var{name}.@refill
11266
11267@item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{}
11268@findex deftypefun
11269The @code{@@deftypefun} command is the specialized definition command
11270for functions in typed languages. The command is equivalent to
11271@samp{@@deftypefn Function @dots{}}.@refill
11272
11273@need 800
11274@noindent
11275Thus,
11276
11277@smallexample
11278@group
11279@@deftypefun int foobar (int @@var@{foo@}, float @@var@{bar@})
11280@dots{}
11281@@end deftypefun
11282@end group
11283@end smallexample
11284
11285@noindent
11286produces the following in Info:
11287
11288@example
11289@group
11290-- Function: int foobar (int FOO, float BAR)
11291@dots{}
11292@end group
11293@end example
11294@iftex
11295
11296@need 800
11297@noindent
11298and the following in a printed manual:
11299
11300@quotation
11301@deftypefun int foobar (int @var{foo}, float @var{bar})
11302@dots{}
11303@end deftypefun
11304@end quotation
11305@end iftex
11306
11307@need 800
11308The template is:
11309
11310@example
11311@group
11312@@deftypefun @var{type} @var{name} @var{arguments}@dots{}
11313@var{body-of-description}
11314@@end deftypefun
11315@end group
11316@end example
11317
11318@code{@@deftypefun} creates an entry in the index of functions for
11319@var{name}.@refill
11320
11321@end table
11322
11323
11324@node Typed Variables, Abstract Objects, Typed Functions, Def Cmds in Detail
11325@subsection Variables in Typed Languages
11326
11327Variables in typed languages are handled in a manner similar to
11328functions in typed languages. @xref{Typed Functions}. The general
11329definition command @code{@@deftypevr} corresponds to
11330@code{@@deftypefn} and the specialized definition command
11331@code{@@deftypevar} corresponds to @code{@@deftypefun}.@refill
11332
11333@table @code
11334@findex deftypevr
11335@item @@deftypevr @var{category} @var{data-type} @var{name}
11336The @code{@@deftypevr} command is the general definition command for
11337something like a variable in a typed language---an entity that records
11338a value. You must choose a term to describe the category of the
11339entity being defined; for example, ``Variable'' could be used if the
11340entity is a variable.@refill
11341
11342The @code{@@deftypevr} command is written at the beginning of a line
11343and is followed on the same line by the category of the entity
11344being described, the data type, and the name of this particular
11345entity.@refill
11346
11347@need 800
11348@noindent
11349For example:
11350
11351@example
11352@group
11353@@deftypevr @{Global Flag@} int enable
11354@dots{}
11355@@end deftypevr
11356@end group
11357@end example
11358
11359@noindent
11360produces the following in Info:
11361
11362@example
11363@group
11364-- Global Flag: int enable
11365@dots{}
11366@end group
11367@end example
11368@iftex
11369
11370@noindent
11371and the following in a printed manual:
11372
11373@quotation
11374@deftypevr {Global Flag} int enable
11375@dots{}
11376@end deftypevr
11377@end quotation
11378@end iftex
11379
11380@need 800
11381The template is:
11382
11383@example
11384@@deftypevr @var{category} @var{data-type} @var{name}
11385@var{body-of-description}
11386@@end deftypevr
11387@end example
11388
11389@code{@@deftypevr} creates an entry in the index of variables for
11390@var{name}.@refill
11391
11392@findex deftypevar
11393@item @@deftypevar @var{data-type} @var{name}
11394The @code{@@deftypevar} command is the specialized definition command
11395for variables in typed languages. @code{@@deftypevar} is equivalent
11396to @samp{@@deftypevr Variable @dots{}}.@refill
11397
11398@need 800
11399@noindent
11400For example:
11401
11402@example
11403@group
11404@@deftypevar int fubar
11405@dots{}
11406@@end deftypevar
11407@end group
11408@end example
11409
11410@noindent
11411produces the following in Info:
11412
11413@example
11414@group
11415-- Variable: int fubar
11416@dots{}
11417@end group
11418@end example
11419@iftex
11420
11421@need 800
11422@noindent
11423and the following in a printed manual:
11424
11425@quotation
11426@deftypevar int fubar
11427@dots{}
11428@end deftypevar
11429@end quotation
11430@end iftex
11431
11432@need 800
11433@noindent
11434The template is:
11435
11436@example
11437@group
11438@@deftypevar @var{data-type} @var{name}
11439@var{body-of-description}
11440@@end deftypevar
11441@end group
11442@end example
11443
11444@code{@@deftypevar} creates an entry in the index of variables for
11445@var{name}.@refill
11446@end table
11447
11448@node Abstract Objects
11449@subsection Object-Oriented Programming
11450
11451Here are the commands for formatting descriptions about abstract
11452objects, such as are used in object-oriented programming. A class is
11453a defined type of abstract object. An instance of a class is a
11454particular object that has the type of the class. An instance
11455variable is a variable that belongs to the class but for which each
11456instance has its own value.@refill
11457
11458In a definition, if the name of a class is truly a name defined in the
11459programming system for a class, then you should write an @code{@@code}
11460around it. Otherwise, it is printed in the usual text font.@refill
11461
11462@table @code
11463@findex defcv
11464@item @@defcv @var{category} @var{class} @var{name}
11465The @code{@@defcv} command is the general definition command for
11466variables associated with classes in object-oriented programming. The
11467@code{@@defcv} command is followed by three arguments: the category of
11468thing being defined, the class to which it belongs, and its
11469name. Thus,@refill
11470
11471@example
11472@group
11473@@defcv @{Class Option@} Window border-pattern
11474@dots{}
11475@@end defcv
11476@end group
11477@end example
11478
11479@noindent
11480illustrates how you would write the first line of a definition of the
11481@code{border-pattern} class option of the class @code{Window}.@refill
11482
11483The template is:
11484@example
11485@group
11486@@defcv @var{category} @var{class} @var{name}
11487@dots{}
11488@@end defcv
11489@end group
11490@end example
11491
11492@code{@@defcv} creates an entry in the index of variables.
11493
11494@findex defivar
11495@item @@defivar @var{class} @var{name}
11496The @code{@@defivar} command is the definition command for instance
11497variables in object-oriented programming. @code{@@defivar} is
11498equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}@refill
11499
11500The template is:
11501@example
11502@group
11503@@defivar @var{class} @var{instance-variable-name}
11504@var{body-of-definition}
11505@@end defivar
11506@end group
11507@end example
11508
11509@code{@@defivar} creates an entry in the index of variables.
11510
11511@findex deftypeivar
11512@item @@deftypeivar @var{class} @var{data-type} @var{name}
11513The @code{@@deftypeivar} command is the definition command for typed
11514instance variables in object-oriented programming. It is similar to
11515@code{@@defivar} with the addition of the @var{data-type} parameter to
11516specify the type of the instance variable. @code{@@deftypeivar} creates an
11517entry in the index of variables.
11518
11519@findex defop
11520@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
11521The @code{@@defop} command is the general definition command for
11522entities that may resemble methods in object-oriented programming.
11523These entities take arguments, as functions do, but are associated with
11524particular classes of objects.@refill
11525
11526For example, some systems have constructs called @dfn{wrappers} that
11527are associated with classes as methods are, but that act more like
11528macros than like functions. You could use @code{@@defop Wrapper} to
11529describe one of these.@refill
11530
11531Sometimes it is useful to distinguish methods and @dfn{operations}.
11532You can think of an operation as the specification for a method.
11533Thus, a window system might specify that all window classes have a
11534method named @code{expose}; we would say that this window system
11535defines an @code{expose} operation on windows in general. Typically,
11536the operation has a name and also specifies the pattern of arguments;
11537all methods that implement the operation must accept the same
11538arguments, since applications that use the operation do so without
11539knowing which method will implement it.@refill
11540
11541Often it makes more sense to document operations than methods. For
11542example, window application developers need to know about the
11543@code{expose} operation, but need not be concerned with whether a
11544given class of windows has its own method to implement this operation.
11545To describe this operation, you would write:@refill
11546
11547@example
11548@@defop Operation windows expose
11549@end example
11550
11551The @code{@@defop} command is written at the beginning of a line and
11552is followed on the same line by the overall name of the category of
11553operation, the name of the class of the operation, the name of the
11554operation, and its arguments, if any.@refill
11555
11556The template is:
11557@example
11558@group
11559@@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
11560@var{body-of-definition}
11561@@end defop
11562@end group
11563@end example
11564
11565@code{@@defop} creates an entry, such as `@code{expose} on
11566@code{windows}', in the index of functions.@refill
11567
11568@findex deftypeop
11569@item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
11570The @code{@@deftypeop} command is the definition command for typed
11571operations in object-oriented programming. It is similar to
11572@code{@@defop} with the addition of the @var{data-type} parameter to
11573specify the return type of the method. @code{@@deftypeop} creates an
11574entry in the index of functions.
11575
11576@item @@defmethod @var{class} @var{name} @var{arguments}@dots{}
11577@findex defmethod
11578The @code{@@defmethod} command is the definition command for methods
11579in object-oriented programming. A method is a kind of function that
11580implements an operation for a particular class of objects and its
11581subclasses.
11582@ignore
11583@c ADR: Who cares?!?
11584@c KB: Oh, I don't know, I think this info is crucial!
11585In the Lisp Machine, methods actually were functions, but
11586they were usually defined with @code{defmethod}.
11587@end ignore
11588
11589@code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}.
11590The command is written at the beginning of a line and is followed by
11591the name of the class of the method, the name of the method, and its
11592arguments, if any.@refill
11593
11594@noindent
11595For example:
11596@example
11597@group
11598@@defmethod @code{bar-class} bar-method argument
11599@dots{}
11600@@end defmethod
11601@end group
11602@end example
11603
11604@noindent
11605illustrates the definition for a method called @code{bar-method} of
11606the class @code{bar-class}. The method takes an argument.@refill
11607
11608The template is:
11609
11610@example
11611@group
11612@@defmethod @var{class} @var{method-name} @var{arguments}@dots{}
11613@var{body-of-definition}
11614@@end defmethod
11615@end group
11616@end example
11617
11618@code{@@defmethod} creates an entry, such as `@code{bar-method} on
11619@code{bar-class}', in the index of functions.@refill
11620
11621
11622@item @@deftypemethod @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
11623@findex defmethod
11624The @code{@@deftypemethod} command is the definition command for methods
11625in object-oriented typed languages, such as C++ and Java. It is similar
11626to the @code{@@defmethod} command with the addition of the
11627@var{data-type} parameter to specify the return type of the method.
11628
11629@end table
11630
11631
11632@node Data Types
11633@subsection Data Types
11634
11635Here is the command for data types:@refill
11636
11637@table @code
11638@findex deftp
11639@item @@deftp @var{category} @var{name} @var{attributes}@dots{}
11640The @code{@@deftp} command is the generic definition command for data
11641types. The command is written at the beginning of a line and is
11642followed on the same line by the category, by the name of the type
11643(which is a word like @code{int} or @code{float}), and then by names of
11644attributes of objects of that type. Thus, you could use this command
11645for describing @code{int} or @code{float}, in which case you could use
11646@code{data type} as the category. (A data type is a category of
11647certain objects for purposes of deciding which operations can be
11648performed on them.)@refill
11649
11650In Lisp, for example, @dfn{pair} names a particular data
11651type, and an object of that type has two slots called the
11652@sc{car} and the @sc{cdr}. Here is how you would write the first line
11653of a definition of @code{pair}.@refill
11654
11655@example
11656@group
11657@@deftp @{Data type@} pair car cdr
11658@dots{}
11659@@end deftp
11660@end group
11661@end example
11662
11663@need 950
11664The template is:
11665
11666@example
11667@group
11668@@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
11669@var{body-of-definition}
11670@@end deftp
11671@end group
11672@end example
11673
11674@code{@@deftp} creates an entry in the index of data types.
11675@end table
11676
11677@node Def Cmd Conventions, Sample Function Definition, Def Cmds in Detail, Definition Commands
11678@section Conventions for Writing Definitions
11679@cindex Definition conventions
11680@cindex Conventions for writing definitions
11681
11682When you write a definition using @code{@@deffn}, @code{@@defun}, or
11683one of the other definition commands, please take care to use
11684arguments that indicate the meaning, as with the @var{count} argument
11685to the @code{forward-word} function. Also, if the name of an argument
11686contains the name of a type, such as @var{integer}, take care that the
11687argument actually is of that type.@refill
11688
11689@node Sample Function Definition, , Def Cmd Conventions, Definition Commands
11690@section A Sample Function Definition
11691@cindex Function definitions
11692@cindex Command definitions
11693@cindex Macro definitions
11694@cindex Sample function definition
11695
11696A function definition uses the @code{@@defun} and @code{@@end defun}
11697commands. The name of the function follows immediately after the
11698@code{@@defun} command and it is followed, on the same line, by the
11699parameter list.@refill
11700
11701Here is a definition from @ref{Calling Functions,,, elisp, The GNU Emacs
11702Lisp Reference Manual}.
11703
11704@quotation
11705@defun apply function &rest arguments
11706@code{apply} calls @var{function} with @var{arguments}, just
11707like @code{funcall} but with one difference: the last of
11708@var{arguments} is a list of arguments to give to
11709@var{function}, rather than a single argument. We also say
11710that this list is @dfn{appended} to the other arguments.
11711
11712@code{apply} returns the result of calling @var{function}.
11713As with @code{funcall}, @var{function} must either be a Lisp
11714function or a primitive function; special forms and macros
11715do not make sense in @code{apply}.
11716
11717@example
11718(setq f 'list)
11719 @result{} list
11720(apply f 'x 'y 'z)
11721@error{} Wrong type argument: listp, z
11722(apply '+ 1 2 '(3 4))
11723 @result{} 10
11724(apply '+ '(1 2 3 4))
11725 @result{} 10
11726
11727(apply 'append '((a b c) nil (x y z) nil))
11728 @result{} (a b c x y z)
11729@end example
11730
11731An interesting example of using @code{apply} is found in the description
11732of @code{mapcar}.@refill
11733@end defun
11734@end quotation
11735
11736@need 1200
11737In the Texinfo source file, this example looks like this:
11738
11739@example
11740@group
11741@@defun apply function &rest arguments
11742@@code@{apply@} calls @@var@{function@} with
11743@@var@{arguments@}, just like @@code@{funcall@} but with one
11744difference: the last of @@var@{arguments@} is a list of
11745arguments to give to @@var@{function@}, rather than a single
11746argument. We also say that this list is @@dfn@{appended@}
11747to the other arguments.
11748@end group
11749
11750@group
11751@@code@{apply@} returns the result of calling
11752@@var@{function@}. As with @@code@{funcall@},
11753@@var@{function@} must either be a Lisp function or a
11754primitive function; special forms and macros do not make
11755sense in @@code@{apply@}.
11756@end group
11757
11758@group
11759@@example
11760(setq f 'list)
11761 @@result@{@} list
11762(apply f 'x 'y 'z)
11763@@error@{@} Wrong type argument: listp, z
11764(apply '+ 1 2 '(3 4))
11765 @@result@{@} 10
11766(apply '+ '(1 2 3 4))
11767 @@result@{@} 10
11768
11769(apply 'append '((a b c) nil (x y z) nil))
11770 @@result@{@} (a b c x y z)
11771@@end example
11772@end group
11773
11774@group
11775An interesting example of using @@code@{apply@} is found
11776in the description of @@code@{mapcar@}.
11777@@end defun
11778@end group
11779@end example
11780
11781@noindent
11782In this manual, this function is listed in the Command and Variable
11783Index under @code{apply}.@refill
11784
11785Ordinary variables and user options are described using a format like
11786that for functions except that variables do not take arguments.
11787
11788
11789@node Conditionals
11790@chapter Conditionally Visible Text
11791@cindex Conditionally visible text
11792@cindex Text, conditionally visible
11793@cindex Visibility of conditional text
11794@cindex If text conditionally visible
11795
11796Sometimes it is good to use different text for different output formats.
11797For example, you can use the @dfn{conditional commands} to specify
11798different text for the printed manual and the Info output.
11799
11800Conditional commands may not be nested.
11801
11802The conditional commands comprise the following categories.
11803
11804@itemize @bullet
11805@item Commands for HTML, Info, or @TeX{}.
11806@item Commands for not HTML, Info, or @TeX{}.
11807@item Raw @TeX{} or HTML commands.
11808@item
11809Substituting text for all formats, and testing if a flag is set or clear.
11810@end itemize
11811
11812@menu
11813* Conditional Commands:: Specifying text for HTML, Info, or @TeX{}.
11814* Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}.
11815* Raw Formatter Commands:: Using raw @TeX{} or HTML commands.
11816* set clear value:: Designating which text to format (for
11817 all output formats); and how to set a
11818 flag to a string that you can insert.
11819@end menu
11820
11821
11822@node Conditional Commands
11823@section Conditional Commands
11824
|
| 11825Texinfo has a pair of commands for each output format, to allow
11826conditional inclusion of text for a particular output format.
11827
|
11748@findex ifinfo
11749@code{@@ifinfo} begins segments of text that should be ignored by @TeX{}
11750when it typesets the printed manual. The segment of text appears only
| 11828@findex ifinfo
11829@code{@@ifinfo} begins segments of text that should be ignored by @TeX{}
11830when it typesets the printed manual. The segment of text appears only
|
11751in the Info file. The @code{@@ifinfo} command should appear on a line
11752by itself; end the Info-only text with a line containing @code{@@end
11753ifinfo} by itself. At the beginning of a Texinfo file, the Info
11754permissions are contained within a region marked by @code{@@ifinfo} and
11755@code{@@end ifinfo}. (@xref{Info Summary and Permissions}.)
| 11831in the Info file and (for historical compatibility) the plain text
11832output. The @code{@@ifinfo} command should appear on a line by itself;
11833end the Info-only text with a line containing @code{@@end ifinfo} by
11834itself.
|
11756
11757@findex iftex
11758@findex ifhtml
| 11835
11836@findex iftex
11837@findex ifhtml
|
11759The @code{@@iftex} and @code{@@end iftex} commands are similar to the
11760@code{@@ifinfo} and @code{@@end ifinfo} commands, except that they
11761specify text that will appear in the printed manual but not in the Info
11762file. Likewise for @code{@@ifhtml} and @code{@@end ifhtml}, which
11763specify text to appear only in HTML output.@refill
| 11838@findex ifplaintext
11839The @code{@@iftex} and @code{@@end iftex} commands are analogous to the
11840@code{@@ifinfo} and @code{@@end ifinfo} commands; they specify text that
11841will appear in the printed manual but not in the Info file. Likewise
11842for @code{@@ifhtml} and @code{@@end ifhtml}, which specify text to
11843appear only in HTML output. And for @code{@@ifplaintext} and
11844@code{@@end ifplaintext}, which specify text to appear only in plain
11845text output.
|
11764
11765For example,
11766
11767@example
11768@@iftex
11769This text will appear only in the printed manual.
11770@@end iftex
11771@@ifinfo
| 11846
11847For example,
11848
11849@example
11850@@iftex
11851This text will appear only in the printed manual.
11852@@end iftex
11853@@ifinfo
|
11772However, this text will appear only in Info.
| 11854However, this text will appear only in Info (or plain text).
|
11773@@end ifinfo
11774@@ifhtml
11775And this text will only appear in HTML.
11776@@end ifhtml
| 11855@@end ifinfo
11856@@ifhtml
11857And this text will only appear in HTML.
11858@@end ifhtml
|
| 11859@@ifplaintext
11860Whereas this text will only appear in plain text.
11861@@end ifplaintext
|
11777@end example
11778
11779@noindent
11780The preceding example produces the following line:
11781@iftex
11782This text will appear only in the printed manual.
11783@end iftex
11784@ifinfo
| 11862@end example
11863
11864@noindent
11865The preceding example produces the following line:
11866@iftex
11867This text will appear only in the printed manual.
11868@end iftex
11869@ifinfo
|
11785However, this text will appear only in Info.
| 11870However, this text will appear only in Info (or plain text).
|
11786@end ifinfo
11787@ifhtml
11788And this text will only appear in HTML.
11789@end ifhtml
| 11871@end ifinfo
11872@ifhtml
11873And this text will only appear in HTML.
11874@end ifhtml
|
| 11875@ifplaintext
11876Whereas this text will only appear in plain text.
11877@end ifplaintext
|
11790
11791@noindent
11792Notice that you only see one of the input lines, depending on which
11793version of the manual you are reading.
11794
11795
11796@node Conditional Not Commands
11797@section Conditional Not Commands
11798@findex ifnothtml
11799@findex ifnotinfo
| 11878
11879@noindent
11880Notice that you only see one of the input lines, depending on which
11881version of the manual you are reading.
11882
11883
11884@node Conditional Not Commands
11885@section Conditional Not Commands
11886@findex ifnothtml
11887@findex ifnotinfo
|
| 11888@findex ifnotplaintext
|
11800@findex ifnottex
11801
11802You can specify text to be included in any output format @emph{other}
11803than some given one with the @code{@@ifnot@dots{}} commands:
11804@example
11805@@ifnothtml @dots{} @@end ifnothtml
11806@@ifnotinfo @dots{} @@end ifnotinfo
| 11889@findex ifnottex
11890
11891You can specify text to be included in any output format @emph{other}
11892than some given one with the @code{@@ifnot@dots{}} commands:
11893@example
11894@@ifnothtml @dots{} @@end ifnothtml
11895@@ifnotinfo @dots{} @@end ifnotinfo
|
| 11896@@ifnotplaintext @dots{} @@end ifnotplaintext
|
11807@@ifnottex @dots{} @@end ifnottex
11808@end example
11809@noindent
11810(The @code{@@ifnot@dots{}} command and the @code{@@end} command must
| 11897@@ifnottex @dots{} @@end ifnottex
11898@end example
11899@noindent
11900(The @code{@@ifnot@dots{}} command and the @code{@@end} command must
|
11811actually appear on lines by themselves.)
| 11901appear on lines by themselves in your actual source file.)
|
11812
| 11902
|
11813If the output file is not being made for the given format, the region is
11814included. Otherwise, it is ignored.
| 11903If the output file is @emph{not} being made for the given format, the
11904region is included. Otherwise, it is ignored.
|
11815
| 11905
|
| 11906With one exception (for historical compatibility): @code{@@ifnotinfo}
11907text is omitted for both Info and plain text output, not just Info. To
11908specify text which appears only in Info and not in plain text, use
11909@code{@@ifnotplaintext}, like this:
11910@example
11911@ifinfo
11912@ifnotplaintext
11913This will be in Info, but not plain text.
11914@end ifnotplaintext
11915@end ifinfo
11916@end example
11917
|
11816The regions delimited by these commands are ordinary Texinfo source as
11817with @code{@@iftex}, not raw formatter source as with @code{@@tex}
11818(@pxref{Raw Formatter Commands}).
11819
11820
11821@node Raw Formatter Commands
11822@section Raw Formatter Commands
11823@cindex @TeX{} commands, using ordinary
11824@cindex HTML commands, using ordinary
11825@cindex Raw formatter commands
11826@cindex Ordinary @TeX{} commands, using
11827@cindex Ordinary HTML commands, using
11828@cindex Commands using raw @TeX{}
11829@cindex Commands using raw HTML
11830@cindex plain @TeX{}
11831
11832Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, you
11833can embed some raw @TeX{} commands. Info will ignore these commands
11834since they are only in that part of the file which is seen by @TeX{}.
11835You can write the @TeX{} commands as you would write them in a normal
11836@TeX{} file, except that you must replace the @samp{\} used by @TeX{}
11837with an @samp{@@}. For example, in the @code{@@titlepage} section of a
11838Texinfo file, you can use the @TeX{} command @code{@@vskip} to format
11839the copyright page. (The @code{@@titlepage} command causes Info to
11840ignore the region automatically, as it does with the @code{@@iftex}
11841command.)
11842
11843However, many features of plain @TeX{} will not work, as they are
11844overridden by Texinfo features.
11845
11846@findex tex
11847You can enter plain @TeX{} completely, and use @samp{\} in the @TeX{}
11848commands, by delineating a region with the @code{@@tex} and @code{@@end
11849tex} commands. (The @code{@@tex} command also causes Info to ignore the
11850region, like the @code{@@iftex} command.) The sole exception is that the
11851@code{@@} character still introduces a command, so that @code{@@end tex}
11852can be recognized properly.
11853
11854@cindex Mathematical expressions
11855For example, here is a mathematical expression written in
11856plain @TeX{}:
11857
11858@example
11859@@tex
11860$$ \chi^2 = \sum_@{i=1@}^N
11861 \left (y_i - (a + b x_i)
11862 \over \sigma_i\right)^2 $$
11863@@end tex
11864@end example
11865
11866@noindent
11867The output of this example will appear only in a printed manual. If
11868you are reading this in Info, you will not see the equation that appears
11869in the printed manual.
11870@iftex
11871In a printed manual, the above expression looks like
11872this:
11873@end iftex
11874
11875@tex
11876$$ \chi^2 = \sum_{i=1}^N
11877 \left(y_i - (a + b x_i)
11878 \over \sigma_i\right)^2 $$
11879@end tex
11880
11881@findex ifhtml
11882@findex html
11883Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to delimit
11884a region to be included in HTML output only, and @code{@@html @dots{}
11885@@end html} for a region of raw HTML (again, except that @code{@@} is
11886still the escape character, so the @code{@@end} command can be
11887recognized.)
11888
11889
11890@node set clear value
11891@section @code{@@set}, @code{@@clear}, and @code{@@value}
11892
11893You can direct the Texinfo formatting commands to format or ignore parts
11894of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset},
11895and @code{@@ifclear} commands.@refill
11896
11897Brief descriptions:
11898
11899@table @code
11900@item @@set @var{flag} [@var{value}]
11901Set the variable @var{flag}, to the optional @var{value} if specifed.
11902
11903@item @@clear @var{flag}
11904Undefine the variable @var{flag}, whether or not it was previously defined.
11905
11906@item @@ifset @var{flag}
11907If @var{flag} is set, text through the next @code{@@end ifset} command
11908is formatted. If @var{flag} is clear, text through the following
11909@code{@@end ifset} command is ignored.
11910
11911@item @@ifclear @var{flag}
11912If @var{flag} is set, text through the next @code{@@end ifclear} command
11913is ignored. If @var{flag} is clear, text through the following
11914@code{@@end ifclear} command is formatted.
11915@end table
11916
11917@menu
11918* set value:: Expand a flag variable to a string.
11919* ifset ifclear:: Format a region if a flag is set.
11920* value Example:: An easy way to update edition information.
11921@end menu
11922
11923
11924@node set value
11925@subsection @code{@@set} and @code{@@value}
11926@findex value
11927
11928You use the @code{@@set} command to specify a value for a flag, which is
11929later expanded by the @code{@@value} command.
11930
11931A @dfn{flag} is an identifier. In general, it is best to use only
11932letters and numerals in a flag name, not @samp{-} or @samp{_}---they
11933will work in some contexts, but not all, due to limitations in @TeX{}.
11934
11935The value is the remainder of the input line, and can contain anything.
11936
11937Write the @code{@@set} command like this:
11938
11939@example
11940@@set foo This is a string.
11941@end example
11942
11943@noindent
11944This sets the value of the flag @code{foo} to ``This is a string.''.
11945
11946The Texinfo formatters then replace an @code{@@value@{@var{flag}@}}
11947command with the string to which @var{flag} is set. Thus, when
11948@code{foo} is set as shown above, the Texinfo formatters convert this:
11949
11950@example
11951@group
11952@@value@{foo@}
11953@exdent @r{to this:}
11954This is a string.
11955@end group
11956@end example
11957
11958You can write an @code{@@value} command within a paragraph; but you
11959must write an @code{@@set} command on a line of its own.
11960
11961If you write the @code{@@set} command like this:
11962
11963@example
11964@@set foo
11965@end example
11966
11967@noindent
11968without specifying a string, the value of @code{foo} is the empty string.
11969
11970If you clear a previously set flag with @code{@@clear @var{flag}}, a
11971subsequent @code{@@value@{flag@}} command will report an error.
11972
11973For example, if you set @code{foo} as follows:@refill
11974
11975@example
11976@@set how-much very, very, very
11977@end example
11978
11979@noindent
11980then the formatters transform
11981
11982@example
11983@group
11984It is a @@value@{how-much@} wet day.
11985@exdent @r{into}
11986It is a very, very, very wet day.
11987@end group
11988@end example
11989
11990If you write
11991
11992@example
11993@@clear how-much
11994@end example
11995
11996@noindent
11997then the formatters transform
11998
11999@example
12000@group
12001It is a @@value@{how-much@} wet day.
12002@exdent @r{into}
12003It is a @{No value for "how-much"@} wet day.
12004@end group
12005@end example
12006
12007
12008@node ifset ifclear
12009@subsection @code{@@ifset} and @code{@@ifclear}
12010
12011@findex ifset
12012When a @var{flag} is set, the Texinfo formatting commands format text
12013between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end
12014ifset} commands. When the @var{flag} is cleared, the Texinfo formatting
12015commands do @emph{not} format the text. @code{@@ifclear} operates
12016analogously.
12017
12018Write the conditionally formatted text between @code{@@ifset @var{flag}}
12019and @code{@@end ifset} commands, like this:
12020
12021@example
12022@group
12023@@ifset @var{flag}
12024@var{conditional-text}
12025@@end ifset
12026@end group
12027@end example
12028
12029For example, you can create one document that has two variants, such as
12030a manual for a `large' and `small' model:
12031
12032@cindex shrubbery
12033@example
12034You can use this machine to dig up shrubs
12035without hurting them.
12036
12037@@set large
12038
12039@@ifset large
12040It can also dig up fully grown trees.
12041@@end ifset
12042
12043Remember to replant promptly @dots{}
12044@end example
12045
12046@noindent
12047In the example, the formatting commands will format the text between
12048@code{@@ifset large} and @code{@@end ifset} because the @code{large}
12049flag is set.
12050
12051When @var{flag} is cleared, the Texinfo formatting commands do
12052@emph{not} format the text between @code{@@ifset @var{flag}} and
12053@code{@@end ifset}; that text is ignored and does not appear in either
12054printed or Info output.
12055
12056For example, if you clear the flag of the preceding example by writing
12057an @code{@@clear large} command after the @code{@@set large} command
12058(but before the conditional text), then the Texinfo formatting commands
12059ignore the text between the @code{@@ifset large} and @code{@@end ifset}
12060commands. In the formatted output, that text does not appear; in both
12061printed and Info output, you see only the lines that say, ``You can use
12062this machine to dig up shrubs without hurting them. Remember to replant
12063promptly @dots{}''.
12064
12065@findex ifclear
12066If a flag is cleared with an @code{@@clear @var{flag}} command, then
12067the formatting commands format text between subsequent pairs of
12068@code{@@ifclear} and @code{@@end ifclear} commands. But if the flag
12069is set with @code{@@set @var{flag}}, then the formatting commands do
12070@emph{not} format text between an @code{@@ifclear} and an @code{@@end
12071ifclear} command; rather, they ignore that text. An @code{@@ifclear}
12072command looks like this:
12073
12074@example
12075@@ifclear @var{flag}
12076@end example
12077
12078
12079@node value Example
12080@subsection @code{@@value} Example
12081
12082You can use the @code{@@value} command to minimize the number of places
| 11918The regions delimited by these commands are ordinary Texinfo source as
11919with @code{@@iftex}, not raw formatter source as with @code{@@tex}
11920(@pxref{Raw Formatter Commands}).
11921
11922
11923@node Raw Formatter Commands
11924@section Raw Formatter Commands
11925@cindex @TeX{} commands, using ordinary
11926@cindex HTML commands, using ordinary
11927@cindex Raw formatter commands
11928@cindex Ordinary @TeX{} commands, using
11929@cindex Ordinary HTML commands, using
11930@cindex Commands using raw @TeX{}
11931@cindex Commands using raw HTML
11932@cindex plain @TeX{}
11933
11934Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, you
11935can embed some raw @TeX{} commands. Info will ignore these commands
11936since they are only in that part of the file which is seen by @TeX{}.
11937You can write the @TeX{} commands as you would write them in a normal
11938@TeX{} file, except that you must replace the @samp{\} used by @TeX{}
11939with an @samp{@@}. For example, in the @code{@@titlepage} section of a
11940Texinfo file, you can use the @TeX{} command @code{@@vskip} to format
11941the copyright page. (The @code{@@titlepage} command causes Info to
11942ignore the region automatically, as it does with the @code{@@iftex}
11943command.)
11944
11945However, many features of plain @TeX{} will not work, as they are
11946overridden by Texinfo features.
11947
11948@findex tex
11949You can enter plain @TeX{} completely, and use @samp{\} in the @TeX{}
11950commands, by delineating a region with the @code{@@tex} and @code{@@end
11951tex} commands. (The @code{@@tex} command also causes Info to ignore the
11952region, like the @code{@@iftex} command.) The sole exception is that the
11953@code{@@} character still introduces a command, so that @code{@@end tex}
11954can be recognized properly.
11955
11956@cindex Mathematical expressions
11957For example, here is a mathematical expression written in
11958plain @TeX{}:
11959
11960@example
11961@@tex
11962$$ \chi^2 = \sum_@{i=1@}^N
11963 \left (y_i - (a + b x_i)
11964 \over \sigma_i\right)^2 $$
11965@@end tex
11966@end example
11967
11968@noindent
11969The output of this example will appear only in a printed manual. If
11970you are reading this in Info, you will not see the equation that appears
11971in the printed manual.
11972@iftex
11973In a printed manual, the above expression looks like
11974this:
11975@end iftex
11976
11977@tex
11978$$ \chi^2 = \sum_{i=1}^N
11979 \left(y_i - (a + b x_i)
11980 \over \sigma_i\right)^2 $$
11981@end tex
11982
11983@findex ifhtml
11984@findex html
11985Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to delimit
11986a region to be included in HTML output only, and @code{@@html @dots{}
11987@@end html} for a region of raw HTML (again, except that @code{@@} is
11988still the escape character, so the @code{@@end} command can be
11989recognized.)
11990
11991
11992@node set clear value
11993@section @code{@@set}, @code{@@clear}, and @code{@@value}
11994
11995You can direct the Texinfo formatting commands to format or ignore parts
11996of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset},
11997and @code{@@ifclear} commands.@refill
11998
11999Brief descriptions:
12000
12001@table @code
12002@item @@set @var{flag} [@var{value}]
12003Set the variable @var{flag}, to the optional @var{value} if specifed.
12004
12005@item @@clear @var{flag}
12006Undefine the variable @var{flag}, whether or not it was previously defined.
12007
12008@item @@ifset @var{flag}
12009If @var{flag} is set, text through the next @code{@@end ifset} command
12010is formatted. If @var{flag} is clear, text through the following
12011@code{@@end ifset} command is ignored.
12012
12013@item @@ifclear @var{flag}
12014If @var{flag} is set, text through the next @code{@@end ifclear} command
12015is ignored. If @var{flag} is clear, text through the following
12016@code{@@end ifclear} command is formatted.
12017@end table
12018
12019@menu
12020* set value:: Expand a flag variable to a string.
12021* ifset ifclear:: Format a region if a flag is set.
12022* value Example:: An easy way to update edition information.
12023@end menu
12024
12025
12026@node set value
12027@subsection @code{@@set} and @code{@@value}
12028@findex value
12029
12030You use the @code{@@set} command to specify a value for a flag, which is
12031later expanded by the @code{@@value} command.
12032
12033A @dfn{flag} is an identifier. In general, it is best to use only
12034letters and numerals in a flag name, not @samp{-} or @samp{_}---they
12035will work in some contexts, but not all, due to limitations in @TeX{}.
12036
12037The value is the remainder of the input line, and can contain anything.
12038
12039Write the @code{@@set} command like this:
12040
12041@example
12042@@set foo This is a string.
12043@end example
12044
12045@noindent
12046This sets the value of the flag @code{foo} to ``This is a string.''.
12047
12048The Texinfo formatters then replace an @code{@@value@{@var{flag}@}}
12049command with the string to which @var{flag} is set. Thus, when
12050@code{foo} is set as shown above, the Texinfo formatters convert this:
12051
12052@example
12053@group
12054@@value@{foo@}
12055@exdent @r{to this:}
12056This is a string.
12057@end group
12058@end example
12059
12060You can write an @code{@@value} command within a paragraph; but you
12061must write an @code{@@set} command on a line of its own.
12062
12063If you write the @code{@@set} command like this:
12064
12065@example
12066@@set foo
12067@end example
12068
12069@noindent
12070without specifying a string, the value of @code{foo} is the empty string.
12071
12072If you clear a previously set flag with @code{@@clear @var{flag}}, a
12073subsequent @code{@@value@{flag@}} command will report an error.
12074
12075For example, if you set @code{foo} as follows:@refill
12076
12077@example
12078@@set how-much very, very, very
12079@end example
12080
12081@noindent
12082then the formatters transform
12083
12084@example
12085@group
12086It is a @@value@{how-much@} wet day.
12087@exdent @r{into}
12088It is a very, very, very wet day.
12089@end group
12090@end example
12091
12092If you write
12093
12094@example
12095@@clear how-much
12096@end example
12097
12098@noindent
12099then the formatters transform
12100
12101@example
12102@group
12103It is a @@value@{how-much@} wet day.
12104@exdent @r{into}
12105It is a @{No value for "how-much"@} wet day.
12106@end group
12107@end example
12108
12109
12110@node ifset ifclear
12111@subsection @code{@@ifset} and @code{@@ifclear}
12112
12113@findex ifset
12114When a @var{flag} is set, the Texinfo formatting commands format text
12115between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end
12116ifset} commands. When the @var{flag} is cleared, the Texinfo formatting
12117commands do @emph{not} format the text. @code{@@ifclear} operates
12118analogously.
12119
12120Write the conditionally formatted text between @code{@@ifset @var{flag}}
12121and @code{@@end ifset} commands, like this:
12122
12123@example
12124@group
12125@@ifset @var{flag}
12126@var{conditional-text}
12127@@end ifset
12128@end group
12129@end example
12130
12131For example, you can create one document that has two variants, such as
12132a manual for a `large' and `small' model:
12133
12134@cindex shrubbery
12135@example
12136You can use this machine to dig up shrubs
12137without hurting them.
12138
12139@@set large
12140
12141@@ifset large
12142It can also dig up fully grown trees.
12143@@end ifset
12144
12145Remember to replant promptly @dots{}
12146@end example
12147
12148@noindent
12149In the example, the formatting commands will format the text between
12150@code{@@ifset large} and @code{@@end ifset} because the @code{large}
12151flag is set.
12152
12153When @var{flag} is cleared, the Texinfo formatting commands do
12154@emph{not} format the text between @code{@@ifset @var{flag}} and
12155@code{@@end ifset}; that text is ignored and does not appear in either
12156printed or Info output.
12157
12158For example, if you clear the flag of the preceding example by writing
12159an @code{@@clear large} command after the @code{@@set large} command
12160(but before the conditional text), then the Texinfo formatting commands
12161ignore the text between the @code{@@ifset large} and @code{@@end ifset}
12162commands. In the formatted output, that text does not appear; in both
12163printed and Info output, you see only the lines that say, ``You can use
12164this machine to dig up shrubs without hurting them. Remember to replant
12165promptly @dots{}''.
12166
12167@findex ifclear
12168If a flag is cleared with an @code{@@clear @var{flag}} command, then
12169the formatting commands format text between subsequent pairs of
12170@code{@@ifclear} and @code{@@end ifclear} commands. But if the flag
12171is set with @code{@@set @var{flag}}, then the formatting commands do
12172@emph{not} format text between an @code{@@ifclear} and an @code{@@end
12173ifclear} command; rather, they ignore that text. An @code{@@ifclear}
12174command looks like this:
12175
12176@example
12177@@ifclear @var{flag}
12178@end example
12179
12180
12181@node value Example
12182@subsection @code{@@value} Example
12183
12184You can use the @code{@@value} command to minimize the number of places
|
12083you need to change when you record an update to a manual. Here is how
12084it is done in @cite{The GNU Make Manual}:
| 12185you need to change when you record an update to a manual. @xref{GNU
12186Sample Texts}, for an example of this same principle can work with
12187Automake distributions, and full texts.
|
12085
| 12188
|
| 12189Here is an example adapted from @ref{Top,, Overview, make, The GNU Make
12190Manual}):
12191
|
12086@enumerate
12087@item
12088Set the flags:
12089
12090@example
12091@group
12092@@set EDITION 0.35 Beta
12093@@set VERSION 3.63 Beta
12094@@set UPDATED 14 August 1992
12095@@set UPDATE-MONTH August 1992
12096@end group
12097@end example
12098
12099@item
| 12192@enumerate
12193@item
12194Set the flags:
12195
12196@example
12197@group
12198@@set EDITION 0.35 Beta
12199@@set VERSION 3.63 Beta
12200@@set UPDATED 14 August 1992
12201@@set UPDATE-MONTH August 1992
12202@end group
12203@end example
12204
12205@item
|
12100Write text for the first @code{@@ifinfo} section, for people reading the
12101Texinfo file:
| 12206Write text for the @code{@@copying} section (@pxref{copying}):
|
12102
12103@example
12104@group
| 12207
12208@example
12209@group
|
| 12210@@copying
|
12105This is Edition @@value@{EDITION@},
12106last updated @@value@{UPDATED@},
12107of @@cite@{The GNU Make Manual@},
12108for @@code@{make@}, version @@value@{VERSION@}.
| 12211This is Edition @@value@{EDITION@},
12212last updated @@value@{UPDATED@},
12213of @@cite@{The GNU Make Manual@},
12214for @@code@{make@}, version @@value@{VERSION@}.
|
| 12215
12216Copyright @dots{}
12217
12218Permission is granted @dots{}
12219@@end copying
|
12109@end group
12110@end example
12111
12112@item
12113Write text for the title page, for people reading the printed manual:
| 12220@end group
12221@end example
12222
12223@item
12224Write text for the title page, for people reading the printed manual:
|
12114@c List only the month and the year since that looks less fussy on a
12115@c printed cover than a date that lists the day as well.
| |
12116
12117@example
12118@group
| 12225
12226@example
12227@group
|
| 12228@@titlepage
|
12119@@title GNU Make
12120@@subtitle A Program for Directing Recompilation
12121@@subtitle Edition @@value@{EDITION@}, @dots{}
12122@@subtitle @@value@{UPDATE-MONTH@}
| 12229@@title GNU Make
12230@@subtitle A Program for Directing Recompilation
12231@@subtitle Edition @@value@{EDITION@}, @dots{}
12232@@subtitle @@value@{UPDATE-MONTH@}
|
| 12233@@page
12234@@insertcopying
12235@dots{}
12236@@end titlepage
|
12123@end group
12124@end example
12125
12126@noindent
12127(On a printed cover, a date listing the month and the year looks less
12128fussy than a date listing the day as well as the month and year.)
12129
12130@item
12131Write text for the Top node, for people reading the Info file:
12132
12133@example
12134@group
| 12237@end group
12238@end example
12239
12240@noindent
12241(On a printed cover, a date listing the month and the year looks less
12242fussy than a date listing the day as well as the month and year.)
12243
12244@item
12245Write text for the Top node, for people reading the Info file:
12246
12247@example
12248@group
|
12135This is Edition @@value@{EDITION@}
12136of the @@cite@{GNU Make Manual@},
12137last updated @@value@{UPDATED@}
12138for @@code@{make@} Version @@value@{VERSION@}.
| 12249@@ifnottex
12250@@node Top
12251@@top Make
12252
12253@@insertcopying
12254@dots{}
12255@@end ifnottex
|
12139@end group
12140@end example
12141
| 12256@end group
12257@end example
12258
|
12142After you format the manual, the text in the first @code{@@ifinfo}
12143section looks like this:
| 12259After you format the manual, the @code{@@value} constructs have been
12260expanded, so the output contains text like this:
|
12144
12145@example
12146@group
12147This is Edition 0.35 Beta, last updated 14 August 1992,
12148of `The GNU Make Manual', for `make', Version 3.63 Beta.
12149@end group
12150@end example
12151@end enumerate
12152
| 12261
12262@example
12263@group
12264This is Edition 0.35 Beta, last updated 14 August 1992,
12265of `The GNU Make Manual', for `make', Version 3.63 Beta.
12266@end group
12267@end example
12268@end enumerate
12269
|
12153When you update the manual, change only the values of the flags; you do
12154not need to edit the three sections.
| 12270When you update the manual, you change only the values of the flags; you
12271do not need to edit the three sections.
|
12155
12156
12157@node Internationalization
12158@chapter Internationalization
12159
12160@cindex Internationalization
12161Texinfo has some support for writing in languages other than English,
12162although this area still needs considerable work.
12163
12164For a list of the various accented and special characters Texinfo
12165supports, see @ref{Inserting Accents}.
12166
12167@menu
12168* documentlanguage:: Declaring the current language.
12169* documentencoding:: Declaring the input encoding.
12170@end menu
12171
12172
12173@node documentlanguage
12174@section @code{@@documentlanguage @var{cc}}: Set the Document Language
12175
12176@findex documentlanguage
12177@cindex Language, declaring
12178@cindex Document language, declaring
12179
12180The @code{@@documentlanguage} command declares the current document
12181language. Write it on a line by itself, with a two-letter ISO-639
12182language code following (list is included below). If you have a
12183multilingual document, the intent is to be able to use this command
12184multiple times, to declare each language change. If the command is not
12185used at all, the default is @code{en} for English.
12186
12187@cindex @file{txi-@var{cc}.tex}
12188At present, this command is ignored in Info and HTML output. For
12189@TeX{}, it causes the file @file{txi-@var{cc}.tex} to be read (if it
12190exists). Such a file appropriately redefines the various English words
12191used in @TeX{} output, such as `Chapter', `See', and so on.
12192
12193@cindex Hyphenation patterns, language-dependent
12194It would be good if this command also changed @TeX{}'s ideas of the
12195current hyphenation patterns (via the @TeX{} primitive
12196@code{\language}), but this is unfortunately not currently implemented.
12197
12198@cindex ISO 639 codes
12199@cindex Language codes
12200Hereare the valid language codes, from ISO-639.
12201
12202@multitable @columnfractions .07 .26 .07 .26 .07 .26
12203@item
12204@code{aa} @tab Afar @tab
12205@code{ab} @tab Abkhazian @tab
12206@code{af} @tab Afrikaans
12207@item
12208@code{am} @tab Amharic @tab
12209@code{ar} @tab Arabic @tab
12210@code{as} @tab Assamese
12211@item
12212@code{ay} @tab Aymara @tab
12213@code{az} @tab Azerbaijani @tab
12214@code{ba} @tab Bashkir
12215@item
12216@code{be} @tab Byelorussian @tab
12217@code{bg} @tab Bulgarian @tab
12218@code{bh} @tab Bihari
12219@item
12220@code{bi} @tab Bislama @tab
12221@code{bn} @tab Bengali; Bangla @tab
12222@code{bo} @tab Tibetan
12223@item
12224@code{br} @tab Breton @tab
12225@code{ca} @tab Catalan @tab
12226@code{co} @tab Corsican
12227@item
12228@code{cs} @tab Czech @tab
12229@code{cy} @tab Welsh @tab
12230@code{da} @tab Danish
12231@item
12232@code{de} @tab German @tab
12233@code{dz} @tab Bhutani @tab
12234@code{el} @tab Greek
12235@item
12236@code{en} @tab English @tab
12237@code{eo} @tab Esperanto @tab
12238@code{es} @tab Spanish
12239@item
12240@code{et} @tab Estonian @tab
12241@code{eu} @tab Basque @tab
12242@code{fa} @tab Persian
12243@item
12244@code{fi} @tab Finnish @tab
12245@code{fj} @tab Fiji @tab
12246@code{fo} @tab Faroese
12247@item
12248@code{fr} @tab French @tab
12249@code{fy} @tab Frisian @tab
12250@code{ga} @tab Irish
12251@item
12252@code{gd} @tab Scots Gaelic @tab
12253@code{gl} @tab Galician @tab
12254@code{gn} @tab Guarani
12255@item
12256@code{gu} @tab Gujarati @tab
12257@code{ha} @tab Hausa @tab
12258@code{he} @tab Hebrew
12259@item
12260@code{hi} @tab Hindi @tab
12261@code{hr} @tab Croatian @tab
12262@code{hu} @tab Hungarian
12263@item
12264@code{hy} @tab Armenian @tab
12265@code{ia} @tab Interlingua @tab
12266@code{id} @tab Indonesian
12267@item
12268@code{ie} @tab Interlingue @tab
12269@code{ik} @tab Inupiak @tab
12270@code{is} @tab Icelandic
12271@item
12272@code{it} @tab Italian @tab
12273@code{iu} @tab Inuktitut @tab
12274@code{ja} @tab Japanese
12275@item
12276@code{jw} @tab Javanese @tab
12277@code{ka} @tab Georgian @tab
12278@code{kk} @tab Kazakh
12279@item
12280@code{kl} @tab Greenlandic @tab
12281@code{km} @tab Cambodian @tab
12282@code{kn} @tab Kannada
12283@item
12284@code{ks} @tab Kashmiri @tab
12285@code{ko} @tab Korean @tab
12286@code{ku} @tab Kurdish
12287@item
12288@code{ky} @tab Kirghiz @tab
12289@code{la} @tab Latin @tab
12290@code{ln} @tab Lingala
12291@item
12292@code{lt} @tab Lithuanian @tab
12293@code{lo} @tab Laothian @tab
12294@code{lv} @tab Latvian, Lettish
12295@item
12296@code{mg} @tab Malagasy @tab
12297@code{mi} @tab Maori @tab
12298@code{mk} @tab Macedonian
12299@item
12300@code{ml} @tab Malayalam @tab
12301@code{mn} @tab Mongolian @tab
12302@code{mo} @tab Moldavian
12303@item
12304@code{mr} @tab Marathi @tab
12305@code{ms} @tab Malay @tab
12306@code{mt} @tab Maltese
12307@item
12308@code{my} @tab Burmese @tab
12309@code{na} @tab Nauru @tab
12310@code{ne} @tab Nepali
12311@item
12312@code{nl} @tab Dutch @tab
12313@code{no} @tab Norwegian @tab
12314@code{oc} @tab Occitan
12315@item
12316@code{om} @tab (Afan) Oromo @tab
12317@code{or} @tab Oriya @tab
12318@code{pa} @tab Punjabi
12319@item
12320@code{pl} @tab Polish @tab
12321@code{ps} @tab Pashto, Pushto @tab
12322@code{pt} @tab Portuguese
12323@item
12324@code{qu} @tab Quechua @tab
12325@code{rm} @tab Rhaeto-Romance @tab
12326@code{rn} @tab Kirundi
12327@item
12328@code{ro} @tab Romanian @tab
12329@code{ru} @tab Russian @tab
12330@code{rw} @tab Kinyarwanda
12331@item
12332@code{sa} @tab Sanskrit @tab
12333@code{sd} @tab Sindhi @tab
12334@code{sg} @tab Sangro
12335@item
12336@code{sh} @tab Serbo-Croatian @tab
12337@code{si} @tab Sinhalese @tab
12338@code{sk} @tab Slovak
12339@item
12340@code{sl} @tab Slovenian @tab
12341@code{sm} @tab Samoan @tab
12342@code{sn} @tab Shona
12343@item
12344@code{so} @tab Somali @tab
12345@code{sq} @tab Albanian @tab
12346@code{sr} @tab Serbian
12347@item
12348@code{ss} @tab Siswati @tab
12349@code{st} @tab Sesotho @tab
12350@code{su} @tab Sundanese
12351@item
12352@code{sv} @tab Swedish @tab
12353@code{sw} @tab Swahili @tab
12354@code{ta} @tab Tamil
12355@item
12356@code{te} @tab Telugu @tab
12357@code{tg} @tab Tajik @tab
12358@code{th} @tab Thai
12359@item
12360@code{ti} @tab Tigrinya @tab
12361@code{tk} @tab Turkmen @tab
12362@code{tl} @tab Tagalog
12363@item
12364@code{tn} @tab Setswana @tab
12365@code{to} @tab Tonga @tab
12366@code{tr} @tab Turkish
12367@item
12368@code{ts} @tab Tsonga @tab
12369@code{tt} @tab Tatar @tab
12370@code{tw} @tab Twi
12371@item
12372@code{ug} @tab Uighur @tab
12373@code{uk} @tab Ukrainian @tab
12374@code{ur} @tab Urdu
12375@item
12376@code{uz} @tab Uzbek @tab
12377@code{vi} @tab Vietnamese @tab
12378@code{vo} @tab Volapuk
12379@item
12380@code{wo} @tab Wolof @tab
12381@code{xh} @tab Xhosa @tab
12382@code{yi} @tab Yiddish
12383@item
12384@code{yo} @tab Yoruba @tab
12385@code{za} @tab Zhuang @tab
12386@code{zh} @tab Chinese
12387@item
12388@code{zu} @tab Zulu
12389@end multitable
12390
12391
12392@node documentencoding
12393@section @code{@@documentencoding @var{enc}}: Set Input Encoding
12394
12395@findex documentencoding
12396@cindex Encoding, declaring
12397@cindex Input encoding, declaring
12398@cindex Document input encoding
12399
12400The @code{@@documentencoding} command declares the input document
12401encoding. Write it on a line by itself, with a valid encoding
12402specification following, such as @samp{ISO-8859-1}.
12403
12404@cindex http-equiv, and charset
12405@cindex meta HTML tag, and charset
12406At present, this is used only in HTML output from @code{makeinfo}. If a
12407document encoding @var{enc} is specified, it is used in a
12408@samp{<meta>} tag included in the @samp{<head>} of the output:
12409
12410@example
12411<meta http-equiv="Content-Type" content="text/html;
12412 charset=@var{enc}">
12413@end example
12414
12415
12416@node Defining New Texinfo Commands
12417@chapter Defining New Texinfo Commands
12418@cindex Macros
12419@cindex Defining new Texinfo commands
12420@cindex New Texinfo commands, defining
12421@cindex Texinfo commands, defining new
12422@cindex User-defined Texinfo commands
12423
12424Texinfo provides several ways to define new commands:
12425
12426@itemize @bullet
12427@item
12428A Texinfo @dfn{macro} allows you to define a new Texinfo command as any
12429sequence of text and/or existing commands (including other macros). The
12430macro can have any number of @dfn{parameters}---text you supply each
12431time you use the macro.
12432
12433Incidentally, these macros have nothing to do with the @code{@@defmac}
12434command, which is for documenting macros in the subject of the manual
12435(@pxref{Def Cmd Template}).
12436
12437@item
12438@samp{@@alias} is a convenient way to define a new name for an existing
12439command.
12440
12441@item
12442@samp{@@definfoenclose} allows you to define new commands with
12443customized output in the Info file.
12444
12445@end itemize
12446
12447@menu
12448* Defining Macros:: Defining and undefining new commands.
12449* Invoking Macros:: Using a macro, once you've defined it.
12450* Macro Details:: Beyond basic macro usage.
12451* alias:: Command aliases.
12452* definfoenclose:: Customized highlighting.
12453@end menu
12454
12455
12456@node Defining Macros
12457@section Defining Macros
12458@cindex Defining macros
12459@cindex Macro definitions
12460
12461@findex macro
12462You use the Texinfo @code{@@macro} command to define a macro, like this:
12463
12464@example
12465@@macro @var{macroname}@{@var{param1}, @var{param2}, @dots{}@}
12466@var{text} @dots{} \@var{param1}\ @dots{}
12467@@end macro
12468@end example
12469
12470The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to
12471arguments supplied when the macro is subsequently used in the document
12472(described in the next section).
12473
12474For a macro to work with @TeX{}, @var{macroname} must consist entirely
12475of letters: no digits, hyphens, underscores, or other special characters.
12476
12477If a macro needs no parameters, you can define it either with an empty
12478list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro
12479foo}).
12480
12481@cindex Body of a macro
12482@cindex Mutually recursive macros
12483@cindex Recursion, mutual
12484The definition or @dfn{body} of the macro can contain most Texinfo
12485commands, including previously-defined macros. Not-yet-defined macro
12486invocations are not allowed; thus, it is not possible to have mutually
12487recursive Texinfo macros. Also, a macro definition that defines another
12488macro does not work in @TeX{} due to limitations in the design of
12489@code{@@macro}.
12490
12491@cindex Parameters to macros
12492In the macro body, instances of a parameter name surrounded by
12493backslashes, as in @samp{\@var{param1}\} in the example above, are
12494replaced by the corresponding argument from the macro invocation. You
12495can use parameter names any number of times in the body, including zero.
12496
12497@cindex Backslash in macros
12498To get a single @samp{\} in the macro expansion, use @samp{\\}. Any
12499other use of @samp{\} in the body yields a warning.
12500
12501@cindex Spaces in macros
12502@cindex Whitespace in macros
12503The newlines after the @code{@@macro} line and before the @code{@@end
12504macro} line are ignored, that is, not included in the macro body. All
12505other whitespace is treated according to the usual Texinfo rules.
12506
12507@cindex Recursive macro invocations
12508@findex rmacro
12509To allow a macro to be used recursively, that is, in an argument to a
12510call to itself, you must define it with @samp{@@rmacro}, like this:
12511
12512@example
12513@@rmacro rmac @{arg@}
12514a\arg\b
12515@@end rmacro
12516@dots{}
12517@@rmac@{1@@rmac@{text@}2@}
12518@end example
12519
12520This produces the output `a1atextb2b'. With @samp{@@macro} instead of
12521@samp{@@rmacro}, an error message is given.
12522
12523@findex unmacro
12524@cindex Macros, undefining
12525@cindex Undefining macros
12526You can undefine a macro @var{foo} with @code{@@unmacro @var{foo}}.
12527It is not an error to undefine a macro that is already undefined.
12528For example:
12529
12530@example
12531@@unmacro foo
12532@end example
12533
12534
12535@node Invoking Macros
12536@section Invoking Macros
12537@cindex Invoking macros
12538@cindex Expanding macros
12539@cindex Running macros
12540@cindex Macro invocation
12541
12542After a macro is defined (see the previous section), you can use
12543(@dfn{invoke}) it in your document like this:
12544
12545@example
12546@@@var{macroname} @{@var{arg1}, @var{arg2}, @dots{}@}
12547@end example
12548
12549@noindent and the result will be just as if you typed the body of
12550@var{macroname} at that spot. For example:
12551
12552@example
12553@@macro foo @{p, q@}
12554Together: \p\ & \q\.
12555@@end macro
12556@@foo@{a, b@}
12557@end example
12558
12559@noindent produces:
12560
12561@display
12562Together: a & b.
12563@end display
12564
12565@cindex Backslash, and macros
12566Thus, the arguments and parameters are separated by commas and delimited
12567by braces; any whitespace after (but not before) a comma is ignored.
12568The braces are required in the invocation (but not the definition), even
12569when the macro takes no arguments, consistent with all other Texinfo
12570commands. For example:
12571
12572@example
12573@@macro argless @{@}
12574No arguments here.
12575@@end macro
12576@@argless@{@}
12577@end example
12578
12579@noindent produces:
12580
12581@display
12582No arguments here.
12583@end display
12584
12585@cindex Comma, in macro arguments
12586@cindex Braces, in macro arguments
12587To insert a comma, brace, or backslash in an argument, prepend a
12588backslash, as in
12589
12590@example
12591@@@var{macname} @{\\\@{\@}\,@}
12592@end example
12593
12594@noindent
12595which will pass the (almost certainly error-producing) argument
12596@samp{\@{@},} to @var{macname}. However, commas in parameters, even
12597if escaped by a backslash, might cause trouble in @TeX{}.
12598
12599If the macro is defined to take a single argument, and is invoked
12600without any braces, the entire rest of the line after the macro name is
12601supplied as the argument. For example:
12602
12603@example
12604@@macro bar @{p@}
12605Twice: \p\ & \p\.
12606@@end macro
12607@@bar aah
12608@end example
12609
12610@noindent produces:
12611
12612@c Sorry for cheating, but let's not require macros to process the manual.
12613@display
12614Twice: aah & aah.
12615@end display
12616
12617If the macro is defined to take a single argument, and is invoked with
12618braces, the braced text is passed as the argument, regardless of
12619commas. For example:
12620
12621@example
12622@@macro bar @{p@}
12623Twice: \p\ & \p\.
12624@@end macro
12625@@bar@{a,b@}
12626@end example
12627
12628@noindent produces:
12629
12630@display
12631Twice: a,b & a,b.
12632@end display
12633
12634
12635@node Macro Details
12636@section Macro Details
12637@cindex Macro details
12638@cindex Details of macro usage
12639
12640Due to unavoidable disparities in the @TeX{} and @command{makeinfo}
12641implementations, Texinfo macros have the following limitations.
12642
12643@itemize @bullet
12644@item
12645All macros are expanded inside at least one @TeX{} group. This means
12646that @code{@@set} and other such commands will have no effect inside a
12647macro.
12648
12649@item
12650Macros containing a command which must be on a line by itself, such as a
12651conditional, cannot be invoked in the middle of a line.
12652
12653@item
12654Commas in macro arguments, even if escaped by a backslash, don't
12655always work.
12656
12657@item
12658The @TeX{} implementation cannot construct macros that define macros in
12659the natural way. To do this, you must use conditionals and raw @TeX{}.
12660For example:
12661
12662@example
| 12272
12273
12274@node Internationalization
12275@chapter Internationalization
12276
12277@cindex Internationalization
12278Texinfo has some support for writing in languages other than English,
12279although this area still needs considerable work.
12280
12281For a list of the various accented and special characters Texinfo
12282supports, see @ref{Inserting Accents}.
12283
12284@menu
12285* documentlanguage:: Declaring the current language.
12286* documentencoding:: Declaring the input encoding.
12287@end menu
12288
12289
12290@node documentlanguage
12291@section @code{@@documentlanguage @var{cc}}: Set the Document Language
12292
12293@findex documentlanguage
12294@cindex Language, declaring
12295@cindex Document language, declaring
12296
12297The @code{@@documentlanguage} command declares the current document
12298language. Write it on a line by itself, with a two-letter ISO-639
12299language code following (list is included below). If you have a
12300multilingual document, the intent is to be able to use this command
12301multiple times, to declare each language change. If the command is not
12302used at all, the default is @code{en} for English.
12303
12304@cindex @file{txi-@var{cc}.tex}
12305At present, this command is ignored in Info and HTML output. For
12306@TeX{}, it causes the file @file{txi-@var{cc}.tex} to be read (if it
12307exists). Such a file appropriately redefines the various English words
12308used in @TeX{} output, such as `Chapter', `See', and so on.
12309
12310@cindex Hyphenation patterns, language-dependent
12311It would be good if this command also changed @TeX{}'s ideas of the
12312current hyphenation patterns (via the @TeX{} primitive
12313@code{\language}), but this is unfortunately not currently implemented.
12314
12315@cindex ISO 639 codes
12316@cindex Language codes
12317Hereare the valid language codes, from ISO-639.
12318
12319@multitable @columnfractions .07 .26 .07 .26 .07 .26
12320@item
12321@code{aa} @tab Afar @tab
12322@code{ab} @tab Abkhazian @tab
12323@code{af} @tab Afrikaans
12324@item
12325@code{am} @tab Amharic @tab
12326@code{ar} @tab Arabic @tab
12327@code{as} @tab Assamese
12328@item
12329@code{ay} @tab Aymara @tab
12330@code{az} @tab Azerbaijani @tab
12331@code{ba} @tab Bashkir
12332@item
12333@code{be} @tab Byelorussian @tab
12334@code{bg} @tab Bulgarian @tab
12335@code{bh} @tab Bihari
12336@item
12337@code{bi} @tab Bislama @tab
12338@code{bn} @tab Bengali; Bangla @tab
12339@code{bo} @tab Tibetan
12340@item
12341@code{br} @tab Breton @tab
12342@code{ca} @tab Catalan @tab
12343@code{co} @tab Corsican
12344@item
12345@code{cs} @tab Czech @tab
12346@code{cy} @tab Welsh @tab
12347@code{da} @tab Danish
12348@item
12349@code{de} @tab German @tab
12350@code{dz} @tab Bhutani @tab
12351@code{el} @tab Greek
12352@item
12353@code{en} @tab English @tab
12354@code{eo} @tab Esperanto @tab
12355@code{es} @tab Spanish
12356@item
12357@code{et} @tab Estonian @tab
12358@code{eu} @tab Basque @tab
12359@code{fa} @tab Persian
12360@item
12361@code{fi} @tab Finnish @tab
12362@code{fj} @tab Fiji @tab
12363@code{fo} @tab Faroese
12364@item
12365@code{fr} @tab French @tab
12366@code{fy} @tab Frisian @tab
12367@code{ga} @tab Irish
12368@item
12369@code{gd} @tab Scots Gaelic @tab
12370@code{gl} @tab Galician @tab
12371@code{gn} @tab Guarani
12372@item
12373@code{gu} @tab Gujarati @tab
12374@code{ha} @tab Hausa @tab
12375@code{he} @tab Hebrew
12376@item
12377@code{hi} @tab Hindi @tab
12378@code{hr} @tab Croatian @tab
12379@code{hu} @tab Hungarian
12380@item
12381@code{hy} @tab Armenian @tab
12382@code{ia} @tab Interlingua @tab
12383@code{id} @tab Indonesian
12384@item
12385@code{ie} @tab Interlingue @tab
12386@code{ik} @tab Inupiak @tab
12387@code{is} @tab Icelandic
12388@item
12389@code{it} @tab Italian @tab
12390@code{iu} @tab Inuktitut @tab
12391@code{ja} @tab Japanese
12392@item
12393@code{jw} @tab Javanese @tab
12394@code{ka} @tab Georgian @tab
12395@code{kk} @tab Kazakh
12396@item
12397@code{kl} @tab Greenlandic @tab
12398@code{km} @tab Cambodian @tab
12399@code{kn} @tab Kannada
12400@item
12401@code{ks} @tab Kashmiri @tab
12402@code{ko} @tab Korean @tab
12403@code{ku} @tab Kurdish
12404@item
12405@code{ky} @tab Kirghiz @tab
12406@code{la} @tab Latin @tab
12407@code{ln} @tab Lingala
12408@item
12409@code{lt} @tab Lithuanian @tab
12410@code{lo} @tab Laothian @tab
12411@code{lv} @tab Latvian, Lettish
12412@item
12413@code{mg} @tab Malagasy @tab
12414@code{mi} @tab Maori @tab
12415@code{mk} @tab Macedonian
12416@item
12417@code{ml} @tab Malayalam @tab
12418@code{mn} @tab Mongolian @tab
12419@code{mo} @tab Moldavian
12420@item
12421@code{mr} @tab Marathi @tab
12422@code{ms} @tab Malay @tab
12423@code{mt} @tab Maltese
12424@item
12425@code{my} @tab Burmese @tab
12426@code{na} @tab Nauru @tab
12427@code{ne} @tab Nepali
12428@item
12429@code{nl} @tab Dutch @tab
12430@code{no} @tab Norwegian @tab
12431@code{oc} @tab Occitan
12432@item
12433@code{om} @tab (Afan) Oromo @tab
12434@code{or} @tab Oriya @tab
12435@code{pa} @tab Punjabi
12436@item
12437@code{pl} @tab Polish @tab
12438@code{ps} @tab Pashto, Pushto @tab
12439@code{pt} @tab Portuguese
12440@item
12441@code{qu} @tab Quechua @tab
12442@code{rm} @tab Rhaeto-Romance @tab
12443@code{rn} @tab Kirundi
12444@item
12445@code{ro} @tab Romanian @tab
12446@code{ru} @tab Russian @tab
12447@code{rw} @tab Kinyarwanda
12448@item
12449@code{sa} @tab Sanskrit @tab
12450@code{sd} @tab Sindhi @tab
12451@code{sg} @tab Sangro
12452@item
12453@code{sh} @tab Serbo-Croatian @tab
12454@code{si} @tab Sinhalese @tab
12455@code{sk} @tab Slovak
12456@item
12457@code{sl} @tab Slovenian @tab
12458@code{sm} @tab Samoan @tab
12459@code{sn} @tab Shona
12460@item
12461@code{so} @tab Somali @tab
12462@code{sq} @tab Albanian @tab
12463@code{sr} @tab Serbian
12464@item
12465@code{ss} @tab Siswati @tab
12466@code{st} @tab Sesotho @tab
12467@code{su} @tab Sundanese
12468@item
12469@code{sv} @tab Swedish @tab
12470@code{sw} @tab Swahili @tab
12471@code{ta} @tab Tamil
12472@item
12473@code{te} @tab Telugu @tab
12474@code{tg} @tab Tajik @tab
12475@code{th} @tab Thai
12476@item
12477@code{ti} @tab Tigrinya @tab
12478@code{tk} @tab Turkmen @tab
12479@code{tl} @tab Tagalog
12480@item
12481@code{tn} @tab Setswana @tab
12482@code{to} @tab Tonga @tab
12483@code{tr} @tab Turkish
12484@item
12485@code{ts} @tab Tsonga @tab
12486@code{tt} @tab Tatar @tab
12487@code{tw} @tab Twi
12488@item
12489@code{ug} @tab Uighur @tab
12490@code{uk} @tab Ukrainian @tab
12491@code{ur} @tab Urdu
12492@item
12493@code{uz} @tab Uzbek @tab
12494@code{vi} @tab Vietnamese @tab
12495@code{vo} @tab Volapuk
12496@item
12497@code{wo} @tab Wolof @tab
12498@code{xh} @tab Xhosa @tab
12499@code{yi} @tab Yiddish
12500@item
12501@code{yo} @tab Yoruba @tab
12502@code{za} @tab Zhuang @tab
12503@code{zh} @tab Chinese
12504@item
12505@code{zu} @tab Zulu
12506@end multitable
12507
12508
12509@node documentencoding
12510@section @code{@@documentencoding @var{enc}}: Set Input Encoding
12511
12512@findex documentencoding
12513@cindex Encoding, declaring
12514@cindex Input encoding, declaring
12515@cindex Document input encoding
12516
12517The @code{@@documentencoding} command declares the input document
12518encoding. Write it on a line by itself, with a valid encoding
12519specification following, such as @samp{ISO-8859-1}.
12520
12521@cindex http-equiv, and charset
12522@cindex meta HTML tag, and charset
12523At present, this is used only in HTML output from @code{makeinfo}. If a
12524document encoding @var{enc} is specified, it is used in a
12525@samp{<meta>} tag included in the @samp{<head>} of the output:
12526
12527@example
12528<meta http-equiv="Content-Type" content="text/html;
12529 charset=@var{enc}">
12530@end example
12531
12532
12533@node Defining New Texinfo Commands
12534@chapter Defining New Texinfo Commands
12535@cindex Macros
12536@cindex Defining new Texinfo commands
12537@cindex New Texinfo commands, defining
12538@cindex Texinfo commands, defining new
12539@cindex User-defined Texinfo commands
12540
12541Texinfo provides several ways to define new commands:
12542
12543@itemize @bullet
12544@item
12545A Texinfo @dfn{macro} allows you to define a new Texinfo command as any
12546sequence of text and/or existing commands (including other macros). The
12547macro can have any number of @dfn{parameters}---text you supply each
12548time you use the macro.
12549
12550Incidentally, these macros have nothing to do with the @code{@@defmac}
12551command, which is for documenting macros in the subject of the manual
12552(@pxref{Def Cmd Template}).
12553
12554@item
12555@samp{@@alias} is a convenient way to define a new name for an existing
12556command.
12557
12558@item
12559@samp{@@definfoenclose} allows you to define new commands with
12560customized output in the Info file.
12561
12562@end itemize
12563
12564@menu
12565* Defining Macros:: Defining and undefining new commands.
12566* Invoking Macros:: Using a macro, once you've defined it.
12567* Macro Details:: Beyond basic macro usage.
12568* alias:: Command aliases.
12569* definfoenclose:: Customized highlighting.
12570@end menu
12571
12572
12573@node Defining Macros
12574@section Defining Macros
12575@cindex Defining macros
12576@cindex Macro definitions
12577
12578@findex macro
12579You use the Texinfo @code{@@macro} command to define a macro, like this:
12580
12581@example
12582@@macro @var{macroname}@{@var{param1}, @var{param2}, @dots{}@}
12583@var{text} @dots{} \@var{param1}\ @dots{}
12584@@end macro
12585@end example
12586
12587The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to
12588arguments supplied when the macro is subsequently used in the document
12589(described in the next section).
12590
12591For a macro to work with @TeX{}, @var{macroname} must consist entirely
12592of letters: no digits, hyphens, underscores, or other special characters.
12593
12594If a macro needs no parameters, you can define it either with an empty
12595list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro
12596foo}).
12597
12598@cindex Body of a macro
12599@cindex Mutually recursive macros
12600@cindex Recursion, mutual
12601The definition or @dfn{body} of the macro can contain most Texinfo
12602commands, including previously-defined macros. Not-yet-defined macro
12603invocations are not allowed; thus, it is not possible to have mutually
12604recursive Texinfo macros. Also, a macro definition that defines another
12605macro does not work in @TeX{} due to limitations in the design of
12606@code{@@macro}.
12607
12608@cindex Parameters to macros
12609In the macro body, instances of a parameter name surrounded by
12610backslashes, as in @samp{\@var{param1}\} in the example above, are
12611replaced by the corresponding argument from the macro invocation. You
12612can use parameter names any number of times in the body, including zero.
12613
12614@cindex Backslash in macros
12615To get a single @samp{\} in the macro expansion, use @samp{\\}. Any
12616other use of @samp{\} in the body yields a warning.
12617
12618@cindex Spaces in macros
12619@cindex Whitespace in macros
12620The newlines after the @code{@@macro} line and before the @code{@@end
12621macro} line are ignored, that is, not included in the macro body. All
12622other whitespace is treated according to the usual Texinfo rules.
12623
12624@cindex Recursive macro invocations
12625@findex rmacro
12626To allow a macro to be used recursively, that is, in an argument to a
12627call to itself, you must define it with @samp{@@rmacro}, like this:
12628
12629@example
12630@@rmacro rmac @{arg@}
12631a\arg\b
12632@@end rmacro
12633@dots{}
12634@@rmac@{1@@rmac@{text@}2@}
12635@end example
12636
12637This produces the output `a1atextb2b'. With @samp{@@macro} instead of
12638@samp{@@rmacro}, an error message is given.
12639
12640@findex unmacro
12641@cindex Macros, undefining
12642@cindex Undefining macros
12643You can undefine a macro @var{foo} with @code{@@unmacro @var{foo}}.
12644It is not an error to undefine a macro that is already undefined.
12645For example:
12646
12647@example
12648@@unmacro foo
12649@end example
12650
12651
12652@node Invoking Macros
12653@section Invoking Macros
12654@cindex Invoking macros
12655@cindex Expanding macros
12656@cindex Running macros
12657@cindex Macro invocation
12658
12659After a macro is defined (see the previous section), you can use
12660(@dfn{invoke}) it in your document like this:
12661
12662@example
12663@@@var{macroname} @{@var{arg1}, @var{arg2}, @dots{}@}
12664@end example
12665
12666@noindent and the result will be just as if you typed the body of
12667@var{macroname} at that spot. For example:
12668
12669@example
12670@@macro foo @{p, q@}
12671Together: \p\ & \q\.
12672@@end macro
12673@@foo@{a, b@}
12674@end example
12675
12676@noindent produces:
12677
12678@display
12679Together: a & b.
12680@end display
12681
12682@cindex Backslash, and macros
12683Thus, the arguments and parameters are separated by commas and delimited
12684by braces; any whitespace after (but not before) a comma is ignored.
12685The braces are required in the invocation (but not the definition), even
12686when the macro takes no arguments, consistent with all other Texinfo
12687commands. For example:
12688
12689@example
12690@@macro argless @{@}
12691No arguments here.
12692@@end macro
12693@@argless@{@}
12694@end example
12695
12696@noindent produces:
12697
12698@display
12699No arguments here.
12700@end display
12701
12702@cindex Comma, in macro arguments
12703@cindex Braces, in macro arguments
12704To insert a comma, brace, or backslash in an argument, prepend a
12705backslash, as in
12706
12707@example
12708@@@var{macname} @{\\\@{\@}\,@}
12709@end example
12710
12711@noindent
12712which will pass the (almost certainly error-producing) argument
12713@samp{\@{@},} to @var{macname}. However, commas in parameters, even
12714if escaped by a backslash, might cause trouble in @TeX{}.
12715
12716If the macro is defined to take a single argument, and is invoked
12717without any braces, the entire rest of the line after the macro name is
12718supplied as the argument. For example:
12719
12720@example
12721@@macro bar @{p@}
12722Twice: \p\ & \p\.
12723@@end macro
12724@@bar aah
12725@end example
12726
12727@noindent produces:
12728
12729@c Sorry for cheating, but let's not require macros to process the manual.
12730@display
12731Twice: aah & aah.
12732@end display
12733
12734If the macro is defined to take a single argument, and is invoked with
12735braces, the braced text is passed as the argument, regardless of
12736commas. For example:
12737
12738@example
12739@@macro bar @{p@}
12740Twice: \p\ & \p\.
12741@@end macro
12742@@bar@{a,b@}
12743@end example
12744
12745@noindent produces:
12746
12747@display
12748Twice: a,b & a,b.
12749@end display
12750
12751
12752@node Macro Details
12753@section Macro Details
12754@cindex Macro details
12755@cindex Details of macro usage
12756
12757Due to unavoidable disparities in the @TeX{} and @command{makeinfo}
12758implementations, Texinfo macros have the following limitations.
12759
12760@itemize @bullet
12761@item
12762All macros are expanded inside at least one @TeX{} group. This means
12763that @code{@@set} and other such commands will have no effect inside a
12764macro.
12765
12766@item
12767Macros containing a command which must be on a line by itself, such as a
12768conditional, cannot be invoked in the middle of a line.
12769
12770@item
12771Commas in macro arguments, even if escaped by a backslash, don't
12772always work.
12773
12774@item
12775The @TeX{} implementation cannot construct macros that define macros in
12776the natural way. To do this, you must use conditionals and raw @TeX{}.
12777For example:
12778
12779@example
|
12663@@ifinfo
| 12780@@ifnottex
|
12664@@macro ctor @{name, arg@}
12665@@macro \name\
12666something involving \arg\ somehow
12667@@end macro
12668@@end macro
| 12781@@macro ctor @{name, arg@}
12782@@macro \name\
12783something involving \arg\ somehow
12784@@end macro
12785@@end macro
|
12669@@end ifinfo
| 12786@@end ifnottex
|
12670@@tex
12671\gdef\ctor#1@{\ctorx#1,@}
12672\gdef\ctorx#1,#2,@{\def#1@{something involving #2 somehow@}@}
12673@@end tex
12674@end example
12675
12676@item
12677It is best to avoid comments inside macro definitions.
12678
12679@end itemize
12680
12681If some macro feature causes errors when producing the printed version
12682of a manual, try expanding the macros with @command{makeinfo} by
12683invoking @command{texi2dvi} with the @samp{-e} option; see @ref{Format
12684with texi2dvi}.
12685
12686@node alias
12687@section @samp{@@alias @var{new}=@var{existing}}
12688@cindex Aliases, command
12689@cindex Command aliases
12690@findex alias
12691
12692The @samp{@@alias} command defines a new command to be just like an
12693existing one. This is useful for defining additional markup names, thus
12694preserving semantic information in the input even though the output
12695result may be the same.
12696
12697Write the @samp{@@alias} command on a line by itself, followed by the
12698new command name, an equals sign, and the existing command name.
12699Whitespace around the equals sign is ignored. Thus:
12700@example
12701@@alias @var{new} = @var{existing}
12702@end example
12703
12704For example, if your document contains citations for both books and
12705some other media (movies, for example), you might like to define a
12706macro @code{@@moviecite@{@}} that does the same thing as an ordinary
12707@code{@@cite@{@}} but conveys the extra semantic information as well.
12708You'd do this as follows:
12709
12710@example
12711@@alias moviecite = cite
12712@end example
12713
12714Macros do not always have the same effect due to vagaries of argument
12715parsing. Also, aliases are much simpler to define than macros. So the
12716command is not redundant. (It was also heavily used in the Jargon File!)
12717
12718Aliases must not be recursive, directly or indirectly.
12719
12720@node definfoenclose
12721@section @samp{definfoenclose}: Customized Highlighting
12722@cindex Highlighting, customized
12723@cindex Customized highlighting
12724@findex definfoenclose
12725
12726A @code{@@definfoenclose} command may be used to define a highlighting
12727command for Info, but not for @TeX{}. A command defined using
12728@code{@@definfoenclose} marks text by enclosing it in strings that
12729precede and follow the text. You can use this to get closer control of
12730your Info output.
12731
12732Presumably, if you define a command with @code{@@definfoenclose} for Info,
12733you will create a corresponding command for @TeX{}, either in
12734@file{texinfo.tex}, @file{texinfo.cnf}, or within an @samp{@@iftex} in
12735your document.
12736
12737Write a @code{@@definfoenclose} command on a line and follow it with
12738three arguments separated by commas. The first argument to
12739@code{@@definfoenclose} is the @@-command name (without the @code{@@});
12740the second argument is the Info start delimiter string; and the third
12741argument is the Info end delimiter string. The latter two arguments
12742enclose the highlighted text in the Info file. A delimiter string may
12743contain spaces. Neither the start nor end delimiter is required. If
12744you do not want a start delimiter but do want an end delimiter, you must
12745follow the command name with two commas in a row; otherwise, the Info
12746formatting commands will naturally misinterpret the end delimiter string
12747you intended as the start delimiter string.
12748
12749If you do a @code{@@definfoenclose} on the name of a pre-defined macro
12750(such as @code{@@emph}, @code{@@strong}, @code{@@t}, or @code{@@i}), the
12751enclosure definition will override the built-in definition.
12752
12753An enclosure command defined this way takes one argument in braces; this
12754is intended for new markup commands (@pxref{Marking Text}).
12755
12756@findex phoo
12757For example, you can write:
12758
12759@example
12760@@definfoenclose phoo,//,\\
12761@end example
12762
12763@noindent
12764near the beginning of a Texinfo file to define @code{@@phoo} as an Info
12765formatting command that inserts `//' before and `\\' after the argument
12766to @code{@@phoo}. You can then write @code{@@phoo@{bar@}} wherever you
12767want `//bar\\' highlighted in Info.
12768
12769Also, for @TeX{} formatting, you could write
12770
12771@example
12772@@iftex
12773@@global@@let@@phoo=@@i
12774@@end iftex
12775@end example
12776
12777@noindent
12778to define @code{@@phoo} as a command that causes @TeX{} to typeset the
12779argument to @code{@@phoo} in italics.
12780
12781Each definition applies to its own formatter: one for @TeX{}, the other
12782for @code{texinfo-format-buffer} or @code{texinfo-format-region}. The
12783@code{@@definfoenclose} command need not be within @samp{@@ifinfo}, but
12784the raw @TeX{} commands do need to be in @samp{@@iftex}.
12785
12786@findex headword
12787Here is another example: write
12788
12789@example
12790@@definfoenclose headword, , :
12791@end example
12792
12793@noindent
12794near the beginning of the file, to define @code{@@headword} as an Info
12795formatting command that inserts nothing before and a colon after the
12796argument to @code{@@headword}.
12797
12798@samp{@@definfoenclose} definitions must not be recursive, directly or
12799indirectly.
12800
12801
12802@node Hardcopy
12803@chapter Formatting and Printing Hardcopy
12804@cindex Format and print hardcopy
12805@cindex Printing hardcopy
12806@cindex Hardcopy, printing it
12807@cindex Making a printed manual
12808@cindex Sorting indices
12809@cindex Indices, sorting
12810@cindex @TeX{} index sorting
12811@pindex texindex
12812
12813There are three major shell commands for making a printed manual from a
12814Texinfo file: one for converting the Texinfo file into a file that will be
12815printed, a second for sorting indices, and a third for printing the
12816formatted document. When you use the shell commands, you can either
12817work directly in the operating system shell or work within a shell
12818inside GNU Emacs.
12819
12820If you are using GNU Emacs, you can use commands provided by Texinfo
12821mode instead of shell commands. In addition to the three commands to
12822format a file, sort the indices, and print the result, Texinfo mode
12823offers key bindings for commands to recenter the output buffer, show the
12824print queue, and delete a job from the print queue.
12825
12826@menu
12827* Use TeX:: Use @TeX{} to format for hardcopy.
12828* Format with tex/texindex:: How to format with explicit shell commands.
12829* Format with texi2dvi:: A simpler way to format.
12830* Print with lpr:: How to print.
12831* Within Emacs:: How to format and print from an Emacs shell.
12832* Texinfo Mode Printing:: How to format and print in Texinfo mode.
12833* Compile-Command:: How to print using Emacs's compile command.
12834* Requirements Summary:: @TeX{} formatting requirements summary.
12835* Preparing for TeX:: What to do before you use @TeX{}.
12836* Overfull hboxes:: What are and what to do with overfull hboxes.
12837* smallbook:: How to print small format books and manuals.
12838* A4 Paper:: How to print on A4 or A5 paper.
12839* pagesizes:: How to print with customized page sizes.
12840* Cropmarks and Magnification:: How to print marks to indicate the size
12841 of pages and how to print scaled up output.
12842* PDF Output:: Portable Document Format output.
12843@end menu
12844
12845@node Use TeX
12846@section Use @TeX{}
12847
12848The typesetting program called @TeX{} is used for formatting a Texinfo
12849file. @TeX{} is a very powerful typesetting program and, if used correctly,
12850does an exceptionally good job. (@xref{Obtaining TeX, , How to Obtain
12851@TeX{}}, for information on how to obtain @TeX{}.)
12852
12853The standalone @code{makeinfo} program and Emacs functions
12854@code{texinfo-format-region} and @code{texinfo-format-buffer} commands
12855read the very same @@-commands in the Texinfo file as does @TeX{}, but
12856process them differently to make an Info file (@pxref{Creating an Info
12857File}).
12858
12859
12860@node Format with tex/texindex
12861@section Format with @code{tex} and @code{texindex}
12862@cindex Shell formatting with @code{tex} and @code{texindex}
12863@cindex Formatting with @code{tex} and @code{texindex}
12864@cindex DVI file
12865
12866Format the Texinfo file with the shell command @code{tex} followed by
12867the name of the Texinfo file. For example:
12868
12869@example
12870tex foo.texi
12871@end example
12872
12873@noindent @TeX{} will produce a @dfn{DVI file} as well as several auxiliary
12874files containing information for indices, cross references, etc. The
12875DVI file (for @dfn{DeVice Independent} file) can be printed on virtually
12876any device (see the following sections).
12877
12878@pindex texindex
12879The @code{tex} formatting command itself does not sort the indices; it
12880writes an output file of unsorted index data. (The @code{texi2dvi}
12881command automatically generates indices; @pxref{Format with texi2dvi,,
12882Format with @code{texi2dvi}}.) To generate a printed index after
12883running the @code{tex} command, you first need a sorted index to work
12884from. The @code{texindex} command sorts indices. (The source file
12885@file{texindex.c} comes as part of the standard Texinfo distribution,
12886among other places.)@refill
12887
12888@cindex Names of index files
12889@cindex Index file names
12890The @code{tex} formatting command outputs unsorted index files under
12891names that obey a standard convention: the name of your main input file
12892with any @samp{.tex} (or similar, @pxref{tex invocation,,, web2c,
12893Web2c}) extension removed, followed by the two letter names of indices.
12894For example, the raw index output files for the input file
12895@file{foo.texinfo} would be @file{foo.cp}, @file{foo.vr}, @file{foo.fn},
12896@file{foo.tp}, @file{foo.pg} and @file{foo.ky}. Those are exactly the
12897arguments to give to @code{texindex}.
12898
12899@need 1000
12900@cindex Wildcards
12901@cindex Globbing
12902Instead of specifying all the unsorted index file names explicitly, you
12903can use @samp{??} as shell wildcards and give the command in this
12904form:
12905
12906@example
12907texindex foo.??
12908@end example
12909
12910@noindent
12911This command will run @code{texindex} on all the unsorted index files,
12912including any that you have defined yourself using @code{@@defindex}
12913or @code{@@defcodeindex}. (You may execute @samp{texindex foo.??}
12914even if there are similarly named files with two letter extensions
12915that are not index files, such as @samp{foo.el}. The @code{texindex}
12916command reports but otherwise ignores such files.)
12917
12918For each file specified, @code{texindex} generates a sorted index file
12919whose name is made by appending @samp{s} to the input file name. The
12920@code{@@printindex} command looks for a file with that name
12921(@pxref{Printing Indices & Menus}). @code{texindex} does not alter the
12922raw index output file.
12923
12924After you have sorted the indices, you need to rerun the @code{tex}
12925formatting command on the Texinfo file. This regenerates the DVI file,
12926this time with up-to-date index entries.
12927
12928Finally, you may need to run @code{tex} one more time, to get the page
12929numbers in the cross-references correct.
12930
12931To summarize, this is a five step process:
12932
12933@enumerate
12934@item
12935Run @code{tex} on your Texinfo file. This generates a DVI file (with
12936undefined cross-references and no indices), and the raw index files
12937(with two letter extensions).
12938
12939@item
12940Run @code{texindex} on the raw index files. This creates the
12941corresponding sorted index files (with three letter extensions).
12942
12943@item
12944Run @code{tex} again on your Texinfo file. This regenerates the DVI
12945file, this time with indices and defined cross-references, but with page
12946numbers for the cross-references from last time, generally incorrect.
12947
12948@item
12949Sort the indices again, with @code{texindex}.
12950
12951@item
12952Run @code{tex} one last time. This time the correct page numbers are
12953written for the cross-references.
12954@end enumerate
12955
12956@pindex texi2dvi
12957Alternatively, it's a one-step process: run @code{texi2dvi}
12958(@pxref{Format with texi2dvi}).
12959
12960You need not run @code{texindex} each time after you run @code{tex}. If
12961you do not, on the next run, the @code{tex} formatting command will use
12962whatever sorted index files happen to exist from the previous use of
12963@code{texindex}. This is usually ok while you are debugging.
12964
12965@cindex Auxiliary files, avoiding
12966@findex novalidate
12967@cindex Pointer validation, suppressing
12968@cindex Chapters, formatting one at a time
12969Sometimes you may wish to print a document while you know it is
12970incomplete, or to print just one chapter of a document. In that case,
12971the usual auxiliary files that @TeX{} creates and warnings @TeX{} gives
12972when cross-references are not satisfied are just nuisances. You can
12973avoid them with the @code{@@novalidate} command, which you must give
12974@emph{before} the @code{@@setfilename} command
12975(@pxref{setfilename,,@code{@@setfilename}}). Thus, the beginning of
12976your file would look approximately like this:
12977
12978@example
12979\input texinfo
12980@@novalidate
12981@@setfilename myfile.info
12982@dots{}
12983@end example
12984
12985@noindent @code{@@novalidate} also turns off validation in
12986@code{makeinfo}, just like its @code{--no-validate} option
12987(@pxref{Pointer Validation}).
12988
12989
12990@node Format with texi2dvi
12991@section Format with @code{texi2dvi}
12992@pindex texi2dvi @r{(shell script)}
12993
12994The @code{texi2dvi} command automatically runs both @code{tex} and
12995@code{texindex} as many times as necessary to produce a DVI file with
12996sorted indices and all cross-references resolved. It simplifies the
12997@code{tex}---@code{texindex}---@code{tex}---@code{tex} sequence
12998described in the previous section.
12999
13000To run @code{texi2dvi} on an input file @file{foo.texi}, do this (where
13001@samp{prompt$ } is your shell prompt):
13002
13003@example
13004prompt$ @kbd{texi2dvi foo.texi}
13005@end example
13006
13007As shown in this example, the input filenames to @code{texi2dvi} must
13008include any extension (@samp{.texi}, @samp{.texinfo}, etc.). Under
13009MS-DOS and perhaps in other circumstances, you may need to run @samp{sh
13010texi2dvi foo.texi} instead of relying on the operating system to invoke
13011the shell on the @samp{texi2dvi} script.
13012
13013Perhaps the most useful option to @code{texi2dvi} is
13014@samp{--texinfo=@var{cmd}}. This inserts @var{cmd} on a line by itself
13015after the @code{@@setfilename} in a temporary copy of the input file
13016before running @TeX{}. With this, you can specify different printing
13017formats, such as @code{@@smallbook} (@pxref{smallbook}),
13018@code{@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes}
13019(@pxref{pagesizes}), without actually changing the document source.
13020(You can also do this on a site-wide basis with @file{texinfo.cnf};
13021@pxref{Preparing for TeX,,Preparing for @TeX{}}).
13022
13023For a list of other options, run @samp{texi2dvi --help}.
13024
13025
13026@node Print with lpr
13027@section Shell Print Using @code{lpr -d}
13028@pindex lpr @r{(DVI print command)}
13029
13030The precise command to print a DVI file depends on your system
13031installation. Two common ones are @samp{dvips foo.dvi -o} and @samp{lpr
13032-d foo.dvi}.
13033
13034For example, the following commands will (perhaps) suffice to sort the
13035indices, format, and print the @cite{Bison Manual}:
13036
13037@example
13038@group
13039tex bison.texinfo
13040texindex bison.??
13041tex bison.texinfo
13042lpr -d bison.dvi
13043@end group
13044@end example
13045
13046@noindent
13047(Remember that the shell commands may be different at your site; but
13048these are commonly used versions.)
13049
13050Using the @code{texi2dvi} shell script (see the previous section):
13051
13052@example
13053@group
13054texi2dvi bison.texinfo
13055lpr -d bison.dvi
13056# or perhaps dvips bison.dvi -o
13057@end group
13058@end example
13059
13060@cindex Shell printing, on MS-DOS/MS-Windows
13061@cindex Printing DVI files, on MS-DOS/MS-Windows
13062@pindex lpr@r{-d, replacements on MS-DOS/MS-Windows}
13063@code{lpr} is a standard program on Unix systems, but it is usually
13064absent on MS-DOS/MS-Windows. Some network packages come with a
13065program named @code{lpr}, but these are usually limited to sending files
13066to a print server over the network, and generally don't support the
13067@samp{-d} option. If you are unfortunate enough to work on one of these
13068systems, you have several alternative ways of printing DVI files:
13069
13070@itemize @bullet{}
13071@item Find and install a Unix-like @code{lpr} program, or its clone.
13072If you can do that, you will be able to print DVI files just like
13073described above.
13074
13075@item Send the DVI files to a network printer queue for DVI files.
13076Some network printers have special queues for printing DVI files. You
13077should be able to set up your network software to send files to that
13078queue. In some cases, the version of @code{lpr} which comes with your
13079network software will have a special option to send a file to specific
13080queues, like this:
13081
13082@example
13083lpr -Qdvi -hprint.server.domain bison.dvi
13084@end example
13085
13086@item Convert the DVI file to a Postscript or PCL file and send it to your
13087local printer. @xref{dvips invocation,,, dvips, Dvips}, and the man
13088pages for @code{dvilj}, for detailed description of these tools. Once
13089the DVI file is converted to the format your local printer understands
13090directly, just send it to the appropriate port, usually @samp{PRN}.
13091@end itemize
13092
13093
13094@node Within Emacs
13095@section From an Emacs Shell
13096@cindex Print, format from Emacs shell
13097@cindex Format, print from Emacs shell
13098@cindex Shell, format, print from
13099@cindex Emacs shell, format, print from
13100@cindex GNU Emacs shell, format, print from
13101
13102You can give formatting and printing commands from a shell within GNU
13103Emacs. To create a shell within Emacs, type @kbd{M-x shell}. In this
13104shell, you can format and print the document. @xref{Hardcopy, , Format
13105and Print Hardcopy}, for details.
13106
13107You can switch to and from the shell buffer while @code{tex} is
13108running and do other editing. If you are formatting a long document
13109on a slow machine, this can be very convenient.@refill
13110
13111You can also use @code{texi2dvi} from an Emacs shell. For example,
13112here is how to use @code{texi2dvi} to format and print @cite{Using and
13113Porting GNU CC} from a shell within Emacs:
13114
13115@example
13116@group
13117texi2dvi gcc.texinfo
13118lpr -d gcc.dvi
13119@end group
13120@end example
13121@ifinfo
13122
13123@xref{Texinfo Mode Printing}, for more information about formatting
13124and printing in Texinfo mode.@refill
13125@end ifinfo
13126
13127
13128@node Texinfo Mode Printing, Compile-Command, Within Emacs, Hardcopy
13129@section Formatting and Printing in Texinfo Mode
13130@cindex Region printing in Texinfo mode
13131@cindex Format and print in Texinfo mode
13132@cindex Print and format in Texinfo mode
13133
13134Texinfo mode provides several predefined key commands for @TeX{}
13135formatting and printing. These include commands for sorting indices,
13136looking at the printer queue, killing the formatting job, and
13137recentering the display of the buffer in which the operations
13138occur.@refill
13139
13140@table @kbd
13141@item C-c C-t C-b
13142@itemx M-x texinfo-tex-buffer
13143Run @code{texi2dvi} on the current buffer.@refill
13144
13145@item C-c C-t C-r
13146@itemx M-x texinfo-tex-region
13147Run @TeX{} on the current region.@refill
13148
13149@item C-c C-t C-i
13150@itemx M-x texinfo-texindex
13151Sort the indices of a Texinfo file formatted with
13152@code{texinfo-tex-region}.@refill
13153
13154@item C-c C-t C-p
13155@itemx M-x texinfo-tex-print
13156Print a DVI file that was made with @code{texinfo-tex-region} or
13157@code{texinfo-tex-buffer}.@refill
13158
13159@item C-c C-t C-q
13160@itemx M-x tex-show-print-queue
13161Show the print queue.@refill
13162
13163@item C-c C-t C-d
13164@itemx M-x texinfo-delete-from-print-queue
13165Delete a job from the print queue; you will be prompted for the job
13166number shown by a preceding @kbd{C-c C-t C-q} command
13167(@code{texinfo-show-tex-print-queue}).@refill
13168
13169@item C-c C-t C-k
13170@itemx M-x tex-kill-job
13171Kill the currently running @TeX{} job started by either
13172@code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other
13173process running in the Texinfo shell buffer.@refill
13174
13175@item C-c C-t C-x
13176@itemx M-x texinfo-quit-job
13177Quit a @TeX{} formatting job that has stopped because of an error by
13178sending an @key{x} to it. When you do this, @TeX{} preserves a record
13179of what it did in a @file{.log} file.@refill
13180
13181@item C-c C-t C-l
13182@itemx M-x tex-recenter-output-buffer
13183Redisplay the shell buffer in which the @TeX{} printing and formatting
13184commands are run to show its most recent output.@refill
13185@end table
13186
13187@need 1000
13188Thus, the usual sequence of commands for formatting a buffer is as
13189follows (with comments to the right):@refill
13190
13191@example
13192@group
13193C-c C-t C-b @r{Run @code{texi2dvi} on the buffer.}
13194C-c C-t C-p @r{Print the DVI file.}
13195C-c C-t C-q @r{Display the printer queue.}
13196@end group
13197@end example
13198
13199The Texinfo mode @TeX{} formatting commands start a subshell in Emacs
13200called the @file{*tex-shell*}. The @code{texinfo-tex-command},
13201@code{texinfo-texindex-command}, and @code{tex-dvi-print-command}
13202commands are all run in this shell.
13203
13204You can watch the commands operate in the @samp{*tex-shell*} buffer,
13205and you can switch to and from and use the @samp{*tex-shell*} buffer
13206as you would any other shell buffer.@refill
13207
13208@need 1500
13209The formatting and print commands depend on the values of several variables.
13210The default values are:@refill
13211
13212@example
13213@group
13214 @r{Variable} @r{Default value}
13215
13216texinfo-texi2dvi-command "texi2dvi"
13217texinfo-tex-command "tex"
13218texinfo-texindex-command "texindex"
13219texinfo-delete-from-print-queue-command "lprm"
13220texinfo-tex-trailer "@@bye"
13221tex-start-of-header "%**start"
13222tex-end-of-header "%**end"
13223tex-dvi-print-command "lpr -d"
13224tex-show-queue-command "lpq"
13225@end group
13226@end example
13227
13228You can change the values of these variables with the @kbd{M-x
13229edit-options} command (@pxref{Edit Options, , Editing Variable Values,
13230emacs, The GNU Emacs Manual}), with the @kbd{M-x set-variable} command
13231(@pxref{Examining, , Examining and Setting Variables, emacs, The GNU
13232Emacs Manual}), or with your @file{.emacs} initialization file
13233(@pxref{Init File, , , emacs, The GNU Emacs Manual}).@refill
13234
| 12787@@tex
12788\gdef\ctor#1@{\ctorx#1,@}
12789\gdef\ctorx#1,#2,@{\def#1@{something involving #2 somehow@}@}
12790@@end tex
12791@end example
12792
12793@item
12794It is best to avoid comments inside macro definitions.
12795
12796@end itemize
12797
12798If some macro feature causes errors when producing the printed version
12799of a manual, try expanding the macros with @command{makeinfo} by
12800invoking @command{texi2dvi} with the @samp{-e} option; see @ref{Format
12801with texi2dvi}.
12802
12803@node alias
12804@section @samp{@@alias @var{new}=@var{existing}}
12805@cindex Aliases, command
12806@cindex Command aliases
12807@findex alias
12808
12809The @samp{@@alias} command defines a new command to be just like an
12810existing one. This is useful for defining additional markup names, thus
12811preserving semantic information in the input even though the output
12812result may be the same.
12813
12814Write the @samp{@@alias} command on a line by itself, followed by the
12815new command name, an equals sign, and the existing command name.
12816Whitespace around the equals sign is ignored. Thus:
12817@example
12818@@alias @var{new} = @var{existing}
12819@end example
12820
12821For example, if your document contains citations for both books and
12822some other media (movies, for example), you might like to define a
12823macro @code{@@moviecite@{@}} that does the same thing as an ordinary
12824@code{@@cite@{@}} but conveys the extra semantic information as well.
12825You'd do this as follows:
12826
12827@example
12828@@alias moviecite = cite
12829@end example
12830
12831Macros do not always have the same effect due to vagaries of argument
12832parsing. Also, aliases are much simpler to define than macros. So the
12833command is not redundant. (It was also heavily used in the Jargon File!)
12834
12835Aliases must not be recursive, directly or indirectly.
12836
12837@node definfoenclose
12838@section @samp{definfoenclose}: Customized Highlighting
12839@cindex Highlighting, customized
12840@cindex Customized highlighting
12841@findex definfoenclose
12842
12843A @code{@@definfoenclose} command may be used to define a highlighting
12844command for Info, but not for @TeX{}. A command defined using
12845@code{@@definfoenclose} marks text by enclosing it in strings that
12846precede and follow the text. You can use this to get closer control of
12847your Info output.
12848
12849Presumably, if you define a command with @code{@@definfoenclose} for Info,
12850you will create a corresponding command for @TeX{}, either in
12851@file{texinfo.tex}, @file{texinfo.cnf}, or within an @samp{@@iftex} in
12852your document.
12853
12854Write a @code{@@definfoenclose} command on a line and follow it with
12855three arguments separated by commas. The first argument to
12856@code{@@definfoenclose} is the @@-command name (without the @code{@@});
12857the second argument is the Info start delimiter string; and the third
12858argument is the Info end delimiter string. The latter two arguments
12859enclose the highlighted text in the Info file. A delimiter string may
12860contain spaces. Neither the start nor end delimiter is required. If
12861you do not want a start delimiter but do want an end delimiter, you must
12862follow the command name with two commas in a row; otherwise, the Info
12863formatting commands will naturally misinterpret the end delimiter string
12864you intended as the start delimiter string.
12865
12866If you do a @code{@@definfoenclose} on the name of a pre-defined macro
12867(such as @code{@@emph}, @code{@@strong}, @code{@@t}, or @code{@@i}), the
12868enclosure definition will override the built-in definition.
12869
12870An enclosure command defined this way takes one argument in braces; this
12871is intended for new markup commands (@pxref{Marking Text}).
12872
12873@findex phoo
12874For example, you can write:
12875
12876@example
12877@@definfoenclose phoo,//,\\
12878@end example
12879
12880@noindent
12881near the beginning of a Texinfo file to define @code{@@phoo} as an Info
12882formatting command that inserts `//' before and `\\' after the argument
12883to @code{@@phoo}. You can then write @code{@@phoo@{bar@}} wherever you
12884want `//bar\\' highlighted in Info.
12885
12886Also, for @TeX{} formatting, you could write
12887
12888@example
12889@@iftex
12890@@global@@let@@phoo=@@i
12891@@end iftex
12892@end example
12893
12894@noindent
12895to define @code{@@phoo} as a command that causes @TeX{} to typeset the
12896argument to @code{@@phoo} in italics.
12897
12898Each definition applies to its own formatter: one for @TeX{}, the other
12899for @code{texinfo-format-buffer} or @code{texinfo-format-region}. The
12900@code{@@definfoenclose} command need not be within @samp{@@ifinfo}, but
12901the raw @TeX{} commands do need to be in @samp{@@iftex}.
12902
12903@findex headword
12904Here is another example: write
12905
12906@example
12907@@definfoenclose headword, , :
12908@end example
12909
12910@noindent
12911near the beginning of the file, to define @code{@@headword} as an Info
12912formatting command that inserts nothing before and a colon after the
12913argument to @code{@@headword}.
12914
12915@samp{@@definfoenclose} definitions must not be recursive, directly or
12916indirectly.
12917
12918
12919@node Hardcopy
12920@chapter Formatting and Printing Hardcopy
12921@cindex Format and print hardcopy
12922@cindex Printing hardcopy
12923@cindex Hardcopy, printing it
12924@cindex Making a printed manual
12925@cindex Sorting indices
12926@cindex Indices, sorting
12927@cindex @TeX{} index sorting
12928@pindex texindex
12929
12930There are three major shell commands for making a printed manual from a
12931Texinfo file: one for converting the Texinfo file into a file that will be
12932printed, a second for sorting indices, and a third for printing the
12933formatted document. When you use the shell commands, you can either
12934work directly in the operating system shell or work within a shell
12935inside GNU Emacs.
12936
12937If you are using GNU Emacs, you can use commands provided by Texinfo
12938mode instead of shell commands. In addition to the three commands to
12939format a file, sort the indices, and print the result, Texinfo mode
12940offers key bindings for commands to recenter the output buffer, show the
12941print queue, and delete a job from the print queue.
12942
12943@menu
12944* Use TeX:: Use @TeX{} to format for hardcopy.
12945* Format with tex/texindex:: How to format with explicit shell commands.
12946* Format with texi2dvi:: A simpler way to format.
12947* Print with lpr:: How to print.
12948* Within Emacs:: How to format and print from an Emacs shell.
12949* Texinfo Mode Printing:: How to format and print in Texinfo mode.
12950* Compile-Command:: How to print using Emacs's compile command.
12951* Requirements Summary:: @TeX{} formatting requirements summary.
12952* Preparing for TeX:: What to do before you use @TeX{}.
12953* Overfull hboxes:: What are and what to do with overfull hboxes.
12954* smallbook:: How to print small format books and manuals.
12955* A4 Paper:: How to print on A4 or A5 paper.
12956* pagesizes:: How to print with customized page sizes.
12957* Cropmarks and Magnification:: How to print marks to indicate the size
12958 of pages and how to print scaled up output.
12959* PDF Output:: Portable Document Format output.
12960@end menu
12961
12962@node Use TeX
12963@section Use @TeX{}
12964
12965The typesetting program called @TeX{} is used for formatting a Texinfo
12966file. @TeX{} is a very powerful typesetting program and, if used correctly,
12967does an exceptionally good job. (@xref{Obtaining TeX, , How to Obtain
12968@TeX{}}, for information on how to obtain @TeX{}.)
12969
12970The standalone @code{makeinfo} program and Emacs functions
12971@code{texinfo-format-region} and @code{texinfo-format-buffer} commands
12972read the very same @@-commands in the Texinfo file as does @TeX{}, but
12973process them differently to make an Info file (@pxref{Creating an Info
12974File}).
12975
12976
12977@node Format with tex/texindex
12978@section Format with @code{tex} and @code{texindex}
12979@cindex Shell formatting with @code{tex} and @code{texindex}
12980@cindex Formatting with @code{tex} and @code{texindex}
12981@cindex DVI file
12982
12983Format the Texinfo file with the shell command @code{tex} followed by
12984the name of the Texinfo file. For example:
12985
12986@example
12987tex foo.texi
12988@end example
12989
12990@noindent @TeX{} will produce a @dfn{DVI file} as well as several auxiliary
12991files containing information for indices, cross references, etc. The
12992DVI file (for @dfn{DeVice Independent} file) can be printed on virtually
12993any device (see the following sections).
12994
12995@pindex texindex
12996The @code{tex} formatting command itself does not sort the indices; it
12997writes an output file of unsorted index data. (The @code{texi2dvi}
12998command automatically generates indices; @pxref{Format with texi2dvi,,
12999Format with @code{texi2dvi}}.) To generate a printed index after
13000running the @code{tex} command, you first need a sorted index to work
13001from. The @code{texindex} command sorts indices. (The source file
13002@file{texindex.c} comes as part of the standard Texinfo distribution,
13003among other places.)@refill
13004
13005@cindex Names of index files
13006@cindex Index file names
13007The @code{tex} formatting command outputs unsorted index files under
13008names that obey a standard convention: the name of your main input file
13009with any @samp{.tex} (or similar, @pxref{tex invocation,,, web2c,
13010Web2c}) extension removed, followed by the two letter names of indices.
13011For example, the raw index output files for the input file
13012@file{foo.texinfo} would be @file{foo.cp}, @file{foo.vr}, @file{foo.fn},
13013@file{foo.tp}, @file{foo.pg} and @file{foo.ky}. Those are exactly the
13014arguments to give to @code{texindex}.
13015
13016@need 1000
13017@cindex Wildcards
13018@cindex Globbing
13019Instead of specifying all the unsorted index file names explicitly, you
13020can use @samp{??} as shell wildcards and give the command in this
13021form:
13022
13023@example
13024texindex foo.??
13025@end example
13026
13027@noindent
13028This command will run @code{texindex} on all the unsorted index files,
13029including any that you have defined yourself using @code{@@defindex}
13030or @code{@@defcodeindex}. (You may execute @samp{texindex foo.??}
13031even if there are similarly named files with two letter extensions
13032that are not index files, such as @samp{foo.el}. The @code{texindex}
13033command reports but otherwise ignores such files.)
13034
13035For each file specified, @code{texindex} generates a sorted index file
13036whose name is made by appending @samp{s} to the input file name. The
13037@code{@@printindex} command looks for a file with that name
13038(@pxref{Printing Indices & Menus}). @code{texindex} does not alter the
13039raw index output file.
13040
13041After you have sorted the indices, you need to rerun the @code{tex}
13042formatting command on the Texinfo file. This regenerates the DVI file,
13043this time with up-to-date index entries.
13044
13045Finally, you may need to run @code{tex} one more time, to get the page
13046numbers in the cross-references correct.
13047
13048To summarize, this is a five step process:
13049
13050@enumerate
13051@item
13052Run @code{tex} on your Texinfo file. This generates a DVI file (with
13053undefined cross-references and no indices), and the raw index files
13054(with two letter extensions).
13055
13056@item
13057Run @code{texindex} on the raw index files. This creates the
13058corresponding sorted index files (with three letter extensions).
13059
13060@item
13061Run @code{tex} again on your Texinfo file. This regenerates the DVI
13062file, this time with indices and defined cross-references, but with page
13063numbers for the cross-references from last time, generally incorrect.
13064
13065@item
13066Sort the indices again, with @code{texindex}.
13067
13068@item
13069Run @code{tex} one last time. This time the correct page numbers are
13070written for the cross-references.
13071@end enumerate
13072
13073@pindex texi2dvi
13074Alternatively, it's a one-step process: run @code{texi2dvi}
13075(@pxref{Format with texi2dvi}).
13076
13077You need not run @code{texindex} each time after you run @code{tex}. If
13078you do not, on the next run, the @code{tex} formatting command will use
13079whatever sorted index files happen to exist from the previous use of
13080@code{texindex}. This is usually ok while you are debugging.
13081
13082@cindex Auxiliary files, avoiding
13083@findex novalidate
13084@cindex Pointer validation, suppressing
13085@cindex Chapters, formatting one at a time
13086Sometimes you may wish to print a document while you know it is
13087incomplete, or to print just one chapter of a document. In that case,
13088the usual auxiliary files that @TeX{} creates and warnings @TeX{} gives
13089when cross-references are not satisfied are just nuisances. You can
13090avoid them with the @code{@@novalidate} command, which you must give
13091@emph{before} the @code{@@setfilename} command
13092(@pxref{setfilename,,@code{@@setfilename}}). Thus, the beginning of
13093your file would look approximately like this:
13094
13095@example
13096\input texinfo
13097@@novalidate
13098@@setfilename myfile.info
13099@dots{}
13100@end example
13101
13102@noindent @code{@@novalidate} also turns off validation in
13103@code{makeinfo}, just like its @code{--no-validate} option
13104(@pxref{Pointer Validation}).
13105
13106
13107@node Format with texi2dvi
13108@section Format with @code{texi2dvi}
13109@pindex texi2dvi @r{(shell script)}
13110
13111The @code{texi2dvi} command automatically runs both @code{tex} and
13112@code{texindex} as many times as necessary to produce a DVI file with
13113sorted indices and all cross-references resolved. It simplifies the
13114@code{tex}---@code{texindex}---@code{tex}---@code{tex} sequence
13115described in the previous section.
13116
13117To run @code{texi2dvi} on an input file @file{foo.texi}, do this (where
13118@samp{prompt$ } is your shell prompt):
13119
13120@example
13121prompt$ @kbd{texi2dvi foo.texi}
13122@end example
13123
13124As shown in this example, the input filenames to @code{texi2dvi} must
13125include any extension (@samp{.texi}, @samp{.texinfo}, etc.). Under
13126MS-DOS and perhaps in other circumstances, you may need to run @samp{sh
13127texi2dvi foo.texi} instead of relying on the operating system to invoke
13128the shell on the @samp{texi2dvi} script.
13129
13130Perhaps the most useful option to @code{texi2dvi} is
13131@samp{--texinfo=@var{cmd}}. This inserts @var{cmd} on a line by itself
13132after the @code{@@setfilename} in a temporary copy of the input file
13133before running @TeX{}. With this, you can specify different printing
13134formats, such as @code{@@smallbook} (@pxref{smallbook}),
13135@code{@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes}
13136(@pxref{pagesizes}), without actually changing the document source.
13137(You can also do this on a site-wide basis with @file{texinfo.cnf};
13138@pxref{Preparing for TeX,,Preparing for @TeX{}}).
13139
13140For a list of other options, run @samp{texi2dvi --help}.
13141
13142
13143@node Print with lpr
13144@section Shell Print Using @code{lpr -d}
13145@pindex lpr @r{(DVI print command)}
13146
13147The precise command to print a DVI file depends on your system
13148installation. Two common ones are @samp{dvips foo.dvi -o} and @samp{lpr
13149-d foo.dvi}.
13150
13151For example, the following commands will (perhaps) suffice to sort the
13152indices, format, and print the @cite{Bison Manual}:
13153
13154@example
13155@group
13156tex bison.texinfo
13157texindex bison.??
13158tex bison.texinfo
13159lpr -d bison.dvi
13160@end group
13161@end example
13162
13163@noindent
13164(Remember that the shell commands may be different at your site; but
13165these are commonly used versions.)
13166
13167Using the @code{texi2dvi} shell script (see the previous section):
13168
13169@example
13170@group
13171texi2dvi bison.texinfo
13172lpr -d bison.dvi
13173# or perhaps dvips bison.dvi -o
13174@end group
13175@end example
13176
13177@cindex Shell printing, on MS-DOS/MS-Windows
13178@cindex Printing DVI files, on MS-DOS/MS-Windows
13179@pindex lpr@r{-d, replacements on MS-DOS/MS-Windows}
13180@code{lpr} is a standard program on Unix systems, but it is usually
13181absent on MS-DOS/MS-Windows. Some network packages come with a
13182program named @code{lpr}, but these are usually limited to sending files
13183to a print server over the network, and generally don't support the
13184@samp{-d} option. If you are unfortunate enough to work on one of these
13185systems, you have several alternative ways of printing DVI files:
13186
13187@itemize @bullet{}
13188@item Find and install a Unix-like @code{lpr} program, or its clone.
13189If you can do that, you will be able to print DVI files just like
13190described above.
13191
13192@item Send the DVI files to a network printer queue for DVI files.
13193Some network printers have special queues for printing DVI files. You
13194should be able to set up your network software to send files to that
13195queue. In some cases, the version of @code{lpr} which comes with your
13196network software will have a special option to send a file to specific
13197queues, like this:
13198
13199@example
13200lpr -Qdvi -hprint.server.domain bison.dvi
13201@end example
13202
13203@item Convert the DVI file to a Postscript or PCL file and send it to your
13204local printer. @xref{dvips invocation,,, dvips, Dvips}, and the man
13205pages for @code{dvilj}, for detailed description of these tools. Once
13206the DVI file is converted to the format your local printer understands
13207directly, just send it to the appropriate port, usually @samp{PRN}.
13208@end itemize
13209
13210
13211@node Within Emacs
13212@section From an Emacs Shell
13213@cindex Print, format from Emacs shell
13214@cindex Format, print from Emacs shell
13215@cindex Shell, format, print from
13216@cindex Emacs shell, format, print from
13217@cindex GNU Emacs shell, format, print from
13218
13219You can give formatting and printing commands from a shell within GNU
13220Emacs. To create a shell within Emacs, type @kbd{M-x shell}. In this
13221shell, you can format and print the document. @xref{Hardcopy, , Format
13222and Print Hardcopy}, for details.
13223
13224You can switch to and from the shell buffer while @code{tex} is
13225running and do other editing. If you are formatting a long document
13226on a slow machine, this can be very convenient.@refill
13227
13228You can also use @code{texi2dvi} from an Emacs shell. For example,
13229here is how to use @code{texi2dvi} to format and print @cite{Using and
13230Porting GNU CC} from a shell within Emacs:
13231
13232@example
13233@group
13234texi2dvi gcc.texinfo
13235lpr -d gcc.dvi
13236@end group
13237@end example
13238@ifinfo
13239
13240@xref{Texinfo Mode Printing}, for more information about formatting
13241and printing in Texinfo mode.@refill
13242@end ifinfo
13243
13244
13245@node Texinfo Mode Printing, Compile-Command, Within Emacs, Hardcopy
13246@section Formatting and Printing in Texinfo Mode
13247@cindex Region printing in Texinfo mode
13248@cindex Format and print in Texinfo mode
13249@cindex Print and format in Texinfo mode
13250
13251Texinfo mode provides several predefined key commands for @TeX{}
13252formatting and printing. These include commands for sorting indices,
13253looking at the printer queue, killing the formatting job, and
13254recentering the display of the buffer in which the operations
13255occur.@refill
13256
13257@table @kbd
13258@item C-c C-t C-b
13259@itemx M-x texinfo-tex-buffer
13260Run @code{texi2dvi} on the current buffer.@refill
13261
13262@item C-c C-t C-r
13263@itemx M-x texinfo-tex-region
13264Run @TeX{} on the current region.@refill
13265
13266@item C-c C-t C-i
13267@itemx M-x texinfo-texindex
13268Sort the indices of a Texinfo file formatted with
13269@code{texinfo-tex-region}.@refill
13270
13271@item C-c C-t C-p
13272@itemx M-x texinfo-tex-print
13273Print a DVI file that was made with @code{texinfo-tex-region} or
13274@code{texinfo-tex-buffer}.@refill
13275
13276@item C-c C-t C-q
13277@itemx M-x tex-show-print-queue
13278Show the print queue.@refill
13279
13280@item C-c C-t C-d
13281@itemx M-x texinfo-delete-from-print-queue
13282Delete a job from the print queue; you will be prompted for the job
13283number shown by a preceding @kbd{C-c C-t C-q} command
13284(@code{texinfo-show-tex-print-queue}).@refill
13285
13286@item C-c C-t C-k
13287@itemx M-x tex-kill-job
13288Kill the currently running @TeX{} job started by either
13289@code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other
13290process running in the Texinfo shell buffer.@refill
13291
13292@item C-c C-t C-x
13293@itemx M-x texinfo-quit-job
13294Quit a @TeX{} formatting job that has stopped because of an error by
13295sending an @key{x} to it. When you do this, @TeX{} preserves a record
13296of what it did in a @file{.log} file.@refill
13297
13298@item C-c C-t C-l
13299@itemx M-x tex-recenter-output-buffer
13300Redisplay the shell buffer in which the @TeX{} printing and formatting
13301commands are run to show its most recent output.@refill
13302@end table
13303
13304@need 1000
13305Thus, the usual sequence of commands for formatting a buffer is as
13306follows (with comments to the right):@refill
13307
13308@example
13309@group
13310C-c C-t C-b @r{Run @code{texi2dvi} on the buffer.}
13311C-c C-t C-p @r{Print the DVI file.}
13312C-c C-t C-q @r{Display the printer queue.}
13313@end group
13314@end example
13315
13316The Texinfo mode @TeX{} formatting commands start a subshell in Emacs
13317called the @file{*tex-shell*}. The @code{texinfo-tex-command},
13318@code{texinfo-texindex-command}, and @code{tex-dvi-print-command}
13319commands are all run in this shell.
13320
13321You can watch the commands operate in the @samp{*tex-shell*} buffer,
13322and you can switch to and from and use the @samp{*tex-shell*} buffer
13323as you would any other shell buffer.@refill
13324
13325@need 1500
13326The formatting and print commands depend on the values of several variables.
13327The default values are:@refill
13328
13329@example
13330@group
13331 @r{Variable} @r{Default value}
13332
13333texinfo-texi2dvi-command "texi2dvi"
13334texinfo-tex-command "tex"
13335texinfo-texindex-command "texindex"
13336texinfo-delete-from-print-queue-command "lprm"
13337texinfo-tex-trailer "@@bye"
13338tex-start-of-header "%**start"
13339tex-end-of-header "%**end"
13340tex-dvi-print-command "lpr -d"
13341tex-show-queue-command "lpq"
13342@end group
13343@end example
13344
13345You can change the values of these variables with the @kbd{M-x
13346edit-options} command (@pxref{Edit Options, , Editing Variable Values,
13347emacs, The GNU Emacs Manual}), with the @kbd{M-x set-variable} command
13348(@pxref{Examining, , Examining and Setting Variables, emacs, The GNU
13349Emacs Manual}), or with your @file{.emacs} initialization file
13350(@pxref{Init File, , , emacs, The GNU Emacs Manual}).@refill
13351
|
13235@cindex Customize Emacs package
13236@findex Development/Docs/Texinfo Customize group
| 13352@cindex Customize Emacs package (@t{Development/Docs/Texinfo})
|
13237Beginning with version 20, GNU Emacs offers a user-friendly interface,
13238called @dfn{Customize}, for changing values of user-definable variables.
13239@xref{Easy Customization, , Easy Customization Interface, emacs, The GNU
13240Emacs Manual}, for more details about this. The Texinfo variables can
13241be found in the @samp{Development/Docs/Texinfo} group, once you invoke
13242the @kbd{M-x customize} command.
13243
13244
| 13353Beginning with version 20, GNU Emacs offers a user-friendly interface,
13354called @dfn{Customize}, for changing values of user-definable variables.
13355@xref{Easy Customization, , Easy Customization Interface, emacs, The GNU
13356Emacs Manual}, for more details about this. The Texinfo variables can
13357be found in the @samp{Development/Docs/Texinfo} group, once you invoke
13358the @kbd{M-x customize} command.
13359
13360
|
13245@node Compile-Command, Requirements Summary, Texinfo Mode Printing, Hardcopy
| 13361@node Compile-Command
|
13246@section Using the Local Variables List
13247@cindex Local variables
13248@cindex Compile command for formatting
13249@cindex Format with the compile command
13250
13251Yet another way to apply the @TeX{} formatting command to a Texinfo file
13252is to put that command in a @dfn{local variables list} at the end of the
13253Texinfo file. You can then specify the @code{tex} or @code{texi2dvi}
13254commands as a @code{compile-command} and have Emacs run it by typing
13255@kbd{M-x compile}. This creates a special shell called the
13256@file{*compilation*} buffer in which Emacs runs the compile command.
13257For example, at the end of the @file{gdb.texinfo} file, after the
13258@code{@@bye}, you could put the following:@refill
13259
13260@example
13261@group
13262Local Variables:
13263compile-command: "texi2dvi gdb.texinfo"
13264End:
13265@end group
13266@end example
13267
13268@noindent
13269This technique is most often used by programmers who also compile programs
13270this way; see @ref{Compilation, , , emacs, The GNU Emacs Manual}.@refill
13271
13272
13273@node Requirements Summary
13274@section @TeX{} Formatting Requirements Summary
13275@cindex Requirements for formatting
13276@cindex Minimal requirements for formatting
13277@cindex Formatting requirements
13278
13279Every Texinfo file that is to be input to @TeX{} must begin with a
13280@code{\input} command and must contain an @code{@@setfilename} command:
13281
13282@example
13283\input texinfo
13284@@setfilename @var{arg-not-used-by-@TeX{}}
13285@end example
13286
13287@noindent
13288The first command instructs @TeX{} to load the macros it needs to
13289process a Texinfo file and the second command opens auxiliary files.
13290
13291Every Texinfo file must end with a line that terminates @TeX{}'s
13292processing and forces out unfinished pages:
13293
13294@example
13295@@bye
13296@end example
13297
13298Strictly speaking, these lines are all a Texinfo file needs to be
13299processed successfully by @TeX{}.
13300
13301Usually, however, the beginning includes an @code{@@settitle} command to
13302define the title of the printed manual, an @code{@@setchapternewpage}
13303command, a title page, a copyright page, and permissions. Besides an
13304@code{@@bye}, the end of a file usually includes indices and a table of
13305contents. (And of course most manuals contain a body of text as well.)
13306
13307For more information, see:
13308@itemize @bullet
13309@item @ref{settitle, , @code{@@settitle}}
13310@item @ref{setchapternewpage, , @code{@@setchapternewpage}}
13311@item @ref{Headings, ,Page Headings}
13312@item @ref{Titlepage & Copyright Page}
13313@item @ref{Printing Indices & Menus}
13314@item @ref{Contents}
13315@end itemize
13316
13317
13318@node Preparing for TeX
13319@section Preparing for @TeX{}
13320@cindex Preparing for @TeX{}
13321@cindex @TeX{} input initialization
13322@cindex @code{TEXINPUTS} environment variable
13323@vindex TEXINPUTS
13324@cindex @b{.profile} initialization file
13325@cindex @b{.cshrc} initialization file
13326@cindex Initialization file for @TeX{} input
13327
13328@TeX{} needs to know where to find the @file{texinfo.tex} file that the
13329@samp{\input texinfo} command on the first line reads. The
13330@file{texinfo.tex} file tells @TeX{} how to handle @@-commands; it is
13331included in all standard GNU distributions.
13332
13333@pindex texinfo.tex@r{, installing}
13334
13335Usually, the installer has put the @file{texinfo.tex} file in the
13336default directory that contains @TeX{} macros when GNU Texinfo, Emacs or
13337other GNU software is installed. In this case, @TeX{} will find the
13338file and you do not need to do anything special. If this has not been
13339done, you can put @file{texinfo.tex} in the current directory when you
13340run @TeX{}, and @TeX{} will find it there.
13341
13342@pindex epsf.tex@r{, installing}
13343Also, you should install @file{epsf.tex}, if it is not already installed
13344from another distribution. More details are at the end of the description
13345of the @code{@@image} command (@pxref{Images}).
13346
13347@pindex pdfcolor.tex@r{, installing}
13348Likewise for @file{pdfcolor.tex}, if it is not already installed and you
13349use pdftex.
13350
13351@pindex texinfo.cnf @r{installation}
13352@cindex Customizing of @TeX{} for Texinfo
13353@cindex Site-wide Texinfo configuration file
13354Optionally, you may create an additional @file{texinfo.cnf}, and install
13355it as well. This file is read by @TeX{} when the @code{@@setfilename}
13356command is executed (@pxref{setfilename,, @code{@@setfilename}}). You can put any
13357commands you like there, according to local site-wide conventions. They
13358will be read by @TeX{} when processing any Texinfo document. For
13359example, if @file{texinfo.cnf} contains the line @samp{@@afourpaper}
13360(@pxref{A4 Paper}), then all Texinfo documents will be processed with
13361that page size in effect. If you have nothing to put in
13362@file{texinfo.cnf}, you do not need to create it.
13363
13364@vindex TEXINPUTS
13365If neither of the above locations for these system files suffice for
13366you, you can specify the directories explicitly. For
13367@file{texinfo.tex}, you can do this by writing the complete path for the
13368file after the @code{\input} command. Another way, that works for both
13369@file{texinfo.tex} and @file{texinfo.cnf} (and any other file @TeX{}
13370might read), is to set the @code{TEXINPUTS} environment variable in your
13371@file{.cshrc} or @file{.profile} file.
13372
13373Which you use of @file{.cshrc} or @file{.profile} depends on
13374whether you use a Bourne shell-compatible (@code{sh}, @code{bash},
13375@code{ksh}, @dots{}) or C shell-compatible (@code{csh}, @code{tcsh})
13376command interpreter. The latter read the @file{.cshrc} file for
13377initialization information, and the former read @file{.profile}.
13378
13379In a @file{.cshrc} file, you could use the following @code{csh} command
13380sequence:
13381
13382@example
13383setenv TEXINPUTS .:/home/me/mylib:/usr/lib/tex/macros
13384@end example
13385
13386@need 1000
13387In a @file{.profile} file, you could use the following @code{sh} command
13388sequence:
13389
13390@example
13391@group
13392TEXINPUTS=.:/home/me/mylib:/usr/lib/tex/macros
13393export TEXINPUTS
13394@end group
13395@end example
13396
13397On MS-DOS/MS-Windows, you would say it like this@footnote{Note the use
13398of the @samp{;} character, instead of @samp{:}, as directory separator
13399on these systems.}:
13400
13401@example
13402@group
13403set TEXINPUTS=.;d:/home/me/mylib;c:/usr/lib/tex/macros
13404@end group
13405@end example
13406
13407@noindent
13408It is customary for DOS/Windows users to put such commands in the
13409@file{autoexec.bat} file, or in the Windows Registry.@refill
13410
13411@noindent
13412These settings would cause @TeX{} to look for @file{\input} file first
13413in the current directory, indicated by the @samp{.}, then in a
13414hypothetical user's @file{me/mylib} directory, and finally in a system
13415directory @file{/usr/lib/tex/macros}.
13416
13417@cindex Dumping a .fmt file
13418@cindex Format file, dumping
13419Finally, you may wish to dump a @file{.fmt} file (@pxref{Memory dumps,,,
13420web2c, Web2c}) so that @TeX{} can load Texinfo faster. (The
13421disadvantage is that then updating @file{texinfo.tex} requires
13422redumping.) You can do this by running this command, assuming
13423@file{epsf.tex} is findable by @TeX{}:
13424
13425@example
13426initex texinfo @@dump
13427@end example
13428
13429(@code{dump} is a @TeX{} primitive.) Then, move @file{texinfo.fmt} to
13430wherever your @code{.fmt} files are found; typically, this will be in the
13431subdirectory @file{web2c} of your @TeX{} installation.
13432
13433
13434@node Overfull hboxes
13435@section Overfull ``hboxes''
13436@cindex Overfull @samp{hboxes}
13437@cindex @samp{hboxes}, overfull
13438@cindex Final output
13439
13440@TeX{} is sometimes unable to typeset a line without extending it into
13441the right margin. This can occur when @TeX{} comes upon what it
13442interprets as a long word that it cannot hyphenate, such as an
13443electronic mail network address or a very long title. When this
13444happens, @TeX{} prints an error message like this:
13445
13446@example
13447Overfull @@hbox (20.76302pt too wide)
13448@end example
13449
13450@findex hbox
13451@noindent
13452(In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''.
13453@samp{@@hbox} is a @TeX{} primitive not needed in the Texinfo language.)
13454
13455@TeX{} also provides the line number in the Texinfo source file and
13456the text of the offending line, which is marked at all the places that
13457@TeX{} considered hyphenation.
13458@xref{Debugging with TeX, , Catching Errors with @TeX{} Formatting},
13459for more information about typesetting errors.
13460
13461If the Texinfo file has an overfull hbox, you can rewrite the sentence
13462so the overfull hbox does not occur, or you can decide to leave it. A
13463small excursion into the right margin often does not matter and may not
13464even be noticeable.
13465
13466If you have many overfull boxes and/or an antipathy to rewriting, you
13467can coerce @TeX{} into greatly increasing the allowable interword
13468spacing, thus (if you're lucky) avoiding many of the bad line breaks,
13469like this:
13470
13471@findex \emergencystretch
13472@example
13473@@tex
13474\global\emergencystretch = .9\hsize
13475@@end tex
13476@end example
13477
13478@noindent
13479(You should adjust the fraction as needed.) This huge value for
13480@code{\emergencystretch} cannot be the default, since then the typeset
13481output would generally be of noticeably lower quality; the default
13482is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension
13483containing the current line width.
13484
13485@cindex Black rectangle in hardcopy
13486@cindex Rectangle, black in hardcopy
13487@cindex Box, ugly black in hardcopy
13488@cindex Ugly black rectangles in hardcopy
13489For what overfull boxes you have, however, @TeX{} will print a large,
13490ugly, black rectangle beside the line that contains the overfull hbox
13491unless told otherwise. This is so you will notice the location of the
13492problem if you are correcting a draft.
13493
13494@findex finalout
13495To prevent such a monstrosity from marring your final printout, write
13496the following in the beginning of the Texinfo file on a line of its own,
13497before the @code{@@titlepage} command:
13498
13499@example
13500@@finalout
13501@end example
13502
13503
13504@node smallbook
13505@section Printing ``Small'' Books
13506@findex smallbook
13507@cindex Small book size
13508@cindex Book, printing small
13509@cindex Page sizes for books
13510@cindex Size of printed book
13511
13512By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch
13513format. However, you can direct @TeX{} to typeset a document in a 7 by
135149.25 inch format that is suitable for bound books by inserting the
13515following command on a line by itself at the beginning of the Texinfo
13516file, before the title page:@refill
13517
13518@example
13519@@smallbook
13520@end example
13521
13522@noindent
13523(Since many books are about 7 by 9.25 inches, this command might better
13524have been called the @code{@@regularbooksize} command, but it came to be
13525called the @code{@@smallbook} command by comparison to the 8.5 by 11 inch format.)
13526
13527If you write the @code{@@smallbook} command between the
13528start-of-header and end-of-header lines, the Texinfo mode @TeX{}
13529region formatting command, @code{texinfo-tex-region}, will format the
13530region in ``small'' book size (@pxref{Start of Header}).@refill
13531
13532@xref{small}, for information about
13533commands that make it easier to produce examples for a smaller manual.
13534
13535@xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
13536@TeX{}}, for other ways to format with @code{@@smallbook} that do not
13537require changing the source file.
13538
13539
13540@node A4 Paper
13541@section Printing on A4 Paper
13542@cindex A4 paper, printing on
13543@cindex A5 paper, printing on
13544@cindex Paper size, A4
13545@cindex European A4 paper
13546@findex afourpaper
13547
13548You can tell @TeX{} to format a document for printing on European size
13549A4 paper (or A5) with the @code{@@afourpaper} (or @code{@@afivepaper})
13550command. Write the command on a line by itself near the beginning of
13551the Texinfo file, before the title page. For example, this is how you
13552would write the header for this manual:
13553
13554@example
13555@group
13556\input texinfo @@c -*-texinfo-*-
13557@@c %**start of header
13558@@setfilename texinfo
13559@@settitle Texinfo
13560@@afourpaper
13561@@c %**end of header
13562@end group
13563@end example
13564
13565@xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
13566@TeX{}}, for other ways to format for different paper sizes that do not
13567require changing the source file.
13568
13569@findex afourlatex
13570@findex afourwide
13571You may or may not prefer the formatting that results from the command
13572@code{@@afourlatex}. There's also @code{@@afourwide} for A4 paper in
13573wide format.
13574
13575@node pagesizes
13576@section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom page sizes
13577@findex pagesizes
13578@cindex Custom page sizes
13579@cindex Page sizes, customized
13580@cindex Text width and height
13581@cindex Width of text area
13582@cindex Height of text area
13583@cindex Depth of text area
13584
13585You can explicitly specify the height and (optionally) width of the main
13586text area on the page with the @code{@@pagesizes} command. Write this
13587on a line by itself near the beginning of the Texinfo file, before the
13588title page. The height comes first, then the width if desired,
13589separated by a comma. Examples:
13590
13591@example
13592@@pagesizes 200mm,150mm @c for b5 paper
13593@end example
13594@noindent and
13595@example
13596@@pagesizes 11.5in @c for legal paper
13597@end example
13598
13599@cindex B5 paper, printing on
13600@cindex Legal paper, printing on
13601This would be reasonable for printing on B5-size paper. To emphasize,
13602this command specifies the size of the @emph{text area}, not the size of
13603the paper (which is 250@dmn{mm} by 177@dmn{mm} for B5, 14@dmn{in} by
136048.5@dmn{in} for legal).
13605
13606@cindex Margins on page, not controllable
13607To make more elaborate changes, such as changing any of the page
13608margins, you must define a new command in @file{texinfo.tex} (or
13609@file{texinfo.cnf}, @pxref{Preparing for TeX,,Preparing for @TeX{}}).
13610
13611@xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
13612@TeX{}}, for other ways to specify @code{@@pagesizes} that do not
13613require changing the source file.
13614
13615@code{@@pagesizes} is ignored by @code{makeinfo}.
13616
13617
13618@node Cropmarks and Magnification
13619@section Cropmarks and Magnification
13620@findex cropmarks
13621@cindex Cropmarks for printing
13622@cindex Printing cropmarks
13623You can (attempt to) direct @TeX{} to print cropmarks at the corners of
13624pages with the @code{@@cropmarks} command. Write the @code{@@cropmarks}
13625command on a line by itself between @code{@@iftex} and @code{@@end
13626iftex} lines near the beginning of the Texinfo file, before the title
13627page, like this:@refill
13628
13629@example
13630@group
13631@@iftex
13632@@cropmarks
13633@@end iftex
13634@end group
13635@end example
13636
13637This command is mainly for printers that typeset several pages on one
13638sheet of film; but you can attempt to use it to mark the corners of a
13639book set to 7 by 9.25 inches with the @code{@@smallbook} command.
13640(Printers will not produce cropmarks for regular sized output that is
13641printed on regular sized paper.) Since different printing machines work
13642in different ways, you should explore the use of this command with a
13643spirit of adventure. You may have to redefine the command in
13644@file{texinfo.tex}.
13645
| 13362@section Using the Local Variables List
13363@cindex Local variables
13364@cindex Compile command for formatting
13365@cindex Format with the compile command
13366
13367Yet another way to apply the @TeX{} formatting command to a Texinfo file
13368is to put that command in a @dfn{local variables list} at the end of the
13369Texinfo file. You can then specify the @code{tex} or @code{texi2dvi}
13370commands as a @code{compile-command} and have Emacs run it by typing
13371@kbd{M-x compile}. This creates a special shell called the
13372@file{*compilation*} buffer in which Emacs runs the compile command.
13373For example, at the end of the @file{gdb.texinfo} file, after the
13374@code{@@bye}, you could put the following:@refill
13375
13376@example
13377@group
13378Local Variables:
13379compile-command: "texi2dvi gdb.texinfo"
13380End:
13381@end group
13382@end example
13383
13384@noindent
13385This technique is most often used by programmers who also compile programs
13386this way; see @ref{Compilation, , , emacs, The GNU Emacs Manual}.@refill
13387
13388
13389@node Requirements Summary
13390@section @TeX{} Formatting Requirements Summary
13391@cindex Requirements for formatting
13392@cindex Minimal requirements for formatting
13393@cindex Formatting requirements
13394
13395Every Texinfo file that is to be input to @TeX{} must begin with a
13396@code{\input} command and must contain an @code{@@setfilename} command:
13397
13398@example
13399\input texinfo
13400@@setfilename @var{arg-not-used-by-@TeX{}}
13401@end example
13402
13403@noindent
13404The first command instructs @TeX{} to load the macros it needs to
13405process a Texinfo file and the second command opens auxiliary files.
13406
13407Every Texinfo file must end with a line that terminates @TeX{}'s
13408processing and forces out unfinished pages:
13409
13410@example
13411@@bye
13412@end example
13413
13414Strictly speaking, these lines are all a Texinfo file needs to be
13415processed successfully by @TeX{}.
13416
13417Usually, however, the beginning includes an @code{@@settitle} command to
13418define the title of the printed manual, an @code{@@setchapternewpage}
13419command, a title page, a copyright page, and permissions. Besides an
13420@code{@@bye}, the end of a file usually includes indices and a table of
13421contents. (And of course most manuals contain a body of text as well.)
13422
13423For more information, see:
13424@itemize @bullet
13425@item @ref{settitle, , @code{@@settitle}}
13426@item @ref{setchapternewpage, , @code{@@setchapternewpage}}
13427@item @ref{Headings, ,Page Headings}
13428@item @ref{Titlepage & Copyright Page}
13429@item @ref{Printing Indices & Menus}
13430@item @ref{Contents}
13431@end itemize
13432
13433
13434@node Preparing for TeX
13435@section Preparing for @TeX{}
13436@cindex Preparing for @TeX{}
13437@cindex @TeX{} input initialization
13438@cindex @code{TEXINPUTS} environment variable
13439@vindex TEXINPUTS
13440@cindex @b{.profile} initialization file
13441@cindex @b{.cshrc} initialization file
13442@cindex Initialization file for @TeX{} input
13443
13444@TeX{} needs to know where to find the @file{texinfo.tex} file that the
13445@samp{\input texinfo} command on the first line reads. The
13446@file{texinfo.tex} file tells @TeX{} how to handle @@-commands; it is
13447included in all standard GNU distributions.
13448
13449@pindex texinfo.tex@r{, installing}
13450
13451Usually, the installer has put the @file{texinfo.tex} file in the
13452default directory that contains @TeX{} macros when GNU Texinfo, Emacs or
13453other GNU software is installed. In this case, @TeX{} will find the
13454file and you do not need to do anything special. If this has not been
13455done, you can put @file{texinfo.tex} in the current directory when you
13456run @TeX{}, and @TeX{} will find it there.
13457
13458@pindex epsf.tex@r{, installing}
13459Also, you should install @file{epsf.tex}, if it is not already installed
13460from another distribution. More details are at the end of the description
13461of the @code{@@image} command (@pxref{Images}).
13462
13463@pindex pdfcolor.tex@r{, installing}
13464Likewise for @file{pdfcolor.tex}, if it is not already installed and you
13465use pdftex.
13466
13467@pindex texinfo.cnf @r{installation}
13468@cindex Customizing of @TeX{} for Texinfo
13469@cindex Site-wide Texinfo configuration file
13470Optionally, you may create an additional @file{texinfo.cnf}, and install
13471it as well. This file is read by @TeX{} when the @code{@@setfilename}
13472command is executed (@pxref{setfilename,, @code{@@setfilename}}). You can put any
13473commands you like there, according to local site-wide conventions. They
13474will be read by @TeX{} when processing any Texinfo document. For
13475example, if @file{texinfo.cnf} contains the line @samp{@@afourpaper}
13476(@pxref{A4 Paper}), then all Texinfo documents will be processed with
13477that page size in effect. If you have nothing to put in
13478@file{texinfo.cnf}, you do not need to create it.
13479
13480@vindex TEXINPUTS
13481If neither of the above locations for these system files suffice for
13482you, you can specify the directories explicitly. For
13483@file{texinfo.tex}, you can do this by writing the complete path for the
13484file after the @code{\input} command. Another way, that works for both
13485@file{texinfo.tex} and @file{texinfo.cnf} (and any other file @TeX{}
13486might read), is to set the @code{TEXINPUTS} environment variable in your
13487@file{.cshrc} or @file{.profile} file.
13488
13489Which you use of @file{.cshrc} or @file{.profile} depends on
13490whether you use a Bourne shell-compatible (@code{sh}, @code{bash},
13491@code{ksh}, @dots{}) or C shell-compatible (@code{csh}, @code{tcsh})
13492command interpreter. The latter read the @file{.cshrc} file for
13493initialization information, and the former read @file{.profile}.
13494
13495In a @file{.cshrc} file, you could use the following @code{csh} command
13496sequence:
13497
13498@example
13499setenv TEXINPUTS .:/home/me/mylib:/usr/lib/tex/macros
13500@end example
13501
13502@need 1000
13503In a @file{.profile} file, you could use the following @code{sh} command
13504sequence:
13505
13506@example
13507@group
13508TEXINPUTS=.:/home/me/mylib:/usr/lib/tex/macros
13509export TEXINPUTS
13510@end group
13511@end example
13512
13513On MS-DOS/MS-Windows, you would say it like this@footnote{Note the use
13514of the @samp{;} character, instead of @samp{:}, as directory separator
13515on these systems.}:
13516
13517@example
13518@group
13519set TEXINPUTS=.;d:/home/me/mylib;c:/usr/lib/tex/macros
13520@end group
13521@end example
13522
13523@noindent
13524It is customary for DOS/Windows users to put such commands in the
13525@file{autoexec.bat} file, or in the Windows Registry.@refill
13526
13527@noindent
13528These settings would cause @TeX{} to look for @file{\input} file first
13529in the current directory, indicated by the @samp{.}, then in a
13530hypothetical user's @file{me/mylib} directory, and finally in a system
13531directory @file{/usr/lib/tex/macros}.
13532
13533@cindex Dumping a .fmt file
13534@cindex Format file, dumping
13535Finally, you may wish to dump a @file{.fmt} file (@pxref{Memory dumps,,,
13536web2c, Web2c}) so that @TeX{} can load Texinfo faster. (The
13537disadvantage is that then updating @file{texinfo.tex} requires
13538redumping.) You can do this by running this command, assuming
13539@file{epsf.tex} is findable by @TeX{}:
13540
13541@example
13542initex texinfo @@dump
13543@end example
13544
13545(@code{dump} is a @TeX{} primitive.) Then, move @file{texinfo.fmt} to
13546wherever your @code{.fmt} files are found; typically, this will be in the
13547subdirectory @file{web2c} of your @TeX{} installation.
13548
13549
13550@node Overfull hboxes
13551@section Overfull ``hboxes''
13552@cindex Overfull @samp{hboxes}
13553@cindex @samp{hboxes}, overfull
13554@cindex Final output
13555
13556@TeX{} is sometimes unable to typeset a line without extending it into
13557the right margin. This can occur when @TeX{} comes upon what it
13558interprets as a long word that it cannot hyphenate, such as an
13559electronic mail network address or a very long title. When this
13560happens, @TeX{} prints an error message like this:
13561
13562@example
13563Overfull @@hbox (20.76302pt too wide)
13564@end example
13565
13566@findex hbox
13567@noindent
13568(In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''.
13569@samp{@@hbox} is a @TeX{} primitive not needed in the Texinfo language.)
13570
13571@TeX{} also provides the line number in the Texinfo source file and
13572the text of the offending line, which is marked at all the places that
13573@TeX{} considered hyphenation.
13574@xref{Debugging with TeX, , Catching Errors with @TeX{} Formatting},
13575for more information about typesetting errors.
13576
13577If the Texinfo file has an overfull hbox, you can rewrite the sentence
13578so the overfull hbox does not occur, or you can decide to leave it. A
13579small excursion into the right margin often does not matter and may not
13580even be noticeable.
13581
13582If you have many overfull boxes and/or an antipathy to rewriting, you
13583can coerce @TeX{} into greatly increasing the allowable interword
13584spacing, thus (if you're lucky) avoiding many of the bad line breaks,
13585like this:
13586
13587@findex \emergencystretch
13588@example
13589@@tex
13590\global\emergencystretch = .9\hsize
13591@@end tex
13592@end example
13593
13594@noindent
13595(You should adjust the fraction as needed.) This huge value for
13596@code{\emergencystretch} cannot be the default, since then the typeset
13597output would generally be of noticeably lower quality; the default
13598is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension
13599containing the current line width.
13600
13601@cindex Black rectangle in hardcopy
13602@cindex Rectangle, black in hardcopy
13603@cindex Box, ugly black in hardcopy
13604@cindex Ugly black rectangles in hardcopy
13605For what overfull boxes you have, however, @TeX{} will print a large,
13606ugly, black rectangle beside the line that contains the overfull hbox
13607unless told otherwise. This is so you will notice the location of the
13608problem if you are correcting a draft.
13609
13610@findex finalout
13611To prevent such a monstrosity from marring your final printout, write
13612the following in the beginning of the Texinfo file on a line of its own,
13613before the @code{@@titlepage} command:
13614
13615@example
13616@@finalout
13617@end example
13618
13619
13620@node smallbook
13621@section Printing ``Small'' Books
13622@findex smallbook
13623@cindex Small book size
13624@cindex Book, printing small
13625@cindex Page sizes for books
13626@cindex Size of printed book
13627
13628By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch
13629format. However, you can direct @TeX{} to typeset a document in a 7 by
136309.25 inch format that is suitable for bound books by inserting the
13631following command on a line by itself at the beginning of the Texinfo
13632file, before the title page:@refill
13633
13634@example
13635@@smallbook
13636@end example
13637
13638@noindent
13639(Since many books are about 7 by 9.25 inches, this command might better
13640have been called the @code{@@regularbooksize} command, but it came to be
13641called the @code{@@smallbook} command by comparison to the 8.5 by 11 inch format.)
13642
13643If you write the @code{@@smallbook} command between the
13644start-of-header and end-of-header lines, the Texinfo mode @TeX{}
13645region formatting command, @code{texinfo-tex-region}, will format the
13646region in ``small'' book size (@pxref{Start of Header}).@refill
13647
13648@xref{small}, for information about
13649commands that make it easier to produce examples for a smaller manual.
13650
13651@xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
13652@TeX{}}, for other ways to format with @code{@@smallbook} that do not
13653require changing the source file.
13654
13655
13656@node A4 Paper
13657@section Printing on A4 Paper
13658@cindex A4 paper, printing on
13659@cindex A5 paper, printing on
13660@cindex Paper size, A4
13661@cindex European A4 paper
13662@findex afourpaper
13663
13664You can tell @TeX{} to format a document for printing on European size
13665A4 paper (or A5) with the @code{@@afourpaper} (or @code{@@afivepaper})
13666command. Write the command on a line by itself near the beginning of
13667the Texinfo file, before the title page. For example, this is how you
13668would write the header for this manual:
13669
13670@example
13671@group
13672\input texinfo @@c -*-texinfo-*-
13673@@c %**start of header
13674@@setfilename texinfo
13675@@settitle Texinfo
13676@@afourpaper
13677@@c %**end of header
13678@end group
13679@end example
13680
13681@xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
13682@TeX{}}, for other ways to format for different paper sizes that do not
13683require changing the source file.
13684
13685@findex afourlatex
13686@findex afourwide
13687You may or may not prefer the formatting that results from the command
13688@code{@@afourlatex}. There's also @code{@@afourwide} for A4 paper in
13689wide format.
13690
13691@node pagesizes
13692@section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom page sizes
13693@findex pagesizes
13694@cindex Custom page sizes
13695@cindex Page sizes, customized
13696@cindex Text width and height
13697@cindex Width of text area
13698@cindex Height of text area
13699@cindex Depth of text area
13700
13701You can explicitly specify the height and (optionally) width of the main
13702text area on the page with the @code{@@pagesizes} command. Write this
13703on a line by itself near the beginning of the Texinfo file, before the
13704title page. The height comes first, then the width if desired,
13705separated by a comma. Examples:
13706
13707@example
13708@@pagesizes 200mm,150mm @c for b5 paper
13709@end example
13710@noindent and
13711@example
13712@@pagesizes 11.5in @c for legal paper
13713@end example
13714
13715@cindex B5 paper, printing on
13716@cindex Legal paper, printing on
13717This would be reasonable for printing on B5-size paper. To emphasize,
13718this command specifies the size of the @emph{text area}, not the size of
13719the paper (which is 250@dmn{mm} by 177@dmn{mm} for B5, 14@dmn{in} by
137208.5@dmn{in} for legal).
13721
13722@cindex Margins on page, not controllable
13723To make more elaborate changes, such as changing any of the page
13724margins, you must define a new command in @file{texinfo.tex} (or
13725@file{texinfo.cnf}, @pxref{Preparing for TeX,,Preparing for @TeX{}}).
13726
13727@xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
13728@TeX{}}, for other ways to specify @code{@@pagesizes} that do not
13729require changing the source file.
13730
13731@code{@@pagesizes} is ignored by @code{makeinfo}.
13732
13733
13734@node Cropmarks and Magnification
13735@section Cropmarks and Magnification
13736@findex cropmarks
13737@cindex Cropmarks for printing
13738@cindex Printing cropmarks
13739You can (attempt to) direct @TeX{} to print cropmarks at the corners of
13740pages with the @code{@@cropmarks} command. Write the @code{@@cropmarks}
13741command on a line by itself between @code{@@iftex} and @code{@@end
13742iftex} lines near the beginning of the Texinfo file, before the title
13743page, like this:@refill
13744
13745@example
13746@group
13747@@iftex
13748@@cropmarks
13749@@end iftex
13750@end group
13751@end example
13752
13753This command is mainly for printers that typeset several pages on one
13754sheet of film; but you can attempt to use it to mark the corners of a
13755book set to 7 by 9.25 inches with the @code{@@smallbook} command.
13756(Printers will not produce cropmarks for regular sized output that is
13757printed on regular sized paper.) Since different printing machines work
13758in different ways, you should explore the use of this command with a
13759spirit of adventure. You may have to redefine the command in
13760@file{texinfo.tex}.
13761
|
13646@findex mag @r{(@TeX{} command)}
| 13762@findex \mag @r{(raw @TeX{} magnification)}
|
13647@cindex Magnified printing
13648@cindex Larger or smaller pages
13649You can attempt to direct @TeX{} to typeset pages larger or smaller than
13650usual with the @code{\mag} @TeX{} command. Everything that is typeset
13651is scaled proportionally larger or smaller. (@code{\mag} stands for
13652``magnification''.) This is @emph{not} a Texinfo @@-command, but is a
13653plain @TeX{} command that is prefixed with a backslash. You have to
13654write this command between @code{@@tex} and @code{@@end tex}
13655(@pxref{Raw Formatter Commands}).
13656
13657Follow the @code{\mag} command with an @samp{=} and then a number that
13658is 1000 times the magnification you desire. For example, to print pages
13659at 1.2 normal size, write the following near the beginning of the
13660Texinfo file, before the title page:
13661
13662@example
13663@group
13664@@tex
13665\mag=1200
13666@@end tex
13667@end group
13668@end example
13669
13670With some printing technologies, you can print normal-sized copies that
13671look better than usual by giving a larger-than-normal master to your
13672print shop. They do the reduction, thus effectively increasing the
13673resolution.
13674
13675Depending on your system, DVI files prepared with a
13676nonstandard-@code{\mag} may not print or may print only with certain
13677magnifications. Be prepared to experiment.
13678
13679
13680@node PDF Output
13681@section PDF Output
13682@cindex PDF output
13683
13684@pindex pdftex
13685You can generate a PDF output file from Texinfo source by using the
13686@command{pdftex} program to process your file instead of plain
13687@command{tex}. Just run @samp{pdftex foo.texi} instead of @samp{tex
13688foo.texi}, or give the @samp{--pdf} option to @command{texi2dvi}.
13689
13690@dfn{PDF} stands for `Portable Document Format'. It was invented by
13691Adobe Systems some years ago for document interchange, based on their
13692PostScript language. A @uref{http://www.foolabs.com/xpdf/, PDF reader}
13693for the X window system is freely available, as is the
13694@uref{http://partners.adobe.com/asn/developer/technotes/, definition of
13695the file format}. Since PDF is a binary format, there are no
13696@samp{@@ifpdf} or @samp{@@pdf} commands as with the other output
13697formats.
13698
13699Despite the `portable' in the name, PDF files are nowhere near as
13700portable in practice as the plain ASCII formats (Info, HTML) that
13701Texinfo supports (DVI portability is arguable). They also tend to be
13702much larger and do not support the bitmap fonts used by @TeX{} (by
13703default) very well. Nevertheless, a PDF file does preserve an actual
13704printed document on a screen as faithfully as possible, so it has its place.
13705
13706PDF support in Texinfo is fairly rudimentary.
13707
13708
13709@node Creating and Installing Info Files
13710@chapter Creating and Installing Info Files
13711
13712This chapter describes how to create and install Info files. @xref{Info
13713Files}, for general information about the file format itself.
13714
13715@menu
13716* Creating an Info File::
| 13763@cindex Magnified printing
13764@cindex Larger or smaller pages
13765You can attempt to direct @TeX{} to typeset pages larger or smaller than
13766usual with the @code{\mag} @TeX{} command. Everything that is typeset
13767is scaled proportionally larger or smaller. (@code{\mag} stands for
13768``magnification''.) This is @emph{not} a Texinfo @@-command, but is a
13769plain @TeX{} command that is prefixed with a backslash. You have to
13770write this command between @code{@@tex} and @code{@@end tex}
13771(@pxref{Raw Formatter Commands}).
13772
13773Follow the @code{\mag} command with an @samp{=} and then a number that
13774is 1000 times the magnification you desire. For example, to print pages
13775at 1.2 normal size, write the following near the beginning of the
13776Texinfo file, before the title page:
13777
13778@example
13779@group
13780@@tex
13781\mag=1200
13782@@end tex
13783@end group
13784@end example
13785
13786With some printing technologies, you can print normal-sized copies that
13787look better than usual by giving a larger-than-normal master to your
13788print shop. They do the reduction, thus effectively increasing the
13789resolution.
13790
13791Depending on your system, DVI files prepared with a
13792nonstandard-@code{\mag} may not print or may print only with certain
13793magnifications. Be prepared to experiment.
13794
13795
13796@node PDF Output
13797@section PDF Output
13798@cindex PDF output
13799
13800@pindex pdftex
13801You can generate a PDF output file from Texinfo source by using the
13802@command{pdftex} program to process your file instead of plain
13803@command{tex}. Just run @samp{pdftex foo.texi} instead of @samp{tex
13804foo.texi}, or give the @samp{--pdf} option to @command{texi2dvi}.
13805
13806@dfn{PDF} stands for `Portable Document Format'. It was invented by
13807Adobe Systems some years ago for document interchange, based on their
13808PostScript language. A @uref{http://www.foolabs.com/xpdf/, PDF reader}
13809for the X window system is freely available, as is the
13810@uref{http://partners.adobe.com/asn/developer/technotes/, definition of
13811the file format}. Since PDF is a binary format, there are no
13812@samp{@@ifpdf} or @samp{@@pdf} commands as with the other output
13813formats.
13814
13815Despite the `portable' in the name, PDF files are nowhere near as
13816portable in practice as the plain ASCII formats (Info, HTML) that
13817Texinfo supports (DVI portability is arguable). They also tend to be
13818much larger and do not support the bitmap fonts used by @TeX{} (by
13819default) very well. Nevertheless, a PDF file does preserve an actual
13820printed document on a screen as faithfully as possible, so it has its place.
13821
13822PDF support in Texinfo is fairly rudimentary.
13823
13824
13825@node Creating and Installing Info Files
13826@chapter Creating and Installing Info Files
13827
13828This chapter describes how to create and install Info files. @xref{Info
13829Files}, for general information about the file format itself.
13830
13831@menu
13832* Creating an Info File::
|
13717* Installing an Info File::
| 13833* Installing an Info File::
|
13718@end menu
13719
13720
13721@node Creating an Info File
13722@section Creating an Info File
13723@cindex Creating an Info file
13724@cindex Info, creating an online file
13725@cindex Formatting a file for Info
13726
13727@code{makeinfo} is a program that converts a Texinfo file into an Info
13728file, HTML file, or plain text. @code{texinfo-format-region} and
13729@code{texinfo-format-buffer} are GNU Emacs functions that convert
13730Texinfo to Info.
13731
13732For information on installing the Info file in the Info system,
13733@pxref{Installing an Info File}.
13734
13735@menu
13736* makeinfo advantages:: @code{makeinfo} provides better error checking.
13737* Invoking makeinfo:: How to run @code{makeinfo} from a shell.
13738* makeinfo options:: Specify fill-column and other options.
13739* Pointer Validation:: How to check that pointers point somewhere.
13740* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs.
13741* texinfo-format commands:: Two Info formatting commands written
13742 in Emacs Lisp are an alternative
13743 to @code{makeinfo}.
13744* Batch Formatting:: How to format for Info in Emacs Batch mode.
13745* Tag and Split Files:: How tagged and split files help Info
13746 to run better.
13747* makeinfo html:: Generating HTML output.
13748@end menu
13749
13750
13751@node makeinfo advantages
13752@subsection @code{makeinfo} Preferred
13753
13754The @code{makeinfo} utility creates an Info file from a Texinfo source
13755file more quickly than either of the Emacs formatting commands and
13756provides better error messages. We recommend it. @code{makeinfo} is a
13757C program that is independent of Emacs. You do not need to run Emacs to
13758use @code{makeinfo}, which means you can use @code{makeinfo} on machines
13759that are too small to run Emacs. You can run @code{makeinfo} in any one
13760of three ways: from an operating system shell, from a shell inside
13761Emacs, or by typing the @kbd{C-c C-m C-r} or the @kbd{C-c C-m C-b}
13762command in Texinfo mode in Emacs.
13763@refill
13764
13765The @code{texinfo-format-region} and the @code{texinfo-format-buffer}
13766commands are useful if you cannot run @code{makeinfo}. Also, in some
13767circumstances, they format short regions or buffers more quickly than
13768@code{makeinfo}.@refill
13769
13770@node Invoking makeinfo
13771@subsection Running @code{makeinfo} from a Shell
13772
13773To create an Info file from a Texinfo file, type @code{makeinfo}
13774followed by the name of the Texinfo file. Thus, to create the Info
13775file for Bison, type the following to the shell:
13776
13777@example
13778makeinfo bison.texinfo
13779@end example
13780
13781(You can run a shell inside Emacs by typing @kbd{M-x shell}.)@refill
13782
13783@ifinfo
13784Sometimes you will want to specify options. For example, if you wish
13785to discover which version of @code{makeinfo} you are using,
13786type:@refill
13787
13788@example
13789makeinfo --version
13790@end example
13791
13792@xref{makeinfo options}, for more information.
13793@end ifinfo
13794
13795
13796@node makeinfo options
| 13834@end menu
13835
13836
13837@node Creating an Info File
13838@section Creating an Info File
13839@cindex Creating an Info file
13840@cindex Info, creating an online file
13841@cindex Formatting a file for Info
13842
13843@code{makeinfo} is a program that converts a Texinfo file into an Info
13844file, HTML file, or plain text. @code{texinfo-format-region} and
13845@code{texinfo-format-buffer} are GNU Emacs functions that convert
13846Texinfo to Info.
13847
13848For information on installing the Info file in the Info system,
13849@pxref{Installing an Info File}.
13850
13851@menu
13852* makeinfo advantages:: @code{makeinfo} provides better error checking.
13853* Invoking makeinfo:: How to run @code{makeinfo} from a shell.
13854* makeinfo options:: Specify fill-column and other options.
13855* Pointer Validation:: How to check that pointers point somewhere.
13856* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs.
13857* texinfo-format commands:: Two Info formatting commands written
13858 in Emacs Lisp are an alternative
13859 to @code{makeinfo}.
13860* Batch Formatting:: How to format for Info in Emacs Batch mode.
13861* Tag and Split Files:: How tagged and split files help Info
13862 to run better.
13863* makeinfo html:: Generating HTML output.
13864@end menu
13865
13866
13867@node makeinfo advantages
13868@subsection @code{makeinfo} Preferred
13869
13870The @code{makeinfo} utility creates an Info file from a Texinfo source
13871file more quickly than either of the Emacs formatting commands and
13872provides better error messages. We recommend it. @code{makeinfo} is a
13873C program that is independent of Emacs. You do not need to run Emacs to
13874use @code{makeinfo}, which means you can use @code{makeinfo} on machines
13875that are too small to run Emacs. You can run @code{makeinfo} in any one
13876of three ways: from an operating system shell, from a shell inside
13877Emacs, or by typing the @kbd{C-c C-m C-r} or the @kbd{C-c C-m C-b}
13878command in Texinfo mode in Emacs.
13879@refill
13880
13881The @code{texinfo-format-region} and the @code{texinfo-format-buffer}
13882commands are useful if you cannot run @code{makeinfo}. Also, in some
13883circumstances, they format short regions or buffers more quickly than
13884@code{makeinfo}.@refill
13885
13886@node Invoking makeinfo
13887@subsection Running @code{makeinfo} from a Shell
13888
13889To create an Info file from a Texinfo file, type @code{makeinfo}
13890followed by the name of the Texinfo file. Thus, to create the Info
13891file for Bison, type the following to the shell:
13892
13893@example
13894makeinfo bison.texinfo
13895@end example
13896
13897(You can run a shell inside Emacs by typing @kbd{M-x shell}.)@refill
13898
13899@ifinfo
13900Sometimes you will want to specify options. For example, if you wish
13901to discover which version of @code{makeinfo} you are using,
13902type:@refill
13903
13904@example
13905makeinfo --version
13906@end example
13907
13908@xref{makeinfo options}, for more information.
13909@end ifinfo
13910
13911
13912@node makeinfo options
|
13797@comment node-name, next, previous, up
| |
13798@subsection Options for @code{makeinfo}
13799@cindex @code{makeinfo} options
13800@cindex Options for @code{makeinfo}
13801
13802The @code{makeinfo} command takes a number of options. Most often,
13803options are used to set the value of the fill column and specify the
13804footnote style. Each command line option is a word preceded by
13805@samp{--} or a letter preceded by @samp{-}. You can use abbreviations
13806for the long option names as long as they are unique.@refill
13807
13808For example, you could use the following shell command to create an Info
13809file for @file{bison.texinfo} in which each line is filled to only 68
13810columns:@refill
13811
13812@example
13813makeinfo --fill-column=68 bison.texinfo
13814@end example
13815
13816You can write two or more options in sequence, like this:@refill
13817
13818@example
13819makeinfo --no-split --fill-column=70 @dots{}
13820@end example
13821
13822@noindent
13823This would keep the Info file together as one possibly very long
13824file and would also set the fill column to 70.@refill
13825
13826The options are:
13827
13828@table @code
13829
13830@item -D @var{var}
13831@opindex -D @var{var}
13832Cause the variable @var{var} to be defined. This is equivalent to
13833@code{@@set @var{var}} in the Texinfo file (@pxref{set clear value}).
13834
13835@item --commands-in-node-names
13836@opindex --commands-in-node-names
13837Allow @code{@@}-commands in node names. This is not recommended, as it
13838can probably never be implemented in @TeX{}. It also makes
13839@code{makeinfo} much slower. Also, this option is ignored when
13840@samp{--no-validate} is used. @xref{Pointer Validation}, for more
13841details.
13842
13843@item --docbook
13844@opindex --docbook
13845Generate DocBook output rather than Info.
13846
13847@item --error-limit=@var{limit}
13848@itemx -e @var{limit}
13849@opindex --error-limit=@var{limit}
13850@opindex -e @var{limit}
13851Set the maximum number of errors that @code{makeinfo} will report
13852before exiting (on the assumption that continuing would be useless);
13853default 100.
13854
13855@item --fill-column=@var{width}
13856@itemx -f @var{width}
13857@opindex --fill-column=@var{width}
13858@opindex -f @var{width}
13859Specify the maximum number of columns in a line; this is the right-hand
13860edge of a line. Paragraphs that are filled will be filled to this
13861width. (Filling is the process of breaking up and connecting lines so
13862that lines are the same length as or shorter than the number specified
13863as the fill column. Lines are broken between words.) The default value
13864is 72. Ignored with @samp{--html}.
13865
13866@item --footnote-style=@var{style}
13867@itemx -s @var{style}
13868@opindex --footnote-style=@var{style}
13869@opindex -s @var{style}
13870Set the footnote style to @var{style}, either @samp{end} for the end
13871node style (the default) or @samp{separate} for the separate node style.
13872The value set by this option overrides the value set in a Texinfo file
13873by an @code{@@footnotestyle} command (@pxref{Footnotes}). When the
13874footnote style is @samp{separate}, @code{makeinfo} makes a new node
13875containing the footnotes found in the current node. When the footnote
13876style is @samp{end}, @code{makeinfo} places the footnote references at
13877the end of the current node. Ignored with @samp{--html}.
13878
13879@item --force
13880@itemx -F
13881@opindex --force
13882@opindex -F
13883Ordinarily, if the input file has errors, the output files are not
13884created. With this option, they are preserved.
13885
13886@item --help
13887@itemx -h
13888@opindex --help
13889@opindex -h
13890Print a usage message listing all available options, then exit successfully.
13891
13892@item --html
13893@opindex --html
13894Generate HTML output rather than Info. @xref{makeinfo html}. By
13895default, the HTML output is split into one output file per source node,
13896and the split output is written into a subdirectory with the name of the
13897top-level info file.
13898
13899@item -I @var{dir}
13900@opindex -I @var{dir}
13901Append @var{dir} to the directory search list for finding files that
13902are included using the @code{@@include} command. By default,
13903@code{makeinfo} searches only the current directory. If @var{dir} is
13904not given, the current directory @file{.} is appended. Note that
13905@var{dir} can actually be a list of several directories separated by the
13906usual path separator character (@samp{:} on Unix, @samp{;} on
13907MS-DOS/MS-Windows).
13908
13909@item --macro-expand=@var{file}
13910@itemx -E @var{file}
13911Output the Texinfo source with all the macros expanded to the named
13912file. Normally, the results of macro expansion are used internally by
13913@code{makeinfo} and then discarded. This option is used by
13914@command{texi2dvi} if you are using an old version of @file{texinfo.tex}
13915that does not support @code{@@macro}.
13916
13917@item --no-headers
13918@opindex --no-headers
13919@cindex Plain text output
13920@cindex ASCII text output
13921@cindex Generating plain text files
13922@cindex @file{INSTALL} file, generating
| 13913@subsection Options for @code{makeinfo}
13914@cindex @code{makeinfo} options
13915@cindex Options for @code{makeinfo}
13916
13917The @code{makeinfo} command takes a number of options. Most often,
13918options are used to set the value of the fill column and specify the
13919footnote style. Each command line option is a word preceded by
13920@samp{--} or a letter preceded by @samp{-}. You can use abbreviations
13921for the long option names as long as they are unique.@refill
13922
13923For example, you could use the following shell command to create an Info
13924file for @file{bison.texinfo} in which each line is filled to only 68
13925columns:@refill
13926
13927@example
13928makeinfo --fill-column=68 bison.texinfo
13929@end example
13930
13931You can write two or more options in sequence, like this:@refill
13932
13933@example
13934makeinfo --no-split --fill-column=70 @dots{}
13935@end example
13936
13937@noindent
13938This would keep the Info file together as one possibly very long
13939file and would also set the fill column to 70.@refill
13940
13941The options are:
13942
13943@table @code
13944
13945@item -D @var{var}
13946@opindex -D @var{var}
13947Cause the variable @var{var} to be defined. This is equivalent to
13948@code{@@set @var{var}} in the Texinfo file (@pxref{set clear value}).
13949
13950@item --commands-in-node-names
13951@opindex --commands-in-node-names
13952Allow @code{@@}-commands in node names. This is not recommended, as it
13953can probably never be implemented in @TeX{}. It also makes
13954@code{makeinfo} much slower. Also, this option is ignored when
13955@samp{--no-validate} is used. @xref{Pointer Validation}, for more
13956details.
13957
13958@item --docbook
13959@opindex --docbook
13960Generate DocBook output rather than Info.
13961
13962@item --error-limit=@var{limit}
13963@itemx -e @var{limit}
13964@opindex --error-limit=@var{limit}
13965@opindex -e @var{limit}
13966Set the maximum number of errors that @code{makeinfo} will report
13967before exiting (on the assumption that continuing would be useless);
13968default 100.
13969
13970@item --fill-column=@var{width}
13971@itemx -f @var{width}
13972@opindex --fill-column=@var{width}
13973@opindex -f @var{width}
13974Specify the maximum number of columns in a line; this is the right-hand
13975edge of a line. Paragraphs that are filled will be filled to this
13976width. (Filling is the process of breaking up and connecting lines so
13977that lines are the same length as or shorter than the number specified
13978as the fill column. Lines are broken between words.) The default value
13979is 72. Ignored with @samp{--html}.
13980
13981@item --footnote-style=@var{style}
13982@itemx -s @var{style}
13983@opindex --footnote-style=@var{style}
13984@opindex -s @var{style}
13985Set the footnote style to @var{style}, either @samp{end} for the end
13986node style (the default) or @samp{separate} for the separate node style.
13987The value set by this option overrides the value set in a Texinfo file
13988by an @code{@@footnotestyle} command (@pxref{Footnotes}). When the
13989footnote style is @samp{separate}, @code{makeinfo} makes a new node
13990containing the footnotes found in the current node. When the footnote
13991style is @samp{end}, @code{makeinfo} places the footnote references at
13992the end of the current node. Ignored with @samp{--html}.
13993
13994@item --force
13995@itemx -F
13996@opindex --force
13997@opindex -F
13998Ordinarily, if the input file has errors, the output files are not
13999created. With this option, they are preserved.
14000
14001@item --help
14002@itemx -h
14003@opindex --help
14004@opindex -h
14005Print a usage message listing all available options, then exit successfully.
14006
14007@item --html
14008@opindex --html
14009Generate HTML output rather than Info. @xref{makeinfo html}. By
14010default, the HTML output is split into one output file per source node,
14011and the split output is written into a subdirectory with the name of the
14012top-level info file.
14013
14014@item -I @var{dir}
14015@opindex -I @var{dir}
14016Append @var{dir} to the directory search list for finding files that
14017are included using the @code{@@include} command. By default,
14018@code{makeinfo} searches only the current directory. If @var{dir} is
14019not given, the current directory @file{.} is appended. Note that
14020@var{dir} can actually be a list of several directories separated by the
14021usual path separator character (@samp{:} on Unix, @samp{;} on
14022MS-DOS/MS-Windows).
14023
14024@item --macro-expand=@var{file}
14025@itemx -E @var{file}
14026Output the Texinfo source with all the macros expanded to the named
14027file. Normally, the results of macro expansion are used internally by
14028@code{makeinfo} and then discarded. This option is used by
14029@command{texi2dvi} if you are using an old version of @file{texinfo.tex}
14030that does not support @code{@@macro}.
14031
14032@item --no-headers
14033@opindex --no-headers
14034@cindex Plain text output
14035@cindex ASCII text output
14036@cindex Generating plain text files
14037@cindex @file{INSTALL} file, generating
|
13923For Info output, do not include menus or node lines in the output and
13924write to standard output (unless @option{--output} is specified). This
13925results in an @sc{ascii} file that you cannot read in Info since it does
13926not contain the requisite nodes or menus. It is primarily useful to
13927extract certain pieces of a manual into separate files to be included in
13928a distribution, such as @file{INSTALL} files.
| 14038@cindex Node separators, omitting
14039@cindex Menus, omitting
14040For Info output, do not include menus or node separator lines in the
14041output. This results in a simple plain text file that you can (for
14042example) send in email without complications, or include in a
14043distribution (as in an @file{INSTALL} file).
|
13929
13930@cindex Navigation links, omitting
| 14044
14045@cindex Navigation links, omitting
|
13931For HTML output, if @samp{--no-split} is also specified, do not include a
13932navigation links at the top of each node. @xref{makeinfo html}.
| 14046For HTML output, likewise omit menus. And if @samp{--no-split} is also
14047specified, do not include a navigation links at the top of each node
14048(these are never included in the default case of split output).
14049@xref{makeinfo html}.
|
13933
| 14050
|
| 14051In both cases, write to standard output by default (can still be
14052overridden by @option{-o}).
14053
|
13934@item --no-split
13935@opindex --no-split
13936@cindex Splitting of output files
13937@cindex Output file splitting
13938Suppress the splitting stage of @code{makeinfo}. By default, large
13939output files (where the size is greater than 70k bytes) are split into
13940smaller subfiles. For Info output, each one is approximately 50k bytes.
13941For HTML output, each file contains one node (@pxref{makeinfo html}).
13942
13943@item --no-pointer-validate
13944@itemx --no-validate
13945@opindex --no-pointer-validate
13946@opindex --no-validate
13947@cindex Pointer validation, suppressing
13948Suppress the pointer-validation phase of @code{makeinfo}. This can also
13949be done with the @code{@@novalidate} command (@pxref{Use TeX,,Use
13950@TeX{}}). Normally, after a Texinfo file is processed, some consistency
13951checks are made to ensure that cross references can be resolved, etc.
13952@xref{Pointer Validation}.
13953
13954@item --no-warn
13955@opindex --no-warn
13956Suppress warning messages (but @emph{not} error messages). You might
13957want this if the file you are creating has examples of Texinfo cross
13958references within it, and the nodes that are referenced do not actually
13959exist.
13960
13961@item --number-sections
13962@opindex --number-sections
13963Output chapter, section, and appendix numbers as in printed manuals.
13964
13965@item --no-number-footnotes
13966@opindex --no-number-footnotes
13967Suppress automatic footnote numbering. By default, @code{makeinfo}
13968numbers each footnote sequentially in a single node, resetting the
13969current footnote number to 1 at the start of each node.
13970
13971@item --output=@var{file}
13972@itemx -o @var{file}
13973@opindex --output=@var{file}
13974@opindex -o @var{file}
13975Specify that the output should be directed to @var{file} and not to the
13976file name specified in the @code{@@setfilename} command found in the
13977Texinfo source (@pxref{setfilename}). If @var{file} is @samp{-}, output
13978goes to standard output and @samp{--no-split} is implied. For split
13979HTML output, @var{file} is the name for the directory into which all
13980HTML nodes are written (@pxref{makeinfo html}).
13981
13982@item -P @var{dir}
13983@opindex -P @var{dir}
13984Prepend @var{dir} to the directory search list for @code{@@include}.
13985If @var{dir} is not given, the current directory @file{.} is prepended.
13986See @samp{-I} for more details.
13987
13988@item --paragraph-indent=@var{indent}
13989@itemx -p @var{indent}
13990@opindex --paragraph-indent=@var{indent}
13991@opindex -p @var{indent}
13992Set the paragraph indentation style to @var{indent}. The value set by
13993this option overrides the value set in a Texinfo file by an
13994@code{@@paragraphindent} command (@pxref{paragraphindent}). The value
13995of @var{indent} is interpreted as follows:
13996
13997@table @asis
13998@item @samp{asis}
13999Preserve any existing indentation at the starts of paragraphs.
14000
14001@item @samp{0} or @samp{none}
14002Delete any existing indentation.
14003
14004@item @var{num}
14005Indent each paragraph by @var{num} spaces.
14006@end table
14007
14008@item --reference-limit=@var{limit}
14009@itemx -r @var{limit}
14010@opindex --reference-limit=@var{limit}
14011@opindex -r @var{limit}
14012Set the value of the number of references to a node that
14013@code{makeinfo} will make without reporting a warning. If a node has more
14014than this number of references in it, @code{makeinfo} will make the
14015references but also report a warning. The default is 1000.
14016
14017@item -U @var{var}
14018Cause @var{var} to be undefined. This is equivalent to
14019@code{@@clear @var{var}} in the Texinfo file (@pxref{set clear value}).
14020
14021@item --verbose
14022@opindex --verbose
14023Cause @code{makeinfo} to display messages saying what it is doing.
14024Normally, @code{makeinfo} only outputs messages if there are errors or
14025warnings.
14026
14027@item --version
14028@itemx -V
14029@opindex --version
14030@opindex -V
14031Print the version number, then exit successfully.
14032
14033@item --xml
14034@opindex --xml
14035Generate XML output rather than Info.
14036
14037@end table
14038
14039
14040@node Pointer Validation
14041@subsection Pointer Validation
14042@cindex Pointer validation with @code{makeinfo}
14043@cindex Validation of pointers
14044
14045If you do not suppress pointer validation with the @samp{--no-validate}
14046option or the @code{@@novalidate} command in the source file (@pxref{Use
14047TeX,,Use @TeX{}}), @code{makeinfo} will check the validity of the final
14048Info file. Mostly, this means ensuring that nodes you have referenced
14049really exist. Here is a complete list of what is checked:
14050
14051@enumerate
14052@item
14053If a `Next', `Previous', or `Up' node reference is a reference to a
14054node in the current file and is not an external reference such as to
14055@file{(dir)}, then the referenced node must exist.@refill
14056
14057@item
14058In every node, if the `Previous' node is different from the `Up' node,
14059then the node pointed to by the `Previous' field must have a `Next'
14060field which points back to this node.@refill
14061
14062@item
14063Every node except the `Top' node must have an `Up' pointer.@refill
14064
14065@item
14066The node referenced by an `Up' pointer must itself reference the current
14067node through a menu item, unless the node referenced by `Up'
14068has the form `(@var{file})'.
14069
14070@item
14071If the `Next' reference of a node is not the same as the `Next' reference
14072of the `Up' reference, then the node referenced by the `Next' pointer
14073must have a `Previous' pointer that points back to the current node.
14074This rule allows the last node in a section to point to the first node
14075of the next chapter.@refill
14076
14077@item
14078Every node except `Top' should be referenced by at least one other node,
14079either via the `Previous' or `Next' links, or via a menu or a
14080cross-reference.@refill
14081@end enumerate
14082
14083@cindex @@-commands in @@node, limited support
14084Some Texinfo documents might fail during the validation phase because
14085they use commands like @code{@@value} and @code{@@definfoenclose} in
14086node definitions and cross-references inconsistently. Consider the
14087following example:
14088
14089@example
14090@group
14091@@set nodename Node 1
14092
14093@@node @@value@{nodename@}, Node 2, Top, Top
14094
14095This is node 1.
14096
14097@@node Node 2, , Node 1, Top
14098
14099This is node 2.
14100@end group
14101@end example
14102
14103@noindent
14104Here, the node ``Node 1'' was referenced both verbatim and through
14105@code{@@value}.
14106
14107By default, @code{makeinfo} fails such cases, because node names are not
14108fully expanded until they are written to the output file. You should
14109always try to reference nodes consistently; e.g., in the above example,
14110the second @code{@@node} line should have also used @code{@@value}.
14111However, if, for some reason, you @emph{must} reference node names
14112inconsistently, and @code{makeinfo} fails to validate the file, you can
14113use the @samp{--commands-in-node-names} option to force @code{makeinfo}
14114to perform the expensive expansion of all node names it finds in the
14115document. This might considerably slow down the program, though;
14116twofold increase in conversion time was measured for large documents
14117such as the Jargon file.
14118
14119@cindex @@value in @@node lines
14120The support for @code{@@}-commands in @code{@@node} directives is not
14121general enough to be freely used. For example, if the example above
14122redefined @code{nodename} somewhere in the document, @code{makeinfo}
14123will fail to convert it, even if invoked with the
14124@samp{--commands-in-node-names} option.
14125
14126@samp{--commands-in-node-names} has no effect if the @samp{--no-validate}
14127option is given.
14128
14129
14130@node makeinfo in Emacs
14131@subsection Running @code{makeinfo} inside Emacs
14132@cindex Running @code{makeinfo} in Emacs
14133@cindex @code{makeinfo} inside Emacs
14134@cindex Shell, running @code{makeinfo} in
14135
14136You can run @code{makeinfo} in GNU Emacs Texinfo mode by using either the
14137@code{makeinfo-region} or the @code{makeinfo-buffer} commands. In
14138Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c
14139C-m C-b} by default.@refill
14140
14141@table @kbd
14142@item C-c C-m C-r
14143@itemx M-x makeinfo-region
14144Format the current region for Info.@refill
14145@findex makeinfo-region
14146
14147@item C-c C-m C-b
14148@itemx M-x makeinfo-buffer
14149Format the current buffer for Info.@refill
14150@findex makeinfo-buffer
14151@end table
14152
14153When you invoke either @code{makeinfo-region} or
14154@code{makeinfo-buffer}, Emacs prompts for a file name, offering the
14155name of the visited file as the default. You can edit the default
14156file name in the minibuffer if you wish, before pressing @key{RET} to
14157start the @code{makeinfo} process.@refill
14158
14159The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands
14160run the @code{makeinfo} program in a temporary shell buffer. If
14161@code{makeinfo} finds any errors, Emacs displays the error messages in
14162the temporary buffer.@refill
14163
14164@cindex Errors, parsing
14165@cindex Parsing errors
14166@findex next-error
14167You can parse the error messages by typing @kbd{C-x `}
14168(@code{next-error}). This causes Emacs to go to and position the
14169cursor on the line in the Texinfo source that @code{makeinfo} thinks
14170caused the error. @xref{Compilation, , Running @code{make} or
14171Compilers Generally, emacs, The GNU Emacs Manual}, for more
14172information about using the @code{next-error} command.@refill
14173
14174In addition, you can kill the shell in which the @code{makeinfo}
14175command is running or make the shell buffer display its most recent
14176output.@refill
14177
14178@table @kbd
14179@item C-c C-m C-k
14180@itemx M-x makeinfo-kill-job
14181@findex makeinfo-kill-job
14182Kill the current running @code{makeinfo} job
14183(from @code{makeinfo-region} or @code{makeinfo-buffer}).@refill
14184
14185@item C-c C-m C-l
14186@itemx M-x makeinfo-recenter-output-buffer
14187@findex makeinfo-recenter-output-buffer
14188Redisplay the @code{makeinfo} shell buffer to display its most recent
14189output.@refill
14190@end table
14191
14192@noindent
14193(Note that the parallel commands for killing and recentering a @TeX{}
14194job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode
14195Printing}.)@refill
14196
14197You can specify options for @code{makeinfo} by setting the
14198@code{makeinfo-options} variable with either the @kbd{M-x
14199edit-options} or the @kbd{M-x set-variable} command, or by setting the
14200variable in your @file{.emacs} initialization file.@refill
14201
14202For example, you could write the following in your @file{.emacs} file:@refill
14203
14204@example
14205@group
14206(setq makeinfo-options
14207 "--paragraph-indent=0 --no-split
14208 --fill-column=70 --verbose")
14209@end group
14210@end example
14211
14212@c If you write these three cross references using xref, you see
14213@c three references to the same named manual, which looks strange.
14214@iftex
14215For more information, see @ref{makeinfo options, , Options for
14216@code{makeinfo}}, as well as ``Editing Variable Values,'' ``Examining
14217and Setting Variables,'' and ``Init File'' in @cite{The GNU Emacs
14218Manual}.
14219@end iftex
14220@noindent
14221@ifinfo
14222For more information, see@*
14223@ref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs Manual},@*
14224@ref{Examining, , Examining and Setting Variables, emacs, The GNU Emacs Manual},@*
14225@ref{Init File, , , emacs, The GNU Emacs Manual}, and@*
14226@ref{makeinfo options, , Options for @code{makeinfo}}.
14227@end ifinfo
14228
14229@node texinfo-format commands
14230@comment node-name, next, previous, up
14231@subsection The @code{texinfo-format@dots{}} Commands
14232@findex texinfo-format-region
14233@findex texinfo-format-buffer
14234
14235In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
14236file with the @code{texinfo-format-region} command. This formats the
14237current region and displays the formatted text in a temporary buffer
14238called @samp{*Info Region*}.@refill
14239
14240Similarly, you can format a buffer with the
14241@code{texinfo-format-buffer} command. This command creates a new
14242buffer and generates the Info file in it. Typing @kbd{C-x C-s} will
14243save the Info file under the name specified by the
14244@code{@@setfilename} line which must be near the beginning of the
14245Texinfo file.@refill
14246
14247@table @kbd
14248@item C-c C-e C-r
14249@itemx @code{texinfo-format-region}
14250Format the current region for Info.
14251@findex texinfo-format-region
14252
14253@item C-c C-e C-b
14254@itemx @code{texinfo-format-buffer}
14255Format the current buffer for Info.
14256@findex texinfo-format-buffer
14257@end table
14258
14259The @code{texinfo-format-region} and @code{texinfo-format-buffer}
14260commands provide you with some error checking, and other functions can
14261provide you with further help in finding formatting errors. These
14262procedures are described in an appendix; see @ref{Catching Mistakes}.
14263However, the @code{makeinfo} program is often faster and
14264provides better error checking (@pxref{makeinfo in Emacs}).@refill
14265
14266@node Batch Formatting
14267@comment node-name, next, previous, up
14268@subsection Batch Formatting
14269@cindex Batch formatting for Info
14270@cindex Info batch formatting
14271
14272You can format Texinfo files for Info using @code{batch-texinfo-format}
14273and Emacs Batch mode. You can run Emacs in Batch mode from any shell,
14274including a shell inside of Emacs. (@xref{Command Switches, , Command
14275Line Switches and Arguments, emacs, The GNU Emacs Manual}.)@refill
14276
14277Here is a shell command to format all the files that end in
14278@file{.texinfo} in the current directory:
14279
14280@example
14281emacs -batch -funcall batch-texinfo-format *.texinfo
14282@end example
14283
14284@noindent
14285Emacs processes all the files listed on the command line, even if an
14286error occurs while attempting to format some of them.@refill
14287
14288Run @code{batch-texinfo-format} only with Emacs in Batch mode as shown;
14289it is not interactive. It kills the Batch mode Emacs on completion.@refill
14290
14291@code{batch-texinfo-format} is convenient if you lack @code{makeinfo}
14292and want to format several Texinfo files at once. When you use Batch
14293mode, you create a new Emacs process. This frees your current Emacs, so
14294you can continue working in it. (When you run
14295@code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot
14296use that Emacs for anything else until the command finishes.)@refill
14297
14298@node Tag and Split Files
14299@comment node-name, next, previous, up
14300@subsection Tag Files and Split Files
14301@cindex Making a tag table automatically
14302@cindex Tag table, making automatically
14303
14304If a Texinfo file has more than 30,000 bytes,
14305@code{texinfo-format-buffer} automatically creates a tag table
14306for its Info file; @code{makeinfo} always creates a tag table. With
14307a @dfn{tag table}, Info can jump to new nodes more quickly than it can
14308otherwise.@refill
14309
14310@cindex Indirect subfiles
14311In addition, if the Texinfo file contains more than about 70,000
14312bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the
14313large Info file into shorter @dfn{indirect} subfiles of about 50,000
14314bytes each. Big files are split into smaller files so that Emacs does
14315not need to make a large buffer to hold the whole of a large Info
14316file; instead, Emacs allocates just enough memory for the small, split-off
14317file that is needed at the time. This way, Emacs avoids wasting
14318memory when you run Info. (Before splitting was implemented, Info
14319files were always kept short and @dfn{include files} were designed as
14320a way to create a single, large printed manual out of the smaller Info
14321files. @xref{Include Files}, for more information. Include files are
14322still used for very large documents, such as @cite{The Emacs Lisp
14323Reference Manual}, in which each chapter is a separate file.)@refill
14324
14325When a file is split, Info itself makes use of a shortened version of
14326the original file that contains just the tag table and references to
14327the files that were split off. The split-off files are called
14328@dfn{indirect} files.@refill
14329
14330The split-off files have names that are created by appending @w{@samp{-1}},
14331@w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the
14332@code{@@setfilename} command. The shortened version of the original file
14333continues to have the name specified by @code{@@setfilename}.@refill
14334
14335At one stage in writing this document, for example, the Info file was saved
14336as the file @file{test-texinfo} and that file looked like this:@refill
14337
14338@example
14339@group
14340Info file: test-texinfo, -*-Text-*-
14341produced by texinfo-format-buffer
14342from file: new-texinfo-manual.texinfo
14343
14344^_
14345Indirect:
14346test-texinfo-1: 102
14347test-texinfo-2: 50422
14348@end group
14349@group
14350test-texinfo-3: 101300
14351^_^L
14352Tag table:
14353(Indirect)
14354Node: overview^?104
14355Node: info file^?1271
14356@end group
14357@group
14358Node: printed manual^?4853
14359Node: conventions^?6855
14360@dots{}
14361@end group
14362@end example
14363
14364@noindent
14365(But @file{test-texinfo} had far more nodes than are shown here.) Each of
14366the split-off, indirect files, @file{test-texinfo-1},
14367@file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file
14368after the line that says @samp{Indirect:}. The tag table is listed after
14369the line that says @samp{Tag table:}. @refill
14370
14371In the list of indirect files, the number following the file name
14372records the cumulative number of bytes in the preceding indirect files,
14373not counting the file list itself, the tag table, or the permissions
14374text in each file. In the tag table, the number following the node name
14375records the location of the beginning of the node, in bytes from the
14376beginning of the (unsplit) output.
14377
14378If you are using @code{texinfo-format-buffer} to create Info files,
14379you may want to run the @code{Info-validate} command. (The
14380@code{makeinfo} command does such a good job on its own, you do not
14381need @code{Info-validate}.) However, you cannot run the @kbd{M-x
14382Info-validate} node-checking command on indirect files. For
14383information on how to prevent files from being split and how to
14384validate the structure of the nodes, see @ref{Using
14385Info-validate}.@refill
14386
14387
14388@node makeinfo html
14389@subsection Generating HTML
14390@cindex HTML
14391
14392Besides generating output in the Info format, you can use the
14393@samp{--html} option to generate output in HTML format, for installation
14394on a web site (for example). By default, the HTML output is split at
14395node level.
14396
14397When splitting, the HTML output files are written into a subdirectory.
14398The subdirectory is named according to the name from
14399@code{@@setfilename} with any extension removed; for example, HTML
14400output for @code{@@setfilename emacs.info} would be written into a
14401subdirectory named @samp{emacs}. If that directory cannot be created
14402for any reason, then @samp{.html} is appended to the directory name, as
14403in @samp{emacs.html} (this is necessary because sometimes the info file
14404is named without an extension, e.g., @samp{texinfo}). If the
14405@samp{@var{name}.html} directory can't be created either,
14406@code{makeinfo} gives up. In any case, the top-level output file within
14407the directory is always named @samp{index.html}.
14408
14409Monolithic output (@code{--no-split}) is named according to
14410@code{@@setfilename} or @code{--outfile}. Cross-document node
14411references are not supported in monolithic HTML.
14412
14413Texinfo input marked up with the @code{@@ifhtml} command will produce
14414output only with the @samp{--html} option supplied. Input marked up
14415with the @code{@@html} is passed literally to the output (suppressing
14416the normal escaping of input @samp{<}, @samp{>} and @samp{&} characters
14417which have special significance in HTML).
14418
14419The @samp{--footnote-style} option is currently ignored for HTML output;
14420footnotes are linked to the end of the output file.
14421
14422The HTML generated is mostly standard (i.e., HTML 2.0, RFC-1866). The
14423exception is that HTML 3.2 tables are generated from the
14424@code{@@multitable} command, but tagged to degrade as well as possible
| 14054@item --no-split
14055@opindex --no-split
14056@cindex Splitting of output files
14057@cindex Output file splitting
14058Suppress the splitting stage of @code{makeinfo}. By default, large
14059output files (where the size is greater than 70k bytes) are split into
14060smaller subfiles. For Info output, each one is approximately 50k bytes.
14061For HTML output, each file contains one node (@pxref{makeinfo html}).
14062
14063@item --no-pointer-validate
14064@itemx --no-validate
14065@opindex --no-pointer-validate
14066@opindex --no-validate
14067@cindex Pointer validation, suppressing
14068Suppress the pointer-validation phase of @code{makeinfo}. This can also
14069be done with the @code{@@novalidate} command (@pxref{Use TeX,,Use
14070@TeX{}}). Normally, after a Texinfo file is processed, some consistency
14071checks are made to ensure that cross references can be resolved, etc.
14072@xref{Pointer Validation}.
14073
14074@item --no-warn
14075@opindex --no-warn
14076Suppress warning messages (but @emph{not} error messages). You might
14077want this if the file you are creating has examples of Texinfo cross
14078references within it, and the nodes that are referenced do not actually
14079exist.
14080
14081@item --number-sections
14082@opindex --number-sections
14083Output chapter, section, and appendix numbers as in printed manuals.
14084
14085@item --no-number-footnotes
14086@opindex --no-number-footnotes
14087Suppress automatic footnote numbering. By default, @code{makeinfo}
14088numbers each footnote sequentially in a single node, resetting the
14089current footnote number to 1 at the start of each node.
14090
14091@item --output=@var{file}
14092@itemx -o @var{file}
14093@opindex --output=@var{file}
14094@opindex -o @var{file}
14095Specify that the output should be directed to @var{file} and not to the
14096file name specified in the @code{@@setfilename} command found in the
14097Texinfo source (@pxref{setfilename}). If @var{file} is @samp{-}, output
14098goes to standard output and @samp{--no-split} is implied. For split
14099HTML output, @var{file} is the name for the directory into which all
14100HTML nodes are written (@pxref{makeinfo html}).
14101
14102@item -P @var{dir}
14103@opindex -P @var{dir}
14104Prepend @var{dir} to the directory search list for @code{@@include}.
14105If @var{dir} is not given, the current directory @file{.} is prepended.
14106See @samp{-I} for more details.
14107
14108@item --paragraph-indent=@var{indent}
14109@itemx -p @var{indent}
14110@opindex --paragraph-indent=@var{indent}
14111@opindex -p @var{indent}
14112Set the paragraph indentation style to @var{indent}. The value set by
14113this option overrides the value set in a Texinfo file by an
14114@code{@@paragraphindent} command (@pxref{paragraphindent}). The value
14115of @var{indent} is interpreted as follows:
14116
14117@table @asis
14118@item @samp{asis}
14119Preserve any existing indentation at the starts of paragraphs.
14120
14121@item @samp{0} or @samp{none}
14122Delete any existing indentation.
14123
14124@item @var{num}
14125Indent each paragraph by @var{num} spaces.
14126@end table
14127
14128@item --reference-limit=@var{limit}
14129@itemx -r @var{limit}
14130@opindex --reference-limit=@var{limit}
14131@opindex -r @var{limit}
14132Set the value of the number of references to a node that
14133@code{makeinfo} will make without reporting a warning. If a node has more
14134than this number of references in it, @code{makeinfo} will make the
14135references but also report a warning. The default is 1000.
14136
14137@item -U @var{var}
14138Cause @var{var} to be undefined. This is equivalent to
14139@code{@@clear @var{var}} in the Texinfo file (@pxref{set clear value}).
14140
14141@item --verbose
14142@opindex --verbose
14143Cause @code{makeinfo} to display messages saying what it is doing.
14144Normally, @code{makeinfo} only outputs messages if there are errors or
14145warnings.
14146
14147@item --version
14148@itemx -V
14149@opindex --version
14150@opindex -V
14151Print the version number, then exit successfully.
14152
14153@item --xml
14154@opindex --xml
14155Generate XML output rather than Info.
14156
14157@end table
14158
14159
14160@node Pointer Validation
14161@subsection Pointer Validation
14162@cindex Pointer validation with @code{makeinfo}
14163@cindex Validation of pointers
14164
14165If you do not suppress pointer validation with the @samp{--no-validate}
14166option or the @code{@@novalidate} command in the source file (@pxref{Use
14167TeX,,Use @TeX{}}), @code{makeinfo} will check the validity of the final
14168Info file. Mostly, this means ensuring that nodes you have referenced
14169really exist. Here is a complete list of what is checked:
14170
14171@enumerate
14172@item
14173If a `Next', `Previous', or `Up' node reference is a reference to a
14174node in the current file and is not an external reference such as to
14175@file{(dir)}, then the referenced node must exist.@refill
14176
14177@item
14178In every node, if the `Previous' node is different from the `Up' node,
14179then the node pointed to by the `Previous' field must have a `Next'
14180field which points back to this node.@refill
14181
14182@item
14183Every node except the `Top' node must have an `Up' pointer.@refill
14184
14185@item
14186The node referenced by an `Up' pointer must itself reference the current
14187node through a menu item, unless the node referenced by `Up'
14188has the form `(@var{file})'.
14189
14190@item
14191If the `Next' reference of a node is not the same as the `Next' reference
14192of the `Up' reference, then the node referenced by the `Next' pointer
14193must have a `Previous' pointer that points back to the current node.
14194This rule allows the last node in a section to point to the first node
14195of the next chapter.@refill
14196
14197@item
14198Every node except `Top' should be referenced by at least one other node,
14199either via the `Previous' or `Next' links, or via a menu or a
14200cross-reference.@refill
14201@end enumerate
14202
14203@cindex @@-commands in @@node, limited support
14204Some Texinfo documents might fail during the validation phase because
14205they use commands like @code{@@value} and @code{@@definfoenclose} in
14206node definitions and cross-references inconsistently. Consider the
14207following example:
14208
14209@example
14210@group
14211@@set nodename Node 1
14212
14213@@node @@value@{nodename@}, Node 2, Top, Top
14214
14215This is node 1.
14216
14217@@node Node 2, , Node 1, Top
14218
14219This is node 2.
14220@end group
14221@end example
14222
14223@noindent
14224Here, the node ``Node 1'' was referenced both verbatim and through
14225@code{@@value}.
14226
14227By default, @code{makeinfo} fails such cases, because node names are not
14228fully expanded until they are written to the output file. You should
14229always try to reference nodes consistently; e.g., in the above example,
14230the second @code{@@node} line should have also used @code{@@value}.
14231However, if, for some reason, you @emph{must} reference node names
14232inconsistently, and @code{makeinfo} fails to validate the file, you can
14233use the @samp{--commands-in-node-names} option to force @code{makeinfo}
14234to perform the expensive expansion of all node names it finds in the
14235document. This might considerably slow down the program, though;
14236twofold increase in conversion time was measured for large documents
14237such as the Jargon file.
14238
14239@cindex @@value in @@node lines
14240The support for @code{@@}-commands in @code{@@node} directives is not
14241general enough to be freely used. For example, if the example above
14242redefined @code{nodename} somewhere in the document, @code{makeinfo}
14243will fail to convert it, even if invoked with the
14244@samp{--commands-in-node-names} option.
14245
14246@samp{--commands-in-node-names} has no effect if the @samp{--no-validate}
14247option is given.
14248
14249
14250@node makeinfo in Emacs
14251@subsection Running @code{makeinfo} inside Emacs
14252@cindex Running @code{makeinfo} in Emacs
14253@cindex @code{makeinfo} inside Emacs
14254@cindex Shell, running @code{makeinfo} in
14255
14256You can run @code{makeinfo} in GNU Emacs Texinfo mode by using either the
14257@code{makeinfo-region} or the @code{makeinfo-buffer} commands. In
14258Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c
14259C-m C-b} by default.@refill
14260
14261@table @kbd
14262@item C-c C-m C-r
14263@itemx M-x makeinfo-region
14264Format the current region for Info.@refill
14265@findex makeinfo-region
14266
14267@item C-c C-m C-b
14268@itemx M-x makeinfo-buffer
14269Format the current buffer for Info.@refill
14270@findex makeinfo-buffer
14271@end table
14272
14273When you invoke either @code{makeinfo-region} or
14274@code{makeinfo-buffer}, Emacs prompts for a file name, offering the
14275name of the visited file as the default. You can edit the default
14276file name in the minibuffer if you wish, before pressing @key{RET} to
14277start the @code{makeinfo} process.@refill
14278
14279The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands
14280run the @code{makeinfo} program in a temporary shell buffer. If
14281@code{makeinfo} finds any errors, Emacs displays the error messages in
14282the temporary buffer.@refill
14283
14284@cindex Errors, parsing
14285@cindex Parsing errors
14286@findex next-error
14287You can parse the error messages by typing @kbd{C-x `}
14288(@code{next-error}). This causes Emacs to go to and position the
14289cursor on the line in the Texinfo source that @code{makeinfo} thinks
14290caused the error. @xref{Compilation, , Running @code{make} or
14291Compilers Generally, emacs, The GNU Emacs Manual}, for more
14292information about using the @code{next-error} command.@refill
14293
14294In addition, you can kill the shell in which the @code{makeinfo}
14295command is running or make the shell buffer display its most recent
14296output.@refill
14297
14298@table @kbd
14299@item C-c C-m C-k
14300@itemx M-x makeinfo-kill-job
14301@findex makeinfo-kill-job
14302Kill the current running @code{makeinfo} job
14303(from @code{makeinfo-region} or @code{makeinfo-buffer}).@refill
14304
14305@item C-c C-m C-l
14306@itemx M-x makeinfo-recenter-output-buffer
14307@findex makeinfo-recenter-output-buffer
14308Redisplay the @code{makeinfo} shell buffer to display its most recent
14309output.@refill
14310@end table
14311
14312@noindent
14313(Note that the parallel commands for killing and recentering a @TeX{}
14314job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode
14315Printing}.)@refill
14316
14317You can specify options for @code{makeinfo} by setting the
14318@code{makeinfo-options} variable with either the @kbd{M-x
14319edit-options} or the @kbd{M-x set-variable} command, or by setting the
14320variable in your @file{.emacs} initialization file.@refill
14321
14322For example, you could write the following in your @file{.emacs} file:@refill
14323
14324@example
14325@group
14326(setq makeinfo-options
14327 "--paragraph-indent=0 --no-split
14328 --fill-column=70 --verbose")
14329@end group
14330@end example
14331
14332@c If you write these three cross references using xref, you see
14333@c three references to the same named manual, which looks strange.
14334@iftex
14335For more information, see @ref{makeinfo options, , Options for
14336@code{makeinfo}}, as well as ``Editing Variable Values,'' ``Examining
14337and Setting Variables,'' and ``Init File'' in @cite{The GNU Emacs
14338Manual}.
14339@end iftex
14340@noindent
14341@ifinfo
14342For more information, see@*
14343@ref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs Manual},@*
14344@ref{Examining, , Examining and Setting Variables, emacs, The GNU Emacs Manual},@*
14345@ref{Init File, , , emacs, The GNU Emacs Manual}, and@*
14346@ref{makeinfo options, , Options for @code{makeinfo}}.
14347@end ifinfo
14348
14349@node texinfo-format commands
14350@comment node-name, next, previous, up
14351@subsection The @code{texinfo-format@dots{}} Commands
14352@findex texinfo-format-region
14353@findex texinfo-format-buffer
14354
14355In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
14356file with the @code{texinfo-format-region} command. This formats the
14357current region and displays the formatted text in a temporary buffer
14358called @samp{*Info Region*}.@refill
14359
14360Similarly, you can format a buffer with the
14361@code{texinfo-format-buffer} command. This command creates a new
14362buffer and generates the Info file in it. Typing @kbd{C-x C-s} will
14363save the Info file under the name specified by the
14364@code{@@setfilename} line which must be near the beginning of the
14365Texinfo file.@refill
14366
14367@table @kbd
14368@item C-c C-e C-r
14369@itemx @code{texinfo-format-region}
14370Format the current region for Info.
14371@findex texinfo-format-region
14372
14373@item C-c C-e C-b
14374@itemx @code{texinfo-format-buffer}
14375Format the current buffer for Info.
14376@findex texinfo-format-buffer
14377@end table
14378
14379The @code{texinfo-format-region} and @code{texinfo-format-buffer}
14380commands provide you with some error checking, and other functions can
14381provide you with further help in finding formatting errors. These
14382procedures are described in an appendix; see @ref{Catching Mistakes}.
14383However, the @code{makeinfo} program is often faster and
14384provides better error checking (@pxref{makeinfo in Emacs}).@refill
14385
14386@node Batch Formatting
14387@comment node-name, next, previous, up
14388@subsection Batch Formatting
14389@cindex Batch formatting for Info
14390@cindex Info batch formatting
14391
14392You can format Texinfo files for Info using @code{batch-texinfo-format}
14393and Emacs Batch mode. You can run Emacs in Batch mode from any shell,
14394including a shell inside of Emacs. (@xref{Command Switches, , Command
14395Line Switches and Arguments, emacs, The GNU Emacs Manual}.)@refill
14396
14397Here is a shell command to format all the files that end in
14398@file{.texinfo} in the current directory:
14399
14400@example
14401emacs -batch -funcall batch-texinfo-format *.texinfo
14402@end example
14403
14404@noindent
14405Emacs processes all the files listed on the command line, even if an
14406error occurs while attempting to format some of them.@refill
14407
14408Run @code{batch-texinfo-format} only with Emacs in Batch mode as shown;
14409it is not interactive. It kills the Batch mode Emacs on completion.@refill
14410
14411@code{batch-texinfo-format} is convenient if you lack @code{makeinfo}
14412and want to format several Texinfo files at once. When you use Batch
14413mode, you create a new Emacs process. This frees your current Emacs, so
14414you can continue working in it. (When you run
14415@code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot
14416use that Emacs for anything else until the command finishes.)@refill
14417
14418@node Tag and Split Files
14419@comment node-name, next, previous, up
14420@subsection Tag Files and Split Files
14421@cindex Making a tag table automatically
14422@cindex Tag table, making automatically
14423
14424If a Texinfo file has more than 30,000 bytes,
14425@code{texinfo-format-buffer} automatically creates a tag table
14426for its Info file; @code{makeinfo} always creates a tag table. With
14427a @dfn{tag table}, Info can jump to new nodes more quickly than it can
14428otherwise.@refill
14429
14430@cindex Indirect subfiles
14431In addition, if the Texinfo file contains more than about 70,000
14432bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the
14433large Info file into shorter @dfn{indirect} subfiles of about 50,000
14434bytes each. Big files are split into smaller files so that Emacs does
14435not need to make a large buffer to hold the whole of a large Info
14436file; instead, Emacs allocates just enough memory for the small, split-off
14437file that is needed at the time. This way, Emacs avoids wasting
14438memory when you run Info. (Before splitting was implemented, Info
14439files were always kept short and @dfn{include files} were designed as
14440a way to create a single, large printed manual out of the smaller Info
14441files. @xref{Include Files}, for more information. Include files are
14442still used for very large documents, such as @cite{The Emacs Lisp
14443Reference Manual}, in which each chapter is a separate file.)@refill
14444
14445When a file is split, Info itself makes use of a shortened version of
14446the original file that contains just the tag table and references to
14447the files that were split off. The split-off files are called
14448@dfn{indirect} files.@refill
14449
14450The split-off files have names that are created by appending @w{@samp{-1}},
14451@w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the
14452@code{@@setfilename} command. The shortened version of the original file
14453continues to have the name specified by @code{@@setfilename}.@refill
14454
14455At one stage in writing this document, for example, the Info file was saved
14456as the file @file{test-texinfo} and that file looked like this:@refill
14457
14458@example
14459@group
14460Info file: test-texinfo, -*-Text-*-
14461produced by texinfo-format-buffer
14462from file: new-texinfo-manual.texinfo
14463
14464^_
14465Indirect:
14466test-texinfo-1: 102
14467test-texinfo-2: 50422
14468@end group
14469@group
14470test-texinfo-3: 101300
14471^_^L
14472Tag table:
14473(Indirect)
14474Node: overview^?104
14475Node: info file^?1271
14476@end group
14477@group
14478Node: printed manual^?4853
14479Node: conventions^?6855
14480@dots{}
14481@end group
14482@end example
14483
14484@noindent
14485(But @file{test-texinfo} had far more nodes than are shown here.) Each of
14486the split-off, indirect files, @file{test-texinfo-1},
14487@file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file
14488after the line that says @samp{Indirect:}. The tag table is listed after
14489the line that says @samp{Tag table:}. @refill
14490
14491In the list of indirect files, the number following the file name
14492records the cumulative number of bytes in the preceding indirect files,
14493not counting the file list itself, the tag table, or the permissions
14494text in each file. In the tag table, the number following the node name
14495records the location of the beginning of the node, in bytes from the
14496beginning of the (unsplit) output.
14497
14498If you are using @code{texinfo-format-buffer} to create Info files,
14499you may want to run the @code{Info-validate} command. (The
14500@code{makeinfo} command does such a good job on its own, you do not
14501need @code{Info-validate}.) However, you cannot run the @kbd{M-x
14502Info-validate} node-checking command on indirect files. For
14503information on how to prevent files from being split and how to
14504validate the structure of the nodes, see @ref{Using
14505Info-validate}.@refill
14506
14507
14508@node makeinfo html
14509@subsection Generating HTML
14510@cindex HTML
14511
14512Besides generating output in the Info format, you can use the
14513@samp{--html} option to generate output in HTML format, for installation
14514on a web site (for example). By default, the HTML output is split at
14515node level.
14516
14517When splitting, the HTML output files are written into a subdirectory.
14518The subdirectory is named according to the name from
14519@code{@@setfilename} with any extension removed; for example, HTML
14520output for @code{@@setfilename emacs.info} would be written into a
14521subdirectory named @samp{emacs}. If that directory cannot be created
14522for any reason, then @samp{.html} is appended to the directory name, as
14523in @samp{emacs.html} (this is necessary because sometimes the info file
14524is named without an extension, e.g., @samp{texinfo}). If the
14525@samp{@var{name}.html} directory can't be created either,
14526@code{makeinfo} gives up. In any case, the top-level output file within
14527the directory is always named @samp{index.html}.
14528
14529Monolithic output (@code{--no-split}) is named according to
14530@code{@@setfilename} or @code{--outfile}. Cross-document node
14531references are not supported in monolithic HTML.
14532
14533Texinfo input marked up with the @code{@@ifhtml} command will produce
14534output only with the @samp{--html} option supplied. Input marked up
14535with the @code{@@html} is passed literally to the output (suppressing
14536the normal escaping of input @samp{<}, @samp{>} and @samp{&} characters
14537which have special significance in HTML).
14538
14539The @samp{--footnote-style} option is currently ignored for HTML output;
14540footnotes are linked to the end of the output file.
14541
14542The HTML generated is mostly standard (i.e., HTML 2.0, RFC-1866). The
14543exception is that HTML 3.2 tables are generated from the
14544@code{@@multitable} command, but tagged to degrade as well as possible
|
14425in browsers without table support. Please report output from an
14426error-free run of @code{makeinfo} which violates the @w{HTML 3.2} DTD as
14427a bug.
| 14545in browsers without table support. The HTML 4 @samp{lang} attribute on
14546the @samp{<html>} attribute is also used. Please report output from an
14547error-free run of @code{makeinfo} which has browser portability problems
14548as a bug.
|
14428
14429Navigation bars are inserted at the start of nodes, similarly to Info
14430output. The @samp{--no-headers} option will suppress this if used with
14431@samp{--no-split}. Header @code{<link>} elements in split output can
14432support info-like navigation with browsers like Lynx and @w{Emacs W3}
14433which implement this @w{HTML 1.0} feature. @samp{@@xref} commands to
14434other documents are generated assuming the other document is available
14435in split HTML form, and installed in the same HTML documentation tree,
14436at @file{../<info-document>/}.
14437
14438
14439@node Installing an Info File
14440@section Installing an Info File
14441@cindex Installing an Info file
14442@cindex Info file installation
14443@cindex @file{dir} directory for Info installation
14444
14445Info files are usually kept in the @file{info} directory. You can read
14446Info files using the standalone Info program or the Info reader built
14447into Emacs. (@inforef{Top, info, info}, for an introduction to Info.)
14448
14449@menu
14450* Directory File:: The top level menu for all Info files.
| 14549
14550Navigation bars are inserted at the start of nodes, similarly to Info
14551output. The @samp{--no-headers} option will suppress this if used with
14552@samp{--no-split}. Header @code{<link>} elements in split output can
14553support info-like navigation with browsers like Lynx and @w{Emacs W3}
14554which implement this @w{HTML 1.0} feature. @samp{@@xref} commands to
14555other documents are generated assuming the other document is available
14556in split HTML form, and installed in the same HTML documentation tree,
14557at @file{../<info-document>/}.
14558
14559
14560@node Installing an Info File
14561@section Installing an Info File
14562@cindex Installing an Info file
14563@cindex Info file installation
14564@cindex @file{dir} directory for Info installation
14565
14566Info files are usually kept in the @file{info} directory. You can read
14567Info files using the standalone Info program or the Info reader built
14568into Emacs. (@inforef{Top, info, info}, for an introduction to Info.)
14569
14570@menu
14571* Directory File:: The top level menu for all Info files.
|
14451* New Info File:: Listing a new info file.
| 14572* New Info File:: Listing a new Info file.
|
14452* Other Info Directories:: How to specify Info files that are
14453 located in other directories.
14454* Installing Dir Entries:: How to specify what menu entry to add
14455 to the Info directory.
14456* Invoking install-info:: @code{install-info} options.
14457@end menu
14458
14459
14460@node Directory File
14461@subsection The Directory File @file{dir}
14462
14463For Info to work, the @file{info} directory must contain a file that
14464serves as a top level directory for the Info system. By convention,
14465this file is called @file{dir}. (You can find the location of this file
14466within Emacs by typing @kbd{C-h i} to enter Info and then typing
14467@kbd{C-x C-f} to see the pathname to the @file{info} directory.)
14468
14469The @file{dir} file is itself an Info file. It contains the top level
14470menu for all the Info files in the system. The menu looks like
14471this:@refill
14472
14473@example
14474@group
14475* Menu:
14476* Info: (info). Documentation browsing system.
14477* Emacs: (emacs). The extensible, self-documenting
14478 text editor.
14479* Texinfo: (texinfo). With one source file, make
14480 either a printed manual using
14481 @@TeX@{@} or an Info file.
14482@dots{}
14483@end group
14484@end example
14485
14486Each of these menu entries points to the `Top' node of the Info file
14487that is named in parentheses. (The menu entry does not need to
14488specify the `Top' node, since Info goes to the `Top' node if no node
14489name is mentioned. @xref{Other Info Files, , Nodes in Other Info
14490Files}.)@refill
14491
14492Thus, the @samp{Info} entry points to the `Top' node of the
14493@file{info} file and the @samp{Emacs} entry points to the `Top' node
14494of the @file{emacs} file.@refill
14495
14496In each of the Info files, the `Up' pointer of the `Top' node refers
14497back to the @code{dir} file. For example, the line for the `Top'
14498node of the Emacs manual looks like this in Info:@refill
14499
14500@example
14501File: emacs Node: Top, Up: (DIR), Next: Distrib
14502@end example
14503
14504@noindent
14505In this case, the @file{dir} file name is written in upper case
14506letters---it can be written in either upper or lower case. This is not
14507true in general, it is a special case for @file{dir}.
14508
14509
14510@node New Info File
14511@subsection Listing a New Info File
14512@cindex Adding a new Info file
14513@cindex Listing a new Info file
14514@cindex New Info file, listing it in @file{dir} file
14515@cindex Info file, listing a new
14516@cindex @file{dir} file listing
14517
14518To add a new Info file to your system, you must write a menu entry to
14519add to the menu in the @file{dir} file in the @file{info} directory.
14520For example, if you were adding documentation for GDB, you would write
14521the following new entry:@refill
14522
14523@example
14524* GDB: (gdb). The source-level C debugger.
14525@end example
14526
14527@noindent
14528The first part of the menu entry is the menu entry name, followed by a
14529colon. The second part is the name of the Info file, in parentheses,
14530followed by a period. The third part is the description.
14531
14532The name of an Info file often has a @file{.info} extension. Thus, the
14533Info file for GDB might be called either @file{gdb} or @file{gdb.info}.
14534The Info reader programs automatically try the file name both with and
14535without @file{.info}@footnote{On MS-DOS/MS-Windows systems, Info will
14536try the @file{.inf} extension as well.}; so it is better to avoid
14537clutter and not to write @samp{.info} explicitly in the menu entry. For
14538example, the GDB menu entry should use just @samp{gdb} for the file
14539name, not @samp{gdb.info}.
14540
14541
14542@node Other Info Directories
14543@subsection Info Files in Other Directories
14544@cindex Installing Info in another directory
14545@cindex Info installed in another directory
14546@cindex Another Info directory
14547@cindex @file{dir} files and Info directories
14548
14549If an Info file is not in the @file{info} directory, there are three
14550ways to specify its location:@refill
14551
14552@enumerate
14553@item
14554Write the pathname in the @file{dir} file as the second part of the menu.
14555
14556@item
14557If you are using Emacs, list the name of the file in a second @file{dir}
14558file, in its directory; and then add the name of that directory to the
14559@code{Info-directory-list} variable in your personal or site
14560initialization file.
14561
14562This variable tells Emacs where to look for @file{dir} files (the files
14563must be named @file{dir}). Emacs merges the files named @file{dir} from
14564each of the listed directories. (In Emacs version 18, you can set the
14565@code{Info-directory} variable to the name of only one
14566directory.)@refill
14567
14568@item
14569Specify the Info directory name in the @code{INFOPATH} environment
14570variable in your @file{.profile} or @file{.cshrc} initialization file.
14571(Only you and others who set this environment variable will be able to
14572find Info files whose location is specified this way.)
14573@end enumerate
14574
14575For example, to reach a test file in the @file{/home/bob/info}
14576directory, you could add an entry like this to the menu in the
14577standard @file{dir} file:@refill
14578
14579@example
14580* Test: (/home/bob/info/info-test). Bob's own test file.
14581@end example
14582
14583@noindent
14584In this case, the absolute file name of the @file{info-test} file is
14585written as the second part of the menu entry.@refill
14586
14587Alternatively, you could write the following in your @file{.emacs} file:
14588
14589@vindex Info-directory-list
14590@example
14591@group
14592(require 'info)
14593(setq Info-directory-list
14594 (cons (expand-file-name "/home/bob/info")
14595 Info-directory-list))
14596@end group
14597@end example
14598
14599This tells Emacs to merge the system @file{dir} file with the @file{dir}
14600file in @file{/home/bob/info}. Thus, Info will list the
14601@file{/home/bob/info/info-test} file as a menu entry in the
14602@file{/home/bob/info/dir} file. Emacs does the merging only when
14603@kbd{M-x info} is first run, so if you want to set
14604@code{Info-directory-list} in an Emacs session where you've already run
14605@code{info}, you must @code{(setq Info-dir-contents nil)} to force Emacs
14606to recompose the @file{dir} file.
14607
14608@vindex INFOPATH
14609Finally, you can tell Info where to look by setting the @code{INFOPATH}
14610environment variable in your shell startup file, such as @file{.cshrc},
14611@file{.profile} or @file{autoexec.bat}. If you use a Bourne-compatible
14612shell such as @code{sh} or @code{bash} for your shell command
14613interpreter, you set the @code{INFOPATH} environment variable in the
14614@file{.profile} initialization file; but if you use @code{csh} or
14615@code{tcsh}, you set the variable in the @file{.cshrc} initialization
14616file. On MS-DOS/MS-Windows systems, you must set @code{INFOPATH} in
14617your @file{autoexec.bat} file or in the Registry. Each type of shell
14618uses a different syntax.
14619
14620@itemize @bullet
14621@item
14622In a @file{.cshrc} file, you could set the @code{INFOPATH}
14623variable as follows:@refill
14624
14625@smallexample
14626setenv INFOPATH .:~/info:/usr/local/emacs/info
14627@end smallexample
14628
14629@item
14630In a @file{.profile} file, you would achieve the same effect by
14631writing:@refill
14632
14633@smallexample
14634INFOPATH=.:$HOME/info:/usr/local/emacs/info
14635export INFOPATH
14636@end smallexample
14637
14638@item
14639@pindex autoexec.bat
14640In a @file{autoexec.bat} file, you write this command@footnote{Note the
14641use of @samp{;} as the directory separator, and a different syntax for
14642using values of other environment variables.}:
14643
14644@smallexample
14645set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info
14646@end smallexample
14647@end itemize
14648
14649@noindent
14650The @samp{.} indicates the current directory as usual. Emacs uses the
14651@code{INFOPATH} environment variable to initialize the value of Emacs's
14652own @code{Info-directory-list} variable. The stand-alone Info reader
14653merges any files named @file{dir} in any directory listed in the
14654@env{INFOPATH} variable into a single menu presented to you in the node
14655called @samp{(dir)Top}.
14656
14657@cindex colon, last in @env{INFOPATH}
14658However you set @env{INFOPATH}, if its last character is a
14659colon@footnote{On MS-DOS/MS-Windows systems, use semi-colon instead.}, this
14660is replaced by the default (compiled-in) path. This gives you a way to
14661augment the default path with new directories without having to list all
14662the standard places. For example (using @code{sh} syntax):
14663
14664@example
14665INFOPATH=/local/info:
14666export INFOPATH
14667@end example
14668
14669@noindent
14670will search @file{/local/info} first, then the standard directories.
14671Leading or doubled colons are not treated specially.
14672
14673@cindex @file{dir} file, creating your own
14674When you create your own @file{dir} file for use with
14675@code{Info-directory-list} or @env{INFOPATH}, it's easiest to start by
14676copying an existing @file{dir} file and replace all the text after the
14677@samp{* Menu:} with your desired entries. That way, the punctuation and
14678special CTRL-_ characters that Info needs will be present.
14679
14680
14681@node Installing Dir Entries
14682@subsection Installing Info Directory Files
14683
14684When you install an Info file onto your system, you can use the program
14685@code{install-info} to update the Info directory file @file{dir}.
14686Normally the makefile for the package runs @code{install-info}, just
14687after copying the Info file into its proper installed location.
14688
14689@findex dircategory
14690@findex direntry
| 14573* Other Info Directories:: How to specify Info files that are
14574 located in other directories.
14575* Installing Dir Entries:: How to specify what menu entry to add
14576 to the Info directory.
14577* Invoking install-info:: @code{install-info} options.
14578@end menu
14579
14580
14581@node Directory File
14582@subsection The Directory File @file{dir}
14583
14584For Info to work, the @file{info} directory must contain a file that
14585serves as a top level directory for the Info system. By convention,
14586this file is called @file{dir}. (You can find the location of this file
14587within Emacs by typing @kbd{C-h i} to enter Info and then typing
14588@kbd{C-x C-f} to see the pathname to the @file{info} directory.)
14589
14590The @file{dir} file is itself an Info file. It contains the top level
14591menu for all the Info files in the system. The menu looks like
14592this:@refill
14593
14594@example
14595@group
14596* Menu:
14597* Info: (info). Documentation browsing system.
14598* Emacs: (emacs). The extensible, self-documenting
14599 text editor.
14600* Texinfo: (texinfo). With one source file, make
14601 either a printed manual using
14602 @@TeX@{@} or an Info file.
14603@dots{}
14604@end group
14605@end example
14606
14607Each of these menu entries points to the `Top' node of the Info file
14608that is named in parentheses. (The menu entry does not need to
14609specify the `Top' node, since Info goes to the `Top' node if no node
14610name is mentioned. @xref{Other Info Files, , Nodes in Other Info
14611Files}.)@refill
14612
14613Thus, the @samp{Info} entry points to the `Top' node of the
14614@file{info} file and the @samp{Emacs} entry points to the `Top' node
14615of the @file{emacs} file.@refill
14616
14617In each of the Info files, the `Up' pointer of the `Top' node refers
14618back to the @code{dir} file. For example, the line for the `Top'
14619node of the Emacs manual looks like this in Info:@refill
14620
14621@example
14622File: emacs Node: Top, Up: (DIR), Next: Distrib
14623@end example
14624
14625@noindent
14626In this case, the @file{dir} file name is written in upper case
14627letters---it can be written in either upper or lower case. This is not
14628true in general, it is a special case for @file{dir}.
14629
14630
14631@node New Info File
14632@subsection Listing a New Info File
14633@cindex Adding a new Info file
14634@cindex Listing a new Info file
14635@cindex New Info file, listing it in @file{dir} file
14636@cindex Info file, listing a new
14637@cindex @file{dir} file listing
14638
14639To add a new Info file to your system, you must write a menu entry to
14640add to the menu in the @file{dir} file in the @file{info} directory.
14641For example, if you were adding documentation for GDB, you would write
14642the following new entry:@refill
14643
14644@example
14645* GDB: (gdb). The source-level C debugger.
14646@end example
14647
14648@noindent
14649The first part of the menu entry is the menu entry name, followed by a
14650colon. The second part is the name of the Info file, in parentheses,
14651followed by a period. The third part is the description.
14652
14653The name of an Info file often has a @file{.info} extension. Thus, the
14654Info file for GDB might be called either @file{gdb} or @file{gdb.info}.
14655The Info reader programs automatically try the file name both with and
14656without @file{.info}@footnote{On MS-DOS/MS-Windows systems, Info will
14657try the @file{.inf} extension as well.}; so it is better to avoid
14658clutter and not to write @samp{.info} explicitly in the menu entry. For
14659example, the GDB menu entry should use just @samp{gdb} for the file
14660name, not @samp{gdb.info}.
14661
14662
14663@node Other Info Directories
14664@subsection Info Files in Other Directories
14665@cindex Installing Info in another directory
14666@cindex Info installed in another directory
14667@cindex Another Info directory
14668@cindex @file{dir} files and Info directories
14669
14670If an Info file is not in the @file{info} directory, there are three
14671ways to specify its location:@refill
14672
14673@enumerate
14674@item
14675Write the pathname in the @file{dir} file as the second part of the menu.
14676
14677@item
14678If you are using Emacs, list the name of the file in a second @file{dir}
14679file, in its directory; and then add the name of that directory to the
14680@code{Info-directory-list} variable in your personal or site
14681initialization file.
14682
14683This variable tells Emacs where to look for @file{dir} files (the files
14684must be named @file{dir}). Emacs merges the files named @file{dir} from
14685each of the listed directories. (In Emacs version 18, you can set the
14686@code{Info-directory} variable to the name of only one
14687directory.)@refill
14688
14689@item
14690Specify the Info directory name in the @code{INFOPATH} environment
14691variable in your @file{.profile} or @file{.cshrc} initialization file.
14692(Only you and others who set this environment variable will be able to
14693find Info files whose location is specified this way.)
14694@end enumerate
14695
14696For example, to reach a test file in the @file{/home/bob/info}
14697directory, you could add an entry like this to the menu in the
14698standard @file{dir} file:@refill
14699
14700@example
14701* Test: (/home/bob/info/info-test). Bob's own test file.
14702@end example
14703
14704@noindent
14705In this case, the absolute file name of the @file{info-test} file is
14706written as the second part of the menu entry.@refill
14707
14708Alternatively, you could write the following in your @file{.emacs} file:
14709
14710@vindex Info-directory-list
14711@example
14712@group
14713(require 'info)
14714(setq Info-directory-list
14715 (cons (expand-file-name "/home/bob/info")
14716 Info-directory-list))
14717@end group
14718@end example
14719
14720This tells Emacs to merge the system @file{dir} file with the @file{dir}
14721file in @file{/home/bob/info}. Thus, Info will list the
14722@file{/home/bob/info/info-test} file as a menu entry in the
14723@file{/home/bob/info/dir} file. Emacs does the merging only when
14724@kbd{M-x info} is first run, so if you want to set
14725@code{Info-directory-list} in an Emacs session where you've already run
14726@code{info}, you must @code{(setq Info-dir-contents nil)} to force Emacs
14727to recompose the @file{dir} file.
14728
14729@vindex INFOPATH
14730Finally, you can tell Info where to look by setting the @code{INFOPATH}
14731environment variable in your shell startup file, such as @file{.cshrc},
14732@file{.profile} or @file{autoexec.bat}. If you use a Bourne-compatible
14733shell such as @code{sh} or @code{bash} for your shell command
14734interpreter, you set the @code{INFOPATH} environment variable in the
14735@file{.profile} initialization file; but if you use @code{csh} or
14736@code{tcsh}, you set the variable in the @file{.cshrc} initialization
14737file. On MS-DOS/MS-Windows systems, you must set @code{INFOPATH} in
14738your @file{autoexec.bat} file or in the Registry. Each type of shell
14739uses a different syntax.
14740
14741@itemize @bullet
14742@item
14743In a @file{.cshrc} file, you could set the @code{INFOPATH}
14744variable as follows:@refill
14745
14746@smallexample
14747setenv INFOPATH .:~/info:/usr/local/emacs/info
14748@end smallexample
14749
14750@item
14751In a @file{.profile} file, you would achieve the same effect by
14752writing:@refill
14753
14754@smallexample
14755INFOPATH=.:$HOME/info:/usr/local/emacs/info
14756export INFOPATH
14757@end smallexample
14758
14759@item
14760@pindex autoexec.bat
14761In a @file{autoexec.bat} file, you write this command@footnote{Note the
14762use of @samp{;} as the directory separator, and a different syntax for
14763using values of other environment variables.}:
14764
14765@smallexample
14766set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info
14767@end smallexample
14768@end itemize
14769
14770@noindent
14771The @samp{.} indicates the current directory as usual. Emacs uses the
14772@code{INFOPATH} environment variable to initialize the value of Emacs's
14773own @code{Info-directory-list} variable. The stand-alone Info reader
14774merges any files named @file{dir} in any directory listed in the
14775@env{INFOPATH} variable into a single menu presented to you in the node
14776called @samp{(dir)Top}.
14777
14778@cindex colon, last in @env{INFOPATH}
14779However you set @env{INFOPATH}, if its last character is a
14780colon@footnote{On MS-DOS/MS-Windows systems, use semi-colon instead.}, this
14781is replaced by the default (compiled-in) path. This gives you a way to
14782augment the default path with new directories without having to list all
14783the standard places. For example (using @code{sh} syntax):
14784
14785@example
14786INFOPATH=/local/info:
14787export INFOPATH
14788@end example
14789
14790@noindent
14791will search @file{/local/info} first, then the standard directories.
14792Leading or doubled colons are not treated specially.
14793
14794@cindex @file{dir} file, creating your own
14795When you create your own @file{dir} file for use with
14796@code{Info-directory-list} or @env{INFOPATH}, it's easiest to start by
14797copying an existing @file{dir} file and replace all the text after the
14798@samp{* Menu:} with your desired entries. That way, the punctuation and
14799special CTRL-_ characters that Info needs will be present.
14800
14801
14802@node Installing Dir Entries
14803@subsection Installing Info Directory Files
14804
14805When you install an Info file onto your system, you can use the program
14806@code{install-info} to update the Info directory file @file{dir}.
14807Normally the makefile for the package runs @code{install-info}, just
14808after copying the Info file into its proper installed location.
14809
14810@findex dircategory
14811@findex direntry
|
14691In order for the Info file to work with @code{install-info}, you should
14692use the commands @code{@@dircategory} and
| 14812In order for the Info file to work with @code{install-info}, you include
14813the commands @code{@@dircategory} and
|
14693@code{@@direntry}@dots{}@code{@@end direntry} in the Texinfo source
14694file. Use @code{@@direntry} to specify the menu entries to add to the
14695Info directory file, and use @code{@@dircategory} to specify which part
14696of the Info directory to put it in. Here is how these commands are used
14697in this manual:
14698
14699@smallexample
14700@@dircategory Texinfo documentation system
14701@@direntry
14702* Texinfo: (texinfo). The GNU documentation format.
14703* install-info: (texinfo)Invoking install-info. @dots{}
14704@dots{}
14705@@end direntry
14706@end smallexample
14707
14708Here's what this produces in the Info file:
14709
14710@smallexample
14711INFO-DIR-SECTION Texinfo documentation system
14712START-INFO-DIR-ENTRY
14713* Texinfo: (texinfo). The GNU documentation format.
14714* install-info: (texinfo)Invoking install-info. @dots{}
14715@dots{}
14716END-INFO-DIR-ENTRY
14717@end smallexample
14718
14719@noindent
14720The @code{install-info} program sees these lines in the Info file, and
14721that is how it knows what to do.
14722
14723Always use the @code{@@direntry} and @code{@@dircategory} commands near
14724the beginning of the Texinfo input, before the first @code{@@node}
14725command. If you use them later on in the input, @code{install-info}
14726will not notice them.
14727
14728If you use @code{@@dircategory} more than once in the Texinfo source,
14729each usage specifies the `current' category; any subsequent
14730@code{@@direntry} commands will add to that category.
14731
14732Here are some recommended @code{@@dircategory} categories:
14733
14734@display
14735GNU packages
14736GNU programming tools
14737GNU programming documentation
14738GNU Emacs Lisp
14739GNU libraries
| 14814@code{@@direntry}@dots{}@code{@@end direntry} in the Texinfo source
14815file. Use @code{@@direntry} to specify the menu entries to add to the
14816Info directory file, and use @code{@@dircategory} to specify which part
14817of the Info directory to put it in. Here is how these commands are used
14818in this manual:
14819
14820@smallexample
14821@@dircategory Texinfo documentation system
14822@@direntry
14823* Texinfo: (texinfo). The GNU documentation format.
14824* install-info: (texinfo)Invoking install-info. @dots{}
14825@dots{}
14826@@end direntry
14827@end smallexample
14828
14829Here's what this produces in the Info file:
14830
14831@smallexample
14832INFO-DIR-SECTION Texinfo documentation system
14833START-INFO-DIR-ENTRY
14834* Texinfo: (texinfo). The GNU documentation format.
14835* install-info: (texinfo)Invoking install-info. @dots{}
14836@dots{}
14837END-INFO-DIR-ENTRY
14838@end smallexample
14839
14840@noindent
14841The @code{install-info} program sees these lines in the Info file, and
14842that is how it knows what to do.
14843
14844Always use the @code{@@direntry} and @code{@@dircategory} commands near
14845the beginning of the Texinfo input, before the first @code{@@node}
14846command. If you use them later on in the input, @code{install-info}
14847will not notice them.
14848
14849If you use @code{@@dircategory} more than once in the Texinfo source,
14850each usage specifies the `current' category; any subsequent
14851@code{@@direntry} commands will add to that category.
14852
14853Here are some recommended @code{@@dircategory} categories:
14854
14855@display
14856GNU packages
14857GNU programming tools
14858GNU programming documentation
14859GNU Emacs Lisp
14860GNU libraries
|
14740Linux
| |
14741TeX
14742Individual utilities
14743@end display
14744
14745The idea is to include the `Invoking' node for every program installed
14746by a package under `Individual utilities', and an entry for the manual
14747as a whole in the appropriate other category.
14748
14749
14750@node Invoking install-info
14751@subsection Invoking install-info
14752
14753@pindex install-info
14754
14755@code{install-info} inserts menu entries from an Info file into the
14756top-level @file{dir} file in the Info system (see the previous sections
14757for an explanation of how the @file{dir} file works). It's most often
14758run as part of software installation, or when constructing a @file{dir} file
14759for all manuals on a system. Synopsis:
14760
14761@example
14762install-info [@var{option}]@dots{} [@var{info-file} [@var{dir-file}]]
14763@end example
14764
14765If @var{info-file} or @var{dir-file} are not specified, the options
14766(described below) that define them must be. There are no compile-time
14767defaults, and standard input is never used. @code{install-info} can
14768read only one Info file and write only one @file{dir} file per invocation.
14769
14770@cindex @file{dir}, created by @code{install-info}
14771If @var{dir-file} (however specified) does not exist,
14772@code{install-info} creates it if possible (with no entries).
14773
14774@cindex Compressed files, reading
14775@cindex Dir files, compressed
14776If any input file is compressed with @code{gzip} (@pxref{Invoking
14777gzip,,,gzip, Gzip}), @code{install-info} automatically uncompresses it
14778for reading. And if @var{dir-file} is compressed, @code{install-info}
14779also automatically leaves it compressed after writing any changes.
14780If @var{dir-file} itself does not exist, @code{install-info} tries to
14781open @file{@var{dir-file}.gz}.
14782
14783Options:
14784
14785@table @code
14786@item --delete
14787@opindex --delete
14788Delete the entries in @var{info-file} from @var{dir-file}. The file
14789name in the entry in @var{dir-file} must be @var{info-file} (except for
14790an optional @samp{.info} in either one). Don't insert any new entries.
14791
14792@item --dir-file=@var{name}
14793@itemx -d @var{name}
14794@opindex --dir-file=@var{name}
14795@opindex -d @var{name}
14796Specify file name of the Info directory file. This is equivalent to
14797using the @var{dir-file} argument.
14798
14799@item --entry=@var{text}
14800@itemx -e @var{text}
14801@opindex --entry=@var{text}
14802@opindex -e @var{text}
14803Insert @var{text} as an Info directory entry; @var{text} should have the
14804form of an Info menu item line plus zero or more extra lines starting
14805with whitespace. If you specify more than one entry, they are all
14806added. If you don't specify any entries, they are determined from
14807information in the Info file itself.
14808
14809@item --help
14810@itemx -h
14811@opindex --help
14812@opindex -h
14813Display a usage message listing basic usage and all available options,
14814then exit successfully.
14815
14816@item --info-file=@var{file}
14817@itemx -i @var{file}
14818@opindex --info-file=@var{file}
14819@opindex -i @var{file}
14820Specify Info file to install in the directory.
14821Equivalent to using the @var{info-file} argument.
14822
14823@item --info-dir=@var{dir}
14824@itemx -D @var{dir}
14825@opindex --info-dir=@var{dir}
14826@opindex -D @var{dir}
14827Specify the directory where @file{dir} resides.
14828Equivalent to @samp{--dir-file=@var{dir}/dir}.
14829
14830@item --item=@var{text}
14831@opindex --item=@var{text}
14832Same as @samp{--entry=@var{text}}. An Info directory entry is actually
14833a menu item.
14834
14835@item --quiet
14836@opindex --quiet
14837Suppress warnings.
14838
14839@item --remove
14840@itemx -r
14841@opindex --remove
14842@opindex -r
14843Same as @samp{--delete}.
14844
14845@item --section=@var{sec}
14846@itemx -s @var{sec}
14847@opindex --section=@var{sec}
14848@opindex -s @var{sec}
14849Put this file's entries in section @var{sec} of the directory. If you
14850specify more than one section, all the entries are added in each of the
14851sections. If you don't specify any sections, they are determined from
14852information in the Info file itself.
14853
14854@item --version
14855@itemx -V
14856@opindex --version
14857@opindex -V
14858@cindex version number, finding
14859Display version information and exit successfully.
14860
14861@end table
14862
14863
14864@node Command List
14865@appendix @@-Command List
14866@cindex Alphabetical @@-command list
14867@cindex List of @@-commands
14868@cindex @@-command list
14869@cindex Reference to @@-commands
14870
14871Here is an alphabetical list of the @@-commands in Texinfo. Square
14872brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis,
14873@samp{@dots{}}, indicates repeated text.
14874
14875@sp 1
14876@table @code
14877@item @@@var{whitespace}
14878An @code{@@} followed by a space, tab, or newline produces a normal,
14879stretchable, interword space. @xref{Multiple Spaces}.
14880
14881@item @@!
14882Generate an exclamation point that really does end a sentence (usually
14883after an end-of-sentence capital letter). @xref{Ending a Sentence}.
14884
14885@item @@"
14886@itemx @@'
14887Generate an umlaut or acute accent, respectively, over the next
14888character, as in @"o and @'o. @xref{Inserting Accents}.
14889
14890@item @@*
14891Force a line break. Do not end a paragraph that uses @code{@@*} with
| 14861TeX
14862Individual utilities
14863@end display
14864
14865The idea is to include the `Invoking' node for every program installed
14866by a package under `Individual utilities', and an entry for the manual
14867as a whole in the appropriate other category.
14868
14869
14870@node Invoking install-info
14871@subsection Invoking install-info
14872
14873@pindex install-info
14874
14875@code{install-info} inserts menu entries from an Info file into the
14876top-level @file{dir} file in the Info system (see the previous sections
14877for an explanation of how the @file{dir} file works). It's most often
14878run as part of software installation, or when constructing a @file{dir} file
14879for all manuals on a system. Synopsis:
14880
14881@example
14882install-info [@var{option}]@dots{} [@var{info-file} [@var{dir-file}]]
14883@end example
14884
14885If @var{info-file} or @var{dir-file} are not specified, the options
14886(described below) that define them must be. There are no compile-time
14887defaults, and standard input is never used. @code{install-info} can
14888read only one Info file and write only one @file{dir} file per invocation.
14889
14890@cindex @file{dir}, created by @code{install-info}
14891If @var{dir-file} (however specified) does not exist,
14892@code{install-info} creates it if possible (with no entries).
14893
14894@cindex Compressed files, reading
14895@cindex Dir files, compressed
14896If any input file is compressed with @code{gzip} (@pxref{Invoking
14897gzip,,,gzip, Gzip}), @code{install-info} automatically uncompresses it
14898for reading. And if @var{dir-file} is compressed, @code{install-info}
14899also automatically leaves it compressed after writing any changes.
14900If @var{dir-file} itself does not exist, @code{install-info} tries to
14901open @file{@var{dir-file}.gz}.
14902
14903Options:
14904
14905@table @code
14906@item --delete
14907@opindex --delete
14908Delete the entries in @var{info-file} from @var{dir-file}. The file
14909name in the entry in @var{dir-file} must be @var{info-file} (except for
14910an optional @samp{.info} in either one). Don't insert any new entries.
14911
14912@item --dir-file=@var{name}
14913@itemx -d @var{name}
14914@opindex --dir-file=@var{name}
14915@opindex -d @var{name}
14916Specify file name of the Info directory file. This is equivalent to
14917using the @var{dir-file} argument.
14918
14919@item --entry=@var{text}
14920@itemx -e @var{text}
14921@opindex --entry=@var{text}
14922@opindex -e @var{text}
14923Insert @var{text} as an Info directory entry; @var{text} should have the
14924form of an Info menu item line plus zero or more extra lines starting
14925with whitespace. If you specify more than one entry, they are all
14926added. If you don't specify any entries, they are determined from
14927information in the Info file itself.
14928
14929@item --help
14930@itemx -h
14931@opindex --help
14932@opindex -h
14933Display a usage message listing basic usage and all available options,
14934then exit successfully.
14935
14936@item --info-file=@var{file}
14937@itemx -i @var{file}
14938@opindex --info-file=@var{file}
14939@opindex -i @var{file}
14940Specify Info file to install in the directory.
14941Equivalent to using the @var{info-file} argument.
14942
14943@item --info-dir=@var{dir}
14944@itemx -D @var{dir}
14945@opindex --info-dir=@var{dir}
14946@opindex -D @var{dir}
14947Specify the directory where @file{dir} resides.
14948Equivalent to @samp{--dir-file=@var{dir}/dir}.
14949
14950@item --item=@var{text}
14951@opindex --item=@var{text}
14952Same as @samp{--entry=@var{text}}. An Info directory entry is actually
14953a menu item.
14954
14955@item --quiet
14956@opindex --quiet
14957Suppress warnings.
14958
14959@item --remove
14960@itemx -r
14961@opindex --remove
14962@opindex -r
14963Same as @samp{--delete}.
14964
14965@item --section=@var{sec}
14966@itemx -s @var{sec}
14967@opindex --section=@var{sec}
14968@opindex -s @var{sec}
14969Put this file's entries in section @var{sec} of the directory. If you
14970specify more than one section, all the entries are added in each of the
14971sections. If you don't specify any sections, they are determined from
14972information in the Info file itself.
14973
14974@item --version
14975@itemx -V
14976@opindex --version
14977@opindex -V
14978@cindex version number, finding
14979Display version information and exit successfully.
14980
14981@end table
14982
14983
14984@node Command List
14985@appendix @@-Command List
14986@cindex Alphabetical @@-command list
14987@cindex List of @@-commands
14988@cindex @@-command list
14989@cindex Reference to @@-commands
14990
14991Here is an alphabetical list of the @@-commands in Texinfo. Square
14992brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis,
14993@samp{@dots{}}, indicates repeated text.
14994
14995@sp 1
14996@table @code
14997@item @@@var{whitespace}
14998An @code{@@} followed by a space, tab, or newline produces a normal,
14999stretchable, interword space. @xref{Multiple Spaces}.
15000
15001@item @@!
15002Generate an exclamation point that really does end a sentence (usually
15003after an end-of-sentence capital letter). @xref{Ending a Sentence}.
15004
15005@item @@"
15006@itemx @@'
15007Generate an umlaut or acute accent, respectively, over the next
15008character, as in @"o and @'o. @xref{Inserting Accents}.
15009
15010@item @@*
15011Force a line break. Do not end a paragraph that uses @code{@@*} with
|
14892an @code{@@refill} command. @xref{Line Breaks}.@refill
| 15012an @code{@@refill} command. @xref{Line Breaks}.
|
14893
14894@item @@,@{@var{c}@}
14895Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting
14896Accents}.
14897
14898@item @@-
14899Insert a discretionary hyphenation point. @xref{- and hyphenation}.
14900
14901@item @@.
14902Produce a period that really does end a sentence (usually after an
14903end-of-sentence capital letter). @xref{Ending a Sentence}.
14904
14905@item @@:
14906Indicate to @TeX{} that an immediately preceding period, question
14907mark, exclamation mark, or colon does not end a sentence. Prevent
14908@TeX{} from inserting extra whitespace as it does at the end of a
14909sentence. The command has no effect on the Info file output.
14910@xref{Not Ending a Sentence}.
14911
14912@item @@=
14913Generate a macron (bar) accent over the next character, as in @=o.
14914@xref{Inserting Accents}.
14915
14916@item @@?
14917Generate a question mark that really does end a sentence (usually after
14918an end-of-sentence capital letter). @xref{Ending a Sentence}.
14919
14920@item @@@@
14921Stands for an at sign, @samp{@@}.
14922@xref{Braces Atsigns, , Inserting @@ and braces}.
14923
| 15013
15014@item @@,@{@var{c}@}
15015Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting
15016Accents}.
15017
15018@item @@-
15019Insert a discretionary hyphenation point. @xref{- and hyphenation}.
15020
15021@item @@.
15022Produce a period that really does end a sentence (usually after an
15023end-of-sentence capital letter). @xref{Ending a Sentence}.
15024
15025@item @@:
15026Indicate to @TeX{} that an immediately preceding period, question
15027mark, exclamation mark, or colon does not end a sentence. Prevent
15028@TeX{} from inserting extra whitespace as it does at the end of a
15029sentence. The command has no effect on the Info file output.
15030@xref{Not Ending a Sentence}.
15031
15032@item @@=
15033Generate a macron (bar) accent over the next character, as in @=o.
15034@xref{Inserting Accents}.
15035
15036@item @@?
15037Generate a question mark that really does end a sentence (usually after
15038an end-of-sentence capital letter). @xref{Ending a Sentence}.
15039
15040@item @@@@
15041Stands for an at sign, @samp{@@}.
15042@xref{Braces Atsigns, , Inserting @@ and braces}.
15043
|
| 15044@item @@\
15045Stands for a backslash (@samp{\}) inside @code{@@math}.
15046@xref{math,,@code{math}}.
15047
|
14924@item @@^
14925@itemx @@`
14926Generate a circumflex (hat) or grave accent, respectively, over the next
| 15048@item @@^
15049@itemx @@`
15050Generate a circumflex (hat) or grave accent, respectively, over the next
|
14927character, as in @^o.
| 15051character, as in @^o and @`e.
|
14928@xref{Inserting Accents}.
14929
14930@item @@@{
14931Stands for a left brace, @samp{@{}.
14932@xref{Braces Atsigns, , Inserting @@ and braces}.
14933
14934@item @@@}
14935Stands for a right-hand brace, @samp{@}}.@*
14936@xref{Braces Atsigns, , Inserting @@ and braces}.
14937
14938@item @@~
14939Generate a tilde accent over the next character, as in @~N.
14940@xref{Inserting Accents}.
14941
14942@item @@AA@{@}
14943@itemx @@aa@{@}
14944Generate the uppercase and lowercase Scandinavian A-ring letters,
14945respectively: @AA{}, @aa{}. @xref{Inserting Accents}.
14946
14947@item @@acronym@{@var{abbrev}@}
14948Tag @var{abbrev} as an acronym, that is, an abbreviation written in all
14949capital letters, such as `NASA'. @xref{acronym,, @code{acronym}}.
14950
14951@item @@AE@{@}
14952@itemx @@ae@{@}
14953Generate the uppercase and lowercase AE ligatures, respectively:
14954@AE{}, @ae{}. @xref{Inserting Accents}.
14955
14956@itemx @@afivepaper
14957Change page dimensions for the A5 paper size. @xref{A4 Paper}.
14958
14959@item @@afourlatex
14960@itemx @@afourpaper
14961@itemx @@afourwide
14962Change page dimensions for the A4 paper size. @xref{A4 Paper}.
14963
14964@item @@alias @var{new}=@var{existing}
14965Make the command @samp{@@@var{new}} an alias for the existing command
14966@samp{@@@var{existing}}. @xref{alias}.
14967
14968@item @@anchor@{@var{name}@}
14969Define @var{name} as the current location for use as a cross-reference
14970target. @xref{anchor,, @code{@@anchor}}.
14971
14972@item @@appendix @var{title}
14973Begin an appendix. The title appears in the table
14974of contents of a printed manual. In Info, the title is
14975underlined with asterisks. @xref{unnumbered & appendix, , The
14976@code{@@unnumbered} and @code{@@appendix} Commands}.@refill
14977
14978@item @@appendixsec @var{title}
14979@itemx @@appendixsection @var{title}
14980Begin an appendix section within an appendix. The section title appears
14981in the table of contents of a printed manual. In Info, the title is
14982underlined with equal signs. @code{@@appendixsection} is a longer
14983spelling of the @code{@@appendixsec} command. @xref{unnumberedsec
14984appendixsec heading, , Section Commands}.@refill
14985
14986@item @@appendixsubsec @var{title}
14987Begin an appendix subsection within an appendix. The title appears
14988in the table of contents of a printed manual. In Info, the title is
14989underlined with hyphens. @xref{unnumberedsubsec appendixsubsec
14990subheading, , Subsection Commands}.@refill
14991
14992@item @@appendixsubsubsec @var{title}
14993Begin an appendix subsubsection within an appendix subsection. The
14994title appears in the table of contents of a printed manual. In Info,
14995the title is underlined with periods. @xref{subsubsection,, The
14996`subsub' Commands}.@refill
14997
14998@item @@asis
14999Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to
15000print the table's first column without highlighting (``as is'').
15001@xref{Two-column Tables, , Making a Two-column Table}.@refill
15002
15003@item @@author @var{author}
15004Typeset @var{author} flushleft and underline it. @xref{title
15005subtitle author, , The @code{@@title} and @code{@@author}
15006Commands}.@refill
15007
15008@item @@b@{@var{text}@}
15009Print @var{text} in @b{bold} font. No effect in Info. @xref{Fonts}.@refill
15010
15011@ignore
15012@item @@br
15013Force a paragraph break. If used within a line, follow @code{@@br}
15014with braces. @xref{br, , @code{@@br}}.@refill
15015@end ignore
15016
15017@item @@bullet@{@}
15018Generate a large round dot, or the closest possible
15019thing to one. @xref{bullet, , @code{@@bullet}}.@refill
15020
15021@item @@bye
15022Stop formatting a file. The formatters do not see the contents of a
15023file following an @code{@@bye} command. @xref{Ending a File}.@refill
15024
15025@item @@c @var{comment}
15026Begin a comment in Texinfo. The rest of the line does not appear in
15027either the Info file or the printed manual. A synonym for
15028@code{@@comment}. @xref{Comments, , Comments}.@refill
15029
15030@item @@cartouche
15031Highlight an example or quotation by drawing a box with rounded
15032corners around it. Pair with @code{@@end cartouche}. No effect in
15033Info. @xref{cartouche, , Drawing Cartouches Around Examples}.)@refill
15034
15035@item @@center @var{line-of-text}
15036Center the line of text following the command.
15037@xref{titlefont center sp, , @code{@@center}}.@refill
15038
15039@item @@centerchap @var{line-of-text}
15040Like @code{@@chapter}, but centers the chapter title. @xref{chapter,,
15041@code{@@chapter}}.
15042
15043@item @@chapheading @var{title}
15044Print a chapter-like heading in the text, but not in the table of
15045contents of a printed manual. In Info, the title is underlined with
15046asterisks. @xref{majorheading & chapheading, , @code{@@majorheading}
15047and @code{@@chapheading}}.@refill
15048
15049@item @@chapter @var{title}
15050Begin a chapter. The chapter title appears in the table of
15051contents of a printed manual. In Info, the title is underlined with
15052asterisks. @xref{chapter, , @code{@@chapter}}.@refill
15053
15054@item @@cindex @var{entry}
15055Add @var{entry} to the index of concepts. @xref{Index Entries, ,
15056Defining the Entries of an Index}.@refill
15057
15058@item @@cite@{@var{reference}@}
15059Highlight the name of a book or other reference that lacks a
15060companion Info file. @xref{cite, , @code{@@cite}}.@refill
15061
15062@item @@clear @var{flag}
15063Unset @var{flag}, preventing the Texinfo formatting commands from
15064formatting text between subsequent pairs of @code{@@ifset @var{flag}}
15065and @code{@@end ifset} commands, and preventing
15066@code{@@value@{@var{flag}@}} from expanding to the value to which
15067@var{flag} is set.
15068@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
15069
15070@item @@code@{@var{sample-code}@}
15071Highlight text that is an expression, a syntactically complete token
15072of a program, or a program name. @xref{code, , @code{@@code}}.@refill
15073
15074@item @@command@{@var{command-name}@}
15075Indicate a command name, such as @command{ls}.
15076@xref{command,, @code{@@command}}.
15077
15078@item @@comment @var{comment}
15079Begin a comment in Texinfo. The rest of the line does not appear in
15080either the Info file or the printed manual. A synonym for @code{@@c}.
15081@xref{Comments}.
15082
15083@item @@contents
15084Print a complete table of contents. Has no effect in Info, which uses
15085menus instead. @xref{Contents, , Generating a Table of
15086Contents}.@refill
15087
15088@item @@copyright@{@}
15089Generate a copyright symbol. @xref{copyright symbol, ,
15090@code{@@copyright}}.@refill
15091
15092@ignore
15093@item @@ctrl@{@var{ctrl-char}@}
15094Describe an @sc{ascii} control character. Insert actual control character
15095into Info file. @xref{ctrl, , @code{@@ctrl}}.@refill
15096@end ignore
15097
15098@item @@defcodeindex @var{index-name}
15099Define a new index and its indexing command. Print entries in an
15100@code{@@code} font. @xref{New Indices, , Defining New
15101Indices}.@refill
15102
15103@item @@defcv @var{category} @var{class} @var{name}
15104@itemx @@defcvx @var{category} @var{class} @var{name}
15105Format a description for a variable associated with a class in
15106object-oriented programming. Takes three arguments: the category of
15107thing being defined, the class to which it belongs, and its name.
15108@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
15109
15110@item @@deffn @var{category} @var{name} @var{arguments}@dots{}
15111@itemx @@deffnx @var{category} @var{name} @var{arguments}@dots{}
15112Format a description for a function, interactive command, or similar
15113entity that may take arguments. @code{@@deffn} takes as arguments the
15114category of entity being described, the name of this particular
15115entity, and its arguments, if any. @xref{Definition Commands}.@refill
15116
15117@item @@defindex @var{index-name}
15118Define a new index and its indexing command. Print entries in a roman
15119font. @xref{New Indices, , Defining New Indices}.@refill
15120
15121@item @@definfoenclose @var{newcmd}, @var{before}, @var{after},
15122Create new @@-command @var{newcmd} for Info that marks text by enclosing
15123it in strings that precede and follow the text. @xref{definfoenclose}.
15124
15125@item @@defivar @var{class} @var{instance-variable-name}
15126@itemx @@defivarx @var{class} @var{instance-variable-name}
15127This command formats a description for an instance variable in
15128object-oriented programming. The command is equivalent to @samp{@@defcv
15129@{Instance Variable@} @dots{}}. @xref{Definition Commands}, and
15130@ref{deffnx,, Def Cmds in Detail}.
15131
15132@item @@defmac @var{macroname} @var{arguments}@dots{}
15133@itemx @@defmacx @var{macroname} @var{arguments}@dots{}
15134Format a description for a macro. The command is equivalent to
15135@samp{@@deffn Macro @dots{}}. @xref{Definition Commands}, and
15136@ref{deffnx,, Def Cmds in Detail}.
15137
15138@item @@defmethod @var{class} @var{method-name} @var{arguments}@dots{}
15139@itemx @@defmethodx @var{class} @var{method-name} @var{arguments}@dots{}
15140Format a description for a method in object-oriented programming. The
15141command is equivalent to @samp{@@defop Method @dots{}}. Takes as
15142arguments the name of the class of the method, the name of the
15143method, and its arguments, if any. @xref{Definition Commands}, and
15144@ref{deffnx,, Def Cmds in Detail}.
15145
15146@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
15147@itemx @@defopx @var{category} @var{class} @var{name} @var{arguments}@dots{}
15148Format a description for an operation in object-oriented programming.
15149@code{@@defop} takes as arguments the overall name of the category of
15150operation, the name of the class of the operation, the name of the
15151operation, and its arguments, if any. @xref{Definition
15152Commands}, and @ref{Abstract Objects}.
15153
15154@item @@defopt @var{option-name}
15155@itemx @@defoptx @var{option-name}
15156Format a description for a user option. The command is equivalent to
15157@samp{@@defvr @{User Option@} @dots{}}. @xref{Definition Commands}, and
15158@ref{deffnx,, Def Cmds in Detail}.
15159
15160@item @@defspec @var{special-form-name} @var{arguments}@dots{}
15161@itemx @@defspecx @var{special-form-name} @var{arguments}@dots{}
15162Format a description for a special form. The command is equivalent to
15163@samp{@@deffn @{Special Form@} @dots{}}. @xref{Definition Commands},
15164and @ref{deffnx,, Def Cmds in Detail}.
15165
15166@item @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
15167@itemx @@deftpx @var{category} @var{name-of-type} @var{attributes}@dots{}
15168Format a description for a data type. @code{@@deftp} takes as arguments
15169the category, the name of the type (which is a word like @samp{int} or
15170@samp{float}), and then the names of attributes of objects of that type.
15171@xref{Definition Commands}, and @ref{Data Types}.
15172
15173@item @@deftypefn @var{classification} @var{data-type} @var{name} @var{arguments}@dots{}
15174@itemx @@deftypefnx @var{classification} @var{data-type} @var{name} @var{arguments}@dots{}
15175Format a description for a function or similar entity that may take
15176arguments and that is typed. @code{@@deftypefn} takes as arguments the
15177classification of entity being described, the type, the name of the
15178entity, and its arguments, if any. @xref{Definition Commands}, and
15179@ref{deffnx,, Def Cmds in Detail}.
15180
15181@item @@deftypefun @var{data-type} @var{function-name} @var{arguments}@dots{}
15182@itemx @@deftypefunx @var{data-type} @var{function-name} @var{arguments}@dots{}
15183Format a description for a function in a typed language.
15184The command is equivalent to @samp{@@deftypefn Function @dots{}}.
15185@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
15186
15187@item @@deftypeivar @var{class} @var{data-type} @var{variable-name}
15188@itemx @@deftypeivarx @var{class} @var{data-type} @var{variable-name}
15189Format a description for a typed instance variable in object-oriented
15190programming. @xref{Definition Commands}, and @ref{Abstract Objects}.
15191
15192@item @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
15193@itemx @@deftypemethodx @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
15194Format a description for a typed method in object-oriented programming.
15195@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
15196
15197@item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
15198@itemx @@deftypeopx @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
15199Format a description for a typed operation in object-oriented programming.
15200@xref{Definition Commands}, and @ref{Abstract Objects}.
15201
15202@item @@deftypevar @var{data-type} @var{variable-name}
15203@itemx @@deftypevarx @var{data-type} @var{variable-name}
15204Format a description for a variable in a typed language. The command is
15205equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition
15206Commands}, and @ref{deffnx,, Def Cmds in Detail}.
15207
15208@item @@deftypevr @var{classification} @var{data-type} @var{name}
15209@itemx @@deftypevrx @var{classification} @var{data-type} @var{name}
15210Format a description for something like a variable in a typed
15211language---an entity that records a value. Takes as arguments the
15212classification of entity being described, the type, and the name of the
15213entity. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in
15214Detail}.
15215
15216@item @@defun @var{function-name} @var{arguments}@dots{}
15217@itemx @@defunx @var{function-name} @var{arguments}@dots{}
15218Format a description for functions. The command is equivalent to
15219@samp{@@deffn Function @dots{}}. @xref{Definition Commands}, and
15220@ref{deffnx,, Def Cmds in Detail}.
15221
15222@item @@defvar @var{variable-name}
15223@itemx @@defvarx @var{variable-name}
15224Format a description for variables. The command is equivalent to
15225@samp{@@defvr Variable @dots{}}. @xref{Definition Commands}, and
15226@ref{deffnx,, Def Cmds in Detail}.
15227
15228@item @@defvr @var{category} @var{name}
15229@itemx @@defvrx @var{category} @var{name}
15230Format a description for any kind of variable. @code{@@defvr} takes
15231as arguments the category of the entity and the name of the entity.
15232@xref{Definition Commands},
15233and @ref{deffnx,, Def Cmds in Detail}.
15234
15235@item @@detailmenu
15236Avoid @code{makeinfo} confusion stemming from the detailed node listing
15237in a master menu. @xref{Master Menu Parts}.
15238
15239@item @@dfn@{@var{term}@}
15240Highlight the introductory or defining use of a term.
15241@xref{dfn, , @code{@@dfn}}.@refill
15242
15243@item @@dircategory @var{dirpart}
15244Specify a part of the Info directory menu where this file's entry should
15245go. @xref{Installing Dir Entries}.
15246
15247@item @@direntry
15248Begin the Info directory menu entry for this file. Pair with
15249@code{@@end direntry}. @xref{Installing Dir Entries}.
15250
15251@item @@display
15252Begin a kind of example. Like @code{@@example} (indent text, do not
15253fill), but do not select a new font. Pair with @code{@@end display}.
15254@xref{display, , @code{@@display}}.
15255
15256@item @@dmn@{@var{dimension}@}
15257Format a unit of measure, as in 12@dmn{pt}. Causes @TeX{} to insert a
15258thin space before @var{dimension}. No effect in Info.
15259@xref{dmn, , @code{@@dmn}}.
15260
15261@item @@documentdescription
15262Set the document description text, included in the HTML output. Pair
15263with @code{@@end documentdescription}. @xref{documentdescription,,
15264@code{@@documentdescription}}.
15265
15266@item @@documentencoding @var{enc}
15267Declare the input encoding to be @var{enc}.
15268@xref{documentencoding,, @code{@@documentencoding}}.
15269
15270@item @@documentlanguage @var{CC}
15271Declare the document language as the two-character ISO-639 abbreviation
15272@var{CC}. @xref{documentlanguage,, @code{@@documentlanguage}}.
15273
15274@item @@dotaccent@{@var{c}@}
15275Generate a dot accent over the character @var{c}, as in @dotaccent{o}.
15276@xref{Inserting Accents}.
15277
15278@item @@dots@{@}
15279Insert an ellipsis: @samp{@dots{}}.
15280@xref{dots, , @code{@@dots}}.@refill
15281
15282@item @@email@{@var{address}[, @var{displayed-text}]@}
15283Indicate an electronic mail address.
15284@xref{email, , @code{@@email}}.
15285
15286@item @@emph@{@var{text}@}
15287Highlight @var{text}; text is displayed in @emph{italics} in printed
15288output, and surrounded by asterisks in Info. @xref{Emphasis, ,
15289Emphasizing Text}.
15290
15291@item @@end @var{environment}
15292Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting
15293Commands,,@@-commands}.
15294
15295@item @@env@{@var{environment-variable}@}
15296Indicate an environment variable name, such as @env{PATH}.
15297@xref{env,, @code{@@env}}.
15298
15299@item @@enddots@{@}
15300Generate an end-of-sentence of ellipsis, like this @enddots{}
15301@xref{dots,,@code{@@dots@{@}}}.
15302
15303@item @@enumerate [@var{number-or-letter}]
15304Begin a numbered list, using @code{@@item} for each entry.
15305Optionally, start list with @var{number-or-letter}. Pair with
15306@code{@@end enumerate}. @xref{enumerate, ,
15307@code{@@enumerate}}.@refill
15308
15309@item @@equiv@{@}
15310Indicate to the reader the exact equivalence of two forms with a
15311glyph: @samp{@equiv{}}. @xref{Equivalence}.@refill
15312
15313@item @@error@{@}
15314Indicate to the reader with a glyph that the following text is
15315an error message: @samp{@error{}}. @xref{Error Glyph}.@refill
15316
15317@item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
15318@itemx @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
15319Specify page footings resp.@: headings for even-numbered (left-hand)
| 15052@xref{Inserting Accents}.
15053
15054@item @@@{
15055Stands for a left brace, @samp{@{}.
15056@xref{Braces Atsigns, , Inserting @@ and braces}.
15057
15058@item @@@}
15059Stands for a right-hand brace, @samp{@}}.@*
15060@xref{Braces Atsigns, , Inserting @@ and braces}.
15061
15062@item @@~
15063Generate a tilde accent over the next character, as in @~N.
15064@xref{Inserting Accents}.
15065
15066@item @@AA@{@}
15067@itemx @@aa@{@}
15068Generate the uppercase and lowercase Scandinavian A-ring letters,
15069respectively: @AA{}, @aa{}. @xref{Inserting Accents}.
15070
15071@item @@acronym@{@var{abbrev}@}
15072Tag @var{abbrev} as an acronym, that is, an abbreviation written in all
15073capital letters, such as `NASA'. @xref{acronym,, @code{acronym}}.
15074
15075@item @@AE@{@}
15076@itemx @@ae@{@}
15077Generate the uppercase and lowercase AE ligatures, respectively:
15078@AE{}, @ae{}. @xref{Inserting Accents}.
15079
15080@itemx @@afivepaper
15081Change page dimensions for the A5 paper size. @xref{A4 Paper}.
15082
15083@item @@afourlatex
15084@itemx @@afourpaper
15085@itemx @@afourwide
15086Change page dimensions for the A4 paper size. @xref{A4 Paper}.
15087
15088@item @@alias @var{new}=@var{existing}
15089Make the command @samp{@@@var{new}} an alias for the existing command
15090@samp{@@@var{existing}}. @xref{alias}.
15091
15092@item @@anchor@{@var{name}@}
15093Define @var{name} as the current location for use as a cross-reference
15094target. @xref{anchor,, @code{@@anchor}}.
15095
15096@item @@appendix @var{title}
15097Begin an appendix. The title appears in the table
15098of contents of a printed manual. In Info, the title is
15099underlined with asterisks. @xref{unnumbered & appendix, , The
15100@code{@@unnumbered} and @code{@@appendix} Commands}.@refill
15101
15102@item @@appendixsec @var{title}
15103@itemx @@appendixsection @var{title}
15104Begin an appendix section within an appendix. The section title appears
15105in the table of contents of a printed manual. In Info, the title is
15106underlined with equal signs. @code{@@appendixsection} is a longer
15107spelling of the @code{@@appendixsec} command. @xref{unnumberedsec
15108appendixsec heading, , Section Commands}.@refill
15109
15110@item @@appendixsubsec @var{title}
15111Begin an appendix subsection within an appendix. The title appears
15112in the table of contents of a printed manual. In Info, the title is
15113underlined with hyphens. @xref{unnumberedsubsec appendixsubsec
15114subheading, , Subsection Commands}.@refill
15115
15116@item @@appendixsubsubsec @var{title}
15117Begin an appendix subsubsection within an appendix subsection. The
15118title appears in the table of contents of a printed manual. In Info,
15119the title is underlined with periods. @xref{subsubsection,, The
15120`subsub' Commands}.@refill
15121
15122@item @@asis
15123Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to
15124print the table's first column without highlighting (``as is'').
15125@xref{Two-column Tables, , Making a Two-column Table}.@refill
15126
15127@item @@author @var{author}
15128Typeset @var{author} flushleft and underline it. @xref{title
15129subtitle author, , The @code{@@title} and @code{@@author}
15130Commands}.@refill
15131
15132@item @@b@{@var{text}@}
15133Print @var{text} in @b{bold} font. No effect in Info. @xref{Fonts}.@refill
15134
15135@ignore
15136@item @@br
15137Force a paragraph break. If used within a line, follow @code{@@br}
15138with braces. @xref{br, , @code{@@br}}.@refill
15139@end ignore
15140
15141@item @@bullet@{@}
15142Generate a large round dot, or the closest possible
15143thing to one. @xref{bullet, , @code{@@bullet}}.@refill
15144
15145@item @@bye
15146Stop formatting a file. The formatters do not see the contents of a
15147file following an @code{@@bye} command. @xref{Ending a File}.@refill
15148
15149@item @@c @var{comment}
15150Begin a comment in Texinfo. The rest of the line does not appear in
15151either the Info file or the printed manual. A synonym for
15152@code{@@comment}. @xref{Comments, , Comments}.@refill
15153
15154@item @@cartouche
15155Highlight an example or quotation by drawing a box with rounded
15156corners around it. Pair with @code{@@end cartouche}. No effect in
15157Info. @xref{cartouche, , Drawing Cartouches Around Examples}.)@refill
15158
15159@item @@center @var{line-of-text}
15160Center the line of text following the command.
15161@xref{titlefont center sp, , @code{@@center}}.@refill
15162
15163@item @@centerchap @var{line-of-text}
15164Like @code{@@chapter}, but centers the chapter title. @xref{chapter,,
15165@code{@@chapter}}.
15166
15167@item @@chapheading @var{title}
15168Print a chapter-like heading in the text, but not in the table of
15169contents of a printed manual. In Info, the title is underlined with
15170asterisks. @xref{majorheading & chapheading, , @code{@@majorheading}
15171and @code{@@chapheading}}.@refill
15172
15173@item @@chapter @var{title}
15174Begin a chapter. The chapter title appears in the table of
15175contents of a printed manual. In Info, the title is underlined with
15176asterisks. @xref{chapter, , @code{@@chapter}}.@refill
15177
15178@item @@cindex @var{entry}
15179Add @var{entry} to the index of concepts. @xref{Index Entries, ,
15180Defining the Entries of an Index}.@refill
15181
15182@item @@cite@{@var{reference}@}
15183Highlight the name of a book or other reference that lacks a
15184companion Info file. @xref{cite, , @code{@@cite}}.@refill
15185
15186@item @@clear @var{flag}
15187Unset @var{flag}, preventing the Texinfo formatting commands from
15188formatting text between subsequent pairs of @code{@@ifset @var{flag}}
15189and @code{@@end ifset} commands, and preventing
15190@code{@@value@{@var{flag}@}} from expanding to the value to which
15191@var{flag} is set.
15192@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
15193
15194@item @@code@{@var{sample-code}@}
15195Highlight text that is an expression, a syntactically complete token
15196of a program, or a program name. @xref{code, , @code{@@code}}.@refill
15197
15198@item @@command@{@var{command-name}@}
15199Indicate a command name, such as @command{ls}.
15200@xref{command,, @code{@@command}}.
15201
15202@item @@comment @var{comment}
15203Begin a comment in Texinfo. The rest of the line does not appear in
15204either the Info file or the printed manual. A synonym for @code{@@c}.
15205@xref{Comments}.
15206
15207@item @@contents
15208Print a complete table of contents. Has no effect in Info, which uses
15209menus instead. @xref{Contents, , Generating a Table of
15210Contents}.@refill
15211
15212@item @@copyright@{@}
15213Generate a copyright symbol. @xref{copyright symbol, ,
15214@code{@@copyright}}.@refill
15215
15216@ignore
15217@item @@ctrl@{@var{ctrl-char}@}
15218Describe an @sc{ascii} control character. Insert actual control character
15219into Info file. @xref{ctrl, , @code{@@ctrl}}.@refill
15220@end ignore
15221
15222@item @@defcodeindex @var{index-name}
15223Define a new index and its indexing command. Print entries in an
15224@code{@@code} font. @xref{New Indices, , Defining New
15225Indices}.@refill
15226
15227@item @@defcv @var{category} @var{class} @var{name}
15228@itemx @@defcvx @var{category} @var{class} @var{name}
15229Format a description for a variable associated with a class in
15230object-oriented programming. Takes three arguments: the category of
15231thing being defined, the class to which it belongs, and its name.
15232@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
15233
15234@item @@deffn @var{category} @var{name} @var{arguments}@dots{}
15235@itemx @@deffnx @var{category} @var{name} @var{arguments}@dots{}
15236Format a description for a function, interactive command, or similar
15237entity that may take arguments. @code{@@deffn} takes as arguments the
15238category of entity being described, the name of this particular
15239entity, and its arguments, if any. @xref{Definition Commands}.@refill
15240
15241@item @@defindex @var{index-name}
15242Define a new index and its indexing command. Print entries in a roman
15243font. @xref{New Indices, , Defining New Indices}.@refill
15244
15245@item @@definfoenclose @var{newcmd}, @var{before}, @var{after},
15246Create new @@-command @var{newcmd} for Info that marks text by enclosing
15247it in strings that precede and follow the text. @xref{definfoenclose}.
15248
15249@item @@defivar @var{class} @var{instance-variable-name}
15250@itemx @@defivarx @var{class} @var{instance-variable-name}
15251This command formats a description for an instance variable in
15252object-oriented programming. The command is equivalent to @samp{@@defcv
15253@{Instance Variable@} @dots{}}. @xref{Definition Commands}, and
15254@ref{deffnx,, Def Cmds in Detail}.
15255
15256@item @@defmac @var{macroname} @var{arguments}@dots{}
15257@itemx @@defmacx @var{macroname} @var{arguments}@dots{}
15258Format a description for a macro. The command is equivalent to
15259@samp{@@deffn Macro @dots{}}. @xref{Definition Commands}, and
15260@ref{deffnx,, Def Cmds in Detail}.
15261
15262@item @@defmethod @var{class} @var{method-name} @var{arguments}@dots{}
15263@itemx @@defmethodx @var{class} @var{method-name} @var{arguments}@dots{}
15264Format a description for a method in object-oriented programming. The
15265command is equivalent to @samp{@@defop Method @dots{}}. Takes as
15266arguments the name of the class of the method, the name of the
15267method, and its arguments, if any. @xref{Definition Commands}, and
15268@ref{deffnx,, Def Cmds in Detail}.
15269
15270@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
15271@itemx @@defopx @var{category} @var{class} @var{name} @var{arguments}@dots{}
15272Format a description for an operation in object-oriented programming.
15273@code{@@defop} takes as arguments the overall name of the category of
15274operation, the name of the class of the operation, the name of the
15275operation, and its arguments, if any. @xref{Definition
15276Commands}, and @ref{Abstract Objects}.
15277
15278@item @@defopt @var{option-name}
15279@itemx @@defoptx @var{option-name}
15280Format a description for a user option. The command is equivalent to
15281@samp{@@defvr @{User Option@} @dots{}}. @xref{Definition Commands}, and
15282@ref{deffnx,, Def Cmds in Detail}.
15283
15284@item @@defspec @var{special-form-name} @var{arguments}@dots{}
15285@itemx @@defspecx @var{special-form-name} @var{arguments}@dots{}
15286Format a description for a special form. The command is equivalent to
15287@samp{@@deffn @{Special Form@} @dots{}}. @xref{Definition Commands},
15288and @ref{deffnx,, Def Cmds in Detail}.
15289
15290@item @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
15291@itemx @@deftpx @var{category} @var{name-of-type} @var{attributes}@dots{}
15292Format a description for a data type. @code{@@deftp} takes as arguments
15293the category, the name of the type (which is a word like @samp{int} or
15294@samp{float}), and then the names of attributes of objects of that type.
15295@xref{Definition Commands}, and @ref{Data Types}.
15296
15297@item @@deftypefn @var{classification} @var{data-type} @var{name} @var{arguments}@dots{}
15298@itemx @@deftypefnx @var{classification} @var{data-type} @var{name} @var{arguments}@dots{}
15299Format a description for a function or similar entity that may take
15300arguments and that is typed. @code{@@deftypefn} takes as arguments the
15301classification of entity being described, the type, the name of the
15302entity, and its arguments, if any. @xref{Definition Commands}, and
15303@ref{deffnx,, Def Cmds in Detail}.
15304
15305@item @@deftypefun @var{data-type} @var{function-name} @var{arguments}@dots{}
15306@itemx @@deftypefunx @var{data-type} @var{function-name} @var{arguments}@dots{}
15307Format a description for a function in a typed language.
15308The command is equivalent to @samp{@@deftypefn Function @dots{}}.
15309@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
15310
15311@item @@deftypeivar @var{class} @var{data-type} @var{variable-name}
15312@itemx @@deftypeivarx @var{class} @var{data-type} @var{variable-name}
15313Format a description for a typed instance variable in object-oriented
15314programming. @xref{Definition Commands}, and @ref{Abstract Objects}.
15315
15316@item @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
15317@itemx @@deftypemethodx @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
15318Format a description for a typed method in object-oriented programming.
15319@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
15320
15321@item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
15322@itemx @@deftypeopx @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
15323Format a description for a typed operation in object-oriented programming.
15324@xref{Definition Commands}, and @ref{Abstract Objects}.
15325
15326@item @@deftypevar @var{data-type} @var{variable-name}
15327@itemx @@deftypevarx @var{data-type} @var{variable-name}
15328Format a description for a variable in a typed language. The command is
15329equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition
15330Commands}, and @ref{deffnx,, Def Cmds in Detail}.
15331
15332@item @@deftypevr @var{classification} @var{data-type} @var{name}
15333@itemx @@deftypevrx @var{classification} @var{data-type} @var{name}
15334Format a description for something like a variable in a typed
15335language---an entity that records a value. Takes as arguments the
15336classification of entity being described, the type, and the name of the
15337entity. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in
15338Detail}.
15339
15340@item @@defun @var{function-name} @var{arguments}@dots{}
15341@itemx @@defunx @var{function-name} @var{arguments}@dots{}
15342Format a description for functions. The command is equivalent to
15343@samp{@@deffn Function @dots{}}. @xref{Definition Commands}, and
15344@ref{deffnx,, Def Cmds in Detail}.
15345
15346@item @@defvar @var{variable-name}
15347@itemx @@defvarx @var{variable-name}
15348Format a description for variables. The command is equivalent to
15349@samp{@@defvr Variable @dots{}}. @xref{Definition Commands}, and
15350@ref{deffnx,, Def Cmds in Detail}.
15351
15352@item @@defvr @var{category} @var{name}
15353@itemx @@defvrx @var{category} @var{name}
15354Format a description for any kind of variable. @code{@@defvr} takes
15355as arguments the category of the entity and the name of the entity.
15356@xref{Definition Commands},
15357and @ref{deffnx,, Def Cmds in Detail}.
15358
15359@item @@detailmenu
15360Avoid @code{makeinfo} confusion stemming from the detailed node listing
15361in a master menu. @xref{Master Menu Parts}.
15362
15363@item @@dfn@{@var{term}@}
15364Highlight the introductory or defining use of a term.
15365@xref{dfn, , @code{@@dfn}}.@refill
15366
15367@item @@dircategory @var{dirpart}
15368Specify a part of the Info directory menu where this file's entry should
15369go. @xref{Installing Dir Entries}.
15370
15371@item @@direntry
15372Begin the Info directory menu entry for this file. Pair with
15373@code{@@end direntry}. @xref{Installing Dir Entries}.
15374
15375@item @@display
15376Begin a kind of example. Like @code{@@example} (indent text, do not
15377fill), but do not select a new font. Pair with @code{@@end display}.
15378@xref{display, , @code{@@display}}.
15379
15380@item @@dmn@{@var{dimension}@}
15381Format a unit of measure, as in 12@dmn{pt}. Causes @TeX{} to insert a
15382thin space before @var{dimension}. No effect in Info.
15383@xref{dmn, , @code{@@dmn}}.
15384
15385@item @@documentdescription
15386Set the document description text, included in the HTML output. Pair
15387with @code{@@end documentdescription}. @xref{documentdescription,,
15388@code{@@documentdescription}}.
15389
15390@item @@documentencoding @var{enc}
15391Declare the input encoding to be @var{enc}.
15392@xref{documentencoding,, @code{@@documentencoding}}.
15393
15394@item @@documentlanguage @var{CC}
15395Declare the document language as the two-character ISO-639 abbreviation
15396@var{CC}. @xref{documentlanguage,, @code{@@documentlanguage}}.
15397
15398@item @@dotaccent@{@var{c}@}
15399Generate a dot accent over the character @var{c}, as in @dotaccent{o}.
15400@xref{Inserting Accents}.
15401
15402@item @@dots@{@}
15403Insert an ellipsis: @samp{@dots{}}.
15404@xref{dots, , @code{@@dots}}.@refill
15405
15406@item @@email@{@var{address}[, @var{displayed-text}]@}
15407Indicate an electronic mail address.
15408@xref{email, , @code{@@email}}.
15409
15410@item @@emph@{@var{text}@}
15411Highlight @var{text}; text is displayed in @emph{italics} in printed
15412output, and surrounded by asterisks in Info. @xref{Emphasis, ,
15413Emphasizing Text}.
15414
15415@item @@end @var{environment}
15416Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting
15417Commands,,@@-commands}.
15418
15419@item @@env@{@var{environment-variable}@}
15420Indicate an environment variable name, such as @env{PATH}.
15421@xref{env,, @code{@@env}}.
15422
15423@item @@enddots@{@}
15424Generate an end-of-sentence of ellipsis, like this @enddots{}
15425@xref{dots,,@code{@@dots@{@}}}.
15426
15427@item @@enumerate [@var{number-or-letter}]
15428Begin a numbered list, using @code{@@item} for each entry.
15429Optionally, start list with @var{number-or-letter}. Pair with
15430@code{@@end enumerate}. @xref{enumerate, ,
15431@code{@@enumerate}}.@refill
15432
15433@item @@equiv@{@}
15434Indicate to the reader the exact equivalence of two forms with a
15435glyph: @samp{@equiv{}}. @xref{Equivalence}.@refill
15436
15437@item @@error@{@}
15438Indicate to the reader with a glyph that the following text is
15439an error message: @samp{@error{}}. @xref{Error Glyph}.@refill
15440
15441@item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
15442@itemx @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
15443Specify page footings resp.@: headings for even-numbered (left-hand)
|
15320pages. Only allowed inside @code{@@iftex}. @xref{Custom Headings, ,
| 15444pages. @xref{Custom Headings, ,
|
15321How to Make Your Own Headings}.@refill
15322
15323@item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
15324@itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
15325Specify page footings resp.@: headings for every page. Not relevant to
15326Info. @xref{Custom Headings, , How to Make Your Own Headings}.@refill
15327
15328@item @@example
15329Begin an example. Indent text, do not fill, and select fixed-width font.
15330Pair with @code{@@end example}. @xref{example, ,
15331@code{@@example}}.@refill
15332
15333@item @@exampleindent @var{indent}
15334Indent example-like environments by @var{indent} number of spaces
15335(perhaps 0). @xref{exampleindent,, Paragraph Indenting}.
15336
15337@item @@exclamdown@{@}
15338Produce an upside-down exclamation point. @xref{Inserting Accents}.
15339
15340@item @@exdent @var{line-of-text}
15341Remove any indentation a line might have. @xref{exdent, ,
15342Undoing the Indentation of a Line}.@refill
15343
15344@item @@expansion@{@}
15345Indicate the result of a macro expansion to the reader with a special
15346glyph: @samp{@expansion{}}.
15347@xref{expansion, , @expansion{} Indicating an Expansion}.@refill
15348
15349@item @@file@{@var{filename}@}
15350Highlight the name of a file, buffer, node, or directory. @xref{file, ,
15351@code{@@file}}.@refill
15352
15353@item @@finalout
15354Prevent @TeX{} from printing large black warning rectangles beside
15355over-wide lines. @xref{Overfull hboxes}.@refill
15356
15357@item @@findex @var{entry}
15358Add @var{entry} to the index of functions. @xref{Index Entries, ,
15359Defining the Entries of an Index}.@refill
15360
15361@item @@flushleft
15362@itemx @@flushright
15363Left justify every line but leave the right end ragged.
15364Leave font as is. Pair with @code{@@end flushleft}.
15365@code{@@flushright} analogous.
15366@xref{flushleft & flushright, , @code{@@flushleft} and
15367@code{@@flushright}}.@refill
15368
15369@item @@footnote@{@var{text-of-footnote}@}
15370Enter a footnote. Footnote text is printed at the bottom of the page
15371by @TeX{}; Info may format in either `End' node or `Separate' node style.
15372@xref{Footnotes}.@refill
15373
15374@item @@footnotestyle @var{style}
15375Specify an Info file's footnote style, either @samp{end} for the end
15376node style or @samp{separate} for the separate node style.
15377@xref{Footnotes}.@refill
15378
15379@item @@format
15380Begin a kind of example. Like @code{@@display}, but do not narrow the
15381margins. Pair with @code{@@end format}. @xref{example,,
15382@code{@@example}}.
15383
15384@item @@ftable @var{formatting-command}
15385Begin a two-column table, using @code{@@item} for each entry.
15386Automatically enter each of the items in the first column into the
15387index of functions. Pair with @code{@@end ftable}. The same as
15388@code{@@table}, except for indexing. @xref{ftable vtable, ,
15389@code{@@ftable} and @code{@@vtable}}.@refill
15390
15391@item @@group
15392Hold text together that must appear on one printed page. Pair with
15393@code{@@end group}. Not relevant to Info. @xref{group, ,
15394@code{@@group}}.@refill
15395
15396@item @@H@{@var{c}@}
15397Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}.
15398
15399@item @@heading @var{title}
15400Print an unnumbered section-like heading in the text, but not in the
15401table of contents of a printed manual. In Info, the title is
15402underlined with equal signs. @xref{unnumberedsec appendixsec heading,
15403, Section Commands}.@refill
15404
15405@item @@headings @var{on-off-single-double}
15406Turn page headings on or off, and/or specify single-sided or double-sided
15407page headings for printing. @xref{headings on off, , The
15408@code{@@headings} Command}.
15409
15410@item @@html
15411Enter HTML completely. Pair with @code{@@end html}. @xref{Raw
15412Formatter Commands}.
15413
15414@item @@hyphenation@{@var{hy-phen-a-ted words}@}
15415Explicitly define hyphenation points. @xref{- and hyphenation,,
15416@code{@@-} and @code{@@hyphenation}}.
15417
15418@item @@i@{@var{text}@}
| 15445How to Make Your Own Headings}.@refill
15446
15447@item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
15448@itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
15449Specify page footings resp.@: headings for every page. Not relevant to
15450Info. @xref{Custom Headings, , How to Make Your Own Headings}.@refill
15451
15452@item @@example
15453Begin an example. Indent text, do not fill, and select fixed-width font.
15454Pair with @code{@@end example}. @xref{example, ,
15455@code{@@example}}.@refill
15456
15457@item @@exampleindent @var{indent}
15458Indent example-like environments by @var{indent} number of spaces
15459(perhaps 0). @xref{exampleindent,, Paragraph Indenting}.
15460
15461@item @@exclamdown@{@}
15462Produce an upside-down exclamation point. @xref{Inserting Accents}.
15463
15464@item @@exdent @var{line-of-text}
15465Remove any indentation a line might have. @xref{exdent, ,
15466Undoing the Indentation of a Line}.@refill
15467
15468@item @@expansion@{@}
15469Indicate the result of a macro expansion to the reader with a special
15470glyph: @samp{@expansion{}}.
15471@xref{expansion, , @expansion{} Indicating an Expansion}.@refill
15472
15473@item @@file@{@var{filename}@}
15474Highlight the name of a file, buffer, node, or directory. @xref{file, ,
15475@code{@@file}}.@refill
15476
15477@item @@finalout
15478Prevent @TeX{} from printing large black warning rectangles beside
15479over-wide lines. @xref{Overfull hboxes}.@refill
15480
15481@item @@findex @var{entry}
15482Add @var{entry} to the index of functions. @xref{Index Entries, ,
15483Defining the Entries of an Index}.@refill
15484
15485@item @@flushleft
15486@itemx @@flushright
15487Left justify every line but leave the right end ragged.
15488Leave font as is. Pair with @code{@@end flushleft}.
15489@code{@@flushright} analogous.
15490@xref{flushleft & flushright, , @code{@@flushleft} and
15491@code{@@flushright}}.@refill
15492
15493@item @@footnote@{@var{text-of-footnote}@}
15494Enter a footnote. Footnote text is printed at the bottom of the page
15495by @TeX{}; Info may format in either `End' node or `Separate' node style.
15496@xref{Footnotes}.@refill
15497
15498@item @@footnotestyle @var{style}
15499Specify an Info file's footnote style, either @samp{end} for the end
15500node style or @samp{separate} for the separate node style.
15501@xref{Footnotes}.@refill
15502
15503@item @@format
15504Begin a kind of example. Like @code{@@display}, but do not narrow the
15505margins. Pair with @code{@@end format}. @xref{example,,
15506@code{@@example}}.
15507
15508@item @@ftable @var{formatting-command}
15509Begin a two-column table, using @code{@@item} for each entry.
15510Automatically enter each of the items in the first column into the
15511index of functions. Pair with @code{@@end ftable}. The same as
15512@code{@@table}, except for indexing. @xref{ftable vtable, ,
15513@code{@@ftable} and @code{@@vtable}}.@refill
15514
15515@item @@group
15516Hold text together that must appear on one printed page. Pair with
15517@code{@@end group}. Not relevant to Info. @xref{group, ,
15518@code{@@group}}.@refill
15519
15520@item @@H@{@var{c}@}
15521Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}.
15522
15523@item @@heading @var{title}
15524Print an unnumbered section-like heading in the text, but not in the
15525table of contents of a printed manual. In Info, the title is
15526underlined with equal signs. @xref{unnumberedsec appendixsec heading,
15527, Section Commands}.@refill
15528
15529@item @@headings @var{on-off-single-double}
15530Turn page headings on or off, and/or specify single-sided or double-sided
15531page headings for printing. @xref{headings on off, , The
15532@code{@@headings} Command}.
15533
15534@item @@html
15535Enter HTML completely. Pair with @code{@@end html}. @xref{Raw
15536Formatter Commands}.
15537
15538@item @@hyphenation@{@var{hy-phen-a-ted words}@}
15539Explicitly define hyphenation points. @xref{- and hyphenation,,
15540@code{@@-} and @code{@@hyphenation}}.
15541
15542@item @@i@{@var{text}@}
|
15419Print @var{text} in @i{italic} font. No effect in Info.
15420@xref{Fonts}.@refill
| 15543Print @var{text} in @i{italic} font. No effect in Info. @xref{Fonts}.
|
15421
15422@item @@ifclear @var{flag}
15423If @var{flag} is cleared, the Texinfo formatting commands format text
15424between @code{@@ifclear @var{flag}} and the following @code{@@end
15425ifclear} command.
15426@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
15427
15428@item @@ifhtml
15429@itemx @@ifinfo
15430Begin a stretch of text that will be ignored by @TeX{} when it typesets
| 15544
15545@item @@ifclear @var{flag}
15546If @var{flag} is cleared, the Texinfo formatting commands format text
15547between @code{@@ifclear @var{flag}} and the following @code{@@end
15548ifclear} command.
15549@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
15550
15551@item @@ifhtml
15552@itemx @@ifinfo
15553Begin a stretch of text that will be ignored by @TeX{} when it typesets
|
15431the printed manual. The text appears only in the HTML resp.@: Info
15432file. Pair with @code{@@end ifhtml} resp.@: @code{@@end ifinfo}.
15433@xref{Conditionals}.
| 15554the printed manual. @code{@@ifhtml} text appears only in the HTML
15555output. @code{@@ifinfo} output appears in both Info and (for historical
15556compatibility) plain text output . Pair with @code{@@end ifhtml}
15557resp.@: @code{@@end ifinfo}. @xref{Conditionals}.
|
15434
15435@item @@ifnothtml
15436@itemx @@ifnotinfo
| 15558
15559@item @@ifnothtml
15560@itemx @@ifnotinfo
|
| 15561@itemx @@ifnotplaintext
|
15437@itemx @@ifnottex
15438Begin a stretch of text that will be ignored in one output format but
| 15562@itemx @@ifnottex
15563Begin a stretch of text that will be ignored in one output format but
|
15439not the others. The text appears only in the format not specified.
15440Pair with @code{@@end ifnothtml} resp.@: @code{@@end ifnotinfo} resp.@:
15441@code{@@end ifnotinfo}. @xref{Conditionals}.
| 15564not the others. The text appears in the formats not specified:
15565@code{@@ifnothtml} text is omitted from html output, etc. The exception
15566is @code{@@ifnotinfo} text, which is omitted from plain text output as
15567well as Info output. Pair with @code{@@end ifnothtml} resp.@:
15568@code{@@end ifnotinfo} resp.@: @code{@@end ifnotplaintext} resp.@:
15569@code{@@end ifnottex}. @xref{Conditionals}.
|
15442
| 15570
|
| 15571@item @@ifplaintext
15572Begin a stretch of text that appears only in the plain text output.
15573Pair with @code{@@end ifplaintext}. @xref{Conditionals}.
15574
|
15443@item @@ifset @var{flag}
15444If @var{flag} is set, the Texinfo formatting commands format text
15445between @code{@@ifset @var{flag}} and the following @code{@@end ifset}
15446command.
15447@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
15448
15449@item @@iftex
15450Begin a stretch of text that will not appear in the Info file, but
15451will be processed only by @TeX{}. Pair with @code{@@end iftex}.
15452@xref{Conditionals, , Conditionally Visible Text}.@refill
15453
15454@item @@ignore
15455Begin a stretch of text that will not appear in either the Info file
15456or the printed output. Pair with @code{@@end ignore}.
15457@xref{Comments, , Comments and Ignored Text}.@refill
15458
15459@item @@image@{@var{filename}, [@var{width}], [@var{height}], [@var{alt}], [@var{ext}]@}
15460Include graphics image in external @var{filename} scaled to the given
15461@var{width} and/or @var{height}, using @var{alt} text and looking for
15462@samp{@var{filename}.@var{ext}} in HTML. @xref{Images}.
15463
15464@item @@include @var{filename}
15465Incorporate the contents of the file @var{filename} into the Info file
15466or printed document. @xref{Include Files}.@refill
15467
15468@item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@}
15469Make a cross reference to an Info file for which there is no printed
15470manual. @xref{inforef, , Cross references using
15471@code{@@inforef}}.@refill
15472
15473@item \input @var{macro-definitions-file}
15474Use the specified macro definitions file. This command is used only
15475in the first line of a Texinfo file to cause @TeX{} to make use of the
15476@file{texinfo} macro definitions file. The backslash in @code{\input}
15477is used instead of an @code{@@} because @TeX{} does not
15478recognize @code{@@} until after it has read the definitions file.
| 15575@item @@ifset @var{flag}
15576If @var{flag} is set, the Texinfo formatting commands format text
15577between @code{@@ifset @var{flag}} and the following @code{@@end ifset}
15578command.
15579@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
15580
15581@item @@iftex
15582Begin a stretch of text that will not appear in the Info file, but
15583will be processed only by @TeX{}. Pair with @code{@@end iftex}.
15584@xref{Conditionals, , Conditionally Visible Text}.@refill
15585
15586@item @@ignore
15587Begin a stretch of text that will not appear in either the Info file
15588or the printed output. Pair with @code{@@end ignore}.
15589@xref{Comments, , Comments and Ignored Text}.@refill
15590
15591@item @@image@{@var{filename}, [@var{width}], [@var{height}], [@var{alt}], [@var{ext}]@}
15592Include graphics image in external @var{filename} scaled to the given
15593@var{width} and/or @var{height}, using @var{alt} text and looking for
15594@samp{@var{filename}.@var{ext}} in HTML. @xref{Images}.
15595
15596@item @@include @var{filename}
15597Incorporate the contents of the file @var{filename} into the Info file
15598or printed document. @xref{Include Files}.@refill
15599
15600@item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@}
15601Make a cross reference to an Info file for which there is no printed
15602manual. @xref{inforef, , Cross references using
15603@code{@@inforef}}.@refill
15604
15605@item \input @var{macro-definitions-file}
15606Use the specified macro definitions file. This command is used only
15607in the first line of a Texinfo file to cause @TeX{} to make use of the
15608@file{texinfo} macro definitions file. The backslash in @code{\input}
15609is used instead of an @code{@@} because @TeX{} does not
15610recognize @code{@@} until after it has read the definitions file.
|
15479@xref{Header, , The Texinfo File Header}.@refill
| 15611@xref{Texinfo File Header}.
|
15480
15481@item @@item
15482Indicate the beginning of a marked paragraph for @code{@@itemize} and
15483@code{@@enumerate}; indicate the beginning of the text of a first column
15484entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}.
15485@xref{Lists and Tables}.@refill
15486
15487@item @@itemize @var{mark-generating-character-or-command}
15488Produce a sequence of indented paragraphs, with a mark inside the left
15489margin at the beginning of each paragraph. Pair with @code{@@end
15490itemize}. @xref{itemize, , @code{@@itemize}}.@refill
15491
15492@item @@itemx
15493Like @code{@@item} but do not generate extra vertical space above the
15494item text. @xref{itemx, , @code{@@itemx}}.@refill
15495
15496@item @@kbd@{@var{keyboard-characters}@}
15497Indicate text that is characters of input to be typed by
15498users. @xref{kbd, , @code{@@kbd}}.@refill
15499
15500@item @@kbdinputstyle @var{style}
15501Specify when @code{@@kbd} should use a font distinct from @code{@@code}.
15502@xref{kbd, , @code{@@kbd}}.@refill
15503
15504@item @@key@{@var{key-name}@}
15505Indicate a name for a key on a keyboard.
15506@xref{key, , @code{@@key}}.@refill
15507
15508@item @@kindex @var{entry}
15509Add @var{entry} to the index of keys.
15510@xref{Index Entries, , Defining the Entries of an Index}.@refill
15511
15512@item @@L@{@}
15513@itemx @@l@{@}
15514Generate the uppercase and lowercase Polish suppressed-L letters,
15515respectively: @L{}, @l{}.
15516
15517@c Possibly this can be tossed now that we have macros. --karl, 16sep96.
15518@c Yes, let's toss it, it's pretty weird. --karl, 15jun97.
15519@c @item @@global@@let@var{new-command}=@var{existing-command}
15520@c Equate a new highlighting command with an existing one. Only for
15521@c @TeX{}. Write definition inside of @code{@@iftex} @dots{} @code{@@end
15522@c iftex}. @xref{Customized Highlighting}.@refill
15523
15524@item @@lisp
15525Begin an example of Lisp code. Indent text, do not fill, and select
15526fixed-width font. Pair with @code{@@end lisp}. @xref{lisp, , @code{@@lisp}}.
15527
15528@item @@lowersections
15529Change subsequent chapters to sections, sections to subsections, and so
15530on. @xref{Raise/lower sections, , @code{@@raisesections} and
15531@code{@@lowersections}}.@refill
15532
15533@item @@macro @var{macroname} @{@var{params}@}
15534Define a new Texinfo command @code{@@@var{macroname}@{@var{params}@}}.
15535Only supported by @code{makeinfo} and @code{texi2dvi}. @xref{Defining
15536Macros}.
15537
15538@item @@majorheading @var{title}
15539Print a chapter-like heading in the text, but not in the table of
15540contents of a printed manual. Generate more vertical whitespace before
15541the heading than the @code{@@chapheading} command. In Info, the chapter
15542heading line is underlined with asterisks. @xref{majorheading &
15543chapheading, , @code{@@majorheading} and @code{@@chapheading}}.@refill
15544
15545@item @@math@{@var{mathematical-expression}@}
15546Format a mathematical expression.
15547@xref{math, , @code{@@math}: Inserting Mathematical Expressions}.
15548
15549@item @@menu
15550Mark the beginning of a menu of nodes in Info. No effect in a printed
15551manual. Pair with @code{@@end menu}. @xref{Menus}.@refill
15552
15553@item @@minus@{@}
15554Generate a minus sign, `@minus{}'. @xref{minus, , @code{@@minus}}.@refill
15555
15556@item @@multitable @var{column-width-spec}
15557Begin a multi-column table. Pair with @code{@@end multitable}.
15558@xref{Multitable Column Widths}.
15559
15560@item @@need @var{n}
15561Start a new page in a printed manual if fewer than @var{n} mils
15562(thousandths of an inch) remain on the current page. @xref{need, ,
15563@code{@@need}}.@refill
15564
15565@item @@node @var{name}, @var{next}, @var{previous}, @var{up}
15566Define the beginning of a new node in Info, and serve as a locator for
15567references for @TeX{}. @xref{node, , @code{@@node}}.@refill
15568
15569@item @@noindent
15570Prevent text from being indented as if it were a new paragraph.
15571@xref{noindent, , @code{@@noindent}}.@refill
15572
15573@item @@novalidate
15574Suppress validation of node references, omit creation of auxiliary files
15575with @TeX{}. Use before @code{@@setfilename}. @xref{Pointer Validation}.
15576
15577@item @@O@{@}
15578@itemx @@o@{@}
15579Generate the uppercase and lowercase O-with-slash letters, respectively:
15580@O{}, @o{}.
15581
15582@item @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
15583@itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
15584Specify page footings resp.@: headings for odd-numbered (right-hand)
| 15612
15613@item @@item
15614Indicate the beginning of a marked paragraph for @code{@@itemize} and
15615@code{@@enumerate}; indicate the beginning of the text of a first column
15616entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}.
15617@xref{Lists and Tables}.@refill
15618
15619@item @@itemize @var{mark-generating-character-or-command}
15620Produce a sequence of indented paragraphs, with a mark inside the left
15621margin at the beginning of each paragraph. Pair with @code{@@end
15622itemize}. @xref{itemize, , @code{@@itemize}}.@refill
15623
15624@item @@itemx
15625Like @code{@@item} but do not generate extra vertical space above the
15626item text. @xref{itemx, , @code{@@itemx}}.@refill
15627
15628@item @@kbd@{@var{keyboard-characters}@}
15629Indicate text that is characters of input to be typed by
15630users. @xref{kbd, , @code{@@kbd}}.@refill
15631
15632@item @@kbdinputstyle @var{style}
15633Specify when @code{@@kbd} should use a font distinct from @code{@@code}.
15634@xref{kbd, , @code{@@kbd}}.@refill
15635
15636@item @@key@{@var{key-name}@}
15637Indicate a name for a key on a keyboard.
15638@xref{key, , @code{@@key}}.@refill
15639
15640@item @@kindex @var{entry}
15641Add @var{entry} to the index of keys.
15642@xref{Index Entries, , Defining the Entries of an Index}.@refill
15643
15644@item @@L@{@}
15645@itemx @@l@{@}
15646Generate the uppercase and lowercase Polish suppressed-L letters,
15647respectively: @L{}, @l{}.
15648
15649@c Possibly this can be tossed now that we have macros. --karl, 16sep96.
15650@c Yes, let's toss it, it's pretty weird. --karl, 15jun97.
15651@c @item @@global@@let@var{new-command}=@var{existing-command}
15652@c Equate a new highlighting command with an existing one. Only for
15653@c @TeX{}. Write definition inside of @code{@@iftex} @dots{} @code{@@end
15654@c iftex}. @xref{Customized Highlighting}.@refill
15655
15656@item @@lisp
15657Begin an example of Lisp code. Indent text, do not fill, and select
15658fixed-width font. Pair with @code{@@end lisp}. @xref{lisp, , @code{@@lisp}}.
15659
15660@item @@lowersections
15661Change subsequent chapters to sections, sections to subsections, and so
15662on. @xref{Raise/lower sections, , @code{@@raisesections} and
15663@code{@@lowersections}}.@refill
15664
15665@item @@macro @var{macroname} @{@var{params}@}
15666Define a new Texinfo command @code{@@@var{macroname}@{@var{params}@}}.
15667Only supported by @code{makeinfo} and @code{texi2dvi}. @xref{Defining
15668Macros}.
15669
15670@item @@majorheading @var{title}
15671Print a chapter-like heading in the text, but not in the table of
15672contents of a printed manual. Generate more vertical whitespace before
15673the heading than the @code{@@chapheading} command. In Info, the chapter
15674heading line is underlined with asterisks. @xref{majorheading &
15675chapheading, , @code{@@majorheading} and @code{@@chapheading}}.@refill
15676
15677@item @@math@{@var{mathematical-expression}@}
15678Format a mathematical expression.
15679@xref{math, , @code{@@math}: Inserting Mathematical Expressions}.
15680
15681@item @@menu
15682Mark the beginning of a menu of nodes in Info. No effect in a printed
15683manual. Pair with @code{@@end menu}. @xref{Menus}.@refill
15684
15685@item @@minus@{@}
15686Generate a minus sign, `@minus{}'. @xref{minus, , @code{@@minus}}.@refill
15687
15688@item @@multitable @var{column-width-spec}
15689Begin a multi-column table. Pair with @code{@@end multitable}.
15690@xref{Multitable Column Widths}.
15691
15692@item @@need @var{n}
15693Start a new page in a printed manual if fewer than @var{n} mils
15694(thousandths of an inch) remain on the current page. @xref{need, ,
15695@code{@@need}}.@refill
15696
15697@item @@node @var{name}, @var{next}, @var{previous}, @var{up}
15698Define the beginning of a new node in Info, and serve as a locator for
15699references for @TeX{}. @xref{node, , @code{@@node}}.@refill
15700
15701@item @@noindent
15702Prevent text from being indented as if it were a new paragraph.
15703@xref{noindent, , @code{@@noindent}}.@refill
15704
15705@item @@novalidate
15706Suppress validation of node references, omit creation of auxiliary files
15707with @TeX{}. Use before @code{@@setfilename}. @xref{Pointer Validation}.
15708
15709@item @@O@{@}
15710@itemx @@o@{@}
15711Generate the uppercase and lowercase O-with-slash letters, respectively:
15712@O{}, @o{}.
15713
15714@item @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
15715@itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
15716Specify page footings resp.@: headings for odd-numbered (right-hand)
|
15585pages. Only allowed inside @code{@@iftex}. @xref{Custom Headings, ,
| 15717pages. @xref{Custom Headings, ,
|
15586How to Make Your Own Headings}.@refill
15587
15588@item @@OE@{@}
15589@itemx @@oe@{@}
15590Generate the uppercase and lowercase OE ligatures, respectively:
15591@OE{}, @oe{}. @xref{Inserting Accents}.
15592
15593@item @@option@{@var{option-name}@}
15594Indicate a command-line option, such as @option{-l} or @option{--help}.
15595@xref{option,, @code{@@option}}.
15596
15597@item @@page
15598Start a new page in a printed manual. No effect in Info.
15599@xref{page, , @code{@@page}}.@refill
15600
15601@item @@pagesizes [@var{width}][, @var{height}]
15602Change page dimensions. @xref{pagesizes}.
15603
15604@item @@paragraphindent @var{indent}
15605Indent paragraphs by @var{indent} number of spaces (perhaps 0); preserve
15606source file indentation if @var{indent} is @code{asis}.
15607@xref{paragraphindent,, Paragraph Indenting}.
15608
15609@item @@pindex @var{entry}
15610Add @var{entry} to the index of programs. @xref{Index Entries, , Defining
15611the Entries of an Index}.@refill
15612
15613@item @@point@{@}
15614Indicate the position of point in a buffer to the reader with a
15615glyph: @samp{@point{}}. @xref{Point Glyph, , Indicating
15616Point in a Buffer}.@refill
15617
15618@item @@pounds@{@}
15619Generate the pounds sterling currency sign.
15620@xref{pounds,,@code{@@pounds@{@}}}.
15621
15622@item @@print@{@}
15623Indicate printed output to the reader with a glyph:
15624@samp{@print{}}. @xref{Print Glyph}.@refill
15625
15626@item @@printindex @var{index-name}
15627Print an alphabetized two-column index in a printed manual or generate
15628an alphabetized menu of index entries for Info. @xref{Printing
15629Indices & Menus}.@refill
15630
15631@item @@pxref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
15632Make a reference that starts with a lower case `see' in a printed
15633manual. Use within parentheses only. Do not follow command with a
15634punctuation mark---the Info formatting commands automatically insert
15635terminating punctuation as needed. Only the first argument is mandatory.
15636@xref{pxref, , @code{@@pxref}}.@refill
15637
15638@item @@questiondown@{@}
15639Generate an upside-down question mark. @xref{Inserting Accents}.
15640
15641@item @@quotation
15642Narrow the margins to indicate text that is quoted from another real
15643or imaginary work. Write command on a line of its own. Pair with
15644@code{@@end quotation}. @xref{quotation, ,
15645@code{@@quotation}}.@refill
15646
15647@item @@r@{@var{text}@}
15648Print @var{text} in @r{roman} font. No effect in Info.
15649@xref{Fonts}.@refill
15650
15651@item @@raisesections
15652Change subsequent sections to chapters, subsections to sections, and so
15653on. @xref{Raise/lower sections, , @code{@@raisesections} and
15654@code{@@lowersections}}.@refill
15655
15656@item @@ref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
15657Make a reference. In a printed manual, the reference does not start
15658with a `See'. Follow command with a punctuation mark. Only the first
15659argument is mandatory. @xref{ref, , @code{@@ref}}.@refill
15660
15661@item @@refill
15662In Info, refill and indent the paragraph after all the other processing
15663has been done. No effect on @TeX{}, which always refills. This command
15664is no longer needed, since all formatters now automatically refill.
15665@xref{Refilling Paragraphs}.@refill
15666
15667@item @@result@{@}
15668Indicate the result of an expression to the reader with a special
15669glyph: @samp{@result{}}. @xref{result, , @code{@@result}}.@refill
15670
15671@item @@ringaccent@{@var{c}@}
15672Generate a ring accent over the next character, as in @ringaccent{o}.
15673@xref{Inserting Accents}.
15674
15675@item @@samp@{@var{text}@}
15676Highlight @var{text} that is a literal example of a sequence of
15677characters. Used for single characters, for statements, and often for
15678entire shell commands. @xref{samp, , @code{@@samp}}.@refill
15679
15680@item @@sc@{@var{text}@}
15681Set @var{text} in a printed output in @sc{the small caps font} and
15682set text in the Info file in uppercase letters.
15683@xref{Smallcaps}.@refill
15684
15685@item @@section @var{title}
15686Begin a section within a chapter. In a printed manual, the section
15687title is numbered and appears in the table of contents. In Info, the
15688title is underlined with equal signs. @xref{section, ,
15689@code{@@section}}.@refill
15690
15691@item @@set @var{flag} [@var{string}]
15692Make @var{flag} active, causing the Texinfo formatting commands to
15693format text between subsequent pairs of @code{@@ifset @var{flag}} and
15694@code{@@end ifset} commands. Optionally, set value of @var{flag} to
15695@var{string}.
15696@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.
15697
15698@item @@setchapternewpage @var{on-off-odd}
15699Specify whether chapters start on new pages, and if so, whether on
15700odd-numbered (right-hand) new pages. @xref{setchapternewpage, ,
15701@code{@@setchapternewpage}}.
15702
15703@item @@setcontentsaftertitlepage
15704Put the table of contents after the @samp{@@end titlepage} even if the
15705@code{@@contents} command is not there. @xref{Contents}.
15706
15707@item @@setfilename @var{info-file-name}
15708Provide a name to be used by the Info file. This command is essential
15709for @TeX{} formatting as well, even though it produces no output.
15710@xref{setfilename, , @code{@@setfilename}}.
15711
15712@item @@setshortcontentsaftertitlepage
15713Place the short table of contents after the @samp{@@end titlepage}
15714command even if the @code{@@shortcontents} command is not there.
15715@xref{Contents}.
15716
15717@item @@settitle @var{title}
15718Provide a title for page headers in a printed manual, and the default
15719document description for HTML @samp{<head>}.
15720@xref{settitle, , @code{@@settitle}}.@refill
15721
15722@item @@shortcontents
15723Print a short table of contents. Not relevant to Info, which uses
15724menus rather than tables of contents. A synonym for
15725@code{@@summarycontents}. @xref{Contents, , Generating a Table of
15726Contents}.@refill
15727
15728@item @@shorttitlepage @var{title}
15729Generate a minimal title page. @xref{titlepage,,@code{@@titlepage}}.
15730
15731@item @@smallbook
15732Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format
15733rather than the regular 8.5 by 11 inch format. @xref{smallbook, ,
15734Printing Small Books}. Also, see @ref{small}.
15735
15736@item @@smalldisplay
15737Begin a kind of example. Like @code{@@smallexample} (narrow margins, no
15738filling), but do not select the fixed-width font. Pair with @code{@@end
15739smalldisplay}. @xref{small}.
15740
15741@item @@smallexample
15742Indent text to indicate an example. Do not fill, select fixed-width
15743font, narrow the margins. In printed manuals, print text in a smaller
15744font than with @code{@@example}. Pair with @code{@@end smallexample}.
15745@xref{small}.
15746
15747@item @@smallformat
15748Begin a kind of example. Like @code{@@smalldisplay}, but do not narrow
15749the margins. Pair with @code{@@end smallformat}. @xref{small}.
15750
15751@item @@smalllisp
15752Begin an example of Lisp code. Same as @code{@@smallexample}. Pair
15753with @code{@@end smalllisp}. @xref{small}.
15754
15755@item @@sp @var{n}
15756Skip @var{n} blank lines. @xref{sp, , @code{@@sp}}.@refill
15757
15758@item @@ss@{@}
15759Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}.
15760
15761@item @@strong @{@var{text}@}
15762Emphasize @var{text} by typesetting it in a @strong{bold} font for the
15763printed manual and by surrounding it with asterisks for Info.
15764@xref{emph & strong, , Emphasizing Text}.@refill
15765
15766@item @@subheading @var{title}
15767Print an unnumbered subsection-like heading in the text, but not in
15768the table of contents of a printed manual. In Info, the title is
15769underlined with hyphens. @xref{unnumberedsubsec appendixsubsec
15770subheading, , @code{@@unnumberedsubsec} @code{@@appendixsubsec}
15771@code{@@subheading}}.@refill
15772
15773@item @@subsection @var{title}
15774Begin a subsection within a section. In a printed manual, the
15775subsection title is numbered and appears in the table of contents. In
15776Info, the title is underlined with hyphens. @xref{subsection, ,
15777@code{@@subsection}}.@refill
15778
15779@item @@subsubheading @var{title}
15780Print an unnumbered subsubsection-like heading in the text, but not in
15781the table of contents of a printed manual. In Info, the title is
15782underlined with periods. @xref{subsubsection, , The `subsub'
15783Commands}.@refill
15784
15785@item @@subsubsection @var{title}
15786Begin a subsubsection within a subsection. In a printed manual,
15787the subsubsection title is numbered and appears in the table of
15788contents. In Info, the title is underlined with periods.
15789@xref{subsubsection, , The `subsub' Commands}.@refill
15790
15791@item @@subtitle @var{title}
15792In a printed manual, set a subtitle in a normal sized font flush to
15793the right-hand side of the page. Not relevant to Info, which does not
15794have title pages. @xref{title subtitle author, , @code{@@title}
15795@code{@@subtitle} and @code{@@author} Commands}.@refill
15796
15797@item @@summarycontents
15798Print a short table of contents. Not relevant to Info, which uses
15799menus rather than tables of contents. A synonym for
15800@code{@@shortcontents}. @xref{Contents, , Generating a Table of
15801Contents}.@refill
15802
15803@item @@syncodeindex @var{from-index} @var{into-index}
15804Merge the index named in the first argument into the index named in
15805the second argument, printing the entries from the first index in
15806@code{@@code} font. @xref{Combining Indices}.@refill
15807
15808@item @@synindex @var{from-index} @var{into-index}
15809Merge the index named in the first argument into the index named in
15810the second argument. Do not change the font of @var{from-index}
15811entries. @xref{Combining Indices}.@refill
15812
15813@item @@t@{@var{text}@}
15814Print @var{text} in a @t{fixed-width}, typewriter-like font.
15815No effect in Info. @xref{Fonts}.@refill
15816
15817@item @@tab
15818Separate columns in a multitable. @xref{Multitable Rows}.
15819
15820@item @@table @var{formatting-command}
15821Begin a two-column table, using @code{@@item} for each entry. Write
15822each first column entry on the same line as @code{@@item}. First
15823column entries are printed in the font resulting from
15824@var{formatting-command}. Pair with @code{@@end table}.
15825@xref{Two-column Tables, , Making a Two-column Table}.
15826Also see @ref{ftable vtable, , @code{@@ftable} and @code{@@vtable}},
15827and @ref{itemx, , @code{@@itemx}}.@refill
15828
15829@item @@TeX@{@}
15830Insert the logo @TeX{}. @xref{TeX and copyright, , Inserting @TeX{}
15831and @copyright{}}.@refill
15832
15833@item @@tex
15834Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Raw
15835Formatter Commands}.
15836
15837@item @@thischapter
15838@itemx @@thischaptername
15839@itemx @@thisfile
15840@itemx @@thispage
15841@itemx @@thistitle
15842Only allowed in a heading or footing. Stands for the number and name of
15843the current chapter (in the format `Chapter 1: Title'), the chapter name
15844only, the filename, the current page number, and the title of the
15845document, respectively. @xref{Custom Headings, , How to Make Your Own
15846Headings}.@refill
15847
15848@item @@tieaccent@{@var{cc}@}
15849Generate a tie-after accent over the next two characters @var{cc}, as in
15850`@tieaccent{oo}'. @xref{Inserting Accents}.
15851
15852@item @@tindex @var{entry}
15853Add @var{entry} to the index of data types. @xref{Index Entries, ,
15854Defining the Entries of an Index}.@refill
15855
15856@item @@title @var{title}
15857In a printed manual, set a title flush to the left-hand side of the
15858page in a larger than normal font and underline it with a black rule.
15859Not relevant to Info, which does not have title pages. @xref{title
15860subtitle author, , The @code{@@title} @code{@@subtitle} and
15861@code{@@author} Commands}.@refill
15862
15863@item @@titlefont@{@var{text}@}
15864In a printed manual, print @var{text} in a larger than normal font.
15865Not relevant to Info, which does not have title pages.
15866@xref{titlefont center sp, , The @code{@@titlefont} @code{@@center}
15867and @code{@@sp} Commands}.@refill
15868
15869@item @@titlepage
15870Indicate to Texinfo the beginning of the title page. Write command on
15871a line of its own. Pair with @code{@@end titlepage}. Nothing between
15872@code{@@titlepage} and @code{@@end titlepage} appears in Info.
15873@xref{titlepage, , @code{@@titlepage}}.@refill
15874
15875@item @@today@{@}
15876Insert the current date, in `1 Jan 1900' style. @xref{Custom
15877Headings, , How to Make Your Own Headings}.@refill
15878
15879@item @@top @var{title}
15880In a Texinfo file to be formatted with @code{makeinfo}, identify the
| 15718How to Make Your Own Headings}.@refill
15719
15720@item @@OE@{@}
15721@itemx @@oe@{@}
15722Generate the uppercase and lowercase OE ligatures, respectively:
15723@OE{}, @oe{}. @xref{Inserting Accents}.
15724
15725@item @@option@{@var{option-name}@}
15726Indicate a command-line option, such as @option{-l} or @option{--help}.
15727@xref{option,, @code{@@option}}.
15728
15729@item @@page
15730Start a new page in a printed manual. No effect in Info.
15731@xref{page, , @code{@@page}}.@refill
15732
15733@item @@pagesizes [@var{width}][, @var{height}]
15734Change page dimensions. @xref{pagesizes}.
15735
15736@item @@paragraphindent @var{indent}
15737Indent paragraphs by @var{indent} number of spaces (perhaps 0); preserve
15738source file indentation if @var{indent} is @code{asis}.
15739@xref{paragraphindent,, Paragraph Indenting}.
15740
15741@item @@pindex @var{entry}
15742Add @var{entry} to the index of programs. @xref{Index Entries, , Defining
15743the Entries of an Index}.@refill
15744
15745@item @@point@{@}
15746Indicate the position of point in a buffer to the reader with a
15747glyph: @samp{@point{}}. @xref{Point Glyph, , Indicating
15748Point in a Buffer}.@refill
15749
15750@item @@pounds@{@}
15751Generate the pounds sterling currency sign.
15752@xref{pounds,,@code{@@pounds@{@}}}.
15753
15754@item @@print@{@}
15755Indicate printed output to the reader with a glyph:
15756@samp{@print{}}. @xref{Print Glyph}.@refill
15757
15758@item @@printindex @var{index-name}
15759Print an alphabetized two-column index in a printed manual or generate
15760an alphabetized menu of index entries for Info. @xref{Printing
15761Indices & Menus}.@refill
15762
15763@item @@pxref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
15764Make a reference that starts with a lower case `see' in a printed
15765manual. Use within parentheses only. Do not follow command with a
15766punctuation mark---the Info formatting commands automatically insert
15767terminating punctuation as needed. Only the first argument is mandatory.
15768@xref{pxref, , @code{@@pxref}}.@refill
15769
15770@item @@questiondown@{@}
15771Generate an upside-down question mark. @xref{Inserting Accents}.
15772
15773@item @@quotation
15774Narrow the margins to indicate text that is quoted from another real
15775or imaginary work. Write command on a line of its own. Pair with
15776@code{@@end quotation}. @xref{quotation, ,
15777@code{@@quotation}}.@refill
15778
15779@item @@r@{@var{text}@}
15780Print @var{text} in @r{roman} font. No effect in Info.
15781@xref{Fonts}.@refill
15782
15783@item @@raisesections
15784Change subsequent sections to chapters, subsections to sections, and so
15785on. @xref{Raise/lower sections, , @code{@@raisesections} and
15786@code{@@lowersections}}.@refill
15787
15788@item @@ref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
15789Make a reference. In a printed manual, the reference does not start
15790with a `See'. Follow command with a punctuation mark. Only the first
15791argument is mandatory. @xref{ref, , @code{@@ref}}.@refill
15792
15793@item @@refill
15794In Info, refill and indent the paragraph after all the other processing
15795has been done. No effect on @TeX{}, which always refills. This command
15796is no longer needed, since all formatters now automatically refill.
15797@xref{Refilling Paragraphs}.@refill
15798
15799@item @@result@{@}
15800Indicate the result of an expression to the reader with a special
15801glyph: @samp{@result{}}. @xref{result, , @code{@@result}}.@refill
15802
15803@item @@ringaccent@{@var{c}@}
15804Generate a ring accent over the next character, as in @ringaccent{o}.
15805@xref{Inserting Accents}.
15806
15807@item @@samp@{@var{text}@}
15808Highlight @var{text} that is a literal example of a sequence of
15809characters. Used for single characters, for statements, and often for
15810entire shell commands. @xref{samp, , @code{@@samp}}.@refill
15811
15812@item @@sc@{@var{text}@}
15813Set @var{text} in a printed output in @sc{the small caps font} and
15814set text in the Info file in uppercase letters.
15815@xref{Smallcaps}.@refill
15816
15817@item @@section @var{title}
15818Begin a section within a chapter. In a printed manual, the section
15819title is numbered and appears in the table of contents. In Info, the
15820title is underlined with equal signs. @xref{section, ,
15821@code{@@section}}.@refill
15822
15823@item @@set @var{flag} [@var{string}]
15824Make @var{flag} active, causing the Texinfo formatting commands to
15825format text between subsequent pairs of @code{@@ifset @var{flag}} and
15826@code{@@end ifset} commands. Optionally, set value of @var{flag} to
15827@var{string}.
15828@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.
15829
15830@item @@setchapternewpage @var{on-off-odd}
15831Specify whether chapters start on new pages, and if so, whether on
15832odd-numbered (right-hand) new pages. @xref{setchapternewpage, ,
15833@code{@@setchapternewpage}}.
15834
15835@item @@setcontentsaftertitlepage
15836Put the table of contents after the @samp{@@end titlepage} even if the
15837@code{@@contents} command is not there. @xref{Contents}.
15838
15839@item @@setfilename @var{info-file-name}
15840Provide a name to be used by the Info file. This command is essential
15841for @TeX{} formatting as well, even though it produces no output.
15842@xref{setfilename, , @code{@@setfilename}}.
15843
15844@item @@setshortcontentsaftertitlepage
15845Place the short table of contents after the @samp{@@end titlepage}
15846command even if the @code{@@shortcontents} command is not there.
15847@xref{Contents}.
15848
15849@item @@settitle @var{title}
15850Provide a title for page headers in a printed manual, and the default
15851document description for HTML @samp{<head>}.
15852@xref{settitle, , @code{@@settitle}}.@refill
15853
15854@item @@shortcontents
15855Print a short table of contents. Not relevant to Info, which uses
15856menus rather than tables of contents. A synonym for
15857@code{@@summarycontents}. @xref{Contents, , Generating a Table of
15858Contents}.@refill
15859
15860@item @@shorttitlepage @var{title}
15861Generate a minimal title page. @xref{titlepage,,@code{@@titlepage}}.
15862
15863@item @@smallbook
15864Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format
15865rather than the regular 8.5 by 11 inch format. @xref{smallbook, ,
15866Printing Small Books}. Also, see @ref{small}.
15867
15868@item @@smalldisplay
15869Begin a kind of example. Like @code{@@smallexample} (narrow margins, no
15870filling), but do not select the fixed-width font. Pair with @code{@@end
15871smalldisplay}. @xref{small}.
15872
15873@item @@smallexample
15874Indent text to indicate an example. Do not fill, select fixed-width
15875font, narrow the margins. In printed manuals, print text in a smaller
15876font than with @code{@@example}. Pair with @code{@@end smallexample}.
15877@xref{small}.
15878
15879@item @@smallformat
15880Begin a kind of example. Like @code{@@smalldisplay}, but do not narrow
15881the margins. Pair with @code{@@end smallformat}. @xref{small}.
15882
15883@item @@smalllisp
15884Begin an example of Lisp code. Same as @code{@@smallexample}. Pair
15885with @code{@@end smalllisp}. @xref{small}.
15886
15887@item @@sp @var{n}
15888Skip @var{n} blank lines. @xref{sp, , @code{@@sp}}.@refill
15889
15890@item @@ss@{@}
15891Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}.
15892
15893@item @@strong @{@var{text}@}
15894Emphasize @var{text} by typesetting it in a @strong{bold} font for the
15895printed manual and by surrounding it with asterisks for Info.
15896@xref{emph & strong, , Emphasizing Text}.@refill
15897
15898@item @@subheading @var{title}
15899Print an unnumbered subsection-like heading in the text, but not in
15900the table of contents of a printed manual. In Info, the title is
15901underlined with hyphens. @xref{unnumberedsubsec appendixsubsec
15902subheading, , @code{@@unnumberedsubsec} @code{@@appendixsubsec}
15903@code{@@subheading}}.@refill
15904
15905@item @@subsection @var{title}
15906Begin a subsection within a section. In a printed manual, the
15907subsection title is numbered and appears in the table of contents. In
15908Info, the title is underlined with hyphens. @xref{subsection, ,
15909@code{@@subsection}}.@refill
15910
15911@item @@subsubheading @var{title}
15912Print an unnumbered subsubsection-like heading in the text, but not in
15913the table of contents of a printed manual. In Info, the title is
15914underlined with periods. @xref{subsubsection, , The `subsub'
15915Commands}.@refill
15916
15917@item @@subsubsection @var{title}
15918Begin a subsubsection within a subsection. In a printed manual,
15919the subsubsection title is numbered and appears in the table of
15920contents. In Info, the title is underlined with periods.
15921@xref{subsubsection, , The `subsub' Commands}.@refill
15922
15923@item @@subtitle @var{title}
15924In a printed manual, set a subtitle in a normal sized font flush to
15925the right-hand side of the page. Not relevant to Info, which does not
15926have title pages. @xref{title subtitle author, , @code{@@title}
15927@code{@@subtitle} and @code{@@author} Commands}.@refill
15928
15929@item @@summarycontents
15930Print a short table of contents. Not relevant to Info, which uses
15931menus rather than tables of contents. A synonym for
15932@code{@@shortcontents}. @xref{Contents, , Generating a Table of
15933Contents}.@refill
15934
15935@item @@syncodeindex @var{from-index} @var{into-index}
15936Merge the index named in the first argument into the index named in
15937the second argument, printing the entries from the first index in
15938@code{@@code} font. @xref{Combining Indices}.@refill
15939
15940@item @@synindex @var{from-index} @var{into-index}
15941Merge the index named in the first argument into the index named in
15942the second argument. Do not change the font of @var{from-index}
15943entries. @xref{Combining Indices}.@refill
15944
15945@item @@t@{@var{text}@}
15946Print @var{text} in a @t{fixed-width}, typewriter-like font.
15947No effect in Info. @xref{Fonts}.@refill
15948
15949@item @@tab
15950Separate columns in a multitable. @xref{Multitable Rows}.
15951
15952@item @@table @var{formatting-command}
15953Begin a two-column table, using @code{@@item} for each entry. Write
15954each first column entry on the same line as @code{@@item}. First
15955column entries are printed in the font resulting from
15956@var{formatting-command}. Pair with @code{@@end table}.
15957@xref{Two-column Tables, , Making a Two-column Table}.
15958Also see @ref{ftable vtable, , @code{@@ftable} and @code{@@vtable}},
15959and @ref{itemx, , @code{@@itemx}}.@refill
15960
15961@item @@TeX@{@}
15962Insert the logo @TeX{}. @xref{TeX and copyright, , Inserting @TeX{}
15963and @copyright{}}.@refill
15964
15965@item @@tex
15966Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Raw
15967Formatter Commands}.
15968
15969@item @@thischapter
15970@itemx @@thischaptername
15971@itemx @@thisfile
15972@itemx @@thispage
15973@itemx @@thistitle
15974Only allowed in a heading or footing. Stands for the number and name of
15975the current chapter (in the format `Chapter 1: Title'), the chapter name
15976only, the filename, the current page number, and the title of the
15977document, respectively. @xref{Custom Headings, , How to Make Your Own
15978Headings}.@refill
15979
15980@item @@tieaccent@{@var{cc}@}
15981Generate a tie-after accent over the next two characters @var{cc}, as in
15982`@tieaccent{oo}'. @xref{Inserting Accents}.
15983
15984@item @@tindex @var{entry}
15985Add @var{entry} to the index of data types. @xref{Index Entries, ,
15986Defining the Entries of an Index}.@refill
15987
15988@item @@title @var{title}
15989In a printed manual, set a title flush to the left-hand side of the
15990page in a larger than normal font and underline it with a black rule.
15991Not relevant to Info, which does not have title pages. @xref{title
15992subtitle author, , The @code{@@title} @code{@@subtitle} and
15993@code{@@author} Commands}.@refill
15994
15995@item @@titlefont@{@var{text}@}
15996In a printed manual, print @var{text} in a larger than normal font.
15997Not relevant to Info, which does not have title pages.
15998@xref{titlefont center sp, , The @code{@@titlefont} @code{@@center}
15999and @code{@@sp} Commands}.@refill
16000
16001@item @@titlepage
16002Indicate to Texinfo the beginning of the title page. Write command on
16003a line of its own. Pair with @code{@@end titlepage}. Nothing between
16004@code{@@titlepage} and @code{@@end titlepage} appears in Info.
16005@xref{titlepage, , @code{@@titlepage}}.@refill
16006
16007@item @@today@{@}
16008Insert the current date, in `1 Jan 1900' style. @xref{Custom
16009Headings, , How to Make Your Own Headings}.@refill
16010
16011@item @@top @var{title}
16012In a Texinfo file to be formatted with @code{makeinfo}, identify the
|
15881topmost @code{@@node} line in the file, which must be written on the line
| 16013topmost @code{@@node} in the file, which must be written on the line
|
15882immediately preceding the @code{@@top} command. Used for
15883@code{makeinfo}'s node pointer insertion feature. The title is
15884underlined with asterisks. Both the @code{@@node} line and the @code{@@top}
| 16014immediately preceding the @code{@@top} command. Used for
16015@code{makeinfo}'s node pointer insertion feature. The title is
16016underlined with asterisks. Both the @code{@@node} line and the @code{@@top}
|
15885line normally should be enclosed by @code{@@ifinfo} and @code{@@end
15886ifinfo}. In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
| 16017line normally should be enclosed by @code{@@ifnottex} and @code{@@end
16018ifnottex}. In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
|
15887command is merely a synonym for @code{@@unnumbered}. @xref{makeinfo
15888Pointer Creation, , Creating Pointers with @code{makeinfo}}.
15889
15890@item @@u@{@var{c}@}
15891@itemx @@ubaraccent@{@var{c}@}
15892@itemx @@udotaccent@{@var{c}@}
15893Generate a breve, underbar, or underdot accent, respectively, over or
15894under the character @var{c}, as in @u{o}, @ubaraccent{o},
15895@udotaccent{o}. @xref{Inserting Accents}.
15896
15897@item @@unnumbered @var{title}
15898In a printed manual, begin a chapter that appears without chapter
15899numbers of any kind. The title appears in the table of contents of a
15900printed manual. In Info, the title is underlined with asterisks.
15901@xref{unnumbered & appendix, , @code{@@unnumbered} and
15902@code{@@appendix}}.@refill
15903
15904@item @@unnumberedsec @var{title}
15905In a printed manual, begin a section that appears without section
15906numbers of any kind. The title appears in the table of contents of a
15907printed manual. In Info, the title is underlined with equal signs.
15908@xref{unnumberedsec appendixsec heading, , Section Commands}.@refill
15909
15910@item @@unnumberedsubsec @var{title}
15911In a printed manual, begin an unnumbered subsection within a
15912chapter. The title appears in the table of contents of a printed
15913manual. In Info, the title is underlined with hyphens.
15914@xref{unnumberedsubsec appendixsubsec subheading, ,
15915@code{@@unnumberedsubsec} @code{@@appendixsubsec}
15916@code{@@subheading}}.@refill
15917
15918@item @@unnumberedsubsubsec @var{title}
15919In a printed manual, begin an unnumbered subsubsection within a
15920chapter. The title appears in the table of contents of a printed
15921manual. In Info, the title is underlined with periods.
15922@xref{subsubsection, , The `subsub' Commands}.@refill
15923
15924@item @@uref@{@var{url}[, @var{displayed-text}][, @var{replacement}@}
15925Define a cross reference to an external uniform resource locator for the
15926World Wide Web. @xref{uref, , @code{@@uref}}.@refill
15927
15928@item @@url@{@var{url}@}
15929Indicate text that is a uniform resource locator for the World Wide
15930Web. @xref{url, , @code{@@url}}.@refill
15931
15932@item @@v@{@var{c}@}
15933Generate check accent over the character @var{c}, as in @v{o}.
15934@xref{Inserting Accents}.
15935
15936@item @@value@{@var{flag}@}
15937Replace @var{flag} with the value to which it is set by @code{@@set
15938@var{flag}}.
15939@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
15940
15941@item @@var@{@var{metasyntactic-variable}@}
15942Highlight a metasyntactic variable, which is something that stands for
15943another piece of text. @xref{var, , Indicating Metasyntactic
15944Variables}.@refill
15945
15946@item @@verb@{@var{delim} @var{literal} @var{delim}@}
15947Output @var{literal}, delimited by the single character @var{delim},
15948exactly as is (in the fixed-width font), including any whitespace or
15949Texinfo special characters. @xref{verb,,@code{verb}}.
15950
15951@item @@verbatim
15952Output the text of the environment exactly as is (in the fixed-width
15953font). Pair with @code{@@end verbatim}. @xref{verbatim,,@code{verbatim}}.
15954
15955@item @@verbatiminclude @var{filename}
15956Output the contents of @var{filename} exactly as is (in the fixed-width font).
15957@xref{verbatiminclude,,@code{verbatiminclude}}.
15958
15959@item @@vindex @var{entry}
15960Add @var{entry} to the index of variables. @xref{Index Entries, ,
15961Defining the Entries of an Index}.@refill
15962
15963@item @@vskip @var{amount}
15964In a printed manual, insert whitespace so as to push text on the
15965remainder of the page towards the bottom of the page. Used in
15966formatting the copyright page with the argument @samp{0pt plus
159671filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used
| 16019command is merely a synonym for @code{@@unnumbered}. @xref{makeinfo
16020Pointer Creation, , Creating Pointers with @code{makeinfo}}.
16021
16022@item @@u@{@var{c}@}
16023@itemx @@ubaraccent@{@var{c}@}
16024@itemx @@udotaccent@{@var{c}@}
16025Generate a breve, underbar, or underdot accent, respectively, over or
16026under the character @var{c}, as in @u{o}, @ubaraccent{o},
16027@udotaccent{o}. @xref{Inserting Accents}.
16028
16029@item @@unnumbered @var{title}
16030In a printed manual, begin a chapter that appears without chapter
16031numbers of any kind. The title appears in the table of contents of a
16032printed manual. In Info, the title is underlined with asterisks.
16033@xref{unnumbered & appendix, , @code{@@unnumbered} and
16034@code{@@appendix}}.@refill
16035
16036@item @@unnumberedsec @var{title}
16037In a printed manual, begin a section that appears without section
16038numbers of any kind. The title appears in the table of contents of a
16039printed manual. In Info, the title is underlined with equal signs.
16040@xref{unnumberedsec appendixsec heading, , Section Commands}.@refill
16041
16042@item @@unnumberedsubsec @var{title}
16043In a printed manual, begin an unnumbered subsection within a
16044chapter. The title appears in the table of contents of a printed
16045manual. In Info, the title is underlined with hyphens.
16046@xref{unnumberedsubsec appendixsubsec subheading, ,
16047@code{@@unnumberedsubsec} @code{@@appendixsubsec}
16048@code{@@subheading}}.@refill
16049
16050@item @@unnumberedsubsubsec @var{title}
16051In a printed manual, begin an unnumbered subsubsection within a
16052chapter. The title appears in the table of contents of a printed
16053manual. In Info, the title is underlined with periods.
16054@xref{subsubsection, , The `subsub' Commands}.@refill
16055
16056@item @@uref@{@var{url}[, @var{displayed-text}][, @var{replacement}@}
16057Define a cross reference to an external uniform resource locator for the
16058World Wide Web. @xref{uref, , @code{@@uref}}.@refill
16059
16060@item @@url@{@var{url}@}
16061Indicate text that is a uniform resource locator for the World Wide
16062Web. @xref{url, , @code{@@url}}.@refill
16063
16064@item @@v@{@var{c}@}
16065Generate check accent over the character @var{c}, as in @v{o}.
16066@xref{Inserting Accents}.
16067
16068@item @@value@{@var{flag}@}
16069Replace @var{flag} with the value to which it is set by @code{@@set
16070@var{flag}}.
16071@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
16072
16073@item @@var@{@var{metasyntactic-variable}@}
16074Highlight a metasyntactic variable, which is something that stands for
16075another piece of text. @xref{var, , Indicating Metasyntactic
16076Variables}.@refill
16077
16078@item @@verb@{@var{delim} @var{literal} @var{delim}@}
16079Output @var{literal}, delimited by the single character @var{delim},
16080exactly as is (in the fixed-width font), including any whitespace or
16081Texinfo special characters. @xref{verb,,@code{verb}}.
16082
16083@item @@verbatim
16084Output the text of the environment exactly as is (in the fixed-width
16085font). Pair with @code{@@end verbatim}. @xref{verbatim,,@code{verbatim}}.
16086
16087@item @@verbatiminclude @var{filename}
16088Output the contents of @var{filename} exactly as is (in the fixed-width font).
16089@xref{verbatiminclude,,@code{verbatiminclude}}.
16090
16091@item @@vindex @var{entry}
16092Add @var{entry} to the index of variables. @xref{Index Entries, ,
16093Defining the Entries of an Index}.@refill
16094
16095@item @@vskip @var{amount}
16096In a printed manual, insert whitespace so as to push text on the
16097remainder of the page towards the bottom of the page. Used in
16098formatting the copyright page with the argument @samp{0pt plus
160991filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used
|
15968only in contexts ignored for Info. @xref{Copyright & Permissions, ,
15969The Copyright Page and Printed Permissions}.@refill
| 16100only in contexts ignored for Info. @xref{Copyright}.
|
15970
15971@item @@vtable @var{formatting-command}
15972Begin a two-column table, using @code{@@item} for each entry.
15973Automatically enter each of the items in the first column into the
15974index of variables. Pair with @code{@@end vtable}. The same as
15975@code{@@table}, except for indexing. @xref{ftable vtable, ,
15976@code{@@ftable} and @code{@@vtable}}.@refill
15977
15978@item @@w@{@var{text}@}
15979Prevent @var{text} from being split across two lines. Do not end a
15980paragraph that uses @code{@@w} with an @code{@@refill} command.
15981@xref{w, , @code{@@w}}.@refill
15982
15983@item @@xref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
15984Make a reference that starts with `See' in a printed manual. Follow
15985command with a punctuation mark. Only the first argument is
15986mandatory. @xref{xref, , @code{@@xref}}.@refill
15987@end table
15988
15989
15990@node Tips
15991@appendix Tips and Hints
15992
15993Here are some tips for writing Texinfo documentation:@refill
15994
15995@cindex Tips
15996@cindex Usage tips
15997@cindex Hints
15998@itemize @bullet
15999@item
16000Write in the present tense, not in the past or the future.
16001
16002@item
16003Write actively! For example, write ``We recommend that @dots{}'' rather
16004than ``It is recommended that @dots{}''.
16005
16006@item
16007Use 70 or 72 as your fill column. Longer lines are hard to read.
16008
16009@item
16010Include a copyright notice and copying permissions.
16011@end itemize
16012
16013@subsubheading Index, Index, Index!
16014
16015Write many index entries, in different ways.
16016Readers like indices; they are helpful and convenient.
16017
16018Although it is easiest to write index entries as you write the body of
16019the text, some people prefer to write entries afterwards. In either
16020case, write an entry before the paragraph to which it applies. This
16021way, an index entry points to the first page of a paragraph that is
16022split across pages.
16023
16024Here are more hints we have found valuable:
16025
16026@itemize @bullet
16027@item
16028Write each index entry differently, so each entry refers to a different
16029place in the document.
16030
16031@item
16032Write index entries only where a topic is discussed significantly. For
16033example, it is not useful to index ``debugging information'' in a
16034chapter on reporting bugs. Someone who wants to know about debugging
16035information will certainly not find it in that chapter.
16036
16037@item
16038Consistently capitalize the first word of every concept index entry,
16039or else consistently use lower case. Terse entries often call for
16040lower case; longer entries for capitalization. Whichever case
16041convention you use, please use one or the other consistently! Mixing
16042the two styles looks bad.
16043
16044@item
16045Always capitalize or use upper case for those words in an index for
16046which this is proper, such as names of countries or acronyms. Always
16047use the appropriate case for case-sensitive names, such as those in C or
16048Lisp.
16049
16050@item
16051Write the indexing commands that refer to a whole section immediately
16052after the section command, and write the indexing commands that refer to
16053a paragraph before that paragraph.
16054
16055In the example that follows, a blank line comes after the index
16056entry for ``Leaping'':
16057
16058@example
16059@group
16060@@section The Dog and the Fox
16061@@cindex Jumping, in general
16062@@cindex Leaping
16063
16064@@cindex Dog, lazy, jumped over
16065@@cindex Lazy dog jumped over
16066@@cindex Fox, jumps over dog
16067@@cindex Quick fox jumps over dog
16068The quick brown fox jumps over the lazy dog.
16069@end group
16070@end example
16071
16072@noindent
16073(Note that the example shows entries for the same concept that are
16074written in different ways---@samp{Lazy dog}, and @samp{Dog, lazy}---so
16075readers can look up the concept in different ways.)
16076@end itemize
16077
16078@subsubheading Blank Lines
16079
16080@itemize @bullet
16081@item
16082Insert a blank line between a sectioning command and the first following
16083sentence or paragraph, or between the indexing commands associated with
16084the sectioning command and the first following sentence or paragraph, as
16085shown in the tip on indexing. Otherwise, a formatter may fold title and
16086paragraph together.
16087
16088@item
16089Always insert a blank line before an @code{@@table} command and after an
16090@code{@@end table} command; but never insert a blank line after an
16091@code{@@table} command or before an @code{@@end table} command.
16092
16093@need 1000
16094For example,
16095
16096@example
16097@group
16098Types of fox:
16099
16100@@table @@samp
16101@@item Quick
16102Jump over lazy dogs.
16103@end group
16104
16105@group
16106@@item Brown
16107Also jump over lazy dogs.
16108@@end table
16109
16110@end group
16111@group
16112@@noindent
16113On the other hand, @dots{}
16114@end group
16115@end example
16116
16117Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end
16118itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the
16119same way.
16120@end itemize
16121
16122@subsubheading Complete Phrases
16123
16124Complete phrases are easier to read than @dots{}
16125
16126@itemize @bullet
16127@item
16128Write entries in an itemized list as complete sentences; or at least, as
16129complete phrases. Incomplete expressions @dots{} awkward @dots{} like
16130this.
16131
16132@item
16133Write the prefatory sentence or phrase for a multi-item list or table as
16134a complete expression. Do not write ``You can set:''; instead, write
16135``You can set these variables:''. The former expression sounds cut off.
16136@end itemize
16137
16138@subsubheading Editions, Dates and Versions
16139
| 16101
16102@item @@vtable @var{formatting-command}
16103Begin a two-column table, using @code{@@item} for each entry.
16104Automatically enter each of the items in the first column into the
16105index of variables. Pair with @code{@@end vtable}. The same as
16106@code{@@table}, except for indexing. @xref{ftable vtable, ,
16107@code{@@ftable} and @code{@@vtable}}.@refill
16108
16109@item @@w@{@var{text}@}
16110Prevent @var{text} from being split across two lines. Do not end a
16111paragraph that uses @code{@@w} with an @code{@@refill} command.
16112@xref{w, , @code{@@w}}.@refill
16113
16114@item @@xref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
16115Make a reference that starts with `See' in a printed manual. Follow
16116command with a punctuation mark. Only the first argument is
16117mandatory. @xref{xref, , @code{@@xref}}.@refill
16118@end table
16119
16120
16121@node Tips
16122@appendix Tips and Hints
16123
16124Here are some tips for writing Texinfo documentation:@refill
16125
16126@cindex Tips
16127@cindex Usage tips
16128@cindex Hints
16129@itemize @bullet
16130@item
16131Write in the present tense, not in the past or the future.
16132
16133@item
16134Write actively! For example, write ``We recommend that @dots{}'' rather
16135than ``It is recommended that @dots{}''.
16136
16137@item
16138Use 70 or 72 as your fill column. Longer lines are hard to read.
16139
16140@item
16141Include a copyright notice and copying permissions.
16142@end itemize
16143
16144@subsubheading Index, Index, Index!
16145
16146Write many index entries, in different ways.
16147Readers like indices; they are helpful and convenient.
16148
16149Although it is easiest to write index entries as you write the body of
16150the text, some people prefer to write entries afterwards. In either
16151case, write an entry before the paragraph to which it applies. This
16152way, an index entry points to the first page of a paragraph that is
16153split across pages.
16154
16155Here are more hints we have found valuable:
16156
16157@itemize @bullet
16158@item
16159Write each index entry differently, so each entry refers to a different
16160place in the document.
16161
16162@item
16163Write index entries only where a topic is discussed significantly. For
16164example, it is not useful to index ``debugging information'' in a
16165chapter on reporting bugs. Someone who wants to know about debugging
16166information will certainly not find it in that chapter.
16167
16168@item
16169Consistently capitalize the first word of every concept index entry,
16170or else consistently use lower case. Terse entries often call for
16171lower case; longer entries for capitalization. Whichever case
16172convention you use, please use one or the other consistently! Mixing
16173the two styles looks bad.
16174
16175@item
16176Always capitalize or use upper case for those words in an index for
16177which this is proper, such as names of countries or acronyms. Always
16178use the appropriate case for case-sensitive names, such as those in C or
16179Lisp.
16180
16181@item
16182Write the indexing commands that refer to a whole section immediately
16183after the section command, and write the indexing commands that refer to
16184a paragraph before that paragraph.
16185
16186In the example that follows, a blank line comes after the index
16187entry for ``Leaping'':
16188
16189@example
16190@group
16191@@section The Dog and the Fox
16192@@cindex Jumping, in general
16193@@cindex Leaping
16194
16195@@cindex Dog, lazy, jumped over
16196@@cindex Lazy dog jumped over
16197@@cindex Fox, jumps over dog
16198@@cindex Quick fox jumps over dog
16199The quick brown fox jumps over the lazy dog.
16200@end group
16201@end example
16202
16203@noindent
16204(Note that the example shows entries for the same concept that are
16205written in different ways---@samp{Lazy dog}, and @samp{Dog, lazy}---so
16206readers can look up the concept in different ways.)
16207@end itemize
16208
16209@subsubheading Blank Lines
16210
16211@itemize @bullet
16212@item
16213Insert a blank line between a sectioning command and the first following
16214sentence or paragraph, or between the indexing commands associated with
16215the sectioning command and the first following sentence or paragraph, as
16216shown in the tip on indexing. Otherwise, a formatter may fold title and
16217paragraph together.
16218
16219@item
16220Always insert a blank line before an @code{@@table} command and after an
16221@code{@@end table} command; but never insert a blank line after an
16222@code{@@table} command or before an @code{@@end table} command.
16223
16224@need 1000
16225For example,
16226
16227@example
16228@group
16229Types of fox:
16230
16231@@table @@samp
16232@@item Quick
16233Jump over lazy dogs.
16234@end group
16235
16236@group
16237@@item Brown
16238Also jump over lazy dogs.
16239@@end table
16240
16241@end group
16242@group
16243@@noindent
16244On the other hand, @dots{}
16245@end group
16246@end example
16247
16248Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end
16249itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the
16250same way.
16251@end itemize
16252
16253@subsubheading Complete Phrases
16254
16255Complete phrases are easier to read than @dots{}
16256
16257@itemize @bullet
16258@item
16259Write entries in an itemized list as complete sentences; or at least, as
16260complete phrases. Incomplete expressions @dots{} awkward @dots{} like
16261this.
16262
16263@item
16264Write the prefatory sentence or phrase for a multi-item list or table as
16265a complete expression. Do not write ``You can set:''; instead, write
16266``You can set these variables:''. The former expression sounds cut off.
16267@end itemize
16268
16269@subsubheading Editions, Dates and Versions
16270
|
16140Write the edition and version numbers and date in three places in every
16141manual:
| 16271Include edition numbers, version numbers, and dates in the
16272@code{@@copying} text (for people reading the Texinfo file, and for the
16273legal copyright in the output files). Then use @code{@@insertcopying}
16274in the @code{@@titlepage} section (for people reading the printed
16275output) and the Top node (for people reading the online output).
|
16142
| 16276
|
16143@enumerate
16144@item
16145In the first @code{@@ifinfo} section, for people reading the Texinfo file.
| 16277It is easiest to do this using @code{@@set} and @code{@@value}.
16278@xref{value Example, , @code{@@value} Example}, and @ref{GNU Sample Texts}.
|
16146
| 16279
|
16147@item
16148In the @code{@@titlepage} section, for people reading the printed manual.
| |
16149
| 16280
|
16150@item
16151In the `Top' node, for people reading the Info file.
16152@end enumerate
16153
16154@noindent
16155Also, it helps to write a note before the first @code{@@ifinfo}
16156section to explain what you are doing.
16157
16158@need 800
16159@noindent
16160For example:
16161
16162@example
16163@group
16164@@c ===> NOTE! <==
16165@@c Specify the edition and version numbers and date
16166@@c in *three* places:
16167@@c 1. First ifinfo section 2. title page 3. top node
16168@@c To find the locations, search for !!set
16169@end group
16170
16171@group
16172@@ifinfo
16173@@c !!set edition, date, version
16174This is Edition 4.03, January 1992,
16175of the @@cite@{GDB Manual@} for GDB Version 4.3.
16176@dots{}
16177@end group
16178@end example
16179
16180@noindent
16181---or use @code{@@set} and @code{@@value}
16182(@pxref{value Example, , @code{@@value} Example}).
16183
| |
16184@subsubheading Definition Commands
16185
16186Definition commands are @code{@@deffn}, @code{@@defun},
16187@code{@@defmac}, and the like, and enable you to write descriptions in
16188a uniform format.@refill
16189
16190@itemize @bullet
16191@item
16192Write just one definition command for each entity you define with a
16193definition command. The automatic indexing feature creates an index
16194entry that leads the reader to the definition.
16195
16196@item
16197Use @code{@@table} @dots{} @code{@@end table} in an appendix that
16198contains a summary of functions, not @code{@@deffn} or other definition
16199commands.
16200@end itemize
16201
16202@subsubheading Capitalization
16203
16204@itemize @bullet
16205@item
16206Capitalize ``Texinfo''; it is a name. Do not write the @samp{x} or
16207@samp{i} in upper case.
16208
16209@item
16210Capitalize ``Info''; it is a name.
16211
16212@item
16213Write @TeX{} using the @code{@@TeX@{@}} command. Note the uppercase
16214@samp{T} and @samp{X}. This command causes the formatters to
16215typeset the name according to the wishes of Donald Knuth, who wrote
16216@TeX{}.
16217@end itemize
16218
16219@subsubheading Spaces
16220
16221Do not use spaces to format a Texinfo file, except inside of
16222@code{@@example} @dots{} @code{@@end example} and similar commands.
16223
16224@need 700
16225For example, @TeX{} fills the following:
16226
16227@example
16228@group
16229 @@kbd@{C-x v@}
16230 @@kbd@{M-x vc-next-action@}
16231 Perform the next logical operation
16232 on the version-controlled file
16233 corresponding to the current buffer.
16234@end group
16235@end example
16236
16237@need 950
16238@noindent
16239so it looks like this:
16240
16241@iftex
16242@quotation
16243 @kbd{C-x v}
16244 @kbd{M-x vc-next-action}
16245 Perform the next logical operation on the version-controlled file
16246 corresponding to the current buffer.
16247@end quotation
16248@end iftex
16249@ifinfo
16250@quotation
16251`C-x v' `M-x vc-next-action' Perform the next logical operation on the
16252version-controlled file corresponding to the current buffer.
16253@end quotation
16254@end ifinfo
16255
16256@noindent
16257In this case, the text should be formatted with
16258@code{@@table}, @code{@@item}, and @code{@@itemx}, to create a table.
16259
16260@subsubheading @@code, @@samp, @@var, and @samp{---}
16261
16262@itemize @bullet
16263@item
16264Use @code{@@code} around Lisp symbols, including command names.
16265For example,
16266
16267@example
16268The main function is @@code@{vc-next-action@}, @dots{}
16269@end example
16270
16271@item
16272Avoid putting letters such as @samp{s} immediately after an
16273@samp{@@code}. Such letters look bad.
16274
16275@item
16276Use @code{@@var} around meta-variables. Do not write angle brackets
16277around them.
16278
16279@item
16280Use three hyphens in a row, @samp{---}, to indicate a long dash. @TeX{}
16281typesets these as a long dash and the Info formatters reduce three
16282hyphens to two.
16283@end itemize
16284
16285@subsubheading Periods Outside of Quotes
16286
16287Place periods and other punctuation marks @emph{outside} of quotations,
16288unless the punctuation is part of the quotation. This practice goes
16289against publishing conventions in the United States, but enables the
16290reader to distinguish between the contents of the quotation and the
16291whole passage.
16292
16293For example, you should write the following sentence with the period
16294outside the end quotation marks:
16295
16296@example
16297Evidently, @samp{au} is an abbreviation for ``author''.
16298@end example
16299
16300@noindent
16301since @samp{au} does @emph{not} serve as an abbreviation for
16302@samp{author.} (with a period following the word).
16303
16304@subsubheading Introducing New Terms
16305
16306@itemize @bullet
16307@item
16308Introduce new terms so that a reader who does not know them can
16309understand them from context; or write a definition for the term.
16310
16311For example, in the following, the terms ``check in'', ``register'' and
16312``delta'' are all appearing for the first time; the example sentence should be
16313rewritten so they are understandable.
16314
16315@quotation
16316The major function assists you in checking in a file to your
16317version control system and registering successive sets of changes to
16318it as deltas.
16319@end quotation
16320
16321@item
16322Use the @code{@@dfn} command around a word being introduced, to indicate
16323that the reader should not expect to know the meaning already, and
16324should expect to learn the meaning from this passage.
16325@end itemize
16326
16327@subsubheading @@pxref
16328
16329@c !!! maybe include this in the tips on pxref
16330@ignore
16331By the way, it is okay to use pxref with something else in front of
16332it within the parens, as long as the pxref is followed by the close
16333paren, and the material inside the parens is not part of a larger
16334sentence. Also, you can use xref inside parens as part of a complete
16335sentence so long as you terminate the cross reference with punctuation.
16336@end ignore
16337Absolutely never use @code{@@pxref} except in the special context for
16338which it is designed: inside parentheses, with the closing parenthesis
16339following immediately after the closing brace. One formatter
16340automatically inserts closing punctuation and the other does not. This
16341means that the output looks right both in printed output and in an Info
16342file, but only when the command is used inside parentheses.
16343
16344@subsubheading Invoking from a Shell
16345
16346You can invoke programs such as Emacs, GCC, and @code{gawk} from a
16347shell. The documentation for each program should contain a section that
16348describes this. Unfortunately, if the node names and titles for these
16349sections are all different, they are difficult for users to find.
16350
16351So, there is a convention to name such sections with a phrase beginning
16352with the word `Invoking', as in `Invoking Emacs'; this way, users can
16353find the section easily.
16354
16355
16356@subsubheading ANSI C Syntax
16357
16358When you use @code{@@example} to describe a C function's calling
16359conventions, use the ANSI C syntax, like this:@refill
16360
16361@example
16362void dld_init (char *@@var@{path@});
16363@end example
16364
16365@noindent
16366And in the subsequent discussion, refer to the argument values by
16367writing the same argument names, again highlighted with
16368@code{@@var}.@refill
16369
16370@need 800
16371Avoid the obsolete style that looks like this:@refill
16372
16373@example
16374#include <dld.h>
16375
16376dld_init (path)
16377char *path;
16378@end example
16379
16380Also, it is best to avoid writing @code{#include} above the
16381declaration just to indicate that the function is declared in a
16382header file. The practice may give the misimpression that the
16383@code{#include} belongs near the declaration of the function. Either
16384state explicitly which header file holds the declaration or, better
16385yet, name the header file used for a group of functions at the
16386beginning of the section that describes the functions.@refill
16387
16388@subsubheading Bad Examples
16389
16390Here are several examples of bad writing to avoid:
16391
16392In this example, say, `` @dots{} you must @code{@@dfn}@{check
16393in@} the new version.'' That flows better.
16394
16395@quotation
16396When you are done editing the file, you must perform a
16397@code{@@dfn}@{check in@}.
16398@end quotation
16399
16400In the following example, say, ``@dots{} makes a unified interface such as VC
16401mode possible.''
16402
16403@quotation
16404SCCS, RCS and other version-control systems all perform similar
16405functions in broadly similar ways (it is this resemblance which makes
16406a unified control mode like this possible).
16407@end quotation
16408
16409And in this example, you should specify what `it' refers to:
16410
16411@quotation
16412If you are working with other people, it assists in coordinating
16413everyone's changes so they do not step on each other.
16414@end quotation
16415
16416@subsubheading And Finally @dots{}
16417
16418@itemize @bullet
16419@item
16420Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last
16421sound in the name `Bach'. But pronounce Texinfo as in `speck':
16422``teckinfo''.
16423
16424@item
16425Write notes for yourself at the very end of a Texinfo file after the
16426@code{@@bye}. None of the formatters process text after the
16427@code{@@bye}; it is as if the text were within @code{@@ignore} @dots{}
16428@code{@@end ignore}.
16429@end itemize
16430
16431
| 16281@subsubheading Definition Commands
16282
16283Definition commands are @code{@@deffn}, @code{@@defun},
16284@code{@@defmac}, and the like, and enable you to write descriptions in
16285a uniform format.@refill
16286
16287@itemize @bullet
16288@item
16289Write just one definition command for each entity you define with a
16290definition command. The automatic indexing feature creates an index
16291entry that leads the reader to the definition.
16292
16293@item
16294Use @code{@@table} @dots{} @code{@@end table} in an appendix that
16295contains a summary of functions, not @code{@@deffn} or other definition
16296commands.
16297@end itemize
16298
16299@subsubheading Capitalization
16300
16301@itemize @bullet
16302@item
16303Capitalize ``Texinfo''; it is a name. Do not write the @samp{x} or
16304@samp{i} in upper case.
16305
16306@item
16307Capitalize ``Info''; it is a name.
16308
16309@item
16310Write @TeX{} using the @code{@@TeX@{@}} command. Note the uppercase
16311@samp{T} and @samp{X}. This command causes the formatters to
16312typeset the name according to the wishes of Donald Knuth, who wrote
16313@TeX{}.
16314@end itemize
16315
16316@subsubheading Spaces
16317
16318Do not use spaces to format a Texinfo file, except inside of
16319@code{@@example} @dots{} @code{@@end example} and similar commands.
16320
16321@need 700
16322For example, @TeX{} fills the following:
16323
16324@example
16325@group
16326 @@kbd@{C-x v@}
16327 @@kbd@{M-x vc-next-action@}
16328 Perform the next logical operation
16329 on the version-controlled file
16330 corresponding to the current buffer.
16331@end group
16332@end example
16333
16334@need 950
16335@noindent
16336so it looks like this:
16337
16338@iftex
16339@quotation
16340 @kbd{C-x v}
16341 @kbd{M-x vc-next-action}
16342 Perform the next logical operation on the version-controlled file
16343 corresponding to the current buffer.
16344@end quotation
16345@end iftex
16346@ifinfo
16347@quotation
16348`C-x v' `M-x vc-next-action' Perform the next logical operation on the
16349version-controlled file corresponding to the current buffer.
16350@end quotation
16351@end ifinfo
16352
16353@noindent
16354In this case, the text should be formatted with
16355@code{@@table}, @code{@@item}, and @code{@@itemx}, to create a table.
16356
16357@subsubheading @@code, @@samp, @@var, and @samp{---}
16358
16359@itemize @bullet
16360@item
16361Use @code{@@code} around Lisp symbols, including command names.
16362For example,
16363
16364@example
16365The main function is @@code@{vc-next-action@}, @dots{}
16366@end example
16367
16368@item
16369Avoid putting letters such as @samp{s} immediately after an
16370@samp{@@code}. Such letters look bad.
16371
16372@item
16373Use @code{@@var} around meta-variables. Do not write angle brackets
16374around them.
16375
16376@item
16377Use three hyphens in a row, @samp{---}, to indicate a long dash. @TeX{}
16378typesets these as a long dash and the Info formatters reduce three
16379hyphens to two.
16380@end itemize
16381
16382@subsubheading Periods Outside of Quotes
16383
16384Place periods and other punctuation marks @emph{outside} of quotations,
16385unless the punctuation is part of the quotation. This practice goes
16386against publishing conventions in the United States, but enables the
16387reader to distinguish between the contents of the quotation and the
16388whole passage.
16389
16390For example, you should write the following sentence with the period
16391outside the end quotation marks:
16392
16393@example
16394Evidently, @samp{au} is an abbreviation for ``author''.
16395@end example
16396
16397@noindent
16398since @samp{au} does @emph{not} serve as an abbreviation for
16399@samp{author.} (with a period following the word).
16400
16401@subsubheading Introducing New Terms
16402
16403@itemize @bullet
16404@item
16405Introduce new terms so that a reader who does not know them can
16406understand them from context; or write a definition for the term.
16407
16408For example, in the following, the terms ``check in'', ``register'' and
16409``delta'' are all appearing for the first time; the example sentence should be
16410rewritten so they are understandable.
16411
16412@quotation
16413The major function assists you in checking in a file to your
16414version control system and registering successive sets of changes to
16415it as deltas.
16416@end quotation
16417
16418@item
16419Use the @code{@@dfn} command around a word being introduced, to indicate
16420that the reader should not expect to know the meaning already, and
16421should expect to learn the meaning from this passage.
16422@end itemize
16423
16424@subsubheading @@pxref
16425
16426@c !!! maybe include this in the tips on pxref
16427@ignore
16428By the way, it is okay to use pxref with something else in front of
16429it within the parens, as long as the pxref is followed by the close
16430paren, and the material inside the parens is not part of a larger
16431sentence. Also, you can use xref inside parens as part of a complete
16432sentence so long as you terminate the cross reference with punctuation.
16433@end ignore
16434Absolutely never use @code{@@pxref} except in the special context for
16435which it is designed: inside parentheses, with the closing parenthesis
16436following immediately after the closing brace. One formatter
16437automatically inserts closing punctuation and the other does not. This
16438means that the output looks right both in printed output and in an Info
16439file, but only when the command is used inside parentheses.
16440
16441@subsubheading Invoking from a Shell
16442
16443You can invoke programs such as Emacs, GCC, and @code{gawk} from a
16444shell. The documentation for each program should contain a section that
16445describes this. Unfortunately, if the node names and titles for these
16446sections are all different, they are difficult for users to find.
16447
16448So, there is a convention to name such sections with a phrase beginning
16449with the word `Invoking', as in `Invoking Emacs'; this way, users can
16450find the section easily.
16451
16452
16453@subsubheading ANSI C Syntax
16454
16455When you use @code{@@example} to describe a C function's calling
16456conventions, use the ANSI C syntax, like this:@refill
16457
16458@example
16459void dld_init (char *@@var@{path@});
16460@end example
16461
16462@noindent
16463And in the subsequent discussion, refer to the argument values by
16464writing the same argument names, again highlighted with
16465@code{@@var}.@refill
16466
16467@need 800
16468Avoid the obsolete style that looks like this:@refill
16469
16470@example
16471#include <dld.h>
16472
16473dld_init (path)
16474char *path;
16475@end example
16476
16477Also, it is best to avoid writing @code{#include} above the
16478declaration just to indicate that the function is declared in a
16479header file. The practice may give the misimpression that the
16480@code{#include} belongs near the declaration of the function. Either
16481state explicitly which header file holds the declaration or, better
16482yet, name the header file used for a group of functions at the
16483beginning of the section that describes the functions.@refill
16484
16485@subsubheading Bad Examples
16486
16487Here are several examples of bad writing to avoid:
16488
16489In this example, say, `` @dots{} you must @code{@@dfn}@{check
16490in@} the new version.'' That flows better.
16491
16492@quotation
16493When you are done editing the file, you must perform a
16494@code{@@dfn}@{check in@}.
16495@end quotation
16496
16497In the following example, say, ``@dots{} makes a unified interface such as VC
16498mode possible.''
16499
16500@quotation
16501SCCS, RCS and other version-control systems all perform similar
16502functions in broadly similar ways (it is this resemblance which makes
16503a unified control mode like this possible).
16504@end quotation
16505
16506And in this example, you should specify what `it' refers to:
16507
16508@quotation
16509If you are working with other people, it assists in coordinating
16510everyone's changes so they do not step on each other.
16511@end quotation
16512
16513@subsubheading And Finally @dots{}
16514
16515@itemize @bullet
16516@item
16517Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last
16518sound in the name `Bach'. But pronounce Texinfo as in `speck':
16519``teckinfo''.
16520
16521@item
16522Write notes for yourself at the very end of a Texinfo file after the
16523@code{@@bye}. None of the formatters process text after the
16524@code{@@bye}; it is as if the text were within @code{@@ignore} @dots{}
16525@code{@@end ignore}.
16526@end itemize
16527
16528
|
16432@node Sample Texinfo File
16433@appendix A Sample Texinfo File
| 16529@node Sample Texinfo Files
16530@appendix Sample Texinfo Files
16531@cindex Sample Texinfo files
16532
16533The first example is from the first chapter (@pxref{Short Sample}),
16534given here in its entirety, without commentary. The second sample
16535includes the full texts to be used in GNU manuals.
16536
16537@menu
16538* Short Sample Texinfo File::
16539* GNU Sample Texts::
16540@end menu
16541
16542
16543@node Short Sample Texinfo File
16544@section Short Sample
|
16434@cindex Sample Texinfo file, no comments
16435
16436Here is a complete, short sample Texinfo file, without any commentary.
| 16545@cindex Sample Texinfo file, no comments
16546
16547Here is a complete, short sample Texinfo file, without any commentary.
|
16437You can see this file, with comments, in the first chapter.
16438@xref{Short Sample, , A Short Sample Texinfo File}.
| 16548You can see this file, with comments, in the first chapter. @xref{Short
16549Sample}.
|
16439
| 16550
|
| 16551In a nutshell: The @command{makeinfo} program transforms a Texinfo
16552source file such as this into an Info file or HTML; and @TeX{} typesets
16553it for a printed manual.
16554
16555
|
16440@sp 1
16441@example
16442\input texinfo @@c -*-texinfo-*-
16443@@c %**start of header
16444@@setfilename sample.info
| 16556@sp 1
16557@example
16558\input texinfo @@c -*-texinfo-*-
16559@@c %**start of header
16560@@setfilename sample.info
|
16445@@settitle Sample Document
| 16561@@settitle Sample Manual 1.0
|
16446@@c %**end of header
16447
| 16562@@c %**end of header
16563
|
16448@@ifinfo
| 16564@@copying
|
16449This is a short example of a complete Texinfo file.
16450
16451Copyright (C) 2002 Free Software Foundation, Inc.
| 16565This is a short example of a complete Texinfo file.
16566
16567Copyright (C) 2002 Free Software Foundation, Inc.
|
16452@@end ifinfo
| 16568@@end copying
|
16453
16454@@titlepage
| 16569
16570@@titlepage
|
16455@@comment The title is printed in a large font.
| |
16456@@title Sample Title
| 16571@@title Sample Title
|
16457
16458@@c The following two commands start the copyright page.
| |
16459@@page
16460@@vskip 0pt plus 1filll
| 16572@@page
16573@@vskip 0pt plus 1filll
|
16461Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
| 16574@@insertcopying
|
16462@@end titlepage
16463
16464@@c Output the table of the contents at the beginning.
16465@@contents
16466
16467@@ifnottex
16468@@node Top
16469
| 16575@@end titlepage
16576
16577@@c Output the table of the contents at the beginning.
16578@@contents
16579
16580@@ifnottex
16581@@node Top
16582
|
16470This is the top node of a sample document.
| 16583@@insertcopying
|
16471@@end ifnottex
16472
16473@@menu
16474* First Chapter:: The first chapter is the
| 16584@@end ifnottex
16585
16586@@menu
16587* First Chapter:: The first chapter is the
|
16475 only chapter in this sample.
16476* Concept Index:: This index has two entries.
| 16588 only chapter in this sample.
16589* Index:: Complete index.
|
16477@@end menu
16478
16479
| 16590@@end menu
16591
16592
|
16480@@node First Chapter
| 16593@@node First Chapter
|
16481@@chapter First Chapter
| 16594@@chapter First Chapter
|
16482@@cindex Chapter, first
| |
16483
| 16595
|
16484This is the contents of the first chapter.
16485@@cindex Another sample index entry
| 16596@@cindex chapter, first
|
16486
| 16597
|
| 16598This is the first chapter.
16599@@cindex index entry, another
16600
|
16487Here is a numbered list.
16488
16489@@enumerate
16490@@item
16491This is the first item.
16492
16493@@item
16494This is the second item.
16495@@end enumerate
16496
| 16601Here is a numbered list.
16602
16603@@enumerate
16604@@item
16605This is the first item.
16606
16607@@item
16608This is the second item.
16609@@end enumerate
16610
|
16497The @@code@{makeinfo@} command transforms a Texinfo source file
16498such as this into an Info file or HTML; and @@TeX typesets it
16499for a printed manual.
| |
16500
| 16611
|
| 16612@@node Index
16613@@unnumbered Index
|
16501
| 16614
|
16502@@node Concept Index
16503@@unnumbered Concept Index
| 16615@@printindex cp
|
16504
| 16616
|
| 16617@@bye
16618@end example
16619
16620
16621@node GNU Sample Texts
16622@section GNU Sample Texts
16623
16624@cindex GNU sample texts
16625@cindex Sample texts, GNU
16626@cindex Full texts, GNU
16627
16628Here is a sample Texinfo document with the full texts that should be
16629used in GNU manuals.
16630
16631As well as the legal texts, it also serves as a practical example of how
16632many elements in a GNU system can affect the manual. If you're not
16633familiar with all these different elements, don't worry. They're not
16634required and a perfectly good manual can be written without them.
16635They're included here nonetheless because many manuals do (or could)
16636benefit from them.
16637
16638@xref{Short Sample}, for a minimal example of a Texinfo file.
16639@xref{Beginning a File}, for a full explanation of that minimal
16640example.
16641
16642Here are some notes on the example:
16643
16644@itemize @bullet
16645@item
16646@cindex $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $ comment
16647@cindex CVS $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $, in Texinfo
16648@cindex RCS $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $, in Texinfo
16649The @samp{$Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $} comment is for CVS (@pxref{Top,, Overview, cvs,
16650Concurrent Versions System}) or RCS (see rcsintro(1)) version control
16651systems, which expand it into a string such as:
16652@example
16653$Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $
16654@end example
16655(This is useful in all sources that use version control, not just manuals.)
16656
16657@item
16658@pindex automake@r{, and version info}
16659The @file{version.texi} in the @code{@@include} command is maintained
16660automatically by Automake (@pxref{Top,, Introduction, automake, GNU
16661Automake}). It sets the @samp{VERSION} and @samp{UPDATED} values used
16662elsewhere. If your distribution doesn't use Automake, you can mimic
16663these or equivalent settings.
16664
16665@item
16666The @code{@@syncodeindex} command reflects the recommendation to use only
16667one index if at all possible, to make it easier for readers.
16668
16669@item
16670The @code{@@dircategory} is for constructing the Info directory.
16671@xref{Installing Dir Entries}, which includes a variety of recommended
16672category names.
16673
16674@item
16675The `Invoking' node is a GNU standard to help users find the basic
16676information about command-line usage of a given program. @xref{Manual
16677Structure Details,,,standards, GNU Coding Standards}.
16678
16679@item
16680It is best to include the entire GNU Free Documentation License in a GNU
16681manual, unless the manual is only a few pages long. Of course this
16682sample is even shorter than that, but it includes the FDL anyway in
16683order to show one conventional way of doing so. The @file{fdl.texi}
16684file is available on the GNU machines (and in the Texinfo and other GNU
16685distributions).
16686
16687The FDL provides for omitting itself under certain conditions, but in
16688that case the sample texts given here have to be modified. @xref{GNU
16689Free Documentation License}.
16690
16691@item
16692If your manual has invariant sections (again, see the license itself for
16693details), then don't forget to include them.
16694@end itemize
16695
16696Here is the sample document:
16697
16698@c We do the first part of this with @example instead of @verbatim
16699@c because the literal @setfilename and @include confuse Automake. Argh.
16700@example
16701\input texinfo @@c -*-texinfo-*-
16702@@comment $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $
16703@@comment %**start of header
16704@@setfilename sample.info
16705@@include version.texi
16706@@settitle GNU Sample @@value@{VERSION@}
16707@@syncodeindex pg cp
16708@@comment %**end of header
16709@@copying
16710This manual is for GNU Sample
16711(version @@value@{VERSION@}, @@value@{UPDATED@}),
16712which is an example in the Texinfo documentation.
16713
16714Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
16715
16716@@quotation
16717Permission is granted to copy, distribute and/or modify this document
16718under the terms of the GNU Free Documentation License, Version 1.1 or
16719any later version published by the Free Software Foundation; with no
16720Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
16721and with the Back-Cover Texts as in (a) below. A copy of the
16722license is included in the section entitled ``GNU Free Documentation
16723License.''
16724
16725(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
16726this GNU Manual, like GNU software. Copies published by the Free
16727Software Foundation raise funds for GNU development.''
16728@@end quotation
16729@@end copying
16730
16731@@dircategory Texinfo documentation system
16732@@direntry
16733* sample: (sample)Invoking sample.
16734@@end direntry
16735
16736@@titlepage
16737@@title GNU Sample
16738@@subtitle for version @@value@{VERSION@}, @@value@{UPDATED@}
16739@@author A.U. Thor (@@email@{bug-texinfo@@@@gnu.org@})
16740@@page
16741@@vskip 0pt plus 1filll
16742@@insertcopying
16743@@end titlepage
16744
16745@@contents
16746
16747@@ifnottex
16748@@node Top
16749@@top GNU Sample
16750
16751@@insertcopying
16752@@end ifnottex
16753
16754@@menu
16755* Invoking sample::
16756* Copying This Manual::
16757* Index::
16758@@end menu
16759
16760
16761@@node Invoking sample
16762@@chapter Invoking sample
16763
16764@@pindex sample
16765@@cindex invoking @@command@{sample@}
16766
16767This is a sample manual. There is no sample program to
16768invoke, but if there was, you could see its basic usage
16769and command line options here.
16770
16771
16772@@node Copying This Manual
16773@@appendix Copying This Manual
16774
16775@@menu
16776* GNU Free Documentation License:: License for copying this manual.
16777@@end menu
16778
16779@@include fdl.texi
16780
16781
16782@@node Index
16783@@unnumbered Index
16784
|
16505@@printindex cp
16506
16507@@bye
16508@end example
16509
16510
16511@node Include Files
16512@appendix Include Files
16513@cindex Include files
16514
16515When @TeX{} or an Info formatting command sees an @code{@@include}
16516command in a Texinfo file, it processes the contents of the file named
16517by the command and incorporates them into the DVI or Info file being
16518created. Index entries from the included file are incorporated into
| 16785@@printindex cp
16786
16787@@bye
16788@end example
16789
16790
16791@node Include Files
16792@appendix Include Files
16793@cindex Include files
16794
16795When @TeX{} or an Info formatting command sees an @code{@@include}
16796command in a Texinfo file, it processes the contents of the file named
16797by the command and incorporates them into the DVI or Info file being
16798created. Index entries from the included file are incorporated into
|
16519the indices of the output file.@refill
| 16799the indices of the output file.
|
16520
16521Include files let you keep a single large document as a collection of
16522conveniently small parts.
16523
16524@menu
16525* Using Include Files:: How to use the @code{@@include} command.
16526* texinfo-multiple-files-update:: How to create and update nodes and
16527 menus when using included files.
16528* Include File Requirements:: What @code{texinfo-multiple-files-update} expects.
16529* Sample Include File:: A sample outer file with included files
16530 within it; and a sample included file.
16531* Include Files Evolution:: How use of the @code{@@include} command
16532 has changed over time.
16533@end menu
16534
16535@node Using Include Files, texinfo-multiple-files-update, Include Files, Include Files
16536@section How to Use Include Files
16537@findex include
16538
16539To include another file within a Texinfo file, write the
16540@code{@@include} command at the beginning of a line and follow it on
16541the same line by the name of a file to be included. For
16542example:@refill
16543
16544@example
16545@@include buffers.texi
16546@end example
16547
16548An included file should simply be a segment of text that you expect to
16549be included as is into the overall or @dfn{outer} Texinfo file; it
16550should not contain the standard beginning and end parts of a Texinfo
16551file. In particular, you should not start an included file with a
16552line saying @samp{\input texinfo}; if you do, that phrase is inserted
16553into the output file as is. Likewise, you should not end an included
16554file with an @code{@@bye} command; nothing after @code{@@bye} is
16555formatted.@refill
16556
16557In the past, you were required to write an @code{@@setfilename} line at the
16558beginning of an included file, but no longer. Now, it does not matter
16559whether you write such a line. If an @code{@@setfilename} line exists
16560in an included file, it is ignored.@refill
16561
16562Conventionally, an included file begins with an @code{@@node} line that
16563is followed by an @code{@@chapter} line. Each included file is one
16564chapter. This makes it easy to use the regular node and menu creating
16565and updating commands to create the node pointers and menus within the
16566included file. However, the simple Emacs node and menu creating and
16567updating commands do not work with multiple Texinfo files. Thus you
16568cannot use these commands to fill in the `Next', `Previous', and `Up'
16569pointers of the @code{@@node} line that begins the included file. Also,
16570you cannot use the regular commands to create a master menu for the
16571whole file. Either you must insert the menus and the `Next',
16572`Previous', and `Up' pointers by hand, or you must use the GNU Emacs
16573Texinfo mode command, @code{texinfo-multiple-files-update}, that is
16574designed for @code{@@include} files.@refill
16575
16576@node texinfo-multiple-files-update, Include File Requirements, Using Include Files, Include Files
16577@section @code{texinfo-multiple-files-update}
16578@findex texinfo-multiple-files-update
16579
16580GNU Emacs Texinfo mode provides the @code{texinfo-multiple-files-update}
16581command. This command creates or updates `Next', `Previous', and `Up'
16582pointers of included files as well as those in the outer or overall
16583Texinfo file, and it creates or updates a main menu in the outer file.
16584Depending whether you call it with optional arguments, the command
16585updates only the pointers in the first @code{@@node} line of the
16586included files or all of them:@refill
16587
16588@table @kbd
16589@item M-x texinfo-multiple-files-update
16590Called without any arguments:@refill
16591
16592@itemize @minus
16593@item
16594Create or update the `Next', `Previous', and `Up' pointers of the
16595first @code{@@node} line in each file included in an outer or overall
16596Texinfo file.@refill
16597
16598@item
16599Create or update the `Top' level node pointers of the outer or
16600overall file.@refill
16601
16602@item
16603Create or update a main menu in the outer file.@refill
16604@end itemize
16605
16606@item C-u M-x texinfo-multiple-files-update
16607Called with @kbd{C-u} as a prefix argument:
16608
16609@itemize @minus{}
16610@item
16611Create or update pointers in the first @code{@@node} line in each
16612included file.
16613
16614@item
16615Create or update the `Top' level node pointers of the outer file.
16616
16617@item
16618Create and insert a master menu in the outer file. The master menu
16619is made from all the menus in all the included files.@refill
16620@end itemize
16621
16622@item C-u 8 M-x texinfo-multiple-files-update
16623Called with a numeric prefix argument, such as @kbd{C-u 8}:
16624
16625@itemize @minus
16626@item
16627Create or update @strong{all} the `Next', `Previous', and `Up' pointers
16628of all the included files.@refill
16629
16630@item
16631Create or update @strong{all} the menus of all the included
16632files.@refill
16633
16634@item
16635Create or update the `Top' level node pointers of the outer or
16636overall file.@refill
16637
16638@item
16639And then create a master menu in the outer file. This is similar to
16640invoking @code{texinfo-master-menu} with an argument when you are
16641working with just one file.@refill
16642@end itemize
16643@end table
16644
16645Note the use of the prefix argument in interactive use: with a regular
16646prefix argument, just @w{@kbd{C-u}}, the
16647@code{texinfo-multiple-files-update} command inserts a master menu;
16648with a numeric prefix argument, such as @kbd{C-u 8}, the command
16649updates @strong{every} pointer and menu in @strong{all} the files and then inserts a
16650master menu.@refill
16651
16652
16653@node Include File Requirements
16654@section Include File Requirements
16655@cindex Include file requirements
16656@cindex Requirements for include files
16657
16658If you plan to use the @code{texinfo-multiple-files-update} command,
16659the outer Texinfo file that lists included files within it should
16660contain nothing but the beginning and end parts of a Texinfo file, and
16661a number of @code{@@include} commands listing the included files. It
16662should not even include indices, which should be listed in an included
16663file of their own.@refill
16664
16665Moreover, each of the included files must contain exactly one highest
16666level node (conventionally, @code{@@chapter} or equivalent),
16667and this node must be the first node in the included file.
16668Furthermore, each of these highest level nodes in each included file
16669must be at the same hierarchical level in the file structure.
16670Usually, each is an @code{@@chapter}, an @code{@@appendix}, or an
16671@code{@@unnumbered} node. Thus, normally, each included file contains
16672one, and only one, chapter or equivalent-level node.@refill
16673
16674The outer file should contain only @emph{one} node, the `Top' node. It
16675should @emph{not} contain any nodes besides the single `Top' node. The
16676@code{texinfo-multiple-files-update} command will not process
16677them.@refill
16678
16679@node Sample Include File, Include Files Evolution, Include File Requirements, Include Files
16680@section Sample File with @code{@@include}
16681@cindex Sample @code{@@include} file
16682@cindex Include file sample
16683@cindex @code{@@include} file sample
16684
16685Here is an example of a complete outer Texinfo file with @code{@@include} files
16686within it before running @code{texinfo-multiple-files-update}, which
16687would insert a main or master menu:@refill
16688
16689@example
16690@group
16691\input texinfo @@c -*-texinfo-*-
16692@c %**start of header
16693@@setfilename include-example.info
16694@@settitle Include Example
16695@c %**end of header
16696@end group
16697
16698@group
16699@@setchapternewpage odd
16700@@titlepage
16701@@sp 12
16702@@center @@titlefont@{Include Example@}
16703@@sp 2
16704@@center by Whom Ever
16705@end group
16706
16707@group
16708@@page
16709@@vskip 0pt plus 1filll
16710Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
16711@@end titlepage
16712@end group
16713
16714@group
16715@@ifinfo
16716@@node Top, First, , (dir)
16717@@top Master Menu
16718@@end ifinfo
16719@end group
16720
16721@group
16722@@include foo.texinfo
16723@@include bar.texinfo
16724@@include concept-index.texinfo
16725@end group
16726
16727@group
16728@@summarycontents
16729@@contents
16730
16731@@bye
16732@end group
16733@end example
16734
| 16800
16801Include files let you keep a single large document as a collection of
16802conveniently small parts.
16803
16804@menu
16805* Using Include Files:: How to use the @code{@@include} command.
16806* texinfo-multiple-files-update:: How to create and update nodes and
16807 menus when using included files.
16808* Include File Requirements:: What @code{texinfo-multiple-files-update} expects.
16809* Sample Include File:: A sample outer file with included files
16810 within it; and a sample included file.
16811* Include Files Evolution:: How use of the @code{@@include} command
16812 has changed over time.
16813@end menu
16814
16815@node Using Include Files, texinfo-multiple-files-update, Include Files, Include Files
16816@section How to Use Include Files
16817@findex include
16818
16819To include another file within a Texinfo file, write the
16820@code{@@include} command at the beginning of a line and follow it on
16821the same line by the name of a file to be included. For
16822example:@refill
16823
16824@example
16825@@include buffers.texi
16826@end example
16827
16828An included file should simply be a segment of text that you expect to
16829be included as is into the overall or @dfn{outer} Texinfo file; it
16830should not contain the standard beginning and end parts of a Texinfo
16831file. In particular, you should not start an included file with a
16832line saying @samp{\input texinfo}; if you do, that phrase is inserted
16833into the output file as is. Likewise, you should not end an included
16834file with an @code{@@bye} command; nothing after @code{@@bye} is
16835formatted.@refill
16836
16837In the past, you were required to write an @code{@@setfilename} line at the
16838beginning of an included file, but no longer. Now, it does not matter
16839whether you write such a line. If an @code{@@setfilename} line exists
16840in an included file, it is ignored.@refill
16841
16842Conventionally, an included file begins with an @code{@@node} line that
16843is followed by an @code{@@chapter} line. Each included file is one
16844chapter. This makes it easy to use the regular node and menu creating
16845and updating commands to create the node pointers and menus within the
16846included file. However, the simple Emacs node and menu creating and
16847updating commands do not work with multiple Texinfo files. Thus you
16848cannot use these commands to fill in the `Next', `Previous', and `Up'
16849pointers of the @code{@@node} line that begins the included file. Also,
16850you cannot use the regular commands to create a master menu for the
16851whole file. Either you must insert the menus and the `Next',
16852`Previous', and `Up' pointers by hand, or you must use the GNU Emacs
16853Texinfo mode command, @code{texinfo-multiple-files-update}, that is
16854designed for @code{@@include} files.@refill
16855
16856@node texinfo-multiple-files-update, Include File Requirements, Using Include Files, Include Files
16857@section @code{texinfo-multiple-files-update}
16858@findex texinfo-multiple-files-update
16859
16860GNU Emacs Texinfo mode provides the @code{texinfo-multiple-files-update}
16861command. This command creates or updates `Next', `Previous', and `Up'
16862pointers of included files as well as those in the outer or overall
16863Texinfo file, and it creates or updates a main menu in the outer file.
16864Depending whether you call it with optional arguments, the command
16865updates only the pointers in the first @code{@@node} line of the
16866included files or all of them:@refill
16867
16868@table @kbd
16869@item M-x texinfo-multiple-files-update
16870Called without any arguments:@refill
16871
16872@itemize @minus
16873@item
16874Create or update the `Next', `Previous', and `Up' pointers of the
16875first @code{@@node} line in each file included in an outer or overall
16876Texinfo file.@refill
16877
16878@item
16879Create or update the `Top' level node pointers of the outer or
16880overall file.@refill
16881
16882@item
16883Create or update a main menu in the outer file.@refill
16884@end itemize
16885
16886@item C-u M-x texinfo-multiple-files-update
16887Called with @kbd{C-u} as a prefix argument:
16888
16889@itemize @minus{}
16890@item
16891Create or update pointers in the first @code{@@node} line in each
16892included file.
16893
16894@item
16895Create or update the `Top' level node pointers of the outer file.
16896
16897@item
16898Create and insert a master menu in the outer file. The master menu
16899is made from all the menus in all the included files.@refill
16900@end itemize
16901
16902@item C-u 8 M-x texinfo-multiple-files-update
16903Called with a numeric prefix argument, such as @kbd{C-u 8}:
16904
16905@itemize @minus
16906@item
16907Create or update @strong{all} the `Next', `Previous', and `Up' pointers
16908of all the included files.@refill
16909
16910@item
16911Create or update @strong{all} the menus of all the included
16912files.@refill
16913
16914@item
16915Create or update the `Top' level node pointers of the outer or
16916overall file.@refill
16917
16918@item
16919And then create a master menu in the outer file. This is similar to
16920invoking @code{texinfo-master-menu} with an argument when you are
16921working with just one file.@refill
16922@end itemize
16923@end table
16924
16925Note the use of the prefix argument in interactive use: with a regular
16926prefix argument, just @w{@kbd{C-u}}, the
16927@code{texinfo-multiple-files-update} command inserts a master menu;
16928with a numeric prefix argument, such as @kbd{C-u 8}, the command
16929updates @strong{every} pointer and menu in @strong{all} the files and then inserts a
16930master menu.@refill
16931
16932
16933@node Include File Requirements
16934@section Include File Requirements
16935@cindex Include file requirements
16936@cindex Requirements for include files
16937
16938If you plan to use the @code{texinfo-multiple-files-update} command,
16939the outer Texinfo file that lists included files within it should
16940contain nothing but the beginning and end parts of a Texinfo file, and
16941a number of @code{@@include} commands listing the included files. It
16942should not even include indices, which should be listed in an included
16943file of their own.@refill
16944
16945Moreover, each of the included files must contain exactly one highest
16946level node (conventionally, @code{@@chapter} or equivalent),
16947and this node must be the first node in the included file.
16948Furthermore, each of these highest level nodes in each included file
16949must be at the same hierarchical level in the file structure.
16950Usually, each is an @code{@@chapter}, an @code{@@appendix}, or an
16951@code{@@unnumbered} node. Thus, normally, each included file contains
16952one, and only one, chapter or equivalent-level node.@refill
16953
16954The outer file should contain only @emph{one} node, the `Top' node. It
16955should @emph{not} contain any nodes besides the single `Top' node. The
16956@code{texinfo-multiple-files-update} command will not process
16957them.@refill
16958
16959@node Sample Include File, Include Files Evolution, Include File Requirements, Include Files
16960@section Sample File with @code{@@include}
16961@cindex Sample @code{@@include} file
16962@cindex Include file sample
16963@cindex @code{@@include} file sample
16964
16965Here is an example of a complete outer Texinfo file with @code{@@include} files
16966within it before running @code{texinfo-multiple-files-update}, which
16967would insert a main or master menu:@refill
16968
16969@example
16970@group
16971\input texinfo @@c -*-texinfo-*-
16972@c %**start of header
16973@@setfilename include-example.info
16974@@settitle Include Example
16975@c %**end of header
16976@end group
16977
16978@group
16979@@setchapternewpage odd
16980@@titlepage
16981@@sp 12
16982@@center @@titlefont@{Include Example@}
16983@@sp 2
16984@@center by Whom Ever
16985@end group
16986
16987@group
16988@@page
16989@@vskip 0pt plus 1filll
16990Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
16991@@end titlepage
16992@end group
16993
16994@group
16995@@ifinfo
16996@@node Top, First, , (dir)
16997@@top Master Menu
16998@@end ifinfo
16999@end group
17000
17001@group
17002@@include foo.texinfo
17003@@include bar.texinfo
17004@@include concept-index.texinfo
17005@end group
17006
17007@group
17008@@summarycontents
17009@@contents
17010
17011@@bye
17012@end group
17013@end example
17014
|
16735An included file, such as @file{foo.texinfo}, might look like
16736this:@refill
| 17015An included file, such as @file{foo.texinfo}, might look like this:
|
16737
16738@example
16739@group
16740@@node First, Second, , Top
16741@@chapter First Chapter
16742
16743Contents of first chapter @dots{}
16744@end group
16745@end example
16746
16747The full contents of @file{concept-index.texinfo} might be as simple as this:
16748
16749@example
16750@group
16751@@node Concept Index
16752@@unnumbered Concept Index
16753
16754@@printindex cp
16755@end group
16756@end example
16757
16758The outer Texinfo source file for @cite{The GNU Emacs Lisp Reference
16759Manual} is named @file{elisp.texi}. This outer file contains a master
16760menu with 417 entries and a list of 41 @code{@@include}
16761files.@refill
16762
16763
16764@node Include Files Evolution
16765@section Evolution of Include Files
16766
16767When Info was first created, it was customary to create many small
16768Info files on one subject. Each Info file was formatted from its own
16769Texinfo source file. This custom meant that Emacs did not need to
16770make a large buffer to hold the whole of a large Info file when
16771someone wanted information; instead, Emacs allocated just enough
16772memory for the small Info file that contained the particular
16773information sought. This way, Emacs could avoid wasting memory.@refill
16774
16775References from one file to another were made by referring to the file
16776name as well as the node name. (@xref{Other Info Files, , Referring to
16777Other Info Files}. Also, see @ref{Four and Five Arguments, ,
16778@code{@@xref} with Four and Five Arguments}.)@refill
16779
16780Include files were designed primarily as a way to create a single,
16781large printed manual out of several smaller Info files. In a printed
16782manual, all the references were within the same document, so @TeX{}
16783could automatically determine the references' page numbers. The Info
16784formatting commands used include files only for creating joint
16785indices; each of the individual Texinfo files had to be formatted for
16786Info individually. (Each, therefore, required its own
16787@code{@@setfilename} line.)@refill
16788
16789However, because large Info files are now split automatically, it is
16790no longer necessary to keep them small.@refill
16791
16792Nowadays, multiple Texinfo files are used mostly for large documents,
16793such as @cite{The GNU Emacs Lisp Reference Manual}, and for projects
16794in which several different people write different sections of a
16795document simultaneously.@refill
16796
16797In addition, the Info formatting commands have been extended to work
16798with the @code{@@include} command so as to create a single large Info
16799file that is split into smaller files if necessary. This means that
16800you can write menus and cross references without naming the different
16801Texinfo files.@refill
16802
16803
16804@node Headings
16805@appendix Page Headings
16806@cindex Headings
16807@cindex Footings
16808@cindex Page numbering
16809@cindex Page headings
16810@cindex Formatting headings and footings
16811
16812Most printed manuals contain headings along the top of every page
16813except the title and copyright pages. Some manuals also contain
16814footings. (Headings and footings have no meaning to Info, which is
16815not paginated.)@refill
16816
16817@menu
16818* Headings Introduced:: Conventions for using page headings.
16819* Heading Format:: Standard page heading formats.
16820* Heading Choice:: How to specify the type of page heading.
16821* Custom Headings:: How to create your own headings and footings.
16822@end menu
16823
16824@node Headings Introduced, Heading Format, Headings, Headings
16825@ifinfo
16826@heading Headings Introduced
16827@end ifinfo
16828
16829Texinfo provides standard page heading formats for manuals that are
16830printed on one side of each sheet of paper and for manuals that are
16831printed on both sides of the paper. Typically, you will use these
16832formats, but you can specify your own format if you wish.@refill
16833
16834In addition, you can specify whether chapters should begin on a new
16835page, or merely continue the same page as the previous chapter; and if
16836chapters begin on new pages, you can specify whether they must be
16837odd-numbered pages.@refill
16838
16839By convention, a book is printed on both sides of each sheet of paper.
16840When you open a book, the right-hand page is odd-numbered, and
16841chapters begin on right-hand pages---a preceding left-hand page is
16842left blank if necessary. Reports, however, are often printed on just
16843one side of paper, and chapters begin on a fresh page immediately
16844following the end of the preceding chapter. In short or informal
16845reports, chapters often do not begin on a new page at all, but are
16846separated from the preceding text by a small amount of whitespace.@refill
16847
16848The @code{@@setchapternewpage} command controls whether chapters begin
16849on new pages, and whether one of the standard heading formats is used.
16850In addition, Texinfo has several heading and footing commands that you
16851can use to generate your own heading and footing formats.@refill
16852
16853In Texinfo, headings and footings are single lines at the tops and
16854bottoms of pages; you cannot create multiline headings or footings.
16855Each header or footer line is divided into three parts: a left part, a
16856middle part, and a right part. Any part, or a whole line, may be left
16857blank. Text for the left part of a header or footer line is set
16858flushleft; text for the middle part is centered; and, text for the
16859right part is set flushright.@refill
16860
16861@node Heading Format, Heading Choice, Headings Introduced, Headings
16862@comment node-name, next, previous, up
16863@section Standard Heading Formats
16864
16865Texinfo provides two standard heading formats, one for manuals printed
16866on one side of each sheet of paper, and the other for manuals printed
16867on both sides of the paper.
16868
16869By default, nothing is specified for the footing of a Texinfo file,
16870so the footing remains blank.@refill
16871
16872The standard format for single-sided printing consists of a header
16873line in which the left-hand part contains the name of the chapter, the
16874central part is blank, and the right-hand part contains the page
16875number.@refill
16876
16877@need 950
16878A single-sided page looks like this:
16879
16880@example
16881@group
16882 _______________________
16883 | |
16884 | chapter page number |
16885 | |
16886 | Start of text ... |
16887 | ... |
16888 | |
16889
16890@end group
16891@end example
16892
16893The standard format for two-sided printing depends on whether the page
16894number is even or odd. By convention, even-numbered pages are on the
16895left- and odd-numbered pages are on the right. (@TeX{} will adjust the
16896widths of the left- and right-hand margins. Usually, widths are
16897correct, but during double-sided printing, it is wise to check that
16898pages will bind properly---sometimes a printer will produce output in
16899which the even-numbered pages have a larger right-hand margin than the
16900odd-numbered pages.)@refill
16901
16902In the standard double-sided format, the left part of the left-hand
16903(even-numbered) page contains the page number, the central part is
16904blank, and the right part contains the title (specified by the
16905@code{@@settitle} command). The left part of the right-hand
16906(odd-numbered) page contains the name of the chapter, the central part
16907is blank, and the right part contains the page number.@refill
16908
16909@need 750
16910Two pages, side by side as in an open book, look like this:@refill
16911
16912@example
16913@group
16914 _______________________ _______________________
16915 | | | |
16916 | page number title | | chapter page number |
16917 | | | |
16918 | Start of text ... | | More text ... |
16919 | ... | | ... |
16920 | | | |
16921
16922@end group
16923@end example
16924
16925@noindent
16926The chapter name is preceded by the word ``Chapter'', the chapter number
16927and a colon. This makes it easier to keep track of where you are in the
16928manual.@refill
16929
16930@node Heading Choice, Custom Headings, Heading Format, Headings
16931@comment node-name, next, previous, up
16932@section Specifying the Type of Heading
16933
16934@TeX{} does not begin to generate page headings for a standard Texinfo
16935file until it reaches the @code{@@end titlepage} command. Thus, the
16936title and copyright pages are not numbered. The @code{@@end
16937titlepage} command causes @TeX{} to begin to generate page headings
16938according to a standard format specified by the
16939@code{@@setchapternewpage} command that precedes the
16940@code{@@titlepage} section.@refill
16941
16942@need 1000
16943There are four possibilities:@refill
16944
16945@table @asis
16946@item No @code{@@setchapternewpage} command
16947Cause @TeX{} to specify the single-sided heading format, with chapters
16948on new pages. This is the same as @code{@@setchapternewpage on}.@refill
16949
16950@item @code{@@setchapternewpage on}
16951Specify the single-sided heading format, with chapters on new pages.@refill
16952
16953@item @code{@@setchapternewpage off}
16954Cause @TeX{} to start a new chapter on the same page as the last page of
16955the preceding chapter, after skipping some vertical whitespace. Also
16956cause @TeX{} to typeset for single-sided printing. (You can override
16957the headers format with the @code{@@headings double} command; see
16958@ref{headings on off, , The @code{@@headings} Command}.)@refill
16959
16960@item @code{@@setchapternewpage odd}
16961Specify the double-sided heading format, with chapters on new pages.@refill
16962@end table
16963
16964@noindent
16965Texinfo lacks an @code{@@setchapternewpage even} command.@refill
16966
16967@node Custom Headings, , Heading Choice, Headings
16968@comment node-name, next, previous, up
16969@section How to Make Your Own Headings
16970
16971You can use the standard headings provided with Texinfo or specify
16972your own. By default, Texinfo has no footers, so if you specify them,
16973the available page size for the main text will be slightly reduced.
16974
16975Texinfo provides six commands for specifying headings and
16976footings:
16977@itemize @bullet
16978@item
16979@code{@@everyheading} @code{@@everyfooting} generate page headers and
16980footers that are the same for both even- and odd-numbered pages.
16981@item
16982@code{@@evenheading} and @code{@@evenfooting} command generate headers
16983and footers for even-numbered (left-hand) pages.
16984@item
16985@code{@@oddheading} and @code{@@oddfooting} generate headers and footers
16986for odd-numbered (right-hand) pages.
16987@end itemize
16988
16989Write custom heading specifications in the Texinfo file immediately
| 17016
17017@example
17018@group
17019@@node First, Second, , Top
17020@@chapter First Chapter
17021
17022Contents of first chapter @dots{}
17023@end group
17024@end example
17025
17026The full contents of @file{concept-index.texinfo} might be as simple as this:
17027
17028@example
17029@group
17030@@node Concept Index
17031@@unnumbered Concept Index
17032
17033@@printindex cp
17034@end group
17035@end example
17036
17037The outer Texinfo source file for @cite{The GNU Emacs Lisp Reference
17038Manual} is named @file{elisp.texi}. This outer file contains a master
17039menu with 417 entries and a list of 41 @code{@@include}
17040files.@refill
17041
17042
17043@node Include Files Evolution
17044@section Evolution of Include Files
17045
17046When Info was first created, it was customary to create many small
17047Info files on one subject. Each Info file was formatted from its own
17048Texinfo source file. This custom meant that Emacs did not need to
17049make a large buffer to hold the whole of a large Info file when
17050someone wanted information; instead, Emacs allocated just enough
17051memory for the small Info file that contained the particular
17052information sought. This way, Emacs could avoid wasting memory.@refill
17053
17054References from one file to another were made by referring to the file
17055name as well as the node name. (@xref{Other Info Files, , Referring to
17056Other Info Files}. Also, see @ref{Four and Five Arguments, ,
17057@code{@@xref} with Four and Five Arguments}.)@refill
17058
17059Include files were designed primarily as a way to create a single,
17060large printed manual out of several smaller Info files. In a printed
17061manual, all the references were within the same document, so @TeX{}
17062could automatically determine the references' page numbers. The Info
17063formatting commands used include files only for creating joint
17064indices; each of the individual Texinfo files had to be formatted for
17065Info individually. (Each, therefore, required its own
17066@code{@@setfilename} line.)@refill
17067
17068However, because large Info files are now split automatically, it is
17069no longer necessary to keep them small.@refill
17070
17071Nowadays, multiple Texinfo files are used mostly for large documents,
17072such as @cite{The GNU Emacs Lisp Reference Manual}, and for projects
17073in which several different people write different sections of a
17074document simultaneously.@refill
17075
17076In addition, the Info formatting commands have been extended to work
17077with the @code{@@include} command so as to create a single large Info
17078file that is split into smaller files if necessary. This means that
17079you can write menus and cross references without naming the different
17080Texinfo files.@refill
17081
17082
17083@node Headings
17084@appendix Page Headings
17085@cindex Headings
17086@cindex Footings
17087@cindex Page numbering
17088@cindex Page headings
17089@cindex Formatting headings and footings
17090
17091Most printed manuals contain headings along the top of every page
17092except the title and copyright pages. Some manuals also contain
17093footings. (Headings and footings have no meaning to Info, which is
17094not paginated.)@refill
17095
17096@menu
17097* Headings Introduced:: Conventions for using page headings.
17098* Heading Format:: Standard page heading formats.
17099* Heading Choice:: How to specify the type of page heading.
17100* Custom Headings:: How to create your own headings and footings.
17101@end menu
17102
17103@node Headings Introduced, Heading Format, Headings, Headings
17104@ifinfo
17105@heading Headings Introduced
17106@end ifinfo
17107
17108Texinfo provides standard page heading formats for manuals that are
17109printed on one side of each sheet of paper and for manuals that are
17110printed on both sides of the paper. Typically, you will use these
17111formats, but you can specify your own format if you wish.@refill
17112
17113In addition, you can specify whether chapters should begin on a new
17114page, or merely continue the same page as the previous chapter; and if
17115chapters begin on new pages, you can specify whether they must be
17116odd-numbered pages.@refill
17117
17118By convention, a book is printed on both sides of each sheet of paper.
17119When you open a book, the right-hand page is odd-numbered, and
17120chapters begin on right-hand pages---a preceding left-hand page is
17121left blank if necessary. Reports, however, are often printed on just
17122one side of paper, and chapters begin on a fresh page immediately
17123following the end of the preceding chapter. In short or informal
17124reports, chapters often do not begin on a new page at all, but are
17125separated from the preceding text by a small amount of whitespace.@refill
17126
17127The @code{@@setchapternewpage} command controls whether chapters begin
17128on new pages, and whether one of the standard heading formats is used.
17129In addition, Texinfo has several heading and footing commands that you
17130can use to generate your own heading and footing formats.@refill
17131
17132In Texinfo, headings and footings are single lines at the tops and
17133bottoms of pages; you cannot create multiline headings or footings.
17134Each header or footer line is divided into three parts: a left part, a
17135middle part, and a right part. Any part, or a whole line, may be left
17136blank. Text for the left part of a header or footer line is set
17137flushleft; text for the middle part is centered; and, text for the
17138right part is set flushright.@refill
17139
17140@node Heading Format, Heading Choice, Headings Introduced, Headings
17141@comment node-name, next, previous, up
17142@section Standard Heading Formats
17143
17144Texinfo provides two standard heading formats, one for manuals printed
17145on one side of each sheet of paper, and the other for manuals printed
17146on both sides of the paper.
17147
17148By default, nothing is specified for the footing of a Texinfo file,
17149so the footing remains blank.@refill
17150
17151The standard format for single-sided printing consists of a header
17152line in which the left-hand part contains the name of the chapter, the
17153central part is blank, and the right-hand part contains the page
17154number.@refill
17155
17156@need 950
17157A single-sided page looks like this:
17158
17159@example
17160@group
17161 _______________________
17162 | |
17163 | chapter page number |
17164 | |
17165 | Start of text ... |
17166 | ... |
17167 | |
17168
17169@end group
17170@end example
17171
17172The standard format for two-sided printing depends on whether the page
17173number is even or odd. By convention, even-numbered pages are on the
17174left- and odd-numbered pages are on the right. (@TeX{} will adjust the
17175widths of the left- and right-hand margins. Usually, widths are
17176correct, but during double-sided printing, it is wise to check that
17177pages will bind properly---sometimes a printer will produce output in
17178which the even-numbered pages have a larger right-hand margin than the
17179odd-numbered pages.)@refill
17180
17181In the standard double-sided format, the left part of the left-hand
17182(even-numbered) page contains the page number, the central part is
17183blank, and the right part contains the title (specified by the
17184@code{@@settitle} command). The left part of the right-hand
17185(odd-numbered) page contains the name of the chapter, the central part
17186is blank, and the right part contains the page number.@refill
17187
17188@need 750
17189Two pages, side by side as in an open book, look like this:@refill
17190
17191@example
17192@group
17193 _______________________ _______________________
17194 | | | |
17195 | page number title | | chapter page number |
17196 | | | |
17197 | Start of text ... | | More text ... |
17198 | ... | | ... |
17199 | | | |
17200
17201@end group
17202@end example
17203
17204@noindent
17205The chapter name is preceded by the word ``Chapter'', the chapter number
17206and a colon. This makes it easier to keep track of where you are in the
17207manual.@refill
17208
17209@node Heading Choice, Custom Headings, Heading Format, Headings
17210@comment node-name, next, previous, up
17211@section Specifying the Type of Heading
17212
17213@TeX{} does not begin to generate page headings for a standard Texinfo
17214file until it reaches the @code{@@end titlepage} command. Thus, the
17215title and copyright pages are not numbered. The @code{@@end
17216titlepage} command causes @TeX{} to begin to generate page headings
17217according to a standard format specified by the
17218@code{@@setchapternewpage} command that precedes the
17219@code{@@titlepage} section.@refill
17220
17221@need 1000
17222There are four possibilities:@refill
17223
17224@table @asis
17225@item No @code{@@setchapternewpage} command
17226Cause @TeX{} to specify the single-sided heading format, with chapters
17227on new pages. This is the same as @code{@@setchapternewpage on}.@refill
17228
17229@item @code{@@setchapternewpage on}
17230Specify the single-sided heading format, with chapters on new pages.@refill
17231
17232@item @code{@@setchapternewpage off}
17233Cause @TeX{} to start a new chapter on the same page as the last page of
17234the preceding chapter, after skipping some vertical whitespace. Also
17235cause @TeX{} to typeset for single-sided printing. (You can override
17236the headers format with the @code{@@headings double} command; see
17237@ref{headings on off, , The @code{@@headings} Command}.)@refill
17238
17239@item @code{@@setchapternewpage odd}
17240Specify the double-sided heading format, with chapters on new pages.@refill
17241@end table
17242
17243@noindent
17244Texinfo lacks an @code{@@setchapternewpage even} command.@refill
17245
17246@node Custom Headings, , Heading Choice, Headings
17247@comment node-name, next, previous, up
17248@section How to Make Your Own Headings
17249
17250You can use the standard headings provided with Texinfo or specify
17251your own. By default, Texinfo has no footers, so if you specify them,
17252the available page size for the main text will be slightly reduced.
17253
17254Texinfo provides six commands for specifying headings and
17255footings:
17256@itemize @bullet
17257@item
17258@code{@@everyheading} @code{@@everyfooting} generate page headers and
17259footers that are the same for both even- and odd-numbered pages.
17260@item
17261@code{@@evenheading} and @code{@@evenfooting} command generate headers
17262and footers for even-numbered (left-hand) pages.
17263@item
17264@code{@@oddheading} and @code{@@oddfooting} generate headers and footers
17265for odd-numbered (right-hand) pages.
17266@end itemize
17267
17268Write custom heading specifications in the Texinfo file immediately
|
16990after the @code{@@end titlepage} command. Enclose your specifications
16991between @code{@@iftex} and @code{@@end iftex} commands since the
16992@code{texinfo-format-buffer} command may not recognize them. Also,
16993you must cancel the predefined heading commands with the
| 17269after the @code{@@end titlepage} command.
17270You must cancel the predefined heading commands with the
|
16994@code{@@headings off} command before defining your own
16995specifications.@refill
16996
16997@need 1000
16998Here is how to tell @TeX{} to place the chapter name at the left, the
16999page number in the center, and the date at the right of every header
17000for both even- and odd-numbered pages:@refill
17001
17002@example
17003@group
| 17271@code{@@headings off} command before defining your own
17272specifications.@refill
17273
17274@need 1000
17275Here is how to tell @TeX{} to place the chapter name at the left, the
17276page number in the center, and the date at the right of every header
17277for both even- and odd-numbered pages:@refill
17278
17279@example
17280@group
|
17004@@iftex
| |
17005@@headings off
17006@@everyheading @@thischapter @@| @@thispage @@| @@today@{@}
| 17281@@headings off
17282@@everyheading @@thischapter @@| @@thispage @@| @@today@{@}
|
17007@@end iftex
| |
17008@end group
17009@end example
17010
17011@noindent
17012You need to divide the left part from the central part and the central
17013part from the right part by inserting @samp{@@|} between parts.
17014Otherwise, the specification command will not be able to tell where
17015the text for one part ends and the next part begins.@refill
17016
17017Each part can contain text or @@-commands. The text
17018is printed as if the part were within an ordinary paragraph in the
17019body of the page. The @@-commands replace
17020themselves with the page number, date, chapter name, or
17021whatever.@refill
17022
17023@need 950
17024Here are the six heading and footing commands:@refill
17025
17026@findex everyheading
17027@findex everyfooting
17028@table @code
17029@item @@everyheading @var{left} @@| @var{center} @@| @var{right}
17030@itemx @@everyfooting @var{left} @@| @var{center} @@| @var{right}
17031
17032The `every' commands specify the format for both even- and odd-numbered
17033pages. These commands are for documents that are printed on one side
17034of each sheet of paper, or for documents in which you want symmetrical
17035headers or footers.@refill
17036
17037@findex evenheading
17038@findex evenfooting
17039@findex oddheading
17040@findex oddfooting
17041@item @@evenheading @var{left} @@| @var{center} @@| @var{right}
17042@itemx @@oddheading @var{left} @@| @var{center} @@| @var{right}
17043
17044@itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right}
17045@itemx @@oddfooting @var{left} @@| @var{center} @@| @var{right}
17046
17047The `even' and `odd' commands specify the format for even-numbered
17048pages and odd-numbered pages. These commands are for books and
17049manuals that are printed on both sides of each sheet of paper.
17050@end table
17051
17052Use the @samp{@@this@dots{}} series of @@-commands to
17053provide the names of chapters
17054and sections and the page number. You can use the
17055@samp{@@this@dots{}} commands in the left, center, or right portions
17056of headers and footers, or anywhere else in a Texinfo file so long as
17057they are between @code{@@iftex} and @code{@@end iftex} commands.@refill
17058
17059@need 1000
17060Here are the @samp{@@this@dots{}} commands:@refill
17061
17062@table @code
17063@findex thispage
17064@item @@thispage
17065Expands to the current page number.@refill
17066@c !!! Karl Berry says that `thissection' can fail on page breaks.
17067@ignore
17068@item @@thissection
17069Expands to the name of the current section.@refill
17070@end ignore
17071
17072@findex thischaptername
17073@item @@thischaptername
17074Expands to the name of the current chapter.@refill
17075
17076@findex thischapter
17077@item @@thischapter
17078Expands to the number and name of the current
17079chapter, in the format `Chapter 1: Title'.@refill
17080
17081@findex thistitle
17082@item @@thistitle
17083Expands to the name of the document, as specified by the
17084@code{@@settitle} command.@refill
17085
17086@findex thisfile
17087@item @@thisfile
17088For @code{@@include} files only: expands to the name of the current
17089@code{@@include} file. If the current Texinfo source file is not an
17090@code{@@include} file, this command has no effect. This command does
17091@emph{not} provide the name of the current Texinfo source file unless
17092it is an @code{@@include} file. (@xref{Include Files}, for more
17093information about @code{@@include} files.)@refill
17094@end table
17095
17096@noindent
17097You can also use the @code{@@today@{@}} command, which expands to the
17098current date, in `1 Jan 1900' format.@refill
17099@findex today
17100
17101Other @@-commands and text are printed in a header or footer just as
17102if they were in the body of a page. It is useful to incorporate text,
17103particularly when you are writing drafts:@refill
17104
17105@example
17106@group
| 17283@end group
17284@end example
17285
17286@noindent
17287You need to divide the left part from the central part and the central
17288part from the right part by inserting @samp{@@|} between parts.
17289Otherwise, the specification command will not be able to tell where
17290the text for one part ends and the next part begins.@refill
17291
17292Each part can contain text or @@-commands. The text
17293is printed as if the part were within an ordinary paragraph in the
17294body of the page. The @@-commands replace
17295themselves with the page number, date, chapter name, or
17296whatever.@refill
17297
17298@need 950
17299Here are the six heading and footing commands:@refill
17300
17301@findex everyheading
17302@findex everyfooting
17303@table @code
17304@item @@everyheading @var{left} @@| @var{center} @@| @var{right}
17305@itemx @@everyfooting @var{left} @@| @var{center} @@| @var{right}
17306
17307The `every' commands specify the format for both even- and odd-numbered
17308pages. These commands are for documents that are printed on one side
17309of each sheet of paper, or for documents in which you want symmetrical
17310headers or footers.@refill
17311
17312@findex evenheading
17313@findex evenfooting
17314@findex oddheading
17315@findex oddfooting
17316@item @@evenheading @var{left} @@| @var{center} @@| @var{right}
17317@itemx @@oddheading @var{left} @@| @var{center} @@| @var{right}
17318
17319@itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right}
17320@itemx @@oddfooting @var{left} @@| @var{center} @@| @var{right}
17321
17322The `even' and `odd' commands specify the format for even-numbered
17323pages and odd-numbered pages. These commands are for books and
17324manuals that are printed on both sides of each sheet of paper.
17325@end table
17326
17327Use the @samp{@@this@dots{}} series of @@-commands to
17328provide the names of chapters
17329and sections and the page number. You can use the
17330@samp{@@this@dots{}} commands in the left, center, or right portions
17331of headers and footers, or anywhere else in a Texinfo file so long as
17332they are between @code{@@iftex} and @code{@@end iftex} commands.@refill
17333
17334@need 1000
17335Here are the @samp{@@this@dots{}} commands:@refill
17336
17337@table @code
17338@findex thispage
17339@item @@thispage
17340Expands to the current page number.@refill
17341@c !!! Karl Berry says that `thissection' can fail on page breaks.
17342@ignore
17343@item @@thissection
17344Expands to the name of the current section.@refill
17345@end ignore
17346
17347@findex thischaptername
17348@item @@thischaptername
17349Expands to the name of the current chapter.@refill
17350
17351@findex thischapter
17352@item @@thischapter
17353Expands to the number and name of the current
17354chapter, in the format `Chapter 1: Title'.@refill
17355
17356@findex thistitle
17357@item @@thistitle
17358Expands to the name of the document, as specified by the
17359@code{@@settitle} command.@refill
17360
17361@findex thisfile
17362@item @@thisfile
17363For @code{@@include} files only: expands to the name of the current
17364@code{@@include} file. If the current Texinfo source file is not an
17365@code{@@include} file, this command has no effect. This command does
17366@emph{not} provide the name of the current Texinfo source file unless
17367it is an @code{@@include} file. (@xref{Include Files}, for more
17368information about @code{@@include} files.)@refill
17369@end table
17370
17371@noindent
17372You can also use the @code{@@today@{@}} command, which expands to the
17373current date, in `1 Jan 1900' format.@refill
17374@findex today
17375
17376Other @@-commands and text are printed in a header or footer just as
17377if they were in the body of a page. It is useful to incorporate text,
17378particularly when you are writing drafts:@refill
17379
17380@example
17381@group
|
17107@@iftex
| |
17108@@headings off
17109@@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter
17110@@everyfooting @@| @@| Version: 0.27: @@today@{@}
| 17382@@headings off
17383@@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter
17384@@everyfooting @@| @@| Version: 0.27: @@today@{@}
|
17111@@end iftex
| |
17112@end group
17113@end example
17114
17115Beware of overlong titles: they may overlap another part of the
17116header or footer and blot it out.@refill
17117
17118
17119@node Catching Mistakes
17120@appendix Formatting Mistakes
17121@cindex Structure, catching mistakes in
17122@cindex Nodes, catching mistakes
17123@cindex Catching mistakes
17124@cindex Correcting mistakes
17125@cindex Mistakes, catching
17126@cindex Problems, catching
17127@cindex Debugging the Texinfo structure
17128
| 17385@end group
17386@end example
17387
17388Beware of overlong titles: they may overlap another part of the
17389header or footer and blot it out.@refill
17390
17391
17392@node Catching Mistakes
17393@appendix Formatting Mistakes
17394@cindex Structure, catching mistakes in
17395@cindex Nodes, catching mistakes
17396@cindex Catching mistakes
17397@cindex Correcting mistakes
17398@cindex Mistakes, catching
17399@cindex Problems, catching
17400@cindex Debugging the Texinfo structure
17401
|
17129Besides mistakes in the content of your documentation, there
17130are two kinds of mistake you can make with Texinfo: you can make mistakes
17131with @@-commands, and you can make mistakes with the structure of the
17132nodes and chapters.@refill
| 17402Besides mistakes in the content of your documentation, there are two
17403kinds of mistake you can make with Texinfo: you can make mistakes with
17404@@-commands, and you can make mistakes with the structure of the nodes
17405and chapters.
|
17133
17134Emacs has two tools for catching the @@-command mistakes and two for
17135catching structuring mistakes.@refill
17136
17137For finding problems with @@-commands, you can run @TeX{} or a region
17138formatting command on the region that has a problem; indeed, you can
17139run these commands on each region as you write it.@refill
17140
17141For finding problems with the structure of nodes and chapters, you can use
17142@kbd{C-c C-s} (@code{texinfo-show-structure}) and the related @code{occur}
17143command and you can use the @kbd{M-x Info-validate} command.@refill
17144
17145@menu
17146* makeinfo Preferred:: @code{makeinfo} finds errors.
17147* Debugging with Info:: How to catch errors with Info formatting.
17148* Debugging with TeX:: How to catch errors with @TeX{} formatting.
17149* Using texinfo-show-structure:: How to use @code{texinfo-show-structure}.
17150* Using occur:: How to list all lines containing a pattern.
17151* Running Info-Validate:: How to find badly referenced nodes.
17152@end menu
17153
17154@node makeinfo Preferred, Debugging with Info, Catching Mistakes, Catching Mistakes
17155@ifinfo
17156@heading @code{makeinfo} Find Errors
17157@end ifinfo
17158
17159The @code{makeinfo} program does an excellent job of catching errors
17160and reporting them---far better than @code{texinfo-format-region} or
17161@code{texinfo-format-buffer}. In addition, the various functions for
17162automatically creating and updating node pointers and menus remove
17163many opportunities for human error.@refill
17164
17165If you can, use the updating commands to create and insert pointers
17166and menus. These prevent many errors. Then use @code{makeinfo} (or
17167its Texinfo mode manifestations, @code{makeinfo-region} and
17168@code{makeinfo-buffer}) to format your file and check for other
17169errors. This is the best way to work with Texinfo. But if you
17170cannot use @code{makeinfo}, or your problem is very puzzling, then you
17171may want to use the tools described in this appendix.@refill
17172
17173@node Debugging with Info, Debugging with TeX, makeinfo Preferred, Catching Mistakes
17174@comment node-name, next, previous, up
17175@section Catching Errors with Info Formatting
17176@cindex Catching errors with Info formatting
17177@cindex Debugging with Info formatting
17178
17179After you have written part of a Texinfo file, you can use the
17180@code{texinfo-format-region} or the @code{makeinfo-region} command to
17181see whether the region formats properly.@refill
17182
17183Most likely, however, you are reading this section because for some
17184reason you cannot use the @code{makeinfo-region} command; therefore, the
17185rest of this section presumes that you are using
17186@code{texinfo-format-region}.@refill
17187
17188If you have made a mistake with an @@-command,
17189@code{texinfo-format-region} will stop processing at or after the
17190error and display an error message. To see where in the buffer the
17191error occurred, switch to the @samp{*Info Region*} buffer; the cursor
17192will be in a position that is after the location of the error. Also,
17193the text will not be formatted after the place where the error
17194occurred (or more precisely, where it was detected).@refill
17195
17196For example, if you accidentally end a menu with the command @code{@@end
17197menus} with an `s' on the end, instead of with @code{@@end menu}, you
17198will see an error message that says:@refill
17199
17200@example
17201@@end menus is not handled by texinfo
17202@end example
17203
17204@noindent
17205The cursor will stop at the point in the buffer where the error
17206occurs, or not long after it. The buffer will look like this:@refill
17207
17208@example
17209@group
17210---------- Buffer: *Info Region* ----------
17211* Menu:
17212
17213* Using texinfo-show-structure:: How to use
17214 `texinfo-show-structure'
17215 to catch mistakes.
17216* Running Info-Validate:: How to check for
17217 unreferenced nodes.
17218@@end menus
17219@point{}
17220---------- Buffer: *Info Region* ----------
17221@end group
17222@end example
17223
17224The @code{texinfo-format-region} command sometimes provides slightly
17225odd error messages. For example, the following cross reference fails to format:@refill
17226
17227@example
17228(@@xref@{Catching Mistakes, for more info.)
17229@end example
17230
17231@noindent
17232In this case, @code{texinfo-format-region} detects the missing closing
17233brace but displays a message that says @samp{Unbalanced parentheses}
17234rather than @samp{Unbalanced braces}. This is because the formatting
17235command looks for mismatches between braces as if they were
17236parentheses.@refill
17237
17238Sometimes @code{texinfo-format-region} fails to detect mistakes. For
17239example, in the following, the closing brace is swapped with the
17240closing parenthesis:@refill
17241
17242@example
17243(@@xref@{Catching Mistakes), for more info.@}
17244@end example
17245
17246@noindent
17247Formatting produces:
17248@example
17249(*Note for more info.: Catching Mistakes)
17250@end example
17251
17252The only way for you to detect this error is to realize that the
17253reference should have looked like this:@refill
17254
17255@example
17256(*Note Catching Mistakes::, for more info.)
17257@end example
17258
17259Incidentally, if you are reading this node in Info and type @kbd{f
17260@key{RET}} (@code{Info-follow-reference}), you will generate an error
17261message that says:
17262
17263@example
17264No such node: "Catching Mistakes) The only way @dots{}
17265@end example
17266
17267@noindent
17268This is because Info perceives the example of the error as the first
17269cross reference in this node and if you type a @key{RET} immediately
17270after typing the Info @kbd{f} command, Info will attempt to go to the
17271referenced node. If you type @kbd{f catch @key{TAB} @key{RET}}, Info
17272will complete the node name of the correctly written example and take
17273you to the `Catching Mistakes' node. (If you try this, you can return
17274from the `Catching Mistakes' node by typing @kbd{l}
17275(@code{Info-last}).)
17276
17277@c !!! section on using Elisp debugger ignored.
17278@ignore
17279Sometimes @code{texinfo-format-region} will stop long after the
17280original error; this is because it does not discover the problem until
17281then. In this case, you will need to backtrack.@refill
17282
17283@c menu
17284@c * Using the Emacs Lisp Debugger:: How to use the Emacs Lisp debugger.
17285@c end menu
17286
17287@c node Using the Emacs Lisp Debugger
17288@c appendixsubsec Using the Emacs Lisp Debugger
17289@c index Using the Emacs Lisp debugger
17290@c index Emacs Lisp debugger
17291@c index Debugger, using the Emacs Lisp
17292
17293If an error is especially elusive, you can turn on the Emacs Lisp
17294debugger and look at the backtrace; this tells you where in the
17295@code{texinfo-format-region} function the problem occurred. You can
17296turn on the debugger with the command:@refill
17297
17298@example
17299M-x set-variable @key{RET} debug-on-error @key{RET} t @key{RET}
17300@end example
17301
17302@noindent
17303and turn it off with
17304
17305@example
17306M-x set-variable @key{RET} debug-on-error @key{RET} nil @key{RET}
17307@end example
17308
17309Often, when you are using the debugger, it is easier to follow what is
17310going on if you use the Emacs Lisp files that are not byte-compiled.
17311The byte-compiled sources send octal numbers to the debugger that may
17312look mysterious. To use the uncompiled source files, load
17313@file{texinfmt.el} and @file{texinfo.el} with the @kbd{M-x load-file}
17314command.@refill
17315
17316The debugger will not catch an error if @code{texinfo-format-region}
17317does not detect one. In the example shown above,
17318@code{texinfo-format-region} did not find the error when the whole
17319list was formatted, but only when part of the list was formatted.
17320When @code{texinfo-format-region} did not find an error, the debugger
17321did not find one either. @refill
17322
17323However, when @code{texinfo-format-region} did report an error, it
17324invoked the debugger. This is the backtrace it produced:@refill
17325
17326@example
17327---------- Buffer: *Backtrace* ----------
17328Signalling: (search-failed "[@},]")
17329 re-search-forward("[@},]")
17330 (while ...)
17331 (let ...)
17332 texinfo-format-parse-args()
17333 (let ...)
17334 texinfo-format-xref()
17335 funcall(texinfo-format-xref)
17336 (if ...)
17337 (let ...)
17338 (if ...)
17339 (while ...)
17340 texinfo-format-scan()
17341 (save-excursion ...)
17342 (let ...)
17343 texinfo-format-region(103370 103631)
17344* call-interactively(texinfo-format-region)
17345---------- Buffer: *Backtrace* ----------
17346@end example
17347
17348The backtrace is read from the bottom up.
17349@code{texinfo-format-region} was called interactively; and it, in
17350turn, called various functions, including @code{texinfo-format-scan},
17351@code{texinfo-format-xref} and @code{texinfo-format-parse-args}.
17352Inside the function @code{texinfo-format-parse-args}, the function
17353@code{re-search-forward} was called; it was this function that could
17354not find the missing right-hand brace.@refill
17355
17356@xref{Lisp Debug, , Debugging Emacs Lisp, emacs, The GNU Emacs
17357Manual}, for more information.@refill
17358@end ignore
17359
17360@node Debugging with TeX, Using texinfo-show-structure, Debugging with Info, Catching Mistakes
17361@comment node-name, next, previous, up
17362@section Catching Errors with @TeX{} Formatting
17363@cindex Catching errors with @TeX{} formatting
17364@cindex Debugging with @TeX{} formatting
17365
17366You can also catch mistakes when you format a file with @TeX{}.@refill
17367
17368Usually, you will want to do this after you have run
17369@code{texinfo-format-buffer} (or, better, @code{makeinfo-buffer}) on
17370the same file, because @code{texinfo-format-buffer} sometimes displays
17371error messages that make more sense than @TeX{}. (@xref{Debugging
17372with Info}, for more information.)@refill
17373
17374For example, @TeX{} was run on a Texinfo file, part of which is shown
17375here:@refill
17376
17377@example
17378---------- Buffer: texinfo.texi ----------
17379name of the Texinfo file as an extension. The
17380@@samp@{??@} are `wildcards' that cause the shell to
17381substitute all the raw index files. (@@xref@{sorting
17382indices, for more information about sorting
17383indices.)@@refill
17384---------- Buffer: texinfo.texi ----------
17385@end example
17386
17387@noindent
17388(The cross reference lacks a closing brace.)
17389@TeX{} produced the following output, after which it stopped:@refill
17390
17391@example
17392---------- Buffer: *tex-shell* ----------
17393Runaway argument?
17394@{sorting indices, for more information about sorting
17395indices.) @@refill @@ETC.
17396! Paragraph ended before @@xref was complete.
17397<to be read again>
17398 @@par
17399l.27
17400
17401?
17402---------- Buffer: *tex-shell* ----------
17403@end example
17404
17405In this case, @TeX{} produced an accurate and
17406understandable error message:
17407
17408@example
17409Paragraph ended before @@xref was complete.
17410@end example
17411
17412@noindent
17413@samp{@@par} is an internal @TeX{} command of no relevance to Texinfo.
17414@samp{l.27} means that @TeX{} detected the problem on line 27 of the
17415Texinfo file. The @samp{?} is the prompt @TeX{} uses in this
17416circumstance.@refill
17417
17418Unfortunately, @TeX{} is not always so helpful, and sometimes you must
17419truly be a Sherlock Holmes to discover what went wrong.@refill
17420
17421In any case, if you run into a problem like this, you can do one of three
17422things.@refill
17423
17424@enumerate
17425@item
17426You can tell @TeX{} to continue running and ignore just this error by
17427typing @key{RET} at the @samp{?} prompt.@refill
17428
17429@item
17430You can tell @TeX{} to continue running and to ignore all errors as best
17431it can by typing @kbd{r @key{RET}} at the @samp{?} prompt.@refill
17432
17433This is often the best thing to do. However, beware: the one error
17434may produce a cascade of additional error messages as its consequences
17435are felt through the rest of the file. To stop @TeX{} when it is
17436producing such an avalanche of error messages, type @kbd{C-c} (or
17437@kbd{C-c C-c}, if you are running a shell inside Emacs).
17438
17439@item
17440You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}}
17441at the @samp{?} prompt.@refill
17442@end enumerate
17443
17444If you are running @TeX{} inside Emacs, you need to switch to the shell
17445buffer and line at which @TeX{} offers the @samp{?} prompt.
17446
17447Sometimes @TeX{} will format a file without producing error messages even
17448though there is a problem. This usually occurs if a command is not ended
17449but @TeX{} is able to continue processing anyhow. For example, if you fail
17450to end an itemized list with the @code{@@end itemize} command, @TeX{} will
17451write a DVI file that you can print out. The only error message that
17452@TeX{} will give you is the somewhat mysterious comment that@refill
17453
17454@example
17455(@@end occurred inside a group at level 1)
17456@end example
17457
17458@noindent
17459However, if you print the DVI file, you will find that the text
17460of the file that follows the itemized list is entirely indented as if
17461it were part of the last item in the itemized list. The error message
17462is the way @TeX{} says that it expected to find an @code{@@end}
17463command somewhere in the file; but that it could not determine where
17464it was needed.@refill
17465
17466Another source of notoriously hard-to-find errors is a missing
17467@code{@@end group} command. If you ever are stumped by
17468incomprehensible errors, look for a missing @code{@@end group} command
17469first.@refill
17470
17471If the Texinfo file lacks header lines,
17472@TeX{} may stop in the
17473beginning of its run and display output that looks like the following.
17474The @samp{*} indicates that @TeX{} is waiting for input.@refill
17475
17476@example
17477This is TeX, Version 3.14159 (Web2c 7.0)
17478(test.texinfo [1])
17479*
17480@end example
17481
17482@noindent
17483In this case, simply type @kbd{\end @key{RET}} after the asterisk. Then
17484write the header lines in the Texinfo file and run the @TeX{} command
17485again. (Note the use of the backslash, @samp{\}. @TeX{} uses @samp{\}
17486instead of @samp{@@}; and in this circumstance, you are working
17487directly with @TeX{}, not with Texinfo.)@refill
17488
17489@node Using texinfo-show-structure, Using occur, Debugging with TeX, Catching Mistakes
17490@comment node-name, next, previous, up
17491@section Using @code{texinfo-show-structure}
17492@cindex Showing the structure of a file
17493@findex texinfo-show-structure
17494
17495It is not always easy to keep track of the nodes, chapters, sections, and
17496subsections of a Texinfo file. This is especially true if you are revising
17497or adding to a Texinfo file that someone else has written.@refill
17498
17499In GNU Emacs, in Texinfo mode, the @code{texinfo-show-structure}
17500command lists all the lines that begin with the @@-commands that
17501specify the structure: @code{@@chapter}, @code{@@section},
17502@code{@@appendix}, and so on. With an argument (@w{@kbd{C-u}}
17503as prefix argument, if interactive),
17504the command also shows the @code{@@node} lines. The
17505@code{texinfo-show-structure} command is bound to @kbd{C-c C-s} in
17506Texinfo mode, by default.@refill
17507
17508The lines are displayed in a buffer called the @samp{*Occur*} buffer,
17509indented by hierarchical level. For example, here is a part of what was
17510produced by running @code{texinfo-show-structure} on this manual:@refill
17511
17512@example
17513@group
17514 Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\|
17515 unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
17516 in buffer texinfo.texi.
17517 @dots{}
17518 4177:@@chapter Nodes
17519 4198: @@heading Two Paths
17520 4231: @@section Node and Menu Illustration
17521 4337: @@section The @@code@{@@@@node@} Command
17522 4393: @@subheading Choosing Node and Pointer Names
17523 4417: @@subsection How to Write an @@code@{@@@@node@} Line
17524 4469: @@subsection @@code@{@@@@node@} Line Tips
17525 @dots{}
17526@end group
17527@end example
17528
17529This says that lines 4337, 4393, and 4417 of @file{texinfo.texi} begin
17530with the @code{@@section}, @code{@@subheading}, and @code{@@subsection}
17531commands respectively. If you move your cursor into the @samp{*Occur*}
17532window, you can position the cursor over one of the lines and use the
17533@kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to
17534the corresponding spot in the Texinfo file. @xref{Other Repeating
17535Search, , Using Occur, emacs, The GNU Emacs Manual}, for more
17536information about @code{occur-mode-goto-occurrence}.@refill
17537
17538The first line in the @samp{*Occur*} window describes the @dfn{regular
17539expression} specified by @var{texinfo-heading-pattern}. This regular
17540expression is the pattern that @code{texinfo-show-structure} looks for.
17541@xref{Regexps, , Using Regular Expressions, emacs, The GNU Emacs Manual},
17542for more information.@refill
17543
17544When you invoke the @code{texinfo-show-structure} command, Emacs will
17545display the structure of the whole buffer. If you want to see the
17546structure of just a part of the buffer, of one chapter, for example,
17547use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the
17548region. (@xref{Narrowing, , , emacs, The GNU Emacs Manual}.) This is
17549how the example used above was generated. (To see the whole buffer
17550again, use @kbd{C-x n w} (@code{widen}).)@refill
17551
17552If you call @code{texinfo-show-structure} with a prefix argument by
17553typing @w{@kbd{C-u C-c C-s}}, it will list lines beginning with
17554@code{@@node} as well as the lines beginning with the @@-sign commands
17555for @code{@@chapter}, @code{@@section}, and the like.@refill
17556
17557You can remind yourself of the structure of a Texinfo file by looking at
17558the list in the @samp{*Occur*} window; and if you have mis-named a node
17559or left out a section, you can correct the mistake.@refill
17560
17561@node Using occur, Running Info-Validate, Using texinfo-show-structure, Catching Mistakes
17562@comment node-name, next, previous, up
17563@section Using @code{occur}
17564@cindex Occurrences, listing with @code{@@occur}
17565@findex occur
17566
17567Sometimes the @code{texinfo-show-structure} command produces too much
17568information. Perhaps you want to remind yourself of the overall structure
17569of a Texinfo file, and are overwhelmed by the detailed list produced by
17570@code{texinfo-show-structure}. In this case, you can use the @code{occur}
17571command directly. To do this, type@refill
17572
17573@example
17574@kbd{M-x occur}
17575@end example
17576
17577@noindent
17578and then, when prompted, type a @dfn{regexp}, a regular expression for
17579the pattern you want to match. (@xref{Regexps, , Regular Expressions,
17580emacs, The GNU Emacs Manual}.) The @code{occur} command works from
17581the current location of the cursor in the buffer to the end of the
17582buffer. If you want to run @code{occur} on the whole buffer, place
17583the cursor at the beginning of the buffer.@refill
17584
17585For example, to see all the lines that contain the word
17586@samp{@@chapter} in them, just type @samp{@@chapter}. This will
17587produce a list of the chapters. It will also list all the sentences
17588with @samp{@@chapter} in the middle of the line.@refill
17589
17590If you want to see only those lines that start with the word
17591@samp{@@chapter}, type @samp{^@@chapter} when prompted by
17592@code{occur}. If you want to see all the lines that end with a word
17593or phrase, end the last word with a @samp{$}; for example,
17594@samp{catching mistakes$}. This can be helpful when you want to see
17595all the nodes that are part of the same chapter or section and
17596therefore have the same `Up' pointer.@refill
17597
17598@xref{Other Repeating Search, , Using Occur, emacs , The GNU Emacs Manual},
17599for more information.@refill
17600
17601@node Running Info-Validate, , Using occur, Catching Mistakes
17602@comment node-name, next, previous, up
17603@section Finding Badly Referenced Nodes
17604@findex Info-validate
17605@cindex Nodes, checking for badly referenced
17606@cindex Checking for badly referenced nodes
17607@cindex Looking for badly referenced nodes
17608@cindex Finding badly referenced nodes
17609@cindex Badly referenced nodes
17610
17611You can use the @code{Info-validate} command to check whether any of
17612the `Next', `Previous', `Up' or other node pointers fail to point to a
17613node. This command checks that every node pointer points to an
17614existing node. The @code{Info-validate} command works only on Info
17615files, not on Texinfo files.@refill
17616
17617The @code{makeinfo} program validates pointers automatically, so you
17618do not need to use the @code{Info-validate} command if you are using
17619@code{makeinfo}. You only may need to use @code{Info-validate} if you
17620are unable to run @code{makeinfo} and instead must create an Info file
17621using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or
17622if you write an Info file from scratch.@refill
17623
17624@menu
17625* Using Info-validate:: How to run @code{Info-validate}.
17626* Unsplit:: How to create an unsplit file.
17627* Tagifying:: How to tagify a file.
17628* Splitting:: How to split a file manually.
17629@end menu
17630
17631@node Using Info-validate, Unsplit, Running Info-Validate, Running Info-Validate
17632@subsection Running @code{Info-validate}
17633@cindex Running @code{Info-validate}
17634@cindex Info validating a large file
17635@cindex Validating a large file
17636
17637To use @code{Info-validate}, visit the Info file you wish to check and
17638type:@refill
17639
17640@example
17641M-x Info-validate
17642@end example
17643
17644@noindent
17645Note that the @code{Info-validate} command requires an upper case
17646`I'. You may also need to create a tag table before running
17647@code{Info-validate}. @xref{Tagifying}.
17648
17649If your file is valid, you will receive a message that says ``File appears
17650valid''. However, if you have a pointer that does not point to a node,
17651error messages will be displayed in a buffer called @samp{*problems in
17652info file*}.@refill
17653
17654For example, @code{Info-validate} was run on a test file that contained
17655only the first node of this manual. One of the messages said:@refill
17656
17657@example
17658In node "Overview", invalid Next: Texinfo Mode
17659@end example
17660
17661@noindent
17662This meant that the node called @samp{Overview} had a `Next' pointer that
17663did not point to anything (which was true in this case, since the test file
17664had only one node in it).@refill
17665
17666Now suppose we add a node named @samp{Texinfo Mode} to our test case
17667but we do not specify a `Previous' for this node. Then we will get
17668the following error message:@refill
17669
17670@example
17671In node "Texinfo Mode", should have Previous: Overview
17672@end example
17673
17674@noindent
17675This is because every `Next' pointer should be matched by a
17676`Previous' (in the node where the `Next' points) which points back.@refill
17677
17678@code{Info-validate} also checks that all menu entries and cross references
17679point to actual nodes.@refill
17680
17681@code{Info-validate} requires a tag table and does not work with files
17682that have been split. (The @code{texinfo-format-buffer} command
17683automatically splits large files.) In order to use @code{Info-validate}
17684on a large file, you must run @code{texinfo-format-buffer} with an
17685argument so that it does not split the Info file; and you must create a
17686tag table for the unsplit file.
17687
17688@node Unsplit, Tagifying, Using Info-validate, Running Info-Validate
17689@comment node-name, next, previous, up
17690@subsection Creating an Unsplit File
17691@cindex Creating an unsplit file
17692@cindex Unsplit file creation
17693
17694You can run @code{Info-validate} only on a single Info file that has a
17695tag table. The command will not work on the indirect subfiles that
17696are generated when a master file is split. If you have a large file
17697(longer than 70,000 bytes or so), you need to run the
17698@code{texinfo-format-buffer} or @code{makeinfo-buffer} command in such
17699a way that it does not create indirect subfiles. You will also need
17700to create a tag table for the Info file. After you have done this,
17701you can run @code{Info-validate} and look for badly referenced
17702nodes.@refill
17703
17704The first step is to create an unsplit Info file. To prevent
17705@code{texinfo-format-buffer} from splitting a Texinfo file into
17706smaller Info files, give a prefix to the @kbd{M-x
17707texinfo-format-buffer} command:@refill
17708
17709@example
17710C-u M-x texinfo-format-buffer
17711@end example
17712
17713@noindent
17714or else
17715
17716@example
17717C-u C-c C-e C-b
17718@end example
17719
17720@noindent
17721When you do this, Texinfo will not split the file and will not create
17722a tag table for it. @refill
17723@cindex Making a tag table manually
17724@cindex Tag table, making manually
17725
17726@node Tagifying, Splitting, Unsplit, Running Info-Validate
17727@subsection Tagifying a File
17728
17729After creating an unsplit Info file, you must create a tag table for
17730it. Visit the Info file you wish to tagify and type:@refill
17731
17732@example
17733M-x Info-tagify
17734@end example
17735
17736@noindent
17737(Note the upper case @samp{I} in @code{Info-tagify}.) This creates an
17738Info file with a tag table that you can validate.@refill
17739
17740The third step is to validate the Info file:@refill
17741
17742@example
17743M-x Info-validate
17744@end example
17745
17746@noindent
17747(Note the upper case @samp{I} in @code{Info-validate}.)
17748In brief, the steps are:@refill
17749
17750@example
17751@group
17752C-u M-x texinfo-format-buffer
17753M-x Info-tagify
17754M-x Info-validate
17755@end group
17756@end example
17757
17758After you have validated the node structure, you can rerun
17759@code{texinfo-format-buffer} in the normal way so it will construct a
17760tag table and split the file automatically, or you can make the tag
17761table and split the file manually.@refill
17762
17763@node Splitting, , Tagifying, Running Info-Validate
17764@comment node-name, next, previous, up
17765@subsection Splitting a File Manually
17766@cindex Splitting an Info file manually
17767@cindex Info file, splitting manually
17768
17769You should split a large file or else let the
17770@code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it
17771for you automatically. (Generally you will let one of the formatting
17772commands do this job for you. @xref{Creating an Info File}.)@refill
17773
17774The split-off files are called the indirect subfiles.@refill
17775
17776Info files are split to save memory. With smaller files, Emacs does not
17777have make such a large buffer to hold the information.@refill
17778
17779If an Info file has more than 30 nodes, you should also make a tag
17780table for it. @xref{Using Info-validate}, for information
17781about creating a tag table. (Again, tag tables are usually created
17782automatically by the formatting command; you only need to create a tag
17783table yourself if you are doing the job manually. Most likely, you
17784will do this for a large, unsplit file on which you have run
17785@code{Info-validate}.)@refill
17786
17787@c Info-split is autoloaded in `loaddefs.el' in Emacs 18.51
17788@ignore
17789Before running @code{Info-split}, you need to load the @code{info} library
17790into Emacs by giving the command @kbd{M-x load-library @key{RET} info
17791@key{RET}}.
17792@end ignore
17793
17794Visit the Info file you wish to tagify and split and type the two
17795commands:@refill
17796
17797@example
17798M-x Info-tagify
17799M-x Info-split
17800@end example
17801
17802@noindent
17803(Note that the @samp{I} in @samp{Info} is upper case.)@refill
17804
17805When you use the @code{Info-split} command, the buffer is modified into a
17806(small) Info file which lists the indirect subfiles. This file should be
17807saved in place of the original visited file. The indirect subfiles are
17808written in the same directory the original file is in, with names generated
17809by appending @samp{-} and a number to the original file name.@refill
17810
17811The primary file still functions as an Info file, but it contains just
17812the tag table and a directory of subfiles.@refill
17813
17814
17815@node Refilling Paragraphs
17816@appendix Refilling Paragraphs
17817@cindex Refilling paragraphs
17818@cindex Filling paragraphs
17819@cindex Paragraphs, filling
17820@findex refill
17821
17822The @code{@@refill} command refills and, optionally, indents the first
17823line of a paragraph.@footnote{Perhaps the command should have been
17824called the @code{@@refillandindent} command, but @code{@@refill} is
17825shorter and the name was chosen before indenting was possible.} The
17826@code{@@refill} command is no longer important, but we describe it here
17827because you once needed it. You will see it in many old Texinfo
17828files.@refill
17829
17830Without refilling, paragraphs containing long @@-constructs may look
17831bad after formatting because the formatter removes @@-commands and
17832shortens some lines more than others. In the past, neither the
17833@code{texinfo-format-region} command nor the
17834@code{texinfo-format-buffer} command refilled paragraphs
17835automatically. The @code{@@refill} command had to be written at the
17836end of every paragraph to cause these formatters to fill them. (Both
17837@TeX{} and @code{makeinfo} have always refilled paragraphs
17838automatically.) Now, all the Info formatters automatically fill and
17839indent those paragraphs that need to be filled and indented.@refill
17840
17841The @code{@@refill} command causes @code{texinfo-format-region} and
17842@code{texinfo-format-buffer} to refill a paragraph in the Info file
17843@emph{after} all the other processing has been done. For this reason,
17844you can not use @code{@@refill} with a paragraph containing either
17845@code{@@*} or @code{@@w@{ @dots{} @}} since the refilling action will
17846override those two commands.@refill
17847
17848The @code{texinfo-format-region} and @code{texinfo-format-buffer}
17849commands now automatically append @code{@@refill} to the end of each
17850paragraph that should be filled. They do not append @code{@@refill} to
17851the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}}
17852and therefore do not refill or indent them.@refill
17853
17854
17855@node Command Syntax
17856@appendix @@-Command Syntax
17857@cindex @@-command syntax
17858@cindex Syntax, of @@-commands
17859@cindex Command syntax
17860
17861The character @samp{@@} is used to start special Texinfo commands.
17862(It has the same meaning that @samp{\} has in plain @TeX{}.) Texinfo
17863has four types of @@-command:@refill
17864
17865@table @asis
17866@item 1. Non-alphabetic commands.
17867These commands consist of an @@ followed by a punctuation mark or other
17868character that is not part of the alphabet. Non-alphabetic commands are
17869almost always part of the text within a paragraph, and never take any
17870argument. The two characters (@@ and the other one) are complete in
17871themselves; none is followed by braces. The non-alphabetic commands
17872are: @code{@@.}, @code{@@:}, @code{@@*}, @code{@@@kbd{SPACE}},
17873@code{@@@kbd{TAB}}, @code{@@@kbd{NL}}, @code{@@@@}, @code{@@@{}, and
17874@code{@@@}}.@refill
17875
17876@item 2. Alphabetic commands that do not require arguments.
17877These commands start with @@ followed by a word followed by left- and
17878right-hand braces. These commands insert special symbols in the
17879document; they do not require arguments. For example,
17880@code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}}
17881@result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}',
17882and @code{@@bullet@{@}} @result{} @samp{@bullet{}}.@refill
17883
17884@item 3. Alphabetic commands that require arguments within braces.
17885These commands start with @@ followed by a letter or a word, followed by an
17886argument within braces. For example, the command @code{@@dfn} indicates
17887the introductory or defining use of a term; it is used as follows: @samp{In
17888Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.}@refill
17889
17890@item 4. Alphabetic commands that occupy an entire line.
17891These commands occupy an entire line. The line starts with @@,
17892followed by the name of the command (a word); for example, @code{@@center}
17893or @code{@@cindex}. If no argument is needed, the word is followed by
17894the end of the line. If there is an argument, it is separated from
17895the command name by a space. Braces are not used.@refill
17896@end table
17897
17898@cindex Braces and argument syntax
17899Thus, the alphabetic commands fall into classes that have
17900different argument syntaxes. You cannot tell to which class a command
17901belongs by the appearance of its name, but you can tell by the
17902command's meaning: if the command stands for a glyph, it is in
17903class 2 and does not require an argument; if it makes sense to use the
17904command together with other text as part of a paragraph, the command
17905is in class 3 and must be followed by an argument in braces;
17906otherwise, it is in class 4 and uses the rest of the line as its
17907argument.@refill
17908
17909The purpose of having a different syntax for commands of classes 3 and
179104 is to make Texinfo files easier to read, and also to help the GNU
17911Emacs paragraph and filling commands work properly. There is only one
17912exception to this rule: the command @code{@@refill}, which is always
17913used at the end of a paragraph immediately following the final period
17914or other punctuation character. @code{@@refill} takes no argument and
17915does @emph{not} require braces. @code{@@refill} never confuses the
17916Emacs paragraph commands because it cannot appear at the beginning of
17917a line.@refill
17918
17919
17920@node Obtaining TeX
17921@appendix How to Obtain @TeX{}
17922@cindex Obtaining @TeX{}
17923@cindex @TeX{}, how to obtain
17924
17925@c !!! Here is information about obtaining TeX. Update it whenever.
17926@c !!! Also consider updating TeX.README on ftp.gnu.org.
17927@c Updated by RJC on 1 March 1995, conversation with MacKay.
17928@c Updated by kb@cs.umb.edu on 29 July 1996.
17929@c Updated by kb@cs.umb.edu on 25 April 1997.
17930@c Updated by kb@cs.umb.edu on 27 February 1998.
17931@TeX{} is freely redistributable. You can obtain @TeX{} for Unix
17932systems via anonymous ftp or on physical media. The core material
17933consists of the Web2c @TeX{} distribution (@uref{http://tug.org/web2c}).
17934
17935Instructions for retrieval by anonymous ftp and information on other
17936available distributions:
17937@example
17938@uref{ftp://tug.org/tex/unixtex.ftp}
17939@uref{http://tug.org/unixtex.ftp}
17940@end example
17941
17942The Free Software Foundation provides a core distribution on its Source
17943Code CD-ROM suitable for printing Texinfo manuals. To order it, contact:
17944
17945@display
17946@group
17947Free Software Foundation, Inc.
1794859 Temple Place Suite 330
17949Boston, MA @ @ 02111-1307
17950USA
17951Telephone: @w{+1-617-542-5942}
17952Fax: (including Japan) @w{+1-617-542-2652}
17953Free Dial Fax (in Japan):
17954@w{ } @w{ } @w{ } 0031-13-2473 (KDD)
17955@w{ } @w{ } @w{ } 0066-3382-0158 (IDC)
17956Electronic mail: @code{gnu@@gnu.org}
17957@end group
17958@end display
17959
17960Many other @TeX{} distributions are available; see
17961@uref{http://tug.org/}.
17962
17963
17964@c These are no longer ``new'', and the explanations
17965@c are all given elsewhere anyway, I think. --karl, 25apr97.
17966@c So ignore the entire appendix.
17967@ignore
17968@c node New Features, Command and Variable Index, Obtaining TeX, Top
17969@c appendix Second Edition Features
17970
17971@tex
17972% Widen the space for the first column so three control-character
17973% strings fit in the first column. Switched back to default .8in
17974% value at end of chapter.
17975\global\tableindent=1.0in
17976@end tex
17977
17978The second edition of the Texinfo manual describes more than 20 new
17979Texinfo mode commands and more than 50 previously undocumented Texinfo
17980@@-commands. This edition is more than twice the length of the first
17981edition.@refill
17982
17983Here is a brief description of the new commands.@refill
17984
17985@c menu
17986* New Texinfo Mode Commands:: The updating commands are especially useful.
17987* New Commands:: Many newly described @@-commands.
17988@c end menu
17989
17990@c node New Texinfo Mode Commands, New Commands, Obtaining TeX, Obtaining TeX
17991@c appendixsec New Texinfo Mode Commands
17992
17993Texinfo mode provides commands and features especially designed for
17994working with Texinfo files. More than 20 new commands have been
17995added, including commands for automatically creating and updating
17996both nodes and menus. This is a tedious task when done by hand.@refill
17997
17998The keybindings are intended to be somewhat mnemonic.@refill
17999
18000@c subheading Update all nodes and menus
18001
18002The @code{texinfo-master-menu} command is the primary command:
18003
18004@table @kbd
18005@item C-c C-u m
18006@itemx M-x texinfo-master-menu
18007Create or update a master menu.
18008With @kbd{C-u} as a prefix argument,
18009first create or update all nodes
18010and regular menus.
18011@end table
18012
18013@c subheading Update Pointers
18014
18015@noindent
18016Create or update `Next', `Previous', and `Up' node pointers.@refill
18017
18018@noindent
18019@xref{Updating Nodes and Menus}.
18020
18021@table @kbd
18022@item C-c C-u C-n
18023@itemx M-x texinfo-update-node
18024Update a node.
18025
18026@item C-c C-u C-e
18027@itemx M-x texinfo-every-node-update
18028Update every node in the buffer.
18029@end table
18030
18031@c subheading Update Menus
18032
18033@noindent
18034Create or update menus.@refill
18035
18036@noindent
18037@xref{Updating Nodes and Menus}.
18038
18039@table @kbd
18040@item C-c C-u C-m
18041@itemx M-x texinfo-make-menu
18042Make or update a menu.
18043
18044@item C-c C-u C-a
18045@itemx M-x texinfo-all-menus-update
18046Make or update all the menus in a buffer.
18047With @kbd{C-u} as a prefix argument,
18048first update all the nodes.
18049@end table
18050
18051@c subheading Insert Title as Description
18052
18053@noindent
18054Insert a node's chapter or section title in the space for the
18055description in a menu entry line; position point so you can edit the
18056insert. (This command works somewhat differently than the other
18057insertion commands, which insert only a predefined string.)@refill
18058
18059@noindent
18060@xref{Inserting, Inserting Frequently Used Commands}.
18061
18062@table @kbd
18063@item C-c C-c C-d
18064Insert title.
18065@end table
18066
18067@c subheading Format for Info
18068
18069@noindent
18070Provide keybindings both for the Info formatting commands that are
18071written in Emacs Lisp and for @code{makeinfo} that is written in
18072C.@refill
18073
18074@noindent
18075@xref{Info Formatting}.
18076
18077@noindent
18078Use the Emacs lisp @code{texinfo-format@dots{}} commands:
18079
18080@table @kbd
18081@item C-c C-e C-r
18082Format the region.
18083
18084@item C-c C-e C-b
18085Format the buffer.
18086@end table
18087
18088@noindent
18089Use @code{makeinfo}:
18090
18091@table @kbd
18092@item C-c C-m C-r
18093Format the region.
18094
18095@item C-c C-m C-b
18096Format the buffer.
18097
18098@item C-c C-m C-l
18099Recenter the @code{makeinfo} output buffer.
18100
18101@item C-c C-m C-k
18102Kill the @code{makeinfo} formatting job.
18103@end table
18104
18105@c subheading Typeset and Print
18106
18107@noindent
18108Typeset and print Texinfo documents from within Emacs.@refill
18109
18110@ifinfo
18111@noindent
18112@xref{Printing}.
18113@end ifinfo
18114@iftex
18115@noindent
18116@xref{Printing, , Formatting and Printing}.
18117@end iftex
18118
18119@table @kbd
18120@item C-c C-t C-b
18121Run @code{texi2dvi} on the buffer.
18122
18123@item C-c C-t C-r
18124Run @TeX{} on the region.
18125
18126@item C-c C-t C-i
18127Run @code{texindex}.
18128
18129@item C-c C-t C-p
18130Print the DVI file.
18131
18132@item C-c C-t C-q
18133Show the print queue.
18134
18135@item C-c C-t C-d
18136Delete a job from the print queue.
18137
18138@item C-c C-t C-k
18139Kill the current @TeX{} formatting job.
18140
18141@item C-c C-t C-x
18142Quit a currently stopped @TeX{} formatting job.
18143
18144@item C-c C-t C-l
18145Recenter the output buffer.
18146@end table
18147
18148@c subheading Other Updating Commands
18149
18150@noindent
18151The ``other updating commands'' do not have standard keybindings because
18152they are used less frequently.@refill
18153
18154@noindent
18155@xref{Other Updating Commands}.
18156
18157@table @kbd
18158@item M-x texinfo-insert-node-lines
18159Insert missing @code{@@node} lines using
18160section titles as node names.
18161
18162@item M-x texinfo-multiple-files-update
18163Update a multi-file document.
18164With a numeric prefix, such as @kbd{C-u 8},
18165update @strong{every} pointer and
18166menu in @strong{all} the files and
18167then insert a master menu.
18168
18169@item M-x texinfo-indent-menu-description
18170Indent descriptions in menus.
18171
18172@item M-x texinfo-sequential-node-update
18173Insert node pointers in strict sequence.
18174@end table
18175
18176@c no.de New Commands, , New Texinfo Mode Commands, Obtaining TeX
18177@c appendix.sec New Texinfo @@-Commands
18178
18179The second edition of the Texinfo manual describes more than 50
18180commands that were not described in the first edition. A third or so
18181of these commands existed in Texinfo but were not documented in the
18182manual; the others are new. Here is a listing, with brief
18183descriptions of them:@refill
18184
18185@c subheading Indexing
18186
18187@noindent
18188Create your own index, and merge indices.@refill
18189
18190@noindent
18191@xref{Indices}.
18192
18193@table @kbd
18194@item @@defindex @var{index-name}
18195Define a new index and its indexing command.
18196See also the @code{@@defcodeindex} command.
18197
18198@c written verbosely to avoid overfull hbox
18199@item @@synindex @var{from-index} @var{into-index}
18200Merge the @var{from-index} index into the @var{into-index} index.
18201See also the @code{@@syncodeindex} command.
18202@end table
18203
18204@c subheading Definitions
18205
18206@noindent
18207Describe functions, variables, macros,
18208commands, user options, special forms, and other such artifacts in a
18209uniform format.@refill
18210
18211@noindent
18212@xref{Definition Commands}.
18213
18214@table @kbd
18215@item @@deffn @var{category} @var{name} @var{arguments}@dots{}
18216Format a description for functions, interactive
18217commands, and similar entities.
18218
18219@item @@defvr, @@defop, @dots{}
1822015 other related commands.
18221@end table
18222
18223@c subheading Glyphs
18224
18225@noindent
18226Indicate the results of evaluation, expansion,
18227printed output, an error message, equivalence of expressions, and the
18228location of point.@refill
18229
18230@noindent
18231@xref{Glyphs}.
18232
18233@table @kbd
18234@item @@equiv@{@}
18235@itemx @equiv{}
18236Equivalence:
18237
18238@item @@error@{@}
18239@itemx @error{}
18240Error message
18241
18242@item @@expansion@{@}
18243@itemx @expansion{}
18244Macro expansion
18245
18246@item @@point@{@}
18247@itemx @point{}
18248Position of point
18249
18250@item @@print@{@}
18251@itemx @print{}
18252Printed output
18253
18254@item @@result@{@}
18255@itemx @result{}
18256Result of an expression
18257@end table
18258
18259@c subheading Page Headings
18260
18261@noindent
18262Customize page headings.
18263
18264@noindent
18265@xref{Headings}.
18266
18267@table @kbd
18268@item @@headings @var{on-off-single-double}
18269Headings on or off, single, or double-sided.
18270
18271@item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
18272Footings for even-numbered (left-hand) pages.
18273
18274@item @@evenheading, @@everyheading, @@oddheading, @dots{}
18275Five other related commands.
18276
18277@item @@thischapter
18278Insert name of chapter and chapter number.
18279
18280@item @@thischaptername, @@thisfile, @@thistitle, @@thispage
18281Related commands.
18282@end table
18283
18284@c subheading Formatting
18285
18286@noindent
18287Format blocks of text.
18288
18289@noindent
18290@xref{Quotations and Examples}, and@*
18291@ref{Lists and Tables, , Making Lists and Tables}.
18292
18293@table @kbd
18294@item @@cartouche
18295Draw rounded box surrounding text (not in Info).
18296
18297@item @@enumerate @var{optional-arg}
18298Enumerate a list with letters or numbers.
18299
18300@item @@exdent @var{line-of-text}
18301Remove indentation.
18302
18303@item @@flushleft
18304Left justify.
18305
18306@item @@flushright
18307Right justify.
18308
18309@item @@format
18310Do not narrow nor change font.
18311
18312@item @@ftable @var{formatting-command}
18313@itemx @@vtable @var{formatting-command}
18314Two-column table with indexing.
18315
18316@item @@lisp
18317For an example of Lisp code.
18318
18319@item @@smallexample
18320@itemx @@smalllisp
18321Like @@table and @@lisp @r{but for} @@smallbook.
18322@end table
18323
18324@c subheading Conditionals
18325
18326@noindent
18327Conditionally format text.
18328
18329@noindent
18330@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
18331
18332@table @kbd
18333@item @@set @var{flag} [@var{string}]
18334Set a flag. Optionally, set value
18335of @var{flag} to @var{string}.
18336
18337@item @@clear @var{flag}
18338Clear a flag.
18339
18340@item @@value@{@var{flag}@}
18341Replace with value to which @var{flag} is set.
18342
18343@item @@ifset @var{flag}
18344Format, if @var{flag} is set.
18345
18346@item @@ifclear @var{flag}
18347Ignore, if @var{flag} is set.
18348@end table
18349
18350@c subheading @@heading series for Titles
18351
18352@noindent
18353Produce unnumbered headings that do not appear in a table of contents.
18354
18355@noindent
18356@xref{Structuring}.
18357
18358@table @kbd
18359@item @@heading @var{title}
18360Unnumbered section-like heading not listed
18361in the table of contents of a printed manual.
18362
18363@item @@chapheading, @@majorheading, @@c subheading, @@subsubheading
18364Related commands.
18365@end table
18366
18367@need 1000
18368@c subheading Font commands
18369
18370@need 1000
18371@noindent
18372@xref{Smallcaps}, and @*
18373@ref{Fonts}.
18374
18375@table @kbd
18376@item @@r@{@var{text}@}
18377Print in roman font.
18378
18379@item @@sc@{@var{text}@}
18380Print in @sc{small caps} font.
18381@end table
18382
18383@c subheading Miscellaneous
18384
18385@noindent
18386See @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author} Commands},@*
18387see @ref{Customized Highlighting},@*
18388see @ref{Overfull hboxes},@*
18389see @ref{Footnotes},@*
18390see @ref{dmn, , Format a Dimension},@*
18391see @ref{Raise/lower sections, , @code{@@raisesections} and @code{@@lowersections}},@*
18392see @ref{math, , @code{@@math}: Inserting Mathematical Expressions}.@*
18393see @ref{minus, , Inserting a Minus Sign},@*
18394see @ref{paragraphindent, , Paragraph Indenting},@*
18395see @ref{Cross Reference Commands},@*
18396see @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author}}, and@*
18397see @ref{Custom Headings, , How to Make Your Own Headings}.
18398
18399@table @kbd
18400@item @@author @var{author}
18401Typeset author's name.
18402
18403@c @item @@definfoenclose @var{new-command}, @var{before}, @var{after},
18404@c Define a highlighting command for Info. (Info only.)
18405
18406@item @@finalout
18407Produce cleaner printed output.
18408
18409@item @@footnotestyle @var{end-or-separate}
18410Specify footnote style.
18411
18412@item @@dmn@{@var{dimension}@}
18413Format a dimension.
18414
18415@item @@global@@let@var{new-cmd}=@var{existing-cmd}
18416Define a highlighting command for @TeX{}. (@TeX{} only.)
18417
18418@item @@lowersections
18419Reduce hierarchical level of sectioning commands.
18420
18421@item @@math@{@var{mathematical-expression}@}
18422Format a mathematical expression.
18423
18424@item @@minus@{@}
18425Generate a minus sign.
18426
18427@item @@paragraphindent @var{asis-or-number}
18428Specify paragraph indentation.
18429
18430@item @@raisesections
18431Raise hierarchical level of sectioning commands.
18432
18433@item @@ref@{@var{node-name}, @r{[}@var{entry}@r{]}, @r{[}@var{topic-or-title}@r{]}, @r{[}@var{info-file}@r{]}, @r{[}@var{manual}@r{]}@}
18434Make a reference. In the printed manual, the
18435reference does not start with the word `see'.
18436
18437@item @@title @var{title}
18438Typeset @var{title} in the alternative
18439title page format.
18440
18441@item @@subtitle @var{subtitle}
18442Typeset @var{subtitle} in the alternative
18443title page format.
18444
18445@item @@today@{@}
18446Insert the current date.
18447@end table
18448@tex
18449% Switch width of first column of tables back to default value
18450\global\tableindent=.8in
18451@end tex
18452@end ignore
18453
18454
| 17406
17407Emacs has two tools for catching the @@-command mistakes and two for
17408catching structuring mistakes.@refill
17409
17410For finding problems with @@-commands, you can run @TeX{} or a region
17411formatting command on the region that has a problem; indeed, you can
17412run these commands on each region as you write it.@refill
17413
17414For finding problems with the structure of nodes and chapters, you can use
17415@kbd{C-c C-s} (@code{texinfo-show-structure}) and the related @code{occur}
17416command and you can use the @kbd{M-x Info-validate} command.@refill
17417
17418@menu
17419* makeinfo Preferred:: @code{makeinfo} finds errors.
17420* Debugging with Info:: How to catch errors with Info formatting.
17421* Debugging with TeX:: How to catch errors with @TeX{} formatting.
17422* Using texinfo-show-structure:: How to use @code{texinfo-show-structure}.
17423* Using occur:: How to list all lines containing a pattern.
17424* Running Info-Validate:: How to find badly referenced nodes.
17425@end menu
17426
17427@node makeinfo Preferred, Debugging with Info, Catching Mistakes, Catching Mistakes
17428@ifinfo
17429@heading @code{makeinfo} Find Errors
17430@end ifinfo
17431
17432The @code{makeinfo} program does an excellent job of catching errors
17433and reporting them---far better than @code{texinfo-format-region} or
17434@code{texinfo-format-buffer}. In addition, the various functions for
17435automatically creating and updating node pointers and menus remove
17436many opportunities for human error.@refill
17437
17438If you can, use the updating commands to create and insert pointers
17439and menus. These prevent many errors. Then use @code{makeinfo} (or
17440its Texinfo mode manifestations, @code{makeinfo-region} and
17441@code{makeinfo-buffer}) to format your file and check for other
17442errors. This is the best way to work with Texinfo. But if you
17443cannot use @code{makeinfo}, or your problem is very puzzling, then you
17444may want to use the tools described in this appendix.@refill
17445
17446@node Debugging with Info, Debugging with TeX, makeinfo Preferred, Catching Mistakes
17447@comment node-name, next, previous, up
17448@section Catching Errors with Info Formatting
17449@cindex Catching errors with Info formatting
17450@cindex Debugging with Info formatting
17451
17452After you have written part of a Texinfo file, you can use the
17453@code{texinfo-format-region} or the @code{makeinfo-region} command to
17454see whether the region formats properly.@refill
17455
17456Most likely, however, you are reading this section because for some
17457reason you cannot use the @code{makeinfo-region} command; therefore, the
17458rest of this section presumes that you are using
17459@code{texinfo-format-region}.@refill
17460
17461If you have made a mistake with an @@-command,
17462@code{texinfo-format-region} will stop processing at or after the
17463error and display an error message. To see where in the buffer the
17464error occurred, switch to the @samp{*Info Region*} buffer; the cursor
17465will be in a position that is after the location of the error. Also,
17466the text will not be formatted after the place where the error
17467occurred (or more precisely, where it was detected).@refill
17468
17469For example, if you accidentally end a menu with the command @code{@@end
17470menus} with an `s' on the end, instead of with @code{@@end menu}, you
17471will see an error message that says:@refill
17472
17473@example
17474@@end menus is not handled by texinfo
17475@end example
17476
17477@noindent
17478The cursor will stop at the point in the buffer where the error
17479occurs, or not long after it. The buffer will look like this:@refill
17480
17481@example
17482@group
17483---------- Buffer: *Info Region* ----------
17484* Menu:
17485
17486* Using texinfo-show-structure:: How to use
17487 `texinfo-show-structure'
17488 to catch mistakes.
17489* Running Info-Validate:: How to check for
17490 unreferenced nodes.
17491@@end menus
17492@point{}
17493---------- Buffer: *Info Region* ----------
17494@end group
17495@end example
17496
17497The @code{texinfo-format-region} command sometimes provides slightly
17498odd error messages. For example, the following cross reference fails to format:@refill
17499
17500@example
17501(@@xref@{Catching Mistakes, for more info.)
17502@end example
17503
17504@noindent
17505In this case, @code{texinfo-format-region} detects the missing closing
17506brace but displays a message that says @samp{Unbalanced parentheses}
17507rather than @samp{Unbalanced braces}. This is because the formatting
17508command looks for mismatches between braces as if they were
17509parentheses.@refill
17510
17511Sometimes @code{texinfo-format-region} fails to detect mistakes. For
17512example, in the following, the closing brace is swapped with the
17513closing parenthesis:@refill
17514
17515@example
17516(@@xref@{Catching Mistakes), for more info.@}
17517@end example
17518
17519@noindent
17520Formatting produces:
17521@example
17522(*Note for more info.: Catching Mistakes)
17523@end example
17524
17525The only way for you to detect this error is to realize that the
17526reference should have looked like this:@refill
17527
17528@example
17529(*Note Catching Mistakes::, for more info.)
17530@end example
17531
17532Incidentally, if you are reading this node in Info and type @kbd{f
17533@key{RET}} (@code{Info-follow-reference}), you will generate an error
17534message that says:
17535
17536@example
17537No such node: "Catching Mistakes) The only way @dots{}
17538@end example
17539
17540@noindent
17541This is because Info perceives the example of the error as the first
17542cross reference in this node and if you type a @key{RET} immediately
17543after typing the Info @kbd{f} command, Info will attempt to go to the
17544referenced node. If you type @kbd{f catch @key{TAB} @key{RET}}, Info
17545will complete the node name of the correctly written example and take
17546you to the `Catching Mistakes' node. (If you try this, you can return
17547from the `Catching Mistakes' node by typing @kbd{l}
17548(@code{Info-last}).)
17549
17550@c !!! section on using Elisp debugger ignored.
17551@ignore
17552Sometimes @code{texinfo-format-region} will stop long after the
17553original error; this is because it does not discover the problem until
17554then. In this case, you will need to backtrack.@refill
17555
17556@c menu
17557@c * Using the Emacs Lisp Debugger:: How to use the Emacs Lisp debugger.
17558@c end menu
17559
17560@c node Using the Emacs Lisp Debugger
17561@c appendixsubsec Using the Emacs Lisp Debugger
17562@c index Using the Emacs Lisp debugger
17563@c index Emacs Lisp debugger
17564@c index Debugger, using the Emacs Lisp
17565
17566If an error is especially elusive, you can turn on the Emacs Lisp
17567debugger and look at the backtrace; this tells you where in the
17568@code{texinfo-format-region} function the problem occurred. You can
17569turn on the debugger with the command:@refill
17570
17571@example
17572M-x set-variable @key{RET} debug-on-error @key{RET} t @key{RET}
17573@end example
17574
17575@noindent
17576and turn it off with
17577
17578@example
17579M-x set-variable @key{RET} debug-on-error @key{RET} nil @key{RET}
17580@end example
17581
17582Often, when you are using the debugger, it is easier to follow what is
17583going on if you use the Emacs Lisp files that are not byte-compiled.
17584The byte-compiled sources send octal numbers to the debugger that may
17585look mysterious. To use the uncompiled source files, load
17586@file{texinfmt.el} and @file{texinfo.el} with the @kbd{M-x load-file}
17587command.@refill
17588
17589The debugger will not catch an error if @code{texinfo-format-region}
17590does not detect one. In the example shown above,
17591@code{texinfo-format-region} did not find the error when the whole
17592list was formatted, but only when part of the list was formatted.
17593When @code{texinfo-format-region} did not find an error, the debugger
17594did not find one either. @refill
17595
17596However, when @code{texinfo-format-region} did report an error, it
17597invoked the debugger. This is the backtrace it produced:@refill
17598
17599@example
17600---------- Buffer: *Backtrace* ----------
17601Signalling: (search-failed "[@},]")
17602 re-search-forward("[@},]")
17603 (while ...)
17604 (let ...)
17605 texinfo-format-parse-args()
17606 (let ...)
17607 texinfo-format-xref()
17608 funcall(texinfo-format-xref)
17609 (if ...)
17610 (let ...)
17611 (if ...)
17612 (while ...)
17613 texinfo-format-scan()
17614 (save-excursion ...)
17615 (let ...)
17616 texinfo-format-region(103370 103631)
17617* call-interactively(texinfo-format-region)
17618---------- Buffer: *Backtrace* ----------
17619@end example
17620
17621The backtrace is read from the bottom up.
17622@code{texinfo-format-region} was called interactively; and it, in
17623turn, called various functions, including @code{texinfo-format-scan},
17624@code{texinfo-format-xref} and @code{texinfo-format-parse-args}.
17625Inside the function @code{texinfo-format-parse-args}, the function
17626@code{re-search-forward} was called; it was this function that could
17627not find the missing right-hand brace.@refill
17628
17629@xref{Lisp Debug, , Debugging Emacs Lisp, emacs, The GNU Emacs
17630Manual}, for more information.@refill
17631@end ignore
17632
17633@node Debugging with TeX, Using texinfo-show-structure, Debugging with Info, Catching Mistakes
17634@comment node-name, next, previous, up
17635@section Catching Errors with @TeX{} Formatting
17636@cindex Catching errors with @TeX{} formatting
17637@cindex Debugging with @TeX{} formatting
17638
17639You can also catch mistakes when you format a file with @TeX{}.@refill
17640
17641Usually, you will want to do this after you have run
17642@code{texinfo-format-buffer} (or, better, @code{makeinfo-buffer}) on
17643the same file, because @code{texinfo-format-buffer} sometimes displays
17644error messages that make more sense than @TeX{}. (@xref{Debugging
17645with Info}, for more information.)@refill
17646
17647For example, @TeX{} was run on a Texinfo file, part of which is shown
17648here:@refill
17649
17650@example
17651---------- Buffer: texinfo.texi ----------
17652name of the Texinfo file as an extension. The
17653@@samp@{??@} are `wildcards' that cause the shell to
17654substitute all the raw index files. (@@xref@{sorting
17655indices, for more information about sorting
17656indices.)@@refill
17657---------- Buffer: texinfo.texi ----------
17658@end example
17659
17660@noindent
17661(The cross reference lacks a closing brace.)
17662@TeX{} produced the following output, after which it stopped:@refill
17663
17664@example
17665---------- Buffer: *tex-shell* ----------
17666Runaway argument?
17667@{sorting indices, for more information about sorting
17668indices.) @@refill @@ETC.
17669! Paragraph ended before @@xref was complete.
17670<to be read again>
17671 @@par
17672l.27
17673
17674?
17675---------- Buffer: *tex-shell* ----------
17676@end example
17677
17678In this case, @TeX{} produced an accurate and
17679understandable error message:
17680
17681@example
17682Paragraph ended before @@xref was complete.
17683@end example
17684
17685@noindent
17686@samp{@@par} is an internal @TeX{} command of no relevance to Texinfo.
17687@samp{l.27} means that @TeX{} detected the problem on line 27 of the
17688Texinfo file. The @samp{?} is the prompt @TeX{} uses in this
17689circumstance.@refill
17690
17691Unfortunately, @TeX{} is not always so helpful, and sometimes you must
17692truly be a Sherlock Holmes to discover what went wrong.@refill
17693
17694In any case, if you run into a problem like this, you can do one of three
17695things.@refill
17696
17697@enumerate
17698@item
17699You can tell @TeX{} to continue running and ignore just this error by
17700typing @key{RET} at the @samp{?} prompt.@refill
17701
17702@item
17703You can tell @TeX{} to continue running and to ignore all errors as best
17704it can by typing @kbd{r @key{RET}} at the @samp{?} prompt.@refill
17705
17706This is often the best thing to do. However, beware: the one error
17707may produce a cascade of additional error messages as its consequences
17708are felt through the rest of the file. To stop @TeX{} when it is
17709producing such an avalanche of error messages, type @kbd{C-c} (or
17710@kbd{C-c C-c}, if you are running a shell inside Emacs).
17711
17712@item
17713You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}}
17714at the @samp{?} prompt.@refill
17715@end enumerate
17716
17717If you are running @TeX{} inside Emacs, you need to switch to the shell
17718buffer and line at which @TeX{} offers the @samp{?} prompt.
17719
17720Sometimes @TeX{} will format a file without producing error messages even
17721though there is a problem. This usually occurs if a command is not ended
17722but @TeX{} is able to continue processing anyhow. For example, if you fail
17723to end an itemized list with the @code{@@end itemize} command, @TeX{} will
17724write a DVI file that you can print out. The only error message that
17725@TeX{} will give you is the somewhat mysterious comment that@refill
17726
17727@example
17728(@@end occurred inside a group at level 1)
17729@end example
17730
17731@noindent
17732However, if you print the DVI file, you will find that the text
17733of the file that follows the itemized list is entirely indented as if
17734it were part of the last item in the itemized list. The error message
17735is the way @TeX{} says that it expected to find an @code{@@end}
17736command somewhere in the file; but that it could not determine where
17737it was needed.@refill
17738
17739Another source of notoriously hard-to-find errors is a missing
17740@code{@@end group} command. If you ever are stumped by
17741incomprehensible errors, look for a missing @code{@@end group} command
17742first.@refill
17743
17744If the Texinfo file lacks header lines,
17745@TeX{} may stop in the
17746beginning of its run and display output that looks like the following.
17747The @samp{*} indicates that @TeX{} is waiting for input.@refill
17748
17749@example
17750This is TeX, Version 3.14159 (Web2c 7.0)
17751(test.texinfo [1])
17752*
17753@end example
17754
17755@noindent
17756In this case, simply type @kbd{\end @key{RET}} after the asterisk. Then
17757write the header lines in the Texinfo file and run the @TeX{} command
17758again. (Note the use of the backslash, @samp{\}. @TeX{} uses @samp{\}
17759instead of @samp{@@}; and in this circumstance, you are working
17760directly with @TeX{}, not with Texinfo.)@refill
17761
17762@node Using texinfo-show-structure, Using occur, Debugging with TeX, Catching Mistakes
17763@comment node-name, next, previous, up
17764@section Using @code{texinfo-show-structure}
17765@cindex Showing the structure of a file
17766@findex texinfo-show-structure
17767
17768It is not always easy to keep track of the nodes, chapters, sections, and
17769subsections of a Texinfo file. This is especially true if you are revising
17770or adding to a Texinfo file that someone else has written.@refill
17771
17772In GNU Emacs, in Texinfo mode, the @code{texinfo-show-structure}
17773command lists all the lines that begin with the @@-commands that
17774specify the structure: @code{@@chapter}, @code{@@section},
17775@code{@@appendix}, and so on. With an argument (@w{@kbd{C-u}}
17776as prefix argument, if interactive),
17777the command also shows the @code{@@node} lines. The
17778@code{texinfo-show-structure} command is bound to @kbd{C-c C-s} in
17779Texinfo mode, by default.@refill
17780
17781The lines are displayed in a buffer called the @samp{*Occur*} buffer,
17782indented by hierarchical level. For example, here is a part of what was
17783produced by running @code{texinfo-show-structure} on this manual:@refill
17784
17785@example
17786@group
17787 Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\|
17788 unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
17789 in buffer texinfo.texi.
17790 @dots{}
17791 4177:@@chapter Nodes
17792 4198: @@heading Two Paths
17793 4231: @@section Node and Menu Illustration
17794 4337: @@section The @@code@{@@@@node@} Command
17795 4393: @@subheading Choosing Node and Pointer Names
17796 4417: @@subsection How to Write an @@code@{@@@@node@} Line
17797 4469: @@subsection @@code@{@@@@node@} Line Tips
17798 @dots{}
17799@end group
17800@end example
17801
17802This says that lines 4337, 4393, and 4417 of @file{texinfo.texi} begin
17803with the @code{@@section}, @code{@@subheading}, and @code{@@subsection}
17804commands respectively. If you move your cursor into the @samp{*Occur*}
17805window, you can position the cursor over one of the lines and use the
17806@kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to
17807the corresponding spot in the Texinfo file. @xref{Other Repeating
17808Search, , Using Occur, emacs, The GNU Emacs Manual}, for more
17809information about @code{occur-mode-goto-occurrence}.@refill
17810
17811The first line in the @samp{*Occur*} window describes the @dfn{regular
17812expression} specified by @var{texinfo-heading-pattern}. This regular
17813expression is the pattern that @code{texinfo-show-structure} looks for.
17814@xref{Regexps, , Using Regular Expressions, emacs, The GNU Emacs Manual},
17815for more information.@refill
17816
17817When you invoke the @code{texinfo-show-structure} command, Emacs will
17818display the structure of the whole buffer. If you want to see the
17819structure of just a part of the buffer, of one chapter, for example,
17820use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the
17821region. (@xref{Narrowing, , , emacs, The GNU Emacs Manual}.) This is
17822how the example used above was generated. (To see the whole buffer
17823again, use @kbd{C-x n w} (@code{widen}).)@refill
17824
17825If you call @code{texinfo-show-structure} with a prefix argument by
17826typing @w{@kbd{C-u C-c C-s}}, it will list lines beginning with
17827@code{@@node} as well as the lines beginning with the @@-sign commands
17828for @code{@@chapter}, @code{@@section}, and the like.@refill
17829
17830You can remind yourself of the structure of a Texinfo file by looking at
17831the list in the @samp{*Occur*} window; and if you have mis-named a node
17832or left out a section, you can correct the mistake.@refill
17833
17834@node Using occur, Running Info-Validate, Using texinfo-show-structure, Catching Mistakes
17835@comment node-name, next, previous, up
17836@section Using @code{occur}
17837@cindex Occurrences, listing with @code{@@occur}
17838@findex occur
17839
17840Sometimes the @code{texinfo-show-structure} command produces too much
17841information. Perhaps you want to remind yourself of the overall structure
17842of a Texinfo file, and are overwhelmed by the detailed list produced by
17843@code{texinfo-show-structure}. In this case, you can use the @code{occur}
17844command directly. To do this, type@refill
17845
17846@example
17847@kbd{M-x occur}
17848@end example
17849
17850@noindent
17851and then, when prompted, type a @dfn{regexp}, a regular expression for
17852the pattern you want to match. (@xref{Regexps, , Regular Expressions,
17853emacs, The GNU Emacs Manual}.) The @code{occur} command works from
17854the current location of the cursor in the buffer to the end of the
17855buffer. If you want to run @code{occur} on the whole buffer, place
17856the cursor at the beginning of the buffer.@refill
17857
17858For example, to see all the lines that contain the word
17859@samp{@@chapter} in them, just type @samp{@@chapter}. This will
17860produce a list of the chapters. It will also list all the sentences
17861with @samp{@@chapter} in the middle of the line.@refill
17862
17863If you want to see only those lines that start with the word
17864@samp{@@chapter}, type @samp{^@@chapter} when prompted by
17865@code{occur}. If you want to see all the lines that end with a word
17866or phrase, end the last word with a @samp{$}; for example,
17867@samp{catching mistakes$}. This can be helpful when you want to see
17868all the nodes that are part of the same chapter or section and
17869therefore have the same `Up' pointer.@refill
17870
17871@xref{Other Repeating Search, , Using Occur, emacs , The GNU Emacs Manual},
17872for more information.@refill
17873
17874@node Running Info-Validate, , Using occur, Catching Mistakes
17875@comment node-name, next, previous, up
17876@section Finding Badly Referenced Nodes
17877@findex Info-validate
17878@cindex Nodes, checking for badly referenced
17879@cindex Checking for badly referenced nodes
17880@cindex Looking for badly referenced nodes
17881@cindex Finding badly referenced nodes
17882@cindex Badly referenced nodes
17883
17884You can use the @code{Info-validate} command to check whether any of
17885the `Next', `Previous', `Up' or other node pointers fail to point to a
17886node. This command checks that every node pointer points to an
17887existing node. The @code{Info-validate} command works only on Info
17888files, not on Texinfo files.@refill
17889
17890The @code{makeinfo} program validates pointers automatically, so you
17891do not need to use the @code{Info-validate} command if you are using
17892@code{makeinfo}. You only may need to use @code{Info-validate} if you
17893are unable to run @code{makeinfo} and instead must create an Info file
17894using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or
17895if you write an Info file from scratch.@refill
17896
17897@menu
17898* Using Info-validate:: How to run @code{Info-validate}.
17899* Unsplit:: How to create an unsplit file.
17900* Tagifying:: How to tagify a file.
17901* Splitting:: How to split a file manually.
17902@end menu
17903
17904@node Using Info-validate, Unsplit, Running Info-Validate, Running Info-Validate
17905@subsection Running @code{Info-validate}
17906@cindex Running @code{Info-validate}
17907@cindex Info validating a large file
17908@cindex Validating a large file
17909
17910To use @code{Info-validate}, visit the Info file you wish to check and
17911type:@refill
17912
17913@example
17914M-x Info-validate
17915@end example
17916
17917@noindent
17918Note that the @code{Info-validate} command requires an upper case
17919`I'. You may also need to create a tag table before running
17920@code{Info-validate}. @xref{Tagifying}.
17921
17922If your file is valid, you will receive a message that says ``File appears
17923valid''. However, if you have a pointer that does not point to a node,
17924error messages will be displayed in a buffer called @samp{*problems in
17925info file*}.@refill
17926
17927For example, @code{Info-validate} was run on a test file that contained
17928only the first node of this manual. One of the messages said:@refill
17929
17930@example
17931In node "Overview", invalid Next: Texinfo Mode
17932@end example
17933
17934@noindent
17935This meant that the node called @samp{Overview} had a `Next' pointer that
17936did not point to anything (which was true in this case, since the test file
17937had only one node in it).@refill
17938
17939Now suppose we add a node named @samp{Texinfo Mode} to our test case
17940but we do not specify a `Previous' for this node. Then we will get
17941the following error message:@refill
17942
17943@example
17944In node "Texinfo Mode", should have Previous: Overview
17945@end example
17946
17947@noindent
17948This is because every `Next' pointer should be matched by a
17949`Previous' (in the node where the `Next' points) which points back.@refill
17950
17951@code{Info-validate} also checks that all menu entries and cross references
17952point to actual nodes.@refill
17953
17954@code{Info-validate} requires a tag table and does not work with files
17955that have been split. (The @code{texinfo-format-buffer} command
17956automatically splits large files.) In order to use @code{Info-validate}
17957on a large file, you must run @code{texinfo-format-buffer} with an
17958argument so that it does not split the Info file; and you must create a
17959tag table for the unsplit file.
17960
17961@node Unsplit, Tagifying, Using Info-validate, Running Info-Validate
17962@comment node-name, next, previous, up
17963@subsection Creating an Unsplit File
17964@cindex Creating an unsplit file
17965@cindex Unsplit file creation
17966
17967You can run @code{Info-validate} only on a single Info file that has a
17968tag table. The command will not work on the indirect subfiles that
17969are generated when a master file is split. If you have a large file
17970(longer than 70,000 bytes or so), you need to run the
17971@code{texinfo-format-buffer} or @code{makeinfo-buffer} command in such
17972a way that it does not create indirect subfiles. You will also need
17973to create a tag table for the Info file. After you have done this,
17974you can run @code{Info-validate} and look for badly referenced
17975nodes.@refill
17976
17977The first step is to create an unsplit Info file. To prevent
17978@code{texinfo-format-buffer} from splitting a Texinfo file into
17979smaller Info files, give a prefix to the @kbd{M-x
17980texinfo-format-buffer} command:@refill
17981
17982@example
17983C-u M-x texinfo-format-buffer
17984@end example
17985
17986@noindent
17987or else
17988
17989@example
17990C-u C-c C-e C-b
17991@end example
17992
17993@noindent
17994When you do this, Texinfo will not split the file and will not create
17995a tag table for it. @refill
17996@cindex Making a tag table manually
17997@cindex Tag table, making manually
17998
17999@node Tagifying, Splitting, Unsplit, Running Info-Validate
18000@subsection Tagifying a File
18001
18002After creating an unsplit Info file, you must create a tag table for
18003it. Visit the Info file you wish to tagify and type:@refill
18004
18005@example
18006M-x Info-tagify
18007@end example
18008
18009@noindent
18010(Note the upper case @samp{I} in @code{Info-tagify}.) This creates an
18011Info file with a tag table that you can validate.@refill
18012
18013The third step is to validate the Info file:@refill
18014
18015@example
18016M-x Info-validate
18017@end example
18018
18019@noindent
18020(Note the upper case @samp{I} in @code{Info-validate}.)
18021In brief, the steps are:@refill
18022
18023@example
18024@group
18025C-u M-x texinfo-format-buffer
18026M-x Info-tagify
18027M-x Info-validate
18028@end group
18029@end example
18030
18031After you have validated the node structure, you can rerun
18032@code{texinfo-format-buffer} in the normal way so it will construct a
18033tag table and split the file automatically, or you can make the tag
18034table and split the file manually.@refill
18035
18036@node Splitting, , Tagifying, Running Info-Validate
18037@comment node-name, next, previous, up
18038@subsection Splitting a File Manually
18039@cindex Splitting an Info file manually
18040@cindex Info file, splitting manually
18041
18042You should split a large file or else let the
18043@code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it
18044for you automatically. (Generally you will let one of the formatting
18045commands do this job for you. @xref{Creating an Info File}.)@refill
18046
18047The split-off files are called the indirect subfiles.@refill
18048
18049Info files are split to save memory. With smaller files, Emacs does not
18050have make such a large buffer to hold the information.@refill
18051
18052If an Info file has more than 30 nodes, you should also make a tag
18053table for it. @xref{Using Info-validate}, for information
18054about creating a tag table. (Again, tag tables are usually created
18055automatically by the formatting command; you only need to create a tag
18056table yourself if you are doing the job manually. Most likely, you
18057will do this for a large, unsplit file on which you have run
18058@code{Info-validate}.)@refill
18059
18060@c Info-split is autoloaded in `loaddefs.el' in Emacs 18.51
18061@ignore
18062Before running @code{Info-split}, you need to load the @code{info} library
18063into Emacs by giving the command @kbd{M-x load-library @key{RET} info
18064@key{RET}}.
18065@end ignore
18066
18067Visit the Info file you wish to tagify and split and type the two
18068commands:@refill
18069
18070@example
18071M-x Info-tagify
18072M-x Info-split
18073@end example
18074
18075@noindent
18076(Note that the @samp{I} in @samp{Info} is upper case.)@refill
18077
18078When you use the @code{Info-split} command, the buffer is modified into a
18079(small) Info file which lists the indirect subfiles. This file should be
18080saved in place of the original visited file. The indirect subfiles are
18081written in the same directory the original file is in, with names generated
18082by appending @samp{-} and a number to the original file name.@refill
18083
18084The primary file still functions as an Info file, but it contains just
18085the tag table and a directory of subfiles.@refill
18086
18087
18088@node Refilling Paragraphs
18089@appendix Refilling Paragraphs
18090@cindex Refilling paragraphs
18091@cindex Filling paragraphs
18092@cindex Paragraphs, filling
18093@findex refill
18094
18095The @code{@@refill} command refills and, optionally, indents the first
18096line of a paragraph.@footnote{Perhaps the command should have been
18097called the @code{@@refillandindent} command, but @code{@@refill} is
18098shorter and the name was chosen before indenting was possible.} The
18099@code{@@refill} command is no longer important, but we describe it here
18100because you once needed it. You will see it in many old Texinfo
18101files.@refill
18102
18103Without refilling, paragraphs containing long @@-constructs may look
18104bad after formatting because the formatter removes @@-commands and
18105shortens some lines more than others. In the past, neither the
18106@code{texinfo-format-region} command nor the
18107@code{texinfo-format-buffer} command refilled paragraphs
18108automatically. The @code{@@refill} command had to be written at the
18109end of every paragraph to cause these formatters to fill them. (Both
18110@TeX{} and @code{makeinfo} have always refilled paragraphs
18111automatically.) Now, all the Info formatters automatically fill and
18112indent those paragraphs that need to be filled and indented.@refill
18113
18114The @code{@@refill} command causes @code{texinfo-format-region} and
18115@code{texinfo-format-buffer} to refill a paragraph in the Info file
18116@emph{after} all the other processing has been done. For this reason,
18117you can not use @code{@@refill} with a paragraph containing either
18118@code{@@*} or @code{@@w@{ @dots{} @}} since the refilling action will
18119override those two commands.@refill
18120
18121The @code{texinfo-format-region} and @code{texinfo-format-buffer}
18122commands now automatically append @code{@@refill} to the end of each
18123paragraph that should be filled. They do not append @code{@@refill} to
18124the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}}
18125and therefore do not refill or indent them.@refill
18126
18127
18128@node Command Syntax
18129@appendix @@-Command Syntax
18130@cindex @@-command syntax
18131@cindex Syntax, of @@-commands
18132@cindex Command syntax
18133
18134The character @samp{@@} is used to start special Texinfo commands.
18135(It has the same meaning that @samp{\} has in plain @TeX{}.) Texinfo
18136has four types of @@-command:@refill
18137
18138@table @asis
18139@item 1. Non-alphabetic commands.
18140These commands consist of an @@ followed by a punctuation mark or other
18141character that is not part of the alphabet. Non-alphabetic commands are
18142almost always part of the text within a paragraph, and never take any
18143argument. The two characters (@@ and the other one) are complete in
18144themselves; none is followed by braces. The non-alphabetic commands
18145are: @code{@@.}, @code{@@:}, @code{@@*}, @code{@@@kbd{SPACE}},
18146@code{@@@kbd{TAB}}, @code{@@@kbd{NL}}, @code{@@@@}, @code{@@@{}, and
18147@code{@@@}}.@refill
18148
18149@item 2. Alphabetic commands that do not require arguments.
18150These commands start with @@ followed by a word followed by left- and
18151right-hand braces. These commands insert special symbols in the
18152document; they do not require arguments. For example,
18153@code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}}
18154@result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}',
18155and @code{@@bullet@{@}} @result{} @samp{@bullet{}}.@refill
18156
18157@item 3. Alphabetic commands that require arguments within braces.
18158These commands start with @@ followed by a letter or a word, followed by an
18159argument within braces. For example, the command @code{@@dfn} indicates
18160the introductory or defining use of a term; it is used as follows: @samp{In
18161Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.}@refill
18162
18163@item 4. Alphabetic commands that occupy an entire line.
18164These commands occupy an entire line. The line starts with @@,
18165followed by the name of the command (a word); for example, @code{@@center}
18166or @code{@@cindex}. If no argument is needed, the word is followed by
18167the end of the line. If there is an argument, it is separated from
18168the command name by a space. Braces are not used.@refill
18169@end table
18170
18171@cindex Braces and argument syntax
18172Thus, the alphabetic commands fall into classes that have
18173different argument syntaxes. You cannot tell to which class a command
18174belongs by the appearance of its name, but you can tell by the
18175command's meaning: if the command stands for a glyph, it is in
18176class 2 and does not require an argument; if it makes sense to use the
18177command together with other text as part of a paragraph, the command
18178is in class 3 and must be followed by an argument in braces;
18179otherwise, it is in class 4 and uses the rest of the line as its
18180argument.@refill
18181
18182The purpose of having a different syntax for commands of classes 3 and
181834 is to make Texinfo files easier to read, and also to help the GNU
18184Emacs paragraph and filling commands work properly. There is only one
18185exception to this rule: the command @code{@@refill}, which is always
18186used at the end of a paragraph immediately following the final period
18187or other punctuation character. @code{@@refill} takes no argument and
18188does @emph{not} require braces. @code{@@refill} never confuses the
18189Emacs paragraph commands because it cannot appear at the beginning of
18190a line.@refill
18191
18192
18193@node Obtaining TeX
18194@appendix How to Obtain @TeX{}
18195@cindex Obtaining @TeX{}
18196@cindex @TeX{}, how to obtain
18197
18198@c !!! Here is information about obtaining TeX. Update it whenever.
18199@c !!! Also consider updating TeX.README on ftp.gnu.org.
18200@c Updated by RJC on 1 March 1995, conversation with MacKay.
18201@c Updated by kb@cs.umb.edu on 29 July 1996.
18202@c Updated by kb@cs.umb.edu on 25 April 1997.
18203@c Updated by kb@cs.umb.edu on 27 February 1998.
18204@TeX{} is freely redistributable. You can obtain @TeX{} for Unix
18205systems via anonymous ftp or on physical media. The core material
18206consists of the Web2c @TeX{} distribution (@uref{http://tug.org/web2c}).
18207
18208Instructions for retrieval by anonymous ftp and information on other
18209available distributions:
18210@example
18211@uref{ftp://tug.org/tex/unixtex.ftp}
18212@uref{http://tug.org/unixtex.ftp}
18213@end example
18214
18215The Free Software Foundation provides a core distribution on its Source
18216Code CD-ROM suitable for printing Texinfo manuals. To order it, contact:
18217
18218@display
18219@group
18220Free Software Foundation, Inc.
1822159 Temple Place Suite 330
18222Boston, MA @ @ 02111-1307
18223USA
18224Telephone: @w{+1-617-542-5942}
18225Fax: (including Japan) @w{+1-617-542-2652}
18226Free Dial Fax (in Japan):
18227@w{ } @w{ } @w{ } 0031-13-2473 (KDD)
18228@w{ } @w{ } @w{ } 0066-3382-0158 (IDC)
18229Electronic mail: @code{gnu@@gnu.org}
18230@end group
18231@end display
18232
18233Many other @TeX{} distributions are available; see
18234@uref{http://tug.org/}.
18235
18236
18237@c These are no longer ``new'', and the explanations
18238@c are all given elsewhere anyway, I think. --karl, 25apr97.
18239@c So ignore the entire appendix.
18240@ignore
18241@c node New Features, Command and Variable Index, Obtaining TeX, Top
18242@c appendix Second Edition Features
18243
18244@tex
18245% Widen the space for the first column so three control-character
18246% strings fit in the first column. Switched back to default .8in
18247% value at end of chapter.
18248\global\tableindent=1.0in
18249@end tex
18250
18251The second edition of the Texinfo manual describes more than 20 new
18252Texinfo mode commands and more than 50 previously undocumented Texinfo
18253@@-commands. This edition is more than twice the length of the first
18254edition.@refill
18255
18256Here is a brief description of the new commands.@refill
18257
18258@c menu
18259* New Texinfo Mode Commands:: The updating commands are especially useful.
18260* New Commands:: Many newly described @@-commands.
18261@c end menu
18262
18263@c node New Texinfo Mode Commands, New Commands, Obtaining TeX, Obtaining TeX
18264@c appendixsec New Texinfo Mode Commands
18265
18266Texinfo mode provides commands and features especially designed for
18267working with Texinfo files. More than 20 new commands have been
18268added, including commands for automatically creating and updating
18269both nodes and menus. This is a tedious task when done by hand.@refill
18270
18271The keybindings are intended to be somewhat mnemonic.@refill
18272
18273@c subheading Update all nodes and menus
18274
18275The @code{texinfo-master-menu} command is the primary command:
18276
18277@table @kbd
18278@item C-c C-u m
18279@itemx M-x texinfo-master-menu
18280Create or update a master menu.
18281With @kbd{C-u} as a prefix argument,
18282first create or update all nodes
18283and regular menus.
18284@end table
18285
18286@c subheading Update Pointers
18287
18288@noindent
18289Create or update `Next', `Previous', and `Up' node pointers.@refill
18290
18291@noindent
18292@xref{Updating Nodes and Menus}.
18293
18294@table @kbd
18295@item C-c C-u C-n
18296@itemx M-x texinfo-update-node
18297Update a node.
18298
18299@item C-c C-u C-e
18300@itemx M-x texinfo-every-node-update
18301Update every node in the buffer.
18302@end table
18303
18304@c subheading Update Menus
18305
18306@noindent
18307Create or update menus.@refill
18308
18309@noindent
18310@xref{Updating Nodes and Menus}.
18311
18312@table @kbd
18313@item C-c C-u C-m
18314@itemx M-x texinfo-make-menu
18315Make or update a menu.
18316
18317@item C-c C-u C-a
18318@itemx M-x texinfo-all-menus-update
18319Make or update all the menus in a buffer.
18320With @kbd{C-u} as a prefix argument,
18321first update all the nodes.
18322@end table
18323
18324@c subheading Insert Title as Description
18325
18326@noindent
18327Insert a node's chapter or section title in the space for the
18328description in a menu entry line; position point so you can edit the
18329insert. (This command works somewhat differently than the other
18330insertion commands, which insert only a predefined string.)@refill
18331
18332@noindent
18333@xref{Inserting, Inserting Frequently Used Commands}.
18334
18335@table @kbd
18336@item C-c C-c C-d
18337Insert title.
18338@end table
18339
18340@c subheading Format for Info
18341
18342@noindent
18343Provide keybindings both for the Info formatting commands that are
18344written in Emacs Lisp and for @code{makeinfo} that is written in
18345C.@refill
18346
18347@noindent
18348@xref{Info Formatting}.
18349
18350@noindent
18351Use the Emacs lisp @code{texinfo-format@dots{}} commands:
18352
18353@table @kbd
18354@item C-c C-e C-r
18355Format the region.
18356
18357@item C-c C-e C-b
18358Format the buffer.
18359@end table
18360
18361@noindent
18362Use @code{makeinfo}:
18363
18364@table @kbd
18365@item C-c C-m C-r
18366Format the region.
18367
18368@item C-c C-m C-b
18369Format the buffer.
18370
18371@item C-c C-m C-l
18372Recenter the @code{makeinfo} output buffer.
18373
18374@item C-c C-m C-k
18375Kill the @code{makeinfo} formatting job.
18376@end table
18377
18378@c subheading Typeset and Print
18379
18380@noindent
18381Typeset and print Texinfo documents from within Emacs.@refill
18382
18383@ifinfo
18384@noindent
18385@xref{Printing}.
18386@end ifinfo
18387@iftex
18388@noindent
18389@xref{Printing, , Formatting and Printing}.
18390@end iftex
18391
18392@table @kbd
18393@item C-c C-t C-b
18394Run @code{texi2dvi} on the buffer.
18395
18396@item C-c C-t C-r
18397Run @TeX{} on the region.
18398
18399@item C-c C-t C-i
18400Run @code{texindex}.
18401
18402@item C-c C-t C-p
18403Print the DVI file.
18404
18405@item C-c C-t C-q
18406Show the print queue.
18407
18408@item C-c C-t C-d
18409Delete a job from the print queue.
18410
18411@item C-c C-t C-k
18412Kill the current @TeX{} formatting job.
18413
18414@item C-c C-t C-x
18415Quit a currently stopped @TeX{} formatting job.
18416
18417@item C-c C-t C-l
18418Recenter the output buffer.
18419@end table
18420
18421@c subheading Other Updating Commands
18422
18423@noindent
18424The ``other updating commands'' do not have standard keybindings because
18425they are used less frequently.@refill
18426
18427@noindent
18428@xref{Other Updating Commands}.
18429
18430@table @kbd
18431@item M-x texinfo-insert-node-lines
18432Insert missing @code{@@node} lines using
18433section titles as node names.
18434
18435@item M-x texinfo-multiple-files-update
18436Update a multi-file document.
18437With a numeric prefix, such as @kbd{C-u 8},
18438update @strong{every} pointer and
18439menu in @strong{all} the files and
18440then insert a master menu.
18441
18442@item M-x texinfo-indent-menu-description
18443Indent descriptions in menus.
18444
18445@item M-x texinfo-sequential-node-update
18446Insert node pointers in strict sequence.
18447@end table
18448
18449@c no.de New Commands, , New Texinfo Mode Commands, Obtaining TeX
18450@c appendix.sec New Texinfo @@-Commands
18451
18452The second edition of the Texinfo manual describes more than 50
18453commands that were not described in the first edition. A third or so
18454of these commands existed in Texinfo but were not documented in the
18455manual; the others are new. Here is a listing, with brief
18456descriptions of them:@refill
18457
18458@c subheading Indexing
18459
18460@noindent
18461Create your own index, and merge indices.@refill
18462
18463@noindent
18464@xref{Indices}.
18465
18466@table @kbd
18467@item @@defindex @var{index-name}
18468Define a new index and its indexing command.
18469See also the @code{@@defcodeindex} command.
18470
18471@c written verbosely to avoid overfull hbox
18472@item @@synindex @var{from-index} @var{into-index}
18473Merge the @var{from-index} index into the @var{into-index} index.
18474See also the @code{@@syncodeindex} command.
18475@end table
18476
18477@c subheading Definitions
18478
18479@noindent
18480Describe functions, variables, macros,
18481commands, user options, special forms, and other such artifacts in a
18482uniform format.@refill
18483
18484@noindent
18485@xref{Definition Commands}.
18486
18487@table @kbd
18488@item @@deffn @var{category} @var{name} @var{arguments}@dots{}
18489Format a description for functions, interactive
18490commands, and similar entities.
18491
18492@item @@defvr, @@defop, @dots{}
1849315 other related commands.
18494@end table
18495
18496@c subheading Glyphs
18497
18498@noindent
18499Indicate the results of evaluation, expansion,
18500printed output, an error message, equivalence of expressions, and the
18501location of point.@refill
18502
18503@noindent
18504@xref{Glyphs}.
18505
18506@table @kbd
18507@item @@equiv@{@}
18508@itemx @equiv{}
18509Equivalence:
18510
18511@item @@error@{@}
18512@itemx @error{}
18513Error message
18514
18515@item @@expansion@{@}
18516@itemx @expansion{}
18517Macro expansion
18518
18519@item @@point@{@}
18520@itemx @point{}
18521Position of point
18522
18523@item @@print@{@}
18524@itemx @print{}
18525Printed output
18526
18527@item @@result@{@}
18528@itemx @result{}
18529Result of an expression
18530@end table
18531
18532@c subheading Page Headings
18533
18534@noindent
18535Customize page headings.
18536
18537@noindent
18538@xref{Headings}.
18539
18540@table @kbd
18541@item @@headings @var{on-off-single-double}
18542Headings on or off, single, or double-sided.
18543
18544@item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
18545Footings for even-numbered (left-hand) pages.
18546
18547@item @@evenheading, @@everyheading, @@oddheading, @dots{}
18548Five other related commands.
18549
18550@item @@thischapter
18551Insert name of chapter and chapter number.
18552
18553@item @@thischaptername, @@thisfile, @@thistitle, @@thispage
18554Related commands.
18555@end table
18556
18557@c subheading Formatting
18558
18559@noindent
18560Format blocks of text.
18561
18562@noindent
18563@xref{Quotations and Examples}, and@*
18564@ref{Lists and Tables, , Making Lists and Tables}.
18565
18566@table @kbd
18567@item @@cartouche
18568Draw rounded box surrounding text (not in Info).
18569
18570@item @@enumerate @var{optional-arg}
18571Enumerate a list with letters or numbers.
18572
18573@item @@exdent @var{line-of-text}
18574Remove indentation.
18575
18576@item @@flushleft
18577Left justify.
18578
18579@item @@flushright
18580Right justify.
18581
18582@item @@format
18583Do not narrow nor change font.
18584
18585@item @@ftable @var{formatting-command}
18586@itemx @@vtable @var{formatting-command}
18587Two-column table with indexing.
18588
18589@item @@lisp
18590For an example of Lisp code.
18591
18592@item @@smallexample
18593@itemx @@smalllisp
18594Like @@table and @@lisp @r{but for} @@smallbook.
18595@end table
18596
18597@c subheading Conditionals
18598
18599@noindent
18600Conditionally format text.
18601
18602@noindent
18603@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
18604
18605@table @kbd
18606@item @@set @var{flag} [@var{string}]
18607Set a flag. Optionally, set value
18608of @var{flag} to @var{string}.
18609
18610@item @@clear @var{flag}
18611Clear a flag.
18612
18613@item @@value@{@var{flag}@}
18614Replace with value to which @var{flag} is set.
18615
18616@item @@ifset @var{flag}
18617Format, if @var{flag} is set.
18618
18619@item @@ifclear @var{flag}
18620Ignore, if @var{flag} is set.
18621@end table
18622
18623@c subheading @@heading series for Titles
18624
18625@noindent
18626Produce unnumbered headings that do not appear in a table of contents.
18627
18628@noindent
18629@xref{Structuring}.
18630
18631@table @kbd
18632@item @@heading @var{title}
18633Unnumbered section-like heading not listed
18634in the table of contents of a printed manual.
18635
18636@item @@chapheading, @@majorheading, @@c subheading, @@subsubheading
18637Related commands.
18638@end table
18639
18640@need 1000
18641@c subheading Font commands
18642
18643@need 1000
18644@noindent
18645@xref{Smallcaps}, and @*
18646@ref{Fonts}.
18647
18648@table @kbd
18649@item @@r@{@var{text}@}
18650Print in roman font.
18651
18652@item @@sc@{@var{text}@}
18653Print in @sc{small caps} font.
18654@end table
18655
18656@c subheading Miscellaneous
18657
18658@noindent
18659See @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author} Commands},@*
18660see @ref{Customized Highlighting},@*
18661see @ref{Overfull hboxes},@*
18662see @ref{Footnotes},@*
18663see @ref{dmn, , Format a Dimension},@*
18664see @ref{Raise/lower sections, , @code{@@raisesections} and @code{@@lowersections}},@*
18665see @ref{math, , @code{@@math}: Inserting Mathematical Expressions}.@*
18666see @ref{minus, , Inserting a Minus Sign},@*
18667see @ref{paragraphindent, , Paragraph Indenting},@*
18668see @ref{Cross Reference Commands},@*
18669see @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author}}, and@*
18670see @ref{Custom Headings, , How to Make Your Own Headings}.
18671
18672@table @kbd
18673@item @@author @var{author}
18674Typeset author's name.
18675
18676@c @item @@definfoenclose @var{new-command}, @var{before}, @var{after},
18677@c Define a highlighting command for Info. (Info only.)
18678
18679@item @@finalout
18680Produce cleaner printed output.
18681
18682@item @@footnotestyle @var{end-or-separate}
18683Specify footnote style.
18684
18685@item @@dmn@{@var{dimension}@}
18686Format a dimension.
18687
18688@item @@global@@let@var{new-cmd}=@var{existing-cmd}
18689Define a highlighting command for @TeX{}. (@TeX{} only.)
18690
18691@item @@lowersections
18692Reduce hierarchical level of sectioning commands.
18693
18694@item @@math@{@var{mathematical-expression}@}
18695Format a mathematical expression.
18696
18697@item @@minus@{@}
18698Generate a minus sign.
18699
18700@item @@paragraphindent @var{asis-or-number}
18701Specify paragraph indentation.
18702
18703@item @@raisesections
18704Raise hierarchical level of sectioning commands.
18705
18706@item @@ref@{@var{node-name}, @r{[}@var{entry}@r{]}, @r{[}@var{topic-or-title}@r{]}, @r{[}@var{info-file}@r{]}, @r{[}@var{manual}@r{]}@}
18707Make a reference. In the printed manual, the
18708reference does not start with the word `see'.
18709
18710@item @@title @var{title}
18711Typeset @var{title} in the alternative
18712title page format.
18713
18714@item @@subtitle @var{subtitle}
18715Typeset @var{subtitle} in the alternative
18716title page format.
18717
18718@item @@today@{@}
18719Insert the current date.
18720@end table
18721@tex
18722% Switch width of first column of tables back to default value
18723\global\tableindent=.8in
18724@end tex
18725@end ignore
18726
18727
|
18455@node Documentation Copying
18456@appendix GNU Free Documentation License
| 18728@node Copying This Manual
18729@appendix Copying This Manual
|
18457
| 18730
|
18458@cindex FDL, GNU Free Documentation License
18459@center Version 1.1, March 2000
| 18731@menu
18732* GNU Free Documentation License:: License for copying this manual.
18733@end menu
|
18460
| 18734
|
18461@display
18462Copyright @copyright{} 2000 Free Software Foundation, Inc.
1846359 Temple Place, Suite 330, Boston, MA 02111-1307, USA
| 18735@include fdl.texi
|
18464
| 18736
|
18465Everyone is permitted to copy and distribute verbatim copies
18466of this license document, but changing it is not allowed.
18467@end display
| |
18468
| 18737
|
18469@enumerate 0
18470@item
18471PREAMBLE
18472
18473The purpose of this License is to make a manual, textbook, or other
18474written document @dfn{free} in the sense of freedom: to assure everyone
18475the effective freedom to copy and redistribute it, with or without
18476modifying it, either commercially or noncommercially. Secondarily,
18477this License preserves for the author and publisher a way to get
18478credit for their work, while not being considered responsible for
18479modifications made by others.
18480
18481This License is a kind of ``copyleft'', which means that derivative
18482works of the document must themselves be free in the same sense. It
18483complements the GNU General Public License, which is a copyleft
18484license designed for free software.
18485
18486We have designed this License in order to use it for manuals for free
18487software, because free software needs free documentation: a free
18488program should come with manuals providing the same freedoms that the
18489software does. But this License is not limited to software manuals;
18490it can be used for any textual work, regardless of subject matter or
18491whether it is published as a printed book. We recommend this License
18492principally for works whose purpose is instruction or reference.
18493
18494@item
18495APPLICABILITY AND DEFINITIONS
18496
18497This License applies to any manual or other work that contains a
18498notice placed by the copyright holder saying it can be distributed
18499under the terms of this License. The ``Document'', below, refers to any
18500such manual or work. Any member of the public is a licensee, and is
18501addressed as ``you''.
18502
18503A ``Modified Version'' of the Document means any work containing the
18504Document or a portion of it, either copied verbatim, or with
18505modifications and/or translated into another language.
18506
18507A ``Secondary Section'' is a named appendix or a front-matter section of
18508the Document that deals exclusively with the relationship of the
18509publishers or authors of the Document to the Document's overall subject
18510(or to related matters) and contains nothing that could fall directly
18511within that overall subject. (For example, if the Document is in part a
18512textbook of mathematics, a Secondary Section may not explain any
18513mathematics.) The relationship could be a matter of historical
18514connection with the subject or with related matters, or of legal,
18515commercial, philosophical, ethical or political position regarding
18516them.
18517
18518The ``Invariant Sections'' are certain Secondary Sections whose titles
18519are designated, as being those of Invariant Sections, in the notice
18520that says that the Document is released under this License.
18521
18522The ``Cover Texts'' are certain short passages of text that are listed,
18523as Front-Cover Texts or Back-Cover Texts, in the notice that says that
18524the Document is released under this License.
18525
18526A ``Transparent'' copy of the Document means a machine-readable copy,
18527represented in a format whose specification is available to the
18528general public, whose contents can be viewed and edited directly and
18529straightforwardly with generic text editors or (for images composed of
18530pixels) generic paint programs or (for drawings) some widely available
18531drawing editor, and that is suitable for input to text formatters or
18532for automatic translation to a variety of formats suitable for input
18533to text formatters. A copy made in an otherwise Transparent file
18534format whose markup has been designed to thwart or discourage
18535subsequent modification by readers is not Transparent. A copy that is
18536not ``Transparent'' is called ``Opaque''.
18537
18538Examples of suitable formats for Transparent copies include plain
18539@sc{ascii} without markup, Texinfo input format, La@TeX{} input format,
18540@acronym{SGML} or @acronym{XML} using a publicly available
18541@acronym{DTD}, and standard-conforming simple @acronym{HTML} designed
18542for human modification. Opaque formats include PostScript,
18543@acronym{PDF}, proprietary formats that can be read and edited only by
18544proprietary word processors, @acronym{SGML} or @acronym{XML} for which
18545the @acronym{DTD} and/or processing tools are not generally available,
18546and the machine-generated @acronym{HTML} produced by some word
18547processors for output purposes only.
18548
18549The ``Title Page'' means, for a printed book, the title page itself,
18550plus such following pages as are needed to hold, legibly, the material
18551this License requires to appear in the title page. For works in
18552formats which do not have any title page as such, ``Title Page'' means
18553the text near the most prominent appearance of the work's title,
18554preceding the beginning of the body of the text.
18555
18556@item
18557VERBATIM COPYING
18558
18559You may copy and distribute the Document in any medium, either
18560commercially or noncommercially, provided that this License, the
18561copyright notices, and the license notice saying this License applies
18562to the Document are reproduced in all copies, and that you add no other
18563conditions whatsoever to those of this License. You may not use
18564technical measures to obstruct or control the reading or further
18565copying of the copies you make or distribute. However, you may accept
18566compensation in exchange for copies. If you distribute a large enough
18567number of copies you must also follow the conditions in section 3.
18568
18569You may also lend copies, under the same conditions stated above, and
18570you may publicly display copies.
18571
18572@item
18573COPYING IN QUANTITY
18574
18575If you publish printed copies of the Document numbering more than 100,
18576and the Document's license notice requires Cover Texts, you must enclose
18577the copies in covers that carry, clearly and legibly, all these Cover
18578Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
18579the back cover. Both covers must also clearly and legibly identify
18580you as the publisher of these copies. The front cover must present
18581the full title with all words of the title equally prominent and
18582visible. You may add other material on the covers in addition.
18583Copying with changes limited to the covers, as long as they preserve
18584the title of the Document and satisfy these conditions, can be treated
18585as verbatim copying in other respects.
18586
18587If the required texts for either cover are too voluminous to fit
18588legibly, you should put the first ones listed (as many as fit
18589reasonably) on the actual cover, and continue the rest onto adjacent
18590pages.
18591
18592If you publish or distribute Opaque copies of the Document numbering
18593more than 100, you must either include a machine-readable Transparent
18594copy along with each Opaque copy, or state in or with each Opaque copy
18595a publicly-accessible computer-network location containing a complete
18596Transparent copy of the Document, free of added material, which the
18597general network-using public has access to download anonymously at no
18598charge using public-standard network protocols. If you use the latter
18599option, you must take reasonably prudent steps, when you begin
18600distribution of Opaque copies in quantity, to ensure that this
18601Transparent copy will remain thus accessible at the stated location
18602until at least one year after the last time you distribute an Opaque
18603copy (directly or through your agents or retailers) of that edition to
18604the public.
18605
18606It is requested, but not required, that you contact the authors of the
18607Document well before redistributing any large number of copies, to give
18608them a chance to provide you with an updated version of the Document.
18609
18610@item
18611MODIFICATIONS
18612
18613You may copy and distribute a Modified Version of the Document under
18614the conditions of sections 2 and 3 above, provided that you release
18615the Modified Version under precisely this License, with the Modified
18616Version filling the role of the Document, thus licensing distribution
18617and modification of the Modified Version to whoever possesses a copy
18618of it. In addition, you must do these things in the Modified Version:
18619
18620@enumerate A
18621@item
18622Use in the Title Page (and on the covers, if any) a title distinct
18623from that of the Document, and from those of previous versions
18624(which should, if there were any, be listed in the History section
18625of the Document). You may use the same title as a previous version
18626if the original publisher of that version gives permission.
18627
18628@item
18629List on the Title Page, as authors, one or more persons or entities
18630responsible for authorship of the modifications in the Modified
18631Version, together with at least five of the principal authors of the
18632Document (all of its principal authors, if it has less than five).
18633
18634@item
18635State on the Title page the name of the publisher of the
18636Modified Version, as the publisher.
18637
18638@item
18639Preserve all the copyright notices of the Document.
18640
18641@item
18642Add an appropriate copyright notice for your modifications
18643adjacent to the other copyright notices.
18644
18645@item
18646Include, immediately after the copyright notices, a license notice
18647giving the public permission to use the Modified Version under the
18648terms of this License, in the form shown in the Addendum below.
18649
18650@item
18651Preserve in that license notice the full lists of Invariant Sections
18652and required Cover Texts given in the Document's license notice.
18653
18654@item
18655Include an unaltered copy of this License.
18656
18657@item
18658Preserve the section entitled ``History'', and its title, and add to
18659it an item stating at least the title, year, new authors, and
18660publisher of the Modified Version as given on the Title Page. If
18661there is no section entitled ``History'' in the Document, create one
18662stating the title, year, authors, and publisher of the Document as
18663given on its Title Page, then add an item describing the Modified
18664Version as stated in the previous sentence.
18665
18666@item
18667Preserve the network location, if any, given in the Document for
18668public access to a Transparent copy of the Document, and likewise
18669the network locations given in the Document for previous versions
18670it was based on. These may be placed in the ``History'' section.
18671You may omit a network location for a work that was published at
18672least four years before the Document itself, or if the original
18673publisher of the version it refers to gives permission.
18674
18675@item
18676In any section entitled ``Acknowledgments'' or ``Dedications'',
18677preserve the section's title, and preserve in the section all the
18678substance and tone of each of the contributor acknowledgments
18679and/or dedications given therein.
18680
18681@item
18682Preserve all the Invariant Sections of the Document,
18683unaltered in their text and in their titles. Section numbers
18684or the equivalent are not considered part of the section titles.
18685
18686@item
18687Delete any section entitled ``Endorsements''. Such a section
18688may not be included in the Modified Version.
18689
18690@item
18691Do not retitle any existing section as ``Endorsements''
18692or to conflict in title with any Invariant Section.
18693@end enumerate
18694
18695If the Modified Version includes new front-matter sections or
18696appendices that qualify as Secondary Sections and contain no material
18697copied from the Document, you may at your option designate some or all
18698of these sections as invariant. To do this, add their titles to the
18699list of Invariant Sections in the Modified Version's license notice.
18700These titles must be distinct from any other section titles.
18701
18702You may add a section entitled ``Endorsements'', provided it contains
18703nothing but endorsements of your Modified Version by various
18704parties---for example, statements of peer review or that the text has
18705been approved by an organization as the authoritative definition of a
18706standard.
18707
18708You may add a passage of up to five words as a Front-Cover Text, and a
18709passage of up to 25 words as a Back-Cover Text, to the end of the list
18710of Cover Texts in the Modified Version. Only one passage of
18711Front-Cover Text and one of Back-Cover Text may be added by (or
18712through arrangements made by) any one entity. If the Document already
18713includes a cover text for the same cover, previously added by you or
18714by arrangement made by the same entity you are acting on behalf of,
18715you may not add another; but you may replace the old one, on explicit
18716permission from the previous publisher that added the old one.
18717
18718The author(s) and publisher(s) of the Document do not by this License
18719give permission to use their names for publicity for or to assert or
18720imply endorsement of any Modified Version.
18721
18722@item
18723COMBINING DOCUMENTS
18724
18725You may combine the Document with other documents released under this
18726License, under the terms defined in section 4 above for modified
18727versions, provided that you include in the combination all of the
18728Invariant Sections of all of the original documents, unmodified, and
18729list them all as Invariant Sections of your combined work in its
18730license notice.
18731
18732The combined work need only contain one copy of this License, and
18733multiple identical Invariant Sections may be replaced with a single
18734copy. If there are multiple Invariant Sections with the same name but
18735different contents, make the title of each such section unique by
18736adding at the end of it, in parentheses, the name of the original
18737author or publisher of that section if known, or else a unique number.
18738Make the same adjustment to the section titles in the list of
18739Invariant Sections in the license notice of the combined work.
18740
18741In the combination, you must combine any sections entitled ``History''
18742in the various original documents, forming one section entitled
18743``History''; likewise combine any sections entitled ``Acknowledgments'',
18744and any sections entitled ``Dedications''. You must delete all sections
18745entitled ``Endorsements.''
18746
18747@item
18748COLLECTIONS OF DOCUMENTS
18749
18750You may make a collection consisting of the Document and other documents
18751released under this License, and replace the individual copies of this
18752License in the various documents with a single copy that is included in
18753the collection, provided that you follow the rules of this License for
18754verbatim copying of each of the documents in all other respects.
18755
18756You may extract a single document from such a collection, and distribute
18757it individually under this License, provided you insert a copy of this
18758License into the extracted document, and follow this License in all
18759other respects regarding verbatim copying of that document.
18760
18761@item
18762AGGREGATION WITH INDEPENDENT WORKS
18763
18764A compilation of the Document or its derivatives with other separate
18765and independent documents or works, in or on a volume of a storage or
18766distribution medium, does not as a whole count as a Modified Version
18767of the Document, provided no compilation copyright is claimed for the
18768compilation. Such a compilation is called an ``aggregate'', and this
18769License does not apply to the other self-contained works thus compiled
18770with the Document, on account of their being thus compiled, if they
18771are not themselves derivative works of the Document.
18772
18773If the Cover Text requirement of section 3 is applicable to these
18774copies of the Document, then if the Document is less than one quarter
18775of the entire aggregate, the Document's Cover Texts may be placed on
18776covers that surround only the Document within the aggregate.
18777Otherwise they must appear on covers around the whole aggregate.
18778
18779@item
18780TRANSLATION
18781
18782Translation is considered a kind of modification, so you may
18783distribute translations of the Document under the terms of section 4.
18784Replacing Invariant Sections with translations requires special
18785permission from their copyright holders, but you may include
18786translations of some or all Invariant Sections in addition to the
18787original versions of these Invariant Sections. You may include a
18788translation of this License provided that you also include the
18789original English version of this License. In case of a disagreement
18790between the translation and the original English version of this
18791License, the original English version will prevail.
18792
18793@item
18794TERMINATION
18795
18796You may not copy, modify, sublicense, or distribute the Document except
18797as expressly provided for under this License. Any other attempt to
18798copy, modify, sublicense or distribute the Document is void, and will
18799automatically terminate your rights under this License. However,
18800parties who have received copies, or rights, from you under this
18801License will not have their licenses terminated so long as such
18802parties remain in full compliance.
18803
18804@item
18805FUTURE REVISIONS OF THIS LICENSE
18806
18807The Free Software Foundation may publish new, revised versions
18808of the GNU Free Documentation License from time to time. Such new
18809versions will be similar in spirit to the present version, but may
18810differ in detail to address new problems or concerns. See
18811@uref{http://www.gnu.org/copyleft/}.
18812
18813Each version of the License is given a distinguishing version number.
18814If the Document specifies that a particular numbered version of this
18815License ``or any later version'' applies to it, you have the option of
18816following the terms and conditions either of that specified version or
18817of any later version that has been published (not as a draft) by the
18818Free Software Foundation. If the Document does not specify a version
18819number of this License, you may choose any version ever published (not
18820as a draft) by the Free Software Foundation.
18821@end enumerate
18822
18823@page
18824@appendixsubsec ADDENDUM: How to use this License for your documents
18825
18826To use this License in a document you have written, include a copy of
18827the License in the document and put the following copyright and
18828license notices just after the title page:
18829
18830@smallexample
18831@group
18832 Copyright (C) @var{year} @var{your name}.
18833 Permission is granted to copy, distribute and/or modify this document
18834 under the terms of the GNU Free Documentation License, Version 1.1
18835 or any later version published by the Free Software Foundation;
18836 with the Invariant Sections being @var{list their titles}, with the
18837 Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}.
18838 A copy of the license is included in the section entitled ``GNU
18839 Free Documentation License''.
18840@end group
18841@end smallexample
18842
18843If you have no Invariant Sections, write ``with no Invariant Sections''
18844instead of saying which ones are invariant. If you have no
18845Front-Cover Texts, write ``no Front-Cover Texts'' instead of
18846``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
18847
18848If your document contains nontrivial examples of program code, we
18849recommend releasing these examples in parallel under your choice of
18850free software license, such as the GNU General Public License,
18851to permit their use in free software.
18852
18853
| |
18854@node Command and Variable Index
18855@unnumbered Command and Variable Index
18856
18857This is an alphabetical list of all the @@-commands, assorted Emacs Lisp
18858functions, and several variables. To make the list easier to use, the
18859commands are listed without their preceding @samp{@@}.@refill
18860
18861@printindex fn
18862
18863
18864@node Concept Index
18865@unnumbered Concept Index
18866
18867@printindex cp
18868
18869
18870@bye
| 18738@node Command and Variable Index
18739@unnumbered Command and Variable Index
18740
18741This is an alphabetical list of all the @@-commands, assorted Emacs Lisp
18742functions, and several variables. To make the list easier to use, the
18743commands are listed without their preceding @samp{@@}.@refill
18744
18745@printindex fn
18746
18747
18748@node Concept Index
18749@unnumbered Concept Index
18750
18751@printindex cp
18752
18753
18754@bye
|