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
|