Mercurial > hg > xemacs-beta
comparison man/texinfo/texinfo.texi @ 5791:9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
pointers to all nodes. See xemacs-patches message with ID
<5315f7bf.sHpFD7lXYR05GH6E%james@xemacs.org>.
| author | Jerry James <james@xemacs.org> |
|---|---|
| date | Thu, 27 Mar 2014 08:59:03 -0600 |
| parents | d11efddf3617 |
| children |
comparison
equal
deleted
inserted
replaced
| 5790:dcf9067f26bb | 5791:9fae6227ede5 |
|---|---|
| 1 \input texinfo.tex @c -*-texinfo-*- | 1 \input texinfo.tex @c -*-texinfo-*- |
| 2 @c $Id: texinfo.txi,v 1.225 2008/09/07 22:47:46 karl Exp $ | 2 @c $Id: texinfo.texi 5381 2013-09-26 23:03:58Z karl $ |
| 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 | 3 |
| 6 @c Everything between the start/end of header lines will be passed by | 4 @c Everything between the start/end of header lines will be passed by |
| 7 @c XEmacs's {texinfo,makeinfo}-format region commands. See the `start of | 5 @c XEmacs's {texinfo,makeinfo}-format region commands. See the `start of |
| 8 @c header' node for more info. | 6 @c header' node for more info. |
| 9 @c %**start of header | 7 @c %**start of header |
| 10 @c Synced up with: Texinfo 4.13 of Sep 18, 2008. | 8 @c Synced up with: Texinfo 5.2 of 26 Sep 2013. |
| 11 @c Synced by: Ben Wing, 2-17-10. | 9 @c Synced by: Jerry James, 11 Feb 2014. |
| 12 | 10 |
| 13 @c makeinfo and texinfo.tex ignore all text before @setfilename. | 11 @c makeinfo and texinfo.tex ignore all text before @setfilename. |
| 14 @c | 12 @setfilename texinfo.info |
| 15 @c Ordinarily, the setfilename argument ends with .info. But | |
| 16 @c texinfo.info-13 is too long for 14-character filesystems. | |
| 17 @setfilename ../../info/texinfo.info | |
| 18 | 13 |
| 19 @c Automake automatically updates version.texi to @set VERSION and | 14 @c Automake automatically updates version.texi to @set VERSION and |
| 20 @c @set UPDATED to appropriate values. | 15 @c @set UPDATED to appropriate values. |
| 21 @include version.texi | 16 @include version.texi |
| 22 @c XEmacs: @settitle Texinfo @value{edition} | 17 @c XEmacs: @settitle Texinfo @value{edition} |
| 23 @settitle GNU Texinfo @value{VERSION} | 18 @settitle GNU Texinfo @value{VERSION} |
| 24 | 19 |
| 25 @c Define a new index for options. | 20 @c Define a new index for command-line options. |
| 26 @defcodeindex op | 21 @defcodeindex op |
| 22 | |
| 27 @c Put everything except function (command, in this case) names in one | 23 @c Put everything except function (command, in this case) names in one |
| 28 @c index (arbitrarily chosen to be the concept index). | 24 @c index (arbitrarily chosen to be the concept index). |
| 29 @syncodeindex op cp | 25 @syncodeindex op cp |
| 30 @syncodeindex vr cp | 26 @syncodeindex vr cp |
| 31 @syncodeindex pg cp | 27 @syncodeindex pg cp |
| 36 @comment %**end of header | 32 @comment %**end of header |
| 37 | 33 |
| 38 @copying | 34 @copying |
| 39 This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}), | 35 This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}), |
| 40 a documentation system that can produce both online information and a | 36 a documentation system that can produce both online information and a |
| 41 printed manual from a single source. | 37 printed manual from a single source using semantic markup. |
| 42 | 38 |
| 43 Copyright @copyright{} 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997, | 39 Copyright @copyright{} 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997, |
| 44 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 | 40 1998, 1999, 2001, 2001, 2003, 2004, 2005, 2006, 2007, 2008, 2009, |
| 45 Free Software Foundation, Inc. | 41 2010, 2011, 2012, 2013 Free Software Foundation, Inc. |
| 46 | 42 |
| 47 @quotation | 43 @quotation |
| 48 Permission is granted to copy, distribute and/or modify this document | 44 Permission is granted to copy, distribute and/or modify this document |
| 49 under the terms of the GNU Free Documentation License, Version 1.2 or | 45 under the terms of the GNU Free Documentation License, Version 1.3 or |
| 50 any later version published by the Free Software Foundation; with no | 46 any later version published by the Free Software Foundation; with no |
| 51 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', | 47 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', |
| 52 and with the Back-Cover Texts as in (a) below. A copy of the license | 48 and with the Back-Cover Texts as in (a) below. A copy of the license |
| 53 is included in the section entitled ``GNU Free Documentation | 49 is included in the section entitled ``GNU Free Documentation |
| 54 License.'' | 50 License''. |
| 55 | 51 |
| 56 (a) The FSF's Back-Cover Text is: ``You are free to copy and modify | 52 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and |
| 57 this GNU Manual. Buying copies from GNU Press supports the FSF in | 53 modify this GNU manual. Buying copies from the FSF supports it in |
| 58 developing GNU and promoting software freedom.'' | 54 developing GNU and promoting software freedom.'' |
| 59 @end quotation | 55 @end quotation |
| 60 @end copying | 56 @end copying |
| 61 | 57 |
| 62 @dircategory Texinfo documentation system | 58 @dircategory Texinfo documentation system |
| 63 @direntry | 59 @direntry |
| 64 * Texinfo: (texinfo). The GNU documentation format. | 60 * Texinfo: (texinfo). The GNU documentation format. |
| 65 * install-info: (texinfo)Invoking install-info. Update info/dir entries. | 61 * install-info: (texinfo)Invoking install-info. Update info/dir entries. |
| 62 * makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source. | |
| 63 * pod2texi: (pod2texi)Invoking pod2texi. Translate Perl POD to Texinfo. | |
| 66 * texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents. | 64 * texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents. |
| 67 * texi2pdf: (texinfo)PDF Output. PDF output for Texinfo. | 65 * texi2pdf: (texinfo)PDF Output. PDF output for Texinfo. |
| 68 * pdftexi2dvi: (texinfo)PDF Output. PDF output for Texinfo. | 66 * pdftexi2dvi: (texinfo)PDF Output. PDF output for Texinfo. |
| 69 * texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files. | 67 * texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files. |
| 70 * makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source. | |
| 71 @end direntry | 68 @end direntry |
| 72 | 69 |
| 73 @c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a | 70 @c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a |
| 74 @c prefix arg). This updates the node pointers, which texinfmt.el needs. | 71 @c prefix arg). This updates the node pointers, which texinfmt.el needs. |
| 75 | 72 |
| 81 @c set smallbook | 78 @c set smallbook |
| 82 @c @@clear smallbook | 79 @c @@clear smallbook |
| 83 | 80 |
| 84 @c If you like blank pages, add through texi2dvi -t. | 81 @c If you like blank pages, add through texi2dvi -t. |
| 85 @c setchapternewpage odd | 82 @c setchapternewpage odd |
| 86 | |
| 87 @c Currently undocumented command, 5 December 1993: | |
| 88 @c nwnode (Same as node, but no warnings; for `makeinfo'.) | |
| 89 | 83 |
| 90 | 84 |
| 91 @shorttitlepage GNU Texinfo | 85 @shorttitlepage GNU Texinfo |
| 92 | 86 |
| 93 @titlepage | 87 @titlepage |
| 128 @node Top | 122 @node Top |
| 129 @top Texinfo | 123 @top Texinfo |
| 130 | 124 |
| 131 This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}), | 125 This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}), |
| 132 a documentation system that can produce both online information and a | 126 a documentation system that can produce both online information and a |
| 133 printed manual from a single source. | 127 printed manual from a single source using semantic markup. |
| 134 | 128 |
| 135 The first part of this master menu lists the major nodes in this Info | 129 The first part of this master menu lists the major nodes in this Info |
| 136 document, including the @@-command and concept indices. The rest of | 130 document, including the @@-command and concept indices. The rest of |
| 137 the menu lists all the lower level nodes in the document. | 131 the menu lists all the lower level nodes in the document. |
| 138 | |
| 139 @end ifnottex | 132 @end ifnottex |
| 140 | 133 |
| 141 @menu | 134 @menu |
| 142 * Copying Conditions:: Your rights. | 135 * Copying Conditions:: Your rights. |
| 143 * Overview:: Texinfo in brief. | 136 * Overview:: Texinfo in brief. |
| 144 * Texinfo Mode:: Using the XEmacs Texinfo mode. | 137 * Texinfo Mode:: Using the XEmacs Texinfo mode. |
| 145 * Beginning a File:: What is at the beginning of a Texinfo file? | 138 * Beginning a File:: What is at the beginning of a Texinfo file? |
| 146 * Ending a File:: What is at the end of a Texinfo file? | 139 * Ending a File:: What is at the end of a Texinfo file? |
| 147 * Structuring:: Creating chapters, sections, appendices, etc. | 140 * Chapter Structuring:: Creating chapters, sections, appendices, etc. |
| 148 * Nodes:: Writing nodes, the basic unit of Texinfo. | 141 * Nodes:: Writing nodes, the basic unit of Texinfo. |
| 149 * Menus:: Writing menus. | 142 * Menus:: Writing menus. |
| 150 * Cross References:: Writing cross references. | 143 * Cross References:: Writing cross references. |
| 151 * Marking Text:: Marking words and phrases as code, | 144 * Marking Text:: Marking words and phrases as code, |
| 152 keyboard input, meta-syntactic | 145 keyboard input, meta-syntactic |
| 153 variables, and the like. | 146 variables, and the like. |
| 154 * Quotations and Examples:: Block quotations, examples, etc. | 147 * Quotations and Examples:: Block quotations, examples, etc. |
| 155 * Lists and Tables:: Itemized or numbered lists, and tables. | 148 * Lists and Tables:: Itemized or numbered lists, and tables. |
| 156 * Special Displays:: Floating figures and footnotes. | 149 * Special Displays:: Floating figures and footnotes. |
| 157 * Indices:: Creating indices. | 150 * Indices:: Creating indices. |
| 158 * Insertions:: Inserting @@-signs, braces, etc. | 151 * Insertions:: Inserting @@-signs, braces, etc. |
| 159 * Breaks:: Forcing or preventing line and page breaks. | 152 * Breaks:: Forcing or preventing line and page breaks. |
| 160 * Definition Commands:: Describing functions and the like uniformly. | 153 * Definition Commands:: Describing functions and the like uniformly. |
| 161 * Conditionals:: Specifying text for only some output cases. | 154 * Internationalization:: Supporting languages other than English. |
| 162 * Internationalization:: Supporting languages other than English. | 155 * Conditionals:: Specifying text for only some output cases. |
| 163 * Defining New Texinfo Commands:: User-defined macros and aliases. | 156 * Defining New Texinfo Commands:: User-defined macros and aliases. |
| 164 * Hardcopy:: Output for paper, with @TeX{}. | 157 * Include Files:: How to incorporate other Texinfo files. |
| 165 * Creating and Installing Info Files:: Details on Info output. | 158 |
| 166 * Generating HTML:: Details on HTML output. | 159 * Hardcopy:: Output for paper, with @TeX{}. |
| 167 | 160 * Generic Translator @t{texi2any}:: @command{texi2any}, an all-purpose converter. |
| 168 * Command List:: All the Texinfo @@-commands. | 161 * Creating and Installing Info Files:: Details on Info output. |
| 169 * Tips:: Hints on how to write a Texinfo document. | 162 * Generating HTML:: Details on HTML output. |
| 170 * Sample Texinfo Files:: Complete examples, including full texts. | 163 @c * texi2any Output Customization:: Fine tuning with initialization files. |
| 171 * Include Files:: How to incorporate other Texinfo files. | 164 |
| 172 * Headings:: How to write page headings and footings. | 165 * Command List:: All the Texinfo @@-commands. |
| 173 * Catching Mistakes:: How to find formatting mistakes. | 166 * Tips:: Hints on how to write a Texinfo document. |
| 174 * GNU Free Documentation License::Copying this manual. | 167 * Sample Texinfo Files:: Complete examples, including full texts. |
| 175 * Command and Variable Index:: A menu containing commands and variables. | 168 * Headings:: How to write page headings and footings. |
| 176 * General Index:: A menu covering many topics. | 169 * Catching Mistakes:: How to find mistakes in formatting. |
| 170 * Info Format Specification:: Technical details of the Info file format. | |
| 171 * GNU Free Documentation License:: Copying this manual. | |
| 172 * Command and Variable Index:: A menu containing commands and variables. | |
| 173 * General Index:: A menu covering many topics. | |
| 177 | 174 |
| 178 @detailmenu | 175 @detailmenu |
| 179 --- The Detailed Node Listing --- | 176 --- The Detailed Node Listing --- |
| 180 | 177 |
| 181 Overview of Texinfo | 178 Overview of Texinfo |
| 182 | 179 |
| 183 * Reporting Bugs:: Submitting effective bug reports. | 180 * Reporting Bugs:: Submitting effective bug reports. |
| 184 * Using Texinfo:: Create printed or online output. | 181 * Using Texinfo:: Create printed or online output. |
| 185 * Output Formats:: Overview of the supported output formats. | 182 * Output Formats:: Overview of the supported output formats. |
| 183 * Adding Output Formats:: Man pages and implementing new formats. | |
| 184 * Texinfo Document Structure:: How Texinfo manuals are usually arranged. | |
| 186 * Info Files:: What is an Info file? | 185 * Info Files:: What is an Info file? |
| 187 * Printed Books:: Characteristics of a printed book or manual. | 186 * Printed Books:: Characteristics of a printed book or manual. |
| 188 * Formatting Commands:: @@-commands are used for formatting. | 187 * Formatting Commands:: @@-commands are used for formatting. |
| 189 * Conventions:: General rules for writing a Texinfo file. | 188 * Conventions:: General rules for writing a Texinfo file. |
| 190 * Comments:: Writing comments and ignored text in general. | 189 * Comments:: Writing comments and ignored text in general. |
| 194 * History:: Acknowledgements, contributors and genesis. | 193 * History:: Acknowledgements, contributors and genesis. |
| 195 | 194 |
| 196 Using Texinfo Mode | 195 Using Texinfo Mode |
| 197 | 196 |
| 198 * Texinfo Mode Overview:: How Texinfo mode can help you. | 197 * Texinfo Mode Overview:: How Texinfo mode can help you. |
| 199 * XEmacs Editing:: Texinfo mode adds to XEmacs' general | 198 * XEmacs Editing:: Texinfo mode adds to XEmacs' general |
| 200 purpose editing features. | 199 purpose editing features. |
| 201 * Inserting:: How to insert frequently used @@-commands. | 200 * Inserting:: How to insert frequently used @@-commands. |
| 202 * Showing the Structure:: How to show the structure of a file. | 201 * Showing the Structure:: How to show the structure of a file. |
| 203 * Updating Nodes and Menus:: How to update or create new nodes and menus. | 202 * Updating Nodes and Menus:: How to update or create new nodes and menus. |
| 204 * Info Formatting:: How to format for Info. | 203 * Info Formatting:: How to format for Info. |
| 221 * Document Permissions:: Ensuring your manual is free. | 220 * Document Permissions:: Ensuring your manual is free. |
| 222 * Titlepage & Copyright Page:: Creating the title and copyright pages. | 221 * Titlepage & Copyright Page:: Creating the title and copyright pages. |
| 223 * Contents:: How to create a table of contents. | 222 * Contents:: How to create a table of contents. |
| 224 * The Top Node:: Creating the `Top' node and master menu. | 223 * The Top Node:: Creating the `Top' node and master menu. |
| 225 * Global Document Commands:: Affecting formatting throughout. | 224 * Global Document Commands:: Affecting formatting throughout. |
| 226 * Software Copying Permissions:: Ensure that you and others continue to | |
| 227 have the right to use and share software. | |
| 228 | 225 |
| 229 Texinfo File Header | 226 Texinfo File Header |
| 230 | 227 |
| 231 * First Line:: The first line of a Texinfo file. | 228 * First Line:: The first line of a Texinfo file. |
| 232 * Start of Header:: Formatting a region requires this. | 229 * Start of Header:: Formatting a region requires this. |
| 233 * setfilename:: Tell Info the name of the Info file. | 230 * @t{@@setfilename}:: Tell Info the name of the Info file. |
| 234 * settitle:: Create a title for the printed work. | 231 * @t{@@settitle}:: Create a title for the printed work. |
| 235 * End of Header:: Formatting a region requires this. | 232 * End of Header:: Formatting a region requires this. |
| 236 | 233 |
| 237 Document Permissions | 234 Document Permissions |
| 238 | 235 |
| 239 * copying:: Declare the document's copying permissions. | 236 * @t{@@copying}:: Declare the document's copying permissions. |
| 240 * insertcopying:: Where to insert the permissions. | 237 * @t{@@insertcopying}:: Where to insert the permissions. |
| 241 | 238 |
| 242 Title and Copyright Pages | 239 Title and Copyright Pages |
| 243 | 240 |
| 244 * titlepage:: Create a title for the printed document. | 241 * @t{@@titlepage}:: Create a title for the printed document. |
| 245 * titlefont center sp:: The @code{@@titlefont}, @code{@@center}, | 242 * @t{@@titlefont @@center @@sp}:: The @code{@@titlefont}, @code{@@center}, |
| 246 and @code{@@sp} commands. | 243 and @code{@@sp} commands. |
| 247 * title subtitle author:: The @code{@@title}, @code{@@subtitle}, | 244 * @t{@@title @@subtitle @@author}:: The @code{@@title}, @code{@@subtitle}, |
| 248 and @code{@@author} commands. | 245 and @code{@@author} commands. |
| 249 * Copyright:: How to write the copyright notice and | 246 * Copyright:: How to write the copyright notice and |
| 250 include copying permissions. | 247 include copying permissions. |
| 251 * end titlepage:: Turn on page headings after the title and | 248 * Heading Generation:: Turn on page headings after the title and |
| 252 copyright pages. | 249 copyright pages. |
| 253 * headings on off:: An option for turning headings on and off | |
| 254 and double or single sided printing. | |
| 255 | 250 |
| 256 The `Top' Node and Master Menu | 251 The `Top' Node and Master Menu |
| 257 | 252 |
| 258 * Top Node Example:: | 253 * Top Node Example:: |
| 259 * Master Menu Parts:: | 254 * Master Menu Parts:: |
| 260 | 255 |
| 261 Global Document Commands | 256 Global Document Commands |
| 262 | 257 |
| 263 * documentdescription:: Document summary for the HTML output. | 258 * @t{@@documentdescription}:: Document summary for the HTML output. |
| 264 * setchapternewpage:: Start chapters on right-hand pages. | 259 * @t{@@setchapternewpage}:: Start chapters on right-hand pages. |
| 265 * paragraphindent:: Specify paragraph indentation. | 260 * @t{@@headings}:: An option for turning headings on and off |
| 266 * firstparagraphindent:: Suppress indentation of the first paragraph. | 261 and double or single sided printing. |
| 267 * exampleindent:: Specify environment indentation. | 262 * @t{@@paragraphindent}:: Specify paragraph indentation. |
| 263 * @t{@@firstparagraphindent}:: Suppressing first paragraph indentation. | |
| 264 * @t{@@exampleindent}:: Specify environment indentation. | |
| 268 | 265 |
| 269 Ending a Texinfo File | 266 Ending a Texinfo File |
| 270 | 267 |
| 271 * Printing Indices & Menus:: How to print an index in hardcopy and | 268 * Printing Indices & Menus:: How to print an index in hardcopy and |
| 272 generate index menus in Info. | 269 generate index menus in Info. |
| 274 | 271 |
| 275 Chapter Structuring | 272 Chapter Structuring |
| 276 | 273 |
| 277 * Tree Structuring:: A manual is like an upside down tree @dots{} | 274 * Tree Structuring:: A manual is like an upside down tree @dots{} |
| 278 * Structuring Command Types:: How to divide a manual into parts. | 275 * Structuring Command Types:: How to divide a manual into parts. |
| 279 * makeinfo top:: The @code{@@top} command, part of the `Top' node. | 276 * @t{@@chapter}:: Chapter structuring. |
| 280 * chapter:: | 277 * @t{@@unnumbered @@appendix}:: |
| 281 * unnumbered & appendix:: | 278 * @t{@@majorheading @@chapheading}:: |
| 282 * majorheading & chapheading:: | 279 * @t{@@section}:: |
| 283 * section:: | 280 * @t{@@unnumberedsec @@appendixsec @@heading}:: |
| 284 * unnumberedsec appendixsec heading:: | 281 * @t{@@subsection}:: |
| 285 * subsection:: | 282 * @t{@@unnumberedsubsec @@appendixsubsec @@subheading}:: |
| 286 * unnumberedsubsec appendixsubsec subheading:: | 283 * @t{@@subsubsection}:: Commands for the lowest level sections. |
| 287 * subsubsection:: Commands for the lowest level sections. | 284 * @t{@@part}:: Collections of chapters. |
| 288 * Raise/lower sections:: How to change commands' hierarchical level. | 285 * Raise/lower sections:: How to change commands' hierarchical level. |
| 289 | 286 |
| 290 Nodes | 287 Nodes |
| 291 | 288 |
| 292 * Two Paths:: Different commands to structure | 289 * @t{@@node}:: Creating nodes, in detail. |
| 293 Info output and printed output. | 290 * @t{makeinfo} Pointer Creation:: Letting makeinfo determine node pointers. |
| 291 * @t{@@anchor}:: Defining arbitrary cross reference targets. | |
| 294 * Node Menu Illustration:: A diagram, and sample nodes and menus. | 292 * Node Menu Illustration:: A diagram, and sample nodes and menus. |
| 295 * node:: Creating nodes, in detail. | |
| 296 * makeinfo Pointer Creation:: Letting makeinfo determine node pointers. | |
| 297 * anchor:: Defining arbitrary cross-reference targets. | |
| 298 | 293 |
| 299 The @code{@@node} Command | 294 The @code{@@node} Command |
| 300 | 295 |
| 301 * Node Names:: How to choose node and pointer names. | 296 * Node Names:: How to choose node and pointer names. |
| 302 * Writing a Node:: How to write an @code{@@node} line. | 297 * Writing a Node:: How to write an @code{@@node} line. |
| 303 * Node Line Tips:: Keep names short. | 298 * Node Line Requirements:: Keep names unique. |
| 304 * Node Line Requirements:: Keep names unique, without @@-commands. | |
| 305 * First Node:: How to write a `Top' node. | 299 * First Node:: How to write a `Top' node. |
| 306 * makeinfo top command:: How to use the @code{@@top} command. | 300 * @t{@@top} Command:: How to use the @code{@@top} command. |
| 307 | 301 |
| 308 Menus | 302 Menus |
| 309 | 303 |
| 310 * Menu Location:: Menus go at the ends of short nodes. | 304 * Menu Location:: Menus go at the ends of nodes. |
| 311 * Writing a Menu:: What is a menu? | 305 * Writing a Menu:: What is a menu? |
| 312 * Menu Parts:: A menu entry has three parts. | 306 * Menu Parts:: A menu entry has three parts. |
| 313 * Less Cluttered Menu Entry:: Two part menu entry. | 307 * Less Cluttered Menu Entry:: Two part menu entry. |
| 314 * Menu Example:: Two and three part menu entries. | 308 * Menu Example:: Two and three part menu entries. |
| 315 * Other Info Files:: How to refer to a different Info file. | 309 * Other Info Files:: How to refer to a different Info file. |
| 317 Cross References | 311 Cross References |
| 318 | 312 |
| 319 * References:: What cross references are for. | 313 * References:: What cross references are for. |
| 320 * Cross Reference Commands:: A summary of the different commands. | 314 * Cross Reference Commands:: A summary of the different commands. |
| 321 * Cross Reference Parts:: A cross reference has several parts. | 315 * Cross Reference Parts:: A cross reference has several parts. |
| 322 * xref:: Begin a reference with `See' @dots{} | 316 * @t{@@xref}:: Begin a reference with `See' @dots{} |
| 323 * Top Node Naming:: How to refer to the beginning of another file. | 317 * Top Node Naming:: How to refer to the beginning of another file. |
| 324 * ref:: A reference for the last part of a sentence. | 318 * @t{@@ref}:: A reference for the last part of a sentence. |
| 325 * pxref:: How to write a parenthetical cross reference. | 319 * @t{@@pxref}:: How to write a parenthetical cross reference. |
| 326 * inforef:: How to refer to an Info-only file. | 320 * @t{@@inforef}:: How to refer to an Info-only file. |
| 327 * uref:: How to refer to a uniform resource locator. | 321 * @t{@@url}:: How to refer to a uniform resource locator. |
| 328 * cite:: How to refer to books not in the Info system. | 322 * @t{@@cite}:: How to refer to books not in the Info system. |
| 329 | 323 |
| 330 @code{@@xref} | 324 @code{@@xref} |
| 331 | 325 |
| 332 * Reference Syntax:: What a reference looks like and requires. | 326 * Reference Syntax:: What a reference looks like and requires. |
| 333 * One Argument:: @code{@@xref} with one argument. | 327 * One Argument:: @code{@@xref} with one argument. |
| 334 * Two Arguments:: @code{@@xref} with two arguments. | 328 * Two Arguments:: @code{@@xref} with two arguments. |
| 335 * Three Arguments:: @code{@@xref} with three arguments. | 329 * Three Arguments:: @code{@@xref} with three arguments. |
| 336 * Four and Five Arguments:: @code{@@xref} with four and five arguments. | 330 * Four and Five Arguments:: @code{@@xref} with four and five arguments. |
| 337 | 331 |
| 338 Marking Words and Phrases | 332 Marking Text, Words and Phrases |
| 339 | 333 |
| 340 * Indicating:: How to indicate definitions, files, etc. | 334 * Indicating:: How to indicate definitions, files, etc. |
| 341 * Emphasis:: How to emphasize text. | 335 * Emphasis:: How to emphasize text. |
| 342 | 336 |
| 343 Indicating Definitions, Commands, etc. | 337 Indicating Definitions, Commands, etc. |
| 344 | 338 |
| 345 * Useful Highlighting:: Highlighting provides useful information. | 339 * Useful Highlighting:: Highlighting provides useful information. |
| 346 * code:: Indicating program code. | 340 * @t{@@code}:: Indicating program code. |
| 347 * kbd:: Showing keyboard input. | 341 * @t{@@kbd}:: Showing keyboard input. |
| 348 * key:: Specifying keys. | 342 * @t{@@key}:: Specifying keys. |
| 349 * samp:: A literal sequence of characters. | 343 * @t{@@samp}:: Indicating a literal sequence of characters. |
| 350 * verb:: A verbatim sequence of characters. | 344 * @t{@@verb}:: Indicating a verbatim sequence of characters. |
| 351 * var:: Indicating metasyntactic variables. | 345 * @t{@@var}:: Indicating metasyntactic variables. |
| 352 * env:: Indicating environment variables. | 346 * @t{@@env}:: Indicating environment variables. |
| 353 * file:: Indicating file names. | 347 * @t{@@file}:: Indicating file names. |
| 354 * command:: Indicating command names. | 348 * @t{@@command}:: Indicating command names. |
| 355 * option:: Indicating option names. | 349 * @t{@@option}:: Indicating option names. |
| 356 * dfn:: Specifying definitions. | 350 * @t{@@dfn}:: Specifying definitions. |
| 357 * abbr:: Indicating abbreviations. | 351 * @t{@@abbr}:: Indicating abbreviations. |
| 358 * acronym:: Indicating acronyms. | 352 * @t{@@acronym}:: Indicating acronyms. |
| 359 * indicateurl:: Indicating a World Wide Web reference. | 353 * @t{@@indicateurl}:: Indicating an example url. |
| 360 * email:: Indicating an electronic mail address. | 354 * @t{@@email}:: Indicating an electronic mail address. |
| 361 | 355 |
| 362 Emphasizing Text | 356 Emphasizing Text |
| 363 | 357 |
| 364 * emph & strong:: How to emphasize text in Texinfo. | 358 * @t{@@emph @@strong}:: How to emphasize text in Texinfo. |
| 365 * Smallcaps:: How to use the small caps font. | 359 * Smallcaps:: How to use the small caps font. |
| 366 * Fonts:: Various font commands for printed output. | 360 * Fonts:: Various font commands for printed output. |
| 367 | 361 |
| 368 Quotations and Examples | 362 Quotations and Examples |
| 369 | 363 |
| 370 * Block Enclosing Commands:: Different constructs for different purposes. | 364 * Block Enclosing Commands:: Different constructs for different purposes. |
| 371 * quotation:: Writing a quotation. | 365 * @t{@@quotation}:: Writing a quotation. |
| 372 * example:: Writing an example in a fixed-width font. | 366 * @t{@@indentedblock}:: Block of text indented on left. |
| 373 * verbatim:: Writing a verbatim example. | 367 * @t{@@example}:: Writing an example in a fixed-width font. |
| 374 * verbatiminclude:: Including a file verbatim. | 368 * @t{@@verbatim}:: Writing a verbatim example. |
| 375 * lisp:: Illustrating Lisp code. | 369 * @t{@@verbatiminclude}:: Including a file verbatim. |
| 376 * small:: Examples in a smaller font. | 370 * @t{@@lisp}:: Illustrating Lisp code. |
| 377 * display:: Writing an example in the current font. | 371 * @t{@@small@dots{}}:: Examples in a smaller font. |
| 378 * format:: Writing an example without narrowed margins. | 372 * @t{@@display}:: Writing an example in the current font. |
| 379 * exdent:: Undo indentation on a line. | 373 * @t{@@format}:: Writing an example without narrowed margins. |
| 380 * flushleft & flushright:: Pushing text flush left or flush right. | 374 * @t{@@exdent}:: Undo indentation on a line. |
| 381 * noindent:: Preventing paragraph indentation. | 375 * @t{@@flushleft @@flushright}:: Pushing text flush left or flush right. |
| 382 * indent:: Forcing paragraph indentation. | 376 * @t{@@raggedright}:: Avoiding justification on the right. |
| 383 * cartouche:: Drawing rounded rectangles around examples. | 377 * @t{@@noindent}:: Preventing paragraph indentation. |
| 378 * @t{@@indent}:: Forcing paragraph indentation. | |
| 379 * @t{@@cartouche}:: Drawing rounded rectangles around text. | |
| 384 | 380 |
| 385 Lists and Tables | 381 Lists and Tables |
| 386 | 382 |
| 387 * Introducing Lists:: Texinfo formats lists for you. | 383 * Introducing Lists:: Texinfo formats lists for you. |
| 388 * itemize:: How to construct a simple list. | 384 * @t{@@itemize}:: How to construct a simple list. |
| 389 * enumerate:: How to construct a numbered list. | 385 * @t{@@enumerate}:: How to construct a numbered list. |
| 390 * Two-column Tables:: How to construct a two-column table. | 386 * Two-column Tables:: How to construct a two-column table. |
| 391 * Multi-column Tables:: How to construct generalized tables. | 387 * Multi-column Tables:: How to construct generalized tables. |
| 392 | 388 |
| 393 Making a Two-column Table | 389 Making a Two-column Table |
| 394 | 390 |
| 395 * table:: How to construct a two-column table. | 391 * @t{@@table}:: How to construct a two-column table. |
| 396 * ftable vtable:: Automatic indexing for two-column tables. | 392 * @t{@@ftable @@vtable}:: Automatic indexing for two-column tables. |
| 397 * itemx:: How to put more entries in the first column. | 393 * @t{@@itemx}:: How to put more entries in the first column. |
| 398 | 394 |
| 399 @code{@@multitable}: Multi-column Tables | 395 @code{@@multitable}: Multi-column Tables |
| 400 | 396 |
| 401 * Multitable Column Widths:: Defining multitable column widths. | 397 * Multitable Column Widths:: Defining multitable column widths. |
| 402 * Multitable Rows:: Defining multitable rows, with examples. | 398 * Multitable Rows:: Defining multitable rows, with examples. |
| 407 * Images:: Including graphics and images. | 403 * Images:: Including graphics and images. |
| 408 * Footnotes:: Writing footnotes. | 404 * Footnotes:: Writing footnotes. |
| 409 | 405 |
| 410 Floats | 406 Floats |
| 411 | 407 |
| 412 * float:: Producing floating material. | 408 * @t{@@float}:: Producing floating material. |
| 413 * caption shortcaption:: Specifying descriptions for floats. | 409 * @t{@@caption @@shortcaption}:: Specifying descriptions for floats. |
| 414 * listoffloats:: A table of contents for floats. | 410 * @t{@@listoffloats}:: A table of contents for floats. |
| 415 | 411 |
| 416 Inserting Images | 412 Inserting Images |
| 417 | 413 |
| 418 * Image Syntax:: | 414 * Image Syntax:: |
| 419 * Image Scaling:: | 415 * Image Scaling:: |
| 432 * Combining Indices:: How to combine indices. | 428 * Combining Indices:: How to combine indices. |
| 433 * New Indices:: How to define your own indices. | 429 * New Indices:: How to define your own indices. |
| 434 | 430 |
| 435 Combining Indices | 431 Combining Indices |
| 436 | 432 |
| 437 * syncodeindex:: How to merge two indices, using @code{@@code} | 433 * @t{@@syncodeindex}:: How to merge two indices, using @code{@@code} |
| 438 font for the merged-from index. | 434 font for the merged-from index. |
| 439 * synindex:: How to merge two indices, using the | 435 * @t{@@synindex}:: How to merge two indices, using the |
| 440 default font of the merged-to index. | 436 roman font for the merged-from index. |
| 441 | 437 |
| 442 Special Insertions | 438 Special Insertions |
| 443 | 439 |
| 444 * Atsign Braces Comma:: Inserting @@ and @{@} and ,. | 440 * Special Characters:: Inserting @@ @{@} , \ # |
| 445 * Inserting Quote Characters:: Inserting left and right quotes, in code. | 441 * Inserting Quote Characters:: Inserting left and right quotes, in code. |
| 446 * Inserting Space:: How to insert the right amount of space | 442 * Inserting Space:: Inserting the right amount of whitespace. |
| 447 within a sentence. | 443 * Inserting Accents:: Inserting accents and special characters. |
| 448 * Inserting Accents:: How to insert accents and special characters. | 444 * Inserting Quotation Marks:: Inserting quotation marks. |
| 449 * Inserting Quotation Marks:: How to insert quotation marks. | 445 * Inserting Math:: Formatting mathematical expressions. |
| 450 * Dots Bullets:: How to insert dots and bullets. | 446 * Glyphs for Text:: Inserting Dots, bullets, currencies, etc. |
| 451 * TeX and copyright:: How to insert the @TeX{} logo | 447 * Glyphs for Programming:: Indicating results of evaluation, |
| 452 and the copyright symbol. | |
| 453 * euro:: How to insert the Euro currency symbol. | |
| 454 * pounds:: How to insert the pounds currency symbol. | |
| 455 * textdegree:: How to insert the degrees symbol. | |
| 456 * minus:: How to insert a minus sign. | |
| 457 * geq leq:: How to insert greater/less-than-or-equal signs. | |
| 458 * math:: How to format a mathematical expression. | |
| 459 * Click Sequences:: Inserting GUI usage sequences. | |
| 460 * Glyphs:: How to indicate results of evaluation, | |
| 461 expansion of macros, errors, etc. | 448 expansion of macros, errors, etc. |
| 462 | 449 |
| 463 Inserting @@ and @{@} and @comma{} | 450 Special Characters: Inserting @@ @{@} , \ # |
| 464 | 451 |
| 465 * Inserting an Atsign:: | 452 * Inserting an Atsign:: @code{@@@@}, @code{@@atchar@{@}}. |
| 466 * Inserting Braces:: | 453 * Inserting Braces:: @code{@@@{ @@@}}, @code{@@l rbracechar@{@}}. |
| 467 * Inserting a Comma:: | 454 * Inserting a Comma:: , and @code{@@comma@{@}}. |
| 455 * Inserting a Backslash:: \ and @code{@@backslashchar@{@}}. | |
| 456 * Inserting a Hashsign:: # and @code{@@hashchar@{@}}. | |
| 468 | 457 |
| 469 Inserting Space | 458 Inserting Space |
| 470 | 459 |
| 460 * Multiple Spaces:: Inserting multiple spaces. | |
| 471 * Not Ending a Sentence:: Sometimes a . doesn't end a sentence. | 461 * Not Ending a Sentence:: Sometimes a . doesn't end a sentence. |
| 472 * Ending a Sentence:: Sometimes it does. | 462 * Ending a Sentence:: Sometimes it does. |
| 473 * Multiple Spaces:: Inserting multiple spaces. | 463 * @t{@@frenchspacing}:: Specifying end-of-sentence spacing. |
| 474 * frenchspacing:: Specifying end-of-sentence spacing. | 464 * @t{@@dmn}:: Formatting a dimension. |
| 475 * dmn:: How to format a dimension. | 465 |
| 476 | 466 Glyphs for Text |
| 477 Inserting Ellipsis and Bullets | 467 |
| 478 | 468 * @t{@@TeX @@LaTeX}:: The @TeX{} logos. |
| 479 * dots:: How to insert dots @dots{} | 469 * @t{@@copyright}:: The copyright symbol (c in a circle). |
| 480 * bullet:: How to insert a bullet. | 470 * @t{@@registeredsymbol}:: The registered symbol (R in a circle). |
| 481 | 471 * @t{@@dots}:: How to insert ellipses: @dots{} and @enddots{} |
| 482 Inserting @TeX{} and Legal Symbols: @copyright{}, @registeredsymbol{} | 472 * @t{@@bullet}:: How to insert a bullet: @bullet{} |
| 483 | 473 * @t{@@euro}:: How to insert the euro currency symbol. |
| 484 * tex:: The @TeX{} logos. | 474 * @t{@@pounds}:: How to insert the pounds currency symbol. |
| 485 * copyright symbol:: The copyright symbol (c in a circle). | 475 * @t{@@textdegree}:: How to insert the degrees symbol. |
| 486 * registered symbol:: The registered symbol (R in a circle). | 476 * @t{@@minus}:: How to insert a minus sign. |
| 487 | 477 * @t{@@geq @@leq}:: How to insert greater/less-than-or-equal signs. |
| 488 Glyphs for Examples | 478 |
| 479 Glyphs for Programming | |
| 489 | 480 |
| 490 * Glyphs Summary:: | 481 * Glyphs Summary:: |
| 491 * result:: How to show the result of expression. | 482 * @t{@@result}:: How to show the result of expression. |
| 492 * expansion:: How to indicate an expansion. | 483 * @t{@@expansion}:: How to indicate an expansion. |
| 493 * Print Glyph:: How to indicate printed output. | 484 * @t{@@print}:: How to indicate generated output. |
| 494 * Error Glyph:: How to indicate an error message. | 485 * @t{@@error}:: How to indicate an error message. |
| 495 * Equivalence:: How to indicate equivalence. | 486 * @t{@@equiv}:: How to indicate equivalence. |
| 496 * Point Glyph:: How to indicate the location of point. | 487 * @t{@@point}:: How to indicate the location of point. |
| 497 | 488 * Click Sequences:: Inserting GUI usage sequences. |
| 498 Glyphs Summary | |
| 499 | |
| 500 * result:: | |
| 501 * expansion:: | |
| 502 * Print Glyph:: | |
| 503 * Error Glyph:: | |
| 504 * Equivalence:: | |
| 505 * Point Glyph:: | |
| 506 | 489 |
| 507 Forcing and Preventing Breaks | 490 Forcing and Preventing Breaks |
| 508 | 491 |
| 509 * Break Commands:: Summary of break-related commands. | 492 * Break Commands:: Summary of break-related commands. |
| 510 * Line Breaks:: Forcing line breaks. | 493 * Line Breaks:: Forcing line breaks. |
| 511 * - and hyphenation:: Helping @TeX{} with hyphenation points. | 494 * @t{@@- @@hyphenation}:: Helping @TeX{} with hyphenation points. |
| 512 * allowcodebreaks:: Controlling line breaks within @@code text. | 495 * @t{@@allowcodebreaks}:: Controlling line breaks within @@code text. |
| 513 * w:: Preventing unwanted line breaks in text. | 496 * @t{@@w}:: Preventing unwanted line breaks in text. |
| 514 * tie:: Inserting an unbreakable but varying space. | 497 * @t{@@tie}:: Inserting an unbreakable but varying space. |
| 515 * sp:: Inserting blank lines. | 498 * @t{@@sp}:: Inserting blank lines. |
| 516 * page:: Forcing the start of a new page. | 499 * @t{@@page}:: Forcing the start of a new page. |
| 517 * group:: Preventing unwanted page breaks. | 500 * @t{@@group}:: Preventing unwanted page breaks. |
| 518 * need:: Another way to prevent unwanted page breaks. | 501 * @t{@@need}:: Another way to prevent unwanted page breaks. |
| 519 | 502 |
| 520 Definition Commands | 503 Definition Commands |
| 521 | 504 |
| 522 * Def Cmd Template:: Writing descriptions using definition commands. | 505 * Def Cmd Template:: Writing descriptions using definition commands. |
| 523 * Def Cmd Continuation Lines:: Continuing the heading over source lines. | 506 * Def Cmd Continuation Lines:: Continuing the heading over source lines. |
| 524 * Optional Arguments:: Handling optional and repeated arguments. | 507 * Optional Arguments:: Handling optional and repeated arguments. |
| 525 * deffnx:: Group two or more `first' lines. | 508 * @t{@@deffnx}:: Group two or more `first' lines. |
| 526 * Def Cmds in Detail:: Reference for all the definition commands. | 509 * Def Cmds in Detail:: Reference for all the definition commands. |
| 527 * Def Cmd Conventions:: Conventions for writing definitions. | 510 * Def Cmd Conventions:: Conventions for writing definitions. |
| 528 * Sample Function Definition:: An example. | 511 * Sample Function Definition:: An example. |
| 529 | 512 |
| 530 The Definition Commands | 513 The Definition Commands |
| 537 * Abstract Objects:: Commands for object-oriented programming. | 520 * Abstract Objects:: Commands for object-oriented programming. |
| 538 | 521 |
| 539 Object-Oriented Programming | 522 Object-Oriented Programming |
| 540 | 523 |
| 541 * Variables: Object-Oriented Variables. | 524 * Variables: Object-Oriented Variables. |
| 542 * Methods: Object-Oriented Methods. | 525 * Methods: Object-Oriented Methods. |
| 526 | |
| 527 Internationalization | |
| 528 | |
| 529 * @t{@@documentlanguage}:: Declaring the current language. | |
| 530 * @t{@@documentencoding}:: Declaring the input encoding. | |
| 543 | 531 |
| 544 Conditionally Visible Text | 532 Conditionally Visible Text |
| 545 | 533 |
| 546 * Conditional Commands:: Text for a given format. | 534 * Conditional Commands:: Text for a given format. |
| 547 * Conditional Not Commands:: Text for any format other than a given one. | 535 * Conditional Not Commands:: Text for any format other than a given one. |
| 548 * Raw Formatter Commands:: Using raw formatter commands. | 536 * Raw Formatter Commands:: Using raw formatter commands. |
| 549 * set clear value:: Variable tests and substitutions. | 537 * Inline Conditionals:: Brace-delimited conditional text. |
| 538 * @t{@@set @@clear @@value}:: Variable tests and substitutions. | |
| 539 * Testing for Texinfo Commands:: Testing if a Texinfo command is available. | |
| 550 * Conditional Nesting:: Using conditionals inside conditionals. | 540 * Conditional Nesting:: Using conditionals inside conditionals. |
| 551 | 541 |
| 552 @code{@@set}, @code{@@clear}, and @code{@@value} | 542 @code{@@set}, @code{@@clear}, and @code{@@value} |
| 553 | 543 |
| 554 * set value:: Expand a flag variable to a string. | 544 * @t{@@set @@value}:: Expand a flag variable to a string. |
| 555 * ifset ifclear:: Format a region if a flag is set. | 545 * @t{@@ifset @@ifclear}:: Format a region if a flag is set. |
| 556 * value Example:: An easy way to update edition information. | 546 * @t{@@value} Example:: An easy way to update edition information. |
| 557 | |
| 558 Internationalization | |
| 559 | |
| 560 * documentlanguage:: Declaring the current language. | |
| 561 * documentencoding:: Declaring the input encoding. | |
| 562 | 547 |
| 563 Defining New Texinfo Commands | 548 Defining New Texinfo Commands |
| 564 | 549 |
| 565 * Defining Macros:: Defining and undefining new commands. | 550 * Defining Macros:: Defining and undefining new commands. |
| 566 * Invoking Macros:: Using a macro, once you've defined it. | 551 * Invoking Macros:: Using a macro, once you've defined it. |
| 567 * Macro Details:: Limitations of Texinfo macros. | 552 * Macro Details:: Limitations of Texinfo macros. |
| 568 * alias:: Command aliases. | 553 * @t{@@alias}:: Command aliases. |
| 569 * definfoenclose:: Customized highlighting. | 554 * @t{@@definfoenclose}:: Customized highlighting. |
| 555 * External Macro Processors:: @code{#line} directives. | |
| 556 | |
| 557 External Macro Processors: Line Directives | |
| 558 | |
| 559 * @t{#line} Directive:: | |
| 560 * TeX: @t{#line} and @TeX{}. | |
| 561 * Syntax: @t{#line} Syntax Details. | |
| 562 | |
| 563 Include Files | |
| 564 | |
| 565 * Using Include Files:: How to use the @code{@@include} command. | |
| 566 * @t{texinfo-multiple-files-update}:: How to create and update nodes and | |
| 567 menus when using included files. | |
| 568 * Include Files Requirements:: @code{texinfo-multiple-files-update} needs. | |
| 569 * Sample Include File:: A sample outer file with included files | |
| 570 within it; and a sample included file. | |
| 571 * Include Files Evolution:: How use of the @code{@@include} command | |
| 572 has changed over time. | |
| 570 | 573 |
| 571 Formatting and Printing Hardcopy | 574 Formatting and Printing Hardcopy |
| 572 | 575 |
| 573 * Use TeX:: Use @TeX{} to format for hardcopy. | 576 * Use @TeX{}:: Use @TeX{} to format for hardcopy. |
| 574 * Format with tex/texindex:: How to format with explicit shell commands. | 577 * Format with @t{tex}/@t{texindex}:: How to format with explicit shell commands. |
| 575 * Format with texi2dvi:: A simpler way to format. | 578 * Format with @t{texi2dvi}:: A simpler way to format. |
| 576 * Print with lpr:: How to print. | 579 * Print with @t{lpr}:: How to print. |
| 577 * Within XEmacs:: How to format and print from an XEmacs shell. | 580 * Within XEmacs:: How to format and print from an XEmacs shell. |
| 578 * Texinfo Mode Printing:: How to format and print in Texinfo mode. | 581 * Texinfo Mode Printing:: How to format and print in Texinfo mode. |
| 579 * Compile-Command:: How to print using XEmacs's compile command. | 582 * Compile-Command:: How to print using XEmacs's compile command. |
| 580 * Requirements Summary:: @TeX{} formatting requirements summary. | 583 * Requirements Summary:: @TeX{} formatting requirements summary. |
| 581 * Preparing for TeX:: What to do before you use @TeX{}. | 584 * Preparing for @TeX{}:: What to do before you use @TeX{}. |
| 582 * Overfull hboxes:: What are and what to do with overfull hboxes. | 585 * Overfull hboxes:: What are and what to do with overfull hboxes. |
| 583 * smallbook:: How to print small format books and manuals. | 586 * @t{@@smallbook}:: How to print small format books and manuals. |
| 584 * A4 Paper:: How to print on A4 or A5 paper. | 587 * A4 Paper:: How to print on A4 or A5 paper. |
| 585 * pagesizes:: How to print with customized page sizes. | 588 * @t{@@pagesizes}:: How to print with customized page sizes. |
| 586 * Cropmarks and Magnification:: How to print marks to indicate the size | 589 * Cropmarks and Magnification:: How to print marks to indicate the size |
| 587 of pages and how to print scaled up output. | 590 of pages and how to print scaled up output. |
| 588 * PDF Output:: Portable Document Format output. | 591 * PDF Output:: Portable Document Format output. |
| 589 * Obtaining TeX:: How to Obtain @TeX{}. | 592 * Obtaining @TeX{}:: How to obtain @TeX{}. |
| 593 | |
| 594 @code{texi2any}: The Generic Translator for Texinfo | |
| 595 | |
| 596 * Reference Implementation:: @command{texi2any}: the reference implementation. | |
| 597 * Invoking @t{texi2any}:: Running the translator from a shell. | |
| 598 * @t{texi2any} Printed Output:: Calling @command{texi2dvi}. | |
| 599 * Pointer Validation:: How to check that pointers point somewhere. | |
| 600 * Customization Variables:: Configuring @command{texi2any}. | |
| 601 * Internationalization of Document Strings:: Translating program-inserted text. | |
| 602 * Invoking @t{pod2texi}:: Translating Perl pod to Texinfo. | |
| 603 * @t{texi2html}:: An ancestor of @command{texi2any}. | |
| 604 | |
| 605 Customization Variables | |
| 606 | |
| 607 * Commands: Customization Variables for @@-Commands. | |
| 608 * Options: Customization Variables and Options. | |
| 609 * Other: Other Customization Variables. | |
| 590 | 610 |
| 591 Creating and Installing Info Files | 611 Creating and Installing Info Files |
| 592 | 612 |
| 593 * Creating an Info File:: | 613 * Creating an Info File:: |
| 594 * Installing an Info File:: | 614 * Installing an Info File:: |
| 595 | 615 |
| 596 Creating an Info File | 616 Creating an Info File |
| 597 | 617 |
| 598 * makeinfo advantages:: @code{makeinfo} provides better error checking. | 618 * @t{makeinfo} Advantages:: @code{makeinfo} provides better error checking. |
| 599 * Invoking makeinfo:: How to run @code{makeinfo} from a shell. | 619 * @t{makeinfo} in XEmacs:: How to run @code{makeinfo} from XEmacs. |
| 600 * makeinfo options:: Specify fill-column and other options. | 620 * @t{texinfo-format} commands:: Two Info formatting commands written |
| 601 * Pointer Validation:: How to check that pointers point somewhere. | 621 in Emacs Lisp are an alternative |
| 602 * makeinfo in XEmacs:: How to run @code{makeinfo} from XEmacs. | |
| 603 * texinfo-format commands:: Two Info formatting commands written | |
| 604 in XEmacs Lisp are an alternative | |
| 605 to @code{makeinfo}. | 622 to @code{makeinfo}. |
| 606 * Batch Formatting:: How to format for Info in XEmacs Batch mode. | 623 * Batch Formatting:: How to format for Info in XEmacs Batch mode. |
| 607 * Tag and Split Files:: How tagged and split files help Info | 624 * Tag and Split Files:: How tagged and split files help Info |
| 608 to run better. | 625 to run better. |
| 609 | 626 |
| 613 * New Info File:: Listing a new Info file. | 630 * New Info File:: Listing a new Info file. |
| 614 * Other Info Directories:: How to specify Info files that are | 631 * Other Info Directories:: How to specify Info files that are |
| 615 located in other directories. | 632 located in other directories. |
| 616 * Installing Dir Entries:: How to specify what menu entry to add | 633 * Installing Dir Entries:: How to specify what menu entry to add |
| 617 to the Info directory. | 634 to the Info directory. |
| 618 * Invoking install-info:: @code{install-info} options. | 635 * Invoking @t{install-info}:: @code{install-info} options. |
| 619 | 636 |
| 620 Generating HTML | 637 Generating HTML |
| 621 | 638 |
| 622 * HTML Translation:: Details of the HTML output. | 639 * HTML Translation:: Details of the HTML output. |
| 623 * HTML Splitting:: How HTML output is split. | 640 * HTML Splitting:: How HTML output is split. |
| 624 * HTML CSS:: Influencing HTML output with Cascading Style Sheets. | 641 * HTML CSS:: Influencing HTML output with Cascading Style Sheets. |
| 625 * HTML Xref:: Cross-references in HTML output. | 642 * HTML Xref:: Cross references in HTML output. |
| 626 | 643 |
| 627 HTML Cross-references | 644 HTML Cross References |
| 628 | 645 |
| 629 * Link Basics: HTML Xref Link Basics. | 646 * Link Basics: HTML Xref Link Basics. |
| 630 * Node Expansion: HTML Xref Node Name Expansion. | 647 * Node Expansion: HTML Xref Node Name Expansion. |
| 631 * Command Expansion: HTML Xref Command Expansion. | 648 * Command Expansion: HTML Xref Command Expansion. |
| 632 * 8-bit Expansion: HTML Xref 8-bit Character Expansion. | 649 * 8-bit Expansion: HTML Xref 8-bit Character Expansion. |
| 633 * Mismatch: HTML Xref Mismatch. | 650 * Mismatch: HTML Xref Mismatch. |
| 651 * Configuration: HTML Xref Configuration. htmlxref.cnf. | |
| 652 * Preserving links: HTML Xref Link Preservation. MANUAL-noderename.cnf. | |
| 634 | 653 |
| 635 @@-Command List | 654 @@-Command List |
| 636 | 655 |
| 637 * Command Syntax:: General syntax for varieties of @@-commands. | 656 * Command Syntax:: General syntax for varieties of @@-commands. |
| 657 * Command Contexts:: Guidelines for which commands can be used where. | |
| 638 | 658 |
| 639 Sample Texinfo Files | 659 Sample Texinfo Files |
| 640 | 660 |
| 641 * Short Sample Texinfo File:: | 661 * Short Sample Texinfo File:: |
| 642 * GNU Sample Texts:: | 662 * GNU Sample Texts:: |
| 643 * Verbatim Copying License:: | 663 * Verbatim Copying License:: |
| 644 * All-permissive Copying License:: | 664 * All-permissive Copying License:: |
| 645 | 665 |
| 646 GNU Free Documentation License | |
| 647 | |
| 648 Include Files | |
| 649 | |
| 650 * Using Include Files:: How to use the @code{@@include} command. | |
| 651 * texinfo-multiple-files-update:: How to create and update nodes and | |
| 652 menus when using included files. | |
| 653 * Include Files Requirements:: @code{texinfo-multiple-files-update} needs. | |
| 654 * Sample Include File:: A sample outer file with included files | |
| 655 within it; and a sample included file. | |
| 656 * Include Files Evolution:: How use of the @code{@@include} command | |
| 657 has changed over time. | |
| 658 | |
| 659 Page Headings | 666 Page Headings |
| 660 | 667 |
| 661 * Headings Introduced:: Conventions for using page headings. | 668 * Headings Introduced:: Conventions for using page headings. |
| 662 * Heading Format:: Standard page heading formats. | 669 * Heading Format:: Standard page heading formats. |
| 663 * Heading Choice:: How to specify the type of page heading. | 670 * Heading Choice:: How to specify the type of page heading. |
| 664 * Custom Headings:: How to create your own headings and footings. | 671 * Custom Headings:: How to create your own headings and footings. |
| 665 | 672 |
| 666 Formatting Mistakes | 673 Catching Mistakes |
| 667 | 674 |
| 668 * makeinfo Preferred:: @code{makeinfo} finds errors. | 675 * @t{makeinfo} Preferred:: @code{makeinfo} finds errors. |
| 669 * Debugging with Info:: How to catch errors with Info formatting. | 676 * Debugging with Info:: How to catch errors with Info formatting. |
| 670 * Debugging with TeX:: How to catch errors with @TeX{} formatting. | 677 * Debugging with @TeX{}:: How to catch errors with @TeX{} formatting. |
| 671 * Using texinfo-show-structure:: How to use @code{texinfo-show-structure}. | 678 * Using @t{texinfo-show-structure}:: How to use @code{texinfo-show-structure}. |
| 672 * Using occur:: How to list all lines containing a pattern. | 679 * Using @t{occur}:: How to list all lines containing a pattern. |
| 673 * Running Info-Validate:: How to find badly referenced nodes. | 680 * Running @t{Info-validate}:: How to find badly referenced nodes. |
| 674 | 681 |
| 675 Finding Badly Referenced Nodes | 682 Finding Badly Referenced Nodes |
| 676 | 683 |
| 677 * Using Info-validate:: How to run @code{Info-validate}. | 684 * Using @t{Info-validate}:: How to run @code{Info-validate}. |
| 678 * Unsplit:: How to create an unsplit file. | 685 * Unsplit:: How to create an unsplit file. |
| 679 * Tagifying:: How to tagify a file. | 686 * Tagifying:: How to tagify a file. |
| 680 * Splitting:: How to split a file manually. | 687 * Splitting:: How to split a file manually. |
| 681 | 688 |
| 689 Info Format Specification | |
| 690 | |
| 691 * General: Info Format General Layout. | |
| 692 * Text: Info Format Text Constructs. | |
| 693 | |
| 694 Info Format General Layout | |
| 695 | |
| 696 * Whole: Info Format Whole Manual. Split vs.@: nonsplit manuals. | |
| 697 * Preamble: Info Format Preamble. | |
| 698 * Indirect: Info Format Indirect Tag Table. | |
| 699 * Tag table: Info Format Tag Table. | |
| 700 * Local variables: Info Format Local Variables. | |
| 701 * Regular nodes: Info Format Regular Nodes. | |
| 702 | |
| 703 Info Format Text Constructs | |
| 704 | |
| 705 * Menu: Info Format Menu. | |
| 706 * Image: Info Format Image. | |
| 707 * Printindex: Info Format Printindex. | |
| 708 * Xref: Info Format Cross Reference. | |
| 682 @end detailmenu | 709 @end detailmenu |
| 683 @end menu | 710 @end menu |
| 684 | 711 |
| 685 @c Reward readers for getting to the end of the menu :). | 712 @c Reward readers for getting to the end of the menu :). |
| 686 @c Contributed by Arnold Robbins. | 713 @c Contributed by Arnold Robbins. |
| 693 | 720 |
| 694 @node Copying Conditions | 721 @node Copying Conditions |
| 695 @unnumbered Texinfo Copying Conditions | 722 @unnumbered Texinfo Copying Conditions |
| 696 @cindex Copying conditions | 723 @cindex Copying conditions |
| 697 @cindex Conditions for copying Texinfo | 724 @cindex Conditions for copying Texinfo |
| 698 | 725 @cindex Free software |
| 699 The programs currently being distributed that relate to Texinfo include | 726 @cindex Libre software |
| 700 @code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}. | 727 |
| 701 These programs are @dfn{free}; this means that everyone is free to use | 728 GNU Texinfo is @dfn{free software}; this means that everyone is free |
| 702 them and free to redistribute them on a free basis. The Texinfo-related | 729 to use it and free to redistribute it on certain conditions. Texinfo |
| 703 programs are not in the public domain; they are copyrighted and there | 730 is not in the public domain; it is copyrighted and there are |
| 704 are restrictions on their distribution, but these restrictions are | 731 restrictions on its distribution, but these restrictions are designed |
| 705 designed to permit everything that a good cooperating citizen would want | 732 to permit everything that a good cooperating citizen would want to do. |
| 706 to do. What is not allowed is to try to prevent others from further | 733 What is not allowed is to try to prevent others from further sharing |
| 707 sharing any version of these programs that they might get from you. | 734 any version of Texinfo that they might get from you. |
| 708 | 735 |
| 709 Specifically, we want to make sure that you have the right to give away | 736 Specifically, we want to make sure that you have the right to give away |
| 710 copies of the programs that relate to Texinfo, that you receive source | 737 copies of the programs that relate to Texinfo, that you receive source |
| 711 code or else can get it if you want it, that you can change these | 738 code or else can get it if you want it, that you can change these |
| 712 programs or use pieces of them in new free programs, and that you know | 739 programs or use pieces of them in new free programs, and that you know |
| 723 If these programs are modified by someone else and passed on, we want | 750 If these programs are modified by someone else and passed on, we want |
| 724 their recipients to know that what they have is not what we distributed, | 751 their recipients to know that what they have is not what we distributed, |
| 725 so that any problems introduced by others will not reflect on our | 752 so that any problems introduced by others will not reflect on our |
| 726 reputation. | 753 reputation. |
| 727 | 754 |
| 728 The precise conditions of the licenses for the programs currently being | 755 The precise conditions of the licenses for the programs currently |
| 729 distributed that relate to Texinfo are found in the General Public | 756 being distributed that relate to Texinfo are found in the General |
| 730 Licenses that accompany them. This manual specifically is covered by | 757 Public Licenses that accompany them. This manual is covered by the |
| 731 the GNU Free Documentation License (@pxref{GNU Free Documentation | 758 GNU Free Documentation License (@pxref{GNU Free Documentation |
| 732 License}). | 759 License}). |
| 733 | 760 |
| 734 | 761 |
| 735 @node Overview | 762 @node Overview |
| 736 @chapter Overview of Texinfo | 763 @chapter Overview of Texinfo |
| 737 @cindex Overview of Texinfo | 764 @cindex Overview of Texinfo |
| 738 @cindex Texinfo overview | 765 @cindex Texinfo overview |
| 739 | 766 |
| 740 @dfn{Texinfo}@footnote{The first syllable of ``Texinfo'' is pronounced | 767 @dfn{Texinfo} is a documentation system that uses a single source file |
| 741 like ``speck'', not ``hex''. This odd pronunciation is derived from, | 768 to produce both online information and printed output. This means |
| 742 but is not the same as, the pronunciation of @TeX{}. In the word | 769 that instead of writing two different documents, one for the online |
| 743 @TeX{}, the @samp{X} is actually the Greek letter ``chi'' rather than | 770 information and the other for a printed work, you need write only one |
| 744 the English letter ``ex''. Pronounce @TeX{} as if the @samp{X} were the | 771 document. Therefore, when the work is revised, you need revise only |
| 745 last sound in the name `Bach'; but pronounce Texinfo as if the @samp{x} | |
| 746 were a `k'. Spell ``Texinfo'' with a capital ``T'' and the other | |
| 747 letters in lower case.} is a documentation system that uses a single | |
| 748 source file to produce both online information and printed output. This | |
| 749 means that instead of writing two different documents, one for the | |
| 750 online information and the other for a printed work, you need write only | |
| 751 one document. Therefore, when the work is revised, you need revise only | |
| 752 that one document. | 772 that one document. |
| 753 | 773 |
| 774 @cindex Semantic markup | |
| 775 Texinfo's markup commands are almost entirely @dfn{semantic}; that is, | |
| 776 they specify the intended meaning of text in the document, rather than | |
| 777 physical formatting instructions. | |
| 778 | |
| 779 @cindex Limited scope of Texinfo | |
| 780 Texinfo was devised for the purpose of writing software documentation | |
| 781 and manuals. It is not, and was never intended to be, a | |
| 782 general-purpose formatting program. If you need to lay out a | |
| 783 newspaper, devise a glossy magazine ad, or follow the exact formatting | |
| 784 requirements of a publishing house, Texinfo is not the simplest tool. | |
| 785 On the other hand, if you want to write a good manual for your | |
| 786 program, Texinfo has many features that will make your job easier. | |
| 787 Overall, it's intended to let you concentrate on the content, and thus | |
| 788 provides almost no commands for controlling the final formatting. | |
| 789 | |
| 790 @cindex Pronounciation of Texinfo | |
| 791 @cindex Spelling of Texinfo | |
| 792 The first syllable of ``Texinfo'' is pronounced like ``speck'', not | |
| 793 ``hex''. This odd pronunciation is derived from, but is not the same | |
| 794 as, the pronunciation of @TeX{}. In the word @TeX{}, the @samp{X} is | |
| 795 actually the Greek letter ``chi'' rather than the English letter | |
| 796 ``ex''. Pronounce @TeX{} as if the @samp{X} were the last sound in | |
| 797 the name `Bach'; but pronounce Texinfo as if the @samp{x} were a `k'. | |
| 798 Spell ``Texinfo'' with a capital ``T'' and the other letters in | |
| 799 lowercase. | |
| 800 | |
| 754 Manuals for most GNU packages are written in Texinfo, and available | 801 Manuals for most GNU packages are written in Texinfo, and available |
| 755 online at @url{http://www.gnu.org/doc}. | 802 online at @url{http://www.gnu.org/doc}. The Texinfo |
| 756 | 803 |
| 757 @menu | 804 @menu |
| 758 * Reporting Bugs:: Submitting effective bug reports. | 805 * Reporting Bugs:: Submitting effective bug reports. |
| 759 * Using Texinfo:: Create printed or online output. | 806 * Using Texinfo:: Create printed or online output. |
| 760 * Output Formats:: Overview of the supported output formats. | 807 * Output Formats:: Overview of the supported output formats. |
| 808 * Adding Output Formats:: Man pages and implementing new formats. | |
| 809 * Texinfo Document Structure:: How Texinfo manuals are usually arranged. | |
| 761 * Info Files:: What is an Info file? | 810 * Info Files:: What is an Info file? |
| 762 * Printed Books:: Characteristics of a printed book or manual. | 811 * Printed Books:: Characteristics of a printed book or manual. |
| 763 * Formatting Commands:: @@-commands are used for formatting. | 812 * Formatting Commands:: @@-commands are used for formatting. |
| 764 * Conventions:: General rules for writing a Texinfo file. | 813 * Conventions:: General rules for writing a Texinfo file. |
| 765 * Comments:: Writing comments and ignored text in general. | 814 * Comments:: Writing comments and ignored text in general. |
| 774 @section Reporting Bugs | 823 @section Reporting Bugs |
| 775 | 824 |
| 776 @cindex Bugs, reporting | 825 @cindex Bugs, reporting |
| 777 @cindex Suggestions for Texinfo, making | 826 @cindex Suggestions for Texinfo, making |
| 778 @cindex Reporting bugs | 827 @cindex Reporting bugs |
| 779 We welcome bug reports and suggestions for any aspect of the Texinfo system, | 828 We welcome bug reports and suggestions for any aspect of the Texinfo |
| 780 programs, documentation, installation, anything. Please email them to | 829 system: programs, documentation, installation, etc. Please email them |
| 781 @email{bug-texinfo@@gnu.org}. You can get the latest version of Texinfo | 830 to @email{bug-texinfo@@gnu.org}. You can get the latest version of |
| 782 from @uref{ftp://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide. | 831 Texinfo via its home page, @uref{http://www.gnu.org/software/texinfo}. |
| 783 | 832 |
| 784 @cindex Checklist for bug reports | 833 @cindex Checklist for bug reports |
| 785 For bug reports, please include enough information for the maintainers | 834 For bug reports, please include enough information for the maintainers |
| 786 to reproduce the problem. Generally speaking, that means: | 835 to reproduce the problem. Generally speaking, that means: |
| 787 | 836 |
| 788 @itemize @bullet | 837 @itemize @bullet |
| 789 @item the version number of Texinfo and the program(s) or manual(s) involved. | 838 @item The version number of Texinfo and the program(s) or manual(s) involved. |
| 790 @item hardware and operating system names and versions. | 839 @item The contents of any input files necessary to reproduce the bug. |
| 791 @item the contents of any input files necessary to reproduce the bug. | 840 @item Precisely how you ran any program(s) involved. |
| 792 @item a description of the problem and samples of any erroneous output. | 841 @item A description of the problem and samples of any erroneous output. |
| 793 @item any unusual options you gave to @command{configure}. | 842 @item Hardware and operating system names and versions. |
| 794 @item anything else that you think would be helpful. | 843 @item Anything else that you think would be helpful. |
| 795 @end itemize | 844 @end itemize |
| 796 | 845 |
| 797 When in doubt whether something is needed or not, include it. It's | 846 When in doubt whether something is needed or not, include it. It's |
| 798 better to include too much than to leave out something important. | 847 better to include too much than to leave out something important. |
| 799 | 848 |
| 849 It is critical to send an actual input file that reproduces the | |
| 850 problem. What's not critical is to ``narrow down'' the example to the | |
| 851 smallest possible input---the actual input with which you discovered | |
| 852 the bug will suffice. (Of course, if you do do experiments, the | |
| 853 smaller the input file, the better.) | |
| 854 | |
| 800 @cindex Patches, contributing | 855 @cindex Patches, contributing |
| 801 Patches are most welcome; if possible, please make them with | 856 Patches are most welcome; if possible, please make them with |
| 802 @samp{@w{diff -c}} (@pxref{Top,, Overview, diff, Comparing and Merging | 857 @samp{@w{diff -c}} (@pxref{Top,,, diff, Comparing and Merging Files}) |
| 803 Files}) and include @file{ChangeLog} entries (@pxref{Change Log,,, | 858 and include @file{ChangeLog} entries (@pxref{Change Log,,, xemacs, |
| 804 xemacs, XEmacs User's Manual}), and follow the existing coding style. | 859 XEmacs User's Manual}), and follow the existing coding style. |
| 805 | 860 |
| 806 | 861 |
| 807 @node Using Texinfo | 862 @node Using Texinfo |
| 808 @section Using Texinfo | 863 @section Using Texinfo |
| 809 | 864 |
| 810 @cindex Using Texinfo in general | 865 @cindex Using Texinfo in general |
| 811 @cindex Texinfo, introduction to | 866 @cindex Texinfo, introduction to |
| 812 @cindex Introduction to Texinfo | 867 @cindex Introduction to Texinfo |
| 813 | 868 |
| 814 Using Texinfo, you can create a printed document (via the @TeX{} | 869 Using Texinfo, you can create a printed document (via the @TeX{} |
| 815 typesetting system) the normal features of a book, including chapters, | 870 typesetting system) with the normal features of a book, including |
| 816 sections, cross references, and indices. From the same Texinfo source | 871 chapters, sections, cross references, and indices. From the same |
| 817 file, you can create an Info file with special features to make | 872 Texinfo source file, you can create an Info file with special features |
| 818 documentation browsing easy. You can also create from that same | 873 to make documentation browsing easy. You can also create from that |
| 819 source file an HTML output file suitable for use with a web browser, | 874 same source file an HTML output file suitable for use with a web |
| 820 or an XML file. See the next section (@pxref{Output Formats}) for | 875 browser, a Docbook file, or a transliteration in XML format. See the |
| 821 details and the exact commands to generate output from the source. | 876 next section (@pxref{Output Formats}) for details and sample commands |
| 822 | 877 to generate output from the source. |
| 823 @TeX{} works with virtually all printers; Info works with virtually all | 878 |
| 824 computer terminals; the HTML output works with virtually all web | 879 @TeX{} works with virtually all printers; Info works with virtually |
| 825 browsers. Thus Texinfo can be used by almost any computer user. | 880 all computer terminals; the HTML output works with virtually all web |
| 881 browsers. Thus Texinfo and its output can be used by almost any | |
| 882 computer user. | |
| 826 | 883 |
| 827 @cindex Source file format | 884 @cindex Source file format |
| 828 A Texinfo source file is a plain ASCII file containing text | 885 A Texinfo source file is a plain ASCII file containing text |
| 829 interspersed with @dfn{@@-commands} (words preceded by an @samp{@@}) | 886 interspersed with @dfn{@@-commands} (words preceded by an @samp{@@}) |
| 830 that tell the typesetting and formatting programs what to do. You can | 887 that tell the Texinfo processors what to do. You can edit a Texinfo |
| 831 edit a Texinfo file with any text editor, but it is especially | 888 file with any text editor, but it is especially convenient to use |
| 832 convenient to use XEmacs since that editor has a special mode, | 889 XEmacs since that editor has a special mode, called Texinfo mode, that |
| 833 called Texinfo mode, that provides various Texinfo-related features. | 890 provides various Texinfo-related features. (@xref{Texinfo Mode}.) |
| 834 (@xref{Texinfo Mode}.) | 891 |
| 835 | 892 Texinfo is the official documentation format of the GNU project. More |
| 836 You can use Texinfo to create both online help and printed manuals; | |
| 837 moreover, Texinfo is freely redistributable. For these reasons, Texinfo | |
| 838 is the official documentation format of the GNU project. More | |
| 839 information is available at the @uref{http://www.gnu.org/doc/, GNU | 893 information is available at the @uref{http://www.gnu.org/doc/, GNU |
| 840 documentation web page}. | 894 documentation web page}. |
| 841 | 895 |
| 842 | 896 |
| 843 @node Output Formats | 897 @node Output Formats |
| 848 Here is a brief overview of the output formats currently supported by | 902 Here is a brief overview of the output formats currently supported by |
| 849 Texinfo. | 903 Texinfo. |
| 850 | 904 |
| 851 @table @asis | 905 @table @asis |
| 852 @item Info | 906 @item Info |
| 853 @cindex Info output | 907 @cindex Info output, overview |
| 854 (Generated via @command{makeinfo}.) This format is essentially a | 908 (Generated via @command{makeinfo}.) Info format is mostly a plain |
| 855 plain text transliteration of the Texinfo source. It adds a few | 909 text transliteration of the Texinfo source. It adds a few control |
| 856 control characters to separate nodes and provide navigational | 910 characters to separate nodes and provide navigational information for |
| 857 information for menus, cross-references, indices, and so on. See the | 911 menus, cross references, indices, and so on. The XEmacs Info subsystem |
| 858 next section (@pxref{Info Files}) for more details on this format. | 912 (@pxref{Top,,Getting Started,info, Info}), and the standalone @command{info} |
| 859 The XEmacs Info subsystem (@pxref{Top,,Getting Started,info, Info}), | 913 program (@pxref{Top,,, info-stnd, GNU Info}), among others, can read these |
| 860 and the standalone @command{info} program (@pxref{Top | 914 files. @xref{Info Files}, and @ref{Creating and Installing Info |
| 861 ,, Info Standalone, info-stnd, GNU Info}), among others, can read these | 915 Files}. |
| 862 files. @xref{Creating and Installing Info Files}. | |
| 863 | 916 |
| 864 @item Plain text | 917 @item Plain text |
| 865 @cindex Plain text output | 918 @cindex Plain text output, overview |
| 866 (Generated via @command{makeinfo --no-headers}.) This is almost the | 919 (Generated via @command{makeinfo --plaintext}.) This is almost the |
| 867 same as Info output, except the navigational control characters are | 920 same as Info output with the navigational control characters are |
| 868 omitted. Also, standard output is used by default. | 921 omitted. |
| 869 | 922 |
| 870 @item HTML | 923 @item HTML |
| 871 @cindex HTML output | 924 @cindex HTML output, overview |
| 872 @cindex W3 consortium | 925 @cindex W3 consortium |
| 873 @cindex Mozilla | 926 @cindex Mozilla |
| 874 @cindex Lynx | 927 @cindex Lynx |
| 875 @cindex Emacs-W3 | 928 @cindex XEmacs-W3 |
| 876 (Generated via @command{makeinfo --html}.) This is the Hyper Text | 929 (Generated via @command{makeinfo --html}.) HTML, standing for Hyper |
| 877 Markup Language that has become the most commonly used language for | 930 Text Markup Language, has become the most commonly used language for |
| 878 writing documents on the World Wide Web. Web browsers, such as | 931 writing documents on the World Wide Web. Web browsers, such as |
| 879 Mozilla, Lynx, and Emacs-W3, can render this language online. There | 932 Mozilla, Lynx, and XEmacs-W3, can render this language online. There |
| 880 are many versions of HTML; @command{makeinfo} tries to use a subset | 933 are many versions of HTML; @command{makeinfo} tries to use a subset of |
| 881 of the language that can be interpreted by any common browser. For | 934 the language that can be interpreted by any common browser. For |
| 882 details of the HTML language and much related information, see | 935 details of the HTML language and much related information, see |
| 883 @uref{http://www.w3.org/MarkUp/}. @xref{Generating HTML}. | 936 @uref{http://www.w3.org/MarkUp/}. @xref{Generating HTML}. |
| 884 | 937 |
| 885 @item DVI | 938 @item DVI |
| 886 @cindex DVI output | 939 @cindex DVI output, overview |
| 887 @pindex dvips | 940 @pindex dvips |
| 888 @pindex xdvi | 941 @pindex xdvi |
| 889 (Generated via @command{texi2dvi}.) This DeVice Independent binary | 942 (Generated via @command{texi2dvi}.) The DeVIce Independent binary |
| 890 format is output by the @TeX{} typesetting program | 943 format is output by the @TeX{} typesetting program |
| 891 (@uref{http://tug.org}). This is then read by a DVI `driver', which | 944 (@uref{http://tug.org}). This is then read by a DVI `driver', which |
| 892 writes the actual device-specific commands that can be viewed or | 945 knows the actual device-specific commands that can be viewed or |
| 893 printed, notably Dvips for translation to PostScript (@pxref{Invoking | 946 printed, notably Dvips for translation to PostScript (@pxref{Top,,, |
| 894 Dvips,,, dvips, Dvips}) and Xdvi for viewing on an X display | 947 dvips, Dvips}) and Xdvi for viewing on an X display |
| 895 (@uref{http://sourceforge.net/projects/xdvi/}). @xref{Hardcopy}. | 948 (@uref{http://sourceforge.net/projects/xdvi/}). @xref{Hardcopy}. |
| 896 | 949 (Be aware that the Texinfo language is very different from and much |
| 897 Be aware that the Texinfo language is very different from and much | 950 stricter than @TeX{}'s usual languages: plain @TeX{}, @LaTeX{}, |
| 898 stricter than @TeX{}'s usual languages, plain @TeX{} and @LaTeX{}. | 951 Con@TeX{}t, etc.) |
| 899 For more information on @TeX{} in general, please see the book | 952 |
| 900 @cite{@TeX{} for the Impatient}, available from | 953 @item PostScript |
| 901 @uref{http://savannah.gnu.org/projects/teximpatient}. | 954 @cindex PostScript output, overview |
| 955 (Generated via @command{texi2dvi --ps}.) PostScript is a page | |
| 956 description language that became widely used around 1985 and is still | |
| 957 used today. @uref{http://en.wikipedia.org/wiki/PostScript} gives a | |
| 958 basic description and more preferences. By default, Texinfo uses the | |
| 959 @command{dvips} program to convert @TeX{}'s DVI output to PostScript. | |
| 960 @xref{Top,,, dvips, Dvips}. | |
| 902 | 961 |
| 903 @item PDF | 962 @item PDF |
| 904 @cindex PDF output | 963 @cindex PDF output, overview |
| 905 @cindex Beebe, Nelson | 964 @cindex Beebe, Nelson |
| 906 @pindex pdftex | |
| 907 (Generated via @command{texi2dvi --pdf} or @command{texi2pdf}.) This | 965 (Generated via @command{texi2dvi --pdf} or @command{texi2pdf}.) This |
| 908 format was developed by Adobe Systems for portable document | 966 format was developed by Adobe Systems for portable document |
| 909 interchange, based on their previous PostScript language. It can | 967 interchange, based on their previous PostScript language. It can |
| 910 represent the exact appearance of a document, including fonts and | 968 represent the exact appearance of a document, including fonts and |
| 911 graphics, and supporting arbitrary scaling. It is intended to be | 969 graphics, and supporting arbitrary scaling. It is intended to be |
| 912 platform-independent and easily viewable, among other design goals; | 970 platform-independent and easily viewable, among other design goals; |
| 913 @uref{http://tug.org/TUGboat/Articles/tb22-3/tb72beebe-pdf.pdf} has | 971 @uref{http://en.wikipedia.org/wiki/Portable_Document_Format} and |
| 914 some background. Texinfo uses the @command{pdftex} program, a variant | 972 @uref{http://tug.org/TUGboat/tb22-3/tb72beebe-pdf.pdf} have some |
| 915 of @TeX{}, to output PDF; see | 973 background. By default, Texinfo uses the @command{pdftex} program, an |
| 974 extension of @TeX{}, to output PDF; see | |
| 916 @uref{http://tug.org/applications/pdftex}. @xref{PDF Output}. | 975 @uref{http://tug.org/applications/pdftex}. @xref{PDF Output}. |
| 917 | 976 |
| 918 @item XML | |
| 919 @cindex XML output | |
| 920 @cindex DTD, for Texinfo XML | |
| 921 @pindex texinfo.dtd | |
| 922 (Generated via @command{makeinfo --xml}.) XML is a generic syntax | |
| 923 specification usable for any sort of content (see, for example, | |
| 924 @uref{http://www.w3.org/XML/}). The @command{makeinfo} XML output, | |
| 925 unlike all the formats above, interprets very little of the Texinfo | |
| 926 source. Rather, it merely translates the Texinfo markup commands into | |
| 927 XML syntax, for processing by further XML tools. The particular | |
| 928 syntax output is defined in the file @file{texinfo.dtd} included in | |
| 929 the Texinfo source distribution. | |
| 930 | |
| 931 @item Docbook | 977 @item Docbook |
| 932 @cindex Docbook output | 978 @cindex Docbook output, overview |
| 979 @cindex XML Docbook output, overview | |
| 933 (Generated via @command{makeinfo --docbook}.) This is an XML-based | 980 (Generated via @command{makeinfo --docbook}.) This is an XML-based |
| 934 format developed some years ago, primarily for technical | 981 format developed some years ago, primarily for technical |
| 935 documentation. It therefore bears some resemblance, in broad | 982 documentation. It therefore bears some resemblance, in broad |
| 936 outlines, to Texinfo. See @uref{http://www.docbook.org}. If you want | 983 outline, to Texinfo. See @uref{http://www.docbook.org}. Various |
| 937 to convert from Docbook @emph{to} Texinfo, please see | 984 converters from Docbook @emph{to} Texinfo have also been developed; |
| 938 @uref{http://docbook2X.sourceforge.net}. | 985 see the Texinfo web pages. |
| 939 | 986 |
| 987 @item XML | |
| 988 @cindex XML Texinfo output, overview | |
| 989 @cindex Texinfo XML output, overview | |
| 990 @cindex DTD, for Texinfo XML | |
| 991 @pindex texinfo.dtd | |
| 992 @pindex txixml2texi | |
| 993 (Generated via @command{makeinfo --xml}.) XML is a generic syntax | |
| 994 specification usable for any sort of content (a reference is at | |
| 995 @uref{http://www.w3.org/XML}). The @command{makeinfo} XML output, | |
| 996 unlike all the other output formats, is a transliteration of the | |
| 997 Texinfo source rather than processed output. That is, it translates | |
| 998 the Texinfo markup commands into XML syntax, for further processing by | |
| 999 XML tools. The details of the output are defined in an XML DTD as | |
| 1000 usual, which is contained in a file @file{texinfo.dtd} included in the | |
| 1001 Texinfo source distribution and available via the Texinfo web pages. | |
| 1002 The XML contains enough information to recreate the original content, | |
| 1003 except for syntactic constructs such as Texinfo macros and | |
| 1004 conditionals. The Texinfo source distribution includes a utility script | |
| 1005 @file{txixml2texi} to do that backward transformation. | |
| 940 @end table | 1006 @end table |
| 1007 | |
| 1008 | |
| 1009 @node Adding Output Formats | |
| 1010 @section Adding Output Formats | |
| 1011 @cindex Additional output formats | |
| 1012 | |
| 1013 The output formats in the previous section handle a wide variety of | |
| 1014 usage, but of course there is always room for more. | |
| 941 | 1015 |
| 942 @cindex Man page output, not supported | 1016 @cindex Man page output, not supported |
| 943 From time to time, proposals are made to generate traditional Unix man | 1017 From time to time, proposals are made to generate traditional Unix man |
| 944 pages from Texinfo source. However, because man pages have a very | 1018 pages from Texinfo source. However, because man pages have a strict |
| 945 strict conventional format, generating a good man page requires a | 1019 conventional format, creating a good man page requires a completely |
| 946 completely different source than the typical Texinfo applications of | 1020 different source than the typical Texinfo applications of writing a |
| 947 writing a good user tutorial and/or a good reference manual. This | 1021 good user tutorial and/or a good reference manual. This makes |
| 948 makes generating man pages incompatible with the Texinfo design goal | 1022 generating man pages incompatible with the Texinfo design goal of not |
| 949 of not having to document the same information in different ways for | 1023 having to document the same information in different ways for |
| 950 different output formats. You might as well just write the man page | 1024 different output formats. You might as well write the man page |
| 951 directly. | 1025 directly. |
| 952 | 1026 |
| 953 @pindex help2man | 1027 @pindex help2man |
| 954 @cindex O'Dea, Brendan | 1028 @cindex O'Dea, Brendan |
| 955 Man pages still have their place, and if you wish to support them, you | 1029 As an alternative way to support man pages, you may find the program |
| 956 may find the program @command{help2man} to be useful; it generates a | 1030 @command{help2man} to be useful. It generates a traditional man page |
| 957 traditional man page from the @samp{--help} output of a program. In | 1031 from the @samp{--help} output of a program. In fact, the man pages |
| 958 fact, this is currently used to generate man pages for the programs in | 1032 for the programs in the Texinfo distribution are generated with this. |
| 959 the Texinfo distribution. It is GNU software written by Brendan | 1033 It is GNU software written by Brendan O'Dea, available from |
| 960 O'Dea, available from @uref{ftp://ftp.gnu.org/gnu/help2man/}. | 1034 @uref{http://www.gnu.org/software/help2man}. |
| 961 | 1035 |
| 962 @cindex Output formats, supporting more | 1036 @cindex Output formats, supporting more |
| 963 @cindex SGML-tools output format | 1037 @cindex SGML-tools output format |
| 964 If you are a programmer and would like to contribute to the GNU project | 1038 If you are a programmer and would like to contribute to the GNU |
| 965 by implementing additional output formats for Texinfo, that would be | 1039 project by implementing additional output formats for Texinfo, that |
| 966 excellent. But please do not write a separate translator texi2foo for | 1040 would be excellent. The way to do this that would be most useful is |
| 967 your favorite format foo! That is the hard way to do the job, and makes | 1041 to write a new back-end for @command{texi2any}, our reference |
| 968 extra work in subsequent maintenance, since the Texinfo language is | 1042 implementation of a Texinfo parser; it creates a tree representation |
| 969 continually being enhanced and updated. Instead, the best approach is | 1043 of the Texinfo input that you can use for the conversion. The |
| 970 modify @code{makeinfo} to generate the new format. | 1044 documentation in the source file |
| 1045 @file{tp/Texinfo/Convert/Converter.pm} is a good place to start. | |
| 1046 @xref{Generic Translator @t{texi2any}}. | |
| 1047 | |
| 1048 Another viable approach is use the Texinfo XML output from | |
| 1049 @command{texi2any} as your input. This XML is an essentially complete | |
| 1050 representation of the input, but without the Texinfo syntax and option | |
| 1051 peculiarities, as described above. | |
| 1052 | |
| 1053 @cindex Texinfo parsers, discouraging more | |
| 1054 If you still cannot resist the temptation of writing a new program | |
| 1055 that reads Texinfo source directly, let us give some more caveats: | |
| 1056 please do not underestimate the amount of work required. Texinfo is | |
| 1057 by no means a simple language to parse correctly, and remains under | |
| 1058 development, so you would be committing to an ongoing task. At a | |
| 1059 minimum, please check that the extensive tests of the language that | |
| 1060 come with @command{texi2any} give correct results with your new | |
| 1061 program. | |
| 1062 | |
| 1063 | |
| 1064 @node Texinfo Document Structure | |
| 1065 @section Texinfo Document Structure | |
| 1066 @cindex Texinfo document structure | |
| 1067 @cindex Document structure, of Texinfo | |
| 1068 @cindex Structure, of Texinfo documents | |
| 1069 @cindex Double structure, of Texinfo documents | |
| 1070 | |
| 1071 @anchor{Two Paths}@c node name | |
| 1072 Texinfo documents most usefully have a double structure, reflecting | |
| 1073 the double purposes of printed and online output. For printed output | |
| 1074 (DVI, PDF, @dots{}), with physical pages, there are chapters, | |
| 1075 sections, subsections, etc. For online output (Info, HTML, @dots{}), | |
| 1076 with interactive navigation and no physical pages, there are so-called | |
| 1077 ``nodes''. | |
| 1078 | |
| 1079 Typically, the sectioning structure and the node structure are | |
| 1080 completely parallel, with one node for each chapter, section, etc., | |
| 1081 and with the nodes following the same hierarchical arrangement as the | |
| 1082 sectioning. Thus, if a node is at the logical level of a chapter, its | |
| 1083 child nodes are at the level of sections; similarly, the child nodes | |
| 1084 of sections are at the level of subsections. | |
| 1085 | |
| 1086 Each @dfn{node} has a name, and contains the discussion of one topic. | |
| 1087 Along with the text for the user to read, each node also has pointers | |
| 1088 to other nodes, identified in turn by their own names. Info readers | |
| 1089 display one node at a time, and provide commands for the user to move | |
| 1090 to related nodes. The HTML output can be similarly navigated. | |
| 1091 | |
| 1092 The names of child nodes are listed in a @dfn{menu} within the parent | |
| 1093 node; for example, a node corresponding to a chapter would have a menu | |
| 1094 of the sections in that chapter. The menus allow the user to move to | |
| 1095 the child nodes in a natural way in the online output. | |
| 1096 | |
| 1097 In addition, nodes at the same level are formed into a chain with | |
| 1098 `Next' and `Previous' pointers. As you might imagine, the `Next' | |
| 1099 pointer links to the next node (section), and the `Previous' pointer | |
| 1100 links to the previous node (section). Thus, for example, all the | |
| 1101 nodes that are at the level of sections within a chapter are linked | |
| 1102 together, and the order in this chain is the same as the order of the | |
| 1103 children in the menu of parent chapter. Each child node records the | |
| 1104 parent node name as its `Up' pointer. The last child has no `Next' | |
| 1105 pointer, and the first child has the parent both as its `Previous' and | |
| 1106 as its `Up' pointer. | |
| 1107 | |
| 1108 In addition to menus and `Next', `Previous', and `Up' pointers, | |
| 1109 Texinfo provides pointers of another kind for cross references, that | |
| 1110 can be sprinkled throughout the text. This is usually the best way to | |
| 1111 represent links that do not fit a hierarchical structure. | |
| 1112 | |
| 1113 Although it is technically possible to create Texinfo documents with | |
| 1114 only one structure or the other, or for the two structures not to be | |
| 1115 parallel, or for either the sectioning or node structure to be | |
| 1116 abnormally formed, etc., this is @emph{not at all recommended}. To | |
| 1117 the best of our knowledge, all the Texinfo manuals currently in | |
| 1118 general use do follow the conventional parallel structure. | |
| 971 | 1119 |
| 972 | 1120 |
| 973 @node Info Files | 1121 @node Info Files |
| 974 @section Info Files | 1122 @section Info Files |
| 975 @cindex Info files | 1123 @cindex Info files |
| 976 | 1124 |
| 977 An Info file is a Texinfo file formatted so that the Info documentation | 1125 As mentioned above, Info format is mostly a plain text transliteration |
| 978 reading program can operate on it. (@code{makeinfo} | 1126 of the Texinfo source, with the addition of a few control characters |
| 979 and @code{texinfo-format-buffer} are two commands that convert a Texinfo file | 1127 to separate nodes and provide navigational information, so that |
| 980 into an Info file.) | 1128 Info-reading programs can operate on it. |
| 981 | 1129 |
| 982 Info files are divided into pieces called @dfn{nodes}, each of which | 1130 Info files are nearly always created by processing a Texinfo source |
| 983 contains the discussion of one topic. Each node has a name, and | 1131 document. @command{makeinfo}, also known as @command{texi2any}, is |
| 984 contains both text for the user to read and pointers to other nodes, | 1132 the principal command that converts a Texinfo file into an Info file; |
| 985 which are identified by their names. The Info program displays one node | 1133 @pxref{Generic Translator @t{texi2any}}. |
| 986 at a time, and provides commands with which the user can move to other | |
| 987 related nodes. | |
| 988 | |
| 989 @xref{Top,,, info, GNU Info}, for more information about using Info. | |
| 990 | |
| 991 Each node of an Info file may have any number of child nodes that | |
| 992 describe subtopics of the node's topic. The names of child | |
| 993 nodes are listed in a @dfn{menu} within the parent node; this | |
| 994 allows you to use certain Info commands to move to one of the child | |
| 995 nodes. Generally, an Info file is organized like a book. If a node | |
| 996 is at the logical level of a chapter, its child nodes are at the level | |
| 997 of sections; likewise, the child nodes of sections are at the level | |
| 998 of subsections. | |
| 999 | |
| 1000 All the children of any one parent are linked together in a | |
| 1001 bidirectional chain of `Next' and `Previous' pointers. The `Next' | |
| 1002 pointer provides a link to the next section, and the `Previous' pointer | |
| 1003 provides a link to the previous section. This means that all the nodes | |
| 1004 that are at the level of sections within a chapter are linked together. | |
| 1005 Normally the order in this chain is the same as the order of the | |
| 1006 children in the parent's menu. Each child node records the parent node | |
| 1007 name as its `Up' pointer. The last child has no `Next' pointer, and the | |
| 1008 first child has the parent both as its `Previous' and as its `Up' | |
| 1009 pointer.@footnote{In some documents, the first child has no `Previous' | |
| 1010 pointer. Occasionally, the last child has the node name of the next | |
| 1011 following higher level node as its `Next' pointer.} | |
| 1012 | |
| 1013 The book-like structuring of an Info file into nodes that correspond | |
| 1014 to chapters, sections, and the like is a matter of convention, not a | |
| 1015 requirement. The `Up', `Previous', and `Next' pointers of a node can | |
| 1016 point to any other nodes, and a menu can contain any other nodes. | |
| 1017 Thus, the node structure can be any directed graph. But it is usually | |
| 1018 more comprehensible to follow a structure that corresponds to the | |
| 1019 structure of chapters and sections in a printed book or report.@refill | |
| 1020 | |
| 1021 In addition to menus and to `Next', `Previous', and `Up' pointers, Info | |
| 1022 provides pointers of another kind, called references, that can be | |
| 1023 sprinkled throughout the text. This is usually the best way to | |
| 1024 represent links that do not fit a hierarchical structure.@refill | |
| 1025 | |
| 1026 Usually, you will design a document so that its nodes match the | |
| 1027 structure of chapters and sections in the printed output. But | |
| 1028 occasionally there are times when this is not right for the material | |
| 1029 being discussed. Therefore, Texinfo uses separate commands to specify | |
| 1030 the node structure for the Info file and the section structure for the | |
| 1031 printed output.@refill | |
| 1032 | 1134 |
| 1033 Generally, you enter an Info file through a node that by convention is | 1135 Generally, you enter an Info file through a node that by convention is |
| 1034 named `Top'. This node normally contains just a brief summary of the | 1136 named `Top'. This node normally contains just a brief summary of the |
| 1035 file's purpose, and a large menu through which the rest of the file is | 1137 file's purpose, and a large menu through which the rest of the file is |
| 1036 reached. From this node, you can either traverse the file | 1138 reached. From this node, you can either traverse the file |
| 1040 with the standalone Info program, you can specify specific menu items on | 1142 with the standalone Info program, you can specify specific menu items on |
| 1041 the command line (@pxref{Top,,, info, Info}). | 1143 the command line (@pxref{Top,,, info, Info}). |
| 1042 | 1144 |
| 1043 If you want to read through an Info file in sequence, as if it were a | 1145 If you want to read through an Info file in sequence, as if it were a |
| 1044 printed manual, you can hit @key{SPC} repeatedly, or you get the whole | 1146 printed manual, you can hit @key{SPC} repeatedly, or you get the whole |
| 1045 file with the advanced Info command @kbd{g *}. (@inforef{Advanced, | 1147 file with the advanced Info command @kbd{g *}. (@xref{Advanced,, |
| 1046 Advanced Info commands, info}.)@refill | 1148 Advanced Info commands, info, Info}.) |
| 1047 | 1149 |
| 1048 @c !!! dir file may be located in one of many places: | |
| 1049 @c /usr/local/xemacs/info mentioned in info.c DEFAULT_INFOPATH | |
| 1050 @c /usr/local/lib/xemacs/info mentioned in info.c DEFAULT_INFOPATH | |
| 1051 @c /usr/gnu/info mentioned in info.c DEFAULT_INFOPATH | |
| 1052 @c /usr/local/info | |
| 1053 @c /usr/local/lib/info | |
| 1054 The @file{dir} file in the @file{info} directory serves as the | 1150 The @file{dir} file in the @file{info} directory serves as the |
| 1055 departure point for the whole Info system. From it, you can reach the | 1151 departure point for the whole Info system. From it, you can reach the |
| 1056 `Top' nodes of each of the documents in a complete Info system.@refill | 1152 `Top' nodes of each of the documents in a complete Info system. |
| 1057 | 1153 |
| 1058 @cindex URI syntax for Info | 1154 @cindex URI syntax for Info |
| 1059 If you wish to refer to an Info file in a URI, you can use the | 1155 If you wish to refer to an Info file via a URI, you can use the |
| 1060 (unofficial) syntax exemplified in the following. This works with | 1156 (unofficial) syntax exemplified by the following. This works with |
| 1061 Emacs/W3, for example: | 1157 XEmacs/W3, for example: |
| 1062 @example | 1158 @example |
| 1159 info:xemacs#Dissociated%20Press | |
| 1063 info:///usr/info/xemacs#Dissociated%20Press | 1160 info:///usr/info/xemacs#Dissociated%20Press |
| 1064 info:xemacs#Dissociated%20Press | |
| 1065 info://localhost/usr/info/xemacs#Dissociated%20Press | 1161 info://localhost/usr/info/xemacs#Dissociated%20Press |
| 1066 @end example | 1162 @end example |
| 1067 | 1163 |
| 1068 The @command{info} program itself does not follow URIs of any kind. | 1164 The @command{info} program itself does not follow URIs of any kind. |
| 1069 | 1165 |
| 1075 @cindex Book characteristics, printed | 1171 @cindex Book characteristics, printed |
| 1076 @cindex Texinfo printed book characteristics | 1172 @cindex Texinfo printed book characteristics |
| 1077 @cindex Characteristics, printed books or manuals | 1173 @cindex Characteristics, printed books or manuals |
| 1078 | 1174 |
| 1079 @cindex Knuth, Donald | 1175 @cindex Knuth, Donald |
| 1080 A Texinfo file can be formatted and typeset as a printed book or manual. | 1176 A Texinfo file can be formatted and typeset as a printed book or |
| 1081 To do this, you need @TeX{}, a powerful, sophisticated typesetting | 1177 manual. To do this, you need @TeX{}, a sophisticated typesetting |
| 1082 program written by Donald Knuth.@footnote{You can also use the | 1178 program written by Donald Knuth of Stanford University. |
| 1083 @pindex texi2roff@r{, unsupported software} | |
| 1084 @uref{ftp://tug.org/texi2roff.tar.gz, @code{texi2roff}} program if you | |
| 1085 do not have @TeX{}; since Texinfo is designed for use with @TeX{}, | |
| 1086 @code{texi2roff} is not described here. @code{texi2roff} is not part of | |
| 1087 the standard GNU distribution and is not maintained or up-to-date with | |
| 1088 all the Texinfo features described in this manual.} | |
| 1089 | 1179 |
| 1090 A Texinfo-based book is similar to any other typeset, printed work: it | 1180 A Texinfo-based book is similar to any other typeset, printed work: it |
| 1091 can have a title page, copyright page, table of contents, and preface, | 1181 can have a title page, copyright page, table of contents, and preface, |
| 1092 as well as chapters, numbered or unnumbered sections and subsections, | 1182 as well as chapters, numbered or unnumbered sections and subsections, |
| 1093 page headers, cross references, footnotes, and indices.@refill | 1183 page headers, cross references, footnotes, and indices. |
| 1094 | |
| 1095 You can use Texinfo to write a book without ever having the intention | |
| 1096 of converting it into online information. You can use Texinfo for | |
| 1097 writing a printed novel, and even to write a printed memo, although | |
| 1098 this latter application is not recommended since electronic mail is so | |
| 1099 much easier.@refill | |
| 1100 | 1184 |
| 1101 @TeX{} is a general purpose typesetting program. Texinfo provides a | 1185 @TeX{} is a general purpose typesetting program. Texinfo provides a |
| 1102 file @file{texinfo.tex} that contains information (definitions or | 1186 file @file{texinfo.tex} that contains information (definitions or |
| 1103 @dfn{macros}) that @TeX{} uses when it typesets a Texinfo file. | 1187 @dfn{macros}) that @TeX{} uses when it typesets a Texinfo file. |
| 1104 (@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands | 1188 (@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands |
| 1105 to @TeX{} commands, which @TeX{} can then process to create the typeset | 1189 to @TeX{} commands, which @TeX{} can then process to create the typeset |
| 1106 document.) @file{texinfo.tex} contains the specifications for printing | 1190 document.) @file{texinfo.tex} contains the specifications for printing |
| 1107 a document. You can get the latest version of @file{texinfo.tex} from | 1191 a document. You can get the latest version of @file{texinfo.tex} from |
| 1108 the Texinfo home page, @uref{http://www.gnu.org/software/texinfo/}. | 1192 the Texinfo home page, @uref{http://www.gnu.org/software/texinfo/}. |
| 1109 | 1193 |
| 1110 In the United States, documents are most often printed on 8.5 inch by 11 | 1194 In the United States, documents are most often printed on 8.5 inch by |
| 1111 inch pages (216@dmn{mm} by 280@dmn{mm}); this is the default size. But | 1195 11 inch pages (216@dmn{mm} by 280@dmn{mm}); this is the default size. |
| 1112 you can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by | 1196 But you can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by |
| 1113 235@dmn{mm}, the @code{@@smallbook} size; or on A4 or A5 size paper | 1197 235@dmn{mm}, the @code{@@smallbook} size; or on A4 or A5 size paper |
| 1114 (@code{@@afourpaper}, @code{@@afivepaper}). (@xref{smallbook, , | 1198 (@code{@@afourpaper}, @code{@@afivepaper}). |
| 1115 Printing ``Small'' Books}. Also, see @ref{A4 Paper, ,Printing on A4 | 1199 @xref{@t{@@smallbook}}, and @ref{A4 Paper}. |
| 1116 Paper}.) | 1200 |
| 1117 | 1201 @cindex Literate programming |
| 1118 By changing the parameters in @file{texinfo.tex}, you can change the | |
| 1119 size of the printed document. In addition, you can change the style in | |
| 1120 which the printed document is formatted; for example, you can change the | |
| 1121 sizes and fonts used, the amount of indentation for each paragraph, the | |
| 1122 degree to which words are hyphenated, and the like. By changing the | |
| 1123 specifications, you can make a book look dignified, old and serious, or | |
| 1124 light-hearted, young and cheery. | |
| 1125 | |
| 1126 @TeX{} is freely distributable. It is written in a superset of Pascal | 1202 @TeX{} is freely distributable. It is written in a superset of Pascal |
| 1127 called WEB and can be compiled either in Pascal or (by using a | 1203 for literate programming called WEB and can be compiled either in |
| 1128 conversion program that comes with the @TeX{} distribution) in C. | 1204 Pascal or (by using a conversion program that comes with the @TeX{} |
| 1129 (@xref{TeX Mode, ,@TeX{} Mode, xemacs, XEmacs User's Manual}, for information | 1205 distribution) in C. |
| 1130 about @TeX{}.)@refill | |
| 1131 | 1206 |
| 1132 @TeX{} is very powerful and has a great many features. Because a | 1207 @TeX{} is very powerful and has a great many features. Because a |
| 1133 Texinfo file must be able to present information both on a | 1208 Texinfo file must be able to present information both on a |
| 1134 character-only terminal in Info form and in a typeset book, the | 1209 character-only terminal in Info form and in a typeset book, the |
| 1135 formatting commands that Texinfo supports are necessarily limited. | 1210 formatting commands that Texinfo supports are necessarily limited. |
| 1136 | 1211 |
| 1137 To get a copy of @TeX{}, see | 1212 @xref{Obtaining @TeX{}}, for information on acquiring @TeX{}. It is |
| 1138 @ref{Obtaining TeX, , How to Obtain @TeX{}}. | 1213 not part of the Texinfo distribution. |
| 1139 | 1214 |
| 1140 | 1215 |
| 1141 @node Formatting Commands | 1216 @node Formatting Commands |
| 1142 @section @@-commands | 1217 @section @@-commands |
| 1143 @cindex @@-commands | 1218 @cindex @@-commands |
| 1144 @cindex Formatting commands | 1219 @cindex Formatting commands |
| 1145 | 1220 |
| 1146 In a Texinfo file, the commands that tell @TeX{} how to typeset the | 1221 In a Texinfo file, the commands you write to describe the contents of |
| 1147 printed manual and tell @code{makeinfo} and | 1222 the manual are preceded by an @samp{@@} character; they are called |
| 1148 @code{texinfo-format-buffer} how to create an Info file are preceded | 1223 @dfn{@@-commands}. For example, @code{@@node} is the command to |
| 1149 by @samp{@@}; they are called @dfn{@@-commands}. For example, | 1224 indicate a node and @code{@@chapter} is the command to indicate the |
| 1150 @code{@@node} is the command to indicate a node and @code{@@chapter} | 1225 start of a chapter. Almost all @@ command names are entirely |
| 1151 is the command to indicate the start of a chapter.@refill | 1226 lowercase. |
| 1152 | 1227 |
| 1153 @quotation Note | 1228 Texinfo's @@-commands are a strictly limited set of constructs. The |
| 1154 Almost all @@ command names are entirely lower case. | 1229 strict limits are primarily intended to ``force'' you, the author, to |
| 1155 @end quotation | 1230 concentrate on the writing and the content of your manual, rather than |
| 1156 | 1231 the details of the formatting. |
| 1157 The Texinfo @@-commands are a strictly limited set of constructs. The | |
| 1158 strict limits make it possible for Texinfo files to be understood both | |
| 1159 by @TeX{} and by the code that converts them into Info files. You can | |
| 1160 display Info files on any terminal that displays alphabetic and | |
| 1161 numeric characters. Similarly, you can print the output generated by | |
| 1162 @TeX{} on a wide variety of printers.@refill | |
| 1163 | 1232 |
| 1164 Depending on what they do or what arguments@footnote{The word | 1233 Depending on what they do or what arguments@footnote{The word |
| 1165 @dfn{argument} comes from the way it is used in mathematics and does not | 1234 @dfn{argument} comes from the way it is used in mathematics and does not |
| 1166 refer to a dispute between two people; it refers to the information | 1235 refer to a dispute between two people; it refers to the information |
| 1167 presented to the command. According to the @cite{Oxford English | 1236 presented to the command. According to the @cite{Oxford English |
| 1174 need to write @@-commands on lines of their own or as part of | 1243 need to write @@-commands on lines of their own or as part of |
| 1175 sentences: | 1244 sentences: |
| 1176 | 1245 |
| 1177 @itemize @bullet | 1246 @itemize @bullet |
| 1178 @item | 1247 @item |
| 1179 Write a command such as @code{@@quotation} at the beginning of a line as | 1248 Some commands are written at the start of a line and the rest of the |
| 1180 the only text on the line. (@code{@@quotation} begins an indented | 1249 line comprises the argument text, such as @code{@@chapter} (which |
| 1181 environment.) | 1250 creates chapter titles). |
| 1182 | 1251 |
| 1183 @item | 1252 @item |
| 1184 Write a command such as @code{@@chapter} at the beginning of a line | 1253 Some commands can appear anywhere, generally within a sentence, and |
| 1185 followed by the command's arguments, in this case the chapter title, on | 1254 are followed by empty braces, such as @code{@@dots@{@}} (which creates |
| 1186 the rest of the line. (@code{@@chapter} creates chapter titles.)@refill | 1255 an ellipsis @dots{}). |
| 1187 | 1256 |
| 1188 @item | 1257 @item |
| 1189 Write a command such as @code{@@dots@{@}} wherever you wish but usually | 1258 Some commands can appear anywhere, generally within a sentence, and |
| 1190 within a sentence. (@code{@@dots@{@}} creates an ellipsis @dots{})@refill | 1259 are followed by the argument text in braces, such as |
| 1260 @code{@@code@{a+1@}} (which marks text as being code, @code{a+1} being | |
| 1261 the argument in this case). | |
| 1191 | 1262 |
| 1192 @item | 1263 @item |
| 1193 Write a command such as @code{@@code@{@var{sample-code}@}} wherever you | 1264 Some commands are written at the start of a line, with general text on |
| 1194 wish (but usually within a sentence) with its argument, | 1265 following lines, terminated by a matching @code{@@end} command on a |
| 1195 @var{sample-code} in this example, between the braces. (@code{@@code} | 1266 line of its own. For example, @code{@@example}, then the lines of a |
| 1196 marks text as being code.)@refill | 1267 coding example, then @code{@@end example}. |
| 1197 | |
| 1198 @item | |
| 1199 Write a command such as @code{@@example} on a line of its own; write the | |
| 1200 body-text on following lines; and write the matching @code{@@end} | |
| 1201 command, @code{@@end example} in this case, on a line of its own | |
| 1202 after the body-text. (@code{@@example} @dots{} @code{@@end example} | |
| 1203 indents and typesets body-text as an example.) It's usually ok to | |
| 1204 indent environment commands like this, but in complicated and | |
| 1205 hard-to-define circumstances the extra spaces cause extra space to | |
| 1206 appear in the output, so beware. | |
| 1207 @end itemize | 1268 @end itemize |
| 1208 | 1269 |
| 1209 @noindent | 1270 @noindent |
| 1210 @cindex Braces, when to use | 1271 @cindex Braces, when to use |
| 1211 As a general rule, a command requires braces if it mingles among other | 1272 As a general rule, a command requires braces if it mingles among other |
| 1212 text; but it does not need braces if it starts a line of its own. The | 1273 text; but it does not need braces if it is on a line of its own. The |
| 1213 non-alphabetic commands, such as @code{@@:}, are exceptions to the rule; | 1274 non-alphabetic commands, such as @code{@@:}, are exceptions to the |
| 1214 they do not need braces.@refill | 1275 rule; they do not need braces. |
| 1215 | 1276 |
| 1216 As you gain experience with Texinfo, you will rapidly learn how to | 1277 As you gain experience with Texinfo, you will rapidly learn how to |
| 1217 write the different commands: the different ways to write commands | 1278 write the different commands: the different ways to write commands |
| 1218 actually make it easier to write and read Texinfo files than if all | 1279 actually make it easier to write and read Texinfo files than if all |
| 1219 commands followed exactly the same syntax. @xref{Command Syntax, , | 1280 commands followed exactly the same syntax. @xref{Command Syntax, , |
| 1239 commands. To put one of these special characters into the document, put | 1300 commands. To put one of these special characters into the document, put |
| 1240 an @samp{@@} character in front of it, like this: @samp{@@@@}, | 1301 an @samp{@@} character in front of it, like this: @samp{@@@@}, |
| 1241 @samp{@@@{}, and @samp{@@@}}. | 1302 @samp{@@@{}, and @samp{@@@}}. |
| 1242 | 1303 |
| 1243 @item | 1304 @item |
| 1244 @cindex Paragraph separator | 1305 Texinfo supports the usual quotation marks used in English and in |
| 1245 @cindex Blank lines, as paragraph separator | 1306 other languages; see @ref{Inserting Quotation Marks}. |
| 1246 @cindex Newlines, as blank lines | |
| 1247 Separate paragraphs with one or more blank lines. Currently Texinfo | |
| 1248 only recognizes newline characters as end of line, not the CRLF | |
| 1249 sequence used on some systems; so a @dfn{blank line} means exactly two | |
| 1250 consecutive newlines. Sometimes blank lines are useful or convenient | |
| 1251 in other cases as well; you can use the @code{@@noindent} to inhibit | |
| 1252 paragraph indentation if required (@pxref{noindent,,@code{@@noindent}}). | |
| 1253 | |
| 1254 @item | |
| 1255 Texinfo supports the usual quotation marks used in English, and | |
| 1256 quotation marks used in other languages, please see @ref{Inserting | |
| 1257 Quotation Marks}. | |
| 1258 | 1307 |
| 1259 @item | 1308 @item |
| 1260 @cindex Multiple dashes in source | 1309 @cindex Multiple dashes in source |
| 1261 @cindex Dashes in source | 1310 @cindex Dashes in source |
| 1262 @cindex Hyphens in source, two or three in a row | 1311 @cindex Hyphens in source, two or three in a row |
| 1271 hyphens to two and two hyphens to one (not transitively!). Of course, | 1320 hyphens to two and two hyphens to one (not transitively!). Of course, |
| 1272 any number of hyphens in the source remain as they are in literal | 1321 any number of hyphens in the source remain as they are in literal |
| 1273 contexts, such as @code{@@code} and @code{@@example}. | 1322 contexts, such as @code{@@code} and @code{@@example}. |
| 1274 | 1323 |
| 1275 @item | 1324 @item |
| 1325 @cindex Form feed characters | |
| 1326 @cindex @kbd{CTRL-l} | |
| 1327 Form feed (@kbd{CTRL-l}) characters in the input are handled as | |
| 1328 follows: | |
| 1329 | |
| 1330 @table @asis | |
| 1331 @item PDF/DVI | |
| 1332 In normal text, treated as ending any open paragraph; essentially | |
| 1333 ignored between paragraphs. | |
| 1334 | |
| 1335 @item Info | |
| 1336 Output as-is between paragraphs (their most common use); in other | |
| 1337 contexts, they may be treated as regular spaces (and thus consolidated | |
| 1338 with surrounding whitespace). | |
| 1339 | |
| 1340 @item HTML | |
| 1341 Written as a numeric entity except contexts where spaces are ignored; | |
| 1342 for example, in @samp{@@footnote@{ ^L foo@}}, the form feed is | |
| 1343 ignored. | |
| 1344 | |
| 1345 @item XML | |
| 1346 Keep them everywhere; in attributes, escaped as @samp{\f}; also, | |
| 1347 @samp{\} is escaped as @samp{\\} and newline as @samp{\n}. | |
| 1348 | |
| 1349 @item Docbook | |
| 1350 Completely removed, as they are not allowed. | |
| 1351 @end table | |
| 1352 | |
| 1353 As you can see, because of these differing requirements of the output | |
| 1354 formats, it's not possible to use form feeds completely portably. | |
| 1355 | |
| 1356 @item | |
| 1276 @cindex Tabs; don't use! | 1357 @cindex Tabs; don't use! |
| 1277 @strong{Caution:} Last, do not use tab characters in a Texinfo file | 1358 @strong{Caution:} Last, do not use tab characters in a Texinfo file! |
| 1278 (except in verbatim modes)! @TeX{} uses variable-width fonts, which | 1359 (Except perhaps in verbatim modes.) @TeX{} uses variable-width fonts, |
| 1279 means that it is impractical at best to define a tab to work in all | 1360 which means that it is impractical at best to define a tab to work in |
| 1280 circumstances. Consequently, @TeX{} treats tabs like single spaces, | 1361 all circumstances. Consequently, @TeX{} treats tabs like single |
| 1281 and that is not what they look like in the source. Furthermore, | 1362 spaces, and that is not what they look like in the source. |
| 1282 @code{makeinfo} does nothing special with tabs, and thus a tab | 1363 Furthermore, @code{makeinfo} does nothing special with tabs, and thus |
| 1283 character in your input file will usually appear differently in the | 1364 a tab character in your input file will usually have a different |
| 1284 output. | 1365 appearance in the output. |
| 1285 | 1366 |
| 1286 @noindent | 1367 @noindent |
| 1287 To avoid this problem, Texinfo mode in XEmacs inserts | 1368 To avoid this problem, Texinfo mode in XEmacs inserts |
| 1288 multiple spaces when you press the @key{TAB} key. Also, you can run | 1369 multiple spaces when you press the @key{TAB} key. Also, you can run |
| 1289 @code{untabify} in XEmacs to convert tabs in a region to multiple | 1370 @code{untabify} in XEmacs to convert tabs in a region to multiple |
| 1290 spaces, or use the @code{unexpand} command from the shell. | 1371 spaces, or use the @code{unexpand} command from the shell. |
| 1291 | |
| 1292 @end itemize | 1372 @end itemize |
| 1293 | 1373 |
| 1294 | 1374 |
| 1295 @node Comments | 1375 @node Comments |
| 1296 @section Comments | 1376 @section Comments |
| 1297 | 1377 |
| 1298 @cindex Comments | 1378 @cindex Comments |
| 1299 @findex comment | 1379 @findex comment |
| 1300 @findex c @r{(comment)} | 1380 @findex c @r{(comment)} |
| 1301 | 1381 |
| 1302 You can write comments in a Texinfo file that will not appear in | 1382 You can write comments in a Texinfo file by using the @code{@@comment} |
| 1303 either the Info file or the printed manual by using the | 1383 command, which may be abbreviated to @code{@@c}. Such comments are |
| 1304 @code{@@comment} command (which may be abbreviated to @code{@@c}). | 1384 for a person looking at the Texinfo source file. All the text on a |
| 1305 Such comments are for the person who revises the Texinfo file. All the | 1385 line that follows either @code{@@comment} or @code{@@c} is a comment; |
| 1306 text on a line that follows either @code{@@comment} or @code{@@c} is a | 1386 the rest of the line does not appear in the visible output. |
| 1307 comment; the rest of the line does not appear in either the Info file | 1387 |
| 1308 or the printed manual. | 1388 Often, you can write the @code{@@comment} or @code{@@c} in the middle |
| 1309 | 1389 of a line, and only the text that follows after the @code{@@comment} |
| 1310 Often, you can write the @code{@@comment} or @code{@@c} in the middle of | 1390 or @code{@@c} command does not appear; but some commands, such as |
| 1311 a line, and only the text that follows after the @code{@@comment} or | |
| 1312 @code{@@c} command does not appear; but some commands, such as | |
| 1313 @code{@@settitle} and @code{@@setfilename}, work on a whole line. You | 1391 @code{@@settitle} and @code{@@setfilename}, work on a whole line. You |
| 1314 cannot use @code{@@comment} or @code{@@c} in a line beginning with such | 1392 cannot use @code{@@comment} or @code{@@c} within a line beginning with |
| 1315 a command. | 1393 such a command. |
| 1394 | |
| 1395 @findex DEL @r{(comment character)} | |
| 1396 @cindex Catcode for comments in @TeX{} | |
| 1397 In cases of nested command invocations, complicated macro definitions, | |
| 1398 etc., @code{@@c} and @code{@@comment} may provoke an error when | |
| 1399 processing with @TeX{}. Therefore, you can also use the @kbd{DEL} | |
| 1400 character (ASCII 127 decimal, 0x7f hex, 0177 octal) as a true @TeX{} | |
| 1401 comment character (catcode 14, in @TeX{} internals). Everything on | |
| 1402 the line after the @kbd{DEL} will be ignored. | |
| 1316 | 1403 |
| 1317 @cindex Ignored text | 1404 @cindex Ignored text |
| 1318 @cindex Unprocessed text | 1405 @cindex Unprocessed text |
| 1319 @findex ignore | 1406 @findex ignore |
| 1320 You can write long stretches of text that will not appear in either | 1407 You can also have long stretches of text to be ignored by the Texinfo |
| 1321 the Info file or the printed manual by using the @code{@@ignore} and | 1408 processors with the @code{@@ignore} and @code{@@end ignore} commands. |
| 1322 @code{@@end ignore} commands. Write each of these commands on a line | 1409 Write each of these commands on a line of its own, starting each |
| 1323 of its own, starting each command at the beginning of the line. Text | 1410 command at the beginning of the line. Text between these two commands |
| 1324 between these two commands does not appear in the processed output. | 1411 does not appear in the processed output. You can use @code{@@ignore} |
| 1325 You can use @code{@@ignore} and @code{@@end ignore} for writing | 1412 and @code{@@end ignore} for writing comments. (For some technical |
| 1326 comments. | 1413 caveats regarding nesting of such commands, @pxref{Conditional |
| 1327 | 1414 Nesting}.) |
| 1328 Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or | |
| 1329 @code{@@ifclear} conditions is ignored in the sense that it will not | |
| 1330 contribute to the formatted output. However, @TeX{} and makeinfo must | |
| 1331 still parse the ignored text, in order to understand when to @emph{stop} | |
| 1332 ignoring text from the source file; that means that you may still get | |
| 1333 error messages if you have invalid Texinfo commands within ignored text. | |
| 1334 | 1415 |
| 1335 | 1416 |
| 1336 @node Minimum | 1417 @node Minimum |
| 1337 @section What a Texinfo File Must Have | 1418 @section What a Texinfo File Must Have |
| 1338 @cindex Minimal Texinfo file (requirements) | 1419 @cindex Minimal Texinfo file (requirements) |
| 1340 @cindex Required in Texinfo file | 1421 @cindex Required in Texinfo file |
| 1341 @cindex Texinfo file minimum | 1422 @cindex Texinfo file minimum |
| 1342 | 1423 |
| 1343 By convention, the name of a Texinfo file ends with (in order of | 1424 By convention, the name of a Texinfo file ends with (in order of |
| 1344 preference) one of the extensions @file{.texinfo}, @file{.texi}, | 1425 preference) one of the extensions @file{.texinfo}, @file{.texi}, |
| 1345 @file{.txi}, or @file{.tex}. The longer extensions are preferred since | 1426 @file{.txi}, or @file{.tex}. The longer extensions are preferred |
| 1346 they describe more clearly to a human reader the nature of the file. | 1427 since they describe more clearly to a human reader the nature of the |
| 1347 The shorter extensions are for operating systems that cannot handle long | 1428 file. The shorter extensions are for operating systems that cannot |
| 1348 file names. | 1429 handle long file names. |
| 1349 | 1430 |
| 1350 In order to be made into a printed manual and an Info file, a Texinfo | 1431 In order to be made into a good printed manual and other output |
| 1351 file @strong{must} begin with lines like this: | 1432 formats, a Texinfo file @emph{must} begin with lines like this: |
| 1352 | 1433 |
| 1353 @example | 1434 @example |
| 1354 @group | 1435 @group |
| 1355 \input texinfo | 1436 \input texinfo |
| 1356 @@setfilename @var{info-file-name} | 1437 @@setfilename @var{info-file-name} |
| 1358 @end group | 1439 @end group |
| 1359 @end example | 1440 @end example |
| 1360 | 1441 |
| 1361 @noindent | 1442 @noindent |
| 1362 The contents of the file follow this beginning, and then you | 1443 The contents of the file follow this beginning, and then you |
| 1363 @strong{must} end a Texinfo file with a line like this: | 1444 @emph{must} end the Texinfo source with a line like this: |
| 1364 | 1445 |
| 1365 @example | 1446 @example |
| 1366 @@bye | 1447 @@bye |
| 1367 @end example | 1448 @end example |
| 1368 | 1449 |
| 1382 tells @TeX{} to open auxiliary files. @strong{All text before | 1463 tells @TeX{} to open auxiliary files. @strong{All text before |
| 1383 @code{@@setfilename} is ignored!} | 1464 @code{@@setfilename} is ignored!} |
| 1384 | 1465 |
| 1385 @item | 1466 @item |
| 1386 The @code{@@settitle} line specifies a title for the page headers (or | 1467 The @code{@@settitle} line specifies a title for the page headers (or |
| 1387 footers) of the printed manual, and the default document description for | 1468 footers) of the printed manual, and the default title and document |
| 1388 the @samp{<head>} in HTML format. Strictly speaking, @code{@@settitle} | 1469 description for the @samp{<head>} in HTML@. Strictly speaking, |
| 1389 is optional---if you don't mind your document being titled `Untitled'. | 1470 @code{@@settitle} is optional---if you don't mind your document being |
| 1471 titled `Untitled'. | |
| 1390 | 1472 |
| 1391 @item | 1473 @item |
| 1392 The @code{@@bye} line at the end of the file on a line of its own tells | 1474 The @code{@@bye} line at the end of the file on a line of its own tells |
| 1393 the formatters that the file is ended and to stop formatting. | 1475 the formatters that the file is ended and to stop formatting. |
| 1394 | |
| 1395 @end itemize | 1476 @end itemize |
| 1396 | 1477 |
| 1397 Typically, you will not use quite such a spare format, but will include | 1478 If you use XEmacs, it is also useful to include mode setting and |
| 1398 mode setting and start-of-header and end-of-header lines at the | 1479 start-of-header and end-of-header lines at the beginning of a Texinfo |
| 1399 beginning of a Texinfo file, like this: | 1480 file, like this: |
| 1400 | 1481 |
| 1401 @example | 1482 @example |
| 1402 @group | 1483 @group |
| 1403 \input texinfo @@c -*-texinfo-*- | 1484 \input texinfo @@c -*-texinfo-*- |
| 1404 @@c %**start of header | 1485 @@c %**start of header |
| 1410 | 1491 |
| 1411 @noindent | 1492 @noindent |
| 1412 In the first line, @samp{-*-texinfo-*-} causes XEmacs to switch into | 1493 In the first line, @samp{-*-texinfo-*-} causes XEmacs to switch into |
| 1413 Texinfo mode when you edit the file. | 1494 Texinfo mode when you edit the file. |
| 1414 | 1495 |
| 1415 The @code{@@c} lines which surround the @code{@@setfilename} and | 1496 The @code{@@c ...header} lines above which surround the |
| 1416 @code{@@settitle} lines are optional, but you need them in order to | 1497 @code{@@setfilename} and @code{@@settitle} lines allow you to process, |
| 1417 run @TeX{} or Info on just part of the file. (@xref{Start of Header}.) | 1498 within XEmacs, just part of the Texinfo source. (@xref{Start of |
| 1499 Header}.) | |
| 1418 | 1500 |
| 1419 Furthermore, you will usually provide a Texinfo file with a title page, | 1501 Furthermore, you will usually provide a Texinfo file with a title page, |
| 1420 indices, and the like, all of which are explained in this manual. But | 1502 indices, and the like, all of which are explained in this manual. But |
| 1421 the minimum, which can be useful for short documents, is just the three | 1503 the minimum, which can be useful for short documents, is just the three |
| 1422 lines at the beginning and the one line at the end. | 1504 lines at the beginning and the one line at the end. |
| 1508 @example | 1590 @example |
| 1509 @group | 1591 @group |
| 1510 @@copying | 1592 @@copying |
| 1511 This is a short example of a complete Texinfo file, version 1.0. | 1593 This is a short example of a complete Texinfo file, version 1.0. |
| 1512 | 1594 |
| 1513 Copyright @@copyright@{@} 2005 Free Software Foundation, Inc. | 1595 Copyright @@copyright@{@} 2013 Free Software Foundation, Inc. |
| 1514 @@end copying | 1596 @@end copying |
| 1515 @end group | 1597 @end group |
| 1516 @end example | 1598 @end example |
| 1517 | 1599 |
| 1518 @subheading Part 3: Titlepage, Contents, Copyright | 1600 @subheading Part 3: Titlepage, Contents, Copyright |
| 1656 @cindex Berry, Karl | 1738 @cindex Berry, Karl |
| 1657 Richard M. Stallman invented the Texinfo format, wrote the initial | 1739 Richard M. Stallman invented the Texinfo format, wrote the initial |
| 1658 processors, and created Edition 1.0 of this manual. Robert@tie{}J. | 1740 processors, and created Edition 1.0 of this manual. Robert@tie{}J. |
| 1659 Chassell greatly revised and extended the manual, starting with | 1741 Chassell greatly revised and extended the manual, starting with |
| 1660 Edition 1.1. Brian Fox was responsible for the standalone Texinfo | 1742 Edition 1.1. Brian Fox was responsible for the standalone Texinfo |
| 1661 distribution until version 3.8, and wrote the standalone | 1743 distribution until version 3.8, and originally wrote the standalone |
| 1662 @command{makeinfo} and @command{info} programs. Karl Berry has | 1744 @command{makeinfo} and @command{info} programs. Karl Berry has |
| 1663 continued maintenance since Texinfo 3.8 (manual edition 2.22). | 1745 continued maintenance since Texinfo 3.8 (manual edition 2.22). |
| 1664 | 1746 |
| 1665 @cindex Pinard, Fran@,{c}ois | 1747 @cindex Pinard, Fran@,{c}ois |
| 1666 @cindex Zuhn, David D. | 1748 @cindex Schwab, Andreas |
| 1749 @cindex Weinberg, Zack | |
| 1667 @cindex Weisshaus, Melissa | 1750 @cindex Weisshaus, Melissa |
| 1668 @cindex Zaretskii, Eli | 1751 @cindex Zaretskii, Eli |
| 1669 @cindex Schwab, Andreas | 1752 @cindex Zuhn, David D. |
| 1670 @cindex Weinberg, Zack | 1753 Our thanks go out to all who helped improve this work, particularly |
| 1671 Our thanks go out to all who helped improve this work, particularly the | 1754 the indefatigable Eli Zaretskii and Andreas Schwab, who have provided |
| 1672 indefatigable Eli Zaretskii and Andreas Schwab, who have provided | |
| 1673 patches beyond counting. Fran@,{c}ois Pinard and David@tie{}D. Zuhn, | 1755 patches beyond counting. Fran@,{c}ois Pinard and David@tie{}D. Zuhn, |
| 1674 tirelessly recorded and reported mistakes and obscurities. Zack | 1756 tirelessly recorded and reported mistakes and obscurities. Zack |
| 1675 Weinberg did the impossible by implementing the macro syntax in | 1757 Weinberg did the impossible by implementing the macro syntax in |
| 1676 @file{texinfo.tex}. Special thanks go to Melissa Weisshaus for her | 1758 @file{texinfo.tex}. Thanks to Melissa Weisshaus for her frequent |
| 1677 frequent reviews of nearly similar editions. Dozens of others have | 1759 reviews of nearly similar editions. Dozens of others have contributed |
| 1678 contributed patches and suggestions, they are gratefully acknowledged in | 1760 patches and suggestions, they are gratefully acknowledged in the |
| 1679 the @file{ChangeLog} file. Our mistakes are our own. | 1761 @file{ChangeLog} file. Our mistakes are our own. |
| 1762 | |
| 1763 @cindex History of Texinfo | |
| 1764 @cindex Texinfo history | |
| 1765 @subheading Beginnings | |
| 1680 | 1766 |
| 1681 @cindex Scribe | 1767 @cindex Scribe |
| 1682 @cindex Reid, Brian | 1768 @cindex Reid, Brian |
| 1683 @cindex History of Texinfo | 1769 In the 1970's at CMU, Brian Reid developed a program and format named |
| 1684 @cindex Texinfo history | 1770 Scribe to mark up documents for printing. It used the @code{@@} |
| 1685 A bit of history: in the 1970's at CMU, Brian Reid developed a program | 1771 character to introduce commands, as Texinfo does. Much more |
| 1686 and format named Scribe to mark up documents for printing. It used the | |
| 1687 @code{@@} character to introduce commands, as Texinfo does. Much more | |
| 1688 consequentially, it strove to describe document contents rather than | 1772 consequentially, it strove to describe document contents rather than |
| 1689 formatting, an idea wholeheartedly adopted by Texinfo. | 1773 formatting, an idea wholeheartedly adopted by Texinfo. |
| 1690 | 1774 |
| 1691 @cindex Bolio | 1775 @cindex Bolio |
| 1692 @cindex Bo@TeX{} | 1776 @cindex Bo@TeX{} |
| 1700 both Bolio and Bo@TeX{}. He also developed a nifty on-line help format | 1784 both Bolio and Bo@TeX{}. He also developed a nifty on-line help format |
| 1701 called Info, and then combined Bo@TeX{} and Info to create Texinfo, a | 1785 called Info, and then combined Bo@TeX{} and Info to create Texinfo, a |
| 1702 mark up language for text that is intended to be read both online and | 1786 mark up language for text that is intended to be read both online and |
| 1703 as printed hard copy. | 1787 as printed hard copy. |
| 1704 | 1788 |
| 1789 Moving forward, the original translator to create Info was written | |
| 1790 (primarily by RMS and Bob Chassell) in Emacs Lisp, namely the | |
| 1791 @code{texinfo-format-buffer} and other functions. In the early 1990s, | |
| 1792 Brian Fox reimplemented the conversion program in C, now called | |
| 1793 @command{makeinfo}. | |
| 1794 | |
| 1795 @subheading Reimplementing in Perl | |
| 1796 | |
| 1797 @cindex Cons, Lionel | |
| 1798 @cindex Dumas, Patrice | |
| 1799 In 2012, the C @command{makeinfo} was itself replaced by a Perl | |
| 1800 implementation generically called @command{texi2any}. This version | |
| 1801 supports the same level of output customization as | |
| 1802 @command{texi2html}, an independent program originally written by | |
| 1803 Lionel Cons, later with substantial work by many others. The many | |
| 1804 additional features needed to make @command{texi2html} a replacement | |
| 1805 for @command{makeinfo} were implemented by Patrice Dumas. The first | |
| 1806 never-released version of @command{texi2any} was based on the | |
| 1807 @command{texi2html} code. That implementation, however, was abandoned | |
| 1808 in favor of the current program, which parses the Texinfo input into a | |
| 1809 tree for processing. It still supports nearly all the features of | |
| 1810 @command{texi2html}. | |
| 1811 | |
| 1812 The new Perl program is much slower than the old C program. We hope | |
| 1813 the speed gap will close in the future, but it may not ever be | |
| 1814 entirely comparable. So why did we switch? In short, we intend and | |
| 1815 hope that the present program will be much easier than the previous C | |
| 1816 implementation of @command{makeinfo} to extend to different output | |
| 1817 styles, back-end output formats, and all other customizations. | |
| 1818 In more detail: | |
| 1819 | |
| 1820 @itemize @bullet | |
| 1821 @item HTML customization. Many GNU and other free software packages | |
| 1822 had been happily using the HTML customization features in | |
| 1823 @command{texi2html} for years. Thus, in effect two independent | |
| 1824 implementations of the Texinfo language had developed, and keeping | |
| 1825 them in sync was not simple. Adding the HTML customization possible | |
| 1826 in @command{texi2html} to a C program would have been an | |
| 1827 enormous effort. | |
| 1828 | |
| 1829 @item Unicode, and multilingual support generally, especially of east | |
| 1830 Asian languages. Although of course it's perfectly plausible to write | |
| 1831 such support in C, in the particular case of @command{makeinfo}, it | |
| 1832 would have been tantamount to rewriting the entire program. In Perl, | |
| 1833 much of that comes essentially for free. | |
| 1834 | |
| 1835 @item Additional back-ends. The @command{makeinfo} code had become | |
| 1836 convoluted to the point where adding a new back-end was quite complex, | |
| 1837 requiring complex interactions with existing back-ends. In contrast, | |
| 1838 our Perl implementation provides a clean tree-based representation for | |
| 1839 all back-ends to work from. People have requested numerous different | |
| 1840 back-ends (@LaTeX{}, the latest (X)HTML, @dots{}), and they will now | |
| 1841 be much more feasible to implement. Which leads to the last item: | |
| 1842 | |
| 1843 @item Making contributions easier. In general, due to the cleaner | |
| 1844 structure, the Perl program should be considerably easier than the C | |
| 1845 for anyone to read and contribute to, with the resulting obvious | |
| 1846 benefits. | |
| 1847 @end itemize | |
| 1848 | |
| 1849 @xref{Reference Implementation}, for more on the rationale for and | |
| 1850 role of @command{texi2any}. | |
| 1851 | |
| 1705 | 1852 |
| 1706 @node Texinfo Mode | 1853 @node Texinfo Mode |
| 1707 @chapter Using Texinfo Mode | 1854 @chapter Using Texinfo Mode |
| 1708 @cindex Texinfo mode | 1855 @cindex Texinfo mode |
| 1709 @cindex Mode, using Texinfo | 1856 @cindex Mode, using Texinfo |
| 1710 @cindex XEmacs | 1857 @cindex XEmacs |
| 1858 @cindex Emacs | |
| 1711 | 1859 |
| 1712 You may edit a Texinfo file with any text editor you choose. A Texinfo | 1860 You may edit a Texinfo file with any text editor you choose. A Texinfo |
| 1713 file is no different from any other ASCII file. However, XEmacs | 1861 file is no different from any other ASCII file. However, XEmacs |
| 1714 comes with a special mode, called Texinfo mode, that provides XEmacs | 1862 comes with a special mode, called Texinfo mode, that provides XEmacs |
| 1715 commands and tools to help ease your work. | 1863 commands and tools to help ease your work. |
| 1720 this chapter briefly and come back to it after reading succeeding | 1868 this chapter briefly and come back to it after reading succeeding |
| 1721 chapters which describe the Texinfo formatting language in detail. | 1869 chapters which describe the Texinfo formatting language in detail. |
| 1722 | 1870 |
| 1723 @menu | 1871 @menu |
| 1724 * Texinfo Mode Overview:: How Texinfo mode can help you. | 1872 * Texinfo Mode Overview:: How Texinfo mode can help you. |
| 1725 * XEmacs Editing:: Texinfo mode adds to XEmacs' general | 1873 * XEmacs Editing:: Texinfo mode adds to XEmacs' general |
| 1726 purpose editing features. | 1874 purpose editing features. |
| 1727 * Inserting:: How to insert frequently used @@-commands. | 1875 * Inserting:: How to insert frequently used @@-commands. |
| 1728 * Showing the Structure:: How to show the structure of a file. | 1876 * Showing the Structure:: How to show the structure of a file. |
| 1729 * Updating Nodes and Menus:: How to update or create new nodes and menus. | 1877 * Updating Nodes and Menus:: How to update or create new nodes and menus. |
| 1730 * Info Formatting:: How to format for Info. | 1878 * Info Formatting:: How to format for Info. |
| 1738 Texinfo mode provides special features for working with Texinfo files. | 1886 Texinfo mode provides special features for working with Texinfo files. |
| 1739 You can: | 1887 You can: |
| 1740 | 1888 |
| 1741 @itemize @bullet | 1889 @itemize @bullet |
| 1742 @item | 1890 @item |
| 1743 Insert frequently used @@-commands. @refill | 1891 Insert frequently used @@-commands. |
| 1744 | 1892 |
| 1745 @item | 1893 @item |
| 1746 Automatically create @code{@@node} lines. | 1894 Automatically create @code{@@node} lines. |
| 1747 | 1895 |
| 1748 @item | 1896 @item |
| 1749 Show the structure of a Texinfo source file.@refill | 1897 Show the structure of a Texinfo source file. |
| 1750 | 1898 |
| 1751 @item | 1899 @item |
| 1752 Automatically create or update the `Next', | 1900 Automatically create or update the `Next', |
| 1753 `Previous', and `Up' pointers of a node. | 1901 `Previous', and `Up' pointers of a node. |
| 1754 | 1902 |
| 1755 @item | 1903 @item |
| 1756 Automatically create or update menus.@refill | 1904 Automatically create or update menus. |
| 1757 | 1905 |
| 1758 @item | 1906 @item |
| 1759 Automatically create a master menu.@refill | 1907 Automatically create a master menu. |
| 1760 | 1908 |
| 1761 @item | 1909 @item |
| 1762 Format a part or all of a file for Info.@refill | 1910 Format a part or all of a file for Info. |
| 1763 | 1911 |
| 1764 @item | 1912 @item |
| 1765 Typeset and print part or all of a file.@refill | 1913 Typeset and print part or all of a file. |
| 1766 @end itemize | 1914 @end itemize |
| 1767 | 1915 |
| 1768 Perhaps the two most helpful features are those for inserting frequently | 1916 Perhaps the two most helpful features are those for inserting frequently |
| 1769 used @@-commands and for creating node pointers and menus.@refill | 1917 used @@-commands and for creating node pointers and menus. |
| 1770 | 1918 |
| 1771 @node XEmacs Editing | 1919 @node XEmacs Editing |
| 1772 @section The Usual XEmacs Editing Commands | 1920 @section The Usual XEmacs Editing Commands |
| 1773 | 1921 |
| 1774 In most cases, the usual Text mode commands work the same in Texinfo | 1922 In most cases, the usual Text mode commands work the same in Texinfo |
| 1777 difference concerns filling. In Texinfo mode, the paragraph | 1925 difference concerns filling. In Texinfo mode, the paragraph |
| 1778 separation variable and syntax table are redefined so that Texinfo | 1926 separation variable and syntax table are redefined so that Texinfo |
| 1779 commands that should be on lines of their own are not inadvertently | 1927 commands that should be on lines of their own are not inadvertently |
| 1780 included in paragraphs. Thus, the @kbd{M-q} (@code{fill-paragraph}) | 1928 included in paragraphs. Thus, the @kbd{M-q} (@code{fill-paragraph}) |
| 1781 command will refill a paragraph but not mix an indexing command on a | 1929 command will refill a paragraph but not mix an indexing command on a |
| 1782 line adjacent to it into the paragraph.@refill | 1930 line adjacent to it into the paragraph. |
| 1783 | 1931 |
| 1784 In addition, Texinfo mode sets the @code{page-delimiter} variable to | 1932 In addition, Texinfo mode sets the @code{page-delimiter} variable to |
| 1785 the value of @code{texinfo-chapter-level-regexp}; by default, this is | 1933 the value of @code{texinfo-chapter-level-regexp}; by default, this is |
| 1786 a regular expression matching the commands for chapters and their | 1934 a regular expression matching the commands for chapters and their |
| 1787 equivalents, such as appendices. With this value for the page | 1935 equivalents, such as appendices. With this value for the page |
| 1788 delimiter, you can jump from chapter title to chapter title with the | 1936 delimiter, you can jump from chapter title to chapter title with the |
| 1789 @kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [} | 1937 @kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [} |
| 1790 (@code{backward-page}) commands and narrow to a chapter with the | 1938 (@code{backward-page}) commands and narrow to a chapter with the |
| 1791 @kbd{C-x n p} (@code{narrow-to-page}) command. (@xref{Pages, , ,xemacs, | 1939 @kbd{C-x n p} (@code{narrow-to-page}) command. (@xref{Pages, , ,xemacs, |
| 1792 XEmacs User's Manual}, for details about the page commands.)@refill | 1940 XEmacs User's Manual}, for details about the page commands.) |
| 1793 | 1941 |
| 1794 You may name a Texinfo file however you wish, but the convention is to | 1942 You may name a Texinfo file however you wish, but the convention is to |
| 1795 end a Texinfo file name with one of the extensions | 1943 end a Texinfo file name with one of the extensions |
| 1796 @file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}. A longer | 1944 @file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}. A longer |
| 1797 extension is preferred, since it is explicit, but a shorter extension | 1945 extension is preferred, since it is explicit, but a shorter extension |
| 1800 file with a @file{.texinfo}, @file{.texi} or @file{.txi} | 1948 file with a @file{.texinfo}, @file{.texi} or @file{.txi} |
| 1801 extension. Also, XEmacs switches to Texinfo mode | 1949 extension. Also, XEmacs switches to Texinfo mode |
| 1802 when you visit a | 1950 when you visit a |
| 1803 file that has @samp{-*-texinfo-*-} in its first line. If ever you are | 1951 file that has @samp{-*-texinfo-*-} in its first line. If ever you are |
| 1804 in another mode and wish to switch to Texinfo mode, type @code{M-x | 1952 in another mode and wish to switch to Texinfo mode, type @code{M-x |
| 1805 texinfo-mode}.@refill | 1953 texinfo-mode}. |
| 1806 | 1954 |
| 1807 Like all other XEmacs features, you can customize or enhance Texinfo | 1955 Like all other XEmacs features, you can customize or enhance Texinfo |
| 1808 mode as you wish. In particular, the keybindings are very easy to | 1956 mode as you wish. In particular, the keybindings are very easy to |
| 1809 change. The keybindings described here are the default or standard | 1957 change. The keybindings described here are the default or standard |
| 1810 ones.@refill | 1958 ones. |
| 1811 | 1959 |
| 1812 @node Inserting | 1960 @node Inserting |
| 1813 @comment node-name, next, previous, up | |
| 1814 @section Inserting Frequently Used Commands | 1961 @section Inserting Frequently Used Commands |
| 1815 @cindex Inserting frequently used commands | 1962 @cindex Inserting frequently used commands |
| 1816 @cindex Frequently used commands, inserting | 1963 @cindex Frequently used commands, inserting |
| 1817 @cindex Commands, inserting them | 1964 @cindex Commands, inserting them |
| 1818 | 1965 |
| 1819 Texinfo mode provides commands to insert various frequently used | 1966 Texinfo mode provides commands to insert various frequently used |
| 1820 @@-commands into the buffer. You can use these commands to save | 1967 @@-commands into the buffer. You can use these commands to save |
| 1821 keystrokes.@refill | 1968 keystrokes. |
| 1822 | 1969 |
| 1823 The insert commands are invoked by typing @kbd{C-c} twice and then the | 1970 The insert commands are invoked by typing @kbd{C-c} twice and then the |
| 1824 first letter of the @@-command:@refill | 1971 first letter of the @@-command: |
| 1825 | 1972 |
| 1826 @table @kbd | 1973 @table @kbd |
| 1827 @item C-c C-c c | 1974 @item C-c C-c c |
| 1828 @itemx M-x texinfo-insert-@@code | 1975 @itemx M-x texinfo-insert-@@code |
| 1829 @findex texinfo-insert-@@code | 1976 @findex texinfo-insert-@@code |
| 1830 Insert @code{@@code@{@}} and put the | 1977 Insert @code{@@code@{@}} and put the |
| 1831 cursor between the braces.@refill | 1978 cursor between the braces. |
| 1832 | 1979 |
| 1833 @item C-c C-c d | 1980 @item C-c C-c d |
| 1834 @itemx M-x texinfo-insert-@@dfn | 1981 @itemx M-x texinfo-insert-@@dfn |
| 1835 @findex texinfo-insert-@@dfn | 1982 @findex texinfo-insert-@@dfn |
| 1836 Insert @code{@@dfn@{@}} and put the | 1983 Insert @code{@@dfn@{@}} and put the |
| 1837 cursor between the braces.@refill | 1984 cursor between the braces. |
| 1838 | 1985 |
| 1839 @item C-c C-c e | 1986 @item C-c C-c e |
| 1840 @itemx M-x texinfo-insert-@@end | 1987 @itemx M-x texinfo-insert-@@end |
| 1841 @findex texinfo-insert-@@end | 1988 @findex texinfo-insert-@@end |
| 1842 Insert @code{@@end} and attempt to insert the correct following word, | 1989 Insert @code{@@end} and attempt to insert the correct following word, |
| 1843 such as @samp{example} or @samp{table}. (This command does not handle | 1990 such as @samp{example} or @samp{table}. (This command does not handle |
| 1844 nested lists correctly, but inserts the word appropriate to the | 1991 nested lists correctly, but inserts the word appropriate to the |
| 1845 immediately preceding list.)@refill | 1992 immediately preceding list.) |
| 1846 | 1993 |
| 1847 @item C-c C-c i | 1994 @item C-c C-c i |
| 1848 @itemx M-x texinfo-insert-@@item | 1995 @itemx M-x texinfo-insert-@@item |
| 1849 @findex texinfo-insert-@@item | 1996 @findex texinfo-insert-@@item |
| 1850 Insert @code{@@item} and put the | 1997 Insert @code{@@item} and put the |
| 1851 cursor at the beginning of the next line.@refill | 1998 cursor at the beginning of the next line. |
| 1852 | 1999 |
| 1853 @item C-c C-c k | 2000 @item C-c C-c k |
| 1854 @itemx M-x texinfo-insert-@@kbd | 2001 @itemx M-x texinfo-insert-@@kbd |
| 1855 @findex texinfo-insert-@@kbd | 2002 @findex texinfo-insert-@@kbd |
| 1856 Insert @code{@@kbd@{@}} and put the | 2003 Insert @code{@@kbd@{@}} and put the |
| 1857 cursor between the braces.@refill | 2004 cursor between the braces. |
| 1858 | 2005 |
| 1859 @item C-c C-c n | 2006 @item C-c C-c n |
| 1860 @itemx M-x texinfo-insert-@@node | 2007 @itemx M-x texinfo-insert-@@node |
| 1861 @findex texinfo-insert-@@node | 2008 @findex texinfo-insert-@@node |
| 1862 Insert @code{@@node} and a comment line | 2009 Insert @code{@@node} and a comment line |
| 1863 listing the sequence for the `Next', | 2010 listing the sequence for the `Next', |
| 1864 `Previous', and `Up' nodes. | 2011 `Previous', and `Up' nodes. |
| 1865 Leave point after the @code{@@node}.@refill | 2012 Leave point after the @code{@@node}. |
| 1866 | 2013 |
| 1867 @item C-c C-c o | 2014 @item C-c C-c o |
| 1868 @itemx M-x texinfo-insert-@@noindent | 2015 @itemx M-x texinfo-insert-@@noindent |
| 1869 @findex texinfo-insert-@@noindent | 2016 @findex texinfo-insert-@@noindent |
| 1870 Insert @code{@@noindent} and put the | 2017 Insert @code{@@noindent} and put the |
| 1871 cursor at the beginning of the next line.@refill | 2018 cursor at the beginning of the next line. |
| 1872 | 2019 |
| 1873 @item C-c C-c s | 2020 @item C-c C-c s |
| 1874 @itemx M-x texinfo-insert-@@samp | 2021 @itemx M-x texinfo-insert-@@samp |
| 1875 @findex texinfo-insert-@@samp | 2022 @findex texinfo-insert-@@samp |
| 1876 Insert @code{@@samp@{@}} and put the | 2023 Insert @code{@@samp@{@}} and put the |
| 1877 cursor between the braces.@refill | 2024 cursor between the braces. |
| 1878 | 2025 |
| 1879 @item C-c C-c t | 2026 @item C-c C-c t |
| 1880 @itemx M-x texinfo-insert-@@table | 2027 @itemx M-x texinfo-insert-@@table |
| 1881 @findex texinfo-insert-@@table | 2028 @findex texinfo-insert-@@table |
| 1882 Insert @code{@@table} followed by a @key{SPC} | 2029 Insert @code{@@table} followed by a @key{SPC} |
| 1883 and leave the cursor after the @key{SPC}.@refill | 2030 and leave the cursor after the @key{SPC}. |
| 1884 | 2031 |
| 1885 @item C-c C-c v | 2032 @item C-c C-c v |
| 1886 @itemx M-x texinfo-insert-@@var | 2033 @itemx M-x texinfo-insert-@@var |
| 1887 @findex texinfo-insert-@@var | 2034 @findex texinfo-insert-@@var |
| 1888 Insert @code{@@var@{@}} and put the | 2035 Insert @code{@@var@{@}} and put the |
| 1889 cursor between the braces.@refill | 2036 cursor between the braces. |
| 1890 | 2037 |
| 1891 @item C-c C-c x | 2038 @item C-c C-c x |
| 1892 @itemx M-x texinfo-insert-@@example | 2039 @itemx M-x texinfo-insert-@@example |
| 1893 @findex texinfo-insert-@@example | 2040 @findex texinfo-insert-@@example |
| 1894 Insert @code{@@example} and put the | 2041 Insert @code{@@example} and put the |
| 1895 cursor at the beginning of the next line.@refill | 2042 cursor at the beginning of the next line. |
| 1896 | 2043 |
| 1897 @c M-@{ was the binding for texinfo-insert-braces; | 2044 @c M-@{ was the binding for texinfo-insert-braces; |
| 1898 @c in Emacs 19, backward-paragraph will take this binding. | 2045 @c in Emacs 19, backward-paragraph will take this binding. |
| 1899 @item C-c C-c @{ | 2046 @item C-c C-c @{ |
| 1900 @itemx M-x texinfo-insert-braces | 2047 @itemx M-x texinfo-insert-braces |
| 1901 @findex texinfo-insert-braces | 2048 @findex texinfo-insert-braces |
| 1902 Insert @code{@{@}} and put the cursor between the braces.@refill | 2049 Insert @code{@{@}} and put the cursor between the braces. |
| 1903 | 2050 |
| 1904 @item C-c @} | 2051 @item C-c @} |
| 1905 @itemx C-c ] | 2052 @itemx C-c ] |
| 1906 @itemx M-x up-list | 2053 @itemx M-x up-list |
| 1907 @findex up-list | 2054 @findex up-list |
| 1908 Move from between a pair of braces forward past the closing brace. | 2055 Move from between a pair of braces forward past the closing brace. |
| 1909 Typing @kbd{C-c ]} is easier than typing @kbd{C-c @}}, which | 2056 Typing @kbd{C-c ]} is easier than typing @kbd{C-c @}}, which |
| 1910 is, however, more mnemonic; hence the two keybindings. (Also, you can | 2057 is, however, more mnemonic; hence the two keybindings. (Also, you can |
| 1911 move out from between braces by typing @kbd{C-f}.)@refill | 2058 move out from between braces by typing @kbd{C-f}.) |
| 1912 @end table | 2059 @end table |
| 1913 | 2060 |
| 1914 To put a command such as @w{@code{@@code@{@dots{}@}}} around an | 2061 To put a command such as @w{@code{@@code@{@dots{}@}}} around an |
| 1915 @emph{existing} word, position the cursor in front of the word and type | 2062 @emph{existing} word, position the cursor in front of the word and type |
| 1916 @kbd{C-u 1 C-c C-c c}. This makes it easy to edit existing plain text. | 2063 @kbd{C-u 1 C-c C-c c}. This makes it easy to edit existing plain text. |
| 1918 point to include between braces---@samp{1} for one word, @samp{2} for | 2065 point to include between braces---@samp{1} for one word, @samp{2} for |
| 1919 two words, and so on. Use a negative argument to enclose the previous | 2066 two words, and so on. Use a negative argument to enclose the previous |
| 1920 word or words. If you do not specify a prefix argument, XEmacs inserts | 2067 word or words. If you do not specify a prefix argument, XEmacs inserts |
| 1921 the @@-command string and positions the cursor between the braces. This | 2068 the @@-command string and positions the cursor between the braces. This |
| 1922 feature works only for those @@-commands that operate on a word or words | 2069 feature works only for those @@-commands that operate on a word or words |
| 1923 within one line, such as @code{@@kbd} and @code{@@var}.@refill | 2070 within one line, such as @code{@@kbd} and @code{@@var}. |
| 1924 | 2071 |
| 1925 This set of insert commands was created after analyzing the frequency | 2072 This set of insert commands was created after analyzing the frequency |
| 1926 with which different @@-commands are used in the @cite{XEmacs | 2073 with which different @@-commands are used in the @cite{XEmacs User's |
| 1927 Manual} and the @cite{GDB Manual}. If you wish to add your own insert | 2074 Manual} and the @cite{GDB Manual}. If you wish to add your own insert |
| 1928 commands, you can bind a keyboard macro to a key, use abbreviations, | 2075 commands, you can bind a keyboard macro to a key, use abbreviations, |
| 1929 or extend the code in @file{texinfo.el}.@refill | 2076 or extend the code in @file{texinfo.el}. |
| 1930 | 2077 |
| 1931 @findex texinfo-start-menu-description | 2078 @findex texinfo-start-menu-description |
| 1932 @cindex Menu description, start | 2079 @cindex Menu description, start |
| 1933 @cindex Description for menu, start | 2080 @cindex Description for menu, start |
| 1934 @kbd{C-c C-c C-d} (@code{texinfo-start-menu-description}) is an insert | 2081 @kbd{C-c C-c C-d} (@code{texinfo-start-menu-description}) is an insert |
| 1935 command that works differently from the other insert commands. It | 2082 command that works differently from the other insert commands. It |
| 1936 inserts a node's section or chapter title in the space for the | 2083 inserts a node's section or chapter title in the space for the |
| 1937 description in a menu entry line. (A menu entry has three parts, the | 2084 description in a menu entry line. (A menu entry has three parts, the |
| 1938 entry name, the node name, and the description. Only the node name is | 2085 entry name, the node name, and the description. Only the node name is |
| 1939 required, but a description helps explain what the node is about. | 2086 required, but a description helps explain what the node is about. |
| 1940 @xref{Menu Parts, , The Parts of a Menu}.)@refill | 2087 @xref{Menu Parts, , The Parts of a Menu}.) |
| 1941 | 2088 |
| 1942 To use @code{texinfo-start-menu-description}, position point in a menu | 2089 To use @code{texinfo-start-menu-description}, position point in a menu |
| 1943 entry line and type @kbd{C-c C-c C-d}. The command looks for and copies | 2090 entry line and type @kbd{C-c C-c C-d}. The command looks for and copies |
| 1944 the title that goes with the node name, and inserts the title as a | 2091 the title that goes with the node name, and inserts the title as a |
| 1945 description; it positions point at beginning of the inserted text so you | 2092 description; it positions point at beginning of the inserted text so you |
| 1946 can edit it. The function does not insert the title if the menu entry | 2093 can edit it. The function does not insert the title if the menu entry |
| 1947 line already contains a description.@refill | 2094 line already contains a description. |
| 1948 | 2095 |
| 1949 This command is only an aid to writing descriptions; it does not do the | 2096 This command is only an aid to writing descriptions; it does not do the |
| 1950 whole job. You must edit the inserted text since a title tends to use | 2097 whole job. You must edit the inserted text since a title tends to use |
| 1951 the same words as a node name but a useful description uses different | 2098 the same words as a node name but a useful description uses different |
| 1952 words.@refill | 2099 words. |
| 1953 | 2100 |
| 1954 @node Showing the Structure | 2101 @node Showing the Structure |
| 1955 @comment node-name, next, previous, up | 2102 @section Showing the Sectioning Structure of a File |
| 1956 @section Showing the Section Structure of a File | 2103 @cindex Showing the sectioning structure of a file |
| 1957 @cindex Showing the section structure of a file | 2104 @cindex Sectioning structure of a file, showing |
| 1958 @cindex Section structure of a file, showing it | 2105 @cindex Structure of a file, showing |
| 1959 @cindex Structure of a file, showing it | 2106 @cindex Outline of file structure, showing |
| 1960 @cindex Outline of file structure, showing it | |
| 1961 @cindex Contents-like outline of file structure | 2107 @cindex Contents-like outline of file structure |
| 1962 @cindex File section structure, showing it | 2108 @cindex File sectioning structure, showing |
| 1963 @cindex Texinfo file section structure, showing it | 2109 @cindex Texinfo file sectioning structure, showing |
| 1964 | 2110 |
| 1965 You can show the section structure of a Texinfo file by using the | 2111 You can show the sectioning structure of a Texinfo file by using the |
| 1966 @kbd{C-c C-s} command (@code{texinfo-show-structure}). This command | 2112 @kbd{C-c C-s} command (@code{texinfo-show-structure}). This command |
| 1967 shows the section structure of a Texinfo file by listing the lines | 2113 lists the lines that begin with the @@-commands for @code{@@chapter}, |
| 1968 that begin with the @@-commands for @code{@@chapter}, | 2114 @code{@@section}, and the like. It constructs what amounts to a table |
| 1969 @code{@@section}, and the like. It constructs what amounts | 2115 of contents. These lines are displayed in another buffer called the |
| 1970 to a table of contents. These lines are displayed in another buffer | 2116 @samp{*Occur*} buffer. In that buffer, you can position the cursor |
| 1971 called the @samp{*Occur*} buffer. In that buffer, you can position | 2117 over one of the lines and use the @kbd{C-c C-c} command |
| 1972 the cursor over one of the lines and use the @kbd{C-c C-c} command | |
| 1973 (@code{occur-mode-goto-occurrence}), to jump to the corresponding spot | 2118 (@code{occur-mode-goto-occurrence}), to jump to the corresponding spot |
| 1974 in the Texinfo file.@refill | 2119 in the Texinfo file. |
| 1975 | 2120 |
| 1976 @table @kbd | 2121 @table @kbd |
| 1977 @item C-c C-s | 2122 @item C-c C-s |
| 1978 @itemx M-x texinfo-show-structure | 2123 @itemx M-x texinfo-show-structure |
| 1979 @findex texinfo-show-structure | 2124 @findex texinfo-show-structure |
| 1980 Show the @code{@@chapter}, @code{@@section}, and such lines of a | 2125 Show the @code{@@chapter}, @code{@@section}, and such lines of a |
| 1981 Texinfo file.@refill | 2126 Texinfo file. |
| 1982 | 2127 |
| 1983 @item C-c C-c | 2128 @item C-c C-c |
| 1984 @itemx M-x occur-mode-goto-occurrence | 2129 @itemx M-x occur-mode-goto-occurrence |
| 1985 @findex occur-mode-goto-occurrence | 2130 @findex occur-mode-goto-occurrence |
| 1986 Go to the line in the Texinfo file corresponding to the line under the | 2131 Go to the line in the Texinfo file corresponding to the line under the |
| 1987 cursor in the @file{*Occur*} buffer.@refill | 2132 cursor in the @file{*Occur*} buffer. |
| 1988 @end table | 2133 @end table |
| 1989 | 2134 |
| 1990 If you call @code{texinfo-show-structure} with a prefix argument by | 2135 If you call @code{texinfo-show-structure} with a prefix argument by |
| 1991 typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the | 2136 typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the |
| 1992 @@-commands for @code{@@chapter}, @code{@@section}, and the like, but | 2137 @@-commands for @code{@@chapter}, @code{@@section}, and the like, but |
| 1999 off the region of the buffer that you are interested in by using the | 2144 off the region of the buffer that you are interested in by using the |
| 2000 @kbd{C-x n n} (@code{narrow-to-region}) command and | 2145 @kbd{C-x n n} (@code{narrow-to-region}) command and |
| 2001 @code{texinfo-show-structure} will work on only that region. To see | 2146 @code{texinfo-show-structure} will work on only that region. To see |
| 2002 the whole buffer again, use @w{@kbd{C-x n w}} (@code{widen}). | 2147 the whole buffer again, use @w{@kbd{C-x n w}} (@code{widen}). |
| 2003 (@xref{Narrowing, , , xemacs, XEmacs User's Manual}, for more | 2148 (@xref{Narrowing, , , xemacs, XEmacs User's Manual}, for more |
| 2004 information about the narrowing commands.)@refill | 2149 information about the narrowing commands.) |
| 2005 | 2150 |
| 2006 @vindex page-delimiter | 2151 @vindex page-delimiter |
| 2007 @cindex Page delimiter in Texinfo mode | 2152 @cindex Page delimiter in Texinfo mode |
| 2008 In addition to providing the @code{texinfo-show-structure} command, | 2153 In addition to providing the @code{texinfo-show-structure} command, |
| 2009 Texinfo mode sets the value of the page delimiter variable to match | 2154 Texinfo mode sets the value of the page delimiter variable to match |
| 2010 the chapter-level @@-commands. This enables you to use the @kbd{C-x | 2155 the chapter-level @@-commands. This enables you to use the @kbd{C-x |
| 2011 ]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page}) | 2156 ]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page}) |
| 2012 commands to move forward and backward by chapter, and to use the | 2157 commands to move forward and backward by chapter, and to use the |
| 2013 @kbd{C-x n p} (@code{narrow-to-page}) command to narrow to a chapter. | 2158 @kbd{C-x n p} (@code{narrow-to-page}) command to narrow to a chapter. |
| 2014 @xref{Pages, , , xemacs, XEmacs User's Manual}, for more information | 2159 @xref{Pages, , , xemacs, XEmacs User's Manual}, for more information |
| 2015 about the page commands.@refill | 2160 about the page commands. |
| 2161 | |
| 2016 | 2162 |
| 2017 @node Updating Nodes and Menus | 2163 @node Updating Nodes and Menus |
| 2018 @comment node-name, next, previous, up | |
| 2019 @section Updating Nodes and Menus | 2164 @section Updating Nodes and Menus |
| 2165 | |
| 2020 @cindex Updating nodes and menus | 2166 @cindex Updating nodes and menus |
| 2021 @cindex Create nodes, menus automatically | 2167 @cindex Create nodes, menus automatically |
| 2022 @cindex Insert nodes, menus automatically | 2168 @cindex Insert nodes, menus automatically |
| 2023 @cindex Automatically insert nodes, menus | 2169 @cindex Automatically insert nodes, menus |
| 2024 | 2170 |
| 2027 because their most frequent use is for updating a Texinfo file after you | 2173 because their most frequent use is for updating a Texinfo file after you |
| 2028 have worked on it; but you can use them to insert the `Next', | 2174 have worked on it; but you can use them to insert the `Next', |
| 2029 `Previous', and `Up' pointers into an @code{@@node} line that has none | 2175 `Previous', and `Up' pointers into an @code{@@node} line that has none |
| 2030 and to create menus in a file that has none. | 2176 and to create menus in a file that has none. |
| 2031 | 2177 |
| 2032 If you do not use the updating commands, you need to write menus and | 2178 If you do not use any updating commands, you need to write menus and |
| 2033 node pointers by hand, which is a tedious task.@refill | 2179 node pointers by hand, which is a tedious task. |
| 2034 | 2180 |
| 2035 @menu | 2181 @menu |
| 2036 * Updating Commands:: Five major updating commands. | 2182 * Updating Commands:: Five major updating commands. |
| 2037 * Updating Requirements:: How to structure a Texinfo file for | 2183 * Updating Requirements:: How to structure a Texinfo file for |
| 2038 using the updating command. | 2184 using the updating command. |
| 2042 @end menu | 2188 @end menu |
| 2043 | 2189 |
| 2044 @node Updating Commands | 2190 @node Updating Commands |
| 2045 @subsection The Updating Commands | 2191 @subsection The Updating Commands |
| 2046 | 2192 |
| 2047 You can use the updating commands to:@refill | 2193 You can use the updating commands to: |
| 2048 | 2194 |
| 2049 @itemize @bullet | 2195 @itemize @bullet |
| 2050 @item | 2196 @item |
| 2051 insert or update the `Next', `Previous', and `Up' pointers of a | 2197 insert or update the `Next', `Previous', and `Up' pointers of a node, |
| 2052 node,@refill | |
| 2053 | 2198 |
| 2054 @item | 2199 @item |
| 2055 insert or update the menu for a section, and@refill | 2200 insert or update the menu for a section, and |
| 2056 | 2201 |
| 2057 @item | 2202 @item |
| 2058 create a master menu for a Texinfo source file.@refill | 2203 create a master menu for a Texinfo source file. |
| 2059 @end itemize | 2204 @end itemize |
| 2060 | 2205 |
| 2061 You can also use the commands to update all the nodes and menus in a | 2206 You can also use the commands to update all the nodes and menus in a |
| 2062 region or in a whole Texinfo file.@refill | 2207 region or in a whole Texinfo file. |
| 2063 | 2208 |
| 2064 The updating commands work only with conventional Texinfo files, which | 2209 The updating commands work only with conventional Texinfo files, which |
| 2065 are structured hierarchically like books. In such files, a structuring | 2210 are structured hierarchically like books. In such files, a structuring |
| 2066 command line must follow closely after each @code{@@node} line, except | 2211 command line must follow closely after each @code{@@node} line, except |
| 2067 for the `Top' @code{@@node} line. (A @dfn{structuring command line} is | 2212 for the `Top' @code{@@node} line. (A @dfn{structuring command line} is |
| 2085 | 2230 |
| 2086 The menu updating commands remove menu entries that refer to other Info | 2231 The menu updating commands remove menu entries that refer to other Info |
| 2087 files since they do not refer to nodes within the current buffer. This | 2232 files since they do not refer to nodes within the current buffer. This |
| 2088 is a deficiency. Rather than use menu entries, you can use cross | 2233 is a deficiency. Rather than use menu entries, you can use cross |
| 2089 references to refer to other Info files. None of the updating commands | 2234 references to refer to other Info files. None of the updating commands |
| 2090 affect cross references.@refill | 2235 affect cross references. |
| 2091 | 2236 |
| 2092 Texinfo mode has five updating commands that are used most often: two | 2237 Texinfo mode has five updating commands that are used most often: two |
| 2093 are for updating the node pointers or menu of a single node (or a | 2238 are for updating the node pointers or menu of a single node (or a |
| 2094 region); two are for updating every node pointer and menu in a file; | 2239 region); two are for updating every node pointer and menu in a file; |
| 2095 and one, the @code{texinfo-master-menu} command, is for creating a | 2240 and one, the @code{texinfo-master-menu} command, is for creating a |
| 2096 master menu for a complete file, and optionally, for updating every | 2241 master menu for a complete file, and optionally, for updating every |
| 2097 node and menu in the whole Texinfo file.@refill | 2242 node and menu in the whole Texinfo file. |
| 2098 | 2243 |
| 2099 The @code{texinfo-master-menu} command is the primary command:@refill | 2244 The @code{texinfo-master-menu} command is the primary command: |
| 2100 | 2245 |
| 2101 @table @kbd | 2246 @table @kbd |
| 2102 @item C-c C-u m | 2247 @item C-c C-u m |
| 2103 @itemx M-x texinfo-master-menu | 2248 @itemx M-x texinfo-master-menu |
| 2104 @findex texinfo-master-menu | 2249 @findex texinfo-master-menu |
| 2105 Create or update a master menu that includes all the other menus | 2250 Create or update a master menu that includes all the other menus |
| 2106 (incorporating the descriptions from pre-existing menus, if | 2251 (incorporating the descriptions from pre-existing menus, if |
| 2107 any).@refill | 2252 any). |
| 2108 | 2253 |
| 2109 With an argument (prefix argument, @kbd{C-u,} if interactive), first create or | 2254 With an argument (prefix argument, @kbd{C-u,} if interactive), first create or |
| 2110 update all the nodes and all the regular menus in the buffer before | 2255 update all the nodes and all the regular menus in the buffer before |
| 2111 constructing the master menu. (@xref{The Top Node, , The Top Node and | 2256 constructing the master menu. (@xref{The Top Node, , The Top Node and |
| 2112 Master Menu}, for more about a master menu.)@refill | 2257 Master Menu}, for more about a master menu.) |
| 2113 | 2258 |
| 2114 For @code{texinfo-master-menu} to work, the Texinfo file must have a | 2259 For @code{texinfo-master-menu} to work, the Texinfo file must have a |
| 2115 `Top' node and at least one subsequent node.@refill | 2260 `Top' node and at least one subsequent node. |
| 2116 | 2261 |
| 2117 After extensively editing a Texinfo file, you can type the following: | 2262 After extensively editing a Texinfo file, you can type the following: |
| 2118 | 2263 |
| 2119 @example | 2264 @example |
| 2120 C-u M-x texinfo-master-menu | 2265 C-u M-x texinfo-master-menu |
| 2121 @exdent or | 2266 @exdent or |
| 2122 C-u C-c C-u m | 2267 C-u C-c C-u m |
| 2123 @end example | 2268 @end example |
| 2124 | 2269 |
| 2125 @noindent | 2270 @noindent |
| 2126 This updates all the nodes and menus completely and all at once.@refill | 2271 This updates all the nodes and menus completely and all at once. |
| 2127 @end table | 2272 @end table |
| 2128 | 2273 |
| 2129 The other major updating commands do smaller jobs and are designed for | 2274 The other major updating commands do smaller jobs and are designed for |
| 2130 the person who updates nodes and menus as he or she writes a Texinfo | 2275 the person who updates nodes and menus as he or she writes a Texinfo |
| 2131 file.@refill | 2276 file. |
| 2132 | 2277 |
| 2133 @need 1000 | 2278 @need 1000 |
| 2134 The commands are:@refill | 2279 The commands are: |
| 2135 | 2280 |
| 2136 @table @kbd | 2281 @table @kbd |
| 2137 @item C-c C-u C-n | 2282 @item C-c C-u C-n |
| 2138 @itemx M-x texinfo-update-node | 2283 @itemx M-x texinfo-update-node |
| 2139 @findex texinfo-update-node | 2284 @findex texinfo-update-node |
| 2141 within (i.e., for the @code{@@node} line preceding point). If the | 2286 within (i.e., for the @code{@@node} line preceding point). If the |
| 2142 @code{@@node} line has pre-existing `Next', `Previous', or `Up' | 2287 @code{@@node} line has pre-existing `Next', `Previous', or `Up' |
| 2143 pointers in it, the old pointers are removed and new ones inserted. | 2288 pointers in it, the old pointers are removed and new ones inserted. |
| 2144 With an argument (prefix argument, @kbd{C-u}, if interactive), this command | 2289 With an argument (prefix argument, @kbd{C-u}, if interactive), this command |
| 2145 updates all @code{@@node} lines in the region (which is the text | 2290 updates all @code{@@node} lines in the region (which is the text |
| 2146 between point and mark).@refill | 2291 between point and mark). |
| 2147 | 2292 |
| 2148 @item C-c C-u C-m | 2293 @item C-c C-u C-m |
| 2149 @itemx M-x texinfo-make-menu | 2294 @itemx M-x texinfo-make-menu |
| 2150 @findex texinfo-make-menu | 2295 @findex texinfo-make-menu |
| 2151 Create or update the menu in the node that point is within. | 2296 Create or update the menu in the node that point is within. |
| 2152 With an argument (@kbd{C-u} as prefix argument, if | 2297 With an argument (@kbd{C-u} as prefix argument, if |
| 2153 interactive), the command makes or updates menus for the | 2298 interactive), the command makes or updates menus for the |
| 2154 nodes which are either within or a part of the | 2299 nodes which are either within or a part of the |
| 2155 region.@refill | 2300 region. |
| 2156 | 2301 |
| 2157 Whenever @code{texinfo-make-menu} updates an existing menu, the | 2302 Whenever @code{texinfo-make-menu} updates an existing menu, the |
| 2158 descriptions from that menu are incorporated into the new menu. This | 2303 descriptions from that menu are incorporated into the new menu. This |
| 2159 is done by copying descriptions from the existing menu to the entries | 2304 is done by copying descriptions from the existing menu to the entries |
| 2160 in the new menu that have the same node names. If the node names are | 2305 in the new menu that have the same node names. If the node names are |
| 2161 different, the descriptions are not copied to the new menu.@refill | 2306 different, the descriptions are not copied to the new menu. |
| 2162 | 2307 |
| 2163 @item C-c C-u C-e | 2308 @item C-c C-u C-e |
| 2164 @itemx M-x texinfo-every-node-update | 2309 @itemx M-x texinfo-every-node-update |
| 2165 @findex texinfo-every-node-update | 2310 @findex texinfo-every-node-update |
| 2166 Insert or update the `Next', `Previous', and `Up' pointers for every | 2311 Insert or update the `Next', `Previous', and `Up' pointers for every |
| 2167 node in the buffer.@refill | 2312 node in the buffer. |
| 2168 | 2313 |
| 2169 @item C-c C-u C-a | 2314 @item C-c C-u C-a |
| 2170 @itemx M-x texinfo-all-menus-update | 2315 @itemx M-x texinfo-all-menus-update |
| 2171 @findex texinfo-all-menus-update | 2316 @findex texinfo-all-menus-update |
| 2172 Create or update all the menus in the buffer. With an argument | 2317 Create or update all the menus in the buffer. With an argument |
| 2173 (@kbd{C-u} as prefix argument, if interactive), first insert | 2318 (@kbd{C-u} as prefix argument, if interactive), first insert |
| 2174 or update all the node | 2319 or update all the node |
| 2175 pointers before working on the menus.@refill | 2320 pointers before working on the menus. |
| 2176 | 2321 |
| 2177 If a master menu exists, the @code{texinfo-all-menus-update} command | 2322 If a master menu exists, the @code{texinfo-all-menus-update} command |
| 2178 updates it; but the command does not create a new master menu if none | 2323 updates it; but the command does not create a new master menu if none |
| 2179 already exists. (Use the @code{texinfo-master-menu} command for | 2324 already exists. (Use the @code{texinfo-master-menu} command for |
| 2180 that.)@refill | 2325 that.) |
| 2181 | 2326 |
| 2182 When working on a document that does not merit a master menu, you can | 2327 When working on a document that does not merit a master menu, you can |
| 2183 type the following: | 2328 type the following: |
| 2184 | 2329 |
| 2185 @example | 2330 @example |
| 2187 @exdent or | 2332 @exdent or |
| 2188 C-u M-x texinfo-all-menus-update | 2333 C-u M-x texinfo-all-menus-update |
| 2189 @end example | 2334 @end example |
| 2190 | 2335 |
| 2191 @noindent | 2336 @noindent |
| 2192 This updates all the nodes and menus.@refill | 2337 This updates all the nodes and menus. |
| 2193 @end table | 2338 @end table |
| 2194 | 2339 |
| 2195 The @code{texinfo-column-for-description} variable specifies the | 2340 The @code{texinfo-column-for-description} variable specifies the |
| 2196 column to which menu descriptions are indented. By default, the value | 2341 column to which menu descriptions are indented. By default, the value |
| 2197 is 32 although it can be useful to reduce it to as low as 24. You | 2342 is 32 although it can be useful to reduce it to as low as 24. You |
| 2202 | 2347 |
| 2203 Also, the @code{texinfo-indent-menu-description} command may be used to | 2348 Also, the @code{texinfo-indent-menu-description} command may be used to |
| 2204 indent existing menu descriptions to a specified column. Finally, if | 2349 indent existing menu descriptions to a specified column. Finally, if |
| 2205 you wish, you can use the @code{texinfo-insert-node-lines} command to | 2350 you wish, you can use the @code{texinfo-insert-node-lines} command to |
| 2206 insert missing @code{@@node} lines into a file. (@xref{Other Updating | 2351 insert missing @code{@@node} lines into a file. (@xref{Other Updating |
| 2207 Commands}, for more information.)@refill | 2352 Commands}, for more information.) |
| 2208 | 2353 |
| 2209 @node Updating Requirements | 2354 @node Updating Requirements |
| 2210 @subsection Updating Requirements | 2355 @subsection Updating Requirements |
| 2211 @cindex Updating requirements | 2356 @cindex Updating requirements |
| 2212 @cindex Requirements for updating commands | 2357 @cindex Requirements for updating commands |
| 2216 When you construct the hierarchy of the manual, do not `jump down' | 2361 When you construct the hierarchy of the manual, do not `jump down' |
| 2217 more than one level at a time: you can follow the `Top' node with a | 2362 more than one level at a time: you can follow the `Top' node with a |
| 2218 chapter, but not with a section; you can follow a chapter with a | 2363 chapter, but not with a section; you can follow a chapter with a |
| 2219 section, but not with a subsection. However, you may `jump up' any | 2364 section, but not with a subsection. However, you may `jump up' any |
| 2220 number of levels at one time---for example, from a subsection to a | 2365 number of levels at one time---for example, from a subsection to a |
| 2221 chapter.@refill | 2366 chapter. |
| 2222 | 2367 |
| 2223 Each @code{@@node} line, with the exception of the line for the `Top' | 2368 Each @code{@@node} line, with the exception of the line for the `Top' |
| 2224 node, must be followed by a line with a structuring command such as | 2369 node, must be followed by a line with a structuring command such as |
| 2225 @code{@@chapter}, @code{@@section}, or | 2370 @code{@@chapter}, @code{@@section}, or |
| 2226 @code{@@unnumberedsubsec}.@refill | 2371 @code{@@unnumberedsubsec}. |
| 2227 | 2372 |
| 2228 Each @code{@@node} line/structuring-command line combination | 2373 Each @code{@@node} line/structuring-command line combination |
| 2229 must look either like this: | 2374 must look either like this: |
| 2230 | 2375 |
| 2231 @example | 2376 @example |
| 2264 If a file has a `Top' node, it must be called @samp{top} or @samp{Top} | 2409 If a file has a `Top' node, it must be called @samp{top} or @samp{Top} |
| 2265 and be the first node in the file. | 2410 and be the first node in the file. |
| 2266 | 2411 |
| 2267 The menu updating commands create a menu of sections within a chapter, | 2412 The menu updating commands create a menu of sections within a chapter, |
| 2268 a menu of subsections within a section, and so on. This means that | 2413 a menu of subsections within a section, and so on. This means that |
| 2269 you must have a `Top' node if you want a menu of chapters.@refill | 2414 you must have a `Top' node if you want a menu of chapters. |
| 2270 | 2415 |
| 2271 Incidentally, the @code{makeinfo} command will create an Info file for a | 2416 Incidentally, the @code{makeinfo} command will create an Info file for a |
| 2272 hierarchically organized Texinfo file that lacks `Next', `Previous' and | 2417 hierarchically organized Texinfo file that lacks `Next', `Previous' and |
| 2273 `Up' pointers. Thus, if you can be sure that your Texinfo file will be | 2418 `Up' pointers. Thus, if you can be sure that your Texinfo file will be |
| 2274 formatted with @code{makeinfo}, you have no need for the update node | 2419 formatted with @code{makeinfo}, you have no need for the update node |
| 2280 | 2425 |
| 2281 @node Other Updating Commands | 2426 @node Other Updating Commands |
| 2282 @subsection Other Updating Commands | 2427 @subsection Other Updating Commands |
| 2283 | 2428 |
| 2284 In addition to the five major updating commands, Texinfo mode | 2429 In addition to the five major updating commands, Texinfo mode |
| 2285 possesses several less frequently used updating commands:@refill | 2430 possesses several less frequently used updating commands: |
| 2286 | 2431 |
| 2287 @table @kbd | 2432 @table @kbd |
| 2288 @item M-x texinfo-insert-node-lines | 2433 @item M-x texinfo-insert-node-lines |
| 2289 @findex texinfo-insert-node-lines | 2434 @findex texinfo-insert-node-lines |
| 2290 Insert @code{@@node} lines before the @code{@@chapter}, | 2435 Insert @code{@@node} lines before the @code{@@chapter}, |
| 2291 @code{@@section}, and other sectioning commands wherever they are | 2436 @code{@@section}, and other sectioning commands wherever they are |
| 2292 missing throughout a region in a Texinfo file.@refill | 2437 missing throughout a region in a Texinfo file. |
| 2293 | 2438 |
| 2294 With an argument (@kbd{C-u} as prefix argument, if interactive), the | 2439 With an argument (@kbd{C-u} as prefix argument, if interactive), the |
| 2295 @code{texinfo-insert-node-lines} command not only inserts | 2440 command @code{texinfo-insert-node-lines} not only inserts |
| 2296 @code{@@node} lines but also inserts the chapter or section titles as | 2441 @code{@@node} lines but also inserts the chapter or section titles as |
| 2297 the names of the corresponding nodes. In addition, it inserts the | 2442 the names of the corresponding nodes. In addition, it inserts the |
| 2298 titles as node names in pre-existing @code{@@node} lines that lack | 2443 titles as node names in pre-existing @code{@@node} lines that lack |
| 2299 names. Since node names should be more concise than section or | 2444 names. Since node names should be more concise than section or |
| 2300 chapter titles, you must manually edit node names so inserted.@refill | 2445 chapter titles, you must manually edit node names so inserted. |
| 2301 | 2446 |
| 2302 For example, the following marks a whole buffer as a region and inserts | 2447 For example, the following marks a whole buffer as a region and inserts |
| 2303 @code{@@node} lines and titles throughout:@refill | 2448 @code{@@node} lines and titles throughout: |
| 2304 | 2449 |
| 2305 @example | 2450 @example |
| 2306 C-x h C-u M-x texinfo-insert-node-lines | 2451 C-x h C-u M-x texinfo-insert-node-lines |
| 2307 @end example | 2452 @end example |
| 2308 | 2453 |
| 2319 the outer file. With a numeric prefix argument, such as @kbd{C-u 2}, first | 2464 the outer file. With a numeric prefix argument, such as @kbd{C-u 2}, first |
| 2320 update all the menus and all the `Next', `Previous', and `Up' pointers | 2465 update all the menus and all the `Next', `Previous', and `Up' pointers |
| 2321 of all the included files before creating and inserting a master menu in | 2466 of all the included files before creating and inserting a master menu in |
| 2322 the outer file. The @code{texinfo-multiple-files-update} command is | 2467 the outer file. The @code{texinfo-multiple-files-update} command is |
| 2323 described in the appendix on @code{@@include} files. | 2468 described in the appendix on @code{@@include} files. |
| 2324 @xref{texinfo-multiple-files-update}. | 2469 @xref{@t{texinfo-multiple-files-update}}. |
| 2325 | 2470 |
| 2326 @item M-x texinfo-indent-menu-description | 2471 @item M-x texinfo-indent-menu-description |
| 2327 @findex texinfo-indent-menu-description | 2472 @findex texinfo-indent-menu-description |
| 2328 Indent every description in the menu following point to the specified | 2473 Indent every description in the menu following point to the specified |
| 2329 column. You can use this command to give yourself more space for | 2474 column. You can use this command to give yourself more space for |
| 2330 descriptions. With an argument (@kbd{C-u} as prefix argument, if | 2475 descriptions. With an argument (@kbd{C-u} as prefix argument, if |
| 2331 interactive), the @code{texinfo-indent-menu-description} command indents | 2476 interactive), the @code{texinfo-indent-menu-description} command indents |
| 2332 every description in every menu in the region. However, this command | 2477 every description in every menu in the region. However, this command |
| 2333 does not indent the second and subsequent lines of a multi-line | 2478 does not indent the second and subsequent lines of a multi-line |
| 2334 description.@refill | 2479 description. |
| 2335 | 2480 |
| 2336 @item M-x texinfo-sequential-node-update | 2481 @item M-x texinfo-sequential-node-update |
| 2337 @findex texinfo-sequential-node-update | 2482 @findex texinfo-sequential-node-update |
| 2338 Insert the names of the nodes immediately following and preceding the | 2483 Insert the names of the nodes immediately following and preceding the |
| 2339 current node as the `Next' or `Previous' pointers regardless of those | 2484 current node as the `Next' or `Previous' pointers regardless of those |
| 2342 useful for novels and other documents that you read through | 2487 useful for novels and other documents that you read through |
| 2343 sequentially. (However, in Info, the @kbd{g *} command lets | 2488 sequentially. (However, in Info, the @kbd{g *} command lets |
| 2344 you look through the file sequentially, so sequentially ordered nodes | 2489 you look through the file sequentially, so sequentially ordered nodes |
| 2345 are not strictly necessary.) With an argument (prefix argument, if | 2490 are not strictly necessary.) With an argument (prefix argument, if |
| 2346 interactive), the @code{texinfo-sequential-node-update} command | 2491 interactive), the @code{texinfo-sequential-node-update} command |
| 2347 sequentially updates all the nodes in the region.@refill | 2492 sequentially updates all the nodes in the region. |
| 2348 @end table | 2493 @end table |
| 2349 | 2494 |
| 2350 @node Info Formatting | 2495 @node Info Formatting |
| 2351 @comment node-name, next, previous, up | |
| 2352 @section Formatting for Info | 2496 @section Formatting for Info |
| 2353 @cindex Formatting for Info | 2497 @cindex Formatting for Info |
| 2354 @cindex Running an Info formatter | 2498 @cindex Running an Info formatter |
| 2355 @cindex Info formatting | 2499 @cindex Info formatting |
| 2356 | 2500 |
| 2357 Texinfo mode provides several commands for formatting part or all of a | 2501 Texinfo mode provides several commands for formatting part or all of a |
| 2358 Texinfo file for Info. Often, when you are writing a document, you | 2502 Texinfo file for Info. Often, when you are writing a document, you |
| 2359 want to format only part of a file---that is, a region.@refill | 2503 want to format only part of a file---that is, a region. |
| 2360 | 2504 |
| 2361 You can use either the @code{texinfo-format-region} or the | 2505 You can use either the @code{texinfo-format-region} or the |
| 2362 @code{makeinfo-region} command to format a region:@refill | 2506 @code{makeinfo-region} command to format a region: |
| 2363 | 2507 |
| 2364 @table @kbd | 2508 @table @kbd |
| 2365 @findex texinfo-format-region | 2509 @findex texinfo-format-region |
| 2366 @item C-c C-e C-r | 2510 @item C-c C-e C-r |
| 2367 @itemx M-x texinfo-format-region | 2511 @itemx M-x texinfo-format-region |
| 2368 @itemx C-c C-m C-r | 2512 @itemx C-c C-m C-r |
| 2369 @itemx M-x makeinfo-region | 2513 @itemx M-x makeinfo-region |
| 2370 Format the current region for Info.@refill | 2514 Format the current region for Info. |
| 2371 @end table | 2515 @end table |
| 2372 | 2516 |
| 2373 You can use either the @code{texinfo-format-buffer} or the | 2517 You can use either the @code{texinfo-format-buffer} or the |
| 2374 @code{makeinfo-buffer} command to format a whole buffer:@refill | 2518 @code{makeinfo-buffer} command to format a whole buffer: |
| 2375 | 2519 |
| 2376 @table @kbd | 2520 @table @kbd |
| 2377 @findex texinfo-format-buffer | 2521 @findex texinfo-format-buffer |
| 2378 @item C-c C-e C-b | 2522 @item C-c C-e C-b |
| 2379 @itemx M-x texinfo-format-buffer | 2523 @itemx M-x texinfo-format-buffer |
| 2380 @itemx C-c C-m C-b | 2524 @itemx C-c C-m C-b |
| 2381 @itemx M-x makeinfo-buffer | 2525 @itemx M-x makeinfo-buffer |
| 2382 Format the current buffer for Info.@refill | 2526 Format the current buffer for Info. |
| 2383 @end table | 2527 @end table |
| 2384 | 2528 |
| 2385 @need 1000 | 2529 @need 1000 |
| 2386 For example, after writing a Texinfo file, you can type the following: | 2530 For example, after writing a Texinfo file, you can type the following: |
| 2387 | 2531 |
| 2402 @end example | 2546 @end example |
| 2403 | 2547 |
| 2404 For @TeX{} or the Info formatting commands to work, the file @emph{must} | 2548 For @TeX{} or the Info formatting commands to work, the file @emph{must} |
| 2405 include a line that has @code{@@setfilename} in its header. | 2549 include a line that has @code{@@setfilename} in its header. |
| 2406 | 2550 |
| 2407 @xref{Creating an Info File}, for details about Info formatting.@refill | 2551 @xref{Creating an Info File}, for details about Info formatting. |
| 2408 | 2552 |
| 2409 @node Printing | 2553 @node Printing |
| 2410 @comment node-name, next, previous, up | 2554 @comment node-name, next, previous, up |
| 2411 @section Printing | 2555 @section Printing |
| 2412 @cindex Formatting for printing | 2556 @cindex Formatting for printing |
| 2413 @cindex Printing a region or buffer | 2557 @cindex Printing a region or buffer |
| 2414 @cindex Region formatting and printing | 2558 @cindex Region formatting and printing |
| 2415 @cindex Buffer formatting and printing | 2559 @cindex Buffer formatting and printing |
| 2416 @cindex Part of file formatting and printing | 2560 @cindex Part of file formatting and printing |
| 2417 | 2561 |
| 2418 Typesetting and printing a Texinfo file is a multi-step process in which | 2562 Typesetting and printing a Texinfo file is a multi-step process in |
| 2419 you first create a file for printing (called a DVI file), and then | 2563 which you first create a file for printing (called a DVI file), and |
| 2420 print the file. Optionally, you may also create indices. To do this, | 2564 then print the file. Optionally, you may also create indices. To do |
| 2421 you must run the @code{texindex} command after first running the | 2565 this, you must run the @code{texindex} command after first running the |
| 2422 @code{tex} typesetting command; and then you must run the @code{tex} | 2566 @code{tex} typesetting command; and then you must run the @code{tex} |
| 2423 command again. Or else run the @code{texi2dvi} command which | 2567 command again. Or else run the @code{texi2dvi} command which |
| 2424 automatically creates indices as needed (@pxref{Format with texi2dvi}). | 2568 automatically creates indices as needed (@pxref{Format with |
| 2569 @t{texi2dvi}}). | |
| 2425 | 2570 |
| 2426 Often, when you are writing a document, you want to typeset and print | 2571 Often, when you are writing a document, you want to typeset and print |
| 2427 only part of a file to see what it will look like. You can use the | 2572 only part of a file to see what it will look like. You can use the |
| 2428 @code{texinfo-tex-region} and related commands for this purpose. Use | 2573 @code{texinfo-tex-region} and related commands for this purpose. Use |
| 2429 the @code{texinfo-tex-buffer} command to format all of a | 2574 the @code{texinfo-tex-buffer} command to format all of a |
| 2430 buffer.@refill | 2575 buffer. |
| 2431 | 2576 |
| 2432 @table @kbd | 2577 @table @kbd |
| 2433 @item C-c C-t C-b | 2578 @item C-c C-t C-b |
| 2434 @itemx M-x texinfo-tex-buffer | 2579 @itemx M-x texinfo-tex-buffer |
| 2435 @findex texinfo-tex-buffer | 2580 @findex texinfo-tex-buffer |
| 2436 Run @code{texi2dvi} on the buffer. In addition to running @TeX{} on the | 2581 Run @code{texi2dvi} on the buffer. In addition to running @TeX{} on the |
| 2437 buffer, this command automatically creates or updates indices as | 2582 buffer, this command automatically creates or updates indices as |
| 2438 needed.@refill | 2583 needed. |
| 2439 | 2584 |
| 2440 @item C-c C-t C-r | 2585 @item C-c C-t C-r |
| 2441 @itemx M-x texinfo-tex-region | 2586 @itemx M-x texinfo-tex-region |
| 2442 @findex texinfo-tex-region | 2587 @findex texinfo-tex-region |
| 2443 Run @TeX{} on the region.@refill | 2588 Run @TeX{} on the region. |
| 2444 | 2589 |
| 2445 @item C-c C-t C-i | 2590 @item C-c C-t C-i |
| 2446 @itemx M-x texinfo-texindex | 2591 @itemx M-x texinfo-texindex |
| 2447 Run @code{texindex} to sort the indices of a Texinfo file formatted with | 2592 Run @code{texindex} to sort the indices of a Texinfo file formatted with |
| 2448 @code{texinfo-tex-region}. The @code{texinfo-tex-region} command does | 2593 @code{texinfo-tex-region}. The @code{texinfo-tex-region} command does |
| 2449 not run @code{texindex} automatically; it only runs the @code{tex} | 2594 not run @code{texindex} automatically; it only runs the @code{tex} |
| 2450 typesetting command. You must run the @code{texinfo-tex-region} command | 2595 typesetting command. You must run the @code{texinfo-tex-region} command |
| 2451 a second time after sorting the raw index files with the @code{texindex} | 2596 a second time after sorting the raw index files with the @code{texindex} |
| 2452 command. (Usually, you do not format an index when you format a region, | 2597 command. (Usually, you do not format an index when you format a region, |
| 2453 only when you format a buffer. Now that the @code{texi2dvi} command | 2598 only when you format a buffer. Now that the @code{texi2dvi} command |
| 2454 exists, there is little or no need for this command.)@refill | 2599 exists, there is little or no need for this command.) |
| 2455 | 2600 |
| 2456 @item C-c C-t C-p | 2601 @item C-c C-t C-p |
| 2457 @itemx M-x texinfo-tex-print | 2602 @itemx M-x texinfo-tex-print |
| 2458 @findex texinfo-tex-print | 2603 @findex texinfo-tex-print |
| 2459 Print the file (or the part of the file) previously formatted with | 2604 Print the file (or the part of the file) previously formatted with |
| 2460 @code{texinfo-tex-buffer} or @code{texinfo-tex-region}.@refill | 2605 @code{texinfo-tex-buffer} or @code{texinfo-tex-region}. |
| 2461 @end table | 2606 @end table |
| 2462 | 2607 |
| 2463 For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the | 2608 For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the |
| 2464 file @emph{must} start with a @samp{\input texinfo} line and must | 2609 file @emph{must} start with a @samp{\input texinfo} line and must |
| 2465 include an @code{@@settitle} line. The file must end with @code{@@bye} | 2610 include an @code{@@settitle} line. The file must end with @code{@@bye} |
| 2466 on a line by itself. (When you use @code{texinfo-tex-region}, you must | 2611 on a line by itself. (When you use @code{texinfo-tex-region}, you must |
| 2467 surround the @code{@@settitle} line with start-of-header and | 2612 surround the @code{@@settitle} line with start-of-header and |
| 2468 end-of-header lines.)@refill | 2613 end-of-header lines.) |
| 2469 | 2614 |
| 2470 @xref{Hardcopy}, for a description of the other @TeX{} related | 2615 @xref{Hardcopy}, for a description of the other @TeX{} related |
| 2471 commands, such as @code{tex-show-print-queue}.@refill | 2616 commands, such as @code{tex-show-print-queue}. |
| 2472 | 2617 |
| 2473 @node Texinfo Mode Summary | 2618 @node Texinfo Mode Summary |
| 2474 @comment node-name, next, previous, up | |
| 2475 @section Texinfo Mode Summary | 2619 @section Texinfo Mode Summary |
| 2476 | 2620 |
| 2477 In Texinfo mode, each set of commands has default keybindings that | 2621 In Texinfo mode, each set of commands has default keybindings that |
| 2478 begin with the same keys. All the commands that are custom-created | 2622 begin with the same keys. All the commands that are custom-created |
| 2479 for Texinfo mode begin with @kbd{C-c}. The keys are somewhat | 2623 for Texinfo mode begin with @kbd{C-c}. The keys are somewhat |
| 2480 mnemonic.@refill | 2624 mnemonic. |
| 2481 | 2625 |
| 2482 @subheading Insert Commands | 2626 @subheading Insert Commands |
| 2483 | 2627 |
| 2484 The insert commands are invoked by typing @kbd{C-c} twice and then the | 2628 The insert commands are invoked by typing @kbd{C-c} twice and then the |
| 2485 first letter of the @@-command to be inserted. (It might make more | 2629 first letter of the @@-command to be inserted. (It might make more |
| 2486 sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but | 2630 sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but |
| 2487 @kbd{C-c C-c} is quick to type.)@refill | 2631 @kbd{C-c C-c} is quick to type.) |
| 2488 | 2632 |
| 2489 @example | 2633 @example |
| 2490 C-c C-c c @r{Insert} @samp{@@code}. | 2634 C-c C-c c @r{Insert} @samp{@@code}. |
| 2491 C-c C-c d @r{Insert} @samp{@@dfn}. | 2635 C-c C-c d @r{Insert} @samp{@@dfn}. |
| 2492 C-c C-c e @r{Insert} @samp{@@end}. | 2636 C-c C-c e @r{Insert} @samp{@@end}. |
| 2506 @end example | 2650 @end example |
| 2507 | 2651 |
| 2508 @subheading Show Structure | 2652 @subheading Show Structure |
| 2509 | 2653 |
| 2510 The @code{texinfo-show-structure} command is often used within a | 2654 The @code{texinfo-show-structure} command is often used within a |
| 2511 narrowed region.@refill | 2655 narrowed region. |
| 2512 | 2656 |
| 2513 @example | 2657 @example |
| 2514 C-c C-s @r{List all the headings.} | 2658 C-c C-s @r{List all the headings.} |
| 2515 @end example | 2659 @end example |
| 2516 | 2660 |
| 2517 @subheading The Master Update Command | 2661 @subheading The Master Update Command |
| 2518 | 2662 |
| 2519 The @code{texinfo-master-menu} command creates a master menu; and can | 2663 The @code{texinfo-master-menu} command creates a master menu; and can |
| 2520 be used to update every node and menu in a file as well.@refill | 2664 be used to update every node and menu in a file as well. |
| 2521 | 2665 |
| 2522 @c Probably should use @tables in this section. | 2666 @c Probably should use @tables in this section. |
| 2523 @example | 2667 @example |
| 2524 @group | 2668 @group |
| 2525 C-c C-u m | 2669 C-c C-u m |
| 2536 | 2680 |
| 2537 @subheading Update Pointers | 2681 @subheading Update Pointers |
| 2538 | 2682 |
| 2539 The update pointer commands are invoked by typing @kbd{C-c C-u} and | 2683 The update pointer commands are invoked by typing @kbd{C-c C-u} and |
| 2540 then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for | 2684 then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for |
| 2541 @code{texinfo-every-node-update}.@refill | 2685 @code{texinfo-every-node-update}. |
| 2542 | 2686 |
| 2543 @example | 2687 @example |
| 2544 C-c C-u C-n @r{Update a node.} | 2688 C-c C-u C-n @r{Update a node.} |
| 2545 C-c C-u C-e @r{Update every node in the buffer.} | 2689 C-c C-u C-e @r{Update every node in the buffer.} |
| 2546 @end example | 2690 @end example |
| 2549 | 2693 |
| 2550 Invoke the update menu commands by typing @kbd{C-c C-u} | 2694 Invoke the update menu commands by typing @kbd{C-c C-u} |
| 2551 and then either @kbd{C-m} for @code{texinfo-make-menu} or | 2695 and then either @kbd{C-m} for @code{texinfo-make-menu} or |
| 2552 @kbd{C-a} for @code{texinfo-all-menus-update}. To update | 2696 @kbd{C-a} for @code{texinfo-all-menus-update}. To update |
| 2553 both nodes and menus at the same time, precede @kbd{C-c C-u | 2697 both nodes and menus at the same time, precede @kbd{C-c C-u |
| 2554 C-a} with @kbd{C-u}.@refill | 2698 C-a} with @kbd{C-u}. |
| 2555 | 2699 |
| 2556 @example | 2700 @example |
| 2557 C-c C-u C-m @r{Make or update a menu.} | 2701 C-c C-u C-m @r{Make or update a menu.} |
| 2558 | 2702 |
| 2559 @group | 2703 @group |
| 2568 @end group | 2712 @end group |
| 2569 @end example | 2713 @end example |
| 2570 | 2714 |
| 2571 @subheading Format for Info | 2715 @subheading Format for Info |
| 2572 | 2716 |
| 2573 The Info formatting commands that are written in XEmacs Lisp are | 2717 The Info formatting commands that are written in Emacs Lisp are |
| 2574 invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region | 2718 invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region |
| 2575 or @kbd{C-b} for the whole buffer.@refill | 2719 or @kbd{C-b} for the whole buffer. |
| 2576 | 2720 |
| 2577 The Info formatting commands that are written in C and based on the | 2721 The Info formatting commands that are written in C and based on the |
| 2578 @code{makeinfo} program are invoked by typing @kbd{C-c C-m} and then | 2722 @code{makeinfo} program are invoked by typing @kbd{C-c C-m} and then |
| 2579 either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer.@refill | 2723 either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer. |
| 2580 | 2724 |
| 2581 @need 800 | 2725 @need 800 |
| 2582 @noindent | 2726 @noindent |
| 2583 Use the @code{texinfo-format@dots{}} commands: | 2727 Use the @code{texinfo-format@dots{}} commands: |
| 2584 | 2728 |
| 2603 @subheading Typeset and Print | 2747 @subheading Typeset and Print |
| 2604 | 2748 |
| 2605 The @TeX{} typesetting and printing commands are invoked by typing | 2749 The @TeX{} typesetting and printing commands are invoked by typing |
| 2606 @kbd{C-c C-t} and then another control command: @kbd{C-r} for | 2750 @kbd{C-c C-t} and then another control command: @kbd{C-r} for |
| 2607 @code{texinfo-tex-region}, @kbd{C-b} for @code{texinfo-tex-buffer}, | 2751 @code{texinfo-tex-region}, @kbd{C-b} for @code{texinfo-tex-buffer}, |
| 2608 and so on.@refill | 2752 and so on. |
| 2609 | 2753 |
| 2610 @example | 2754 @example |
| 2611 C-c C-t C-r @r{Run @TeX{} on the region.} | 2755 C-c C-t C-r @r{Run @TeX{} on the region.} |
| 2612 C-c C-t C-b @r{Run} @code{texi2dvi} @r{on the buffer.} | 2756 C-c C-t C-b @r{Run} @code{texi2dvi} @r{on the buffer.} |
| 2613 C-c C-t C-i @r{Run} @code{texindex}. | 2757 C-c C-t C-i @r{Run} @code{texindex}. |
| 2668 commands for handling the traditional frontmatter items in Texinfo. | 2812 commands for handling the traditional frontmatter items in Texinfo. |
| 2669 | 2813 |
| 2670 @cindex Frontmatter, text in | 2814 @cindex Frontmatter, text in |
| 2671 Straight text outside of any command before the Top node should be | 2815 Straight text outside of any command before the Top node should be |
| 2672 avoided. Such text is treated differently in the different output | 2816 avoided. Such text is treated differently in the different output |
| 2673 formats: visible in @TeX{} and HTML, by default not shown in Info | 2817 formats: at the time of writing, it is visible in @TeX{} and HTML, by |
| 2674 readers, and so on. | 2818 default not shown in Info readers, and so on. |
| 2675 | 2819 |
| 2676 @menu | 2820 @menu |
| 2677 * Sample Beginning:: A sample beginning for a Texinfo file. | 2821 * Sample Beginning:: A sample beginning for a Texinfo file. |
| 2678 * Texinfo File Header:: The first lines. | 2822 * Texinfo File Header:: The first lines. |
| 2679 * Document Permissions:: Ensuring your manual is free. | 2823 * Document Permissions:: Ensuring your manual is free. |
| 2680 * Titlepage & Copyright Page:: Creating the title and copyright pages. | 2824 * Titlepage & Copyright Page:: Creating the title and copyright pages. |
| 2681 * Contents:: How to create a table of contents. | 2825 * Contents:: How to create a table of contents. |
| 2682 * The Top Node:: Creating the `Top' node and master menu. | 2826 * The Top Node:: Creating the `Top' node and master menu. |
| 2683 * Global Document Commands:: Affecting formatting throughout. | 2827 * Global Document Commands:: Affecting formatting throughout. |
| 2684 * Software Copying Permissions:: Ensure that you and others continue to | |
| 2685 have the right to use and share software. | |
| 2686 @end menu | 2828 @end menu |
| 2687 | 2829 |
| 2688 | 2830 |
| 2689 @node Sample Beginning | 2831 @node Sample Beginning |
| 2690 @section Sample Texinfo File Beginning | 2832 @section Sample Texinfo File Beginning |
| 2769 @node Texinfo File Header | 2911 @node Texinfo File Header |
| 2770 @section Texinfo File Header | 2912 @section Texinfo File Header |
| 2771 @cindex Header for Texinfo files | 2913 @cindex Header for Texinfo files |
| 2772 @cindex Texinfo file header | 2914 @cindex Texinfo file header |
| 2773 | 2915 |
| 2774 Texinfo files start with at least three lines that provide Info and | 2916 Texinfo files start with at least three lines that provide Texinfo |
| 2775 @TeX{} with necessary information. These are the @code{\input texinfo} | 2917 translators with necessary information. These are the @code{\input |
| 2776 line, the @code{@@settitle} line, and the @code{@@setfilename} line. | 2918 texinfo} line, the @code{@@settitle} line, and the |
| 2777 | 2919 @code{@@setfilename} line. |
| 2778 Also, if you want to format just part of the Texinfo file, you must | 2920 |
| 2779 write the @code{@@settitle} and @code{@@setfilename} lines between | 2921 Also, if you want to format just part of the Texinfo file in XEmacs, |
| 2780 start-of-header and end-of-header lines. The start- and end-of-header | 2922 you must write the @code{@@settitle} and @code{@@setfilename} lines |
| 2781 lines are optional, but they do no harm, so you might as well always | 2923 between start-of-header and end-of-header lines. These start- and |
| 2782 include them. | 2924 end-of-header lines are optional, but they do no harm, so you might as |
| 2925 well always include them. | |
| 2783 | 2926 |
| 2784 Any command that affects document formatting as a whole makes sense to | 2927 Any command that affects document formatting as a whole makes sense to |
| 2785 include in the header. @code{@@synindex} (@pxref{synindex}), for | 2928 include in the header. @code{@@synindex} (@pxref{@t{@@synindex}}), |
| 2786 instance, is another command often included in the header. @xref{GNU | 2929 for instance, is another command often included in the header. |
| 2787 Sample Texts}, for complete sample texts. | 2930 |
| 2788 | 2931 Thus, the beginning of a Texinfo file generally looks approximately |
| 2789 Thus, the beginning of a Texinfo file generally looks like this: | 2932 like this: |
| 2790 | 2933 |
| 2791 @example | 2934 @example |
| 2792 @group | 2935 @group |
| 2793 \input texinfo @@c -*-texinfo-*- | 2936 \input texinfo @@c -*-texinfo-*- |
| 2794 @@c %**start of header | 2937 @@c %**start of header |
| 2796 @@settitle Sample Manual 1.0 | 2939 @@settitle Sample Manual 1.0 |
| 2797 @@c %**end of header | 2940 @@c %**end of header |
| 2798 @end group | 2941 @end group |
| 2799 @end example | 2942 @end example |
| 2800 | 2943 |
| 2944 (@xref{GNU Sample Texts}, for complete sample texts.) | |
| 2945 | |
| 2801 @menu | 2946 @menu |
| 2802 * First Line:: The first line of a Texinfo file. | 2947 * First Line:: The first line of a Texinfo file. |
| 2803 * Start of Header:: Formatting a region requires this. | 2948 * Start of Header:: Formatting a region requires this. |
| 2804 * setfilename:: Tell Info the name of the Info file. | 2949 * @t{@@setfilename}:: Tell Info the name of the Info file. |
| 2805 * settitle:: Create a title for the printed work. | 2950 * @t{@@settitle}:: Create a title for the printed work. |
| 2806 * End of Header:: Formatting a region requires this. | 2951 * End of Header:: Formatting a region requires this. |
| 2807 @end menu | 2952 @end menu |
| 2808 | 2953 |
| 2809 | 2954 |
| 2810 @node First Line | 2955 @node First Line |
| 2857 globally affect the document formatting, such as @code{@@synindex} or | 3002 globally affect the document formatting, such as @code{@@synindex} or |
| 2858 @code{@@footnotestyle}; and then by an end-of-header line (@pxref{End of | 3003 @code{@@footnotestyle}; and then by an end-of-header line (@pxref{End of |
| 2859 Header}). | 3004 Header}). |
| 2860 | 3005 |
| 2861 The start- and end-of-header lines allow you to format only part of a | 3006 The start- and end-of-header lines allow you to format only part of a |
| 2862 Texinfo file for Info or printing. @xref{texinfo-format commands}. | 3007 Texinfo file for Info or printing. @xref{@t{texinfo-format} commands}. |
| 2863 | 3008 |
| 2864 The odd string of characters, @samp{%**}, is to ensure that no other | 3009 The odd string of characters, @samp{%**}, is to ensure that no other |
| 2865 comment is accidentally taken for a start-of-header line. You can | 3010 comment is accidentally taken for a start-of-header line. You can |
| 2866 change it if you wish by setting the @code{tex-start-of-header} and/or | 3011 change it if you wish by setting the @code{tex-start-of-header} and/or |
| 2867 @code{tex-end-of-header} XEmacs variables. @xref{Texinfo Mode Printing}. | 3012 @code{tex-end-of-header} XEmacs variables. @xref{Texinfo Mode Printing}. |
| 2868 | 3013 |
| 2869 | 3014 |
| 2870 @node setfilename | 3015 @node @t{@@setfilename} |
| 2871 @subsection @code{@@setfilename}: Set the output file name | 3016 @subsection @code{@@setfilename}: Set the Output File Name |
| 3017 | |
| 3018 @anchor{setfilename}@c old name | |
| 2872 @findex setfilename | 3019 @findex setfilename |
| 2873 @cindex Texinfo requires @code{@@setfilename} | 3020 @cindex Texinfo requires @code{@@setfilename} |
| 2874 | 3021 @cindex Output file name, required |
| 2875 In order to serve as the primary input file for either @code{makeinfo} | 3022 |
| 2876 or @TeX{}, a Texinfo file must contain a line that looks like this: | 3023 The first Texinfo command (that is, after the @code{\input texinfo}) |
| 3024 in a document is generally @code{@@setfilename}: | |
| 2877 | 3025 |
| 2878 @example | 3026 @example |
| 2879 @@setfilename @var{info-file-name} | 3027 @@setfilename @var{info-file-name} |
| 2880 @end example | 3028 @end example |
| 2881 | 3029 |
| 3030 This command is required for @TeX{}, and very strongly recommended for | |
| 3031 @code{makeinfo}. | |
| 3032 | |
| 2882 Write the @code{@@setfilename} command at the beginning of a line and | 3033 Write the @code{@@setfilename} command at the beginning of a line and |
| 2883 follow it on the same line by the Info file name. Do not write anything | 3034 follow it on the same line by the Info file name. Do not write |
| 2884 else on the line; anything on the line after the command is considered | 3035 anything else on the line. |
| 2885 part of the file name, including what would otherwise be a | |
| 2886 comment. | |
| 2887 | 3036 |
| 2888 @cindex Ignored before @code{@@setfilename} | 3037 @cindex Ignored before @code{@@setfilename} |
| 2889 @cindex @samp{\input} source line ignored | 3038 @cindex @samp{\input} source line ignored |
| 2890 The Info formatting commands ignore everything written before the | 3039 When an @code{@@setfilename} line is present, the Texinfo processors |
| 2891 @code{@@setfilename} line, which is why the very first line of | 3040 ignore everything written before the @code{@@setfilename} line. This |
| 2892 the file (the @code{\input} line) does not show up in the output. | 3041 is why the very first line of the file (the @code{\input} line) does |
| 3042 not show up in the output. | |
| 2893 | 3043 |
| 2894 The @code{@@setfilename} line specifies the name of the output file to | 3044 The @code{@@setfilename} line specifies the name of the output file to |
| 2895 be generated. This name must be different from the name of the Texinfo | 3045 be generated. This name must be different from the name of the |
| 2896 file. There are two conventions for choosing the name: you can either | 3046 Texinfo file. There are two conventions for choosing the name: you |
| 2897 remove the extension (such as @samp{.texi}) entirely from the input file | 3047 can either remove the extension (such as @samp{.texi}) entirely from |
| 2898 name, or, preferably, replace it with the @samp{.info} extension. | 3048 the input file name, or (recommended) replace it with the @samp{.info} |
| 3049 extension. | |
| 2899 | 3050 |
| 2900 @cindex Length of file names | 3051 @cindex Length of file names |
| 2901 @cindex File name collision | 3052 @cindex File name collision |
| 2902 @cindex Info file name, choosing | 3053 @cindex Info file name, choosing |
| 2903 Although an explicit @samp{.info} extension is preferable, some | 3054 Although an explicit @samp{.info} extension is preferable, some |
| 2905 problem even when the file name you specify is itself short enough. | 3056 problem even when the file name you specify is itself short enough. |
| 2906 This occurs because the Info formatters split a long Info file into | 3057 This occurs because the Info formatters split a long Info file into |
| 2907 short indirect subfiles, and name them by appending @samp{-1}, | 3058 short indirect subfiles, and name them by appending @samp{-1}, |
| 2908 @samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original | 3059 @samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original |
| 2909 file name. (@xref{Tag and Split Files}.) The subfile name | 3060 file name. (@xref{Tag and Split Files}.) The subfile name |
| 2910 @file{texinfo.info-10}, for example, is too long for old systems with a | 3061 @file{texinfo.info-10}, for example, is too long for old systems with |
| 2911 14-character limit on filenames; so the Info file name for this document | 3062 a 14-character limit on filenames; so the Info file name for this |
| 2912 is @file{texinfo} rather than @file{texinfo.info}. When @code{makeinfo} | 3063 document is @file{texinfo} rather than @file{texinfo.info}. When |
| 2913 is running on operating systems such as MS-DOS which impose severe | 3064 @code{makeinfo} is running on operating systems such as MS-DOS which |
| 2914 limits on file names, it may remove some characters from the original | 3065 impose severe limits on file names, it may remove some characters from |
| 2915 file name to leave enough space for the subfile suffix, thus producing | 3066 the original file name to leave enough space for the subfile suffix, |
| 2916 files named @file{texin-10}, @file{gcc.i12}, etc. | 3067 thus producing files named @file{texin-10}, @file{gcc.i12}, etc. |
| 2917 | 3068 |
| 2918 When producing HTML output, @code{makeinfo} will replace any extension | 3069 When producing another output format, @code{makeinfo} will replace any |
| 2919 with @samp{html}, or add @samp{.html} if the given name has no | 3070 final extension with the output format-specific extension (@samp{html} |
| 2920 extension. | 3071 when generating HTML, for example), or add a dot followed by the |
| 3072 extension (@samp{.html} for HTML) if the given name has no extension. | |
| 2921 | 3073 |
| 2922 @pindex texinfo.cnf | 3074 @pindex texinfo.cnf |
| 2923 The @code{@@setfilename} line produces no output when you typeset a | 3075 The @code{@@setfilename} line produces no output when you typeset a |
| 2924 manual with @TeX{}, but it is nevertheless essential: it opens the | 3076 manual with @TeX{}, but it is nevertheless essential: it opens the |
| 2925 index, cross-reference, and other auxiliary files used by Texinfo, and | 3077 index and other auxiliary files used by Texinfo, and also reads |
| 2926 also reads @file{texinfo.cnf} if that file is present on your system | 3078 @file{texinfo.cnf} if that file is present on your system |
| 2927 (@pxref{Preparing for TeX,, Preparing for @TeX{}}). | 3079 (@pxref{Preparing for @TeX{}}). |
| 2928 | 3080 |
| 2929 | 3081 If there is no @code{@@setfilename} line, @code{makeinfo} uses the |
| 2930 @node settitle | 3082 input file name to determine the output name: first, any of the |
| 2931 @subsection @code{@@settitle}: Set the document title | 3083 extensions @code{.texi}, @code{.tex}, @code{.txi} or @code{.texinfo} |
| 3084 is removed from the input file name; then, the output format specific | |
| 3085 extension is added---@code{.html} when generating HTML, @code{.info} | |
| 3086 when generating Info, etc. The @code{\input} line is still ignored in | |
| 3087 this processing, as well as leading blank lines. | |
| 3088 | |
| 3089 See also the @option{--output} option in @ref{Invoking @t{texi2any}}. | |
| 3090 | |
| 3091 | |
| 3092 @node @t{@@settitle} | |
| 3093 @subsection @code{@@settitle}: Set the Document Title | |
| 3094 | |
| 3095 @anchor{settitle}@c old name | |
| 2932 @findex settitle | 3096 @findex settitle |
| 2933 | 3097 @cindex Document title, specifying |
| 2934 In order to be made into a printed manual, a Texinfo file must contain | 3098 |
| 2935 a line that looks like this: | 3099 A Texinfo file should contain a line that looks like this: |
| 2936 | 3100 |
| 2937 @example | 3101 @example |
| 2938 @@settitle @var{title} | 3102 @@settitle @var{title} |
| 2939 @end example | 3103 @end example |
| 2940 | 3104 |
| 2941 Write the @code{@@settitle} command at the beginning of a line and | 3105 Write the @code{@@settitle} command at the beginning of a line and |
| 2942 follow it on the same line by the title. This tells @TeX{} the title to | 3106 follow it on the same line by the title. Do not write anything else |
| 2943 use in a header or footer. Do not write anything else on the line; | 3107 on the line. The @code{@@settitle} command should precede everything |
| 2944 anything on the line after the command is considered part of the title, | 3108 that generates actual output. The best place for it is right after |
| 2945 including what would otherwise be a comment. | 3109 the @code{@@setfilename} command (described in the previous section). |
| 2946 | 3110 |
| 2947 The @code{@@settitle} command should precede everything that generates | 3111 This command tells @TeX{} the title to use in a header or footer |
| 2948 actual output. The best place for it is right after the | 3112 for double-sided output, in case such headings are output. For |
| 2949 @code{@@setfilename} command (see the previous section). | 3113 more on headings for @TeX{}, see @ref{Heading Generation}. |
| 2950 | 3114 |
| 2951 @cindex <title> HTML tag | 3115 @cindex @code{<title>} HTML tag |
| 2952 In the HTML file produced by @command{makeinfo}, @var{title} serves as | 3116 In the HTML file produced by @command{makeinfo}, @var{title} serves as |
| 2953 the document @samp{<title>}. It also becomes the default document | 3117 the document @samp{<title>}. It also becomes the default document |
| 2954 description in the @samp{<head>} part (@pxref{documentdescription}). | 3118 description in the @samp{<head>} part |
| 2955 | 3119 (@pxref{@t{@@documentdescription}}). |
| 2956 The title in the @code{@@settitle} command does not affect the title as | 3120 |
| 2957 it appears on the title page. Thus, the two do not need not match | 3121 When the title page is used in the output, the title in the |
| 2958 exactly. A practice we recommend is to include the version or edition | 3122 @code{@@settitle} command does not affect the title as it appears on |
| 2959 number of the manual in the @code{@@settitle} title; on the title page, | 3123 the title page. Thus, the two do not need not to match exactly. A |
| 2960 the version number generally appears as a @code{@@subtitle} so it would | 3124 practice we recommend is to include the version or edition number of |
| 2961 be omitted from the @code{@@title}. @xref{titlepage}. | 3125 the manual in the @code{@@settitle} title; on the title page, the |
| 2962 | 3126 version number generally appears as an @code{@@subtitle} so it would |
| 2963 Conventionally, when @TeX{} formats a Texinfo file for double-sided | 3127 be omitted from the @code{@@title}. @xref{@t{@@titlepage}}. |
| 2964 output, the title is printed in the left-hand (even-numbered) page | |
| 2965 headings and the current chapter title is printed in the right-hand | |
| 2966 (odd-numbered) page headings. (@TeX{} learns the title of each chapter | |
| 2967 from each @code{@@chapter} command.) By default, no page footer is | |
| 2968 printed. | |
| 2969 | |
| 2970 Even if you are printing in a single-sided style, @TeX{} looks for an | |
| 2971 @code{@@settitle} command line, in case you include the manual title | |
| 2972 in the heading. | |
| 2973 | |
| 2974 @TeX{} prints page headings only for that text that comes after the | |
| 2975 @code{@@end titlepage} command in the Texinfo file, or that comes | |
| 2976 after an @code{@@headings} command that turns on headings. | |
| 2977 (@xref{headings on off, , The @code{@@headings} Command}, for more | |
| 2978 information.) | |
| 2979 | |
| 2980 You may, if you wish, create your own, customized headings and footings. | |
| 2981 @xref{Headings}, for a detailed discussion of this. | |
| 2982 | 3128 |
| 2983 | 3129 |
| 2984 @node End of Header | 3130 @node End of Header |
| 2985 @subsection End of Header | 3131 @subsection End of Header |
| 2986 @cindex End of header line | 3132 @cindex End of header line |
| 3004 appear in several places in the various Texinfo output formats. | 3150 appear in several places in the various Texinfo output formats. |
| 3005 Therefore, Texinfo provides a command (@code{@@copying}) to declare | 3151 Therefore, Texinfo provides a command (@code{@@copying}) to declare |
| 3006 this text once, and another command (@code{@@insertcopying}) to | 3152 this text once, and another command (@code{@@insertcopying}) to |
| 3007 insert the text at appropriate points. | 3153 insert the text at appropriate points. |
| 3008 | 3154 |
| 3155 @anchor{Software Copying Permissions}@c old node name | |
| 3156 This section is about the license of the Texinfo document. If the | |
| 3157 document is a software manual, the software is typically under a | |
| 3158 different license---for GNU and many other free software packages, | |
| 3159 software is usually released under the GNU GPL, and manuals are | |
| 3160 released under the GNU FDL@. It is helpful to state the license of | |
| 3161 the software of the manual, but giving the complete text of the | |
| 3162 software license is not necessarily required. | |
| 3163 | |
| 3009 @menu | 3164 @menu |
| 3010 * copying:: Declare the document's copying permissions. | 3165 * @t{@@copying}:: Declare the document's copying permissions. |
| 3011 * insertcopying:: Where to insert the permissions. | 3166 * @t{@@insertcopying}:: Where to insert the permissions. |
| 3012 @end menu | 3167 @end menu |
| 3013 | 3168 |
| 3014 | 3169 |
| 3015 @node copying | 3170 @node @t{@@copying} |
| 3016 @subsection @code{@@copying}: Declare Copying Permissions | 3171 @subsection @code{@@copying}: Declare Copying Permissions |
| 3172 | |
| 3173 @anchor{copying}@c old name | |
| 3017 @findex copying | 3174 @findex copying |
| 3018 | 3175 |
| 3019 The @code{@@copying} command should be given very early in the document; | 3176 The @code{@@copying} command should be given very early in the document; |
| 3020 the recommended location is right after the header material | 3177 the recommended location is right after the header material |
| 3021 (@pxref{Texinfo File Header}). It conventionally consists of a sentence | 3178 (@pxref{Texinfo File Header}). It conventionally consists of a sentence |
| 3037 @end example | 3194 @end example |
| 3038 | 3195 |
| 3039 The @code{@@quotation} has no legal significance; it's there to improve | 3196 The @code{@@quotation} has no legal significance; it's there to improve |
| 3040 readability in some contexts. | 3197 readability in some contexts. |
| 3041 | 3198 |
| 3042 @xref{GNU Sample Texts}, for the full text to be used in GNU manuals. | |
| 3043 @xref{GNU Free Documentation License}, for the license itself under | |
| 3044 which GNU and other free manuals are distributed. You need to include | |
| 3045 the license as an appendix to your document. | |
| 3046 | |
| 3047 The text of @code{@@copying} is output as a comment at the beginning of | 3199 The text of @code{@@copying} is output as a comment at the beginning of |
| 3048 Info, HTML, and XML output files. It is @emph{not} output implicitly in | 3200 Info, HTML, and XML output files. It is @emph{not} output implicitly in |
| 3049 plain text or @TeX{}; it's up to you to use @code{@@insertcopying} to | 3201 plain text or @TeX{}; it's up to you to use @code{@@insertcopying} to |
| 3050 emit the copying information. See the next section for details. | 3202 emit the copying information. See the next section for details. |
| 3051 | 3203 |
| 3052 @findex copyright | 3204 @findex copyright |
| 3053 The @code{@@copyright@{@}} command generates a @samp{c} inside a circle | 3205 The @code{@@copyright@{@}} command generates a @samp{c} inside a |
| 3054 in output formats that support this (print and HTML). In the other | 3206 circle when the output format supports this glyph (print and HTML |
| 3055 formats (Info and plain text), it generates @samp{(C)}. The copyright | 3207 always do, for instance). When the glyph is not supported in the |
| 3056 notice itself has the following legally defined sequence: | 3208 output, it generates the three-character sequence @samp{(C)}. |
| 3209 | |
| 3210 The copyright notice itself has the following legally-prescribed | |
| 3211 form: | |
| 3057 | 3212 |
| 3058 @example | 3213 @example |
| 3059 Copyright @copyright{} @var{years} @var{copyright-owner}. | 3214 Copyright @copyright{} @var{years} @var{copyright-owner}. |
| 3060 @end example | 3215 @end example |
| 3061 | 3216 |
| 3064 document is otherwise written in another language. This is due to | 3219 document is otherwise written in another language. This is due to |
| 3065 international law. | 3220 international law. |
| 3066 | 3221 |
| 3067 @cindex Years, in copyright line | 3222 @cindex Years, in copyright line |
| 3068 The list of years should include all years in which a version was | 3223 The list of years should include all years in which a version was |
| 3069 completed (even if it was released in a subsequent year). Ranges are | 3224 completed (even if it was released in a subsequent year). It is |
| 3070 not allowed; each year must be written out individually and in full, | 3225 simplest for each year to be written out individually and in full, |
| 3071 separated by commas. | 3226 separated by commas. |
| 3072 | 3227 |
| 3073 @cindex Copyright holder for FSF works | 3228 @cindex Copyright holder for FSF works |
| 3074 @cindex Holder of copyright for FSF works | 3229 @cindex Holder of copyright for FSF works |
| 3075 @cindex Owner of copyright for FSF works | 3230 @cindex Owner of copyright for FSF works |
| 3081 in the source document and in the output. This often happens for | 3236 in the source document and in the output. This often happens for |
| 3082 documents with a long history, having many different years of | 3237 documents with a long history, having many different years of |
| 3083 publication. If you do use several lines, do not indent any of them | 3238 publication. If you do use several lines, do not indent any of them |
| 3084 (or anything else in the @code{@@copying} block) in the source file. | 3239 (or anything else in the @code{@@copying} block) in the source file. |
| 3085 | 3240 |
| 3086 @xref{Copyright Notices,,,maintain,GNU Maintenance Instructions}, for | 3241 @xref{Copyright Notices,,, maintain, GNU Maintainer Information}, for |
| 3087 additional information. | 3242 additional information. @xref{GNU Sample Texts}, for the full text to |
| 3088 | 3243 be used in GNU manuals. @xref{GNU Free Documentation License}, for |
| 3089 | 3244 the license itself under which GNU and other free manuals are |
| 3090 @node insertcopying | 3245 distributed. |
| 3246 | |
| 3247 | |
| 3248 @node @t{@@insertcopying} | |
| 3091 @subsection @code{@@insertcopying}: Include Permissions Text | 3249 @subsection @code{@@insertcopying}: Include Permissions Text |
| 3250 | |
| 3251 @anchor{insertcopying}@c old name | |
| 3092 @findex insertcopying | 3252 @findex insertcopying |
| 3093 @cindex Copying text, including | 3253 @cindex Copying text, including |
| 3094 @cindex Permissions text, including | 3254 @cindex Permissions text, including |
| 3095 @cindex Including permissions text | 3255 @cindex Including permissions text |
| 3096 | 3256 |
| 3116 Similarly, the @code{@@copying} text is automatically included at the | 3276 Similarly, the @code{@@copying} text is automatically included at the |
| 3117 beginning of each HTML output file, as an HTML comment. Again, this | 3277 beginning of each HTML output file, as an HTML comment. Again, this |
| 3118 text is not visible (unless the reader views the HTML source). | 3278 text is not visible (unless the reader views the HTML source). |
| 3119 | 3279 |
| 3120 The permissions text defined by @code{@@copying} also appears | 3280 The permissions text defined by @code{@@copying} also appears |
| 3121 automatically at the beginning of the XML output file. | 3281 automatically at the beginning of the XML and Docbook output files. |
| 3122 | 3282 |
| 3123 | 3283 |
| 3124 @node Titlepage & Copyright Page | 3284 @node Titlepage & Copyright Page |
| 3125 @section Title and Copyright Pages | 3285 @section Title and Copyright Pages |
| 3126 | 3286 |
| 3127 In hard copy output, the manual's name and author are usually printed on | 3287 In hard copy output, the manual's name and author are usually printed on |
| 3128 a title page. Copyright information is usually printed on the back of | 3288 a title page. Copyright information is usually printed on the back of |
| 3129 the title page. | 3289 the title page. |
| 3130 | 3290 |
| 3131 The title and copyright pages appear in the printed manual, but not in | 3291 The title and copyright pages appear in printed manuals, but not in |
| 3132 the Info file. Because of this, it is possible to use several slightly | 3292 most other output formats. Because of this, it is possible to use |
| 3133 obscure @TeX{} typesetting commands that cannot be used in an Info file. | 3293 several slightly obscure typesetting commands that are not to be used |
| 3134 In addition, this part of the beginning of a Texinfo file contains the | 3294 in the main text. In addition, this part of the beginning of a |
| 3135 text of the copying permissions that appears in the printed manual. | 3295 Texinfo file contains the text of the copying permissions that appears |
| 3136 | 3296 in the printed manual. |
| 3137 @cindex Title page, for plain text | |
| 3138 @cindex Copyright page, for plain text | |
| 3139 You may wish to include titlepage-like information for plain text | |
| 3140 output. Simply place any such leading material between | |
| 3141 @code{@@ifplaintext} and @code{@@end ifplaintext}; @command{makeinfo} | |
| 3142 includes this when writing plain text (@samp{--no-headers}), along with | |
| 3143 an @code{@@insertcopying}. | |
| 3144 | 3297 |
| 3145 @menu | 3298 @menu |
| 3146 * titlepage:: Create a title for the printed document. | 3299 * @t{@@titlepage}:: Create a title for the printed document. |
| 3147 * titlefont center sp:: The @code{@@titlefont}, @code{@@center}, | 3300 * @t{@@titlefont @@center @@sp}:: The @code{@@titlefont}, @code{@@center}, |
| 3148 and @code{@@sp} commands. | 3301 and @code{@@sp} commands. |
| 3149 * title subtitle author:: The @code{@@title}, @code{@@subtitle}, | 3302 * @t{@@title @@subtitle @@author}:: The @code{@@title}, @code{@@subtitle}, |
| 3150 and @code{@@author} commands. | 3303 and @code{@@author} commands. |
| 3151 * Copyright:: How to write the copyright notice and | 3304 * Copyright:: How to write the copyright notice and |
| 3152 include copying permissions. | 3305 include copying permissions. |
| 3153 * end titlepage:: Turn on page headings after the title and | 3306 * Heading Generation:: Turn on page headings after the title and |
| 3154 copyright pages. | 3307 copyright pages. |
| 3155 * headings on off:: An option for turning headings on and off | |
| 3156 and double or single sided printing. | |
| 3157 @end menu | 3308 @end menu |
| 3158 | 3309 |
| 3159 | 3310 |
| 3160 @node titlepage | 3311 @node @t{@@titlepage} |
| 3161 @subsection @code{@@titlepage} | 3312 @subsection @code{@@titlepage} |
| 3313 | |
| 3314 @anchor{titlepage}@c old name | |
| 3162 @cindex Title page | 3315 @cindex Title page |
| 3163 @findex titlepage | 3316 @findex titlepage |
| 3164 | 3317 |
| 3165 Start the material for the title page and following copyright page | 3318 Start the material for the title page and following copyright page |
| 3166 with @code{@@titlepage} on a line by itself and end it with | 3319 with @code{@@titlepage} on a line by itself and end it with |
| 3167 @code{@@end titlepage} on a line by itself. | 3320 @code{@@end titlepage} on a line by itself. |
| 3168 | 3321 |
| 3169 The @code{@@end titlepage} command starts a new page and turns on page | 3322 The @code{@@end titlepage} command starts a new page and turns on page |
| 3170 numbering. (@xref{Headings, , Page Headings}, for details about how to | 3323 numbering (@pxref{Heading Generation}). All the |
| 3171 generate page headings.) All the material that you want to appear on | 3324 material that you want to appear on unnumbered pages should be put |
| 3172 unnumbered pages should be put between the @code{@@titlepage} and | 3325 between the @code{@@titlepage} and @code{@@end titlepage} commands. |
| 3173 @code{@@end titlepage} commands. You can force the table of contents to | 3326 You can force the table of contents to appear there with the |
| 3174 appear there with the @code{@@setcontentsaftertitlepage} command | 3327 @code{@@setcontentsaftertitlepage} command (@pxref{Contents}). |
| 3175 (@pxref{Contents}). | |
| 3176 | 3328 |
| 3177 @findex page@r{, within @code{@@titlepage}} | 3329 @findex page@r{, within @code{@@titlepage}} |
| 3178 By using the @code{@@page} command you can force a page break within the | 3330 By using the @code{@@page} command you can force a page break within the |
| 3179 region delineated by the @code{@@titlepage} and @code{@@end titlepage} | 3331 region delineated by the @code{@@titlepage} and @code{@@end titlepage} |
| 3180 commands and thereby create more than one unnumbered page. This is how | 3332 commands and thereby create more than one unnumbered page. This is how |
| 3210 the sections below. | 3362 the sections below. |
| 3211 | 3363 |
| 3212 @findex shorttitlepage | 3364 @findex shorttitlepage |
| 3213 @cindex Bastard title page | 3365 @cindex Bastard title page |
| 3214 @cindex Title page, bastard | 3366 @cindex Title page, bastard |
| 3215 For extremely simple documents, and for the bastard title page in | 3367 For sufficiently simple documents, and for the bastard title page in |
| 3216 traditional book frontmatter, Texinfo also provides a command | 3368 traditional book frontmatter, Texinfo also provides a command |
| 3217 @code{@@shorttitlepage} which takes the rest of the line as the title. | 3369 @code{@@shorttitlepage} which takes the rest of the line as the title. |
| 3218 The argument is typeset on a page by itself and followed by a blank | 3370 The argument is typeset on a page by itself and followed by a blank |
| 3219 page. | 3371 page. |
| 3220 | 3372 |
| 3221 | 3373 |
| 3222 @node titlefont center sp | 3374 @node @t{@@titlefont @@center @@sp} |
| 3223 @subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp} | 3375 @subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp} |
| 3376 | |
| 3377 @anchor{titlefont center sp}@c old name | |
| 3224 @findex titlefont | 3378 @findex titlefont |
| 3225 @findex center | 3379 @findex center |
| 3226 @findex sp @r{(titlepage line spacing)} | 3380 @findex sp @r{(titlepage line spacing)} |
| 3227 | 3381 |
| 3228 You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center} | 3382 You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center} |
| 3234 have an especially long title. | 3388 have an especially long title. |
| 3235 | 3389 |
| 3236 For HTML output, each @code{@@titlefont} command produces an | 3390 For HTML output, each @code{@@titlefont} command produces an |
| 3237 @code{<h1>} heading, but the HTML document @code{<title>} is not | 3391 @code{<h1>} heading, but the HTML document @code{<title>} is not |
| 3238 affected. For that, you must put an @code{@@settitle} command before | 3392 affected. For that, you must put an @code{@@settitle} command before |
| 3239 the @code{@@titlefont} command (@pxref{settitle}). | 3393 the @code{@@titlefont} command (@pxref{@t{@@settitle}}). |
| 3240 | 3394 |
| 3241 @need 700 | 3395 @need 700 |
| 3242 For example: | 3396 For example: |
| 3243 | 3397 |
| 3244 @example | 3398 @example |
| 3261 @example | 3415 @example |
| 3262 @@sp 2 | 3416 @@sp 2 |
| 3263 @end example | 3417 @end example |
| 3264 | 3418 |
| 3265 @noindent | 3419 @noindent |
| 3266 This inserts two blank lines on the printed page. (@xref{sp, , | 3420 This inserts two blank lines on the printed page. |
| 3267 @code{@@sp}}, for more information about the @code{@@sp} | 3421 (@xref{@t{@@sp}}, for more information about the @code{@@sp} |
| 3268 command.) | 3422 command.) |
| 3269 | 3423 |
| 3270 A template for this method looks like this: | 3424 A template for this method looks like this: |
| 3271 | 3425 |
| 3272 @example | 3426 @example |
| 3287 | 3441 |
| 3288 You can in fact use these commands anywhere, not just on a title page, | 3442 You can in fact use these commands anywhere, not just on a title page, |
| 3289 but since they are not logical markup commands, we don't recommend | 3443 but since they are not logical markup commands, we don't recommend |
| 3290 them. | 3444 them. |
| 3291 | 3445 |
| 3292 @node title subtitle author | 3446 @node @t{@@title @@subtitle @@author} |
| 3293 @subsection @code{@@title}, @code{@@subtitle}, and @code{@@author} | 3447 @subsection @code{@@title}, @code{@@subtitle}, and @code{@@author} |
| 3448 | |
| 3449 @anchor{title subtitle author}@c old name | |
| 3294 @findex title | 3450 @findex title |
| 3295 @findex subtitle | 3451 @findex subtitle |
| 3296 @findex author | 3452 @findex author |
| 3297 | 3453 |
| 3298 You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author} | 3454 You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author} |
| 3301 described in the previous section, in which the @code{@@sp} command is | 3457 described in the previous section, in which the @code{@@sp} command is |
| 3302 needed to adjust vertical spacing. | 3458 needed to adjust vertical spacing. |
| 3303 | 3459 |
| 3304 Write the @code{@@title}, @code{@@subtitle}, or @code{@@author} | 3460 Write the @code{@@title}, @code{@@subtitle}, or @code{@@author} |
| 3305 commands at the beginning of a line followed by the title, subtitle, | 3461 commands at the beginning of a line followed by the title, subtitle, |
| 3306 or author. These commands are only effective in @TeX{} output; it's | 3462 or author. The @code{@@author} command may be used for a quotation in |
| 3307 an error to use them anywhere except within @code{@@titlepage}. | 3463 an @code{@@quotation} block (@pxref{@t{@@quotation}}); |
| 3464 except for that, it is an error to use any of these commands outside | |
| 3465 of @code{@@titlepage}. | |
| 3308 | 3466 |
| 3309 The @code{@@title} command produces a line in which the title is set | 3467 The @code{@@title} command produces a line in which the title is set |
| 3310 flush to the left-hand side of the page in a larger than normal font. | 3468 flush to the left-hand side of the page in a larger than normal font. |
| 3311 The title is underlined with a black rule. Only a single line is | 3469 The title is underlined with a black rule. The title must be given on |
| 3312 allowed; the @code{@@*} command may not be used to break the title into | 3470 a single line in the source file; it will be broken into multiple |
| 3313 two lines. To handle very long titles, you may find it profitable to | 3471 lines of output is needed. |
| 3314 use both @code{@@title} and @code{@@titlefont}; see the final example in | 3472 |
| 3315 this section. | 3473 For long titles, the @code{@@*} command may be used to specify the |
| 3474 line breaks in long titles if the automatic breaks do not suit. Such | |
| 3475 explicit line breaks are generally reflected in all output formats; if | |
| 3476 you only want to specify them for the printed output, use a | |
| 3477 conditional (@pxref{Conditionals}). For example: | |
| 3478 | |
| 3479 @example | |
| 3480 @@title This Long Title@@inlinefmt@{tex,@@*@} Is Broken in @@TeX@{@} | |
| 3481 @end example | |
| 3316 | 3482 |
| 3317 The @code{@@subtitle} command sets subtitles in a normal-sized font | 3483 The @code{@@subtitle} command sets subtitles in a normal-sized font |
| 3318 flush to the right-hand side of the page. | 3484 flush to the right-hand side of the page. |
| 3319 | 3485 |
| 3320 The @code{@@author} command sets the names of the author or authors in | 3486 The @code{@@author} command sets the names of the author or authors in |
| 3321 a middle-sized font flush to the left-hand side of the page on a line | 3487 a middle-sized font flush to the left-hand side of the page on a line |
| 3322 near the bottom of the title page. The names are underlined with a | 3488 near the bottom of the title page. The names are followed by a black |
| 3323 black rule that is thinner than the rule that underlines the title. | 3489 rule that is thinner than the rule that underlines the title. |
| 3324 (The black rule only occurs if the @code{@@author} command line is | |
| 3325 followed by an @code{@@page} command line.) | |
| 3326 | 3490 |
| 3327 There are two ways to use the @code{@@author} command: you can write | 3491 There are two ways to use the @code{@@author} command: you can write |
| 3328 the name or names on the remaining part of the line that starts with | 3492 the name or names on the remaining part of the line that starts with |
| 3329 an @code{@@author} command: | 3493 an @code{@@author} command: |
| 3330 | 3494 |
| 3331 @example | 3495 @example |
| 3332 @@author by Jane Smith and John Doe | 3496 @@author by Jane Smith and John Doe |
| 3333 @end example | 3497 @end example |
| 3334 | 3498 |
| 3335 @noindent | 3499 @noindent |
| 3336 or you can write the names one above each other by using two (or more) | 3500 or you can write the names one above each other by using multiple |
| 3337 @code{@@author} commands: | 3501 @code{@@author} commands: |
| 3338 | 3502 |
| 3339 @example | 3503 @example |
| 3340 @group | 3504 @group |
| 3341 @@author Jane Smith | 3505 @@author Jane Smith |
| 3342 @@author John Doe | 3506 @@author John Doe |
| 3343 @end group | 3507 @end group |
| 3344 @end example | 3508 @end example |
| 3345 | |
| 3346 @noindent | |
| 3347 (Only the bottom name is underlined with a black rule.) | |
| 3348 | 3509 |
| 3349 @need 950 | 3510 @need 950 |
| 3350 A template for this method looks like this: | 3511 A template for this method looks like this: |
| 3351 | 3512 |
| 3352 @example | 3513 @example |
| 3360 @dots{} | 3521 @dots{} |
| 3361 @@end titlepage | 3522 @@end titlepage |
| 3362 @end group | 3523 @end group |
| 3363 @end example | 3524 @end example |
| 3364 | 3525 |
| 3365 You may also combine the @code{@@titlefont} method described in the | |
| 3366 previous section and @code{@@title} method described in this one. This | |
| 3367 may be useful if you have a very long title. Here is a real-life example: | |
| 3368 | |
| 3369 @example | |
| 3370 @group | |
| 3371 @@titlepage | |
| 3372 @@titlefont@{GNU Software@} | |
| 3373 @@sp 1 | |
| 3374 @@title for MS-Windows and MS-DOS | |
| 3375 @@subtitle Edition @@value@{e@} for Release @@value@{cde@} | |
| 3376 @@author by Daniel Hagerty, Melissa Weisshaus | |
| 3377 @@author and Eli Zaretskii | |
| 3378 @end group | |
| 3379 @end example | |
| 3380 | |
| 3381 @noindent | |
| 3382 (The use of @code{@@value} here is explained in @ref{value Example}. | |
| 3383 | |
| 3384 | 3526 |
| 3385 @node Copyright | 3527 @node Copyright |
| 3386 @subsection Copyright Page | 3528 @subsection Copyright Page |
| 3387 @cindex Copyright page | 3529 @cindex Copyright page |
| 3388 @cindex Printed permissions | 3530 @cindex Printed permissions |
| 3404 @example | 3546 @example |
| 3405 @@vskip 0pt plus 1filll | 3547 @@vskip 0pt plus 1filll |
| 3406 @end example | 3548 @end example |
| 3407 | 3549 |
| 3408 @noindent | 3550 @noindent |
| 3409 This is a @TeX{} command that is not supported by the Info formatting | 3551 The @code{@@vskip} command inserts whitespace in the @TeX{} output; it |
| 3410 commands. The @code{@@vskip} command inserts whitespace. The @samp{0pt | 3552 is ignored in all other output formats. The @samp{0pt plus 1filll} |
| 3411 plus 1filll} means to put in zero points of mandatory whitespace, and as | 3553 means to put in zero points of mandatory whitespace, and as much |
| 3412 much optional whitespace as needed to push the following text to the | 3554 optional whitespace as needed to push the following text to the bottom |
| 3413 bottom of the page. Note the use of three @samp{l}s in the word | 3555 of the page. Note the use of three @samp{l}s in the word |
| 3414 @samp{filll}; this is correct. | 3556 @samp{filll}; this is correct. |
| 3415 | 3557 |
| 3416 To insert the copyright text itself, write @code{@@insertcopying} | 3558 To insert the copyright text itself, write @code{@@insertcopying} |
| 3417 next (@pxref{Document Permissions}): | 3559 next (@pxref{Document Permissions}): |
| 3418 | 3560 |
| 3436 | 3578 |
| 3437 Cover art by @dots{} | 3579 Cover art by @dots{} |
| 3438 @@end titlepage | 3580 @@end titlepage |
| 3439 @end example | 3581 @end example |
| 3440 | 3582 |
| 3441 | 3583 We have one more special case to consider: for plain text output, you |
| 3442 @node end titlepage | 3584 must insert the copyright information explicitly if you want it to |
| 3585 appear. For instance, you could have the following after the copyright | |
| 3586 page: | |
| 3587 | |
| 3588 @example | |
| 3589 @@ifplaintext | |
| 3590 @@insertcopying | |
| 3591 @@end ifplaintext | |
| 3592 @end example | |
| 3593 | |
| 3594 You could include other title-like information for the plain text | |
| 3595 output in the same place. | |
| 3596 | |
| 3597 | |
| 3598 | |
| 3599 @node Heading Generation | |
| 3443 @subsection Heading Generation | 3600 @subsection Heading Generation |
| 3444 @findex end titlepage | 3601 |
| 3602 @anchor{end titlepage}@c old name | |
| 3445 @cindex Headings, page, begin to appear | 3603 @cindex Headings, page, begin to appear |
| 3446 @cindex Titlepage end starts headings | 3604 @cindex Titlepage end starts headings |
| 3447 @cindex End titlepage starts headings | 3605 @cindex End titlepage starts headings |
| 3448 | 3606 @cindex Generating page headings |
| 3449 Like all @code{@@end} commands (@pxref{Quotations and Examples}), the @code{@@end titlepage} command | 3607 |
| 3450 must be written at the beginning of a line by itself, with only one | 3608 Like all @code{@@end} commands (@pxref{Quotations and Examples}), the |
| 3451 space between the @code{@@end} and the @code{titlepage}. It not only | 3609 @code{@@end titlepage} command must be written at the beginning of a |
| 3452 marks the end of the title and copyright pages, but also causes @TeX{} | 3610 line by itself, with only one space between the @code{@@end} and the |
| 3453 to start generating page headings and page numbers. | 3611 @code{titlepage}. It not only marks the end of the title and |
| 3454 | 3612 copyright pages, but also causes @TeX{} to start generating page |
| 3455 To repeat what is said elsewhere, Texinfo has two standard page heading | 3613 headings and page numbers. |
| 3456 formats, one for documents which are printed on one side of each sheet of paper | 3614 |
| 3457 (single-sided printing), and the other for documents which are printed on both | 3615 Texinfo has two standard page heading formats, one for documents |
| 3458 sides of each sheet (double-sided printing). | 3616 printed on one side of each sheet of paper (single-sided printing), |
| 3459 You can specify these formats in different ways: | 3617 and the other for documents printed on both sides of each sheet |
| 3618 (double-sided printing). | |
| 3619 | |
| 3620 In full generality, you can control the headings in different ways: | |
| 3460 | 3621 |
| 3461 @itemize @bullet | 3622 @itemize @bullet |
| 3462 @item | 3623 @item |
| 3463 The conventional way is to write an @code{@@setchapternewpage} command | 3624 The conventional way is to write an @code{@@setchapternewpage} command |
| 3464 before the title page commands, and then have the @code{@@end | 3625 before the title page commands, if required, and then have the |
| 3465 titlepage} command start generating page headings in the manner desired. | 3626 @code{@@end titlepage} command start generating page headings in the |
| 3466 (@xref{setchapternewpage}.) | 3627 manner desired. |
| 3628 | |
| 3629 Most documents are formatted with the standard single-sided or | |
| 3630 double-sided headings, (sometimes) using @code{@@setchapternewpage | |
| 3631 odd} for double-sided printing and (almost always) no | |
| 3632 @code{@@setchapternewpage} command for single-sided printing | |
| 3633 (@pxref{@t{@@setchapternewpage}}). | |
| 3467 | 3634 |
| 3468 @item | 3635 @item |
| 3469 Alternatively, you can use the @code{@@headings} command to prevent page | 3636 Alternatively, you can use the @code{@@headings} command to prevent |
| 3470 headings from being generated or to start them for either single or | 3637 page headings from being generated or to start them for either single |
| 3471 double-sided printing. (Write an @code{@@headings} command immediately | 3638 or double-sided printing. Write an @code{@@headings} command |
| 3472 after the @code{@@end titlepage} command. @xref{headings on off, , The | 3639 immediately after the @code{@@end titlepage} command. To turn off |
| 3473 @code{@@headings} Command}, for more information.)@refill | 3640 headings, write @code{@@headings off}. @xref{@t{@@headings}}. |
| 3474 | 3641 |
| 3475 @item | 3642 @item |
| 3476 Or, you may specify your own page heading and footing format. | 3643 Or, you may specify your own page heading and footing format. |
| 3477 @xref{Headings, , Page Headings}, for detailed | 3644 @xref{Headings}. |
| 3478 information about page headings and footings. | |
| 3479 @end itemize | 3645 @end itemize |
| 3480 | |
| 3481 Most documents are formatted with the standard single-sided or | |
| 3482 double-sided format, using @code{@@setchapternewpage odd} for | |
| 3483 double-sided printing and no @code{@@setchapternewpage} command for | |
| 3484 single-sided printing. | |
| 3485 | |
| 3486 | |
| 3487 @node headings on off | |
| 3488 @subsection The @code{@@headings} Command | |
| 3489 @findex headings | |
| 3490 | |
| 3491 The @code{@@headings} command is rarely used. It specifies what kind of | |
| 3492 page headings and footings to print on each page. Usually, this is | |
| 3493 controlled by the @code{@@setchapternewpage} command. You need the | |
| 3494 @code{@@headings} command only if the @code{@@setchapternewpage} command | |
| 3495 does not do what you want, or if you want to turn off predefined page | |
| 3496 headings prior to defining your own. Write an @code{@@headings} command | |
| 3497 immediately after the @code{@@end titlepage} command. | |
| 3498 | |
| 3499 You can use @code{@@headings} as follows: | |
| 3500 | |
| 3501 @table @code | |
| 3502 @item @@headings off | |
| 3503 Turn off printing of page headings. | |
| 3504 | |
| 3505 @item @@headings single | |
| 3506 Turn on page headings appropriate for single-sided printing. | |
| 3507 | |
| 3508 @item @@headings double | |
| 3509 Turn on page headings appropriate for double-sided printing. | |
| 3510 | |
| 3511 @item @@headings singleafter | |
| 3512 @itemx @@headings doubleafter | |
| 3513 Turn on @code{single} or @code{double} headings, respectively, after the | |
| 3514 current page is output. | |
| 3515 | |
| 3516 @item @@headings on | |
| 3517 Turn on page headings: @code{single} if @samp{@@setchapternewpage | |
| 3518 on}, @code{double} otherwise. | |
| 3519 @end table | |
| 3520 | |
| 3521 For example, suppose you write @code{@@setchapternewpage off} before the | |
| 3522 @code{@@titlepage} command to tell @TeX{} to start a new chapter on the | |
| 3523 same page as the end of the last chapter. This command also causes | |
| 3524 @TeX{} to typeset page headers for single-sided printing. To cause | |
| 3525 @TeX{} to typeset for double sided printing, write @code{@@headings | |
| 3526 double} after the @code{@@end titlepage} command. | |
| 3527 | |
| 3528 You can stop @TeX{} from generating any page headings at all by | |
| 3529 writing @code{@@headings off} on a line of its own immediately after the | |
| 3530 line containing the @code{@@end titlepage} command, like this: | |
| 3531 | |
| 3532 @example | |
| 3533 @@end titlepage | |
| 3534 @@headings off | |
| 3535 @end example | |
| 3536 | |
| 3537 @noindent | |
| 3538 The @code{@@headings off} command overrides the @code{@@end titlepage} | |
| 3539 command, which would otherwise cause @TeX{} to print page headings. | |
| 3540 | |
| 3541 You can also specify your own style of page heading and footing. | |
| 3542 @xref{Headings, , Page Headings}, for more information. | |
| 3543 | 3646 |
| 3544 | 3647 |
| 3545 @node Contents | 3648 @node Contents |
| 3546 @section Generating a Table of Contents | 3649 @section Generating a Table of Contents |
| 3547 @cindex Table of contents | 3650 @cindex Table of contents |
| 3548 @cindex Contents, Table of | 3651 @cindex Contents, table of |
| 3549 @cindex Short table of contents | 3652 @cindex Short table of contents |
| 3550 @findex contents | 3653 @findex contents |
| 3551 @findex summarycontents | 3654 @findex summarycontents |
| 3552 @findex shortcontents | 3655 @findex shortcontents |
| 3553 | 3656 |
| 3554 The @code{@@chapter}, @code{@@section}, and other structuring commands | 3657 The @code{@@chapter}, @code{@@section}, and other structuring commands |
| 3555 (@pxref{Structuring}) supply the information to make up a | 3658 (@pxref{Chapter Structuring}) supply the information to make up a |
| 3556 table of contents, but they do not cause an actual table to appear in | 3659 table of contents, but they do not cause an actual table to appear in |
| 3557 the manual. To do this, you must use the @code{@@contents} and/or | 3660 the manual. To do this, you must use the @code{@@contents} and/or |
| 3558 @code{@@summarycontents} command(s). | 3661 @code{@@summarycontents} command(s). |
| 3559 | 3662 |
| 3560 @table @code | 3663 @table @code |
| 3572 | 3675 |
| 3573 Generates a short or summary table of contents that lists only the | 3676 Generates a short or summary table of contents that lists only the |
| 3574 chapters, appendices, and unnumbered chapters. Sections, subsections | 3677 chapters, appendices, and unnumbered chapters. Sections, subsections |
| 3575 and subsubsections are omitted. Only a long manual needs a short | 3678 and subsubsections are omitted. Only a long manual needs a short |
| 3576 table of contents in addition to the full table of contents. | 3679 table of contents in addition to the full table of contents. |
| 3577 | |
| 3578 @end table | 3680 @end table |
| 3579 | 3681 |
| 3580 Both contents commands should be written on a line by themselves, and | 3682 Both contents commands should be written on a line by themselves, and |
| 3581 are best placed near the beginning of the file, after the @code{@@end | 3683 placed near the beginning of the file, after the @code{@@end |
| 3582 titlepage} (@pxref{titlepage}). The contents commands automatically | 3684 titlepage} (@pxref{@t{@@titlepage}}), before any sectioning |
| 3583 generate a chapter-like heading at the top of the first table of | 3685 command. The contents commands automatically generate a chapter-like |
| 3584 contents page, so don't include any sectioning command such as | 3686 heading at the top of the first table of contents page, so don't |
| 3585 @code{@@unnumbered} before them. | 3687 include any sectioning command such as @code{@@unnumbered} before |
| 3688 them. | |
| 3586 | 3689 |
| 3587 Since an Info file uses menus instead of tables of contents, the Info | 3690 Since an Info file uses menus instead of tables of contents, the Info |
| 3588 formatting commands ignore the contents commands. But the contents are | 3691 formatting commands ignore the contents commands. But the contents |
| 3589 included in plain text output (generated by @code{makeinfo | 3692 are included in plain text output (generated by @code{makeinfo |
| 3590 --no-headers}), unless @code{makeinfo} is writing its output to standard | 3693 --plaintext}) and in other output formats, such as HTML. |
| 3591 output. | |
| 3592 | 3694 |
| 3593 When @code{makeinfo} writes a short table of contents while producing | 3695 When @code{makeinfo} writes a short table of contents while producing |
| 3594 HTML output, the links in the short table of contents point to | 3696 HTML output, the links in the short table of contents point to |
| 3595 corresponding entries in the full table of contents rather than the text | 3697 corresponding entries in the full table of contents rather than the text |
| 3596 of the document. The links in the full table of contents point to the | 3698 of the document. The links in the full table of contents point to the |
| 3610 title page. You can do this by specifying | 3712 title page. You can do this by specifying |
| 3611 @code{@@setcontentsaftertitlepage} and/or | 3713 @code{@@setcontentsaftertitlepage} and/or |
| 3612 @code{@@setshortcontentsaftertitlepage}. The first prints only the | 3714 @code{@@setshortcontentsaftertitlepage}. The first prints only the |
| 3613 main contents after the @code{@@end titlepage}; the second prints both | 3715 main contents after the @code{@@end titlepage}; the second prints both |
| 3614 the short contents and the main contents. In either case, any | 3716 the short contents and the main contents. In either case, any |
| 3615 subsequent @code{@@contents} or @code{@@shortcontents} is ignored | 3717 subsequent @code{@@contents} or @code{@@shortcontents} is ignored. |
| 3616 (unless, erroneously, no @code{@@end titlepage} is ever encountered). | |
| 3617 | 3718 |
| 3618 You need to include the @code{@@set@dots{}contentsaftertitlepage} | 3719 You need to include the @code{@@set@dots{}contentsaftertitlepage} |
| 3619 commands early in the document (just after @code{@@setfilename}, for | 3720 commands early in the document (just after @code{@@setfilename}, for |
| 3620 example). We recommend using @command{texi2dvi} (@pxref{Format with | 3721 example). We recommend using @command{texi2dvi} (@pxref{Format with |
| 3621 texi2dvi}) to specify this without altering the source file at all. For | 3722 @t{texi2dvi}}) to specify this without altering the source file at |
| 3622 example: | 3723 all. For example: |
| 3724 | |
| 3623 @example | 3725 @example |
| 3624 texi2dvi --texinfo=@@setcontentsaftertitlepage foo.texi | 3726 texi2dvi --texinfo=@@setcontentsaftertitlepage foo.texi |
| 3625 @end example | 3727 @end example |
| 3728 | |
| 3729 An alternative invocation, using @command{texi2any}: | |
| 3730 | |
| 3731 @example | |
| 3732 texi2any --dvi --Xopt --texinfo=@@setcontentsaftertitlepage foo.texi | |
| 3733 @end example | |
| 3734 | |
| 3626 | 3735 |
| 3627 | 3736 |
| 3628 @node The Top Node | 3737 @node The Top Node |
| 3629 @section The `Top' Node and Master Menu | 3738 @section The `Top' Node and Master Menu |
| 3630 @cindex Top node | 3739 @cindex Top node |
| 3637 information you feel a reader would find helpful. | 3746 information you feel a reader would find helpful. |
| 3638 | 3747 |
| 3639 @findex top | 3748 @findex top |
| 3640 It is conventional and desirable to write an @code{@@top} sectioning | 3749 It is conventional and desirable to write an @code{@@top} sectioning |
| 3641 command line containing the title of the document immediately after | 3750 command line containing the title of the document immediately after |
| 3642 the @code{@@node Top} line (@pxref{makeinfo top command, , The | 3751 the @code{@@node Top} line (@pxref{@t{@@top} Command}). |
| 3643 @code{@@top} Sectioning Command}). | |
| 3644 | 3752 |
| 3645 The contents of the `Top' node should appear only in the online output; | 3753 The contents of the `Top' node should appear only in the online output; |
| 3646 none of it should appear in printed output, so enclose it between | 3754 none of it should appear in printed output, so enclose it between |
| 3647 @code{@@ifnottex} and @code{@@end ifnottex} commands. (@TeX{} does not | 3755 @code{@@ifnottex} and @code{@@end ifnottex} commands. (@TeX{} does not |
| 3648 print either an @code{@@node} line or a menu; they appear only in Info; | 3756 print either an @code{@@node} line or a menu; they appear only in Info; |
| 3690 @subsection Parts of a Master Menu | 3798 @subsection Parts of a Master Menu |
| 3691 @cindex Master menu | 3799 @cindex Master menu |
| 3692 @cindex Menu, master | 3800 @cindex Menu, master |
| 3693 @cindex Parts of a master menu | 3801 @cindex Parts of a master menu |
| 3694 | 3802 |
| 3695 A @dfn{master menu} is a detailed main menu listing all the nodes in a | 3803 A @dfn{master menu} is the main menu. It is customary to include a |
| 3696 file. | 3804 detailed menu listing all the nodes in the document in this menu. |
| 3697 | 3805 |
| 3698 A master menu is enclosed in @code{@@menu} and @code{@@end menu} | 3806 Like any other menu, a master menu is enclosed in @code{@@menu} and |
| 3699 commands and does not appear in the printed document. | 3807 @code{@@end menu} and does not appear in the printed output. |
| 3700 | 3808 |
| 3701 Generally, a master menu is divided into parts. | 3809 Generally, a master menu is divided into parts. |
| 3702 | 3810 |
| 3703 @itemize @bullet | 3811 @itemize @bullet |
| 3704 @item | 3812 @item |
| 3709 The second part contains nodes for the indices. | 3817 The second part contains nodes for the indices. |
| 3710 | 3818 |
| 3711 @item | 3819 @item |
| 3712 @findex detailmenu | 3820 @findex detailmenu |
| 3713 @cindex Detailed menu | 3821 @cindex Detailed menu |
| 3714 The third and subsequent parts contain a listing of the other, lower | 3822 The third and subsequent parts contain a listing of the other, |
| 3715 level nodes, often ordered by chapter. This way, rather than go | 3823 lower-level nodes, often ordered by chapter. This way, rather than go |
| 3716 through an intermediary menu, an inquirer can go directly to a | 3824 through an intermediary menu, an inquirer can go directly to a |
| 3717 particular node when searching for specific information. These menu | 3825 particular node when searching for specific information. These menu |
| 3718 items are not required; add them if you think they are a | 3826 items are not required; add them if you think they are a convenience. |
| 3719 convenience. If you do use them, put @code{@@detailmenu} before the | 3827 If you do use them, put @code{@@detailmenu} before the first one, and |
| 3720 first one, and @code{@@end detailmenu} after the last; otherwise, | 3828 @code{@@end detailmenu} after the last; otherwise, @code{makeinfo} |
| 3721 @code{makeinfo} will get confused. | 3829 will get confused. |
| 3722 @end itemize | 3830 @end itemize |
| 3723 | 3831 |
| 3724 Each section in the menu can be introduced by a descriptive line. So | 3832 Each section in the menu can be introduced by a descriptive line. So |
| 3725 long as the line does not begin with an asterisk, it will not be | 3833 long as the line does not begin with an asterisk, it will not be |
| 3726 treated as a menu entry. (@xref{Writing a Menu}, for more | 3834 treated as a menu entry. (@xref{Writing a Menu}, for more |
| 3769 Besides the basic commands mentioned in the previous sections, here are | 3877 Besides the basic commands mentioned in the previous sections, here are |
| 3770 additional commands which affect the document as a whole. They are | 3878 additional commands which affect the document as a whole. They are |
| 3771 generally all given before the Top node, if they are given at all. | 3879 generally all given before the Top node, if they are given at all. |
| 3772 | 3880 |
| 3773 @menu | 3881 @menu |
| 3774 * documentdescription:: Document summary for the HTML output. | 3882 * @t{@@documentdescription}:: Document summary for the HTML output. |
| 3775 * setchapternewpage:: Start chapters on right-hand pages. | 3883 * @t{@@setchapternewpage}:: Start chapters on right-hand pages. |
| 3776 * paragraphindent:: Specify paragraph indentation. | 3884 * @t{@@headings}:: An option for turning headings on and off |
| 3777 * firstparagraphindent:: Suppress indentation of the first paragraph. | 3885 and double or single sided printing. |
| 3778 * exampleindent:: Specify environment indentation. | 3886 * @t{@@paragraphindent}:: Specify paragraph indentation. |
| 3887 * @t{@@firstparagraphindent}:: Suppressing first paragraph indentation. | |
| 3888 * @t{@@exampleindent}:: Specify environment indentation. | |
| 3779 @end menu | 3889 @end menu |
| 3780 | 3890 |
| 3781 | 3891 |
| 3782 @node documentdescription | 3892 @node @t{@@documentdescription} |
| 3783 @subsection @code{@@documentdescription}: Summary Text | 3893 @subsection @code{@@documentdescription}: Summary Text |
| 3894 @anchor{documentdescription}@c old name | |
| 3895 | |
| 3784 @cindex Document description | 3896 @cindex Document description |
| 3785 @cindex Description of document | 3897 @cindex Description of document |
| 3786 @cindex Summary of document | 3898 @cindex Summary of document |
| 3787 @cindex Abstract of document | 3899 @cindex Abstract of document |
| 3788 @cindex <meta> HTML tag, and document description | 3900 @cindex <meta> HTML tag, and document description |
| 3789 @findex documentdescription | 3901 @findex documentdescription |
| 3790 | 3902 |
| 3791 When producing HTML output for a document, @command{makeinfo} writes a | 3903 When producing HTML output for a document, @command{makeinfo} writes a |
| 3792 @samp{<meta>} element in the @samp{<head>} to give some idea of the | 3904 @samp{<meta>} element in the @samp{<head>} to give some idea of the |
| 3793 content of the document. By default, this @dfn{description} is the title | 3905 content of the document. By default, this @dfn{description} is the |
| 3794 of the document, taken from the @code{@@settitle} command | 3906 title of the document, taken from the @code{@@settitle} command |
| 3795 (@pxref{settitle}). To change this, use the @code{@@documentdescription} | 3907 (@pxref{@t{@@settitle}}). To change this, use the |
| 3796 environment, as in: | 3908 @code{@@documentdescription} environment, as in: |
| 3797 | 3909 |
| 3798 @example | 3910 @example |
| 3799 @@documentdescription | 3911 @@documentdescription |
| 3800 descriptive text. | 3912 descriptive text. |
| 3801 @@end documentdescription | 3913 @@end documentdescription |
| 3810 | 3922 |
| 3811 @code{@@documentdescription} must be specified before the first node of | 3923 @code{@@documentdescription} must be specified before the first node of |
| 3812 the document. | 3924 the document. |
| 3813 | 3925 |
| 3814 | 3926 |
| 3815 @node setchapternewpage | 3927 @node @t{@@setchapternewpage} |
| 3816 @subsection @code{@@setchapternewpage}: | 3928 @subsection @code{@@setchapternewpage}: Blank Pages Before Chapters |
| 3929 | |
| 3930 @anchor{setchapternewpage}@c old name | |
| 3931 @findex setchapternewpage | |
| 3817 @cindex Starting chapters | 3932 @cindex Starting chapters |
| 3818 @cindex Pages, starting odd | 3933 @cindex Pages, starting odd |
| 3819 @findex setchapternewpage | |
| 3820 | 3934 |
| 3821 In an officially bound book, text is usually printed on both sides of | 3935 In an officially bound book, text is usually printed on both sides of |
| 3822 the paper, chapters start on right-hand pages, and right-hand pages have | 3936 the paper, chapters start on right-hand pages, and right-hand pages have |
| 3823 odd numbers. But in short reports, text often is printed only on one | 3937 odd numbers. But in short reports, text often is printed only on one |
| 3824 side of the paper. Also in short reports, chapters sometimes do not | 3938 side of the paper. Also in short reports, chapters sometimes do not |
| 3865 because there is no printing tradition of starting chapters or books on | 3979 because there is no printing tradition of starting chapters or books on |
| 3866 an even-numbered page. | 3980 an even-numbered page. |
| 3867 | 3981 |
| 3868 If you don't like the default headers that @code{@@setchapternewpage} | 3982 If you don't like the default headers that @code{@@setchapternewpage} |
| 3869 sets, you can explicit control them with the @code{@@headings} command. | 3983 sets, you can explicit control them with the @code{@@headings} command. |
| 3870 @xref{headings on off, , The @code{@@headings} Command}. | 3984 @xref{@t{@@headings}}. |
| 3871 | 3985 |
| 3872 At the beginning of a manual or book, pages are not numbered---for | 3986 At the beginning of a manual or book, pages are not numbered---for |
| 3873 example, the title and copyright pages of a book are not numbered. By | 3987 example, the title and copyright pages of a book are not numbered. By |
| 3874 convention, table of contents and frontmatter pages are numbered with | 3988 convention, table of contents and frontmatter pages are numbered with |
| 3875 roman numerals and not in sequence with the rest of the document. | 3989 roman numerals and not in sequence with the rest of the document. |
| 3876 | 3990 |
| 3877 Since an Info file does not have pages, the @code{@@setchapternewpage} | 3991 The @code{@@setchapternewpage} has no effect in output formats that do |
| 3878 command has no effect on it. | 3992 not have pages, such as Info and HTML. |
| 3879 | 3993 |
| 3880 We recommend not including any @code{@@setchapternewpage} command in | 3994 We recommend not including any @code{@@setchapternewpage} command in |
| 3881 your manual sources at all, since the desired output is not intrinsic to | 3995 your document source at all, since such desired pagination is not |
| 3882 the document. For a particular hard copy run, if you don't want the | 3996 intrinsic to the document. For a particular hard copy run, if you |
| 3883 default option (no blank pages, same headers on all pages) use the | 3997 don't want the default output (no blank pages, same headers on all |
| 3884 @option{--texinfo} option to @command{texi2dvi} to specify the output | 3998 pages) use the @option{--texinfo} option to @command{texi2dvi} to |
| 3885 you want. | 3999 specify the output you want. |
| 3886 | 4000 |
| 3887 | 4001 |
| 3888 @node paragraphindent | 4002 @node @t{@@headings} |
| 3889 @subsection @code{@@paragraphindent}: Paragraph Indenting | 4003 @subsection The @code{@@headings} Command |
| 4004 | |
| 4005 @anchor{headings on off}@c old name | |
| 4006 @findex headings | |
| 4007 | |
| 4008 The @code{@@headings} command is rarely used. It specifies what kind of | |
| 4009 page headings and footings to print on each page. Usually, this is | |
| 4010 controlled by the @code{@@setchapternewpage} command. You need the | |
| 4011 @code{@@headings} command only if the @code{@@setchapternewpage} command | |
| 4012 does not do what you want, or if you want to turn off predefined page | |
| 4013 headings prior to defining your own. Write an @code{@@headings} command | |
| 4014 immediately after the @code{@@end titlepage} command. | |
| 4015 | |
| 4016 You can use @code{@@headings} as follows: | |
| 4017 | |
| 4018 @table @code | |
| 4019 @item @@headings off | |
| 4020 Turn off printing of page headings. | |
| 4021 | |
| 4022 @item @@headings single | |
| 4023 Turn on page headings appropriate for single-sided printing. | |
| 4024 | |
| 4025 @item @@headings double | |
| 4026 Turn on page headings appropriate for double-sided printing. | |
| 4027 | |
| 4028 @item @@headings singleafter | |
| 4029 @itemx @@headings doubleafter | |
| 4030 Turn on @code{single} or @code{double} headings, respectively, after the | |
| 4031 current page is output. | |
| 4032 | |
| 4033 @item @@headings on | |
| 4034 Turn on page headings: @code{single} if @samp{@@setchapternewpage | |
| 4035 on}, @code{double} otherwise. | |
| 4036 @end table | |
| 4037 | |
| 4038 For example, suppose you write @code{@@setchapternewpage off} before the | |
| 4039 @code{@@titlepage} command to tell @TeX{} to start a new chapter on the | |
| 4040 same page as the end of the last chapter. This command also causes | |
| 4041 @TeX{} to typeset page headers for single-sided printing. To cause | |
| 4042 @TeX{} to typeset for double sided printing, write @code{@@headings | |
| 4043 double} after the @code{@@end titlepage} command. | |
| 4044 | |
| 4045 You can stop @TeX{} from generating any page headings at all by | |
| 4046 writing @code{@@headings off} on a line of its own immediately after the | |
| 4047 line containing the @code{@@end titlepage} command, like this: | |
| 4048 | |
| 4049 @example | |
| 4050 @@end titlepage | |
| 4051 @@headings off | |
| 4052 @end example | |
| 4053 | |
| 4054 @noindent | |
| 4055 The @code{@@headings off} command overrides the @code{@@end titlepage} | |
| 4056 command, which would otherwise cause @TeX{} to print page headings. | |
| 4057 | |
| 4058 You can also specify your own style of page heading and footing. | |
| 4059 @xref{Headings, , Page Headings}, for more information. | |
| 4060 | |
| 4061 | |
| 4062 @node @t{@@paragraphindent} | |
| 4063 @subsection @code{@@paragraphindent}: Controlling Paragraph Indentation | |
| 4064 | |
| 4065 @anchor{paragraphindent}@c old name | |
| 4066 @findex paragraphindent | |
| 3890 @cindex Indenting paragraphs, control of | 4067 @cindex Indenting paragraphs, control of |
| 3891 @cindex Paragraph indentation control | 4068 @cindex Paragraph indentation control |
| 3892 @findex paragraphindent | |
| 3893 | 4069 |
| 3894 The Texinfo processors may insert whitespace at the beginning of the | 4070 The Texinfo processors may insert whitespace at the beginning of the |
| 3895 first line of each paragraph, thereby indenting that paragraph. You can | 4071 first line of each paragraph, thereby indenting that paragraph. You can |
| 3896 use the @code{@@paragraphindent} command to specify this indentation. | 4072 use the @code{@@paragraphindent} command to specify this indentation. |
| 3897 Write an @code{@@paragraphindent} command at the beginning of a line | 4073 Write an @code{@@paragraphindent} command at the beginning of a line |
| 3928 A peculiarity of the @code{texinfo-format-buffer} and | 4104 A peculiarity of the @code{texinfo-format-buffer} and |
| 3929 @code{texinfo-format-region} commands is that they do not indent (nor | 4105 @code{texinfo-format-region} commands is that they do not indent (nor |
| 3930 fill) paragraphs that contain @code{@@w} or @code{@@*} commands. | 4106 fill) paragraphs that contain @code{@@w} or @code{@@*} commands. |
| 3931 | 4107 |
| 3932 | 4108 |
| 3933 @node firstparagraphindent | 4109 @node @t{@@firstparagraphindent} |
| 3934 @subsection @code{@@firstparagraphindent}: Indenting After Headings | 4110 @subsection @code{@@firstparagraphindent}: Indenting After Headings |
| 4111 | |
| 4112 @anchor{firstparagraphindent}@c old name | |
| 4113 @findex firstparagraphindent | |
| 3935 @cindex First paragraph, suppressing indentation of | 4114 @cindex First paragraph, suppressing indentation of |
| 3936 @cindex Suppressing first paragraph indentation | 4115 @cindex Suppressing first paragraph indentation |
| 3937 @cindex Preventing first paragraph indentation | 4116 @cindex Preventing first paragraph indentation |
| 3938 @cindex Indenting, suppressing of first paragraph | 4117 @cindex Indenting, suppressing of first paragraph |
| 3939 @cindex Headings, indentation after | 4118 @cindex Headings, indentation after |
| 3940 @findex firstparagraphindent | |
| 3941 | 4119 |
| 3942 As you can see in the present manual, the first paragraph in any | 4120 As you can see in the present manual, the first paragraph in any |
| 3943 section is not indented by default. Typographically, indentation is a | 4121 section is not indented by default. Typographically, indentation is a |
| 3944 paragraph separator, which means that it is unnecessary when a new | 4122 paragraph separator, which means that it is unnecessary when a new |
| 3945 section begins. This indentation is controlled with the | 4123 section begins. This indentation is controlled with the |
| 3958 This option is ignored by @command{makeinfo} if | 4136 This option is ignored by @command{makeinfo} if |
| 3959 @code{@@paragraphindent asis} is in effect. | 4137 @code{@@paragraphindent asis} is in effect. |
| 3960 | 4138 |
| 3961 @item @code{insert} | 4139 @item @code{insert} |
| 3962 Include normal paragraph indentation. This respects the paragraph | 4140 Include normal paragraph indentation. This respects the paragraph |
| 3963 indentation set by a @code{@@paragraphindent} command | 4141 indentation set by an @code{@@paragraphindent} command |
| 3964 (@pxref{paragraphindent}). | 4142 (@pxref{@t{@@paragraphindent}}). |
| 3965 @end table | 4143 @end table |
| 3966 | 4144 |
| 3967 For HTML and XML output, the @code{@@firstparagraphindent} setting is | 4145 @code{@@firstparagraphindent} is ignored for HTML and Docbook output. |
| 3968 ignored. | 4146 |
| 3969 | 4147 It is best to write the @code{@@firstparagraphindent} command before the |
| 3970 It is best to write the @code{@@paragraphindent} command before the | |
| 3971 end-of-header line at the beginning of a Texinfo file, so the region | 4148 end-of-header line at the beginning of a Texinfo file, so the region |
| 3972 formatting commands indent paragraphs as specified. @xref{Start of | 4149 formatting commands indent paragraphs as specified. @xref{Start of |
| 3973 Header}. | 4150 Header}. |
| 3974 | 4151 |
| 3975 | 4152 |
| 3976 @node exampleindent | 4153 @node @t{@@exampleindent} |
| 3977 @subsection @code{@@exampleindent}: Environment Indenting | 4154 @subsection @code{@@exampleindent}: Environment Indenting |
| 4155 | |
| 4156 @anchor{exampleindent}@c old name | |
| 4157 @findex exampleindent | |
| 3978 @cindex Indenting environments | 4158 @cindex Indenting environments |
| 3979 @cindex Environment indentation | 4159 @cindex Environment indentation |
| 3980 @cindex Example indentation | 4160 @cindex Example indentation |
| 3981 @findex exampleindent | |
| 3982 | 4161 |
| 3983 The Texinfo processors indent each line of @code{@@example} and similar | 4162 The Texinfo processors indent each line of @code{@@example} and similar |
| 3984 environments. You can use the @code{@@exampleindent} command to specify | 4163 environments. You can use the @code{@@exampleindent} command to specify |
| 3985 this indentation. Write an @code{@@exampleindent} command at the | 4164 this indentation. Write an @code{@@exampleindent} command at the |
| 3986 beginning of a line followed by either @samp{asis} or a number: | 4165 beginning of a line followed by either @samp{asis} or a number: |
| 3987 | 4166 |
| 3988 @example | 4167 @example |
| 3989 @@exampleindent @var{indent} | 4168 @@exampleindent @var{indent} |
| 3990 @end example | 4169 @end example |
| 3991 | 4170 |
| 3992 @code{@@exampleindent} is ignored for HTML output. Otherwise, the | 4171 The indentation is according to the value of @var{indent}: |
| 3993 indentation is according to the value of @var{indent}: | |
| 3994 | 4172 |
| 3995 @table @asis | 4173 @table @asis |
| 3996 @item @code{asis} | 4174 @item @code{asis} |
| 3997 Do not change the existing indentation (not implemented in @TeX{}). | 4175 Do not change the existing indentation (not implemented in @TeX{}). |
| 3998 | 4176 |
| 4011 | 4189 |
| 4012 It is best to write the @code{@@exampleindent} command before the | 4190 It is best to write the @code{@@exampleindent} command before the |
| 4013 end-of-header line at the beginning of a Texinfo file, so the region | 4191 end-of-header line at the beginning of a Texinfo file, so the region |
| 4014 formatting commands indent paragraphs as specified. @xref{Start of | 4192 formatting commands indent paragraphs as specified. @xref{Start of |
| 4015 Header}. | 4193 Header}. |
| 4016 | |
| 4017 | |
| 4018 @node Software Copying Permissions | |
| 4019 @section Software Copying Permissions | |
| 4020 @cindex Software copying permissions | |
| 4021 @cindex Copying software | |
| 4022 @cindex Distribution | |
| 4023 @cindex License agreement | |
| 4024 | |
| 4025 If the Texinfo file has a section containing the ``General Public | |
| 4026 License'' and the distribution information and a warranty disclaimer for | |
| 4027 the software that is documented, we recommend placing this right after | |
| 4028 the `Top' node. The General Public License is very important to Project | |
| 4029 GNU software. It ensures that you and others will continue to have a | |
| 4030 right to use and share the software. | |
| 4031 | |
| 4032 The copying and distribution information and the disclaimer are followed | |
| 4033 by an introduction or else by the first chapter of the manual. | |
| 4034 | |
| 4035 @cindex Introduction, as part of file | |
| 4036 Although an introduction is not a required part of a Texinfo file, it | |
| 4037 is very helpful. Ideally, it should state clearly and concisely what | |
| 4038 the file is about and who would be interested in reading it. In | |
| 4039 general, an introduction would follow the licensing and distribution | |
| 4040 information, although sometimes people put it earlier in the document. | |
| 4041 | 4194 |
| 4042 | 4195 |
| 4043 @node Ending a File | 4196 @node Ending a File |
| 4044 @chapter Ending a Texinfo File | 4197 @chapter Ending a Texinfo File |
| 4045 @cindex Ending a Texinfo file | 4198 @cindex Ending a Texinfo file |
| 4047 @cindex File ending | 4200 @cindex File ending |
| 4048 @findex bye | 4201 @findex bye |
| 4049 | 4202 |
| 4050 The end of a Texinfo file should include commands to create indices, | 4203 The end of a Texinfo file should include commands to create indices, |
| 4051 and the @code{@@bye} command to mark the last line to be processed. | 4204 and the @code{@@bye} command to mark the last line to be processed. |
| 4052 | |
| 4053 For example: | 4205 For example: |
| 4054 | 4206 |
| 4055 @example | 4207 @example |
| 4056 @@node Index | 4208 @@node Index |
| 4057 @@unnumbered Index | 4209 @@unnumbered Index |
| 4151 In plain text output, @code{@@printindex} produces the same menu, but | 4303 In plain text output, @code{@@printindex} produces the same menu, but |
| 4152 the line numbers are relative to the start of the file, since that's | 4304 the line numbers are relative to the start of the file, since that's |
| 4153 more convenient for that format. | 4305 more convenient for that format. |
| 4154 | 4306 |
| 4155 @item | 4307 @item |
| 4156 In HTML and Docbook output, @code{@@printindex} produces links | 4308 In HTML output, @code{@@printindex} produces links to the index |
| 4157 to the index entries. | 4309 entries. |
| 4158 | 4310 |
| 4159 @item | 4311 @item |
| 4160 In XML output, it simply records the index to be printed. | 4312 In XML and Docbook output, it simply records the index to be printed. |
| 4161 @end itemize | 4313 @end itemize |
| 4162 | |
| 4163 It's not possible to generate an index when writing to standard | |
| 4164 output; @command{makeinfo} generates a warning in this case. | |
| 4165 | 4314 |
| 4166 | 4315 |
| 4167 @node File End | 4316 @node File End |
| 4168 @section @code{@@bye} File Ending | 4317 @section @code{@@bye} File Ending |
| 4169 @findex bye | 4318 @findex bye |
| 4170 | 4319 |
| 4171 An @code{@@bye} command terminates Texinfo processing. None of the | 4320 An @code{@@bye} command terminates Texinfo processing. None of the |
| 4172 formatters read anything following @code{@@bye}. The @code{@@bye} | 4321 formatters process anything following @code{@@bye}; any such text is |
| 4173 command should be on a line by itself. | 4322 completely ignored. The @code{@@bye} command should be on a line by |
| 4174 | 4323 itself. |
| 4175 If you wish, you may follow the @code{@@bye} line with notes. These | 4324 |
| 4176 notes will not be formatted and will not appear in either Info or a | 4325 Thus, if you wish, you may follow the @code{@@bye} line with arbitrary |
| 4177 printed manual; it is as if text after @code{@@bye} were within | 4326 notes. Also, you may follow the @code{@@bye} line with a local |
| 4178 @code{@@ignore} @dots{} @code{@@end ignore}. Also, you may follow the | 4327 variables list for XEmacs, most typically a @samp{compile-command} |
| 4179 @code{@@bye} line with a local variables list for XEmacs. | 4328 (@pxref{Compile-Command,, Using the Local Variables List}). |
| 4180 @xref{Compile-Command, , Using Local Variables and the Compile Command}, | 4329 |
| 4181 for more information. | 4330 |
| 4182 | 4331 @node Chapter Structuring |
| 4183 | |
| 4184 @node Structuring | |
| 4185 @chapter Chapter Structuring | 4332 @chapter Chapter Structuring |
| 4333 @anchor{Structuring}@c old name | |
| 4186 @cindex Chapter structuring | 4334 @cindex Chapter structuring |
| 4187 @cindex Structuring of chapters | 4335 @cindex Structuring of chapters |
| 4188 | 4336 @cindex Sectioning |
| 4189 The @dfn{chapter structuring} commands divide a document into a hierarchy of | 4337 |
| 4190 chapters, sections, subsections, and subsubsections. These commands | 4338 Texinfo's @dfn{chapter structuring} commands (could more generally be |
| 4191 generate large headings; they also provide information for the table | 4339 called @dfn{sectioning structuring}, but that is awkward) divide a |
| 4192 of contents of a printed manual (@pxref{Contents, , Generating a Table | 4340 document into a hierarchy of chapters, sections, subsections, and |
| 4193 of Contents}).@refill | 4341 subsubsections. These commands generate large headings in the text, |
| 4194 | 4342 like the one above. They also provide information for generating the |
| 4195 The chapter structuring commands do not create an Info node structure, | 4343 table of contents (@pxref{Contents,, Generating a Table of Contents}), |
| 4196 so normally you should put an @code{@@node} command immediately before | 4344 and for implicitly determining node pointers, as is recommended |
| 4197 each chapter structuring command (@pxref{Nodes}). The only time you | 4345 (@pxref{@t{makeinfo} Pointer Creation}). |
| 4198 are likely to use the chapter structuring commands without using the | 4346 |
| 4199 node structuring commands is if you are writing a document that | 4347 The chapter structuring commands do not create a node structure, so |
| 4200 contains no cross references and will never be transformed into Info | 4348 normally you put an @code{@@node} command immediately before each |
| 4201 format.@refill | 4349 chapter structuring command (@pxref{Nodes}). The only time you are |
| 4202 | 4350 likely to use the chapter structuring commands without also using |
| 4203 It is unlikely that you will ever write a Texinfo file that is | 4351 nodes is if you are writing a document that contains no cross |
| 4204 intended only as an Info file and not as a printable document. If you | 4352 references and will only be printed, not transformed into Info, HTML, |
| 4205 do, you might still use chapter structuring commands to create a | 4353 or other formats. |
| 4206 heading at the top of each node---but you don't need to.@refill | |
| 4207 | 4354 |
| 4208 @menu | 4355 @menu |
| 4209 * Tree Structuring:: A manual is like an upside down tree @dots{} | 4356 * Tree Structuring:: A manual is like an upside down tree @dots{} |
| 4210 * Structuring Command Types:: How to divide a manual into parts. | 4357 * Structuring Command Types:: How to divide a manual into parts. |
| 4211 * makeinfo top:: The @code{@@top} command, part of the `Top' node. | 4358 * @t{@@chapter}:: Chapter structuring. |
| 4212 * chapter:: | 4359 * @t{@@unnumbered @@appendix}:: |
| 4213 * unnumbered & appendix:: | 4360 * @t{@@majorheading @@chapheading}:: |
| 4214 * majorheading & chapheading:: | 4361 * @t{@@section}:: |
| 4215 * section:: | 4362 * @t{@@unnumberedsec @@appendixsec @@heading}:: |
| 4216 * unnumberedsec appendixsec heading:: | 4363 * @t{@@subsection}:: |
| 4217 * subsection:: | 4364 * @t{@@unnumberedsubsec @@appendixsubsec @@subheading}:: |
| 4218 * unnumberedsubsec appendixsubsec subheading:: | 4365 * @t{@@subsubsection}:: Commands for the lowest level sections. |
| 4219 * subsubsection:: Commands for the lowest level sections. | 4366 * @t{@@part}:: Collections of chapters. |
| 4220 * Raise/lower sections:: How to change commands' hierarchical level. | 4367 * Raise/lower sections:: How to change commands' hierarchical level. |
| 4221 @end menu | 4368 @end menu |
| 4222 | 4369 |
| 4223 | 4370 |
| 4224 @node Tree Structuring | 4371 @node Tree Structuring |
| 4227 | 4374 |
| 4228 A Texinfo file is usually structured like a book with chapters, | 4375 A Texinfo file is usually structured like a book with chapters, |
| 4229 sections, subsections, and the like. This structure can be visualized | 4376 sections, subsections, and the like. This structure can be visualized |
| 4230 as a tree (or rather as an upside-down tree) with the root at the top | 4377 as a tree (or rather as an upside-down tree) with the root at the top |
| 4231 and the levels corresponding to chapters, sections, subsection, and | 4378 and the levels corresponding to chapters, sections, subsection, and |
| 4232 subsubsections.@refill | 4379 subsubsections. |
| 4233 | 4380 |
| 4234 Here is a diagram that shows a Texinfo file with three chapters, | 4381 Here is a diagram that shows a Texinfo file with three chapters, each |
| 4235 each of which has two sections.@refill | 4382 with two sections. |
| 4236 | 4383 |
| 4237 @example | 4384 @example |
| 4238 @group | 4385 @group |
| 4239 Top | 4386 Top |
| 4240 | | 4387 | |
| 4249 | 4396 |
| 4250 @end group | 4397 @end group |
| 4251 @end example | 4398 @end example |
| 4252 | 4399 |
| 4253 In a Texinfo file that has this structure, the beginning of Chapter 2 | 4400 In a Texinfo file that has this structure, the beginning of Chapter 2 |
| 4254 looks like this:@refill | 4401 would normally (with implicitly-determined node pointers) be written |
| 4402 like this: | |
| 4255 | 4403 |
| 4256 @example | 4404 @example |
| 4257 @group | 4405 @group |
| 4258 @@node Chapter 2, Chapter 3, Chapter 1, top | 4406 @@node Chapter 2 |
| 4259 @@chapter Chapter 2 | 4407 @@chapter Chapter 2 |
| 4260 @end group | 4408 @end group |
| 4261 @end example | 4409 @end example |
| 4262 | 4410 |
| 4411 @noindent | |
| 4412 But for purposes of example, here is how it would be written with | |
| 4413 explicit node pointers: | |
| 4414 | |
| 4415 @example | |
| 4416 @group | |
| 4417 @@node Chapter 2, Chapter 3, Chapter 1, Top | |
| 4418 @@chapter Chapter 2 | |
| 4419 @end group | |
| 4420 @end example | |
| 4421 | |
| 4263 The chapter structuring commands are described in the sections that | 4422 The chapter structuring commands are described in the sections that |
| 4264 follow; the @code{@@node} and @code{@@menu} commands are described in | 4423 follow; the @code{@@node} command is described in |
| 4265 following chapters. (@xref{Nodes}, and see @ref{Menus}.)@refill | 4424 the following chapter (@pxref{Nodes}). |
| 4266 | 4425 |
| 4267 | 4426 |
| 4268 @node Structuring Command Types | 4427 @node Structuring Command Types |
| 4269 @section Structuring Command Types | 4428 @section Structuring Command Types |
| 4270 | 4429 |
| 4271 The chapter structuring commands fall into four groups or series, each | 4430 The chapter structuring commands fall into four groups or series, each |
| 4272 of which contains structuring commands corresponding to the | 4431 of which contains structuring commands corresponding to the |
| 4273 hierarchical levels of chapters, sections, subsections, and | 4432 hierarchical levels of chapters, sections, subsections, and |
| 4274 subsubsections.@refill | 4433 subsubsections. |
| 4275 | 4434 |
| 4276 The four groups are the @code{@@chapter} series, the | 4435 The four groups of commands are the @code{@@chapter} series, the |
| 4277 @code{@@unnumbered} series, the @code{@@appendix} series, and the | 4436 @code{@@unnumbered} series, the @code{@@appendix} series, and the |
| 4278 @code{@@heading} series.@refill | 4437 @code{@@heading} series. Each command produces a title with a |
| 4279 | 4438 different appearance in the body of the document. Some of the |
| 4280 Each command produces titles that have a different appearance on the | 4439 commands list their titles in the tables of contents, while others do |
| 4281 printed page or Info file; only some of the commands produce | 4440 not. Here are the details: |
| 4282 titles that are listed in the table of contents of a printed book or | |
| 4283 manual.@refill | |
| 4284 | 4441 |
| 4285 @itemize @bullet | 4442 @itemize @bullet |
| 4286 @item | 4443 @item |
| 4287 The @code{@@chapter} and @code{@@appendix} series of commands produce | 4444 The @code{@@chapter} and @code{@@appendix} series of commands produce |
| 4288 numbered or lettered entries both in the body of a printed work and in | 4445 numbered or lettered entries both in the body of a document and in its |
| 4289 its table of contents.@refill | 4446 table of contents. |
| 4290 | 4447 |
| 4291 @item | 4448 @item |
| 4292 The @code{@@unnumbered} series of commands produce unnumbered entries | 4449 The @code{@@unnumbered} series of commands produce unnumbered entries |
| 4293 both in the body of a printed work and in its table of contents. The | 4450 both in the body of a document and in its table of contents. The |
| 4294 @code{@@top} command, which has a special use, is a member of this | 4451 @code{@@top} command, which has a special use, is a member of this |
| 4295 series (@pxref{makeinfo top, , @code{@@top}}). An @code{@@unnumbered} | 4452 series (@pxref{@t{@@top} Command}). An @code{@@unnumbered} section |
| 4296 section should be associated with a node and be a normal part of the | 4453 is a normal part of the document structure. |
| 4297 document structure. | |
| 4298 | 4454 |
| 4299 @item | 4455 @item |
| 4300 The @code{@@heading} series of commands produce simple unnumbered | 4456 The @code{@@heading} series of commands produce simple unnumbered |
| 4301 headings that do not appear in a table of contents, are not associated | 4457 headings that do not appear in a table of contents, are not associated |
| 4302 with nodes, and cannot be cross-referenced. The heading commands | 4458 with nodes, and cannot be cross-referenced. These heading commands |
| 4303 never start a new page. | 4459 never start a new page. |
| 4304 | 4460 @end itemize |
| 4305 @item | 4461 |
| 4306 The @code{@@majorheading} command is similar to @code{@@chapheading}, | |
| 4307 except that it generates a larger vertical whitespace before the | |
| 4308 heading. | |
| 4309 | |
| 4310 @item | |
| 4311 When an @code{@@setchapternewpage} command says to do so, the | 4462 When an @code{@@setchapternewpage} command says to do so, the |
| 4312 @code{@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands | 4463 @code{@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands |
| 4313 start new pages in the printed manual; the @code{@@heading} commands | 4464 start new pages in the printed manual; the @code{@@heading} commands |
| 4314 do not.@refill | 4465 do not. @xref{@t{@@setchapternewpage}}. |
| 4315 @end itemize | 4466 |
| 4316 | 4467 Here is a summary: |
| 4317 Here are the four groups of chapter structuring commands: | |
| 4318 | 4468 |
| 4319 @tex | 4469 @tex |
| 4320 {\globaldefs = 1 \smallfonts} | 4470 {\globaldefs=1 \smallfonts \rm} |
| 4321 @end tex | 4471 @end tex |
| 4322 | 4472 |
| 4323 @multitable @columnfractions .19 .30 .29 .22 | 4473 @multitable @columnfractions .19 .30 .29 .22 |
| 4324 @item @tab @tab @tab No new page | 4474 @item @tab @tab @tab No new page |
| 4325 @item @i{Numbered} @tab @i{Unnumbered} @tab @i{Lettered/numbered} @tab @i{Unnumbered} | 4475 @item @i{Numbered} @tab @i{Unnumbered} @tab @i{Lettered/numbered} @tab @i{Unnumbered} |
| 4329 @item @code{@@section} @tab @code{@@unnumberedsec} @tab @code{@@appendixsec} @tab @code{@@heading} | 4479 @item @code{@@section} @tab @code{@@unnumberedsec} @tab @code{@@appendixsec} @tab @code{@@heading} |
| 4330 @item @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab @code{@@appendixsubsec} @tab @code{@@subheading} | 4480 @item @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab @code{@@appendixsubsec} @tab @code{@@subheading} |
| 4331 @item @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab @code{@@appendixsubsubsec} @tab @code{@@subsubheading} | 4481 @item @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab @code{@@appendixsubsubsec} @tab @code{@@subsubheading} |
| 4332 @end multitable | 4482 @end multitable |
| 4333 @tex | 4483 @tex |
| 4334 {\globaldefs = 1 \textfonts} | 4484 {\globaldefs=1 \textfonts \rm} |
| 4335 @end tex | 4485 @end tex |
| 4336 | 4486 |
| 4337 | 4487 |
| 4338 @node makeinfo top | 4488 @node @t{@@chapter} |
| 4339 @section @code{@@top} | 4489 @section @code{@@chapter}: Chapter Structuring |
| 4340 | 4490 |
| 4341 The @code{@@top} command is a special sectioning command that you use | 4491 @anchor{chapter}@c old name |
| 4342 only after an @samp{@@node Top} line at the beginning of a Texinfo file. | |
| 4343 The @code{@@top} command tells the @code{makeinfo} formatter which node | |
| 4344 is the `Top' node, so it can use it as the root of the node tree if your | |
| 4345 manual uses implicit node pointers. It has the same typesetting effect as | |
| 4346 @code{@@unnumbered} (@pxref{unnumbered & appendix, , @code{@@unnumbered} | |
| 4347 and @code{@@appendix}}). For detailed information, see @ref{makeinfo | |
| 4348 top command, , The @code{@@top} Command}. | |
| 4349 | |
| 4350 The @code{@@top} node and its menu (if any) is conventionally wrapped in | |
| 4351 an @code{@@ifnottex} conditional so that it will appear only in Info and | |
| 4352 HTML output, not @TeX{}. | |
| 4353 | |
| 4354 | |
| 4355 @node chapter | |
| 4356 @comment node-name, next, previous, up | |
| 4357 @section @code{@@chapter} | |
| 4358 @findex chapter | 4492 @findex chapter |
| 4359 | 4493 |
| 4360 @code{@@chapter} identifies a chapter in the document. Write the | 4494 @code{@@chapter} identifies a chapter in the document--the highest |
| 4361 command at the beginning of a line and follow it on the same line by | 4495 level of the normal document structuring hierarchy. Write the command |
| 4362 the title of the chapter.@refill | 4496 at the beginning of a line and follow it on the same line by the title |
| 4363 | 4497 of the chapter. The chapter is numbered automatically, starting |
| 4364 For example, this chapter in this manual is entitled ``Chapter | 4498 from@tie{}1. |
| 4365 Structuring''; the @code{@@chapter} line looks like this:@refill | 4499 |
| 4366 | 4500 For example, the present chapter in this manual is entitled |
| 4367 @example | 4501 ``@code{@@chapter}: Chapter Structuring''; the @code{@@chapter} line |
| 4368 @@chapter Chapter Structuring | 4502 looks like this: |
| 4369 @end example | 4503 |
| 4370 | 4504 @example |
| 4371 In @TeX{}, the @code{@@chapter} command creates a chapter in the | 4505 @@chapter @@code@{@@@@chapter@}: Chapter Structuring |
| 4372 document, specifying the chapter title. The chapter is numbered | 4506 @end example |
| 4373 automatically.@refill | 4507 |
| 4374 | 4508 In @TeX{}, the @code{@@chapter} command produces a chapter heading in |
| 4375 In Info, the @code{@@chapter} command causes the title to appear on a | 4509 the document. |
| 4376 line by itself, with a line of asterisks inserted underneath. Thus, | 4510 |
| 4377 in Info, the above example produces the following output:@refill | 4511 In Info and plain text output, the @code{@@chapter} command causes the |
| 4378 | 4512 title to appear on a line by itself, with a line of asterisks inserted |
| 4379 @example | 4513 underneath. So, the above example produces the following output: |
| 4380 Chapter Structuring | 4514 |
| 4381 ******************* | 4515 @example |
| 4382 @end example | 4516 @group |
| 4517 5 Chapter Structuring | |
| 4518 ********************* | |
| 4519 @end group | |
| 4520 @end example | |
| 4521 | |
| 4522 In HTML, the @code{@@chapter} command produces an @code{<h2>}-level | |
| 4523 header by default (controlled by the @code{CHAPTER_HEADER_LEVEL} | |
| 4524 customization variable, @pxref{Other Customization Variables}). | |
| 4525 | |
| 4526 In the XML and Docbook output, a @code{<chapter>} element is produced | |
| 4527 that includes all the following sections, up to the next chapter. | |
| 4528 | |
| 4529 | |
| 4530 @node @t{@@unnumbered @@appendix} | |
| 4531 @section @code{@@unnumbered}, @code{@@appendix}: Chapters with Other Labeling | |
| 4532 | |
| 4533 @anchor{unnumbered & appendix}@c old name | |
| 4534 @findex unnumbered | |
| 4535 @findex appendix | |
| 4536 | |
| 4537 Use the @code{@@unnumbered} command to start a chapter-level element | |
| 4538 that appears without chapter numbers of any kind. Use the | |
| 4539 @code{@@appendix} command to start an appendix that is labeled by | |
| 4540 letter (`A', `B', @dots{}) instead of by number; appendices are also | |
| 4541 at the chapter level of structuring. | |
| 4542 | |
| 4543 Write an @code{@@appendix} or @code{@@unnumbered} command at the | |
| 4544 beginning of a line and follow it on the same line by the title, | |
| 4545 just as with @code{@@chapter}. | |
| 4383 | 4546 |
| 4384 @findex centerchap | 4547 @findex centerchap |
| 4385 Texinfo also provides a command @code{@@centerchap}, which is analogous | 4548 Texinfo also provides a command @code{@@centerchap}, which is analogous |
| 4386 to @code{@@unnumbered}, but centers its argument in the printed output. | 4549 to @code{@@unnumbered}, but centers its argument in the printed and HTML |
| 4387 This kind of stylistic choice is not usually offered by Texinfo. | 4550 outputs. This kind of stylistic choice is not usually offered by |
| 4388 @c but the Hacker's Dictionary wanted it ... | 4551 Texinfo. It may be suitable for short documents. |
| 4389 | 4552 @c but the Hacker's Dictionary wanted it, before they quit Texinfo. |
| 4390 | 4553 |
| 4391 @node unnumbered & appendix | 4554 @cindex Docbook and prefatory sections |
| 4392 @section @code{@@unnumbered} and @code{@@appendix} | 4555 @cindex Preface, etc., and Docbook |
| 4393 @findex unnumbered | 4556 With @code{@@unnumbered}, if the name of the associated node is one of |
| 4394 @findex appendix | 4557 these English words (case-insensitive): |
| 4395 | 4558 |
| 4396 Use the @code{@@unnumbered} command to create a chapter that appears | 4559 @example |
| 4397 in a printed manual without chapter numbers of any kind. Use the | 4560 Acknowledgements Colophon Dedication Preface |
| 4398 @code{@@appendix} command to create an appendix in a printed manual | 4561 @end example |
| 4399 that is labelled by letter (`A', `B', @dots{}) instead of by number. | 4562 |
| 4400 | 4563 @cindex @code{<acknowledgements>} Docbook tag |
| 4401 Write an @code{@@appendix} or @code{@@unnumbered} command at the | 4564 @cindex @code{<colophon>} Docbook tag |
| 4402 beginning of a line and follow it on the same line by the title, as | 4565 @cindex @code{<dedication>} Docbook tag |
| 4403 you would if you were creating a chapter. | 4566 @cindex @code{<preface>} Docbook tag |
| 4404 | 4567 @cindex @code{<chapter>} Docbook tag |
| 4405 | 4568 @cindex @code{<title>} Docbook tag |
| 4406 @node majorheading & chapheading | 4569 @noindent then the Docbook output uses corresponding special tags |
| 4407 @section @code{@@majorheading}, @code{@@chapheading} | 4570 (@code{<preface>}, etc.)@: instead of the default @code{<chapter>}. |
| 4571 The argument to @code{@@unnumbered} itself can be anything, and is | |
| 4572 output as the following @code{<title>} text as usual. | |
| 4573 | |
| 4574 | |
| 4575 @node @t{@@majorheading @@chapheading} | |
| 4576 @section @code{@@majorheading}, @code{@@chapheading}: Chapter-level Headings | |
| 4577 | |
| 4578 @anchor{majorheading & chapheading}@c old name | |
| 4408 @findex majorheading | 4579 @findex majorheading |
| 4409 @findex chapheading | 4580 @findex chapheading |
| 4410 | 4581 |
| 4411 The @code{@@majorheading} and @code{@@chapheading} commands put | 4582 The @code{@@majorheading} and @code{@@chapheading} commands produce |
| 4412 chapter-like headings in the body of a document.@refill | 4583 chapter-like headings in the body of a document. |
| 4413 | 4584 |
| 4414 However, neither command causes @TeX{} to produce a numbered heading | 4585 However, neither command produces an entry in the table of contents, |
| 4415 or an entry in the table of contents; and neither command causes | 4586 and neither command causes @TeX{} to start a new page in a printed |
| 4416 @TeX{} to start a new page in a printed manual.@refill | 4587 manual. |
| 4417 | 4588 |
| 4418 In @TeX{}, an @code{@@majorheading} command generates a larger vertical | 4589 In @TeX{}, an @code{@@majorheading} command generates a larger vertical |
| 4419 whitespace before the heading than an @code{@@chapheading} command but | 4590 whitespace before the heading than an @code{@@chapheading} command but |
| 4420 is otherwise the same. | 4591 is otherwise the same. |
| 4421 | 4592 |
| 4422 In Info, | 4593 In Info and plain text, the @code{@@majorheading} and |
| 4423 the @code{@@majorheading} and | 4594 @code{@@chapheading} commands produce the same output as |
| 4424 @code{@@chapheading} commands are equivalent to | |
| 4425 @code{@@chapter}: the title is printed on a line by itself with a line | 4595 @code{@@chapter}: the title is printed on a line by itself with a line |
| 4426 of asterisks underneath. (@xref{chapter, , @code{@@chapter}}.)@refill | 4596 of asterisks underneath. Similarly for HTML@. The only difference is |
| 4427 | 4597 the lack of numbering and the lack of any association with nodes. |
| 4428 | 4598 @xref{@t{@@chapter}}. |
| 4429 @node section | 4599 |
| 4430 @section @code{@@section} | 4600 |
| 4601 @node @t{@@section} | |
| 4602 @section @code{@@section}: Sections Below Chapters | |
| 4603 | |
| 4604 @anchor{section}@c old name | |
| 4431 @findex section | 4605 @findex section |
| 4432 | 4606 |
| 4433 A @code{@@section} command identifies a section within a chapter unit, | 4607 An @code{@@section} command identifies a section within a chapter |
| 4434 whether created with @code{@@chapter}, @code{@@unnumbered}, or | 4608 unit, whether created with @code{@@chapter}, @code{@@unnumbered}, or |
| 4435 @code{@@appendix}, following the numbering scheme of the chapter-level | 4609 @code{@@appendix}, following the numbering scheme of the chapter-level |
| 4436 command. Thus, within a @code{@@chapter} chapter numbered `1', the | 4610 command. Thus, within an @code{@@chapter} chapter numbered `1', the |
| 4437 section is numbered like `1.2'; within an @code{@@appendix} | 4611 sections are numbered `1.1', `1.2', etc.; within an @code{@@appendix} |
| 4438 ``chapter'' labeled `A', the section is numbered like `A.2'; within an | 4612 ``chapter'' labeled `A', the sections are numbered `A.1', `A.2', etc.; |
| 4439 @code{@@unnumbered} chapter, the section gets no number. | 4613 within an @code{@@unnumbered} chapter, the section gets no number. |
| 4440 | 4614 The output is underlined with @samp{=} in Info and plain text. |
| 4441 For example, this section is headed with an @code{@@section} command | 4615 |
| 4442 and looks like this in the Texinfo file: | 4616 To make a section, write the @code{@@section} command at the |
| 4443 | |
| 4444 @example | |
| 4445 @@section @@code@{@@@@section@} | |
| 4446 @end example | |
| 4447 | |
| 4448 To create a section, write the @code{@@section} command at the | |
| 4449 beginning of a line and follow it on the same line by the section | 4617 beginning of a line and follow it on the same line by the section |
| 4450 title. The output is underlined with @samp{=} in Info. | 4618 title. For example, |
| 4451 | |
| 4452 Thus, | |
| 4453 | 4619 |
| 4454 @example | 4620 @example |
| 4455 @@section This is a section | 4621 @@section This is a section |
| 4456 @end example | 4622 @end example |
| 4457 | 4623 |
| 4463 5.7 This is a section | 4629 5.7 This is a section |
| 4464 ===================== | 4630 ===================== |
| 4465 @end group | 4631 @end group |
| 4466 @end example | 4632 @end example |
| 4467 | 4633 |
| 4468 | 4634 Section titles are listed in the table of contents. |
| 4469 @node unnumberedsec appendixsec heading | 4635 |
| 4636 The @TeX{}, HTML, Docbook, and XML output is all analogous to the | |
| 4637 chapter-level output, just ``one level down''; @pxref{@t{@@chapter}}. | |
| 4638 | |
| 4639 | |
| 4640 @node @t{@@unnumberedsec @@appendixsec @@heading} | |
| 4470 @section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading} | 4641 @section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading} |
| 4642 | |
| 4643 @anchor{unnumberedsec appendixsec heading}@c old name | |
| 4471 @findex unnumberedsec | 4644 @findex unnumberedsec |
| 4472 @findex appendixsec | 4645 @findex appendixsec |
| 4473 @findex heading | 4646 @findex heading |
| 4474 | 4647 |
| 4475 The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading} | 4648 The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading} |
| 4476 commands are, respectively, the unnumbered, appendix-like, and | 4649 commands are, respectively, the unnumbered, appendix-like, and |
| 4477 heading-like equivalents of the @code{@@section} command, as described | 4650 heading-like equivalents of the @code{@@section} command (see the |
| 4478 in the previous section. | 4651 previous section). |
| 4479 | |
| 4480 @table @code | |
| 4481 @item @@unnumberedsec | |
| 4482 The @code{@@unnumberedsec} command may be used within an | |
| 4483 unnumbered chapter or within a regular chapter or appendix to | |
| 4484 provide an unnumbered section.@refill | |
| 4485 | |
| 4486 @item @@appendixsec | |
| 4487 @itemx @@appendixsection | |
| 4488 @code{@@appendixsection} is a longer spelling of the | |
| 4489 @code{@@appendixsec} command; the two are synonymous.@refill | |
| 4490 @findex appendixsection | |
| 4491 | |
| 4492 Conventionally, the @code{@@appendixsec} or @code{@@appendixsection} | |
| 4493 command is used only within appendices.@refill | |
| 4494 | |
| 4495 @item @@heading | |
| 4496 You may use the @code{@@heading} command anywhere you wish for a | |
| 4497 section-style heading that will not appear in the table of contents.@refill | |
| 4498 @end table | |
| 4499 | 4652 |
| 4500 @code{@@unnumberedsec} and @code{@@appendixsec} do not need to be used | 4653 @code{@@unnumberedsec} and @code{@@appendixsec} do not need to be used |
| 4501 in ordinary circumstances, because @code{@@section} may also be used | 4654 in ordinary circumstances, because @code{@@section} may also be used |
| 4502 within @code{@@unnumbered} and @code{@@appendix} chapters; again, see | 4655 within @code{@@unnumbered} and @code{@@appendix} chapters; again, see |
| 4503 the previous section. | 4656 the previous section. |
| 4504 | 4657 |
| 4505 | 4658 @table @code |
| 4506 @node subsection | 4659 @item @@unnumberedsec |
| 4507 @section The @code{@@subsection} Command | 4660 The @code{@@unnumberedsec} command may be used within an unnumbered |
| 4661 chapter or within a regular chapter or appendix to produce an | |
| 4662 unnumbered section. | |
| 4663 | |
| 4664 @item @@appendixsec | |
| 4665 @itemx @@appendixsection | |
| 4666 @findex appendixsection | |
| 4667 @findex appendixsec | |
| 4668 @code{@@appendixsection} is a longer spelling of the | |
| 4669 @code{@@appendixsec} command; the two are synonymous. | |
| 4670 | |
| 4671 Conventionally, the @code{@@appendixsec} or @code{@@appendixsection} | |
| 4672 command is used only within appendices. | |
| 4673 | |
| 4674 @item @@heading | |
| 4675 You may use the @code{@@heading} command anywhere you wish for a | |
| 4676 section-style heading that will not appear in the table of contents. | |
| 4677 @end table | |
| 4678 | |
| 4679 | |
| 4680 @node @t{@@subsection} | |
| 4681 @section @code{@@subsection}: Subsections Below Sections | |
| 4682 | |
| 4683 @anchor{subsection}@c old name | |
| 4508 @findex subsection | 4684 @findex subsection |
| 4509 | 4685 |
| 4510 Subsections are to sections as sections are to chapters. | 4686 Subsections are to sections as sections are to chapters; |
| 4511 (@xref{section, , @code{@@section}}.) In Info, subsection titles are | 4687 @pxref{@t{@@section}}. In Info and plain text, subsection titles |
| 4512 underlined with @samp{-}. For example, | 4688 are underlined with @samp{-}. For example, |
| 4513 | 4689 |
| 4514 @example | 4690 @example |
| 4515 @@subsection This is a subsection | 4691 @@subsection This is a subsection |
| 4516 @end example | 4692 @end example |
| 4517 | 4693 |
| 4518 @noindent | 4694 @noindent |
| 4519 produces | 4695 might produce |
| 4520 | 4696 |
| 4521 @example | 4697 @example |
| 4522 @group | 4698 @group |
| 4523 1.2.3 This is a subsection | 4699 1.2.3 This is a subsection |
| 4524 -------------------------- | 4700 -------------------------- |
| 4525 @end group | 4701 @end group |
| 4526 @end example | 4702 @end example |
| 4527 | 4703 |
| 4528 In a printed manual, subsections are listed in the table of contents | 4704 Subsection titles are listed in the table of contents. |
| 4529 and are numbered three levels deep.@refill | 4705 |
| 4530 | 4706 The @TeX{}, HTML, Docbook, and XML output is all analogous to the |
| 4531 | 4707 chapter-level output, just ``two levels down''; |
| 4532 @node unnumberedsubsec appendixsubsec subheading | 4708 @pxref{@t{@@chapter}}. |
| 4709 | |
| 4710 | |
| 4711 @node @t{@@unnumberedsubsec @@appendixsubsec @@subheading} | |
| 4533 @section The @code{@@subsection}-like Commands | 4712 @section The @code{@@subsection}-like Commands |
| 4534 @cindex Subsection-like commands | 4713 |
| 4714 @anchor{unnumberedsubsec appendixsubsec subheading}@c old name | |
| 4535 @findex unnumberedsubsec | 4715 @findex unnumberedsubsec |
| 4536 @findex appendixsubsec | 4716 @findex appendixsubsec |
| 4537 @findex subheading | 4717 @findex subheading |
| 4718 @cindex Subsection-like commands | |
| 4538 | 4719 |
| 4539 The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and | 4720 The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and |
| 4540 @code{@@subheading} commands are, respectively, the unnumbered, | 4721 @code{@@subheading} commands are, respectively, the unnumbered, |
| 4541 appendix-like, and heading-like equivalents of the @code{@@subsection} | 4722 appendix-like, and heading-like equivalents of the @code{@@subsection} |
| 4542 command. (@xref{subsection, , @code{@@subsection}}.) | 4723 command. (@xref{@t{@@subsection}}.) |
| 4543 | |
| 4544 In Info, the @code{@@subsection}-like commands generate a title | |
| 4545 underlined with hyphens. In a printed manual, an @code{@@subheading} | |
| 4546 command produces a heading like that of a subsection except that it is | |
| 4547 not numbered and does not appear in the table of contents. Similarly, | |
| 4548 an @code{@@unnumberedsubsec} command produces an unnumbered heading like | |
| 4549 that of a subsection and an @code{@@appendixsubsec} command produces a | |
| 4550 subsection-like heading labelled with a letter and numbers; both of | |
| 4551 these commands produce headings that appear in the table of | |
| 4552 contents. | |
| 4553 | 4724 |
| 4554 @code{@@unnumberedsubsec} and @code{@@appendixsubsec} do not need to | 4725 @code{@@unnumberedsubsec} and @code{@@appendixsubsec} do not need to |
| 4555 be used in ordinary circumstances, because @code{@@subsection} may | 4726 be used in ordinary circumstances, because @code{@@subsection} may |
| 4556 also be used within sections of @code{@@unnumbered} and | 4727 also be used within sections of @code{@@unnumbered} and |
| 4557 @code{@@appendix} chapters (@pxref{section,,@code{section}}). | 4728 @code{@@appendix} chapters (@pxref{@t{@@section}}). |
| 4558 | 4729 |
| 4559 | 4730 An @code{@@subheading} command produces a heading like that of a |
| 4560 @node subsubsection | 4731 subsection except that it is not numbered and does not appear in the |
| 4561 @section The `subsub' Commands | 4732 table of contents. Similarly, an @code{@@unnumberedsubsec} command |
| 4562 @cindex Subsub commands | 4733 produces an unnumbered heading like that of a subsection and an |
| 4734 @code{@@appendixsubsec} command produces a subsection-like heading | |
| 4735 labeled with a letter and numbers; both of these commands produce | |
| 4736 headings that appear in the table of contents. In Info and plain | |
| 4737 text, the @code{@@subsection}-like commands generate a title | |
| 4738 underlined with hyphens. | |
| 4739 | |
| 4740 | |
| 4741 @node @t{@@subsubsection} | |
| 4742 @section @code{@@subsection} and Other Subsub Commands | |
| 4743 | |
| 4744 @anchor{subsubsection}@c old name | |
| 4563 @findex subsubsection | 4745 @findex subsubsection |
| 4564 @findex unnumberedsubsubsec | 4746 @findex unnumberedsubsubsec |
| 4565 @findex appendixsubsubsec | 4747 @findex appendixsubsubsec |
| 4566 @findex subsubheading | 4748 @findex subsubheading |
| 4749 @cindex Subsub sectioning commands | |
| 4567 | 4750 |
| 4568 The fourth and lowest level sectioning commands in Texinfo are the | 4751 The fourth and lowest level sectioning commands in Texinfo are the |
| 4569 `subsub' commands. They are:@refill | 4752 `subsub' commands. They are: |
| 4570 | 4753 |
| 4571 @table @code | 4754 @table @code |
| 4572 @item @@subsubsection | 4755 @item @@subsubsection |
| 4573 Subsubsections are to subsections as subsections are to sections. | 4756 Subsubsections are to subsections as subsections are to sections. |
| 4574 (@xref{subsection, , @code{@@subsection}}.) In a printed manual, | 4757 (@xref{@t{@@subsection}}.) Subsubsection titles appear in the |
| 4575 subsubsection titles appear in the table of contents and are numbered | 4758 table of contents. |
| 4576 four levels deep.@refill | |
| 4577 | 4759 |
| 4578 @item @@unnumberedsubsubsec | 4760 @item @@unnumberedsubsubsec |
| 4579 Unnumbered subsubsection titles appear in the table of contents of a | 4761 Unnumbered subsubsection titles appear in the table of contents, |
| 4580 printed manual, but lack numbers. Otherwise, unnumbered | 4762 but lack numbers. Otherwise, unnumbered subsubsections are the same |
| 4581 subsubsections are the same as subsubsections. In Info, unnumbered | 4763 as subsubsections. |
| 4582 subsubsections look exactly like ordinary subsubsections.@refill | |
| 4583 | 4764 |
| 4584 @item @@appendixsubsubsec | 4765 @item @@appendixsubsubsec |
| 4585 Conventionally, appendix commands are used only for appendices and are | 4766 Conventionally, appendix commands are used only for appendices and are |
| 4586 lettered and numbered appropriately in a printed manual. They also | 4767 lettered and numbered appropriately. They also appear in the table |
| 4587 appear in the table of contents. In Info, appendix subsubsections look | 4768 of contents. |
| 4588 exactly like ordinary subsubsections.@refill | |
| 4589 | 4769 |
| 4590 @item @@subsubheading | 4770 @item @@subsubheading |
| 4591 The @code{@@subsubheading} command may be used anywhere that you need | 4771 The @code{@@subsubheading} command may be used anywhere that you want |
| 4592 a small heading that will not appear in the table of contents. In | 4772 a small heading that will not appear in the table of contents. |
| 4593 Info, subsubheadings look exactly like ordinary subsubsection | |
| 4594 headings.@refill | |
| 4595 @end table | 4773 @end table |
| 4596 | 4774 |
| 4597 @code{@@unnumberedsubsubsec} and @code{@@appendixsubsubsec} do not | 4775 As with subsections, @code{@@unnumberedsubsubsec} and |
| 4598 need to be used in ordinary circumstances, because | 4776 @code{@@appendixsubsubsec} do not need to be used in ordinary |
| 4599 @code{@@subsubsection} may also be used within subsections of | 4777 circumstances, because @code{@@subsubsection} may also be used within |
| 4600 @code{@@unnumbered} and @code{@@appendix} chapters | 4778 subsections of @code{@@unnumbered} and @code{@@appendix} chapters |
| 4601 (@pxref{section,,@code{section}}). | 4779 (@pxref{@t{@@section}}). |
| 4602 | 4780 |
| 4603 | 4781 In Info, `subsub' titles are underlined with periods. For example, |
| 4604 In Info, `subsub' titles are underlined with periods. | |
| 4605 For example,@refill | |
| 4606 | 4782 |
| 4607 @example | 4783 @example |
| 4608 @@subsubsection This is a subsubsection | 4784 @@subsubsection This is a subsubsection |
| 4609 @end example | 4785 @end example |
| 4610 | 4786 |
| 4611 @noindent | 4787 @noindent |
| 4612 produces | 4788 might produce |
| 4613 | 4789 |
| 4614 @example | 4790 @example |
| 4615 @group | 4791 @group |
| 4616 1.2.3.4 This is a subsubsection | 4792 1.2.3.4 This is a subsubsection |
| 4617 ............................... | 4793 ............................... |
| 4618 @end group | 4794 @end group |
| 4619 @end example | 4795 @end example |
| 4620 | 4796 |
| 4797 The @TeX{}, HTML, Docbook, and XML output is all analogous to the | |
| 4798 chapter-level output, just ``three levels down''; @pxref{@t{@@chapter}}. | |
| 4799 | |
| 4800 | |
| 4801 @node @t{@@part} | |
| 4802 @section @code{@@part}: Groups of Chapters | |
| 4803 @findex part | |
| 4804 @cindex Part pages | |
| 4805 | |
| 4806 The final sectioning command is @code{@@part}, to mark a @dfn{part} of | |
| 4807 a manual, that is, a group of chapters or (rarely) appendices. This | |
| 4808 behaves quite differently from the other sectioning commands, to fit | |
| 4809 with the way such ``parts'' are conventionally used in books. | |
| 4810 | |
| 4811 No @code{@@node} command is associated with @code{@@part}. Just write | |
| 4812 the command on a line by itself, including the part title, at the | |
| 4813 place in the document you want to mark off as starting that part. For | |
| 4814 example: | |
| 4815 | |
| 4816 @example | |
| 4817 @@part Part I:@@* The beginning | |
| 4818 @end example | |
| 4819 | |
| 4820 As can be inferred from this example, no automatic numbering or | |
| 4821 labeling of the @code{@@part} text is done. The text is taken as-is. | |
| 4822 | |
| 4823 Because parts are not associated with nodes, no general text can | |
| 4824 follow the @code{@@part} line. To produce the intended output, it | |
| 4825 must be followed by a chapter-level command (including its node). | |
| 4826 Thus, to continue the example: | |
| 4827 | |
| 4828 @example | |
| 4829 @@part Part I:@@* The beginning | |
| 4830 | |
| 4831 @@node Introduction | |
| 4832 @@chapter Introduction | |
| 4833 ... | |
| 4834 @end example | |
| 4835 | |
| 4836 In the @TeX{} output, the @code{@@part} text is included in both the | |
| 4837 normal and short tables of contents (@pxref{Contents}), without a page | |
| 4838 number (since that is the normal convention). In addition, a ``part | |
| 4839 page'' is output in the body of the document, with just the | |
| 4840 @code{@@part} text. In the example above, the @code{@@*} causes a | |
| 4841 line break on the part page (but is replaced with a space in the | |
| 4842 tables of contents). This part page is always forced to be on an odd | |
| 4843 (right-hand) page, regardless of the chapter pagination | |
| 4844 (@pxref{@t{@@setchapternewpage}}). | |
| 4845 | |
| 4846 In the HTML output, the @code{@@part} text is similarly included in | |
| 4847 the tables of contents, and a heading is included in the main document | |
| 4848 text, as part of the following chapter or appendix node. | |
| 4849 | |
| 4850 In the XML and Docbook output, the @code{<part>} element includes all | |
| 4851 the following chapters, up to the next @code{<part>}. A @code{<part>} | |
| 4852 containing chapters is also closed at an appendix. | |
| 4853 | |
| 4854 In the Info and plain text output, @code{@@part} has no effect. | |
| 4855 | |
| 4856 @code{@@part} is ignored when raising or lowering sections (see next | |
| 4857 section). That is, it is never lowered and nothing can be raised to it. | |
| 4858 | |
| 4621 | 4859 |
| 4622 @node Raise/lower sections | 4860 @node Raise/lower sections |
| 4623 @section @code{@@raisesections} and @code{@@lowersections} | 4861 @section Raise/lower Sections: @code{@@raisesections} and @code{@@lowersections} |
| 4624 @findex raisesections | 4862 @findex raisesections |
| 4625 @findex lowersections | 4863 @findex lowersections |
| 4626 @cindex Raising and lowering sections | 4864 @cindex Raising and lowering sections |
| 4627 @cindex Lowering and raising sections | 4865 @cindex Lowering and raising sections |
| 4628 @cindex Sections, raising and lowering | 4866 @cindex Sections, raising and lowering |
| 4629 | 4867 |
| 4630 The @code{@@raisesections} and @code{@@lowersections} commands | 4868 The @code{@@raisesections} and @code{@@lowersections} commands |
| 4631 implicitly raise and lower the hierarchical level of following | 4869 implicitly raise and lower the hierarchical level of following |
| 4632 chapters, sections and the other sectioning commands. | 4870 chapters, sections and the other sectioning commands (excluding parts). |
| 4633 | 4871 |
| 4634 That is, the @code{@@raisesections} command changes sections to | 4872 That is, the @code{@@raisesections} command changes sections to |
| 4635 chapters, subsections to sections, and so on. Conversely, the | 4873 chapters, subsections to sections, and so on. Conversely, the |
| 4636 @code{@@lowersections} command changes chapters to sections, sections | 4874 @code{@@lowersections} command changes chapters to sections, sections |
| 4637 to subsections, and so on. Thus, an @code{@@lowersections} command | 4875 to subsections, and so on. Thus, an @code{@@lowersections} command |
| 4638 cancels an @code{@@raisesections} command, and vice versa. | 4876 cancels an @code{@@raisesections} command, and vice versa. |
| 4639 | 4877 |
| 4640 @cindex Include files, and section levels | 4878 @cindex Include files, and section levels |
| 4641 You can use @code{@@lowersections} to include text written as an outer | 4879 You can use @code{@@lowersections} to include text written as an outer |
| 4642 or standalone Texinfo file in another Texinfo file as an inner, | 4880 or standalone Texinfo file in another Texinfo file as an inner, |
| 4643 included file. Typical usage looks like this: | 4881 included file (@pxref{Include Files}). Typical usage looks like this: |
| 4644 | 4882 |
| 4645 @example | 4883 @example |
| 4646 @@lowersections | 4884 @@lowersections |
| 4647 @@include somefile.texi | 4885 @@include somefile.texi |
| 4648 @@raisesections | 4886 @@raisesections |
| 4649 @end example | 4887 @end example |
| 4650 | 4888 |
| 4651 @noindent (Without the @code{@@raisesections}, all the subsequent | 4889 @noindent (Without the @code{@@raisesections}, all the subsequent |
| 4652 sections in the document would be lowered.) | 4890 sections in the main file would also be lowered.) |
| 4653 | 4891 |
| 4654 If the included file being lowered has a @code{@@top} node, you'll | 4892 If the included file being lowered has an @code{@@top} node, you'll |
| 4655 need to conditionalize its inclusion with a flag (@pxref{set value}). | 4893 need to conditionalize its inclusion with a flag (@pxref{@t{@@set |
| 4894 @@value}}). | |
| 4656 | 4895 |
| 4657 Another difficulty can arise with documents that use the (recommended) | 4896 Another difficulty can arise with documents that use the (recommended) |
| 4658 feature of @command{makeinfo} for implicitly determining node | 4897 feature of @command{makeinfo} for implicitly determining node |
| 4659 pointers. Since @command{makeinfo} must assume a hierarchically | 4898 pointers. Since @command{makeinfo} must assume a hierarchically |
| 4660 organized document to determine the pointers, you cannot just | 4899 organized document to determine the pointers, you cannot just |
| 4661 arbitrarily sprinkle @code{@@raisesections} and @code{@@lowersections} | 4900 arbitrarily sprinkle @code{@@raisesections} and @code{@@lowersections} |
| 4662 commands in the document. The final result has to have menus that | 4901 commands throughout the document. The final result has to have menus |
| 4663 take the raising and lowering into account. Therefore, as a practical | 4902 that take the raising and lowering into account. So, as a practical |
| 4664 matter, you generally only want to raise or lower large chunks, | 4903 matter, you generally only want to raise or lower large chunks, |
| 4665 usually in external files as shown above. | 4904 usually in external files as shown above. |
| 4666 | 4905 |
| 4667 Repeated use of the commands continue to raise or lower the | 4906 Repeated use of the commands continues to raise or lower the |
| 4668 hierarchical level a step at a time. An attempt to raise above | 4907 hierarchical level a step at a time. An attempt to raise above |
| 4669 `chapter' reproduces chapter commands; an attempt to lower below | 4908 `chapter' reproduces chapter commands; an attempt to lower below |
| 4670 `subsubsection' reproduces subsubsection commands. Also, lowered | 4909 `subsubsection' reproduces subsubsection commands. Also, lowered |
| 4671 subsubsections and raised chapters will not work with | 4910 subsubsections and raised chapters will not work with |
| 4672 @command{makeinfo}'s feature of implicitly determining node pointers, | 4911 @command{makeinfo}'s feature of implicitly determining node pointers, |
| 4673 since the menu structure won't be correct. | 4912 since the menu structure cannot be represented correctly. |
| 4674 | 4913 |
| 4675 Write each @code{@@raisesections} and @code{@@lowersections} command | 4914 Write each @code{@@raisesections} and @code{@@lowersections} command |
| 4676 on a line of its own. | 4915 on a line of its own. |
| 4677 | 4916 |
| 4678 | 4917 |
| 4685 other nodes, and can contain @dfn{menus} which are lists of nodes. In | 4924 other nodes, and can contain @dfn{menus} which are lists of nodes. In |
| 4686 Info, the movement commands can carry you to a pointed-to node or to a | 4925 Info, the movement commands can carry you to a pointed-to node or to a |
| 4687 node listed in a menu. | 4926 node listed in a menu. |
| 4688 | 4927 |
| 4689 Node pointers and menus provide structure for Info files just as | 4928 Node pointers and menus provide structure for Info files just as |
| 4690 chapters, sections, subsections, and the like, provide structure for | 4929 chapters, sections, subsections, and the like provide structure for |
| 4691 printed books. | 4930 printed books. The two structures are theoretically distinct. In |
| 4692 | 4931 practice, however, the tree structure of printed books is essentially |
| 4693 Because node names are used in cross-references, it is not desirable | 4932 always used for the node and menu structure also, as this leads to a |
| 4694 to casually change them. Such name changes invalidate references from | 4933 document which is easiest to follow. @xref{Texinfo Document |
| 4695 other manuals, from mail archives, and so on. | 4934 Structure}. |
| 4935 | |
| 4936 Because node names are used in cross references, it is not desirable | |
| 4937 to casually change them once published. Such name changes invalidate | |
| 4938 references from other manuals, from mail archives, and so on. | |
| 4939 @xref{HTML Xref Link Preservation}. | |
| 4696 | 4940 |
| 4697 @menu | 4941 @menu |
| 4698 * Two Paths:: Different commands to structure | 4942 * @t{@@node}:: Creating nodes, in detail. |
| 4699 Info output and printed output. | 4943 * @t{makeinfo} Pointer Creation:: Letting makeinfo determine node pointers. |
| 4944 * @t{@@anchor}:: Defining arbitrary cross reference targets. | |
| 4700 * Node Menu Illustration:: A diagram, and sample nodes and menus. | 4945 * Node Menu Illustration:: A diagram, and sample nodes and menus. |
| 4701 * node:: Creating nodes, in detail. | |
| 4702 * makeinfo Pointer Creation:: Letting makeinfo determine node pointers. | |
| 4703 * anchor:: Defining arbitrary cross-reference targets. | |
| 4704 @end menu | 4946 @end menu |
| 4705 | 4947 |
| 4706 | 4948 |
| 4707 @node Two Paths | 4949 @node @t{@@node} |
| 4708 @section Two Paths | 4950 @section The @code{@@node} Command |
| 4709 | 4951 |
| 4710 The node and menu commands and the chapter structuring commands are | 4952 @anchor{node}@c node |
| 4711 technically independent of each other: | 4953 @findex node |
| 4954 @cindex Node, defined | |
| 4955 | |
| 4956 A @dfn{node} is a stretch of text that begins at an @code{@@node} | |
| 4957 command and continues until the next @code{@@node} command. The | |
| 4958 definition of node is different from that for chapter or section. A | |
| 4959 chapter may contain sections and a section may contain subsections, | |
| 4960 but a node cannot contain subnodes: the text of a node continues only | |
| 4961 until the next @code{@@node} command in the file. A node usually | |
| 4962 contains only one chapter structuring command, immediately following | |
| 4963 the @code{@@node} line. | |
| 4964 | |
| 4965 To specify a node, write an @code{@@node} command at the beginning of | |
| 4966 a line, and follow it with up to four arguments, separated by commas, | |
| 4967 on the rest of the same line. The first argument is required; it is | |
| 4968 the name of this node (for details of node names, @pxref{Node Line | |
| 4969 Requirements}). The subsequent arguments are optional---they are the | |
| 4970 names of the `Next', `Previous', and `Up' pointers, in that order. We | |
| 4971 strongly recommend omitting them if your Texinfo document is | |
| 4972 hierarchically organized, as virtually all are (@pxref{@t{makeinfo} | |
| 4973 Pointer Creation}). You may insert spaces before or after each name | |
| 4974 on the @code{@@node} line if you wish; such spaces are ignored. | |
| 4975 | |
| 4976 @opindex accesskey@r{, in HTML output of nodes} | |
| 4977 Whether the node pointers are specified implicitly or explicitly, the | |
| 4978 Info and HTML output from @command{makeinfo} for each node includes | |
| 4979 links to the `Next', `Previous', and `Up' nodes. The HTML also uses | |
| 4980 the @code{accesskey} attribute with the values @samp{n}, @samp{p}, and | |
| 4981 @samp{u} respectively. This allows people using web browsers to | |
| 4982 follow the navigation using (typically) @kbd{M-@var{letter}}, e.g., | |
| 4983 @kbd{M-n} for the `Next' node, from anywhere within the node. | |
| 4984 | |
| 4985 Usually, you write one of the chapter-structuring command lines | |
| 4986 immediately after an @code{@@node} line---for example, an | |
| 4987 @code{@@section} or @code{@@subsection} line. @xref{Structuring | |
| 4988 Command Types}. | |
| 4989 | |
| 4990 @TeX{} uses both @code{@@node} names and chapter-structuring names in | |
| 4991 the output for cross references. For this reason, you must write | |
| 4992 @code{@@node} lines in a Texinfo file that you intend to format for | |
| 4993 printing, even if you do not intend to format it for Info; and you | |
| 4994 must include a chapter-structuring command after a node for it to be a | |
| 4995 valid cross reference target (to @TeX{}). You can use @code{@@anchor} | |
| 4996 (@pxref{@t{@@anchor}}) to make cross references to an arbitrary | |
| 4997 position in a document. | |
| 4998 | |
| 4999 Cross references, such as the one at the end of this sentence, are | |
| 5000 made with @code{@@xref} and related commands; see @ref{Cross | |
| 5001 References}. | |
| 5002 | |
| 5003 @menu | |
| 5004 * Node Names:: How to choose node and pointer names. | |
| 5005 * Writing a Node:: How to write an @code{@@node} line. | |
| 5006 * Node Line Requirements:: Keep names unique. | |
| 5007 * First Node:: How to write a `Top' node. | |
| 5008 * @t{@@top} Command:: How to use the @code{@@top} command. | |
| 5009 @end menu | |
| 5010 | |
| 5011 | |
| 5012 @node Node Names | |
| 5013 @subsection Choosing Node and Pointer Names | |
| 5014 | |
| 5015 @cindex Node names, choosing | |
| 5016 The name of a node identifies the node. For all the details of node | |
| 5017 names, @pxref{Node Line Requirements}). | |
| 5018 | |
| 5019 @anchor{Node Line Tips}@c previous node name | |
| 5020 Here are some suggestions for node names: | |
| 4712 | 5021 |
| 4713 @itemize @bullet | 5022 @itemize @bullet |
| 4714 @item | 5023 @item |
| 4715 In Info, node and menu commands provide structure. The chapter | 5024 Try to pick node names that are informative but short. |
| 4716 structuring commands generate headings with different kinds of | 5025 |
| 4717 underlining---asterisks for chapters, hyphens for sections, and so on; | 5026 In the Info file, the file name, node name, and pointer names are all |
| 4718 they do nothing else.@refill | 5027 inserted on one line, which may run into the right edge of the window. |
| 5028 (This does not cause a problem with Info, but is ugly.) | |
| 4719 | 5029 |
| 4720 @item | 5030 @item |
| 4721 In @TeX{}, the chapter structuring commands generate chapter and section | 5031 Try to pick node names that differ from each other near the beginnings |
| 4722 numbers and tables of contents. The node and menu commands provide | 5032 of their names. This way, it is easy to use automatic name completion in |
| 4723 information for cross references; they do nothing else.@refill | 5033 Info. |
| 5034 | |
| 5035 @item | |
| 5036 Conventionally, node names are capitalized in the same way as section | |
| 5037 and chapter titles. In this manual, initial and significant words are | |
| 5038 capitalized; others are not. In other manuals, just initial words and | |
| 5039 proper nouns are capitalized. Either way is fine; we recommend just | |
| 5040 being consistent. | |
| 4724 @end itemize | 5041 @end itemize |
| 4725 | 5042 |
| 4726 You can use node pointers and menus to structure an Info file any way | 5043 The pointers from a given node enable you to reach other nodes and |
| 4727 you want; and you can write a Texinfo file so that its Info output has a | 5044 consist simply of the names of those nodes. The pointers are usually |
| 4728 different structure than its printed output. However, virtually all | 5045 not specified explicitly, as @command{makeinfo} can determine them |
| 4729 Texinfo files are written such that the structure for the Info output | 5046 (@pxref{@t{makeinfo} Pointer Creation}). |
| 4730 corresponds to the structure for the printed output. It is neither | 5047 |
| 4731 convenient nor understandable to the reader to do otherwise.@refill | 5048 Normally, a node's `Up' pointer contains the name of the node whose |
| 4732 | 5049 menu mentions that node. The node's `Next' pointer contains the name |
| 4733 Generally, printed output is structured in a tree-like hierarchy in | 5050 of the node that follows the present node in that menu and its |
| 4734 which the chapters are the major limbs from which the sections branch | 5051 `Previous' pointer contains the name of the node that precedes it in |
| 4735 out. Similarly, node pointers and menus are organized to create a | 5052 that menu. When a node's `Previous' node is the same as its `Up' |
| 4736 matching structure in the Info output.@refill | 5053 node, both pointers name the same node. |
| 5054 | |
| 5055 Usually, the first node of a Texinfo file is the `Top' node, and its | |
| 5056 `Up' pointer points to the @file{dir} file, which contains the main menu | |
| 5057 for all of Info. | |
| 5058 | |
| 5059 | |
| 5060 @node Writing a Node | |
| 5061 @subsection Writing an @code{@@node} Line | |
| 5062 @cindex Writing an @code{@@node} line | |
| 5063 @cindex @code{@@node} line writing | |
| 5064 @cindex Node line writing | |
| 5065 | |
| 5066 The easiest and preferred way to write an @code{@@node} line is to | |
| 5067 write @code{@@node} at the beginning of a line and then the name of | |
| 5068 the node, like this: | |
| 5069 | |
| 5070 @example | |
| 5071 @@node @var{node-name} | |
| 5072 @end example | |
| 5073 | |
| 5074 If you are using XEmacs, you can use the update node commands | |
| 5075 provided by Texinfo mode to insert the names of the pointers; or | |
| 5076 (recommended), you can leave the pointers out of the Texinfo file and | |
| 5077 let @code{makeinfo} insert node pointers into the Info file it | |
| 5078 creates. (@xref{Texinfo Mode}, and @ref{@t{makeinfo} Pointer | |
| 5079 Creation}.) | |
| 5080 | |
| 5081 Alternatively, you can insert the `Next', `Previous', and `Up' | |
| 5082 pointers yourself. If you do this, you may find it helpful to use the | |
| 5083 Texinfo mode keyboard command @kbd{C-c C-c n}. This command inserts | |
| 5084 @samp{@@node} and a comment line listing the names of the pointers in | |
| 5085 their proper order. The comment line helps you keep track of which | |
| 5086 arguments are for which pointers. This comment line is especially useful | |
| 5087 if you are not familiar with Texinfo. | |
| 5088 | |
| 5089 The template for a fully-written-out node line with `Next', `Previous', | |
| 5090 and `Up' pointers looks like this: | |
| 5091 | |
| 5092 @example | |
| 5093 @@node @var{node-name}, @var{next}, @var{previous}, @var{up} | |
| 5094 @end example | |
| 5095 | |
| 5096 The @var{node-name} argument must be present, but the others are | |
| 5097 optional. If you wish to specify some but not others, just insert | |
| 5098 commas as needed, as in: @samp{@@node mynode,,,uppernode}. However, | |
| 5099 we recommend leaving off all the pointers and letting @code{makeinfo} | |
| 5100 determine them, as described above. | |
| 5101 | |
| 5102 It's, you can ignore @code{@@node} lines altogether in your | |
| 5103 first draft and then use the @code{texinfo-insert-node-lines} command | |
| 5104 to create @code{@@node} lines for you. However, we do not recommend | |
| 5105 this practice. It is better to name the node itself at the same time | |
| 5106 that you write a segment so you can easily make cross references. | |
| 5107 Useful cross references are an especially important feature of a good | |
| 5108 Texinfo manual. | |
| 5109 | |
| 5110 After you have inserted an @code{@@node} line, you should immediately | |
| 5111 write an @@-command for the chapter or section and insert its name. | |
| 5112 Next (and this is important!), put in several index entries. Usually, | |
| 5113 you will find at least two and often as many as four or five ways of | |
| 5114 referring to the node in the index. Use them all. This will make it | |
| 5115 much easier for people to find the node. | |
| 5116 | |
| 5117 Even when you explicitly specify all pointers, you cannot write the | |
| 5118 nodes in the Texinfo source file in an arbitrary order! Because | |
| 5119 formatters must process the file sequentially, irrespective of node | |
| 5120 pointers, you must write the nodes in the order you wish them to | |
| 5121 appear in the output. For Info format one can imagine that the order | |
| 5122 may not matter, but it matters for the other formats. | |
| 5123 | |
| 5124 | |
| 5125 @node Node Line Requirements | |
| 5126 @subsection @code{@@node} Line Requirements | |
| 5127 | |
| 5128 @cindex Node line requirements | |
| 5129 @cindex Restrictions on node names | |
| 5130 | |
| 5131 Names used with @code{@@node} have several requirements: | |
| 5132 | |
| 5133 @itemize @bullet | |
| 5134 @item | |
| 5135 @cindex Unique node names requirement | |
| 5136 @cindex Node names must be unique | |
| 5137 All the node names in a single Texinfo file must be unique. | |
| 5138 | |
| 5139 This means, for example, that if you end every chapter with a summary, | |
| 5140 you must name each summary node differently. You cannot just call | |
| 5141 them all ``Summary''. You may, however, duplicate the titles of | |
| 5142 chapters, sections, and the like. Thus you can end each chapter with | |
| 5143 a section called ``Summary'', so long as the node names for those | |
| 5144 sections are all different. | |
| 5145 | |
| 5146 @item | |
| 5147 The next/previous/up pointers on @code{@@node} lines must be the names | |
| 5148 of nodes. (It's recommended to leave out these explicit node pointer | |
| 5149 names, which automatically avoids any problem here; @pxref{@t{makeinfo} | |
| 5150 Pointer Creation}.) | |
| 5151 | |
| 5152 @item | |
| 5153 @cindex Commands in node names | |
| 5154 @cindex @@-commands in node names | |
| 5155 Node names can contain @@-commands. The output is generally the | |
| 5156 natural result of the command; for example, using @code{@@TeX@{@}} in a | |
| 5157 node name results in the @TeX{} logo being output, as it would be in | |
| 5158 normal text. Cross references should use @code{@@TeX@{@}} just as the | |
| 5159 node name does. | |
| 5160 | |
| 5161 For Info and HTML output, especially, it is necessary to expand | |
| 5162 commands to some sequence of plain characters; for instance, | |
| 5163 @code{@@TeX@{@}} expands to the three letters @samp{TeX} in the Info | |
| 5164 node name. However, cross references to the node should not take the | |
| 5165 ``shortcut'' of using @samp{TeX}; stick to the actual node name, | |
| 5166 commands and all. | |
| 5167 | |
| 5168 Some commands do not make sense in node names; for instance, | |
| 5169 environments (e.g., @code{@@quotation}), commands that read a whole | |
| 5170 line as their argument (e.g., @code{@@sp}), and plenty of others. | |
| 5171 | |
| 5172 For the complete list of commands that are allowed, and their | |
| 5173 expansion for HTML identifiers and file names, @pxref{HTML Xref | |
| 5174 Command Expansion}. The expansions for Info are generally given with | |
| 5175 main the description of the command. | |
| 5176 | |
| 5177 Prior to the Texinfo 5 release in 2013, this feature was supported in | |
| 5178 an ad hoc way (the @option{--commands-in-node-names} option to | |
| 5179 @command{makeinfo}). Now it is part of the language. | |
| 5180 | |
| 5181 @item | |
| 5182 @cindex Colon in node name | |
| 5183 @cindex Comma in node name | |
| 5184 @cindex Parentheses in node name | |
| 5185 @cindex Period in node name | |
| 5186 @cindex Characters, invalid in node name | |
| 5187 @cindex Invalid characters in node names | |
| 5188 @cindex Node names, invalid characters in | |
| 5189 Unfortunately, you cannot reliably use periods, commas, or colons | |
| 5190 within a node name; these can confuse the Info reader. Also, a node | |
| 5191 name may not start with a left parenthesis preceding a right | |
| 5192 parenthesis, as in @code{(not)allowed}, since this syntax is used to | |
| 5193 specify an external manual. (Perhaps these limitations will be | |
| 5194 removed some day.) | |
| 5195 | |
| 5196 @command{makeinfo} warns about such problematic usage in node names, | |
| 5197 menu items, and cross references. If you don't want to see the | |
| 5198 warnings, you can set the customization variable | |
| 5199 @code{INFO_SPECIAL_CHARS_WARNING} to @samp{0} (@pxref{Other | |
| 5200 Customization Variables}). | |
| 5201 | |
| 5202 Also, if you insist on using these characters in node names (accepting | |
| 5203 the resulting substandard Info output), in order not to confuse the | |
| 5204 Texinfo processors you must still escape those characters, by using | |
| 5205 either special insertions (@pxref{Inserting a Comma}) or @code{@@asis} | |
| 5206 (@pxref{@t{@@asis}}). For example: | |
| 5207 | |
| 5208 @example | |
| 5209 @@node foo@@asis@{::@}bar | |
| 5210 @end example | |
| 5211 | |
| 5212 As an example of avoiding the special characters, the following is a | |
| 5213 section title in this manual: | |
| 5214 | |
| 5215 @smallexample | |
| 5216 @@section @@code@{@@@@unnumbered@}, @@code@{@@@@appendix@}: ... | |
| 5217 @end smallexample | |
| 5218 | |
| 5219 @noindent | |
| 5220 But the corresponding node name lacks the commas and the subtitle: | |
| 5221 | |
| 5222 @smallexample | |
| 5223 @@node @t{@@unnumbered @@appendix} | |
| 5224 @end smallexample | |
| 5225 | |
| 5226 @cindex Case in node name | |
| 5227 @item | |
| 5228 Case is significant in node names. | |
| 5229 | |
| 5230 @cindex White space in node name | |
| 5231 @cindex Spaces in node name | |
| 5232 Spaces before and after names on the @samp{@@node} line are ignored. | |
| 5233 Multiple whitespace characters ``inside'' a name are collapsed to a | |
| 5234 single space. For example: | |
| 5235 | |
| 5236 @example | |
| 5237 @@node foo bar, | |
| 5238 @@node foo bar , | |
| 5239 @@node foo bar, | |
| 5240 @@node foo bar , | |
| 5241 @end example | |
| 5242 | |
| 5243 @noindent all define the same node, namely @samp{foo bar}. References | |
| 5244 to the node should all use that name, with no leading or trailing | |
| 5245 spaces, and a single internal space. | |
| 5246 @end itemize | |
| 5247 | |
| 5248 | |
| 5249 @node First Node | |
| 5250 @subsection The First Node | |
| 5251 @cindex Top node is first | |
| 5252 @cindex First node | |
| 5253 | |
| 5254 The first node of a Texinfo file is the @dfn{Top} node, except in an | |
| 5255 included file (@pxref{Include Files}). The Top node should contain a | |
| 5256 short summary, copying permissions, and a master menu. @xref{The Top | |
| 5257 Node}, for more information on the Top node contents and examples. | |
| 5258 | |
| 5259 Here is a description of the node pointers to be used in the Top node: | |
| 5260 | |
| 5261 @itemize @bullet | |
| 5262 @item | |
| 5263 @cindex Up node of Top node | |
| 5264 @cindex (dir) as Up node of Top node | |
| 5265 The Top node (which must be named @samp{top} or @samp{Top}) should have | |
| 5266 as its `Up' node the name of a node in another file, where there is a | |
| 5267 menu that leads to this file. Specify the file name in parentheses. | |
| 5268 | |
| 5269 Usually, all Info files are installed in one system-wide Info tree | |
| 5270 (often constructed from multiple directories). In this case, use | |
| 5271 @samp{(dir)} as the parent of the Top node; this specifies the | |
| 5272 top-level node in the @file{dir} file, which contains the main menu | |
| 5273 for the Info system as a whole. | |
| 5274 | |
| 5275 @item | |
| 5276 @cindex Next node of Top node | |
| 5277 The `Next' node of the Top node should be the first chapter in your | |
| 5278 document. | |
| 5279 | |
| 5280 @end itemize | |
| 5281 | |
| 5282 @xref{Installing an Info File}, for more information about installing | |
| 5283 an Info file in the @file{info} directory. | |
| 5284 | |
| 5285 It is usually best to leave the pointers off entirely and let the | |
| 5286 tools implicitly define them, with this simple result: | |
| 5287 | |
| 5288 @example | |
| 5289 @@node Top | |
| 5290 @end example | |
| 5291 | |
| 5292 | |
| 5293 @node @t{@@top} Command | |
| 5294 @subsection The @code{@@top} Sectioning Command | |
| 5295 | |
| 5296 @anchor{top command}@c old name | |
| 5297 @anchor{makeinfo top}@c another old name | |
| 5298 @anchor{makeinfo top command}@c yet another name | |
| 5299 @findex top | |
| 5300 | |
| 5301 The @code{@@top} command is a special sectioning command that you | |
| 5302 should only use after an @samp{@@node Top} line at the beginning of a | |
| 5303 Texinfo file. The @code{@@top} command tells the @code{makeinfo} | |
| 5304 formatter which node is to be used as the root of the node tree | |
| 5305 (needed if your manual uses implicit node pointers). | |
| 5306 | |
| 5307 It produces the same sort of output as @code{@@unnumbered} | |
| 5308 (@pxref{@t{@@unnumbered @@appendix}}). | |
| 5309 | |
| 5310 The @code{@@top} node is conventionally wrapped in an | |
| 5311 @code{@@ifnottex} conditional so that it will not appear in @TeX{} | |
| 5312 output (@pxref{Conditionals}). | |
| 5313 Thus, in practice, a Top node usually looks like this: | |
| 5314 | |
| 5315 @example | |
| 5316 @@ifnottex | |
| 5317 @@node Top | |
| 5318 @@top @var{your-manual-title} | |
| 5319 | |
| 5320 @var{very-high-level-summary} | |
| 5321 @@end ifnottex | |
| 5322 @end example | |
| 5323 | |
| 5324 @code{@@top} is ignored when raising or lowering sections. That is, | |
| 5325 it is never lowered and nothing can be raised to it | |
| 5326 (@pxref{Raise/lower sections}). | |
| 5327 | |
| 5328 | |
| 5329 @node @t{makeinfo} Pointer Creation | |
| 5330 @section @code{makeinfo} Pointer Creation | |
| 5331 | |
| 5332 @cindex Creating pointers with @code{makeinfo} | |
| 5333 @cindex Pointer creation with @code{makeinfo} | |
| 5334 @cindex Automatic pointer creation with @code{makeinfo} | |
| 5335 @cindex Implicit pointer creation with @code{makeinfo} | |
| 5336 | |
| 5337 The @code{makeinfo} program can automatically determine node pointers | |
| 5338 for a hierarchically organized document. This implicit node pointer | |
| 5339 creation feature in @code{makeinfo} relieves you from the need to | |
| 5340 update menus and pointers manually or with Texinfo mode commands. | |
| 5341 (@xref{Updating Nodes and Menus}.) We highly recommend taking | |
| 5342 advantage of this. | |
| 5343 | |
| 5344 To do so, write your @code{@@node} lines with just the name of the | |
| 5345 node: | |
| 5346 | |
| 5347 @example | |
| 5348 @@node My Node | |
| 5349 @end example | |
| 5350 | |
| 5351 @noindent | |
| 5352 You do not need to write out the `Next', `Previous', and `Up' | |
| 5353 pointers. | |
| 5354 | |
| 5355 Then, you must write a sectioning command, such as @code{@@chapter} | |
| 5356 or @code{@@section}, on the line immediately following each truncated | |
| 5357 @code{@@node} line (except that comment lines may intervene). This is | |
| 5358 where it normally goes. | |
| 5359 | |
| 5360 Also, you must write the name of each node (except for the `Top' node) | |
| 5361 in a menu that is one or more hierarchical levels above the node's | |
| 5362 level. | |
| 5363 | |
| 5364 Finally, you must follow the `Top' @code{@@node} line with a line | |
| 5365 beginning with @code{@@top} to mark the top-level node in the file. | |
| 5366 @xref{@t{@@top} Command}. | |
| 5367 | |
| 5368 @cindex Detail menu | |
| 5369 @findex detailmenu | |
| 5370 If you use a detailed menu in your master menu (@pxref{Master Menu | |
| 5371 Parts}), mark it with the @code{@@detailmenu @dots{} @@end | |
| 5372 detailmenu} environment, or @command{makeinfo} will get confused, | |
| 5373 typically about the last and/or first node in the document. | |
| 5374 | |
| 5375 In most cases, you will want to take advantage of this feature and not | |
| 5376 redundantly specify node pointers that the programs can determine. | |
| 5377 However, Texinfo documents are not required to be organized | |
| 5378 hierarchically or in fact to contain sectioning commands at all (for | |
| 5379 example, if you never intend the document to be printed), so node | |
| 5380 pointers may still be specified explicitly, in full generality. | |
| 5381 | |
| 5382 | |
| 5383 @node @t{@@anchor} | |
| 5384 @section @code{@@anchor}: Defining Arbitrary Cross Reference Targets | |
| 5385 | |
| 5386 @anchor{anchor}@c old name | |
| 5387 @findex anchor | |
| 5388 @cindex Anchors | |
| 5389 @cindex Cross reference targets, arbitrary | |
| 5390 @cindex Targets for cross references, arbitrary | |
| 5391 | |
| 5392 An @dfn{anchor} is a position in your document, labeled so that cross | |
| 5393 references can refer to it, just as they can to nodes. You create an | |
| 5394 anchor with the @code{@@anchor} command, and give the label as a | |
| 5395 normal brace-delimited argument. For example: | |
| 5396 | |
| 5397 @example | |
| 5398 This marks the @@anchor@{x-spot@}spot. | |
| 5399 @dots{} | |
| 5400 @@xref@{x-spot,,the spot@}. | |
| 5401 @end example | |
| 5402 | |
| 5403 @noindent produces: | |
| 5404 | |
| 5405 @example | |
| 5406 This marks the spot. | |
| 5407 @dots{} | |
| 5408 See [the spot], page 1. | |
| 5409 @end example | |
| 5410 | |
| 5411 As you can see, the @code{@@anchor} command itself produces no output. | |
| 5412 This example defines an anchor `x-spot' just before the word `spot'. | |
| 5413 You can refer to it later with an @code{@@xref} or other cross | |
| 5414 reference command, as shown (@pxref{Cross References}). | |
| 5415 | |
| 5416 It is best to put @code{@@anchor} commands just before the position you | |
| 5417 wish to refer to; that way, the reader's eye is led on to the correct | |
| 5418 text when they jump to the anchor. You can put the @code{@@anchor} | |
| 5419 command on a line by itself if that helps readability of the source. | |
| 5420 Whitespace (including newlines) is ignored after @code{@@anchor}. | |
| 5421 | |
| 5422 Anchor names and node names may not conflict. Anchors and nodes are | |
| 5423 given similar treatment in some ways; for example, the | |
| 5424 @code{goto-node} command takes either an anchor name or a node name as | |
| 5425 an argument. (@xref{Go to node,,, info, Info}.) | |
| 5426 | |
| 5427 Also like node names, anchor names cannot include some characters | |
| 5428 (@pxref{Node Line Requirements}). | |
| 5429 | |
| 5430 @cindex Nodes, deleting or renaming | |
| 5431 Because of this duality, when you delete or rename a node, it is | |
| 5432 usually a good idea to define an @code{@@anchor} with the old name. | |
| 5433 That way, any links to the old node, whether from other Texinfo | |
| 5434 manuals or general web pages, keep working. You can also do this with | |
| 5435 the @file{RENAMED_NODES_FILE} feature of @command{makeinfo} | |
| 5436 (@pxref{HTML Xref Link Preservation}). Both methods keep links | |
| 5437 on the web working; the only substantive difference is that defining | |
| 5438 anchors also makes the old node names available when reading the | |
| 5439 document in Info. | |
| 4737 | 5440 |
| 4738 | 5441 |
| 4739 @node Node Menu Illustration | 5442 @node Node Menu Illustration |
| 4740 @section Node and Menu Illustration | 5443 @section Node and Menu Illustration |
| 4741 | 5444 |
| 4742 Here is a copy of the diagram shown earlier that illustrates a Texinfo | 5445 Here is a copy of the diagram shown earlier that illustrates a Texinfo |
| 4743 file with three chapters, each of which contains two sections.@refill | 5446 file with three chapters, each of which contains two sections. |
| 4744 | 5447 |
| 4745 The ``root'' is at the top of the diagram and the ``leaves'' are at the | 5448 The ``root'' is at the top of the diagram and the ``leaves'' are at |
| 4746 bottom. This is how such a diagram is drawn conventionally; it | 5449 the bottom. This is how such a diagram is drawn conventionally; it |
| 4747 illustrates an upside-down tree. For this reason, the root node is | 5450 illustrates an upside-down tree. For this reason, the root node is |
| 4748 called the `Top' node, and `Up' node pointers carry you closer to the | 5451 called the `Top' node, and `Up' node pointers carry you closer to the |
| 4749 root.@refill | 5452 root. |
| 4750 | 5453 |
| 4751 @example | 5454 @example |
| 4752 @group | 5455 @group |
| 4753 Top | 5456 Top |
| 4754 | | 5457 | |
| 4761 Section Section Section Section Section Section | 5464 Section Section Section Section Section Section |
| 4762 1.1 1.2 2.1 2.2 3.1 3.2 | 5465 1.1 1.2 2.1 2.2 3.1 3.2 |
| 4763 @end group | 5466 @end group |
| 4764 @end example | 5467 @end example |
| 4765 | 5468 |
| 4766 The fully-written command to start Chapter 2 would be this: | 5469 Using explicit pointers (not recommended, but for shown for purposes |
| 5470 of the example), the fully-written command to start Chapter@tie{}2 | |
| 5471 would be this: | |
| 4767 | 5472 |
| 4768 @example | 5473 @example |
| 4769 @group | 5474 @group |
| 4770 @@node Chapter 2, Chapter 3, Chapter 1, Top | 5475 @@node Chapter 2, Chapter 3, Chapter 1, Top |
| 4771 @@comment node-name, next, previous, up | 5476 @@comment node-name, next, previous, up |
| 4772 @end group | 5477 @end group |
| 4773 @end example | 5478 @end example |
| 4774 | 5479 |
| 4775 @noindent | 5480 @noindent |
| 4776 This @code{@@node} line says that the name of this node is ``Chapter | 5481 This @code{@@node} line says that the name of this node is |
| 4777 2'', the name of the `Next' node is ``Chapter 3'', the name of the | 5482 ``Chapter@tie{}2'', the name of the `Next' node is ``Chapter 3'', the |
| 4778 `Previous' node is ``Chapter 1'', and the name of the `Up' node is | 5483 name of the `Previous' node is ``Chapter@tie{}1'', and the name of the |
| 4779 ``Top''. You can omit writing out these node names if your document is | 5484 `Up' node is ``Top''. You can (and should) omit writing out these |
| 4780 hierarchically organized (@pxref{makeinfo Pointer Creation}), but the | 5485 node names if your document is hierarchically organized |
| 4781 pointer relationships still obtain. | 5486 (@pxref{@t{makeinfo} Pointer Creation}), but the pointer |
| 5487 relationships still obtain. | |
| 4782 | 5488 |
| 4783 @quotation Note | 5489 @quotation Note |
| 4784 @strong{Please Note:} `Next' refers to the next node at the same | 5490 `Next' and `Previous' refer to nodes at the @emph{same hierarchical |
| 4785 hierarchical level in the manual, not necessarily to the next node | 5491 level} in the manual, not necessarily to the next node within the |
| 4786 within the Texinfo file. In the Texinfo file, the subsequent node may | 5492 Texinfo file. In the Texinfo file, the subsequent node may be at a |
| 4787 be at a lower level---a section-level node most often follows a | 5493 lower level---a section-level node most often follows a chapter-level |
| 4788 chapter-level node, for example. `Next' and `Previous' refer to nodes | 5494 node, for example. (The `Top' node contains the exception to this |
| 4789 at the @emph{same} hierarchical level. (The `Top' node contains the | 5495 rule. Since the `Top' node is the only node at that level, `Next' |
| 4790 exception to this rule. Since the `Top' node is the only node at that | 5496 refers to the first following node, which is almost always a chapter |
| 4791 level, `Next' refers to the first following node, which is almost always | 5497 or chapter-level node.) |
| 4792 a chapter or chapter-level node.)@refill | |
| 4793 @end quotation | 5498 @end quotation |
| 4794 | 5499 |
| 4795 To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter | 5500 To go to Sections 2.1 and 2.2 using Info, you need a menu inside |
| 4796 2. (@xref{Menus}.) You would write the menu just | 5501 Chapter 2. (@xref{Menus}.) You would write the menu just before the |
| 4797 before the beginning of Section 2.1, like this:@refill | 5502 beginning of Section 2.1, like this: |
| 4798 | 5503 |
| 4799 @example | 5504 @example |
| 4800 @group | 5505 @group |
| 4801 @@menu | 5506 @@menu |
| 4802 * Sect. 2.1:: Description of this section. | 5507 * Sect. 2.1:: Description of this section. |
| 4803 * Sect. 2.2:: | 5508 * Sect. 2.2:: Description. |
| 4804 @@end menu | 5509 @@end menu |
| 4805 @end group | 5510 @end group |
| 4806 @end example | 5511 @end example |
| 4807 | 5512 |
| 4808 Write the node for Sect. 2.1 like this:@refill | 5513 Using explicit pointers, the node for Sect.@: 2.1 is written like this: |
| 4809 | 5514 |
| 4810 @example | 5515 @example |
| 4811 @group | 5516 @group |
| 4812 @@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2 | 5517 @@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2 |
| 4813 @@comment node-name, next, previous, up | 5518 @@comment node-name, next, previous, up |
| 4814 @end group | 5519 @end group |
| 4815 @end example | 5520 @end example |
| 4816 | 5521 |
| 4817 In Info format, the `Next' and `Previous' pointers of a node usually | 5522 In Info format, the `Next' and `Previous' pointers of a node usually |
| 4818 lead to other nodes at the same level---from chapter to chapter or from | 5523 lead to other nodes at the same level---from chapter to chapter or |
| 4819 section to section (sometimes, as shown, the `Previous' pointer points | 5524 from section to section (sometimes, as shown, the `Previous' pointer |
| 4820 up); an `Up' pointer usually leads to a node at the level above (closer | 5525 points up); an `Up' pointer usually leads to a node at the level above |
| 4821 to the `Top' node); and a `Menu' leads to nodes at a level below (closer | 5526 (closer to the `Top' node); and a `Menu' leads to nodes at a level |
| 4822 to `leaves'). (A cross reference can point to a node at any level; | 5527 below (closer to `leaves'). (A cross reference can point to a node at |
| 4823 see @ref{Cross References}.)@refill | 5528 any level; see @ref{Cross References}.) |
| 4824 | 5529 |
| 4825 Usually, an @code{@@node} command and a chapter structuring command are | 5530 Usually, an @code{@@node} command and a chapter structuring command |
| 4826 used in sequence, along with indexing commands. (You may follow the | 5531 are conventionally used together, in that order, often followed by |
| 4827 @code{@@node} line with a comment line that reminds you which pointer is | 5532 indexing commands. (As shown in the example above, you may follow the |
| 4828 which.)@refill | 5533 @code{@@node} line with a comment line, e.g., to show which pointer is |
| 5534 which if explicit pointers are used.) The Texinfo processors use this | |
| 5535 construct to determine the relationships between nodes and sectioning | |
| 5536 commands. | |
| 4829 | 5537 |
| 4830 Here is the beginning of the chapter in this manual called ``Ending a | 5538 Here is the beginning of the chapter in this manual called ``Ending a |
| 4831 Texinfo File''. This shows an @code{@@node} line followed by a comment | 5539 Texinfo File''. This shows an @code{@@node} line followed by an |
| 4832 line, an @code{@@chapter} line, and then by indexing lines.@refill | 5540 @code{@@chapter} line, and then by indexing lines. The manual uses |
| 5541 implictly determined node pointers; therefore, nothing else is needed | |
| 5542 on the @code{@@node} line. | |
| 5543 | |
| 5544 @example | |
| 5545 @group | |
| 5546 @@node Ending a File | |
| 5547 @@chapter Ending a Texinfo File | |
| 5548 @@cindex Ending a Texinfo file | |
| 5549 @@cindex Texinfo file ending | |
| 5550 @@cindex File ending | |
| 5551 @end group | |
| 5552 @end example | |
| 5553 | |
| 5554 An earlier version of the manual used explicit node pointers. Here is | |
| 5555 the beginning of the same chapter for that case. This shows an | |
| 5556 @code{@@node} line followed by a comment line, an @code{@@chapter} | |
| 5557 line, and then by indexing lines. | |
| 4833 | 5558 |
| 4834 @example | 5559 @example |
| 4835 @group | 5560 @group |
| 4836 @@node Ending a File, Structuring, Beginning a File, Top | 5561 @@node Ending a File, Structuring, Beginning a File, Top |
| 4837 @@comment node-name, next, previous, up | 5562 @@comment node-name, next, previous, up |
| 4838 @@chapter Ending a Texinfo File | 5563 @@chapter Ending a Texinfo File |
| 4839 @@cindex Ending a Texinfo file | 5564 @@cindex Ending a Texinfo file |
| 4840 @@cindex Texinfo file ending | 5565 @dots{} |
| 4841 @@cindex File ending | |
| 4842 @end group | 5566 @end group |
| 4843 @end example | 5567 @end example |
| 4844 | |
| 4845 | |
| 4846 @node node | |
| 4847 @section The @code{@@node} Command | |
| 4848 | |
| 4849 @cindex Node, defined | |
| 4850 @findex node | |
| 4851 | |
| 4852 A @dfn{node} is a segment of text that begins at an @code{@@node} | |
| 4853 command and continues until the next @code{@@node} command. The | |
| 4854 definition of node is different from that for chapter or section. A | |
| 4855 chapter may contain sections and a section may contain subsections; | |
| 4856 but a node cannot contain subnodes; the text of a node continues only | |
| 4857 until the next @code{@@node} command in the file. A node usually | |
| 4858 contains only one chapter structuring command, the one that follows | |
| 4859 the @code{@@node} line. On the other hand, in printed output nodes | |
| 4860 are used only for cross references, so a chapter or section may | |
| 4861 contain any number of nodes. Indeed, a chapter usually contains | |
| 4862 several nodes, one for each section, subsection, and | |
| 4863 subsubsection. | |
| 4864 | |
| 4865 To specify a node, write an @code{@@node} command at the beginning of | |
| 4866 a line, and follow it with up to four arguments, separated by commas, | |
| 4867 on the rest of the same line. The first argument is required; it is | |
| 4868 the name of this node (for details of node names, @pxref{Node Line | |
| 4869 Requirements}). The subsequent arguments are the names of the `Next', | |
| 4870 `Previous', and `Up' pointers, in that order, and may be omitted if | |
| 4871 your Texinfo document is hierarchically organized (@pxref{makeinfo | |
| 4872 Pointer Creation}). | |
| 4873 | |
| 4874 @opindex accesskey@r{, in HTML output} | |
| 4875 Whether the node pointers are specified implicitly or explicitly, the | |
| 4876 HTML output from @command{makeinfo} for each node includes links to | |
| 4877 the `Next', `Previous', and `Up' nodes. The HTML also uses the | |
| 4878 @code{accesskey} attribute with the values @samp{n}, @samp{p}, and | |
| 4879 @samp{u} respectively. This allows people using web browsers to | |
| 4880 follow the nagivation using (typically) @kbd{M-@var{letter}}, e.g., | |
| 4881 @kbd{M-n} for the `Next' node, from anywhere within the node. | |
| 4882 | |
| 4883 You may insert spaces before each name on the @code{@@node} line if | |
| 4884 you wish; the spaces are ignored. You must write the name of the node | |
| 4885 and (if present) the names of the `Next', `Previous', and `Up' | |
| 4886 pointers all on the same line. Otherwise, the formatters fail. | |
| 4887 (@inforef{Top, info, info}, for more information about nodes in Info.) | |
| 4888 | |
| 4889 Usually, you write one of the chapter-structuring command lines | |
| 4890 immediately after an @code{@@node} line---for example, an | |
| 4891 @code{@@section} or @code{@@subsection} line. (@xref{Structuring | |
| 4892 Command Types}.) | |
| 4893 | |
| 4894 @TeX{} uses @code{@@node} lines to identify the names to use for cross | |
| 4895 references. For this reason, you must write @code{@@node} lines in a | |
| 4896 Texinfo file that you intend to format for printing, even if you do not | |
| 4897 intend to format it for Info. (Cross references, such as the one at the | |
| 4898 end of this sentence, are made with @code{@@xref} and related commands; | |
| 4899 see @ref{Cross References}.) | |
| 4900 | |
| 4901 @menu | |
| 4902 * Node Names:: How to choose node and pointer names. | |
| 4903 * Writing a Node:: How to write an @code{@@node} line. | |
| 4904 * Node Line Tips:: Keep names short. | |
| 4905 * Node Line Requirements:: Keep names unique, without @@-commands. | |
| 4906 * First Node:: How to write a `Top' node. | |
| 4907 * makeinfo top command:: How to use the @code{@@top} command. | |
| 4908 @end menu | |
| 4909 | |
| 4910 | |
| 4911 @node Node Names | |
| 4912 @subsection Choosing Node and Pointer Names | |
| 4913 | |
| 4914 @cindex Node names, choosing | |
| 4915 The name of a node identifies the node (for details of node names, | |
| 4916 @pxref{Node Line Requirements}). The pointers enable you to reach | |
| 4917 other nodes and consist simply of the names of those nodes. | |
| 4918 | |
| 4919 Normally, a node's `Up' pointer contains the name of the node whose | |
| 4920 menu mentions that node. The node's `Next' pointer contains the name | |
| 4921 of the node that follows the present node in that menu and its | |
| 4922 `Previous' pointer contains the name of the node that precedes it in | |
| 4923 that menu. When a node's `Previous' node is the same as its `Up' | |
| 4924 node, both node pointers name the same node. | |
| 4925 | |
| 4926 Usually, the first node of a Texinfo file is the `Top' node, and its | |
| 4927 `Up' and `Previous' pointers point to the @file{dir} file, which | |
| 4928 contains the main menu for all of Info. | |
| 4929 | |
| 4930 The `Top' node itself contains the main or master menu for the manual. | |
| 4931 Also, it is helpful to include a brief description of the manual in the | |
| 4932 `Top' node. @xref{First Node}, for information on how to write the | |
| 4933 first node of a Texinfo file. | |
| 4934 | |
| 4935 Even when you explicitly specify all pointers, that does not mean you | |
| 4936 can write the nodes in the Texinfo source file in an arbitrary order! | |
| 4937 Because @TeX{} processes the file sequentially, irrespective of node | |
| 4938 pointers, you must write the nodes in the order you wish them to appear | |
| 4939 in the output. | |
| 4940 | |
| 4941 | |
| 4942 @node Writing a Node | |
| 4943 @subsection How to Write an @code{@@node} Line | |
| 4944 @cindex Writing an @code{@@node} line | |
| 4945 @cindex @code{@@node} line writing | |
| 4946 @cindex Node line writing | |
| 4947 | |
| 4948 The easiest way to write an @code{@@node} line is to write @code{@@node} | |
| 4949 at the beginning of a line and then the name of the node, like | |
| 4950 this: | |
| 4951 | |
| 4952 @example | |
| 4953 @@node @var{node-name} | |
| 4954 @end example | |
| 4955 | |
| 4956 If you are using XEmacs, you can use the update node commands | |
| 4957 provided by Texinfo mode to insert the names of the pointers; or you | |
| 4958 can leave the pointers out of the Texinfo file and let @code{makeinfo} | |
| 4959 insert node pointers into the Info file it creates. (@xref{Texinfo | |
| 4960 Mode}, and @ref{makeinfo Pointer Creation}.) | |
| 4961 | |
| 4962 Alternatively, you can insert the `Next', `Previous', and `Up' | |
| 4963 pointers yourself. If you do this, you may find it helpful to use the | |
| 4964 Texinfo mode keyboard command @kbd{C-c C-c n}. This command inserts | |
| 4965 @samp{@@node} and a comment line listing the names of the pointers in | |
| 4966 their proper order. The comment line helps you keep track of which | |
| 4967 arguments are for which pointers. This comment line is especially useful | |
| 4968 if you are not familiar with Texinfo. | |
| 4969 | |
| 4970 The template for a fully-written-out node line with `Next', `Previous', | |
| 4971 and `Up' pointers looks like this: | |
| 4972 | |
| 4973 @example | |
| 4974 @@node @var{node-name}, @var{next}, @var{previous}, @var{up} | |
| 4975 @end example | |
| 4976 | |
| 4977 The @var{node-name} argument must be present, but the others are | |
| 4978 optional. If you wish to specify some but not others, just insert | |
| 4979 commas as needed, as in: @samp{@@node mynode,,,uppernode}. However, | |
| 4980 we recommend leaving off all the pointers and letting @code{makeinfo} | |
| 4981 determine them, as described above. | |
| 4982 | |
| 4983 If you wish, you can ignore @code{@@node} lines altogether in your first | |
| 4984 draft and then use the @code{texinfo-insert-node-lines} command to | |
| 4985 create @code{@@node} lines for you. However, we do not recommend this | |
| 4986 practice. It is better to name the node itself at the same time that | |
| 4987 you write a segment so you can easily make cross references. A large | |
| 4988 number of cross references are an especially important feature of a good | |
| 4989 Info file. | |
| 4990 | |
| 4991 After you have inserted an @code{@@node} line, you should immediately | |
| 4992 write an @@-command for the chapter or section and insert its name. | |
| 4993 Next (and this is important!), put in several index entries. Usually, | |
| 4994 you will find at least two and often as many as four or five ways of | |
| 4995 referring to the node in the index. Use them all. This will make it | |
| 4996 much easier for people to find the node. | |
| 4997 | |
| 4998 | |
| 4999 @node Node Line Tips | |
| 5000 @subsection @code{@@node} Line Tips | |
| 5001 | |
| 5002 Here are three suggestions: | |
| 5003 | |
| 5004 @itemize @bullet | |
| 5005 @item | |
| 5006 Try to pick node names that are informative but short.@refill | |
| 5007 | |
| 5008 In the Info file, the file name, node name, and pointer names are all | |
| 5009 inserted on one line, which may run into the right edge of the window. | |
| 5010 (This does not cause a problem with Info, but is ugly.)@refill | |
| 5011 | |
| 5012 @item | |
| 5013 Try to pick node names that differ from each other near the beginnings | |
| 5014 of their names. This way, it is easy to use automatic name completion in | |
| 5015 Info.@refill | |
| 5016 | |
| 5017 @item | |
| 5018 By convention, node names are capitalized just as they would be for | |
| 5019 section or chapter titles---initial and significant words are | |
| 5020 capitalized; others are not.@refill | |
| 5021 @end itemize | |
| 5022 | |
| 5023 | |
| 5024 @node Node Line Requirements | |
| 5025 @subsection @code{@@node} Line Requirements | |
| 5026 | |
| 5027 @cindex Node line requirements | |
| 5028 @cindex Restrictions on node names | |
| 5029 Here are several requirements for @code{@@node} lines: | |
| 5030 | |
| 5031 @itemize @bullet | |
| 5032 @cindex Unique nodename requirement | |
| 5033 @cindex Node name must be unique | |
| 5034 @item | |
| 5035 All the node names for a single Info file must be unique. | |
| 5036 | |
| 5037 Duplicates confuse the Info movement commands. This means, for | |
| 5038 example, that if you end every chapter with a summary, you must name | |
| 5039 each summary node differently. You cannot just call each one | |
| 5040 ``Summary''. You may, however, duplicate the titles of chapters, sections, | |
| 5041 and the like. Thus you can end each chapter in a book with a section | |
| 5042 called ``Summary'', so long as the node names for those sections are all | |
| 5043 different. | |
| 5044 | |
| 5045 @item | |
| 5046 A pointer name must be the name of a node. | |
| 5047 | |
| 5048 The node to which a pointer points may come before or after the | |
| 5049 node containing the pointer. | |
| 5050 | |
| 5051 @cindex @@-commands in nodename | |
| 5052 @cindex Node name, should not contain @@-commands | |
| 5053 @item | |
| 5054 @@-commands in node names are not allowed. This includes punctuation | |
| 5055 characters that are escaped with a @samp{@@}, such as @code{@@} and | |
| 5056 @code{@{}, and accent commands such as @samp{@@'}. (For a few cases | |
| 5057 when this is useful, Texinfo has limited support for using | |
| 5058 @w{@@-commands} in node names; see @ref{Pointer Validation}.) Perhaps | |
| 5059 this limitation will be removed some day. | |
| 5060 | |
| 5061 @item | |
| 5062 @cindex Colon in nodename | |
| 5063 @cindex Comma in nodename | |
| 5064 @cindex Parentheses in nodename | |
| 5065 @cindex Period in nodename | |
| 5066 @cindex Characters, invalid in node name | |
| 5067 @cindex Invalid characters in node names | |
| 5068 @cindex Node names, invalid characters in | |
| 5069 Unfortunately, you cannot use periods, commas, colons or parentheses | |
| 5070 within a node name; these confuse the Texinfo processors. Perhaps | |
| 5071 this limitation will be removed some day, too. | |
| 5072 | |
| 5073 @need 700 | |
| 5074 For example, the following is a section title in this manual: | |
| 5075 | |
| 5076 @smallexample | |
| 5077 @@code@{@@@@unnumberedsec@}, @@code@{@@@@appendixsec@}, @@code@{@@@@heading@} | |
| 5078 @end smallexample | |
| 5079 | |
| 5080 @noindent | |
| 5081 But the corresponding node name lacks the commas and the @@'s: | |
| 5082 | |
| 5083 @smallexample | |
| 5084 unnumberedsec appendixsec heading | |
| 5085 @end smallexample | |
| 5086 | |
| 5087 @cindex Case in node name | |
| 5088 @item | |
| 5089 Case is significant in node names. | |
| 5090 | |
| 5091 @cindex White space in node name | |
| 5092 @cindex Spaces in node name | |
| 5093 Spaces before and after names on the @samp{@@node} line are ignored, | |
| 5094 but spaces ``inside'' a name are significant. For example: | |
| 5095 | |
| 5096 @example | |
| 5097 @@node foo bar, | |
| 5098 @@node foo bar , | |
| 5099 @@node foo bar , | |
| 5100 @end example | |
| 5101 | |
| 5102 @noindent all define the same node, @samp{foo bar}. References to the | |
| 5103 node should all use that name, without the leading or trailing spaces, | |
| 5104 but with the internal spaces. | |
| 5105 @end itemize | |
| 5106 | |
| 5107 | |
| 5108 @node First Node | |
| 5109 @subsection The First Node | |
| 5110 @cindex Top node is first | |
| 5111 @cindex First node | |
| 5112 | |
| 5113 The first node of a Texinfo file is the @dfn{Top} node, except in an | |
| 5114 included file (@pxref{Include Files}). The Top node should contain a | |
| 5115 short summary, copying permissions, and a master menu. @xref{The Top | |
| 5116 Node}, for more information on the Top node contents and examples. | |
| 5117 | |
| 5118 Here is a description of the node pointers to be used in the Top node: | |
| 5119 | |
| 5120 @itemize @bullet | |
| 5121 | |
| 5122 @item | |
| 5123 @cindex Up node of Top node | |
| 5124 @cindex (dir) as Up node of Top node | |
| 5125 The Top node (which must be named @samp{top} or @samp{Top}) should have | |
| 5126 as its `Up' node the name of a node in another file, where there is a | |
| 5127 menu that leads to this file. Specify the file name in parentheses. | |
| 5128 | |
| 5129 Usually, all Info files are installed in the same Info directory tree; | |
| 5130 in this case, use @samp{(dir)} as the parent of the Top node; this is | |
| 5131 short for @samp{(dir)top}, and specifies the Top node in the @file{dir} | |
| 5132 file, which contains the main menu for the Info system as a whole. | |
| 5133 | |
| 5134 @item | |
| 5135 @cindex Prev node of Top node | |
| 5136 The `Prev' node of the Top node should also be your @samp{(dir)} file. | |
| 5137 | |
| 5138 @item | |
| 5139 @cindex Next node of Top node | |
| 5140 The `Next' node of the Top node should be the first chapter in your | |
| 5141 document. | |
| 5142 | |
| 5143 @end itemize | |
| 5144 | |
| 5145 @xref{Installing an Info File}, for more information about installing | |
| 5146 an Info file in the @file{info} directory. | |
| 5147 | |
| 5148 It is usually best to leave the pointers off entirely and let the | |
| 5149 tools implicitly define them, with this simple result: | |
| 5150 | |
| 5151 @example | |
| 5152 @@node Top | |
| 5153 @end example | |
| 5154 | |
| 5155 | |
| 5156 @node makeinfo top command | |
| 5157 @subsection The @code{@@top} Sectioning Command | |
| 5158 @findex top @r{(@@-command)} | |
| 5159 | |
| 5160 A special sectioning command, @code{@@top} should be used with the | |
| 5161 @code{@@node Top} line. The @code{@@top} sectioning command tells | |
| 5162 @code{makeinfo} that it marks the `Top' node in the file. It provides | |
| 5163 the information that @code{makeinfo} needs to insert node pointers | |
| 5164 automatically. Write the @code{@@top} command at the beginning of the | |
| 5165 line immediately following the @code{@@node Top} line. Write the title | |
| 5166 on the remaining part of the same line as the @code{@@top} command. | |
| 5167 | |
| 5168 In Info, the @code{@@top} sectioning command causes the title to appear | |
| 5169 on a line by itself, with a line of asterisks inserted underneath, as | |
| 5170 other sectioning commands do. | |
| 5171 | |
| 5172 In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top} | |
| 5173 sectioning command is merely a synonym for @code{@@unnumbered}. | |
| 5174 Neither of these formatters require an @code{@@top} command, and do | |
| 5175 nothing special with it. You can use @code{@@chapter} or | |
| 5176 @code{@@unnumbered} after the @code{@@node Top} line when you use | |
| 5177 these formatters. Also, you can use @code{@@chapter} or | |
| 5178 @code{@@unnumbered} when you use the Texinfo updating commands to | |
| 5179 create or update pointers and menus. | |
| 5180 | |
| 5181 Thus, in practice, a Top node starts like this: | |
| 5182 | |
| 5183 @example | |
| 5184 @@node Top | |
| 5185 @@top Your Manual Title | |
| 5186 @end example | |
| 5187 | |
| 5188 | |
| 5189 @node makeinfo Pointer Creation | |
| 5190 @section Creating Pointers with @code{makeinfo} | |
| 5191 @cindex Creating pointers with @code{makeinfo} | |
| 5192 @cindex Pointer creation with @code{makeinfo} | |
| 5193 @cindex Automatic pointer creation with @code{makeinfo} | |
| 5194 | |
| 5195 The @code{makeinfo} program has a feature for automatically | |
| 5196 determining node pointers for a hierarchically organized document. We | |
| 5197 highly recommend using it. | |
| 5198 | |
| 5199 When you take advantage of this feature, you do not need to write the | |
| 5200 `Next', `Previous', and `Up' pointers after the name of a node. | |
| 5201 However, you must write a sectioning command, such as @code{@@chapter} | |
| 5202 or @code{@@section}, on the line immediately following each truncated | |
| 5203 @code{@@node} line (except that comment lines may intervene). | |
| 5204 | |
| 5205 In addition, you must follow the `Top' @code{@@node} line with a line | |
| 5206 beginning with @code{@@top} to mark the `Top' node in the | |
| 5207 file. @xref{makeinfo top, , @code{@@top}}. | |
| 5208 | |
| 5209 Finally, you must write the name of each node (except for the `Top' | |
| 5210 node) in a menu that is one or more hierarchical levels above the | |
| 5211 node's hierarchical level. | |
| 5212 | |
| 5213 @cindex Detail menu | |
| 5214 @findex detailmenu | |
| 5215 If you use a detailed menu in your master menu (@pxref{Master Menu | |
| 5216 Parts}), mark it with the @code{@@detailmenu @@dots@{@} @@end | |
| 5217 detailmenu} environment, or @command{makeinfo} will get confused, | |
| 5218 typically about the last and/or first node in the document. | |
| 5219 | |
| 5220 This implicit node pointer creation feature in @code{makeinfo} | |
| 5221 relieves you from the need to update menus and pointers manually or | |
| 5222 with Texinfo mode commands. (@xref{Updating Nodes and Menus}.) | |
| 5223 | |
| 5224 In most cases, you will want to take advantage of this feature and not | |
| 5225 redundantly specify node pointers. However, Texinfo documents are not | |
| 5226 required to be organized hierarchically or in fact to contain | |
| 5227 sectioning commands at all (for example, if you never intend the | |
| 5228 document to be printed). The special procedure for handling the short | |
| 5229 text before a menu (@pxref{Menus}) also disables this | |
| 5230 feature, for that group of nodes. In those cases, you will need to | |
| 5231 explicitly specify all pointers. | |
| 5232 | |
| 5233 @node anchor | |
| 5234 @section @code{@@anchor}: Defining Arbitrary Cross-reference Targets | |
| 5235 | |
| 5236 @findex anchor | |
| 5237 @cindex Anchors | |
| 5238 @cindex Cross-reference targets, arbitrary | |
| 5239 @cindex Targets for cross-references, arbitrary | |
| 5240 | |
| 5241 An @dfn{anchor} is a position in your document, labeled so that | |
| 5242 cross-references can refer to it, just as they can to nodes. You create | |
| 5243 an anchor with the @code{@@anchor} command, and give the label as a | |
| 5244 normal brace-delimited argument. For example: | |
| 5245 | |
| 5246 @example | |
| 5247 This marks the @@anchor@{x-spot@}spot. | |
| 5248 @dots{} | |
| 5249 @@xref@{x-spot,,the spot@}. | |
| 5250 @end example | |
| 5251 | |
| 5252 @noindent produces: | |
| 5253 | |
| 5254 @example | |
| 5255 This marks the spot. | |
| 5256 @dots{} | |
| 5257 See [the spot], page 1. | |
| 5258 @end example | |
| 5259 | |
| 5260 As you can see, the @code{@@anchor} command itself produces no output. | |
| 5261 This example defines an anchor `x-spot' just before the word `spot'. | |
| 5262 You can refer to it later with an @code{@@xref} or other cross-reference | |
| 5263 command, as shown. @xref{Cross References}, for details on the | |
| 5264 cross-reference commands. | |
| 5265 | |
| 5266 It is best to put @code{@@anchor} commands just before the position you | |
| 5267 wish to refer to; that way, the reader's eye is led on to the correct | |
| 5268 text when they jump to the anchor. You can put the @code{@@anchor} | |
| 5269 command on a line by itself if that helps readability of the source. | |
| 5270 Whitespace (including newlines) is ignored after @code{@@anchor}. | |
| 5271 | |
| 5272 Anchor names and node names may not conflict. Anchors and nodes are | |
| 5273 given similar treatment in some ways; for example, the @code{goto-node} | |
| 5274 command in standalone Info takes either an anchor name or a node name as | |
| 5275 an argument. (@xref{goto-node,,,info-stnd,GNU Info}.) | |
| 5276 | |
| 5277 Also like node names, anchor names cannot include some characters | |
| 5278 (@pxref{Node Line Requirements}). | |
| 5279 | 5568 |
| 5280 | 5569 |
| 5281 @node Menus | 5570 @node Menus |
| 5282 @chapter Menus | 5571 @chapter Menus |
| 5283 @cindex Menus | 5572 @cindex Menus |
| 5285 | 5574 |
| 5286 @dfn{Menus} contain pointers to subordinate nodes. In online output, | 5575 @dfn{Menus} contain pointers to subordinate nodes. In online output, |
| 5287 you use menus to go to such nodes. Menus have no effect in printed | 5576 you use menus to go to such nodes. Menus have no effect in printed |
| 5288 manuals and do not appear in them. | 5577 manuals and do not appear in them. |
| 5289 | 5578 |
| 5290 A node with a menu should not contain much text. If you find yourself | 5579 It's usually best if a node with a menu does not contain much text. |
| 5291 writing a lot of text before a menu, we generally recommend moving | 5580 If you find yourself with a lot of text before a menu, we generally |
| 5292 most of the text into a new subnode---all but a paragraph or two. | 5581 recommend moving all but a couple of paragraphs into a new subnode. |
| 5293 Otherwise, a reader with a terminal that displays only a few lines may | 5582 Otherwise, it is easy for readers to miss the menu. |
| 5294 miss the menu and its associated text. As a practical matter, it is | |
| 5295 best to locate a menu within 20 or so lines of the beginning of the | |
| 5296 node. | |
| 5297 | 5583 |
| 5298 @menu | 5584 @menu |
| 5299 * Menu Location:: Menus go at the ends of short nodes. | 5585 * Menu Location:: Menus go at the ends of nodes. |
| 5300 * Writing a Menu:: What is a menu? | 5586 * Writing a Menu:: What is a menu? |
| 5301 * Menu Parts:: A menu entry has three parts. | 5587 * Menu Parts:: A menu entry has three parts. |
| 5302 * Less Cluttered Menu Entry:: Two part menu entry. | 5588 * Less Cluttered Menu Entry:: Two part menu entry. |
| 5303 * Menu Example:: Two and three part menu entries. | 5589 * Menu Example:: Two and three part menu entries. |
| 5304 * Other Info Files:: How to refer to a different Info file. | 5590 * Other Info Files:: How to refer to a different Info file. |
| 5308 @node Menu Location | 5594 @node Menu Location |
| 5309 @section Menu Location | 5595 @section Menu Location |
| 5310 @cindex Menu location | 5596 @cindex Menu location |
| 5311 @cindex Location of menus | 5597 @cindex Location of menus |
| 5312 | 5598 |
| 5313 A menu must be located at the end of a node, without any regular text | 5599 There may be at most one menu in a node. A menu is conventionally |
| 5314 or additional commands between the @code{@@end menu} and the beginning | 5600 located at the end of a node, without any regular text or additional |
| 5315 of the next node. (As a consequence, there may be at most one menu in | 5601 commands between the @code{@@end menu} and the beginning of the next |
| 5316 a node.) | 5602 node. |
| 5317 | 5603 |
| 5318 @cindex Info format, and menus | 5604 @cindex Info format, and menus |
| 5319 This is actually a useful restriction, since a reader who uses the | 5605 This convention is useful, since a reader who uses the menu could |
| 5320 menu could easily miss any such text. Technically, it is necessary | 5606 easily miss any such text. Also, any such post-menu text will be |
| 5321 because in Info format, there is no marker for the end of a menu, so | 5607 considered part of the menu in Info output (which has no marker for |
| 5322 Info-reading programs would have no way to know when the menu ends and | 5608 the end of a menu). Thus, a line beginning with @samp{* } will likely |
| 5323 normal text resumes. | 5609 be incorrectly handled. |
| 5324 | 5610 |
| 5325 @cindex Hierarchical documents, and menus | 5611 @cindex Hierarchical documents, and menus |
| 5326 Technically, menus can carry you to any node, regardless of the | 5612 Technically, menus can carry you to any node, regardless of the |
| 5327 structure of the document; even to nodes in a different Info file. | 5613 structure of the document; even to nodes in a different Info file. |
| 5328 However, we do not recommend ever making use of this, because the | 5614 However, we do not recommend making use of this, because it is hard |
| 5329 @command{makeinfo} implicit pointer creation feature (@pxref{makeinfo | 5615 for readers to follow. Also, the @command{makeinfo} implicit pointer |
| 5330 Pointer Creation}) and XEmacs Texinfo mode updating commands work | 5616 creation feature (@pxref{@t{makeinfo} Pointer Creation}) and |
| 5331 only to create menus of subordinate nodes in a hierarchically | 5617 XEmacs Texinfo mode updating commands work only to create menus of |
| 5332 structured document. Instead, use cross references to refer to | 5618 subordinate nodes in a hierarchically structured document. It is much |
| 5333 arbitrary nodes. | 5619 better to use cross references to refer to arbitrary nodes. |
| 5334 | 5620 |
| 5335 In the past, we recommended using a @samp{@@heading} command within an | 5621 Years ago, we recommended using an @samp{@@heading} command within an |
| 5336 @code{@@ifinfo} conditional instead of the normal sectioning commands | 5622 @code{@@ifinfo} conditional instead of the normal sectioning commands |
| 5337 after a very short node with a menu. This had the advantage of making | 5623 after a very short node with a menu. This had the advantage of making |
| 5338 the printed output look better, because there was no very short text | 5624 the printed output look better, because there was no very short text |
| 5339 between two headings on the page. But this also does not work with | 5625 between two headings on the page. But it does not work with |
| 5340 @command{makeinfo}'s implicit pointer creation, and it also makes the | 5626 @command{makeinfo}'s implicit pointer creation, and it also makes the |
| 5341 XML output incorrect, since it does not reflect the true document | 5627 XML output incorrect, since it does not reflect the true document |
| 5342 structure. So, regrettably, we can no longer recommend this. | 5628 structure. So, we no longer recommend this. |
| 5343 | 5629 |
| 5344 | 5630 |
| 5345 @node Writing a Menu | 5631 @node Writing a Menu |
| 5346 @section Writing a Menu | 5632 @section Writing a Menu |
| 5347 @cindex Writing a menu | 5633 @cindex Writing a menu |
| 5363 several files at once. | 5649 several files at once. |
| 5364 @@end menu | 5650 @@end menu |
| 5365 @end group | 5651 @end group |
| 5366 @end example | 5652 @end example |
| 5367 | 5653 |
| 5654 @cindex Spaces, in menus | |
| 5368 In a menu, every line that begins with an @w{@samp{* }} is a @dfn{menu | 5655 In a menu, every line that begins with an @w{@samp{* }} is a @dfn{menu |
| 5369 entry}. (Note the space after the asterisk.) A line that does not | 5656 entry}. (Note the space after the asterisk.) A line that does not |
| 5370 start with an @w{@samp{* }} may also appear in a menu. Such a line is | 5657 start with an @w{@samp{* }} may also appear in a menu. Such a line is |
| 5371 not a menu entry but is a menu comment line that appears in the Info | 5658 not a menu entry but rather a @dfn{menu comment} line that appears in |
| 5372 file. In the example above, the line @samp{Larger Units of Text} is a | 5659 the Info file. In the example above, the line @samp{Larger Units of |
| 5373 menu comment line; the two lines starting with @w{@samp{* }} are menu | 5660 Text} is such a menu comment line; the two lines starting with |
| 5374 @cindex Spaces, in menus | 5661 @w{@samp{* }} are menu entries. Space characters in a menu are |
| 5375 entries. Space characters in a menu are preserved as-is; this allows | 5662 preserved as-is in the Info output; this allows you to format the menu |
| 5376 you to format the menu as you wish. | 5663 as you wish. |
| 5377 | 5664 |
| 5378 @opindex accesskey@r{, in HTML output} | 5665 @opindex accesskey@r{, in HTML output of menus} |
| 5379 In the HTML output from @command{makeinfo}, the @code{accesskey} | 5666 In the HTML output from @command{makeinfo}, the @code{accesskey} |
| 5380 attribute is used with the values @samp{1}@dots{}@samp{9} for the | 5667 attribute is used with the values @samp{1}@dots{}@samp{9} for the |
| 5381 first nine entries. This allows people using web browsers to follow | 5668 first nine entries. This allows people using web browsers to follow |
| 5382 the first menu entries using (typically) @kbd{M-@var{digit}}, e.g., | 5669 the first menu entries using (typically) @kbd{M-@var{digit}}, e.g., |
| 5383 @kbd{M-1} for the first entry. | 5670 @kbd{M-1} for the first entry. |
| 5407 | 5694 |
| 5408 @example | 5695 @example |
| 5409 * @var{menu-entry-name}: @var{node-name}. @var{description} | 5696 * @var{menu-entry-name}: @var{node-name}. @var{description} |
| 5410 @end example | 5697 @end example |
| 5411 | 5698 |
| 5412 Follow the menu entry name with a single colon and follow the node name | 5699 Follow the menu entry name with a single colon and follow the node |
| 5413 with tab, comma, newline, or the two characters period and space | 5700 name with tab, comma, newline, or the two characters period and space |
| 5414 (@samp{. }). | 5701 (@samp{. }). |
| 5702 | |
| 5703 @command{makeinfo} warns when the text of a menu item (and node names | |
| 5704 and cross references) contains a problematic construct that will | |
| 5705 interfere with its parsing in Info. If you don't want to see the | |
| 5706 warnings, you can set the customization variable | |
| 5707 @code{INFO_SPECIAL_CHARS_WARNING} to @samp{0} (@pxref{Other | |
| 5708 Customization Variables}). | |
| 5415 | 5709 |
| 5416 In Info, a user selects a node with the @kbd{m} (@code{Info-menu}) | 5710 In Info, a user selects a node with the @kbd{m} (@code{Info-menu}) |
| 5417 command. The menu entry name is what the user types after the @kbd{m} | 5711 command. The menu entry name is what the user types after the @kbd{m} |
| 5418 command. | 5712 command. |
| 5419 | 5713 |
| 5420 The third part of a menu entry is a descriptive phrase or sentence. | 5714 The third part of a menu entry is a descriptive phrase or sentence. |
| 5421 Menu entry names and node names are often short; the description | 5715 Menu entry names and node names are often short; the description |
| 5422 explains to the reader what the node is about. A useful description | 5716 explains to the reader what the node is about. A useful description |
| 5423 complements the node name rather than repeats it. The description, | 5717 complements the node name rather than repeats it. The description, |
| 5424 which is optional, can spread over two or more lines; if it does, some | 5718 which is optional, can spread over multiple lines; if it does, some |
| 5425 authors prefer to indent the second line while others prefer to align it | 5719 authors prefer to indent the second line while others prefer to align |
| 5426 with the first (and all others). It's up to you. | 5720 it with the first (and all others). It's up to you. An empty line, |
| 5721 or the next menu entry, ends a description. | |
| 5427 | 5722 |
| 5428 | 5723 |
| 5429 @node Less Cluttered Menu Entry | 5724 @node Less Cluttered Menu Entry |
| 5430 @section Less Cluttered Menu Entry | 5725 @section Less Cluttered Menu Entry |
| 5431 @cindex Two part menu entry | 5726 @cindex Two part menu entry |
| 5451 | 5746 |
| 5452 @example | 5747 @example |
| 5453 * Name: Name. @var{description} | 5748 * Name: Name. @var{description} |
| 5454 @end example | 5749 @end example |
| 5455 | 5750 |
| 5456 You should indeed use the node name for the menu entry name whenever | 5751 We recommend using the node name for the menu entry name whenever |
| 5457 possible, since it reduces visual clutter in the menu. | 5752 possible, since it reduces visual clutter in the menu. |
| 5458 | 5753 |
| 5459 | 5754 |
| 5460 @node Menu Example | 5755 @node Menu Example |
| 5461 @section A Menu Example | 5756 @section A Menu Example |
| 5462 @cindex Menu example | 5757 @cindex Menu example |
| 5463 @cindex Example menu | 5758 @cindex Example menu |
| 5464 | 5759 |
| 5465 A menu looks like this in Texinfo:@refill | 5760 A menu looks like this in Texinfo: |
| 5466 | 5761 |
| 5467 @example | 5762 @example |
| 5468 @group | 5763 @group |
| 5469 @@menu | 5764 @@menu |
| 5470 * menu entry name: Node name. A short description. | 5765 * menu entry name: Node name. A short description. |
| 5485 * Node name:: This form is preferred. | 5780 * Node name:: This form is preferred. |
| 5486 @end group | 5781 @end group |
| 5487 @end example | 5782 @end example |
| 5488 | 5783 |
| 5489 @need 700 | 5784 @need 700 |
| 5490 Here is an example as you might see it in a Texinfo file:@refill | 5785 Here is an example as you might see it in a Texinfo file: |
| 5491 | 5786 |
| 5492 @example | 5787 @example |
| 5493 @group | 5788 @group |
| 5494 @@menu | 5789 @@menu |
| 5495 Larger Units of Text | 5790 Larger Units of Text |
| 5518 | 5813 |
| 5519 In this example, the menu has two entries. @samp{Files} is both a menu | 5814 In this example, the menu has two entries. @samp{Files} is both a menu |
| 5520 entry name and the name of the node referred to by that name. | 5815 entry name and the name of the node referred to by that name. |
| 5521 @samp{Multiples} is the menu entry name; it refers to the node named | 5816 @samp{Multiples} is the menu entry name; it refers to the node named |
| 5522 @samp{Buffers}. The line @samp{Larger Units of Text} is a comment; it | 5817 @samp{Buffers}. The line @samp{Larger Units of Text} is a comment; it |
| 5523 appears in the menu, but is not an entry.@refill | 5818 appears in the menu, but is not an entry. |
| 5524 | 5819 |
| 5525 Since no file name is specified with either @samp{Files} or | 5820 Since no file name is specified with either @samp{Files} or |
| 5526 @samp{Buffers}, they must be the names of nodes in the same Info file | 5821 @samp{Buffers}, they must be the names of nodes in the same Info file |
| 5527 (@pxref{Other Info Files, , Referring to Other Info Files}).@refill | 5822 (@pxref{Other Info Files, , Referring to Other Info Files}). |
| 5528 | 5823 |
| 5529 @node Other Info Files | 5824 @node Other Info Files |
| 5530 @comment node-name, next, previous, up | |
| 5531 @section Referring to Other Info Files | 5825 @section Referring to Other Info Files |
| 5532 @cindex Referring to other Info files | 5826 @cindex Referring to other Info files |
| 5533 @cindex Nodes in other Info files | 5827 @cindex Nodes in other Info files |
| 5534 @cindex Other Info files' nodes | 5828 @cindex Other Info files' nodes |
| 5535 @cindex Going to other Info files' nodes | 5829 @cindex Going to other Info files' nodes |
| 5536 @cindex Info; other files' nodes | 5830 @cindex Info; other files' nodes |
| 5537 | 5831 |
| 5538 You can create a menu entry that enables a reader in Info to go to a | 5832 You can create a menu entry that enables a reader in Info to go to a |
| 5539 node in another Info file by writing the file name in parentheses just | 5833 node in another Info file by writing the file name in parentheses just |
| 5540 before the node name. In this case, you should use the three-part menu | 5834 before the node name. Some examples: |
| 5541 entry format, which saves the reader from having to type the file | |
| 5542 name.@refill | |
| 5543 | |
| 5544 @need 800 | |
| 5545 The format looks like this:@refill | |
| 5546 | 5835 |
| 5547 @example | 5836 @example |
| 5548 @group | 5837 @group |
| 5549 @@menu | 5838 @@menu |
| 5550 * @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description} | 5839 * @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description} |
| 5551 * @var{second-entry-name}:(@var{filename})@var{second-node}. @var{description} | 5840 * (@var{filename})@var{second-node}:: @var{description} |
| 5552 @@end menu | 5841 @@end menu |
| 5553 @end group | 5842 @end group |
| 5554 @end example | 5843 @end example |
| 5555 | 5844 |
| 5556 For example, to refer directly to the @samp{Outlining} and | 5845 For example, to refer directly to the @samp{Outlining} and |
| 5557 @samp{Rebinding} nodes in the @cite{XEmacs User's Manual}, you would | 5846 @samp{Rebinding} nodes in the @cite{XEmacs User's Manual}, you could write a |
| 5558 write a menu like this:@refill | 5847 menu like this: |
| 5559 | 5848 |
| 5560 @example | 5849 @example |
| 5561 @group | 5850 @group |
| 5562 @@menu | 5851 @@menu |
| 5563 * Outlining: (xemacs)Outline Mode. The major mode for | 5852 * Outlining: (xemacs)Outline Mode. The major mode for |
| 5564 editing outlines. | 5853 editing outlines. |
| 5565 * Rebinding: (xemacs)Rebinding. How to redefine the | 5854 * (xemacs)Rebinding:: How to redefine the |
| 5566 meaning of a key. | 5855 meaning of a key. |
| 5567 @@end menu | 5856 @@end menu |
| 5568 @end group | 5857 @end group |
| 5569 @end example | 5858 @end example |
| 5570 | 5859 |
| 5571 If you do not list the node name, but only name the file, then Info | 5860 If you do not list the node name, but only name the file, then Info |
| 5572 presumes that you are referring to the `Top' node.@refill | 5861 presumes that you are referring to the `Top' node. Examples: |
| 5573 | |
| 5574 The @file{dir} file that contains the main menu for Info has menu | |
| 5575 entries that list only file names. These take you directly to the `Top' | |
| 5576 nodes of each Info document. (@xref{Installing an Info File}.) | |
| 5577 | |
| 5578 @need 700 | |
| 5579 For example: | |
| 5580 | 5862 |
| 5581 @example | 5863 @example |
| 5582 @group | 5864 @group |
| 5583 * Info: (info). Documentation browsing system. | 5865 * Info: (info). Documentation browsing system. |
| 5584 * XEmacs: (xemacs). The extensible, self-documenting | 5866 * (xemacs):: The extensible, self-documenting |
| 5585 text editor. | 5867 text editor. |
| 5586 @end group | 5868 @end group |
| 5587 @end example | 5869 @end example |
| 5588 | |
| 5589 @noindent | |
| 5590 (The @file{dir} top level directory for the Info system is an Info file, | |
| 5591 not a Texinfo file, but a menu entry looks the same in both types of | |
| 5592 file.)@refill | |
| 5593 | 5870 |
| 5594 The XEmacs Texinfo mode menu updating commands only work with nodes | 5871 The XEmacs Texinfo mode menu updating commands only work with nodes |
| 5595 within the current buffer, so you cannot use them to create menus that | 5872 within the current buffer, so you cannot use them to create menus that |
| 5596 refer to other files. You must write such menus by hand. | 5873 refer to other files. You must write such menus by hand. |
| 5597 | 5874 |
| 5608 | 5885 |
| 5609 @menu | 5886 @menu |
| 5610 * References:: What cross references are for. | 5887 * References:: What cross references are for. |
| 5611 * Cross Reference Commands:: A summary of the different commands. | 5888 * Cross Reference Commands:: A summary of the different commands. |
| 5612 * Cross Reference Parts:: A cross reference has several parts. | 5889 * Cross Reference Parts:: A cross reference has several parts. |
| 5613 * xref:: Begin a reference with `See' @dots{} | 5890 * @t{@@xref}:: Begin a reference with `See' @dots{} |
| 5614 * Top Node Naming:: How to refer to the beginning of another file. | 5891 * Top Node Naming:: How to refer to the beginning of another file. |
| 5615 * ref:: A reference for the last part of a sentence. | 5892 * @t{@@ref}:: A reference for the last part of a sentence. |
| 5616 * pxref:: How to write a parenthetical cross reference. | 5893 * @t{@@pxref}:: How to write a parenthetical cross reference. |
| 5617 * inforef:: How to refer to an Info-only file. | 5894 * @t{@@inforef}:: How to refer to an Info-only file. |
| 5618 * uref:: How to refer to a uniform resource locator. | 5895 * @t{@@url}:: How to refer to a uniform resource locator. |
| 5619 * cite:: How to refer to books not in the Info system. | 5896 * @t{@@cite}:: How to refer to books not in the Info system. |
| 5620 @end menu | 5897 @end menu |
| 5898 | |
| 5621 | 5899 |
| 5622 @node References | 5900 @node References |
| 5623 @section What References Are For | 5901 @section What References Are For |
| 5624 | 5902 |
| 5625 Often, but not always, a printed document should be designed so that | 5903 Often, but not always, a printed document should be designed so that |
| 5626 it can be read sequentially. People tire of flipping back and forth | 5904 it can be read sequentially. People tire of flipping back and forth |
| 5627 to find information that should be presented to them as they need | 5905 to find information that should be presented to them as they need |
| 5628 it.@refill | 5906 it. |
| 5629 | 5907 |
| 5630 However, in any document, some information will be too detailed for | 5908 However, in any document, some information will be too detailed for |
| 5631 the current context, or incidental to it; use cross references to | 5909 the current context, or incidental to it; use cross references to |
| 5632 provide access to such information. Also, an online help system or a | 5910 provide access to such information. Also, an online help system or a |
| 5633 reference manual is not like a novel; few read such documents in | 5911 reference manual is not like a novel; few read such documents in |
| 5634 sequence from beginning to end. Instead, people look up what they | 5912 sequence from beginning to end. Instead, people look up what they |
| 5635 need. For this reason, such creations should contain many cross | 5913 need. For this reason, such creations should contain many cross |
| 5636 references to help readers find other information that they may not | 5914 references to help readers find other information that they may not |
| 5637 have read.@refill | 5915 have read. |
| 5638 | 5916 |
| 5639 In a printed manual, a cross reference results in a page reference, | 5917 In a printed manual, a cross reference results in a page reference, |
| 5640 unless it is to another manual altogether, in which case the cross | 5918 unless it is to another manual altogether, in which case the cross |
| 5641 reference names that manual.@refill | 5919 reference names that manual. |
| 5642 | 5920 |
| 5643 In Info, a cross reference results in an entry that you can follow | 5921 In Info, a cross reference results in an entry that you can follow |
| 5644 using the Info @samp{f} command. (@inforef{Help-Xref, Following | 5922 using the Info @samp{f} command. (@xref{Help-Xref,, Following |
| 5645 cross-references, info}.) | 5923 cross-references, info, Info}.) |
| 5924 | |
| 5925 In HTML, a cross reference results in an hyperlink. | |
| 5646 | 5926 |
| 5647 The various cross reference commands use nodes (or anchors, | 5927 The various cross reference commands use nodes (or anchors, |
| 5648 @pxref{anchor,,@code{@@anchor}}) to define cross reference locations. | 5928 @pxref{@t{@@anchor}}) to define cross reference locations. This is |
| 5649 This is evident in Info, in which a cross reference takes you to the | 5929 evident in Info and HTML, in which a cross reference takes you to the |
| 5650 specified location. @TeX{} also uses nodes to define cross reference | 5930 specified location. |
| 5651 locations, but the action is less obvious. When @TeX{} generates a DVI | 5931 |
| 5652 file, it records each node's page number and uses the page numbers in making | 5932 @TeX{} also needs nodes to define cross reference locations, but the |
| 5653 references. Thus, if you are writing a manual that will only be | 5933 action is less obvious. When @TeX{} generates a DVI file, it records |
| 5654 printed, and will not be used online, you must nonetheless write | 5934 each node's page number and uses the page numbers in making |
| 5655 @code{@@node} lines to name the places to which you make cross | 5935 references. Thus, even if you are writing a manual that will only be |
| 5656 references.@refill | 5936 printed, and not used online, you must nonetheless write @code{@@node} |
| 5937 lines in order to name the places to which you make cross references. | |
| 5657 | 5938 |
| 5658 @need 800 | 5939 @need 800 |
| 5659 @node Cross Reference Commands | 5940 @node Cross Reference Commands |
| 5660 @comment node-name, next, previous, up | |
| 5661 @section Different Cross Reference Commands | 5941 @section Different Cross Reference Commands |
| 5662 @cindex Different cross reference commands | 5942 @cindex Different cross reference commands |
| 5663 | 5943 |
| 5664 There are four different cross reference commands:@refill | 5944 There are four different cross reference commands: |
| 5665 | 5945 |
| 5666 @table @code | 5946 @table @code |
| 5667 @item @@xref | 5947 @item @@xref |
| 5668 Used to start a sentence in the printed manual saying @w{`See @dots{}'} | 5948 Used to start a sentence in the printed manual and in HTML with |
| 5669 or an Info cross-reference saying @samp{*Note @var{name}: @var{node}.}. | 5949 @w{`See @dots{}'} or an Info cross reference saying @samp{*Note |
| 5950 @var{name}: @var{node}.}. | |
| 5670 | 5951 |
| 5671 @item @@ref | 5952 @item @@ref |
| 5672 Used within or, more often, at the end of a sentence; same as | 5953 Used within or, more often, at the end of a sentence; produces just |
| 5673 @code{@@xref} for Info; produces just the reference in the printed | 5954 the reference in the printed manual and in HTML without the preceding |
| 5674 manual without a preceding `See'.@refill | 5955 `See' (same as @code{@@xref} for Info). |
| 5675 | 5956 |
| 5676 @item @@pxref | 5957 @item @@pxref |
| 5677 Used within parentheses to make a reference that suits both an Info | 5958 Used within parentheses, at the end of a sentence, or otherwise before |
| 5678 file and a printed book. Starts with a lower case `see' within the | 5959 punctuation, to make a reference. Its output starts with a lowercase |
| 5679 printed manual. (@samp{p} is for `parenthesis'.)@refill | 5960 `see' in the printed manual and in HTML, and a lowercase @samp{*note} |
| 5961 in Info. (@samp{p} is for `parenthesis'.) | |
| 5680 | 5962 |
| 5681 @item @@inforef | 5963 @item @@inforef |
| 5682 Used to make a reference to an Info file for which there is no printed | 5964 Used to make a reference to an Info file for which there is no printed |
| 5683 manual.@refill | 5965 manual. |
| 5684 @end table | 5966 @end table |
| 5685 | 5967 |
| 5686 @noindent | 5968 @noindent |
| 5687 (The @code{@@cite} command is used to make references to books and | 5969 The @code{@@cite} command is used to make references to books and |
| 5688 manuals for which there is no corresponding Info file and, therefore, | 5970 manuals for which there is no corresponding Info file and, therefore, |
| 5689 no node to which to point. @xref{cite, , @code{@@cite}}.)@refill | 5971 no node to which to point. @xref{@t{@@cite}}. |
| 5972 | |
| 5690 | 5973 |
| 5691 @node Cross Reference Parts | 5974 @node Cross Reference Parts |
| 5692 @comment node-name, next, previous, up | |
| 5693 @section Parts of a Cross Reference | 5975 @section Parts of a Cross Reference |
| 5694 @cindex Cross reference parts | 5976 @cindex Cross reference parts |
| 5695 @cindex Parts of a cross reference | 5977 @cindex Parts of a cross reference |
| 5696 | 5978 |
| 5697 A cross reference command requires only one argument, which is the | 5979 A cross reference command to a node requires only one argument, which |
| 5698 name of the node to which it refers. But a cross reference command | 5980 is the name of the node to which it refers. But a cross reference |
| 5699 may contain up to four additional arguments. By using these | 5981 command may contain up to four additional arguments. By using these |
| 5700 arguments, you can provide a cross reference name for Info, a topic | 5982 arguments, you can provide a cross reference name, a topic description |
| 5701 description or section title for the printed output, the name of a | 5983 or section title for the printed output, the name of a different |
| 5702 different Info file, and the name of a different printed | 5984 manual file, and the name of a different printed manual. To refer |
| 5703 manual.@refill | 5985 to another manual as a whole, the manual file and/or the name of the |
| 5704 | 5986 printed manual are the only required arguments (@pxref{Top Node |
| 5705 Here is a simple cross reference example:@refill | 5987 Naming}). |
| 5988 | |
| 5989 Here is a simple cross reference example: | |
| 5706 | 5990 |
| 5707 @example | 5991 @example |
| 5708 @@xref@{Node name@}. | 5992 @@xref@{Node name@}. |
| 5709 @end example | 5993 @end example |
| 5710 | 5994 |
| 5714 @example | 5998 @example |
| 5715 *Note Node name::. | 5999 *Note Node name::. |
| 5716 @end example | 6000 @end example |
| 5717 | 6001 |
| 5718 @noindent | 6002 @noindent |
| 5719 and | 6003 in Info and |
| 5720 | 6004 |
| 5721 @quotation | 6005 @quotation |
| 5722 See Section @var{nnn} [Node name], page @var{ppp}. | 6006 See Section @var{nnn} [Node name], page @var{ppp}. |
| 5723 @end quotation | 6007 @end quotation |
| 5724 | 6008 |
| 6009 @noindent | |
| 6010 in a printed manual. | |
| 6011 | |
| 5725 @need 700 | 6012 @need 700 |
| 5726 Here is an example of a full five-part cross reference:@refill | 6013 Here is an example of a full five-part cross reference: |
| 5727 | 6014 |
| 5728 @example | 6015 @example |
| 5729 @group | 6016 @group |
| 5730 @@xref@{Node name, Cross Reference Name, Particular Topic, | 6017 @@xref@{Node name, Cross Reference Name, Particular Topic, |
| 5731 info-file-name, A Printed Manual@}, for details. | 6018 info-file-name, A Printed Manual@}, for details. |
| 5748 @end quotation | 6035 @end quotation |
| 5749 | 6036 |
| 5750 @noindent | 6037 @noindent |
| 5751 in a printed book. | 6038 in a printed book. |
| 5752 | 6039 |
| 5753 The five possible arguments for a cross reference are:@refill | 6040 The five possible arguments for a cross reference are: |
| 5754 | 6041 |
| 5755 @enumerate | 6042 @enumerate |
| 5756 @item | 6043 @item |
| 5757 The node or anchor name (required). This is the location to which the | 6044 The node or anchor name (required, except for reference to whole |
| 5758 cross reference takes you. In a printed document, the location of the | 6045 manuals). This is the location to which the cross reference takes |
| 5759 node provides the page reference only for references within the same | 6046 you. In a printed document, the location of the node provides the |
| 5760 document.@refill | 6047 page reference only for references within the same document. |
| 5761 | 6048 |
| 5762 @item | 6049 @item |
| 5763 The cross reference name for the Info reference, if it is to be | 6050 The cross reference name. If you include this argument, it becomes |
| 5764 different from the node name or the topic description. If you | 6051 the first part of the cross reference. It is usually omitted; then |
| 5765 include this argument, it becomes the first part of the cross reference. | 6052 the topic description (third argument) is used if it was specified; |
| 5766 It is usually omitted; then the topic description (third argument) is | 6053 if that was omitted as well, the node name is used. |
| 5767 used if it was specified; if that was omitted as well, the node name | |
| 5768 is used. | |
| 5769 | 6054 |
| 5770 @item | 6055 @item |
| 5771 A topic description or section name. Often, this is the title of the | 6056 A topic description or section name. Often, this is the title of the |
| 5772 section. This is used as the name of the reference in the printed | 6057 section. This is used as the name of the reference in the printed |
| 5773 manual. If omitted, the node name is used.@refill | 6058 manual. If omitted, the node name is used. |
| 5774 | 6059 |
| 5775 @item | 6060 @item |
| 5776 The name of the Info file in which the reference is located, if it is | 6061 The name of the manual file in which the reference is located, if it is |
| 5777 different from the current file. You need not include any @samp{.info} | 6062 different from the current file. This name is used both for Info and |
| 5778 suffix on the file name, since Info readers try appending it | 6063 HTML. |
| 5779 automatically. | |
| 5780 | 6064 |
| 5781 @item | 6065 @item |
| 5782 The name of a printed manual from a different Texinfo file.@refill | 6066 The name of a printed manual from a different Texinfo file. |
| 5783 @end enumerate | 6067 @end enumerate |
| 5784 | 6068 |
| 5785 The template for a full five argument cross reference looks like | 6069 The template for a full five argument cross reference looks like |
| 5786 this:@refill | 6070 this: |
| 5787 | 6071 |
| 5788 @example | 6072 @example |
| 5789 @group | 6073 @group |
| 5790 @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}, | 6074 @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}, |
| 5791 @var{info-file-name}, @var{printed-manual-title}@}. | 6075 @var{info-file-name}, @var{printed-manual-title}@}. |
| 5792 @end group | 6076 @end group |
| 5793 @end example | 6077 @end example |
| 5794 | 6078 |
| 5795 Cross references with one, two, three, four, and five arguments are | 6079 Cross references with one, two, three, four, and five arguments are |
| 5796 described separately following the description of @code{@@xref}.@refill | 6080 described separately following the description of @code{@@xref}. |
| 5797 | 6081 |
| 5798 Write a node name in a cross reference in exactly the same way as in | 6082 Write a node name in a cross reference in exactly the same way as in |
| 5799 the @code{@@node} line, including the same capitalization; otherwise, the | 6083 the @code{@@node} line, including the same capitalization; otherwise, the |
| 5800 formatters may not find the reference.@refill | 6084 formatters may not find the reference. |
| 5801 | 6085 |
| 5802 You can write cross reference commands within a paragraph, but note | 6086 @command{makeinfo} warns when the text of a cross reference (and node |
| 5803 how Info and @TeX{} format the output of each of the various commands: | 6087 names and menu items) contains a problematic construct that will |
| 5804 write @code{@@xref} at the beginning of a sentence; write | 6088 interfere with its parsing in Info. If you don't want to see the |
| 5805 @code{@@pxref} only within parentheses, and so on.@refill | 6089 warnings, you can set the customization variable |
| 5806 | 6090 @code{INFO_SPECIAL_CHARS_WARNING} to @samp{0} (@pxref{Other |
| 5807 @node xref | 6091 Customization Variables}). |
| 5808 @comment node-name, next, previous, up | 6092 |
| 6093 | |
| 6094 @node @t{@@xref} | |
| 5809 @section @code{@@xref} | 6095 @section @code{@@xref} |
| 6096 | |
| 6097 @anchor{xref}@c old name | |
| 5810 @findex xref | 6098 @findex xref |
| 5811 @cindex Cross references using @code{@@xref} | 6099 @cindex Cross references using @code{@@xref} |
| 5812 @cindex References using @code{@@xref} | 6100 @cindex References using @code{@@xref} |
| 5813 | 6101 |
| 5814 The @code{@@xref} command generates a cross reference for the | 6102 The @code{@@xref} command generates a cross reference for the |
| 5815 beginning of a sentence. The Info formatting commands convert it into | 6103 beginning of a sentence. The Info formatting commands convert it into |
| 5816 an Info cross reference, which the Info @samp{f} command can use to | 6104 an Info cross reference, which the Info @samp{f} command can use to |
| 5817 bring you directly to another node. The @TeX{} typesetting commands | 6105 bring you directly to another node. The @TeX{} typesetting commands |
| 5818 convert it into a page reference, or a reference to another book or | 6106 convert it into a page reference, or a reference to another book or |
| 5819 manual.@refill | 6107 manual. In the HTML output format the cross reference is output |
| 6108 as a hyperlink. | |
| 5820 | 6109 |
| 5821 @menu | 6110 @menu |
| 5822 * Reference Syntax:: What a reference looks like and requires. | 6111 * Reference Syntax:: What a reference looks like and requires. |
| 5823 * One Argument:: @code{@@xref} with one argument. | 6112 * One Argument:: @code{@@xref} with one argument. |
| 5824 * Two Arguments:: @code{@@xref} with two arguments. | 6113 * Two Arguments:: @code{@@xref} with two arguments. |
| 5827 @end menu | 6116 @end menu |
| 5828 | 6117 |
| 5829 @node Reference Syntax | 6118 @node Reference Syntax |
| 5830 @subsection What a Reference Looks Like and Requires | 6119 @subsection What a Reference Looks Like and Requires |
| 5831 | 6120 |
| 5832 Most often, an Info cross reference looks like this:@refill | 6121 Most often, an Info cross reference looks like this: |
| 5833 | 6122 |
| 5834 @example | 6123 @example |
| 5835 *Note @var{node-name}::. | 6124 *Note @var{node-name}::. |
| 5836 @end example | 6125 @end example |
| 5837 | 6126 |
| 5855 @quotation | 6144 @quotation |
| 5856 See Section @var{section-number} [@var{title-or-topic}], page @var{page}. | 6145 See Section @var{section-number} [@var{title-or-topic}], page @var{page}. |
| 5857 @end quotation | 6146 @end quotation |
| 5858 | 6147 |
| 5859 The @code{@@xref} command does not generate a period or comma to end | 6148 The @code{@@xref} command does not generate a period or comma to end |
| 5860 the cross reference in either the Info file or the printed output. | 6149 the cross reference automatically. You must write that period or |
| 5861 You must write that period or comma yourself; otherwise, Info will not | 6150 comma yourself; otherwise, Info will not recognize the end of the |
| 5862 recognize the end of the reference. (The @code{@@pxref} command works | 6151 reference. (The @code{@@pxref} command works differently; |
| 5863 differently. @xref{pxref, , @code{@@pxref}}.)@refill | 6152 @pxref{@t{@@pxref}}.) |
| 5864 | 6153 |
| 5865 @quotation Caution | 6154 @quotation Caution |
| 5866 A period or comma @strong{must} follow the closing | 6155 A period or comma @emph{must} follow the closing brace of an |
| 5867 brace of an @code{@@xref}. It is required to terminate the cross | 6156 @code{@@xref}. It is required to terminate the cross reference. This |
| 5868 reference. This period or comma will appear in the output, both in | 6157 period or comma will appear in the output. |
| 5869 the Info file and in the printed manual.@refill | |
| 5870 @end quotation | 6158 @end quotation |
| 5871 | 6159 |
| 5872 @code{@@xref} must refer to an Info node by name. Use @code{@@node} | 6160 @code{@@xref} must refer to a node by name. Use @code{@@node} to |
| 5873 to define the node (@pxref{Writing a Node}).@refill | 6161 define the node (@pxref{Writing a Node}), or @code{@@anchor} |
| 5874 | 6162 (@pxref{@t{@@anchor}}). |
| 5875 @code{@@xref} is followed by several arguments inside braces, separated by | 6163 |
| 5876 commas. Whitespace before and after these commas is ignored.@refill | 6164 @code{@@xref} is followed by several arguments inside braces, |
| 5877 | 6165 separated by commas. Whitespace before and after these commas is |
| 5878 A cross reference requires only the name of a node; but it may contain | 6166 ignored. |
| 5879 up to four additional arguments. Each of these variations produces a | 6167 |
| 5880 cross reference that looks somewhat different.@refill | 6168 A cross reference to a node within the current file requires only the |
| 6169 name of a node; but it may contain up to four additional arguments. | |
| 6170 Each of these variations produces a cross reference that looks | |
| 6171 somewhat different. A cross reference to another manual as a whole | |
| 6172 only requires the fourth or fifth argument. | |
| 5881 | 6173 |
| 5882 @quotation Note | 6174 @quotation Note |
| 5883 Commas separate arguments in a cross reference; | 6175 Commas separate arguments in a cross reference, so you must not |
| 5884 avoid including them in the title or other part lest the formatters | 6176 include a comma in the title or any other part lest the formatters |
| 5885 mistake them for separators.@refill | 6177 mistake them for separators. @code{@@comma@{@}} may be used to |
| 6178 protect such commas (@pxref{Inserting a Comma}). | |
| 5886 @end quotation | 6179 @end quotation |
| 6180 | |
| 5887 | 6181 |
| 5888 @node One Argument | 6182 @node One Argument |
| 5889 @subsection @code{@@xref} with One Argument | 6183 @subsection @code{@@xref} with One Argument |
| 6184 @cindex One-argument form of cross references | |
| 5890 | 6185 |
| 5891 The simplest form of @code{@@xref} takes one argument, the name of | 6186 The simplest form of @code{@@xref} takes one argument, the name of |
| 5892 another node in the same Info file. The Info formatters produce | 6187 another node in the same Texinfo file. The Info formatters produce |
| 5893 output that the Info readers can use to jump to the reference; @TeX{} | 6188 output that the Info readers can use to jump to the reference; @TeX{} |
| 5894 produces output that specifies the page and section number for you.@refill | 6189 produces output that specifies the page and section number for you; |
| 6190 the HTML output is a normal hyperlink. | |
| 5895 | 6191 |
| 5896 @need 700 | 6192 @need 700 |
| 5897 @noindent | 6193 @noindent |
| 5898 For example, | 6194 For example, |
| 5899 | 6195 |
| 5907 @example | 6203 @example |
| 5908 *Note Tropical Storms::. | 6204 *Note Tropical Storms::. |
| 5909 @end example | 6205 @end example |
| 5910 | 6206 |
| 5911 @noindent | 6207 @noindent |
| 5912 and | 6208 in Info and |
| 5913 | 6209 |
| 5914 @quotation | 6210 @quotation |
| 5915 See Section 3.1 [Tropical Storms], page 24. | 6211 See Section 3.1 [Tropical Storms], page 24. |
| 5916 @end quotation | 6212 @end quotation |
| 5917 | 6213 |
| 5918 @noindent | 6214 @noindent |
| 5919 (Note that in the preceding example the closing brace is followed by a | 6215 in a printed manual. |
| 5920 period.)@refill | 6216 (Note that in the preceding example the closing brace to |
| 5921 | 6217 @code{@@xref}'s argument is followed by a period.) |
| 5922 You can write a clause after the cross reference, like this:@refill | 6218 |
| 6219 You can write a clause after the cross reference, like this: | |
| 5923 | 6220 |
| 5924 @example | 6221 @example |
| 5925 @@xref@{Tropical Storms@}, for more info. | 6222 @@xref@{Tropical Storms@}, for more info. |
| 5926 @end example | 6223 @end example |
| 5927 | 6224 |
| 5931 @example | 6228 @example |
| 5932 *Note Tropical Storms::, for more info. | 6229 *Note Tropical Storms::, for more info. |
| 5933 @end example | 6230 @end example |
| 5934 | 6231 |
| 5935 @noindent | 6232 @noindent |
| 5936 and | 6233 in Info and |
| 5937 | 6234 |
| 5938 @quotation | 6235 @quotation |
| 5939 See Section 3.1 [Tropical Storms], page 24, for more info. | 6236 See Section 3.1 [Tropical Storms], page 24, for more info. |
| 5940 @end quotation | 6237 @end quotation |
| 5941 | 6238 |
| 5942 @noindent | 6239 |
| 5943 (Note that in the preceding example the closing brace is followed by a | 6240 @noindent |
| 5944 comma, and then by the clause, which is followed by a period.)@refill | 6241 in a printed manual. Note that in the preceding example the closing |
| 6242 brace to @code{@@xref} is followed by a comma, then the additional | |
| 6243 text. It's a common mistake to follow an @code{@@xref} command with a | |
| 6244 space, but this is never correct. | |
| 6245 | |
| 5945 | 6246 |
| 5946 @node Two Arguments | 6247 @node Two Arguments |
| 5947 @subsection @code{@@xref} with Two Arguments | 6248 @subsection @code{@@xref} with Two Arguments |
| 5948 | 6249 @cindex Two-argument form of cross references |
| 5949 With two arguments, the second is used as the name of the Info cross | 6250 |
| 6251 With two arguments, the second is used as the name of the cross | |
| 5950 reference, while the first is still the name of the node to which the | 6252 reference, while the first is still the name of the node to which the |
| 5951 cross reference points.@refill | 6253 cross reference points. |
| 5952 | 6254 |
| 5953 @need 750 | 6255 @need 750 |
| 5954 @noindent | 6256 @noindent |
| 5955 The template is like this: | 6257 The template is like this: |
| 5956 | 6258 |
| 5972 @example | 6274 @example |
| 5973 *Note Lightning: Electrical Effects. | 6275 *Note Lightning: Electrical Effects. |
| 5974 @end example | 6276 @end example |
| 5975 | 6277 |
| 5976 @noindent | 6278 @noindent |
| 5977 and | 6279 in Info and |
| 5978 | 6280 |
| 5979 @quotation | 6281 @quotation |
| 5980 See Section 5.2 [Electrical Effects], page 57. | 6282 See Section 5.2 [Electrical Effects], page 57. |
| 5981 @end quotation | 6283 @end quotation |
| 5982 | 6284 |
| 5983 @noindent | 6285 @noindent |
| 6286 in a printed manual. | |
| 5984 (Note that in the preceding example the closing brace is followed by a | 6287 (Note that in the preceding example the closing brace is followed by a |
| 5985 period; and that the node name is printed, not the cross reference name.) | 6288 period; and that the node name is printed, not the cross reference name.) |
| 5986 | 6289 |
| 5987 You can write a clause after the cross reference, like this:@refill | 6290 You can write a clause after the cross reference, like this: |
| 5988 | 6291 |
| 5989 @example | 6292 @example |
| 5990 @@xref@{Electrical Effects, Lightning@}, for more info. | 6293 @@xref@{Electrical Effects, Lightning@}, for more info. |
| 5991 @end example | 6294 @end example |
| 5992 | 6295 |
| 5993 @noindent | 6296 @noindent |
| 5994 which produces | 6297 which produces |
| 6298 | |
| 5995 @example | 6299 @example |
| 5996 *Note Lightning: Electrical Effects, for more info. | 6300 *Note Lightning: Electrical Effects, for more info. |
| 5997 @end example | 6301 @end example |
| 5998 | 6302 |
| 5999 @noindent | 6303 @noindent |
| 6000 and | 6304 in Info and |
| 6001 | 6305 |
| 6002 @quotation | 6306 @quotation |
| 6003 See Section 5.2 [Electrical Effects], page 57, for more info. | 6307 See Section 5.2 [Electrical Effects], page 57, for more info. |
| 6004 @end quotation | 6308 @end quotation |
| 6005 | 6309 |
| 6006 @noindent | 6310 @noindent |
| 6007 (Note that in the preceding example the closing brace is followed by a | 6311 in a printed manual. (Note that in the preceding example the closing |
| 6008 comma, and then by the clause, which is followed by a period.)@refill | 6312 brace is followed by a comma, and then by the clause, which is |
| 6313 followed by a period.) | |
| 6314 | |
| 6315 The second argument to cross references must observe some of the | |
| 6316 restrictions for node names (@pxref{Node Line Requirements}). The | |
| 6317 most common issue is that colons cannot be used, since that interferes | |
| 6318 with the parsing of the Info file. | |
| 6319 | |
| 6009 | 6320 |
| 6010 @node Three Arguments | 6321 @node Three Arguments |
| 6011 @subsection @code{@@xref} with Three Arguments | 6322 @subsection @code{@@xref} with Three Arguments |
| 6323 @cindex Three-argument form of cross references | |
| 6012 | 6324 |
| 6013 A third argument replaces the node name in the @TeX{} output. The third | 6325 A third argument replaces the node name in the @TeX{} output. The third |
| 6014 argument should be the name of the section in the printed output, or | 6326 argument should be the name of the section in the printed output, or |
| 6015 else state the topic discussed by that section. Often, you will want to | 6327 else state the topic discussed by that section. Often, you will want to |
| 6016 use initial upper case letters so it will be easier to read when the | 6328 use initial uppercase letters so it will be easier to read when the |
| 6017 reference is printed. Use a third argument when the node name is | 6329 reference is printed. Use a third argument when the node name is |
| 6018 unsuitable because of syntax or meaning.@refill | 6330 unsuitable because of syntax or meaning. |
| 6019 | 6331 |
| 6020 Remember to avoid placing a comma within the title or topic section of | 6332 Remember to write a comma or period after the closing brace of an |
| 6021 a cross reference, or within any other section. The formatters divide | |
| 6022 cross references into arguments according to the commas; a comma | |
| 6023 within a title or other section will divide it into two arguments. In | |
| 6024 a reference, you need to write a title such as ``Clouds, Mist, and | |
| 6025 Fog'' without the commas.@refill | |
| 6026 | |
| 6027 Also, remember to write a comma or period after the closing brace of an | |
| 6028 @code{@@xref} to terminate the cross reference. In the following | 6333 @code{@@xref} to terminate the cross reference. In the following |
| 6029 examples, a clause follows a terminating comma.@refill | 6334 examples, a clause follows a terminating comma. |
| 6030 | |
| 6031 | 6335 |
| 6032 @need 750 | 6336 @need 750 |
| 6033 @noindent | 6337 @noindent |
| 6034 The template is like this: | 6338 The template is like this: |
| 6035 | 6339 |
| 6056 @example | 6360 @example |
| 6057 *Note Lightning: Electrical Effects, for details. | 6361 *Note Lightning: Electrical Effects, for details. |
| 6058 @end example | 6362 @end example |
| 6059 | 6363 |
| 6060 @noindent | 6364 @noindent |
| 6061 and | 6365 in Info and |
| 6062 | 6366 |
| 6063 @quotation | 6367 @quotation |
| 6064 See Section 5.2 [Thunder and Lightning], page 57, for details. | 6368 See Section 5.2 [Thunder and Lightning], page 57, for details. |
| 6065 @end quotation | 6369 @end quotation |
| 6066 | 6370 |
| 6371 @noindent | |
| 6372 in a printed manual. | |
| 6373 | |
| 6067 If a third argument is given and the second one is empty, then the | 6374 If a third argument is given and the second one is empty, then the |
| 6068 third argument serves both. (Note how two commas, side by side, mark | 6375 third argument serves for both. (Note how two commas, side by side, mark |
| 6069 the empty second argument.)@refill | 6376 the empty second argument.) |
| 6070 | 6377 |
| 6071 @example | 6378 @example |
| 6072 @group | 6379 @group |
| 6073 @@xref@{Electrical Effects, , Thunder and Lightning@}, | 6380 @@xref@{Electrical Effects, , Thunder and Lightning@}, |
| 6074 for details. | 6381 for details. |
| 6081 @example | 6388 @example |
| 6082 *Note Thunder and Lightning: Electrical Effects, for details. | 6389 *Note Thunder and Lightning: Electrical Effects, for details. |
| 6083 @end example | 6390 @end example |
| 6084 | 6391 |
| 6085 @noindent | 6392 @noindent |
| 6086 and | 6393 in Info and |
| 6087 | 6394 |
| 6088 @quotation | 6395 @quotation |
| 6089 See Section 5.2 [Thunder and Lightning], page 57, for details. | 6396 See Section 5.2 [Thunder and Lightning], page 57, for details. |
| 6090 @end quotation | 6397 @end quotation |
| 6091 | 6398 |
| 6399 @noindent | |
| 6400 in a printed manual. | |
| 6401 | |
| 6402 The third argument to cross references must observe some of the | |
| 6403 restrictions for node names (@pxref{Node Line Requirements}). The | |
| 6404 most common issue is that colons cannot be used, since that interferes | |
| 6405 with the parsing of the Info file. | |
| 6406 | |
| 6092 As a practical matter, it is often best to write cross references with | 6407 As a practical matter, it is often best to write cross references with |
| 6093 just the first argument if the node name and the section title are the | 6408 just the first argument if the node name and the section title are the |
| 6094 same, and with the first and third arguments if the node name and title | 6409 same (or nearly so), and with the first and third arguments only if the |
| 6095 are different.@refill | 6410 node name and title are different. |
| 6096 | 6411 |
| 6097 Here are several examples from @cite{The GNU Awk User's Guide}:@refill | 6412 @findex xrefautomaticsectiontitle |
| 6098 | 6413 Texinfo offers a setting to use the section title instead of node |
| 6099 @smallexample | 6414 names by default in cross references (an explicitly specified third |
| 6100 @@xref@{Sample Program@}. | 6415 argument still takes precedence): |
| 6101 @@xref@{Glossary@}. | 6416 |
| 6102 @@xref@{Case-sensitivity, ,Case-sensitivity in Matching@}. | 6417 @example |
| 6103 @@xref@{Close Output, , Closing Output Files and Pipes@}, | 6418 @@xrefautomaticsectiontitle on |
| 6104 for more information. | 6419 @end example |
| 6105 @@xref@{Regexp, , Regular Expressions as Patterns@}. | 6420 |
| 6106 @end smallexample | 6421 Typically this line would be given near the beginning of the document |
| 6422 and used for the whole manual. But you can turn it off if you want | |
| 6423 (@code{@@xrefautomaticsectiontitle off}), for example, if you're | |
| 6424 including some other sub-document that doesn't have suitable section | |
| 6425 names. | |
| 6426 | |
| 6107 | 6427 |
| 6108 @node Four and Five Arguments | 6428 @node Four and Five Arguments |
| 6109 @subsection @code{@@xref} with Four and Five Arguments | 6429 @subsection @code{@@xref} with Four and Five Arguments |
| 6430 @cindex Four- and five argument forms of cross references | |
| 6110 | 6431 |
| 6111 In a cross reference, a fourth argument specifies the name of another | 6432 In a cross reference, a fourth argument specifies the name of another |
| 6112 Info file, different from the file in which the reference appears, and | 6433 Info file, different from the file in which the reference appears, and |
| 6113 a fifth argument specifies its title as a printed manual.@refill | 6434 a fifth argument specifies its title as a printed manual. |
| 6114 | 6435 |
| 6115 Remember that a comma or period must follow the closing brace of an | 6436 Remember that a comma or period must follow the closing brace of an |
| 6116 @code{@@xref} command to terminate the cross reference. In the | 6437 @code{@@xref} command to terminate the cross reference. |
| 6117 following examples, a clause follows a terminating comma.@refill | |
| 6118 | 6438 |
| 6119 @need 800 | 6439 @need 800 |
| 6120 @noindent | 6440 @noindent |
| 6121 The template is: | 6441 The full template is: |
| 6122 | 6442 |
| 6123 @example | 6443 @example |
| 6124 @group | 6444 @group |
| 6125 @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}, | 6445 @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}, |
| 6126 @var{info-file-name}, @var{printed-manual-title}@}. | 6446 @var{info-file-name}, @var{printed-manual-title}@}. |
| 6131 @noindent | 6451 @noindent |
| 6132 For example, | 6452 For example, |
| 6133 | 6453 |
| 6134 @example | 6454 @example |
| 6135 @@xref@{Electrical Effects, Lightning, Thunder and Lightning, | 6455 @@xref@{Electrical Effects, Lightning, Thunder and Lightning, |
| 6136 weather, An Introduction to Meteorology@}, for details. | 6456 weather, An Introduction to Meteorology@}. |
| 6457 @end example | |
| 6458 | |
| 6459 @noindent | |
| 6460 produces this output in Info: | |
| 6461 | |
| 6462 @example | |
| 6463 *Note Lightning: (weather)Electrical Effects. | |
| 6464 @end example | |
| 6465 | |
| 6466 @noindent | |
| 6467 As you can see, the name of the Info file is enclosed in parentheses | |
| 6468 and precedes the name of the node. | |
| 6469 | |
| 6470 @noindent | |
| 6471 In a printed manual, the reference looks like this: | |
| 6472 | |
| 6473 @quotation | |
| 6474 See section ``Thunder and Lightning'' in @cite{An Introduction to | |
| 6475 Meteorology}. | |
| 6476 @end quotation | |
| 6477 | |
| 6478 @noindent | |
| 6479 The title of the printed manual is typeset like @code{@@cite}; and the | |
| 6480 reference lacks a page number since @TeX{} cannot know to which page a | |
| 6481 reference refers when that reference is to another manual. | |
| 6482 | |
| 6483 Next case: often, you will leave out the second argument when you use | |
| 6484 the long version of @code{@@xref}. In this case, the third argument, | |
| 6485 the topic description, will be used as the cross reference name in | |
| 6486 Info. For example, | |
| 6487 | |
| 6488 @example | |
| 6489 @@xref@{Electrical Effects, , Thunder and Lightning, | |
| 6490 weather, An Introduction to Meteorology@}. | |
| 6137 @end example | 6491 @end example |
| 6138 | 6492 |
| 6139 @noindent | 6493 @noindent |
| 6140 produces | 6494 produces |
| 6141 | 6495 |
| 6142 @example | 6496 @example |
| 6143 *Note Lightning: (weather)Electrical Effects, for details. | 6497 @group |
| 6144 @end example | 6498 *Note Thunder and Lightning: (weather)Electrical Effects. |
| 6145 | 6499 @end group |
| 6146 @noindent | 6500 @end example |
| 6147 The name of the Info file is enclosed in parentheses and precedes | 6501 |
| 6148 the name of the node. | 6502 @noindent |
| 6149 | 6503 in Info and |
| 6150 @noindent | |
| 6151 In a printed manual, the reference looks like this:@refill | |
| 6152 | 6504 |
| 6153 @quotation | 6505 @quotation |
| 6154 See section ``Thunder and Lightning'' in @i{An Introduction to | 6506 See section ``Thunder and Lightning'' in @cite{An Introduction to |
| 6155 Meteorology}, for details. | 6507 Meteorology}. |
| 6156 @end quotation | 6508 @end quotation |
| 6157 | 6509 |
| 6158 @noindent | 6510 @noindent |
| 6159 The title of the printed manual is typeset in italics; and the | 6511 in a printed manual. |
| 6160 reference lacks a page number since @TeX{} cannot know to which page a | 6512 |
| 6161 reference refers when that reference is to another manual.@refill | 6513 Next case: If the node name and the section title are the same in the |
| 6162 | 6514 other manual, you may also leave out the section title. In this case, |
| 6163 Often, you will leave out the second argument when you use the long | 6515 the node name is used in both instances. For example, |
| 6164 version of @code{@@xref}. In this case, the third argument, the topic | 6516 |
| 6165 description, will be used as the cross reference name in Info.@refill | 6517 @example |
| 6166 | 6518 @@xref@{Electrical Effects,,, |
| 6167 @noindent | 6519 weather, An Introduction to Meteorology@}. |
| 6168 The template looks like this: | 6520 @end example |
| 6169 | 6521 |
| 6170 @example | 6522 @noindent |
| 6171 @@xref@{@var{node-name}, , @var{title-or-topic}, @var{info-file-name}, | 6523 produces |
| 6172 @var{printed-manual-title}@}, for details. | 6524 |
| 6173 @end example | 6525 @example |
| 6174 | 6526 @group |
| 6175 @noindent | 6527 *Note (weather)Electrical Effects::. |
| 6176 which produces | 6528 @end group |
| 6177 | 6529 @end example |
| 6178 @example | 6530 |
| 6179 *Note @var{title-or-topic}: (@var{info-file-name})@var{node-name}, for details. | 6531 @noindent |
| 6180 @end example | 6532 in Info and |
| 6181 | |
| 6182 @noindent | |
| 6183 and | |
| 6184 | 6533 |
| 6185 @quotation | 6534 @quotation |
| 6186 See section @var{title-or-topic} in @var{printed-manual-title}, for details. | 6535 See section ``Electrical Effects'' in @cite{An Introduction to |
| 6536 Meteorology}. | |
| 6187 @end quotation | 6537 @end quotation |
| 6188 | 6538 |
| 6189 @need 700 | 6539 @noindent |
| 6190 @noindent | 6540 in a printed manual. |
| 6191 For example, | 6541 |
| 6192 | 6542 A very unusual case: you may want to refer to another manual file that |
| 6193 @example | |
| 6194 @@xref@{Electrical Effects, , Thunder and Lightning, | |
| 6195 weather, An Introduction to Meteorology@}, for details. | |
| 6196 @end example | |
| 6197 | |
| 6198 @noindent | |
| 6199 produces | |
| 6200 | |
| 6201 @example | |
| 6202 @group | |
| 6203 *Note Thunder and Lightning: (weather)Electrical Effects, | |
| 6204 for details. | |
| 6205 @end group | |
| 6206 @end example | |
| 6207 | |
| 6208 @noindent | |
| 6209 and | |
| 6210 | |
| 6211 @quotation | |
| 6212 See section ``Thunder and Lightning'' in @i{An Introduction to | |
| 6213 Meteorology}, for details. | |
| 6214 @end quotation | |
| 6215 | |
| 6216 On rare occasions, you may want to refer to another Info file that | |
| 6217 is within a single printed manual---when multiple Texinfo files are | 6543 is within a single printed manual---when multiple Texinfo files are |
| 6218 incorporated into the same @TeX{} run but make separate Info files. | 6544 incorporated into the same @TeX{} run but can create separate Info or |
| 6219 In this case, you need to specify only the fourth argument, and not | 6545 HTML output files. In this case, you need to specify only the fourth |
| 6220 the fifth.@refill | 6546 argument, and not the fifth. |
| 6547 | |
| 6548 Finally, it's also allowed to leave out all the arguments | |
| 6549 @emph{except} the fourth and fifth, to refer to another manual as a | |
| 6550 whole. See the next section. | |
| 6551 | |
| 6221 | 6552 |
| 6222 @node Top Node Naming | 6553 @node Top Node Naming |
| 6223 @section Naming a `Top' Node | 6554 @section Naming a `Top' Node |
| 6224 @cindex Naming a `Top' Node in references | 6555 @cindex Naming a `Top' Node in references |
| 6225 @cindex @samp{@r{Top}} node naming for references | 6556 @cindex `Top' node naming for references |
| 6226 | 6557 |
| 6227 In a cross reference, you must always name a node. This means that in | 6558 @cindex Manual, referring to as a whole |
| 6228 order to refer to a whole manual, you must identify the `Top' node by | 6559 @cindex Referring to an entire manual |
| 6229 writing it as the first argument to the @code{@@xref} command. (This | 6560 |
| 6230 is different from the way you write a menu entry; see @ref{Other Info | 6561 Ordinarily, you must always name a node in a cross reference. |
| 6231 Files, , Referring to Other Info Files}.) At the same time, to | 6562 However, it's not unusual to want to refer to another manual as a |
| 6232 provide a meaningful section topic or title in the printed cross | 6563 whole, rather than a particular section within it. In this case, |
| 6233 reference (instead of the word `Top'), you must write an appropriate | 6564 giving any section name is an unnecessary distraction. |
| 6234 entry for the third argument to the @code{@@xref} command. | 6565 |
| 6235 @refill | 6566 So, with cross references to other manuals (@pxref{Four and Five |
| 6236 | 6567 Arguments}), if the first argument is either @samp{Top} (capitalized |
| 6237 @noindent | 6568 just that way) or omitted entirely, and the third argument is omitted, |
| 6238 Thus, to make a cross reference to @cite{The GNU Make Manual}, | 6569 the printed output includes no node or section name. (The Info output |
| 6239 write:@refill | 6570 includes @samp{Top} if it was given.) For example, |
| 6240 | 6571 |
| 6241 @example | 6572 @example |
| 6242 @@xref@{Top, , Overview, make, The GNU Make Manual@}. | 6573 @@xref@{Top,,, make, The GNU Make Manual@}. |
| 6574 @end example | |
| 6575 | |
| 6576 @noindent produces | |
| 6577 | |
| 6578 @example | |
| 6579 @group | |
| 6580 *Note (make)::Top. | |
| 6581 @end group | |
| 6582 @end example | |
| 6583 | |
| 6584 @noindent and | |
| 6585 | |
| 6586 @quotation | |
| 6587 See @cite{The GNU Make Manual}. | |
| 6588 @end quotation | |
| 6589 | |
| 6590 @noindent | |
| 6591 Info readers will go to the Top node of the manual whether | |
| 6592 or not the `Top' node is explicitly specified. | |
| 6593 | |
| 6594 It's also possible (and is historical practice) to refer to a whole | |
| 6595 manual by specifying the `Top' node and an appropriate entry for the | |
| 6596 third argument to the @code{@@xref} command. Using this idiom, to | |
| 6597 make a cross reference to @cite{The GNU Make Manual}, you would write: | |
| 6598 | |
| 6599 @example | |
| 6600 @@xref@{Top,, Overview, make, The GNU Make Manual@}. | |
| 6243 @end example | 6601 @end example |
| 6244 | 6602 |
| 6245 @noindent | 6603 @noindent |
| 6246 which produces | 6604 which produces |
| 6247 | 6605 |
| 6248 @example | 6606 @example |
| 6249 *Note Overview: (make)Top. | 6607 *Note Overview: (make)Top. |
| 6250 @end example | 6608 @end example |
| 6251 | 6609 |
| 6252 @noindent | 6610 @noindent |
| 6253 and | 6611 in Info and |
| 6254 | 6612 |
| 6255 @quotation | 6613 @quotation |
| 6256 See section ``Overview'' in @i{The GNU Make Manual}. | 6614 See section ``Overview'' in @cite{The GNU Make Manual}. |
| 6257 @end quotation | 6615 @end quotation |
| 6258 | 6616 |
| 6259 @noindent | 6617 @noindent |
| 6618 in a printed manual. | |
| 6619 | |
| 6260 In this example, @samp{Top} is the name of the first node, and | 6620 In this example, @samp{Top} is the name of the first node, and |
| 6261 @samp{Overview} is the name of the first section of the manual. | 6621 @samp{Overview} is the name of the first section of the manual. There |
| 6262 | 6622 is no widely-used convention for naming the first section in a printed |
| 6263 | 6623 manual, this is just what the Make manual happens to use. This |
| 6264 @node ref | 6624 arbitrariness of the first name is a principal reason why omitting the |
| 6625 third argument in whole-manual cross references is preferable. | |
| 6626 | |
| 6627 | |
| 6628 @node @t{@@ref} | |
| 6265 @section @code{@@ref} | 6629 @section @code{@@ref} |
| 6630 | |
| 6631 @anchor{ref}@c old name | |
| 6632 @findex ref | |
| 6266 @cindex Cross references using @code{@@ref} | 6633 @cindex Cross references using @code{@@ref} |
| 6267 @cindex References using @code{@@ref} | 6634 @cindex References using @code{@@ref} |
| 6268 @findex ref | |
| 6269 | 6635 |
| 6270 @code{@@ref} is nearly the same as @code{@@xref} except that it does | 6636 @code{@@ref} is nearly the same as @code{@@xref} except that it does |
| 6271 not generate a `See' in the printed output, just the reference itself. | 6637 not generate a `See' in the printed output, just the reference itself. |
| 6272 This makes it useful as the last part of a sentence. | 6638 This makes it useful as the last part of a sentence. |
| 6273 | 6639 |
| 6276 @cindex Hurricanes | 6642 @cindex Hurricanes |
| 6277 @example | 6643 @example |
| 6278 For more information, @@pxref@{This@}, and @@ref@{That@}. | 6644 For more information, @@pxref@{This@}, and @@ref@{That@}. |
| 6279 @end example | 6645 @end example |
| 6280 | 6646 |
| 6281 @noindent produces in Info: | 6647 @noindent |
| 6648 produces in Info: | |
| 6282 | 6649 |
| 6283 @example | 6650 @example |
| 6284 For more information, *note This::, and *note That::. | 6651 For more information, *note This::, and *note That::. |
| 6285 @end example | 6652 @end example |
| 6286 | 6653 |
| 6287 @noindent and in printed output: | 6654 @noindent |
| 6655 and in printed output: | |
| 6288 | 6656 |
| 6289 @quotation | 6657 @quotation |
| 6290 For more information, see Section 1.1 [This], page 1, | 6658 For more information, see Section 1.1 [This], page 1, |
| 6291 and Section 1.2 [That], page 2. | 6659 and Section 1.2 [That], page 2. |
| 6292 @end quotation | 6660 @end quotation |
| 6293 | 6661 |
| 6294 The @code{@@ref} command sometimes tempts writers to express | 6662 The @code{@@ref} command can tempt writers to express themselves in a |
| 6295 themselves in a manner that is suitable for a printed manual but looks | 6663 manner that is suitable for a printed manual but looks awkward in the |
| 6296 awkward in the Info format. Bear in mind that your audience will be | 6664 Info format. Bear in mind that your audience could be using both the |
| 6297 using both the printed and the Info format. For example: | 6665 printed and the Info format. For example: |
| 6298 | 6666 |
| 6299 @cindex Sea surges | 6667 @cindex Sea surges |
| 6300 @example | 6668 @example |
| 6301 Sea surges are described in @@ref@{Hurricanes@}. | 6669 Sea surges are described in @@ref@{Hurricanes@}. |
| 6302 @end example | 6670 @end example |
| 6303 | 6671 |
| 6304 @noindent looks ok in the printed output: | 6672 @noindent |
| 6673 looks ok in the printed output: | |
| 6305 | 6674 |
| 6306 @quotation | 6675 @quotation |
| 6307 Sea surges are described in Section 6.7 [Hurricanes], page 72. | 6676 Sea surges are described in Section 6.7 [Hurricanes], page 72. |
| 6308 @end quotation | 6677 @end quotation |
| 6309 | 6678 |
| 6310 @noindent but is awkward to read in Info, ``note'' being a verb: | 6679 @noindent |
| 6680 but is awkward to read in Info, ``note'' being a verb: | |
| 6311 | 6681 |
| 6312 @example | 6682 @example |
| 6313 Sea surges are described in *note Hurricanes::. | 6683 Sea surges are described in *note Hurricanes::. |
| 6314 @end example | 6684 @end example |
| 6315 | 6685 |
| 6316 You should write a period or comma immediately after an @code{@@ref} | 6686 You should write a period or comma immediately after an @code{@@ref} |
| 6317 command with two or more arguments. If there is no such following | 6687 command with two or more arguments. If there is no such following |
| 6318 punctuation, @command{makeinfo} will generate a (grammatically | 6688 punctuation, @command{makeinfo} will generate a (grammatically |
| 6319 incorrect) period in the Info output; otherwise, the cross-reference | 6689 incorrect) period in the Info output; otherwise, the cross reference |
| 6320 would fail completely, due to the current syntax of Info format. | 6690 would fail completely, due to the current syntax of Info format. |
| 6321 | 6691 |
| 6322 In general, it is best to use @code{@@ref} only when you need some | 6692 In general, it is best to use @code{@@ref} only when you need some |
| 6323 word other than ``see'' to precede the reference. When ``see'' (or | 6693 word other than ``see'' to precede the reference. When ``see'' (or |
| 6324 ``See'') is ok, @code{@@xref} and @code{@@pxref} are preferable. | 6694 ``See'') is ok, @code{@@xref} and @code{@@pxref} are preferable. |
| 6325 | 6695 |
| 6326 | 6696 |
| 6327 @node pxref | 6697 @node @t{@@pxref} |
| 6328 @section @code{@@pxref} | 6698 @section @code{@@pxref} |
| 6699 | |
| 6700 @anchor{pxref}@c old name | |
| 6701 @findex pxref | |
| 6329 @cindex Cross references using @code{@@pxref} | 6702 @cindex Cross references using @code{@@pxref} |
| 6330 @cindex References using @code{@@pxref} | 6703 @cindex References using @code{@@pxref} |
| 6331 @findex pxref | |
| 6332 | 6704 |
| 6333 The parenthetical reference command, @code{@@pxref}, is nearly the | 6705 The parenthetical reference command, @code{@@pxref}, is nearly the |
| 6334 same as @code{@@xref}, but it is best used at the end of a sentence or | 6706 same as @code{@@xref}, but it is best used at the end of a sentence or |
| 6335 before a closing parenthesis. The command differs from @code{@@xref} | 6707 before a closing parenthesis. The command differs from @code{@@xref} |
| 6336 in two ways: | 6708 in two ways: |
| 6337 | 6709 |
| 6338 @enumerate | 6710 @enumerate |
| 6339 @item | 6711 @item |
| 6340 @TeX{} typesets the reference for the printed manual with a lower case | 6712 @TeX{} typesets the reference for the printed manual with a lowercase |
| 6341 `see' rather than an upper case `See'. | 6713 `see' rather than an uppercase `See'. |
| 6342 | 6714 |
| 6343 @item | 6715 @item |
| 6344 The Info formatting commands automatically end the reference with a | 6716 The Info formatting commands automatically end the reference with a |
| 6345 closing colon or period, if necessary. | 6717 closing colon or period, if necessary. |
| 6346 @end enumerate | 6718 @end enumerate |
| 6372 @dots{} storms cause flooding (*note Hurricanes::) @dots{} | 6744 @dots{} storms cause flooding (*note Hurricanes::) @dots{} |
| 6373 @end group | 6745 @end group |
| 6374 @end example | 6746 @end example |
| 6375 | 6747 |
| 6376 @noindent | 6748 @noindent |
| 6377 and | 6749 in Info and |
| 6378 | 6750 |
| 6379 @quotation | 6751 @quotation |
| 6380 @dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{} | 6752 @dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{} |
| 6381 @end quotation | 6753 @end quotation |
| 6382 | 6754 |
| 6755 @noindent | |
| 6756 in a printed manual. | |
| 6757 | |
| 6383 With two arguments, a parenthetical cross reference has this template: | 6758 With two arguments, a parenthetical cross reference has this template: |
| 6384 | 6759 |
| 6385 @example | 6760 @example |
| 6386 @dots{} (@@pxref@{@var{node-name}, @var{cross-reference-name}@}) @dots{} | 6761 @dots{} (@@pxref@{@var{node-name}, @var{cross-reference-name}@}) @dots{} |
| 6387 @end example | 6762 @end example |
| 6392 @example | 6767 @example |
| 6393 @dots{} (*note @var{cross-reference-name}: @var{node-name}.) @dots{} | 6768 @dots{} (*note @var{cross-reference-name}: @var{node-name}.) @dots{} |
| 6394 @end example | 6769 @end example |
| 6395 | 6770 |
| 6396 @noindent | 6771 @noindent |
| 6397 and | 6772 in Info and |
| 6398 | 6773 |
| 6399 @quotation | 6774 @quotation |
| 6400 @dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{} | 6775 @dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{} |
| 6401 @end quotation | 6776 @end quotation |
| 6402 | 6777 |
| 6778 @noindent | |
| 6779 in a printed manual. | |
| 6780 | |
| 6403 @code{@@pxref} can be used with up to five arguments, just like | 6781 @code{@@pxref} can be used with up to five arguments, just like |
| 6404 @code{@@xref} (@pxref{xref, , @code{@@xref}}). | 6782 @code{@@xref} (@pxref{@t{@@xref}}). |
| 6405 | 6783 |
| 6406 In past versions of Texinfo, it was not allowed to write punctuation | 6784 In past versions of Texinfo, it was not allowed to write punctuation |
| 6407 after a @code{@@pxref}, so it could be used @emph{only} before a right | 6785 after an @code{@@pxref}, so it could be used @emph{only} before a |
| 6408 parenthesis. This is no longer the case, so now it can be used (for | 6786 right parenthesis. This is no longer the case, so now it can be used |
| 6409 example) at the end of a sentence, where a lowercase ``see'' works | 6787 (for example) at the end of a sentence, where a lowercase ``see'' |
| 6410 best. For instance: | 6788 works best. For instance: |
| 6411 | 6789 |
| 6412 @example | 6790 @example |
| 6413 @dots{} For more information, @@pxref@{More@}. | 6791 @dots{} For more information, @@pxref@{More@}. |
| 6414 @end example | 6792 @end example |
| 6415 | 6793 |
| 6419 @example | 6797 @example |
| 6420 @dots{} For more information, *note More::. | 6798 @dots{} For more information, *note More::. |
| 6421 @end example | 6799 @end example |
| 6422 | 6800 |
| 6423 @noindent | 6801 @noindent |
| 6424 This works fine. @code{@@pxref} should only be followed by a comma, | 6802 In general, @code{@@pxref} should only be followed by a comma, period, |
| 6425 period, or right parenthesis; in other cases, @command{makeinfo} has | 6803 or right parenthesis; in other cases, @command{makeinfo} has to insert |
| 6426 to insert a period to make the cross-reference work correctly in Info, | 6804 a period to make the cross reference work correctly in Info, and that |
| 6427 and that period looks wrong. | 6805 period looks wrong. |
| 6428 | 6806 |
| 6429 As a matter of general style, @code{@@pxref} is best used at the ends | 6807 As a matter of style, @code{@@pxref} is best used at the ends of |
| 6430 of sentences. Although it technically works in the middle of a | 6808 sentences. Although it technically works in the middle of a sentence, |
| 6431 sentence, that location breaks up the flow of reading. | 6809 that location breaks up the flow of reading. |
| 6432 | 6810 |
| 6433 | 6811 |
| 6434 @node inforef | 6812 @node @t{@@inforef} |
| 6435 @section @code{@@inforef} | 6813 @section @code{@@inforef}: Cross References to Info-only Material |
| 6814 | |
| 6815 @anchor{inforef}@c old name | |
| 6816 @findex inforef | |
| 6436 @cindex Cross references using @code{@@inforef} | 6817 @cindex Cross references using @code{@@inforef} |
| 6437 @cindex References using @code{@@inforef} | 6818 @cindex References using @code{@@inforef} |
| 6438 @findex inforef | |
| 6439 | 6819 |
| 6440 @code{@@inforef} is used for making cross references to Info | 6820 @code{@@inforef} is used for making cross references to Info |
| 6441 documents---even from a printed manual. This might be because you | 6821 documents---even from a printed manual. This might be because you |
| 6442 want to refer to conditional @code{@@ifinfo} text | 6822 want to refer to conditional @code{@@ifinfo} text |
| 6443 (@pxref{Conditionals}), or because printed output is not available | 6823 (@pxref{Conditionals}), or because printed output is not available |
| 6444 (perhaps because there is no Texinfo source), among other | 6824 (perhaps because there is no Texinfo source), among other |
| 6445 possibilities. | 6825 possibilities. |
| 6446 | 6826 |
| 6447 The command takes either two or three arguments, in the following | 6827 The command takes either two or three arguments, in the following |
| 6448 order:@refill | 6828 order: |
| 6449 | 6829 |
| 6450 @enumerate | 6830 @enumerate |
| 6451 @item | 6831 @item |
| 6452 The node name. | 6832 The node name. |
| 6453 | 6833 |
| 6459 @end enumerate | 6839 @end enumerate |
| 6460 | 6840 |
| 6461 @noindent | 6841 @noindent |
| 6462 Separate the arguments with commas, as with @code{@@xref}. Also, you | 6842 Separate the arguments with commas, as with @code{@@xref}. Also, you |
| 6463 must terminate the reference with a comma or period after the | 6843 must terminate the reference with a comma or period after the |
| 6464 @samp{@}}, as you do with @code{@@xref}.@refill | 6844 @samp{@}}, as you do with @code{@@xref}. |
| 6465 | 6845 |
| 6466 @noindent | 6846 @noindent |
| 6467 The template is: | 6847 The template is: |
| 6468 | 6848 |
| 6469 @example | 6849 @example |
| 6499 @quotation | 6879 @quotation |
| 6500 See Info file @file{info}, node @samp{Advanced}, for more information. | 6880 See Info file @file{info}, node @samp{Advanced}, for more information. |
| 6501 @end quotation | 6881 @end quotation |
| 6502 | 6882 |
| 6503 (This particular example is not realistic, since the Info manual is | 6883 (This particular example is not realistic, since the Info manual is |
| 6504 written in Texinfo, so all formats are available.) | 6884 written in Texinfo, so all formats are available. In fact, we don't |
| 6885 know of any extant Info-only manuals.) | |
| 6505 | 6886 |
| 6506 The converse of @code{@@inforef} is @code{@@cite}, which is used to | 6887 The converse of @code{@@inforef} is @code{@@cite}, which is used to |
| 6507 refer to printed works for which no Info form exists. @xref{cite, , | 6888 refer to printed works for which no Info form exists. |
| 6508 @code{@@cite}}. | 6889 @xref{@t{@@cite}}. |
| 6509 | 6890 |
| 6510 | 6891 |
| 6511 @node uref | 6892 @node @t{@@url} |
| 6512 @section @code{@@url}, @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}} | 6893 @section @code{@@url}, @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}} |
| 6894 | |
| 6895 @anchor{uref}@c old name | |
| 6513 @findex uref | 6896 @findex uref |
| 6514 @cindex Uniform resource locator, referring to | 6897 @cindex Uniform resource locator, referring to |
| 6515 @cindex URL, referring to | 6898 @cindex URL, referring to |
| 6516 | 6899 |
| 6517 @cindex @code{href}, producing HTML | 6900 @cindex @code{href}, producing HTML |
| 6518 @code{@@uref} produces a reference to a uniform resource locator (url). | 6901 @code{@@uref} produces a reference to a uniform resource locator (url). |
| 6519 It takes one mandatory argument, the url, and two optional arguments | 6902 It takes one mandatory argument, the url, and two optional arguments |
| 6520 which control the text that is displayed. In HTML output, @code{@@uref} | 6903 which control the text that is displayed. In HTML output, @code{@@uref} |
| 6521 produces a link you can follow. | 6904 produces a link you can follow. |
| 6522 | 6905 |
| 6523 @code{@@url} is a synonym for @code{@@uref}. Originally, @code{@@url} | 6906 @anchor{url} @code{@@url} is a synonym for @code{@@uref}. |
| 6524 had the meaning of @code{@@indicateurl} | 6907 (Originally, @code{@@url} had the meaning of @code{@@indicateurl} |
| 6525 (@pxref{indicateurl,,@code{@@indicateurl}}), but in actual practice it | 6908 (@pxref{@t{@@indicateurl}}), but in practice it was almost always |
| 6526 was misused the vast majority of the time. So we've changed the | 6909 misused. So we've changed the meaning.) |
| 6527 meaning. | |
| 6528 | 6910 |
| 6529 The second argument, if specified, is the text to display (the default | 6911 The second argument, if specified, is the text to display (the default |
| 6530 is the url itself); in Info and DVI output, but not in HTML output, the | 6912 is the url itself); in Info and DVI output, but not in HTML output, the |
| 6531 url is also output. | 6913 url is output in addition to this text. |
| 6532 | 6914 |
| 6533 @cindex Man page, reference to | 6915 @cindex Man page, reference to |
| 6534 The third argument, if specified, is the text to display, but in this | 6916 The third argument, if specified, is the text to display, but in this |
| 6535 case the url is @emph{not} output in any format. This is useful when | 6917 case the url is not output in any format. This is useful when the |
| 6536 the text is already sufficiently referential, as in a man page. If | 6918 text is already sufficiently referential, as in a man page. If the |
| 6537 the third argument is given, the second argument is ignored. | 6919 third argument is given, the second argument is ignored. |
| 6538 | 6920 |
| 6539 If the url is long enough to cause problems with line breaking, you | 6921 @cindex Line breaking, and urls |
| 6540 may find it useful to insert @code{@@/} at places where a line break | 6922 @cindex Breakpoints within urls |
| 6541 would be acceptable (after @samp{/} characters, for instance). This | 6923 @TeX{} allows line breaking within urls at only a few characters |
| 6542 tells @TeX{} to allow (but not force) a line break at those places. | 6924 (which are special in urls): @samp{&}, @samp{.}, @samp{#}, @samp{?}, |
| 6543 @xref{Line Breaks}. | 6925 and @samp{/} (but not between @samp{/} characters). A tiny amount of |
| 6926 stretchable space is also inserted around these characters to help | |
| 6927 with line breaking. For HTML output, modern browsers will also do | |
| 6928 line breaking within displayed urls. If you need to allow breaks at | |
| 6929 other characters you can insert @code{@@/} as needed (@pxref{Line | |
| 6930 Breaks}). | |
| 6931 | |
| 6932 @findex urefbreakstyle | |
| 6933 By default, any such breaks at special characters will occur after the | |
| 6934 character. Some people prefer such breaks to happen after the special | |
| 6935 character. This can be controlled with the @code{@@urefbreakstyle} | |
| 6936 command (this command has effect only in @TeX{}): | |
| 6937 | |
| 6938 Write this command at the | |
| 6939 beginning of a line with a single word as an argument, one of the | |
| 6940 following: | |
| 6941 | |
| 6942 @vindex after@r{, value for @code{@@urefbreakstyle}} | |
| 6943 @vindex before@r{, value for @code{@@urefbreakstyle}} | |
| 6944 @vindex none@r{, value for @code{@@urefbreakstyle}} | |
| 6945 @table @samp | |
| 6946 @item after | |
| 6947 (the default) Potentially break after the special characters. | |
| 6948 @item before | |
| 6949 Potentially break before the special characters. | |
| 6950 @item none | |
| 6951 Do not consider breaking at the special characters; any potential | |
| 6952 breaks must be manually inserted. | |
| 6953 @end table | |
| 6544 | 6954 |
| 6545 Here is an example of the simple one argument form, where the url is | 6955 Here is an example of the simple one argument form, where the url is |
| 6546 both the target and the text of the link: | 6956 both the target and the text of the link: |
| 6547 | 6957 |
| 6548 @example | 6958 @example |
| 6549 The official GNU ftp site is @@uref@{ftp://ftp.gnu.org/gnu@}. | 6959 The official GNU ftp site is @@uref@{http://ftp.gnu.org/gnu@}. |
| 6550 @end example | 6960 @end example |
| 6551 | 6961 |
| 6552 @noindent produces: | 6962 @noindent produces: |
| 6553 @display | 6963 @display |
| 6554 The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}. | 6964 The official GNU ftp site is @uref{http://ftp.gnu.org/gnu}. |
| 6555 @end display | 6965 @end display |
| 6556 | 6966 |
| 6557 | 6967 |
| 6558 An example of the two-argument form: | 6968 An example of the two-argument form: |
| 6559 @example | 6969 @example |
| 6560 The official @@uref@{ftp://ftp.gnu.org/gnu, GNU ftp site@} | 6970 The official @@uref@{http://ftp.gnu.org/gnu, GNU ftp site@} |
| 6561 holds programs and texts. | 6971 holds programs and texts. |
| 6562 @end example | 6972 @end example |
| 6563 | 6973 |
| 6564 @noindent produces: | 6974 @noindent produces: |
| 6565 @display | 6975 @display |
| 6566 The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site} | 6976 The official @uref{http://ftp.gnu.org/gnu, GNU ftp site} |
| 6567 holds programs and texts. | 6977 holds programs and texts. |
| 6568 @end display | 6978 @end display |
| 6569 | 6979 |
| 6570 @noindent that is, the Info output is this: | 6980 @noindent that is, the Info output is this: |
| 6571 @example | 6981 @example |
| 6572 The official GNU ftp site (ftp://ftp.gnu.org/gnu) | 6982 The official GNU ftp site (http://ftp.gnu.org/gnu) |
| 6573 holds programs and texts. | 6983 holds programs and texts. |
| 6574 @end example | 6984 @end example |
| 6575 | 6985 |
| 6576 @noindent and the HTML output is this: | 6986 @noindent and the HTML output is this: |
| 6577 @example | 6987 @example |
| 6578 The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a> | 6988 The official <a href="http://ftp.gnu.org/gnu">GNU ftp site</a> |
| 6579 holds programs and texts. | 6989 holds programs and texts. |
| 6580 @end example | 6990 @end example |
| 6581 | 6991 |
| 6582 | 6992 |
| 6583 An example of the three-argument form: | 6993 An example of the three-argument form: |
| 6593 @noindent but with HTML: | 7003 @noindent but with HTML: |
| 6594 @example | 7004 @example |
| 6595 The <a href="/man.cgi/1/ls">ls</a> program @dots{} | 7005 The <a href="/man.cgi/1/ls">ls</a> program @dots{} |
| 6596 @end example | 7006 @end example |
| 6597 | 7007 |
| 6598 To merely indicate a url without creating a link people can follow, use | 7008 Some people prefer to display urls in the unambiguous format: |
| 6599 @code{@@indicateurl} (@pxref{indicateurl, @code{@@indicateurl}}). | |
| 6600 | |
| 6601 Some people prefer to display url's in the unambiguous format: | |
| 6602 | 7009 |
| 6603 @display | 7010 @display |
| 6604 <URL:http://@var{host}/@var{path}> | 7011 <URL:http://@var{host}/@var{path}> |
| 6605 @end display | 7012 @end display |
| 6606 | 7013 |
| 6607 @noindent | 7014 @noindent |
| 6608 @cindex <URL: convention, not used | 7015 @cindex @code{<URL...>} convention, not used |
| 6609 You can use this form in the input file if you wish. We feel it's not | 7016 You can use this form in the input file if you wish. We feel it's not |
| 6610 necessary to include the @samp{<URL:} and @samp{>} in the output, | 7017 necessary to include the @samp{<URL:} and @samp{>} in the output, |
| 6611 since any software that tries to detect url's in text already has to | 7018 since any software that tries to detect urls in text already has to |
| 6612 detect them without the @samp{<URL:} to be useful. | 7019 detect them without the @samp{<URL:} to be useful. |
| 6613 | 7020 |
| 6614 | 7021 To merely indicate a url without creating a link people can follow, |
| 6615 @node cite | 7022 use @code{@@indicateurl} (@pxref{@t{@@indicateurl}}). |
| 7023 | |
| 7024 | |
| 7025 @node @t{@@cite} | |
| 6616 @section @code{@@cite}@{@var{reference}@} | 7026 @section @code{@@cite}@{@var{reference}@} |
| 7027 | |
| 7028 @anchor{cite}@c old name | |
| 6617 @findex cite | 7029 @findex cite |
| 6618 | 7030 |
| 6619 Use the @code{@@cite} command for the name of a book that lacks a | 7031 Use the @code{@@cite} command for the name of a book that lacks a |
| 6620 companion Info file. The command produces italics in the printed | 7032 companion Info file. The command produces italics in the printed |
| 6621 manual, and quotation marks in the Info file. | 7033 manual, and quotation marks in the Info file. |
| 6622 | 7034 |
| 6623 If a book is written in Texinfo, it is better to use a cross reference | 7035 If a book is written in Texinfo, it is better to use a cross reference |
| 6624 command since a reader can easily follow such a reference in Info. | 7036 command since a reader can easily follow such a reference in Info. |
| 6625 @xref{xref, , @code{@@xref}}. | 7037 @xref{@t{@@xref}}. |
| 6626 | 7038 |
| 6627 | 7039 |
| 6628 @node Marking Text | 7040 @node Marking Text |
| 6629 @chapter Marking Words and Phrases | 7041 @chapter Marking Text, Words and Phrases |
| 6630 @cindex Paragraph, marking text within | 7042 @cindex Paragraph, marking text within |
| 6631 @cindex Marking words and phrases | 7043 @cindex Marking words and phrases |
| 6632 @cindex Words and phrases, marking them | 7044 @cindex Words and phrases, marking them |
| 6633 @cindex Marking text within a paragraph | 7045 @cindex Marking text within a paragraph |
| 6634 @cindex Text, marking up | 7046 @cindex Text, marking up |
| 6646 @end menu | 7058 @end menu |
| 6647 | 7059 |
| 6648 | 7060 |
| 6649 @node Indicating | 7061 @node Indicating |
| 6650 @section Indicating Definitions, Commands, etc. | 7062 @section Indicating Definitions, Commands, etc. |
| 7063 | |
| 6651 @cindex Highlighting text | 7064 @cindex Highlighting text |
| 6652 @cindex Indicating commands, definitions, etc. | 7065 @cindex Indicating commands, definitions, etc. |
| 6653 | 7066 |
| 6654 Texinfo has commands for indicating just what kind of object a piece of | 7067 Texinfo has commands for indicating just what kind of object a piece |
| 6655 text refers to. For example, metasyntactic variables are marked by | 7068 of text refers to. For example, email addresses are marked by |
| 6656 @code{@@var}, and code by @code{@@code}. Since the pieces of text are | 7069 @code{@@email}; that way, the result can be a live link to send email |
| 6657 labelled by commands that tell what kind of object they are, it is easy | 7070 when the output format supports it. If the email address was simply |
| 6658 to change the way the Texinfo formatters prepare such text. (Texinfo is | 7071 marked as ``print in a typewriter font'', that would not be possible. |
| 6659 an @emph{intentional} formatting language rather than a @emph{typesetting} | |
| 6660 formatting language.)@refill | |
| 6661 | |
| 6662 For example, in a printed manual, | |
| 6663 code is usually illustrated in a typewriter font; | |
| 6664 @code{@@code} tells @TeX{} to typeset this text in this font. But it | |
| 6665 would be easy to change the way @TeX{} highlights code to use another | |
| 6666 font, and this change would not affect how keystroke examples are | |
| 6667 highlighted. If straight typesetting commands were used in the body | |
| 6668 of the file and you wanted to make a change, you would need to check | |
| 6669 every single occurrence to make sure that you were changing code and | |
| 6670 not something else that should not be changed.@refill | |
| 6671 | 7072 |
| 6672 @menu | 7073 @menu |
| 6673 * Useful Highlighting:: Highlighting provides useful information. | 7074 * Useful Highlighting:: Highlighting provides useful information. |
| 6674 * code:: Indicating program code. | 7075 * @t{@@code}:: Indicating program code. |
| 6675 * kbd:: Showing keyboard input. | 7076 * @t{@@kbd}:: Showing keyboard input. |
| 6676 * key:: Specifying keys. | 7077 * @t{@@key}:: Specifying keys. |
| 6677 * samp:: Indicating a literal sequence of characters. | 7078 * @t{@@samp}:: Indicating a literal sequence of characters. |
| 6678 * verb:: Indicating a verbatim sequence of characters. | 7079 * @t{@@verb}:: Indicating a verbatim sequence of characters. |
| 6679 * var:: Indicating metasyntactic variables. | 7080 * @t{@@var}:: Indicating metasyntactic variables. |
| 6680 * env:: Indicating environment variables. | 7081 * @t{@@env}:: Indicating environment variables. |
| 6681 * file:: Indicating file names. | 7082 * @t{@@file}:: Indicating file names. |
| 6682 * command:: Indicating command names. | 7083 * @t{@@command}:: Indicating command names. |
| 6683 * option:: Indicating option names. | 7084 * @t{@@option}:: Indicating option names. |
| 6684 * dfn:: Specifying definitions. | 7085 * @t{@@dfn}:: Specifying definitions. |
| 6685 * abbr:: Indicating abbreviations. | 7086 * @t{@@abbr}:: Indicating abbreviations. |
| 6686 * acronym:: Indicating acronyms. | 7087 * @t{@@acronym}:: Indicating acronyms. |
| 6687 * indicateurl:: Indicating an example URL. | 7088 * @t{@@indicateurl}:: Indicating an example url. |
| 6688 * email:: Indicating an electronic mail address. | 7089 * @t{@@email}:: Indicating an electronic mail address. |
| 6689 @end menu | 7090 @end menu |
| 6690 | 7091 |
| 6691 | 7092 |
| 6692 @node Useful Highlighting | 7093 @node Useful Highlighting |
| 6693 @subsection Highlighting Commands are Useful | 7094 @subsection Highlighting Commands are Useful |
| 6694 | 7095 |
| 6695 The highlighting commands can be used to extract useful information | 7096 The commands serve a variety of purposes: |
| 6696 from the file, such as lists of functions or file names. It is | |
| 6697 possible, for example, to write a program in XEmacs Lisp (or a keyboard | |
| 6698 macro) to insert an index entry after every paragraph that contains | |
| 6699 words or phrases marked by a specified command. You could do this to | |
| 6700 construct an index of functions if you had not already made the | |
| 6701 entries.@refill | |
| 6702 | |
| 6703 The commands serve a variety of purposes:@refill | |
| 6704 | 7097 |
| 6705 @table @code | 7098 @table @code |
| 6706 @item @@code@{@var{sample-code}@} | 7099 @item @@code@{@var{sample-code}@} |
| 6707 Indicate text that is a literal example of a piece of a program. | 7100 Indicate text that is a literal example of a piece of a program. |
| 6708 @xref{code,,@code{@@code}}. | 7101 @xref{@t{@@code}}. |
| 6709 | 7102 |
| 6710 @item @@kbd@{@var{keyboard-characters}@} | 7103 @item @@kbd@{@var{keyboard-characters}@} |
| 6711 Indicate keyboard input. | 7104 Indicate keyboard input. @xref{@t{@@kbd}}. |
| 6712 @xref{kbd,,@code{@@kbd}}. | |
| 6713 | 7105 |
| 6714 @item @@key@{@var{key-name}@} | 7106 @item @@key@{@var{key-name}@} |
| 6715 Indicate the conventional name for a key on a keyboard. | 7107 Indicate the conventional name for a key on a keyboard. |
| 6716 @xref{key,,@code{@@key}}. | 7108 @xref{@t{@@key}}. |
| 6717 | 7109 |
| 6718 @item @@samp@{@var{text}@} | 7110 @item @@samp@{@var{text}@} |
| 6719 Indicate text that is a literal example of a sequence of characters. | 7111 Indicate text that is a literal example of a sequence of characters. |
| 6720 @xref{samp,,@code{@@samp}}. | 7112 @xref{@t{@@samp}}. |
| 6721 | 7113 |
| 6722 @item @@verb@{@var{text}@} | 7114 @item @@verb@{@var{text}@} |
| 6723 Write a verbatim sequence of characters. | 7115 Write a verbatim sequence of characters. |
| 6724 @xref{verb,,@code{@@verb}}. | 7116 @xref{@t{@@verb}}. |
| 6725 | 7117 |
| 6726 @item @@var@{@var{metasyntactic-variable}@} | 7118 @item @@var@{@var{metasyntactic-variable}@} |
| 6727 Indicate a metasyntactic variable. | 7119 Indicate a metasyntactic variable. @xref{@t{@@var}}. |
| 6728 @xref{var,,@code{@@var}}. | |
| 6729 | 7120 |
| 6730 @item @@env@{@var{environment-variable}@} | 7121 @item @@env@{@var{environment-variable}@} |
| 6731 Indicate an environment variable. | 7122 Indicate an environment variable. @xref{@t{@@env}}. |
| 6732 @xref{env,,@code{@@env}}. | |
| 6733 | 7123 |
| 6734 @item @@file@{@var{file-name}@} | 7124 @item @@file@{@var{file-name}@} |
| 6735 Indicate the name of a file. | 7125 Indicate the name of a file. @xref{@t{@@file}}. |
| 6736 @xref{file,,@code{@@file}}. | |
| 6737 | 7126 |
| 6738 @item @@command@{@var{command-name}@} | 7127 @item @@command@{@var{command-name}@} |
| 6739 Indicate the name of a command. | 7128 Indicate the name of a command. |
| 6740 @xref{command,,@code{@@command}}. | 7129 @xref{@t{@@command}}. |
| 6741 | 7130 |
| 6742 @item @@option@{@var{option}@} | 7131 @item @@option@{@var{option}@} |
| 6743 Indicate a command-line option. | 7132 Indicate a command-line option. |
| 6744 @xref{option,,@code{@@option}}. | 7133 @xref{@t{@@option}}. |
| 6745 | 7134 |
| 6746 @item @@dfn@{@var{term}@} | 7135 @item @@dfn@{@var{term}@} |
| 6747 Indicate the introductory or defining use of a term. | 7136 Indicate the introductory or defining use of a term. |
| 6748 @xref{dfn,,@code{@@dfn}}. | 7137 @xref{@t{@@dfn}}. |
| 6749 | 7138 |
| 6750 @item @@cite@{@var{reference}@} | 7139 @item @@cite@{@var{reference}@} |
| 6751 Indicate the name of a book. | 7140 Indicate the name of a book. @xref{@t{@@cite}}. |
| 6752 @xref{cite,,@code{@@cite}}. | |
| 6753 | 7141 |
| 6754 @item @@abbr@{@var{abbreviation}@} | 7142 @item @@abbr@{@var{abbreviation}@} |
| 6755 Indicate an abbreviation, such as `Comput.'. | 7143 Indicate an abbreviation, such as `Comput.'. |
| 6756 | 7144 |
| 6757 @item @@acronym@{@var{acronym}@} | 7145 @item @@acronym@{@var{acronym}@} |
| 6758 Indicate an acronym. | 7146 Indicate an acronym. @xref{@t{@@acronym}}. |
| 6759 @xref{acronym,,@code{@@acronym}}. | |
| 6760 | 7147 |
| 6761 @item @@indicateurl@{@var{uniform-resource-locator}@} | 7148 @item @@indicateurl@{@var{uniform-resource-locator}@} |
| 6762 Indicate an example (that is, nonfunctional) uniform resource locator. | 7149 Indicate an example (that is, nonfunctional) uniform resource locator. |
| 6763 @xref{indicateurl,,@code{@@indicateurl}}. (Use @code{@@url} | 7150 @xref{@t{@@indicateurl}}. (Use @code{@@url} (@pxref{@t{@@url}}) for |
| 6764 (@pxref{uref,,@code{@@url}}) for live url's.) | 7151 live urls.) |
| 6765 | 7152 |
| 6766 @item @@email@{@var{email-address}[, @var{displayed-text}]@} | 7153 @item @@email@{@var{email-address}[, @var{displayed-text}]@} |
| 6767 Indicate an electronic mail address. | 7154 Indicate an electronic mail address. @xref{@t{@@email}}. |
| 6768 @xref{email,,@code{@@email}}. | 7155 |
| 6769 | |
| 6770 @ignore | |
| 6771 @item @@ctrl@{@var{ctrl-char}@} | |
| 6772 Use for an ASCII control character. | |
| 6773 @end ignore | |
| 6774 @end table | 7156 @end table |
| 6775 | 7157 |
| 6776 | 7158 |
| 6777 @node code | 7159 @node @t{@@code} |
| 6778 @subsection @code{@@code}@{@var{sample-code}@} | 7160 @subsection @code{@@code}@{@var{sample-code}@} |
| 7161 | |
| 7162 @anchor{code}@c old name | |
| 6779 @findex code | 7163 @findex code |
| 6780 | 7164 |
| 6781 @cindex Syntactic tokens, indicating | 7165 @cindex Syntactic tokens, indicating |
| 6782 Use the @code{@@code} command to indicate text that is a piece of a | 7166 Use the @code{@@code} command to indicate text that is a piece of a |
| 6783 program and which consists of entire syntactic tokens. Enclose the | 7167 program and which consists of entire syntactic tokens. Enclose the |
| 6801 languages are case sensitive. In C, for example, @code{Printf} is | 7185 languages are case sensitive. In C, for example, @code{Printf} is |
| 6802 different from the identifier @code{printf}, and most likely is a | 7186 different from the identifier @code{printf}, and most likely is a |
| 6803 misspelling of it. Even in languages which are not case sensitive, it | 7187 misspelling of it. Even in languages which are not case sensitive, it |
| 6804 is confusing to a human reader to see identifiers spelled in different | 7188 is confusing to a human reader to see identifiers spelled in different |
| 6805 ways. Pick one spelling and always use that. If you do not want to | 7189 ways. Pick one spelling and always use that. If you do not want to |
| 6806 start a sentence with a command name written all in lower case, you | 7190 start a sentence with a command name written all in lowercase, you |
| 6807 should rearrange the sentence. | 7191 should rearrange the sentence. |
| 6808 | 7192 |
| 6809 In the printed manual, @code{@@code} causes @TeX{} to typeset the | 7193 In the Info output, @code{@@code} results in single quotation marks |
| 6810 argument in a typewriter face. In the Info file, it causes the Info | 7194 around the text. In other formats, @code{@@code} argument is typeset |
| 6811 formatting commands to use single quotation marks around the text. | 7195 in a typewriter (monospace) font. For example, |
| 6812 For example, | |
| 6813 | 7196 |
| 6814 @example | 7197 @example |
| 6815 The function returns @@code@{nil@}. | 7198 The function returns @@code@{nil@}. |
| 6816 @end example | 7199 @end example |
| 6817 | 7200 |
| 6820 | 7203 |
| 6821 @quotation | 7204 @quotation |
| 6822 The function returns @code{nil}. | 7205 The function returns @code{nil}. |
| 6823 @end quotation | 7206 @end quotation |
| 6824 | 7207 |
| 6825 @iftex | |
| 6826 @noindent | |
| 6827 and this in the Info file: | |
| 6828 @example | |
| 6829 The function returns `nil'. | |
| 6830 @end example | |
| 6831 @end iftex | |
| 6832 | |
| 6833 Here are some cases for which it is preferable @emph{not} to use @code{@@code}: | 7208 Here are some cases for which it is preferable @emph{not} to use @code{@@code}: |
| 6834 | 7209 |
| 6835 @itemize @bullet | 7210 @itemize @bullet |
| 6836 @item | 7211 @item |
| 6837 For shell command names such as @command{ls} (use @code{@@command}). | 7212 For shell command names such as @command{ls} (use @code{@@command}). |
| 6838 | 7213 |
| 6839 @item | 7214 @item |
| 7215 For environment variable such as @env{TEXINPUTS} (use @code{@@env}). | |
| 7216 | |
| 7217 @item | |
| 6840 For shell options such as @samp{-c} when such options stand alone (use | 7218 For shell options such as @samp{-c} when such options stand alone (use |
| 6841 @code{@@option}). | 7219 @code{@@option}). |
| 6842 | 7220 |
| 6843 @item | 7221 @item |
| 6844 Also, an entire shell command often looks better if written using | 7222 An entire shell command often looks better if written using |
| 6845 @code{@@samp} rather than @code{@@code}. In this case, the rule is to | 7223 @code{@@samp} rather than @code{@@code}. In this case, the rule is to |
| 6846 choose the more pleasing format. | 7224 choose the more pleasing format. |
| 6847 | |
| 6848 @item | |
| 6849 For environment variable such as @env{TEXINPUTS} (use @code{@@env}). | |
| 6850 | 7225 |
| 6851 @item | 7226 @item |
| 6852 For a string of characters shorter than a syntactic token. For example, | 7227 For a string of characters shorter than a syntactic token. For example, |
| 6853 if you are writing about @samp{goto-ch}, which is just a part of the | 7228 if you are writing about @samp{goto-ch}, which is just a part of the |
| 6854 name for the @code{goto-char} XEmacs Lisp function, you should use | 7229 name for the @code{goto-char} Emacs Lisp function, you should use |
| 6855 @code{@@samp}. | 7230 @code{@@samp}. |
| 6856 | 7231 |
| 6857 @item | 7232 @item |
| 6858 In general, when writing about the characters used in a token; for | 7233 In general, when writing about the characters used in a token; for |
| 6859 example, do not use @code{@@code} when you are explaining what letters | 7234 example, do not use @code{@@code} when you are explaining what letters |
| 6861 @code{@@samp}.) Also, you should not use @code{@@code} to mark text | 7236 @code{@@samp}.) Also, you should not use @code{@@code} to mark text |
| 6862 that is considered input to programs unless the input is written in a | 7237 that is considered input to programs unless the input is written in a |
| 6863 language that is like a programming language. For example, you should | 7238 language that is like a programming language. For example, you should |
| 6864 not use @code{@@code} for the keystroke commands of XEmacs (use | 7239 not use @code{@@code} for the keystroke commands of XEmacs (use |
| 6865 @code{@@kbd} instead) although you may use @code{@@code} for the names | 7240 @code{@@kbd} instead) although you may use @code{@@code} for the names |
| 6866 of the XEmacs Lisp functions that the keystroke commands invoke. | 7241 of the Emacs Lisp functions that the keystroke commands invoke. |
| 6867 | 7242 |
| 6868 @end itemize | 7243 @end itemize |
| 6869 | 7244 |
| 6870 Since @code{@@command}, @code{@@option}, and @code{@@env} were | 7245 By default, @TeX{} will consider breaking lines at @samp{-} and |
| 6871 introduced relatively recently, it is acceptable to use @code{@@code} or | |
| 6872 @code{@@samp} for command names, options, and environment variables. | |
| 6873 The new commands allow you to express the markup more precisely, but | |
| 6874 there is no real harm in using the older commands, and of course the | |
| 6875 long-standing manuals do so. | |
| 6876 | |
| 6877 Ordinarily, @TeX{} will consider breaking lines at @samp{-} and | |
| 6878 @samp{_} characters within @code{@@code} and related commands. This | 7246 @samp{_} characters within @code{@@code} and related commands. This |
| 6879 can be controlled with @code{@@allowcodebreaks} | 7247 can be controlled with @code{@@allowcodebreaks} |
| 6880 (@pxref{allowcodebreaks,,@code{@@allowcodebreaks}}). | 7248 (@pxref{@t{@@allowcodebreaks}}). The HTML output attempts to |
| 6881 | 7249 respect this for @samp{-}, but ultimately it is up to the browser's |
| 6882 | 7250 behavior. For Info, it seems better never to make such breaks. |
| 6883 @node kbd | 7251 |
| 7252 For Info, the quotes are omitted in the output of the @code{@@code} | |
| 7253 command and related commands (e.g., @code{@@kbd}, @code{@@command}), | |
| 7254 in typewriter-like contexts such as the @code{@@example} environment | |
| 7255 (@pxref{@t{@@example}}) and @code{@@code} itself, etc. | |
| 7256 | |
| 7257 To control which quoting characters are implicitly inserted by Texinfo | |
| 7258 processors in the output of @samp{@@code}, etc., see the | |
| 7259 @code{OPEN_QUOTE_SYMBOL} and @code{CLOSE_QUOTE_SYMBOL} customization | |
| 7260 variables (@pxref{Other Customization Variables}). This is separate | |
| 7261 from how actual quotation characters in the input document are handled | |
| 7262 (@pxref{Inserting Quote Characters}). | |
| 7263 | |
| 7264 | |
| 7265 @node @t{@@kbd} | |
| 6884 @subsection @code{@@kbd}@{@var{keyboard-characters}@} | 7266 @subsection @code{@@kbd}@{@var{keyboard-characters}@} |
| 7267 | |
| 7268 @anchor{kbd}@c old name | |
| 6885 @findex kbd | 7269 @findex kbd |
| 6886 @cindex Keyboard input | 7270 @cindex Keyboard input |
| 6887 | 7271 |
| 6888 Use the @code{@@kbd} command for characters of input to be typed by | 7272 Use the @code{@@kbd} command for characters of input to be typed by |
| 6889 users. For example, to refer to the characters @kbd{M-a}, write: | 7273 users. For example, to refer to the characters @kbd{M-a}, write: |
| 6900 @end example | 7284 @end example |
| 6901 | 7285 |
| 6902 @cindex User input | 7286 @cindex User input |
| 6903 @cindex Slanted typewriter font, for @code{@@kbd} | 7287 @cindex Slanted typewriter font, for @code{@@kbd} |
| 6904 By default, the @code{@@kbd} command produces a different font | 7288 By default, the @code{@@kbd} command produces a different font |
| 6905 (slanted typewriter instead of normal typewriter) in the printed | 7289 (slanted typewriter instead of normal typewriter), |
| 6906 manual, so users can distinguish the characters that they are supposed | 7290 so users can distinguish the characters that they are supposed |
| 6907 to type from those that the computer outputs. | 7291 to type from those that the computer outputs. |
| 6908 | |
| 6909 In Info output, @code{@@kbd} is usually the same as @code{@@code}, | |
| 6910 producing `quotes' around its argument. However, in typewriter-like | |
| 6911 contexts such as the @code{@@example} environment (@pxref{example}) | |
| 6912 and @code{@@code} command itself, the quotes are omitted, since Info | |
| 6913 format cannot use distinguishing fonts. | |
| 6914 | 7292 |
| 6915 @findex kbdinputstyle | 7293 @findex kbdinputstyle |
| 6916 Since the usage of @code{@@kbd} varies from manual to manual, you can | 7294 Since the usage of @code{@@kbd} varies from manual to manual, you can |
| 6917 control the font switching with the @code{@@kbdinputstyle} command. | 7295 control the font switching with the @code{@@kbdinputstyle} command. |
| 6918 This command has no effect on Info output. Write this command at the | 7296 This command has no effect on Info output. Write this command at the |
| 6961 type the characters @kbd{l o g o u t @key{RET}}. | 7339 type the characters @kbd{l o g o u t @key{RET}}. |
| 6962 @end quotation | 7340 @end quotation |
| 6963 | 7341 |
| 6964 (Also, this example shows that you can add spaces for clarity. If you | 7342 (Also, this example shows that you can add spaces for clarity. If you |
| 6965 explicitly want to mention a space character as one of the characters of | 7343 explicitly want to mention a space character as one of the characters of |
| 6966 input, write @kbd{@@key@{SPC@}} for it.)@refill | 7344 input, write @kbd{@@key@{SPC@}} for it.) |
| 6967 | 7345 |
| 6968 | 7346 |
| 6969 @node key | 7347 @node @t{@@key} |
| 6970 @subsection @code{@@key}@{@var{key-name}@} | 7348 @subsection @code{@@key}@{@var{key-name}@} |
| 7349 | |
| 7350 @anchor{key}@c old name | |
| 6971 @findex key | 7351 @findex key |
| 6972 | 7352 |
| 6973 Use the @code{@@key} command for the conventional name for a key on a | 7353 Use the @code{@@key} command for the conventional name for a key on a |
| 6974 keyboard, as in:@refill | 7354 keyboard, as in: |
| 6975 | 7355 |
| 6976 @example | 7356 @example |
| 6977 @@key@{RET@} | 7357 @@key@{RET@} |
| 6978 @end example | 7358 @end example |
| 6979 | 7359 |
| 6980 You can use the @code{@@key} command within the argument of an | 7360 You can use the @code{@@key} command within the argument of an |
| 6981 @code{@@kbd} command when the sequence of characters to be typed | 7361 @code{@@kbd} command when the sequence of characters to be typed |
| 6982 includes one or more keys that are described by name.@refill | 7362 includes one or more keys that are described by name. |
| 6983 | 7363 |
| 6984 For example, to produce @kbd{C-x @key{ESC}} and @kbd{M-@key{TAB}} you | 7364 For example, to produce @kbd{C-x @key{ESC}} and @kbd{M-@key{TAB}} you |
| 6985 would type: | 7365 would type: |
| 6986 | 7366 |
| 6987 @example | 7367 @example |
| 6992 Here is a list of the recommended names for keys: | 7372 Here is a list of the recommended names for keys: |
| 6993 @cindex Recommended names for keys | 7373 @cindex Recommended names for keys |
| 6994 @cindex Keys, recommended names | 7374 @cindex Keys, recommended names |
| 6995 @cindex Names recommended for keys | 7375 @cindex Names recommended for keys |
| 6996 @cindex Abbreviations for keys | 7376 @cindex Abbreviations for keys |
| 7377 @cindex Control keys, specifying | |
| 7378 @cindex Meta keys, specifying | |
| 6997 | 7379 |
| 6998 @quotation | 7380 @quotation |
| 6999 @table @t | 7381 @table @t |
| 7000 @item SPC | 7382 @item SPC |
| 7001 Space | 7383 Space |
| 7032 | 7414 |
| 7033 As a convention in GNU manuals, @code{@@key} should not be used in | 7415 As a convention in GNU manuals, @code{@@key} should not be used in |
| 7034 index entries. | 7416 index entries. |
| 7035 | 7417 |
| 7036 | 7418 |
| 7037 @node samp | 7419 @node @t{@@samp} |
| 7038 @subsection @code{@@samp}@{@var{text}@} | 7420 @subsection @code{@@samp}@{@var{text}@} |
| 7421 | |
| 7422 @anchor{samp}@c old name | |
| 7039 @findex samp | 7423 @findex samp |
| 7040 | 7424 |
| 7041 Use the @code{@@samp} command to indicate text that is a literal example | 7425 Use the @code{@@samp} command to indicate text that is a literal example |
| 7042 or `sample' of a sequence of characters in a file, string, pattern, etc. | 7426 or `sample' of a sequence of characters in a file, string, pattern, etc. |
| 7043 Enclose the text in braces. The argument appears within single | 7427 Enclose the text in braces. The argument appears within single |
| 7044 quotation marks in both the Info file and the printed manual; in | 7428 quotation marks in both the Info file and the printed manual; in |
| 7045 addition, it is printed in a fixed-width font.@refill | 7429 addition, it is printed in a fixed-width font. |
| 7046 | 7430 |
| 7047 @example | 7431 @example |
| 7048 To match @@samp@{foo@} at the end of the line, | 7432 To match @@samp@{foo@} at the end of the line, |
| 7049 use the regexp @@samp@{foo$@}. | 7433 use the regexp @@samp@{foo$@}. |
| 7050 @end example | 7434 @end example |
| 7052 @noindent | 7436 @noindent |
| 7053 produces | 7437 produces |
| 7054 | 7438 |
| 7055 @quotation | 7439 @quotation |
| 7056 To match @samp{foo} at the end of the line, use the regexp | 7440 To match @samp{foo} at the end of the line, use the regexp |
| 7057 @samp{foo$}.@refill | 7441 @samp{foo$}. |
| 7058 @end quotation | 7442 @end quotation |
| 7059 | 7443 |
| 7060 Any time you are referring to single characters, you should use | 7444 Any time you are referring to single characters, you should use |
| 7061 @code{@@samp} unless @code{@@kbd} or @code{@@key} is more appropriate. | 7445 @code{@@samp} unless @code{@@kbd} or @code{@@key} is more appropriate. |
| 7062 Also, you may use @code{@@samp} for entire statements in C and for entire | 7446 Also, you may use @code{@@samp} for entire statements in C and for entire |
| 7063 shell commands---in this case, @code{@@samp} often looks better than | 7447 shell commands---in this case, @code{@@samp} often looks better than |
| 7064 @code{@@code}. Basically, @code{@@samp} is a catchall for whatever is | 7448 @code{@@code}. Basically, @code{@@samp} is a catchall for whatever is |
| 7065 not covered by @code{@@code}, @code{@@kbd}, or @code{@@key}.@refill | 7449 not covered by @code{@@code}, @code{@@kbd}, @code{@@key}, |
| 7450 @code{@@command}, etc. | |
| 7066 | 7451 |
| 7067 Only include punctuation marks within braces if they are part of the | 7452 Only include punctuation marks within braces if they are part of the |
| 7068 string you are specifying. Write punctuation marks outside the braces | 7453 string you are specifying. Write punctuation marks outside the braces |
| 7069 if those punctuation marks are part of the English text that surrounds | 7454 if those punctuation marks are part of the English text that surrounds |
| 7070 the string. In the following sentence, for example, the commas and | 7455 the string. In the following sentence, for example, the commas and |
| 7071 period are outside of the braces:@refill | 7456 period are outside of the braces: |
| 7072 | 7457 |
| 7073 @example | 7458 @example |
| 7074 @group | 7459 @group |
| 7075 In English, the vowels are @@samp@{a@}, @@samp@{e@}, | 7460 In English, the vowels are @@samp@{a@}, @@samp@{e@}, |
| 7076 @@samp@{i@}, @@samp@{o@}, @@samp@{u@}, and sometimes | 7461 @@samp@{i@}, @@samp@{o@}, @@samp@{u@}, and sometimes |
| 7086 @samp{i}, @samp{o}, @samp{u}, and sometimes | 7471 @samp{i}, @samp{o}, @samp{u}, and sometimes |
| 7087 @samp{y}. | 7472 @samp{y}. |
| 7088 @end quotation | 7473 @end quotation |
| 7089 | 7474 |
| 7090 | 7475 |
| 7091 @node verb | 7476 @node @t{@@verb} |
| 7092 @subsection @code{@@verb}@{<char>@var{text}<char>@} | 7477 @subsection @code{@@verb}@{@var{char}@var{text}@var{char}@} |
| 7478 | |
| 7479 @anchor{verb}@c old name | |
| 7093 @findex verb | 7480 @findex verb |
| 7094 @cindex Verbatim in-line text | 7481 @cindex Verbatim in-line text |
| 7095 | 7482 |
| 7096 @cindex Delimiter character, for verbatim | 7483 @cindex Delimiter character, for verbatim |
| 7097 Use the @code{@@verb} command to print a verbatim sequence of | 7484 Use the @code{@@verb} command to print a verbatim sequence of |
| 7101 any unique delimiter character. Enclose the verbatim text, including the | 7488 any unique delimiter character. Enclose the verbatim text, including the |
| 7102 delimiters, in braces. Text is printed in a fixed-width font: | 7489 delimiters, in braces. Text is printed in a fixed-width font: |
| 7103 | 7490 |
| 7104 @example | 7491 @example |
| 7105 How many @@verb@{|@@|@}-escapes does one need to print this | 7492 How many @@verb@{|@@|@}-escapes does one need to print this |
| 7106 @@verb@{.@@a @@b @@c.@} string or @@verb@{+@@'e@?`@!`@{@}\+@} this? | 7493 @@verb@{.@@a @@b.@@c.@} string or @@verb@{+@@'e?`@{@}!`\+@} this? |
| 7107 @end example | 7494 @end example |
| 7108 | 7495 |
| 7109 @noindent | 7496 @noindent |
| 7110 produces | 7497 produces |
| 7111 | 7498 |
| 7112 @example | 7499 @example |
| 7113 How many @verb{|@|}-escapes does one need to print this | 7500 How many @verb{|@|}-escapes does one need to print this |
| 7114 @verb{.@a @b @c.} string or these @verb{+@'e?`{}!`\+} this? | 7501 @verb{.@a @b.@c.} string or @verb{+@'e?`{}!`\+} this? |
| 7115 @end example | 7502 @end example |
| 7116 | 7503 |
| 7117 This is in contrast to @code{@@samp} (see the previous section), | 7504 This is in contrast to @code{@@samp} (see the previous section), |
| 7118 @code{@@code}, and similar commands; in those cases, the argument is | 7505 @code{@@code}, and similar commands; in those cases, the argument is |
| 7119 normal Texinfo text, where the three characters @code{@@@{@}} are | 7506 normal Texinfo text, where the three characters @code{@@@{@}} are |
| 7120 special. With @code{@@verb}, nothing is special except the delimiter | 7507 special, as usual. With @code{@@verb}, nothing is special except the |
| 7121 character you choose. | 7508 delimiter character you choose. |
| 7509 | |
| 7510 The delimiter character itself may appear inside the verbatim text, as | |
| 7511 shown above. As another example, @samp{@@verb@{...@}} prints a single | |
| 7512 (fixed-width) period. | |
| 7122 | 7513 |
| 7123 It is not reliable to use @code{@@verb} inside other Texinfo | 7514 It is not reliable to use @code{@@verb} inside other Texinfo |
| 7124 constructs. In particular, it does not work to use @code{@@verb} in | 7515 constructs. In particular, it does not work to use @code{@@verb} in |
| 7125 anything related to cross-referencing, such as section titles or | 7516 anything related to cross referencing, such as section titles or |
| 7126 figure captions. | 7517 figure captions. |
| 7127 | 7518 |
| 7128 | 7519 |
| 7129 @node var | 7520 @node @t{@@var} |
| 7130 @subsection @code{@@var}@{@var{metasyntactic-variable}@} | 7521 @subsection @code{@@var}@{@var{metasyntactic-variable}@} |
| 7522 | |
| 7523 @anchor{var}@c old name | |
| 7131 @findex var | 7524 @findex var |
| 7132 | 7525 |
| 7133 Use the @code{@@var} command to indicate metasyntactic variables. A | 7526 Use the @code{@@var} command to indicate metasyntactic variables. A |
| 7134 @dfn{metasyntactic variable} is something that stands for another piece of | 7527 @dfn{metasyntactic variable} is something that stands for another |
| 7135 text. For example, you should use a metasyntactic variable in the | 7528 piece of text. For example, you should use a metasyntactic variable |
| 7136 documentation of a function to describe the arguments that are passed | 7529 in the documentation of a function to describe the arguments that are |
| 7137 to that function.@refill | 7530 passed to that function. |
| 7138 | 7531 |
| 7139 Do not use @code{@@var} for the names of particular variables in | 7532 Do not use @code{@@var} for the names of normal variables in computer |
| 7140 programming languages. These are specific names from a program, so | 7533 programs. These are specific names, so @code{@@code} is correct for |
| 7141 @code{@@code} is correct for them (@pxref{code}). For example, the | 7534 them (@t{@@code}). For example, the Emacs Lisp variable |
| 7142 XEmacs Lisp variable @code{texinfo-tex-command} is not a metasyntactic | 7535 @code{texinfo-tex-command} is not a metasyntactic variable; it is |
| 7143 variable; it is properly formatted using @code{@@code}. | 7536 properly formatted using @code{@@code}. |
| 7144 | 7537 |
| 7145 Do not use @code{@@var} for environment variables either; @code{@@env} | 7538 Do not use @code{@@var} for environment variables either; @code{@@env} |
| 7146 is correct for them (see the next section). | 7539 is correct for them (see the next section). |
| 7147 | 7540 |
| 7148 The effect of @code{@@var} in the Info file is to change the case of the | 7541 The effect of @code{@@var} in the Info file is to change the case of |
| 7149 argument to all upper case. In the printed manual and HTML output, the | 7542 the argument to all uppercase. In the printed manual and HTML |
| 7150 argument is printed in slanted type. | 7543 output, the argument is output in slanted type. |
| 7151 | 7544 |
| 7152 @need 700 | 7545 @need 700 |
| 7153 For example, | 7546 For example, |
| 7154 | 7547 |
| 7155 @example | 7548 @example |
| 7164 To delete file @var{filename}, type @samp{rm @var{filename}}. | 7557 To delete file @var{filename}, type @samp{rm @var{filename}}. |
| 7165 @end quotation | 7558 @end quotation |
| 7166 | 7559 |
| 7167 @noindent | 7560 @noindent |
| 7168 (Note that @code{@@var} may appear inside @code{@@code}, | 7561 (Note that @code{@@var} may appear inside @code{@@code}, |
| 7169 @code{@@samp}, @code{@@file}, etc.)@refill | 7562 @code{@@samp}, @code{@@file}, etc.) |
| 7170 | 7563 |
| 7171 Write a metasyntactic variable all in lower case without spaces, and | 7564 Write a metasyntactic variable all in lowercase without spaces, and |
| 7172 use hyphens to make it more readable. Thus, the Texinfo source for | 7565 use hyphens to make it more readable. Thus, the Texinfo source for |
| 7173 the illustration of how to begin a Texinfo manual looks like | 7566 the illustration of how to begin a Texinfo manual looks like |
| 7174 this:@refill | 7567 this: |
| 7175 | 7568 |
| 7176 @example | 7569 @example |
| 7177 @group | 7570 @group |
| 7178 \input texinfo | 7571 \input texinfo |
| 7179 @@@@setfilename @@var@{info-file-name@} | 7572 @@@@setfilename @@var@{info-file-name@} |
| 7191 @@settitle @var{name-of-manual} | 7584 @@settitle @var{name-of-manual} |
| 7192 @end group | 7585 @end group |
| 7193 @end example | 7586 @end example |
| 7194 | 7587 |
| 7195 In some documentation styles, metasyntactic variables are shown with | 7588 In some documentation styles, metasyntactic variables are shown with |
| 7196 angle brackets, for example:@refill | 7589 angle brackets, for example: |
| 7197 | 7590 |
| 7198 @example | 7591 @example |
| 7199 @dots{}, type rm <filename> | 7592 @dots{}, type rm <filename> |
| 7200 @end example | 7593 @end example |
| 7201 | 7594 |
| 7202 @noindent | 7595 @noindent |
| 7203 However, that is not the style that Texinfo uses. (You can, of | 7596 However, that is not the style that Texinfo uses. |
| 7204 course, modify the sources to @file{texinfo.tex} and the Info formatting commands | 7597 |
| 7205 to output the @code{<@dots{}>} format if you wish.)@refill | 7598 @c FIXME add a customization variable? Add an example on how to do that |
| 7206 | 7599 @c for HTML? |
| 7207 | 7600 @c (You can, of course, modify the sources to @file{texinfo.tex} |
| 7208 @node env | 7601 @c and the Info formatting commands |
| 7602 @c to output the @code{<@dots{}>} format if you wish.) | |
| 7603 | |
| 7604 | |
| 7605 @node @t{@@env} | |
| 7209 @subsection @code{@@env}@{@var{environment-variable}@} | 7606 @subsection @code{@@env}@{@var{environment-variable}@} |
| 7607 | |
| 7608 @anchor{env}@c old name | |
| 7210 @findex env | 7609 @findex env |
| 7211 | 7610 |
| 7212 Use the @code{@@env} command to indicate environment variables, as used | 7611 Use the @code{@@env} command to indicate environment variables, as |
| 7213 by many operating systems, including GNU. Do not use it for | 7612 used by many operating systems, including GNU@. Do not use it for |
| 7214 metasyntactic variables; use @code{@@var} instead (see the previous | 7613 @emph{meta}syntactic variables; use @code{@@var} for those (see the |
| 7215 section). | 7614 previous section). |
| 7216 | 7615 |
| 7217 @code{@@env} is equivalent to @code{@@code} in its effects. | 7616 @code{@@env} is equivalent to @code{@@code} in its effects. |
| 7218 For example: | 7617 For example: |
| 7219 | 7618 |
| 7220 @example | 7619 @example |
| 7224 @quotation | 7623 @quotation |
| 7225 The @env{PATH} environment variable @dots{} | 7624 The @env{PATH} environment variable @dots{} |
| 7226 @end quotation | 7625 @end quotation |
| 7227 | 7626 |
| 7228 | 7627 |
| 7229 @node file | 7628 @node @t{@@file} |
| 7230 @subsection @code{@@file}@{@var{file-name}@} | 7629 @subsection @code{@@file}@{@var{file-name}@} |
| 7630 | |
| 7631 @anchor{file}@c old name | |
| 7231 @findex file | 7632 @findex file |
| 7232 | 7633 |
| 7233 Use the @code{@@file} command to indicate text that is the name of a | 7634 Use the @code{@@file} command to indicate text that is the name of a |
| 7234 file, buffer, or directory, or is the name of a node in Info. You can | 7635 file, buffer, or directory, or is the name of a node in Info. You can |
| 7235 also use the command for file name suffixes. Do not use @code{@@file} | 7636 also use the command for file name suffixes. Do not use @code{@@file} |
| 7236 for symbols in a programming language; use @code{@@code}. | 7637 for symbols in a programming language; use @code{@@code}. |
| 7237 | 7638 |
| 7238 Currently, @code{@@file} is equivalent to @code{@@samp} in its effects. | 7639 @code{@@file} is equivalent to @code{code} in its effects. For |
| 7239 For example,@refill | 7640 example, |
| 7240 | 7641 |
| 7241 @example | 7642 @example |
| 7242 The @@file@{.el@} files are in | 7643 The @@file@{.el@} files are in |
| 7243 the @@file@{/usr/local/xemacs/lisp@} directory. | 7644 the @@file@{/usr/local/xemacs/lisp@} directory. |
| 7244 @end example | 7645 @end example |
| 7250 The @file{.el} files are in | 7651 The @file{.el} files are in |
| 7251 the @file{/usr/local/xemacs/lisp} directory. | 7652 the @file{/usr/local/xemacs/lisp} directory. |
| 7252 @end quotation | 7653 @end quotation |
| 7253 | 7654 |
| 7254 | 7655 |
| 7255 @node command | 7656 @node @t{@@command} |
| 7256 @subsection @code{@@command}@{@var{command-name}@} | 7657 @subsection @code{@@command}@{@var{command-name}@} |
| 7658 | |
| 7659 @anchor{command}@c old name | |
| 7257 @findex command | 7660 @findex command |
| 7258 @cindex Command names, indicating | 7661 @cindex Command names, indicating |
| 7259 @cindex Program names, indicating | 7662 @cindex Program names, indicating |
| 7260 | 7663 |
| 7261 Use the @code{@@commannd} command to indicate command names, such as | 7664 Use the @code{@@command} command to indicate command names, such as |
| 7262 @command{ls} or @command{cc}. | 7665 @command{ls} or @command{cc}. |
| 7263 | 7666 |
| 7264 @code{@@command} is equivalent to @code{@@code} in its effects. | 7667 @code{@@command} is equivalent to @code{@@code} in its effects. |
| 7265 For example: | 7668 For example: |
| 7266 | 7669 |
| 7272 The command @command{ls} lists directory contents. | 7675 The command @command{ls} lists directory contents. |
| 7273 @end quotation | 7676 @end quotation |
| 7274 | 7677 |
| 7275 You should write the name of a program in the ordinary text font, rather | 7678 You should write the name of a program in the ordinary text font, rather |
| 7276 than using @code{@@command}, if you regard it as a new English word, | 7679 than using @code{@@command}, if you regard it as a new English word, |
| 7277 such as `XEmacs' or `Bison'. | 7680 such as `Emacs' or `Bison'. |
| 7278 | 7681 |
| 7279 When writing an entire shell command invocation, as in @samp{ls -l}, | 7682 When writing an entire shell command invocation, as in @samp{ls -l}, |
| 7280 you should use either @code{@@samp} or @code{@@code} at your discretion. | 7683 you should use either @code{@@samp} or @code{@@code} at your discretion. |
| 7281 | 7684 |
| 7282 | 7685 |
| 7283 @node option | 7686 @node @t{@@option} |
| 7284 @subsection @code{@@option}@{@var{option-name}@} | 7687 @subsection @code{@@option}@{@var{option-name}@} |
| 7688 | |
| 7689 @anchor{option}@c old name | |
| 7285 @findex option | 7690 @findex option |
| 7286 | 7691 |
| 7287 Use the @code{@@option} command to indicate a command-line option; for | 7692 Use the @code{@@option} command to indicate a command-line option; for |
| 7288 example, @option{-l} or @option{--version} or | 7693 example, @option{-l} or @option{--version} or |
| 7289 @option{--output=@var{filename}}. | 7694 @option{--output=@var{filename}}. |
| 7290 | 7695 |
| 7291 @code{@@option} is equivalent to @code{@@samp} in its effects. | 7696 @code{@@option} is equivalent to @code{@@code} in its effects. |
| 7292 For example: | 7697 For example: |
| 7293 | 7698 |
| 7294 @example | 7699 @example |
| 7295 The option @@option@{-l@} produces a long listing. | 7700 The option @@option@{-l@} produces a long listing. |
| 7296 @end example | 7701 @end example |
| 7297 @noindent produces | 7702 @noindent produces |
| 7298 @quotation | 7703 @quotation |
| 7299 The option @option{-l} produces a long listing. | 7704 The option @option{-l} produces a long listing. |
| 7300 @end quotation | 7705 @end quotation |
| 7301 | 7706 |
| 7302 In tables, putting options inside @code{@@code} produces a | 7707 |
| 7303 more pleasing effect. | 7708 @node @t{@@dfn} |
| 7304 | |
| 7305 @node dfn | |
| 7306 @comment node-name, next, previous, up | |
| 7307 @subsection @code{@@dfn}@{@var{term}@} | 7709 @subsection @code{@@dfn}@{@var{term}@} |
| 7710 | |
| 7711 @anchor{dfn}@c old name | |
| 7308 @findex dfn | 7712 @findex dfn |
| 7309 | 7713 |
| 7310 Use the @code{@@dfn} command to identify the introductory or defining | 7714 Use the @code{@@dfn} command to identify the introductory or defining |
| 7311 use of a technical term. Use the command only in passages whose | 7715 use of a technical term. Use the command only in passages whose |
| 7312 purpose is to introduce a term which will be used again or which the | 7716 purpose is to introduce a term which will be used again or which the |
| 7313 reader ought to know. Mere passing mention of a term for the first | 7717 reader ought to know. Mere passing mention of a term for the first |
| 7314 time does not deserve @code{@@dfn}. The command generates italics in | 7718 time does not deserve @code{@@dfn}. The command generates italics in |
| 7315 the printed manual, and double quotation marks in the Info file. For | 7719 the printed manual, and double quotation marks in the Info file. For |
| 7316 example:@refill | 7720 example: |
| 7317 | 7721 |
| 7318 @example | 7722 @example |
| 7319 Getting rid of a file is called @@dfn@{deleting@} it. | 7723 Getting rid of a file is called @@dfn@{deleting@} it. |
| 7320 @end example | 7724 @end example |
| 7321 | 7725 |
| 7329 As a general rule, a sentence containing the defining occurrence of a | 7733 As a general rule, a sentence containing the defining occurrence of a |
| 7330 term should be a definition of the term. The sentence does not need | 7734 term should be a definition of the term. The sentence does not need |
| 7331 to say explicitly that it is a definition, but it should contain the | 7735 to say explicitly that it is a definition, but it should contain the |
| 7332 information of a definition---it should make the meaning clear. | 7736 information of a definition---it should make the meaning clear. |
| 7333 | 7737 |
| 7334 @ignore | 7738 |
| 7335 @c node ctrl, , cite, Indicating | 7739 @node @t{@@abbr} |
| 7336 @comment node-name, next, previous, up | |
| 7337 @c subsection @code{@@ctrl}@{@var{ctrl-char}@} | |
| 7338 @findex ctrl | |
| 7339 | |
| 7340 The @code{@@ctrl} command is seldom used. It describes an ASCII | |
| 7341 control character by inserting the actual character into the Info | |
| 7342 file. | |
| 7343 | |
| 7344 Usually, in Texinfo, you talk what you type as keyboard entry by | |
| 7345 describing it with @code{@@kbd}: thus, @samp{@@kbd@{C-a@}} for | |
| 7346 @kbd{C-a}. Use @code{@@kbd} in this way when talking about a control | |
| 7347 character that is typed on the keyboard by the user. When talking | |
| 7348 about a control character appearing in a file or a string, do not use | |
| 7349 @code{@@kbd} since the control character is not typed. Also, do not | |
| 7350 use @samp{C-} but spell out @code{control-}, as in @samp{control-a}, | |
| 7351 to make it easier for a reader to understand.@refill | |
| 7352 | |
| 7353 @code{@@ctrl} is an idea from the beginnings of Texinfo which may not | |
| 7354 really fit in to the scheme of things. But there may be times when | |
| 7355 you want to use the command. The pattern is | |
| 7356 @code{@@ctrl@{@var{ch}@}}, where @var{ch} is an ASCII character | |
| 7357 whose control-equivalent is wanted. For example, to specify | |
| 7358 @samp{control-f}, you would enter@refill | |
| 7359 | |
| 7360 @example | |
| 7361 @@ctrl@{f@} | |
| 7362 @end example | |
| 7363 | |
| 7364 @noindent | |
| 7365 produces | |
| 7366 | |
| 7367 @quotation | |
| 7368 @ctrl{f} | |
| 7369 @end quotation | |
| 7370 | |
| 7371 In the Info file, this generates the specified control character, output | |
| 7372 literally into the file. This is done so a user can copy the specified | |
| 7373 control character (along with whatever else he or she wants) into another | |
| 7374 XEmacs buffer and use it. Since the `control-h',`control-i', and | |
| 7375 `control-j' characters are formatting characters, they should not be | |
| 7376 indicated with @code{@@ctrl}.@refill | |
| 7377 | |
| 7378 In a printed manual, @code{@@ctrl} generates text to describe or | |
| 7379 identify that control character: an uparrow followed by the character | |
| 7380 @var{ch}.@refill | |
| 7381 @end ignore | |
| 7382 | |
| 7383 | |
| 7384 @node abbr | |
| 7385 @subsection @code{@@abbr}@{@var{abbreviation}[, @var{meaning}]@} | 7740 @subsection @code{@@abbr}@{@var{abbreviation}[, @var{meaning}]@} |
| 7741 | |
| 7742 @anchor{abbr}@c old name | |
| 7386 @findex abbr | 7743 @findex abbr |
| 7387 | 7744 |
| 7388 @cindex Abbreviations, tagging | 7745 @cindex Abbreviations, tagging |
| 7389 You can use the @code{@@abbr} command for general abbreviations. The | 7746 You can use the @code{@@abbr} command for general abbreviations. The |
| 7390 abbreviation is given as the single argument in braces, as in | 7747 abbreviation is given as the single argument in braces, as in |
| 7395 @code{@@abbr} accepts an optional second argument, intended to be used | 7752 @code{@@abbr} accepts an optional second argument, intended to be used |
| 7396 for the meaning of the abbreviation. | 7753 for the meaning of the abbreviation. |
| 7397 | 7754 |
| 7398 If the abbreviation ends with a lowercase letter and a period, and is | 7755 If the abbreviation ends with a lowercase letter and a period, and is |
| 7399 not at the end of a sentence, and has no second argument, remember to | 7756 not at the end of a sentence, and has no second argument, remember to |
| 7400 use the @code{@@.} command (@pxref{Not Ending a | 7757 use the @code{@@.} command (@pxref{Ending a Sentence}) to get the |
| 7401 Sentence}) to get the correct spacing. However, you do not have to | 7758 correct spacing. However, you do not have to use @code{@@.} within |
| 7402 use @code{@@.} within the abbreviation itself; Texinfo automatically | 7759 the abbreviation itself; Texinfo automatically assumes periods within |
| 7403 assumes periods within the abbreviation do not end a sentence. | 7760 the abbreviation do not end a sentence. |
| 7404 | 7761 |
| 7405 @cindex <abbr> and <abbrev> tags | 7762 @cindex @code{<abbr>} and @code{<abbrev>} tags |
| 7406 In @TeX{} and in the Info output, the first argument is printed as-is; | 7763 In @TeX{} and in the Info output, the first argument is printed as-is; |
| 7407 if the second argument is present, it is printed in parentheses after | 7764 if the second argument is present, it is printed in parentheses after |
| 7408 the abbreviation. In HTML and XML, the @code{<abbr>} tag is | 7765 the abbreviation. In HTML the @code{<abbr>} tag is used; in Docbook, |
| 7409 used; in Docbook, the @code{<abbrev>} tag is used. For instance: | 7766 the @code{<abbrev>} tag is used. For instance: |
| 7410 | 7767 |
| 7411 @example | 7768 @example |
| 7412 @@abbr@{Comput. J., Computer Journal@} | 7769 @@abbr@{Comput. J., Computer Journal@} |
| 7413 @end example | 7770 @end example |
| 7414 | 7771 |
| 7421 For abbreviations consisting of all capital letters, you may prefer to | 7778 For abbreviations consisting of all capital letters, you may prefer to |
| 7422 use the @code{@@acronym} command instead. See the next section for | 7779 use the @code{@@acronym} command instead. See the next section for |
| 7423 more on the usage of these two commands. | 7780 more on the usage of these two commands. |
| 7424 | 7781 |
| 7425 | 7782 |
| 7426 @node acronym | 7783 @node @t{@@acronym} |
| 7427 @subsection @code{@@acronym}@{@var{acronym}[, @var{meaning}]@} | 7784 @subsection @code{@@acronym}@{@var{acronym}[, @var{meaning}]@} |
| 7785 | |
| 7786 @anchor{acronym}@c old name | |
| 7428 @findex acronym | 7787 @findex acronym |
| 7429 | 7788 |
| 7430 @cindex NASA, as acronym | 7789 @cindex NASA, as acronym |
| 7431 @cindex Acronyms, tagging | 7790 @cindex Acronyms, tagging |
| 7432 Use the @code{@@acronym} command for abbreviations written in all | 7791 You can use the @code{@@acronym} command for abbreviations written in |
| 7433 capital letters, such as `@acronym{NASA}'. The abbreviation is given as | 7792 all capital letters, such as `@acronym{NASA}'. The abbreviation is |
| 7434 the single argument in braces, as in @samp{@@acronym@{NASA@}}. As | 7793 given as the single argument in braces, as in |
| 7435 a matter of style, or for particular acronyms, you may prefer to | 7794 @samp{@@acronym@{NASA@}}. As a matter of style, or for particular |
| 7436 use periods, as in @samp{@@acronym@{N.A.S.A.@}}. | 7795 acronyms, you may prefer to use periods, as in |
| 7796 @samp{@@acronym@{N.A.S.A.@}}. | |
| 7437 | 7797 |
| 7438 @code{@@acronym} accepts an optional second argument, intended to be | 7798 @code{@@acronym} accepts an optional second argument, intended to be |
| 7439 used for the meaning of the acronym. | 7799 used for the meaning of the acronym. |
| 7440 | 7800 |
| 7441 If the acronym is at the end of a sentence, and if there is no second | 7801 If the acronym is at the end of a sentence, and if there is no second |
| 7442 argument, remember to use the @code{@@.} or similar command | 7802 argument, remember to use the @code{@@.} or similar command |
| 7443 (@pxref{Ending a Sentence}) to get the correct spacing. | 7803 (@pxref{Ending a Sentence}) to get the correct spacing. |
| 7444 | 7804 |
| 7445 @cindex <acronym> tag | 7805 @cindex @code{<acronym>} tag |
| 7446 In @TeX{}, the acronym is printed in slightly smaller font. In the | 7806 In @TeX{}, the acronym is printed in slightly smaller font. In the |
| 7447 Info output, the argument is printed as-is. In either format, if the | 7807 Info output, the argument is printed as-is. In either format, if the |
| 7448 second argument is present, it is printed in parentheses after the | 7808 second argument is present, it is printed in parentheses after the |
| 7449 acronym. In HTML, Docbook, and XML, the @code{<acronym>} tag is | 7809 acronym. In HTML and Docbook the @code{<acronym>} tag is used. |
| 7450 used. | |
| 7451 | 7810 |
| 7452 For instance (since GNU is a recursive acronym, we use | 7811 For instance (since GNU is a recursive acronym, we use |
| 7453 @code{@@acronym} recursively): | 7812 @code{@@acronym} recursively): |
| 7454 | 7813 |
| 7455 @example | 7814 @example |
| 7472 possibly give a meaning. When choosing whether to use these two | 7831 possibly give a meaning. When choosing whether to use these two |
| 7473 commands, please bear the following in mind. | 7832 commands, please bear the following in mind. |
| 7474 | 7833 |
| 7475 @itemize @minus | 7834 @itemize @minus |
| 7476 @item | 7835 @item |
| 7477 In standard English usage, acronyms are a subset of abbreviations: | 7836 In common English usage, acronyms are a subset of abbreviations: they |
| 7478 they include pronounceable words like `@acronym{NATO}', `radar', and | 7837 include pronounceable words like `@acronym{NATO}', `radar', and |
| 7479 `snafu', and some sources also include syllable acronyms like | 7838 `snafu'; some sources also include syllable acronyms like |
| 7480 `Usenet', hybrids like `@acronym{SIGGRAPH}', and unpronounceable | 7839 `Usenet', hybrids like `@acronym{SIGGRAPH}', and unpronounceable |
| 7481 initialisms like `@acronym{FBI}'. | 7840 initialisms like `@acronym{FBI}'. |
| 7482 | 7841 |
| 7483 @item | 7842 @item |
| 7484 In Texinfo, an acronym (but not an abbreviation) should consist only | 7843 In Texinfo, an acronym (but not an abbreviation) should consist only |
| 7491 @item | 7850 @item |
| 7492 Some browsers place a dotted bottom border under abbreviations but not | 7851 Some browsers place a dotted bottom border under abbreviations but not |
| 7493 acronyms. | 7852 acronyms. |
| 7494 | 7853 |
| 7495 @item | 7854 @item |
| 7496 It's not essential to use either of these commands for all | 7855 It usually turns out to be quite difficult and/or time-consuming to |
| 7856 consistently use @code{@@acronym} for all sequences of uppercase | |
| 7857 letters. Furthermore, it looks strange for some acronyms to be in the | |
| 7858 normal font size and others to be smaller. Thus, a simpler approach | |
| 7859 you may wish to consider is to avoid @code{@@acronym} and just typeset | |
| 7860 everything as normal text in all capitals: @samp{GNU}, producing the | |
| 7861 output `GNU'. | |
| 7862 | |
| 7863 @item | |
| 7864 In general, it's not essential to use either of these commands for all | |
| 7497 abbreviations; use your judgment. Text is perfectly readable without | 7865 abbreviations; use your judgment. Text is perfectly readable without |
| 7498 them. | 7866 them. |
| 7499 | |
| 7500 @end itemize | 7867 @end itemize |
| 7501 | 7868 |
| 7502 | 7869 |
| 7503 @node indicateurl | 7870 @node @t{@@indicateurl} |
| 7504 @subsection @code{@@indicateurl}@{@var{uniform-resource-locator}@} | 7871 @subsection @code{@@indicateurl}@{@var{uniform-resource-locator}@} |
| 7872 | |
| 7873 @anchor{indicateurl}@c old name | |
| 7505 @findex indicateurl | 7874 @findex indicateurl |
| 7506 @cindex Uniform resource locator, indicating | 7875 @cindex Uniform resource locator, indicating |
| 7507 @cindex URL, indicating | 7876 @cindex URL, indicating |
| 7508 | 7877 |
| 7509 Use the @code{@@indicateurl} command to indicate a uniform resource | 7878 Use the @code{@@indicateurl} command to indicate a uniform resource |
| 7510 locator on the World Wide Web. This is analogous to @code{@@file}, | 7879 locator on the World Wide Web. This is purely for markup purposes and |
| 7511 @code{@@var}, etc., and is purely for markup purposes. It does not | 7880 does not produce a link you can follow (use the @code{@@url} or |
| 7512 produce a link you can follow in HTML output (use the @code{@@uref} | 7881 @code{@@uref} command for that, @pxref{@t{@@url}}). |
| 7513 command for that, @pxref{uref,, @code{@@uref}}). It is useful for | 7882 @code{@@indicateurl} is useful for urls which do not actually exist. |
| 7514 url's which do not actually exist. For example: | 7883 For example: |
| 7515 | 7884 |
| 7516 @example | 7885 @example |
| 7517 For example, the url might be @@indicateurl@{http://example.org/path@}. | 7886 For example, the url might be @@indicateurl@{http://example.org/path@}. |
| 7518 @end example | 7887 @end example |
| 7519 | 7888 |
| 7521 | 7890 |
| 7522 @display | 7891 @display |
| 7523 For example, the url might be @indicateurl{http://example.org/path}. | 7892 For example, the url might be @indicateurl{http://example.org/path}. |
| 7524 @end display | 7893 @end display |
| 7525 | 7894 |
| 7526 | 7895 The output from @code{@@indicateurl} is more or less like that of |
| 7527 @node email | 7896 @code{@@samp} (@pxref{@t{@@samp}}). |
| 7897 | |
| 7898 | |
| 7899 @node @t{@@email} | |
| 7528 @subsection @code{@@email}@{@var{email-address}[, @var{displayed-text}]@} | 7900 @subsection @code{@@email}@{@var{email-address}[, @var{displayed-text}]@} |
| 7901 | |
| 7902 @anchor{email}@c old name | |
| 7529 @findex email | 7903 @findex email |
| 7530 | 7904 |
| 7531 Use the @code{@@email} command to indicate an electronic mail address. | 7905 Use the @code{@@email} command to indicate an electronic mail address. |
| 7532 It takes one mandatory argument, the address, and one optional argument, the | 7906 It takes one mandatory argument, the address, and one optional argument, the |
| 7533 text to display (the default is the address itself). | 7907 text to display (the default is the address itself). |
| 7540 | 7914 |
| 7541 @example | 7915 @example |
| 7542 Send bug reports to @@email@{bug-texinfo@@@@gnu.org@}, | 7916 Send bug reports to @@email@{bug-texinfo@@@@gnu.org@}, |
| 7543 suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}. | 7917 suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}. |
| 7544 @end example | 7918 @end example |
| 7919 | |
| 7545 @noindent produces | 7920 @noindent produces |
| 7921 | |
| 7546 @display | 7922 @display |
| 7547 Send bug reports to @email{bug-texinfo@@gnu.org}, | 7923 Send bug reports to @email{bug-texinfo@@gnu.org}, |
| 7548 suggestions to the @email{bug-texinfo@@gnu.org, same place}. | 7924 suggestions to the @email{bug-texinfo@@gnu.org, same place}. |
| 7549 @end display | 7925 @end display |
| 7550 | 7926 |
| 7551 | 7927 |
| 7552 @node Emphasis | 7928 @node Emphasis |
| 7553 @section Emphasizing Text | 7929 @section Emphasizing Text |
| 7554 @cindex Emphasizing text | 7930 @cindex Emphasizing text |
| 7555 | 7931 |
| 7556 Usually, Texinfo changes the font to mark words in the text according to | 7932 Usually, Texinfo changes the font to mark words in the text according |
| 7557 what category the words belong to; an example is the @code{@@code} command. | 7933 to the category the words belong to; an example is the @code{@@code} |
| 7558 Most often, this is the best way to mark words. | 7934 command. Most often, this is the best way to mark words. However, |
| 7559 However, sometimes you will want to emphasize text without indicating a | 7935 sometimes you will want to emphasize text without indicating a |
| 7560 category. Texinfo has two commands to do this. Also, Texinfo has | 7936 category. Texinfo has two commands to do this. Also, Texinfo has |
| 7561 several commands that specify the font in which @TeX{} will typeset | 7937 several commands that specify the font in which text will be output. |
| 7562 text. These commands have no effect on Info and only one of them, | 7938 These commands have no effect in Info and only one of them, the |
| 7563 the @code{@@r} command, has any regular use.@refill | 7939 @code{@@r} command, has any regular use. |
| 7564 | 7940 |
| 7565 @menu | 7941 @menu |
| 7566 * emph & strong:: How to emphasize text in Texinfo. | 7942 * @t{@@emph @@strong}:: How to emphasize text in Texinfo. |
| 7567 * Smallcaps:: How to use the small caps font. | 7943 * Smallcaps:: How to use the small caps font. |
| 7568 * Fonts:: Various font commands for printed output. | 7944 * Fonts:: Various font commands for printed output. |
| 7569 @end menu | 7945 @end menu |
| 7570 | 7946 |
| 7571 @node emph & strong | 7947 |
| 7948 @node @t{@@emph @@strong} | |
| 7572 @subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@} | 7949 @subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@} |
| 7573 @cindex Emphasizing text, font for | 7950 |
| 7951 @anchor{emph & strong}@c oldname | |
| 7574 @findex emph | 7952 @findex emph |
| 7575 @findex strong | 7953 @findex strong |
| 7954 @cindex Emphasizing text, font for | |
| 7576 | 7955 |
| 7577 The @code{@@emph} and @code{@@strong} commands are for emphasis; | 7956 The @code{@@emph} and @code{@@strong} commands are for emphasis; |
| 7578 @code{@@strong} is stronger. In printed output, @code{@@emph} produces | 7957 @code{@@strong} is stronger. In printed output, @code{@@emph} produces |
| 7579 @emph{italics} and @code{@@strong} produces @strong{bold}. | 7958 @emph{italics} and @code{@@strong} produces @strong{bold}. |
| 7959 In the Info output, @code{@@emph} surrounds the text with underscores | |
| 7960 (@samp{_}), and @code{@@strong} puts asterisks around the text. | |
| 7580 | 7961 |
| 7581 For example, | 7962 For example, |
| 7582 | 7963 |
| 7583 @example | 7964 @example |
| 7584 @group | 7965 @group |
| 7585 @@strong@{Caution:@} @@samp@{rm * .[^.]*@} | 7966 @@strong@{Caution:@} @@samp@{rm *@} |
| 7586 removes @@emph@{all@} files in the directory. | 7967 removes @@emph@{all@} normal files. |
| 7587 @end group | 7968 @end group |
| 7588 @end example | 7969 @end example |
| 7589 | 7970 |
| 7590 @noindent | 7971 @noindent |
| 7591 produces the following in printed output and HTML: | 7972 produces the following: |
| 7592 | 7973 |
| 7593 @quotation | 7974 @quotation |
| 7594 @strong{Caution}: @samp{rm * .[^.]*} | 7975 @strong{Caution}: @samp{rm * .[^.]*} |
| 7595 removes @emph{all} files in the directory. | 7976 removes @emph{all} normal files. |
| 7596 @end quotation | 7977 @end quotation |
| 7597 | |
| 7598 @noindent | |
| 7599 and the following in Info: | |
| 7600 | |
| 7601 @example | |
| 7602 *Caution:* `rm * .[^.]*' removes _all_ | |
| 7603 files in the directory. | |
| 7604 @end example | |
| 7605 | 7978 |
| 7606 The @code{@@strong} command is seldom used except to mark what is, in | 7979 The @code{@@strong} command is seldom used except to mark what is, in |
| 7607 effect, a typographical element, such as the word `Caution' in the | 7980 effect, a typographical element, such as the word `Caution' in the |
| 7608 preceding example. | 7981 preceding example. |
| 7609 | 7982 |
| 7610 In the Info output, @code{@@emph} surrounds the text with underscores | |
| 7611 (@samp{_}), and @code{@@strong} puts asterisks around the text. | |
| 7612 | |
| 7613 @quotation Caution | 7983 @quotation Caution |
| 7614 Do not use @code{@@strong} with the word @samp{Note}; Info will | 7984 Do not use @code{@@strong} with the word @samp{Note} followed by a |
| 7615 mistake the combination for a cross reference. (It's usually | 7985 space; Info will mistake the combination for a cross reference. Use a |
| 7616 redundant, anyway.) Use a phrase such as @strong{Please notice} or | 7986 phrase such as @strong{Please notice} or @strong{Caution} instead, or |
| 7617 @strong{Caution} instead, or the optional argument to | 7987 the optional argument to @code{@@quotation}---@samp{Note} is allowable |
| 7618 @code{@@quotation}---@samp{Note} is allowable there. | 7988 there. |
| 7619 @end quotation | 7989 @end quotation |
| 7620 | 7990 |
| 7621 | 7991 |
| 7622 @node Smallcaps | 7992 @node Smallcaps |
| 7623 @subsection @code{@@sc}@{@var{text}@}: The Small Caps Font | 7993 @subsection @code{@@sc}@{@var{text}@}: The Small Caps Font |
| 7624 @cindex Small caps font | 7994 @cindex Small caps font |
| 7625 @findex sc @r{(small caps font)} | 7995 @findex sc @r{(small caps font)} |
| 7626 | 7996 |
| 7627 Use the @samp{@@sc} command to set text in @sc{a small caps font} | 7997 Use the @samp{@@sc} command to set text in @sc{a small caps font} |
| 7628 (where possible). Write the text you want to be in small caps between | 7998 (where possible). Write the text you want to be in small caps between |
| 7629 braces in lower case, like this: | 7999 braces in lowercase, like this: |
| 7630 | 8000 |
| 7631 @example | 8001 @example |
| 7632 Richard @@sc@{Stallman@} founded @@acronym@{GNU@}. | 8002 Richard @@sc@{Stallman@} commenc@'{e} GNU. |
| 7633 @end example | 8003 @end example |
| 7634 | 8004 |
| 7635 @noindent | 8005 @noindent |
| 7636 This produces: | 8006 This produces: |
| 7637 | 8007 |
| 7638 @display | 8008 @display |
| 7639 Richard @sc{Stallman} founded @acronym{GNU}. | 8009 Richard @sc{Stallman} commenc@'{e} GNU. |
| 7640 @end display | 8010 @end display |
| 7641 | 8011 |
| 7642 As shown here, we recommend using @code{@@acronym} for actual | 8012 As shown here, we recommend reserving @code{@@sc} for special cases |
| 7643 acronyms (@pxref{acronym}), and reserving @code{@@sc} for special | 8013 where you want typographic small caps; family names are one such, |
| 7644 cases where you want small caps. The output is not the same | 8014 especially in languages other than English, though there are no |
| 7645 (@code{@@acronym} prints in a smaller text font, not the small caps | 8015 hard-and-fast rules about such things. |
| 7646 font), but more importantly it describes the actual text more | 8016 |
| 7647 accurately. | 8017 @cindex @code{<small>} tag |
| 7648 | |
| 7649 Family names are one case where small capitals are sometimes desirable, | |
| 7650 also as shown here. | |
| 7651 | |
| 7652 @cindex <small> tag | |
| 7653 @TeX{} typesets any uppercase letters between the braces of an | 8018 @TeX{} typesets any uppercase letters between the braces of an |
| 7654 @code{@@sc} command in full-size capitals; only lowercase letters are | 8019 @code{@@sc} command in full-size capitals; only lowercase letters are |
| 7655 printed in the small caps font. In the Info output, the argument to | 8020 printed in the small caps font. In the Info output, the argument to |
| 7656 @code{@@sc} is printed in all upper case. In HTML, the argument is | 8021 @code{@@sc} is printed in all uppercase. In HTML, the argument is |
| 7657 uppercased and the output marked with the @code{<small>} tag to reduce | 8022 uppercased and the output marked with the @code{<small>} tag to reduce |
| 7658 the font size. | 8023 the font size, since HTML cannot easily represent true small caps. |
| 7659 | 8024 |
| 7660 Since it's redundant to mark all-uppercase text with @code{@@sc}, | 8025 Overall, we recommend using standard upper- and lowercase letters |
| 7661 @command{makeinfo} warns about such usage. | 8026 wherever possible. |
| 7662 | |
| 7663 We recommend using regular mixed case wherever possible. | |
| 7664 | 8027 |
| 7665 | 8028 |
| 7666 @node Fonts | 8029 @node Fonts |
| 7667 @subsection Fonts for Printing, Not Info | 8030 @subsection Fonts for Printing |
| 7668 @cindex Fonts for printing, not Info | 8031 @cindex Fonts for printing |
| 7669 | 8032 |
| 7670 @findex fonttextsize | 8033 @findex fonttextsize |
| 7671 @cindex Font size, reducing | 8034 @cindex Font size, reducing |
| 7672 @cindex Reducing font size | 8035 @cindex Reducing font size |
| 7673 @cindex Smaller fonts | 8036 @cindex Smaller fonts |
| 7674 Texinfo provides one command to change the size of the main body font | 8037 Texinfo provides one command to change the size of the main body font |
| 7675 in the @TeX{} output for a document: @code{@@fonttextsize}. It has no | 8038 in the @TeX{} output for a document: @code{@@fonttextsize}. It has no |
| 7676 effect at all in other output. It takes a single argument on the | 8039 effect in other output. It takes a single argument on the remainder |
| 7677 remainder of the line, which must be either @samp{10} or @samp{11}. | 8040 of the line, which must be either @samp{10} or @samp{11}. For |
| 7678 For example: | 8041 example: |
| 7679 | 8042 |
| 7680 @example | 8043 @example |
| 7681 @@fonttextsize 10 | 8044 @@fonttextsize 10 |
| 7682 @end example | 8045 @end example |
| 7683 | 8046 |
| 7684 @cindex Printing cost, reducing | 8047 @cindex Printing cost, reducing |
| 7685 The effect is to reduce the body font to a 10@dmn{pt} size (the | 8048 The effect is to reduce the body font to a 10@dmn{pt} size (the |
| 7686 default is 11@dmn{pt}). Fonts for other elements, such as sections | 8049 default is 11@dmn{pt}). Fonts for other elements, such as sections |
| 7687 and chapters, are reduced accordingly. This should only be used in | 8050 and chapters, are reduced accordingly. This should only be used in |
| 7688 conjunction with @code{@@smallbook} (@pxref{smallbook,,Printing | 8051 conjunction with @code{@@smallbook} (@pxref{@t{@@smallbook}}) or |
| 7689 ``Small'' Books}) or similar, since 10@dmn{pt} fonts on standard paper | 8052 similar, since 10@dmn{pt} fonts on standard paper (8.5x11 or A4) are |
| 7690 (8.5x11 or A4) are too small. One reason to use this command is to | 8053 too small. One reason to use this command is to save pages, and hence |
| 7691 save pages, and hence printing cost, for physical books. | 8054 printing cost, for physical books. |
| 7692 | 8055 |
| 7693 Texinfo does not at present have commands to switch the font family | 8056 Texinfo does not at present have commands to switch the font family |
| 7694 to use, or more general size-changing commands. | 8057 to use, or more general size-changing commands. |
| 7695 | 8058 |
| 7696 @cindex Styles, font | 8059 Texinfo also provides a number of font commands that specify font |
| 7697 Texinfo also provides a number of font commands that specify font changes | 8060 changes in the printed manual and (where possible) in the HTML output. |
| 7698 in the printed manual and (where possible) in the HTML output, but | 8061 They have no effect in Info. All the commands apply to a following |
| 7699 have no effect in the Info file. All the commands apply to an | 8062 argument surrounded by braces. |
| 7700 argument that follows, surrounded by braces. | |
| 7701 | 8063 |
| 7702 @table @code | 8064 @table @code |
| 7703 @item @@b | 8065 @item @@b |
| 7704 @findex b @r{(bold font)} | 8066 @findex b @r{(bold font)} |
| 7705 @cindex Bold font | 8067 @cindex Bold font |
| 7737 | 8099 |
| 7738 @end table | 8100 @end table |
| 7739 | 8101 |
| 7740 (The commands with longer names were invented much later than the | 8102 (The commands with longer names were invented much later than the |
| 7741 others, at which time it did not seem desirable to use very short | 8103 others, at which time it did not seem desirable to use very short |
| 7742 names for such an infrequently needed feature.) | 8104 names for such infrequently needed features.) |
| 7743 | 8105 |
| 7744 @cindex <lineannotation> Docbook tag | 8106 @cindex <lineannotation> Docbook tag |
| 7745 Only the @code{@@r} command has much use: in example-like | 8107 The @code{@@r} command can be useful in example-like environments, to |
| 7746 environments, you can use the @code{@@r} command to write comments in | 8108 write comments in the standard roman font instead of the fixed-width |
| 7747 the standard roman font instead of the fixed-width font. This looks | 8109 font. This looks better in printed output, and produces a |
| 7748 better in printed output, and produces a @code{<lineannotation>} tag | 8110 @code{<lineannotation>} tag in Docbook output. |
| 7749 in Docbook output. | |
| 7750 | 8111 |
| 7751 For example, | 8112 For example, |
| 7752 | 8113 |
| 7753 @example | 8114 @example |
| 7754 @group | 8115 @group |
| 7763 | 8124 |
| 7764 @lisp | 8125 @lisp |
| 7765 (+ 2 2) ; @r{Add two plus two.} | 8126 (+ 2 2) ; @r{Add two plus two.} |
| 7766 @end lisp | 8127 @end lisp |
| 7767 | 8128 |
| 7768 In general, you should avoid using the other font commands. Some of | 8129 The @code{@@t} command can occasionally be useful to produce output in |
| 7769 them are only useful when documenting functionality of specific font | 8130 a typewriter font where that is supported (e.g., HTML and PDF), but no |
| 7770 effects, such as in @TeX{} and related packages. | 8131 distinction is needed in Info or plain text: @code{@@t@{foo@}} |
| 8132 produces @t{foo}, cf. @code{@@code@{foo@}} producing @code{foo}. | |
| 8133 | |
| 8134 For example, we use @code{@@t} in the @code{@@node} commands for this | |
| 8135 manual to specify the Texinfo command names, because the quotes which | |
| 8136 @code{@@code} outputs look extraneous in that particular context. | |
| 8137 | |
| 8138 In general, the other font commands are unlikely to be useful; they | |
| 8139 exist primarily to make it possible to document the functionality of | |
| 8140 specific font effects, such as in @TeX{} and related packages. | |
| 7771 | 8141 |
| 7772 | 8142 |
| 7773 @node Quotations and Examples | 8143 @node Quotations and Examples |
| 7774 @chapter Quotations and Examples | 8144 @chapter Quotations and Examples |
| 7775 | 8145 |
| 7779 | 8149 |
| 7780 @findex end | 8150 @findex end |
| 7781 In Texinfo, you always begin a quotation or example by writing an | 8151 In Texinfo, you always begin a quotation or example by writing an |
| 7782 @@-command at the beginning of a line by itself, and end it by writing | 8152 @@-command at the beginning of a line by itself, and end it by writing |
| 7783 an @code{@@end} command that is also at the beginning of a line by | 8153 an @code{@@end} command that is also at the beginning of a line by |
| 7784 itself. For instance, you begin an example by writing @code{@@example} | 8154 itself. For instance, you begin an example by writing |
| 7785 by itself at the beginning of a line and end the example by writing | 8155 @code{@@example} by itself at the beginning of a line and end the |
| 7786 @code{@@end example} on a line by itself, at the beginning of that | 8156 example by writing @code{@@end example} on a line by itself, at the |
| 7787 line, and with only one space between the @code{@@end} and the | 8157 beginning of that line, and with only one space between the |
| 7788 @code{example}. | 8158 @code{@@end} and the @code{example}. |
| 7789 | 8159 |
| 7790 @menu | 8160 @menu |
| 7791 * Block Enclosing Commands:: Different constructs for different purposes. | 8161 * Block Enclosing Commands:: Different constructs for different purposes. |
| 7792 * quotation:: Writing a quotation. | 8162 * @t{@@quotation}:: Writing a quotation. |
| 7793 * example:: Writing an example in a fixed-width font. | 8163 * @t{@@indentedblock}:: Block of text indented on left. |
| 7794 * verbatim:: Writing a verbatim example. | 8164 * @t{@@example}:: Writing an example in a fixed-width font. |
| 7795 * verbatiminclude:: Including a file verbatim. | 8165 * @t{@@verbatim}:: Writing a verbatim example. |
| 7796 * lisp:: Illustrating Lisp code. | 8166 * @t{@@verbatiminclude}:: Including a file verbatim. |
| 7797 * small:: Examples in a smaller font. | 8167 * @t{@@lisp}:: Illustrating Lisp code. |
| 7798 * display:: Writing an example in the current font. | 8168 * @t{@@small@dots{}}:: Examples in a smaller font. |
| 7799 * format:: Writing an example without narrowed margins. | 8169 * @t{@@display}:: Writing an example in the current font. |
| 7800 * exdent:: Undo indentation on a line. | 8170 * @t{@@format}:: Writing an example without narrowed margins. |
| 7801 * flushleft & flushright:: Pushing text flush left or flush right. | 8171 * @t{@@exdent}:: Undo indentation on a line. |
| 7802 * noindent:: Preventing paragraph indentation. | 8172 * @t{@@flushleft @@flushright}:: Pushing text flush left or flush right. |
| 7803 * indent:: Forcing paragraph indentation. | 8173 * @t{@@raggedright}:: Avoiding justification on the right. |
| 7804 * cartouche:: Drawing rounded rectangles around examples. | 8174 * @t{@@noindent}:: Preventing paragraph indentation. |
| 8175 * @t{@@indent}:: Forcing paragraph indentation. | |
| 8176 * @t{@@cartouche}:: Drawing rounded rectangles around text. | |
| 7805 @end menu | 8177 @end menu |
| 7806 | 8178 |
| 7807 | 8179 |
| 7808 @node Block Enclosing Commands | 8180 @node Block Enclosing Commands |
| 7809 @section Block Enclosing Commands | 8181 @section Block Enclosing Commands |
| 7810 | 8182 |
| 7811 Here are commands for quotations and examples, explained further in the | 8183 Here is a summary of commands that enclose blocks of text, also known |
| 7812 following sections: | 8184 as @dfn{environments}. They're explained further in the following |
| 8185 sections. | |
| 7813 | 8186 |
| 7814 @table @code | 8187 @table @code |
| 7815 @item @@quotation | 8188 @item @@quotation |
| 7816 Indicate text that is quoted. The text is filled, indented (from both | 8189 Indicate text that is quoted. The text is filled, indented (from both |
| 7817 margins), and printed in a roman font by default. | 8190 margins), and printed in a roman font by default. |
| 7818 | 8191 |
| 8192 @item @@indentedblock | |
| 8193 Like @code{@@quotation}, but the text is indented only on the left. | |
| 8194 | |
| 7819 @item @@example | 8195 @item @@example |
| 7820 Illustrate code, commands, and the like. The text is printed | 8196 Illustrate code, commands, and the like. The text is printed |
| 7821 in a fixed-width font, and indented but not filled. | 8197 in a fixed-width font, and indented but not filled. |
| 8198 | |
| 8199 @item @@lisp | |
| 8200 Like @code{@@example}, but specifically for illustrating Lisp code. The | |
| 8201 text is printed in a fixed-width font, and indented but not filled. | |
| 7822 | 8202 |
| 7823 @item @@verbatim | 8203 @item @@verbatim |
| 7824 Mark a piece of text that is to be printed verbatim; no character | 8204 Mark a piece of text that is to be printed verbatim; no character |
| 7825 substitutions are made and all commands are ignored, until the next | 8205 substitutions are made and all commands are ignored, until the next |
| 7826 @code{@@end verbatim}. The text is printed in a fixed-width font, | 8206 @code{@@end verbatim}. The text is printed in a fixed-width font, |
| 7827 and not indented or filled. Extra spaces and blank lines are | 8207 and not indented or filled. Extra spaces and blank lines are |
| 7828 significant, and tabs are expanded. | 8208 significant, and tabs are expanded. |
| 7829 | 8209 |
| 7830 @item @@smallexample | |
| 7831 Same as @code{@@example}, except that in @TeX{} this command typesets | |
| 7832 text in a smaller font. | |
| 7833 | |
| 7834 @item @@lisp | |
| 7835 Like @code{@@example}, but specifically for illustrating Lisp code. The | |
| 7836 text is printed in a fixed-width font, and indented but not filled. | |
| 7837 | |
| 7838 @item @@smalllisp | |
| 7839 Is to @code{@@lisp} as @code{@@smallexample} is to @code{@@example}. | |
| 7840 | |
| 7841 @item @@display | 8210 @item @@display |
| 7842 Display illustrative text. The text is indented but not filled, and | 8211 Display illustrative text. The text is indented but not filled, and |
| 7843 no font is selected (so, by default, the font is roman).@refill | 8212 no font is selected (so, by default, the font is roman). |
| 7844 | |
| 7845 @item @@smalldisplay | |
| 7846 Is to @code{@@display} as @code{@@smallexample} is to @code{@@example}. | |
| 7847 | 8213 |
| 7848 @item @@format | 8214 @item @@format |
| 7849 Like @code{@@display} (the text is not filled and no font is selected), | 8215 Like @code{@@display} (the text is not filled and no font is |
| 7850 but the text is not indented. | 8216 selected), but the text is not indented. |
| 7851 | 8217 |
| 7852 @item @@smallformat | 8218 @item @@smallquotation |
| 7853 Is to @code{@@format} as @code{@@smallexample} is to @code{@@example}. | 8219 @itemx @@smallindentedblock |
| 8220 @itemx @@smallexample | |
| 8221 @itemx @@smalllisp | |
| 8222 @itemx @@smalldisplay | |
| 8223 @itemx @@smallformat | |
| 8224 These @code{@@small...} commands are just like their non-small | |
| 8225 counterparts, except that they output text in a smaller font size, | |
| 8226 where possible. | |
| 8227 | |
| 8228 @item @@flushleft | |
| 8229 @itemx @@flushright | |
| 8230 Text is not filled, but is set flush with the left or right margin, | |
| 8231 respectively. | |
| 8232 | |
| 8233 @item @@raggedright | |
| 8234 Text is filled, but only justified on the left, leaving the right | |
| 8235 margin ragged. | |
| 8236 | |
| 8237 @item @@cartouche | |
| 8238 Highlight text, often an example or quotation, by drawing a box with | |
| 8239 rounded corners around it. | |
| 7854 @end table | 8240 @end table |
| 7855 | 8241 |
| 7856 The @code{@@exdent} command is used within the above constructs to | 8242 The @code{@@exdent} command is used within the above constructs to |
| 7857 undo the indentation of a line. | 8243 undo the indentation of a line. |
| 7858 | 8244 |
| 7859 The @code{@@flushleft} and @code{@@flushright} commands are used to line | |
| 7860 up the left or right margins of unfilled text.@refill | |
| 7861 | |
| 7862 The @code{@@noindent} command may be used after one of the above | 8245 The @code{@@noindent} command may be used after one of the above |
| 7863 constructs to prevent the following text from being indented as a new | 8246 constructs (or anywhere) to prevent the following text from being |
| 7864 paragraph. | 8247 indented as a new paragraph. |
| 7865 | 8248 |
| 7866 You can use the @code{@@cartouche} environment around one of the above | 8249 |
| 7867 constructs to highlight the example or quotation by drawing a box with | 8250 @node @t{@@quotation} |
| 7868 rounded corners around it. @xref{cartouche, , Drawing Cartouches Around | 8251 @section @code{@@quotation}: Block Quotations |
| 7869 Examples}. | 8252 @anchor{quotation}@c old name |
| 7870 | 8253 |
| 7871 | |
| 7872 @node quotation | |
| 7873 @section @code{@@quotation}: Block quotations | |
| 7874 @cindex Quotations | 8254 @cindex Quotations |
| 7875 @findex quotation | 8255 @findex quotation |
| 7876 | 8256 |
| 7877 The text of a quotation is processed normally (regular font, text is | 8257 The text of a quotation is processed like normal text (regular font, |
| 7878 filled) except that: | 8258 text is filled) except that: |
| 7879 | 8259 |
| 7880 @itemize @bullet | 8260 @itemize @bullet |
| 7881 @item | 8261 @item |
| 7882 the margins are closer to the center of the page, so the whole of the | 8262 both the left and right margins are closer to the center of the page, |
| 7883 quotation is indented; | 8263 so the whole of the quotation is indented; |
| 7884 | 8264 |
| 7885 @item | 8265 @item |
| 7886 and the first lines of paragraphs are indented no more than other lines. | 8266 the first lines of paragraphs are indented no more than other lines; and |
| 7887 | 8267 |
| 8268 @item | |
| 8269 an @code{@@author} command may be given to specify the author of the | |
| 8270 quotation. | |
| 7888 @end itemize | 8271 @end itemize |
| 7889 | 8272 |
| 7890 @quotation | 8273 @quotation |
| 7891 This is an example of text written between an @code{@@quotation} | 8274 This is an example of text written between an @code{@@quotation} |
| 7892 command and an @code{@@end quotation} command. An @code{@@quotation} | 8275 command and an @code{@@end quotation} command. An @code{@@quotation} |
| 7918 @quotation Note | 8301 @quotation Note |
| 7919 This is | 8302 This is |
| 7920 a foo. | 8303 a foo. |
| 7921 @end quotation | 8304 @end quotation |
| 7922 | 8305 |
| 7923 If the @code{@@quotation} argument is exactly one of these words: | 8306 If the @code{@@quotation} argument is one of these English words |
| 8307 (case-insensitive): | |
| 7924 | 8308 |
| 7925 @example | 8309 @example |
| 7926 Caution Important Note Tip Warning | 8310 Caution Important Note Tip Warning |
| 7927 @end example | 8311 @end example |
| 7928 | 8312 |
| 7929 @cindex <note> Docbook tag | 8313 @cindex @code{<caution>} Docbook tag |
| 7930 @cindex <blockquote> HTML tag | 8314 @cindex @code{<important>} Docbook tag |
| 8315 @cindex @code{<note>} Docbook tag | |
| 8316 @cindex @code{<tip>} Docbook tag | |
| 8317 @cindex @code{<warning>} Docbook tag | |
| 8318 @cindex @code{<blockquote>} HTML tag | |
| 7931 @noindent then the Docbook output uses corresponding special tags | 8319 @noindent then the Docbook output uses corresponding special tags |
| 7932 (@code{<note>}, etc.) instead of the default @code{<blockquote>}. | 8320 (@code{<note>}, etc.)@: instead of the default @code{<blockquote>}. |
| 7933 HTML output always uses @code{<blockquote>}. | 8321 HTML output always uses @code{<blockquote>}. |
| 7934 | 8322 |
| 7935 | 8323 If the author of the quotation is specified in the @code{@@quotation} |
| 7936 @node example | 8324 block with the @code{@@author} command, a line with the author name is |
| 8325 displayed after the quotation: | |
| 8326 | |
| 8327 @example | |
| 8328 @@quotation | |
| 8329 People sometimes ask me if it is a sin in the Church of Emacs to use | |
| 8330 vi. Using a free version of vi is not a sin; it is a penance. So happy | |
| 8331 hacking. | |
| 8332 | |
| 8333 @@author Richard Stallman | |
| 8334 @@end quotation | |
| 8335 @end example | |
| 8336 | |
| 8337 @noindent | |
| 8338 produces | |
| 8339 | |
| 8340 @quotation | |
| 8341 People sometimes ask me if it is a sin in the Church of Emacs to use | |
| 8342 vi. Using a free version of vi is not a sin; it is a penance. So happy | |
| 8343 hacking. | |
| 8344 | |
| 8345 @author Richard Stallman | |
| 8346 @end quotation | |
| 8347 | |
| 8348 @findex smallquotation | |
| 8349 Texinfo also provides a command @code{@@smallquotation}, which is just | |
| 8350 like @code{@@quotation} but uses a smaller font size where possible. | |
| 8351 @xref{@t{@@small@dots{}}}. | |
| 8352 | |
| 8353 | |
| 8354 @node @t{@@indentedblock} | |
| 8355 @section @code{@@indentedblock}: Indented text blocks | |
| 8356 @cindex Indented text block | |
| 8357 @findex indentedblock | |
| 8358 | |
| 8359 The @code{@@indentedblock} environment is similar to | |
| 8360 @code{@@quotation}, except that text is only indented on the left (and | |
| 8361 there is no optional argument for an author). Thus, the text font | |
| 8362 remains unchanged, and text is gathered and filled as usual, but the | |
| 8363 left margin is increased. For example: | |
| 8364 | |
| 8365 @indentedblock | |
| 8366 This is an example of text written between an @code{@@indentedblock} | |
| 8367 command and an @code{@@end indentedblock} command. The | |
| 8368 @code{@@indentedblock} environment can contain any text or other | |
| 8369 commands desired. | |
| 8370 @end indentedblock | |
| 8371 | |
| 8372 This is written in the Texinfo source as: | |
| 8373 | |
| 8374 @example | |
| 8375 @@indentedblock | |
| 8376 This is an example ... | |
| 8377 @@end indentedblock | |
| 8378 @end example | |
| 8379 | |
| 8380 @findex smallindentedblock | |
| 8381 Texinfo also provides a command @code{@@smallindentedblock}, which is | |
| 8382 just like @code{@@indentedblock} but uses a smaller font size where | |
| 8383 possible. @xref{@t{@@small@dots{}}}. | |
| 8384 | |
| 8385 | |
| 8386 @node @t{@@example} | |
| 7937 @section @code{@@example}: Example Text | 8387 @section @code{@@example}: Example Text |
| 8388 | |
| 8389 @anchor{example}@c old name | |
| 8390 @findex example | |
| 7938 @cindex Examples, formatting them | 8391 @cindex Examples, formatting them |
| 7939 @cindex Formatting examples | 8392 @cindex Formatting examples |
| 7940 @findex example | |
| 7941 | 8393 |
| 7942 The @code{@@example} environment is used to indicate an example that | 8394 The @code{@@example} environment is used to indicate an example that |
| 7943 is not part of the running text, such as computer input or output. | 8395 is not part of the running text, such as computer input or output. |
| 7944 Write an @code{@@example} command at the beginning of a line by | 8396 Write an @code{@@example} command at the beginning of a line by |
| 7945 itself. Mark the end of the example with an @code{@@end example} | 8397 itself. Mark the end of the example with an @code{@@end example} |
| 7953 @item Extra spaces and blank lines are significant. | 8405 @item Extra spaces and blank lines are significant. |
| 7954 @item The output is indented. | 8406 @item The output is indented. |
| 7955 @item The output uses a fixed-width font. | 8407 @item The output uses a fixed-width font. |
| 7956 @item Texinfo commands @emph{are} expanded; if you want the output to | 8408 @item Texinfo commands @emph{are} expanded; if you want the output to |
| 7957 be the input verbatim, use the @code{@@verbatim} environment instead | 8409 be the input verbatim, use the @code{@@verbatim} environment instead |
| 7958 (@pxref{verbatim,,@code{@@verbatim}}). | 8410 (@pxref{@t{@@verbatim}}). |
| 7959 @end itemize | 8411 @end itemize |
| 7960 | 8412 |
| 7961 For example, | 8413 For example, |
| 7962 | 8414 |
| 7963 @example | 8415 @example |
| 7991 | 8443 |
| 7992 Examples are often, logically speaking, ``in the middle'' of a | 8444 Examples are often, logically speaking, ``in the middle'' of a |
| 7993 paragraph, and the text that continues afterwards should not be | 8445 paragraph, and the text that continues afterwards should not be |
| 7994 indented, as in the example above. The @code{@@noindent} command | 8446 indented, as in the example above. The @code{@@noindent} command |
| 7995 prevents a piece of text from being indented as if it were a new | 8447 prevents a piece of text from being indented as if it were a new |
| 7996 paragraph (@pxref{noindent,,@code{@@noindent}}. | 8448 paragraph (@pxref{@t{@@noindent}}. |
| 7997 | 8449 |
| 7998 If you want to embed code fragments within sentences, instead of | 8450 If you want to embed code fragments within sentences, instead of |
| 7999 displaying them, use the @code{@@code} command or its relatives | 8451 displaying them, use the @code{@@code} command or its relatives |
| 8000 (@pxref{code,,@code{@@code}}). | 8452 (@pxref{@t{@@code}}). |
| 8001 | 8453 |
| 8002 If you wish to write a ``comment'' on a line of an example in the | 8454 If you wish to write a ``comment'' on a line of an example in the |
| 8003 normal roman font, you can use the @code{@@r} command (@pxref{Fonts}). | 8455 normal roman font, you can use the @code{@@r} command (@pxref{Fonts}). |
| 8004 | 8456 |
| 8005 | 8457 |
| 8006 @node verbatim | 8458 @node @t{@@verbatim} |
| 8007 @section @code{@@verbatim}: Literal Text | 8459 @section @code{@@verbatim}: Literal Text |
| 8460 | |
| 8461 @anchor{verbatim}@c old name | |
| 8008 @findex verbatim | 8462 @findex verbatim |
| 8009 @cindex Verbatim environment | 8463 @cindex Verbatim environment |
| 8010 | 8464 |
| 8011 Use the @code{@@verbatim} environment for printing of text that may | 8465 Use the @code{@@verbatim} environment for printing of text that may |
| 8012 contain special characters or commands that should not be interpreted, | 8466 contain special characters or commands that should not be interpreted, |
| 8017 In general, the output will be just the same as the input. No | 8471 In general, the output will be just the same as the input. No |
| 8018 character substitutions are made, e.g., all spaces and blank lines are | 8472 character substitutions are made, e.g., all spaces and blank lines are |
| 8019 significant, including tabs. In the printed manual, the text is | 8473 significant, including tabs. In the printed manual, the text is |
| 8020 typeset in a fixed-width font, and not indented or filled. | 8474 typeset in a fixed-width font, and not indented or filled. |
| 8021 | 8475 |
| 8022 Write a @code{@@verbatim} command at the beginning of a line by itself. | 8476 Write an @code{@@verbatim} command at the beginning of a line by |
| 8023 This line will disappear from the output. Mark the end of the verbatim | 8477 itself. This line will disappear from the output. Mark the end of |
| 8024 block with a @code{@@end verbatim} command, also written at the | 8478 the verbatim block with an @code{@@end verbatim} command, also written |
| 8025 beginning of a line by itself. The @code{@@end verbatim} will also | 8479 at the beginning of a line by itself. The @code{@@end verbatim} will |
| 8026 disappear from the output. | 8480 also disappear from the output. |
| 8027 | 8481 |
| 8028 For example: | 8482 For example: |
| 8029 @c oops, got to trick this a bit: can't use @end verbatim inside @verbatim | 8483 @c oops, got to trick this a bit: can't use @end verbatim inside @verbatim |
| 8030 | 8484 |
| 8031 @example | 8485 @example |
| 8069 | 8523 |
| 8070 Finally, a word of warning: it is not reliable to use | 8524 Finally, a word of warning: it is not reliable to use |
| 8071 @code{@@verbatim} inside other Texinfo constructs. | 8525 @code{@@verbatim} inside other Texinfo constructs. |
| 8072 | 8526 |
| 8073 | 8527 |
| 8074 @node verbatiminclude | 8528 @node @t{@@verbatiminclude} |
| 8075 @section @code{@@verbatiminclude} @var{file}: Include a File Verbatim | 8529 @section @code{@@verbatiminclude} @var{file}: Include a File Verbatim |
| 8530 | |
| 8531 @anchor{verbatiminclude}@c old name | |
| 8532 @findex verbatiminclude | |
| 8076 @cindex Verbatim, include file | 8533 @cindex Verbatim, include file |
| 8077 @cindex Including a file verbatim | 8534 @cindex Including a file verbatim |
| 8078 @findex verbatiminclude | |
| 8079 | 8535 |
| 8080 You can include the exact contents of a file in the document with the | 8536 You can include the exact contents of a file in the document with the |
| 8081 @code{@@verbatiminclude} command: | 8537 @code{@@verbatiminclude} command: |
| 8082 | 8538 |
| 8083 @example | 8539 @example |
| 8084 @@verbatiminclude @var{filename} | 8540 @@verbatiminclude @var{filename} |
| 8085 @end example | 8541 @end example |
| 8086 | 8542 |
| 8087 The contents of @var{filename} is printed in a verbatim environment | 8543 The contents of @var{filename} is printed in a verbatim environment |
| 8088 (@pxref{verbatim,,@code{@@verbatim}}). Generally, the file is printed | 8544 (@pxref{@t{@@verbatim}}). Generally, the file is printed exactly |
| 8089 exactly as it is, with all special characters and white space | 8545 as it is, with all special characters and white space retained. No |
| 8090 retained. No indentation is added; if you want indentation, enclose | 8546 indentation is added; if you want indentation, enclose the |
| 8091 the @code{@@verbatiminclude} within @code{@@example} | 8547 @code{@@verbatiminclude} within @code{@@example} |
| 8092 (@pxref{example,,@code{@@example}}). | 8548 (@pxref{@t{@@example}}). |
| 8093 | 8549 |
| 8094 The name of the file is taken literally, with a single exception: | 8550 The name of the file is taken literally, with a single exception: |
| 8095 @code{@@value@{@var{var}@}} references are expanded. This makes it | 8551 @code{@@value@{@var{var}@}} references are expanded. This makes it |
| 8096 possible to include files in other directories within a distribution, | 8552 possible to include files in other directories within a distribution, |
| 8097 for instance: | 8553 for instance: |
| 8105 | 8561 |
| 8106 For a method on printing the file contents in a smaller font size, see | 8562 For a method on printing the file contents in a smaller font size, see |
| 8107 the end of the previous section on @code{@@verbatim}. | 8563 the end of the previous section on @code{@@verbatim}. |
| 8108 | 8564 |
| 8109 | 8565 |
| 8110 @node lisp | 8566 @node @t{@@lisp} |
| 8111 @section @code{@@lisp}: Marking a Lisp Example | 8567 @section @code{@@lisp}: Marking a Lisp Example |
| 8568 | |
| 8569 @anchor{lisp}@c old name | |
| 8112 @findex lisp | 8570 @findex lisp |
| 8113 @cindex Lisp example | 8571 @cindex Lisp example |
| 8114 | 8572 |
| 8115 The @code{@@lisp} command is used for Lisp code. It is synonymous | 8573 The @code{@@lisp} command is used for Lisp code. It is synonymous |
| 8116 with the @code{@@example} command. | 8574 with the @code{@@example} command. |
| 8129 | 8587 |
| 8130 Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by | 8588 Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by |
| 8131 itself. | 8589 itself. |
| 8132 | 8590 |
| 8133 | 8591 |
| 8134 @node small | 8592 @node @t{@@small@dots{}} |
| 8135 @section @code{@@small@dots{}} Block Commands | 8593 @section @code{@@small@dots{}} Block Commands |
| 8136 @cindex Small examples | 8594 |
| 8137 @cindex Examples in smaller fonts | 8595 @anchor{small}@c old name |
| 8138 @cindex Lisp examples in smaller fonts | |
| 8139 @findex smalldisplay | |
| 8140 @findex smallexample | 8596 @findex smallexample |
| 8141 @findex smallformat | 8597 @findex smallformat |
| 8142 @findex smalllisp | 8598 @findex smalllisp |
| 8143 | 8599 @findex smallquotation |
| 8144 In addition to the regular @code{@@example} and @code{@@lisp} commands, | 8600 @cindex Small examples |
| 8601 @cindex Examples in smaller fonts | |
| 8602 @cindex Quotations in smaller fonts | |
| 8603 @cindex Lisp examples in smaller fonts | |
| 8604 | |
| 8605 In addition to the regular @code{@@example} and similar commands, | |
| 8145 Texinfo has ``small'' example-style commands. These are | 8606 Texinfo has ``small'' example-style commands. These are |
| 8146 @code{@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat}, and | 8607 @code{@@smallquotation}, @code{@@smallindentedblock}, |
| 8147 @code{@@smalllisp}. | 8608 @code{@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat}, |
| 8148 | 8609 and @code{@@smalllisp}. |
| 8149 In Info, the @code{@@small@dots{}} commands are equivalent to their | 8610 |
| 8150 non-small companion commands. | 8611 In Info output, the @code{@@small@dots{}} commands are equivalent to |
| 8612 their non-small companion commands. | |
| 8151 | 8613 |
| 8152 In @TeX{}, however, the @code{@@small@dots{}} commands typeset text in | 8614 In @TeX{}, however, the @code{@@small@dots{}} commands typeset text in |
| 8153 a smaller font than the non-small example commands. Consequently, | 8615 a smaller font than the non-small example commands. Thus, for |
| 8154 many examples containing long lines fit on a page without needing to | 8616 instance, code examples can contain longer lines and still fit on a |
| 8155 be shortened. | 8617 page without needing to be rewritten. |
| 8618 | |
| 8619 A smaller font size is also requested in HTML output, and (as usual) | |
| 8620 retained in the Texinfo@tie{}XML transliteration. | |
| 8156 | 8621 |
| 8157 Mark the end of an @code{@@small@dots{}} block with a corresponding | 8622 Mark the end of an @code{@@small@dots{}} block with a corresponding |
| 8158 @code{@@end small@dots{}}. For example, pair @code{@@smallexample} with | 8623 @code{@@end small@dots{}}. For example, pair @code{@@smallexample} with |
| 8159 @code{@@end smallexample}. | 8624 @code{@@end smallexample}. |
| 8160 | 8625 |
| 8161 Here is an example of the font used by the @code{@@small@dots{}} | 8626 Here is an example of the font used by the @code{@@smallexample} |
| 8162 commands (in Info, the output will be the same as usual): | 8627 command (in Info, the output will be the same as usual): |
| 8163 | 8628 |
| 8164 @smallexample | 8629 @smallexample |
| 8165 @dots{} to make sure that you have the freedom to | 8630 @dots{} to make sure that you have the freedom to |
| 8166 distribute copies of free software (and charge for | 8631 distribute copies of free software (and charge for |
| 8167 this service if you wish), that you receive source | 8632 this service if you wish), that you receive source |
| 8168 code or can get it if you want it, that you can | 8633 code or can get it if you want it, that you can |
| 8169 change the software or use pieces of it in new free | 8634 change the software or use pieces of it in new free |
| 8170 programs; and that you know you can do these things. | 8635 programs; and that you know you can do these things. |
| 8171 @end smallexample | 8636 @end smallexample |
| 8172 | 8637 |
| 8173 The @code{@@small@dots{}} commands make it easier to prepare manuals | 8638 The @code{@@small@dots{}} commands use the same font style as their |
| 8174 without forcing you to edit examples by hand to fit them onto narrower | 8639 normal counterparts: @code{@@smallexample} and @code{@@smalllisp} use |
| 8175 pages. | 8640 a fixed-width font, and everything else uses the regular font. |
| 8176 | 8641 They also have the same behavior in other respects---whether filling |
| 8177 As a general rule, a printed document looks much better if you use | 8642 is done and whether margins are narrowed. |
| 8178 only one of (for instance) @code{@@example} or @code{@@smallexample} | 8643 |
| 8644 As a general rule, a printed document looks better if you use only one | |
| 8645 of (for instance) @code{@@example} or @code{@@smallexample} | |
| 8179 consistently within a chapter. | 8646 consistently within a chapter. |
| 8180 | 8647 |
| 8181 | 8648 |
| 8182 @node display | 8649 @node @t{@@display} |
| 8183 @section @code{@@display} and @code{@@smalldisplay} | 8650 @section @code{@@display}: Examples Using the Text Font |
| 8651 | |
| 8652 @anchor{display}@c old name | |
| 8653 @findex display | |
| 8184 @cindex Display formatting | 8654 @cindex Display formatting |
| 8185 @findex display | 8655 |
| 8186 | 8656 The @code{@@display} command begins another kind of environment, where |
| 8187 The @code{@@display} command begins a kind of example, where each line | 8657 the font is left unchanged, not switched to typewriter as with |
| 8188 of input produces a line of output, and the output is indented. It is | 8658 @code{@@example}. Each line of input still produces a line of output, |
| 8189 thus like the @code{@@example} command except that, in a printed | 8659 and the output is still indented. |
| 8190 manual, @code{@@display} does not select the fixed-width font. In | |
| 8191 fact, it does not specify the font at all, so that the text appears in | |
| 8192 the same font it would have appeared in without the @code{@@display} | |
| 8193 command. | |
| 8194 | 8660 |
| 8195 @display | 8661 @display |
| 8196 This is an example of text written between an @code{@@display} command | 8662 This is an example of text written between an @code{@@display} command |
| 8197 and an @code{@@end display} command. The @code{@@display} command | 8663 and an @code{@@end display} command. The @code{@@display} command |
| 8198 indents the text, but does not fill it. | 8664 indents the text, but does not fill it. |
| 8199 @end display | 8665 @end display |
| 8200 | 8666 |
| 8201 @findex smalldisplay | 8667 @findex smalldisplay |
| 8202 Texinfo also provides a command @code{@@smalldisplay}, which is like | 8668 Texinfo also provides the environment @code{@@smalldisplay}, which is |
| 8203 @code{@@display} but uses a smaller font in @code{@@smallbook} format. | 8669 like @code{@@display} but uses a smaller font size. |
| 8204 @xref{small}. | 8670 @xref{@t{@@small@dots{}}}. |
| 8205 | 8671 |
| 8206 The @code{@@table} command (@pxref{table}) does not work inside | 8672 The @code{@@table} command (@pxref{@t{@@table}}) is not supported |
| 8207 @code{@@display}. Since @code{@@display} is line-oriented, it doesn't | 8673 inside @code{@@display}. Since @code{@@display} is line-oriented, it |
| 8208 make sense to use them together. If you want to indent a table, try | 8674 doesn't make sense to use them together. If you want to indent a |
| 8209 @code{@@quotation} (@pxref{quotation}). | 8675 table, try @code{@@quotation} (@pxref{@t{@@quotation}}) or |
| 8210 | 8676 @code{@@indentedblock} (@pxref{@t{@@indentedblock}}). |
| 8211 | 8677 |
| 8212 @node format | 8678 |
| 8213 @section @code{@@format} and @code{@@smallformat} | 8679 @node @t{@@format} |
| 8680 @section @code{@@format}: Examples Using the Full Line Width | |
| 8681 | |
| 8682 @anchor{format}@c old name | |
| 8214 @findex format | 8683 @findex format |
| 8215 | 8684 |
| 8216 The @code{@@format} command is similar to @code{@@example} except | 8685 The @code{@@format} command is similar to @code{@@display}, except it |
| 8217 that, in the printed manual, @code{@@format} does not select the | 8686 leaves the text unindented. Like @code{@@display}, it does not select |
| 8218 fixed-width font and does not narrow the margins. | 8687 the fixed-width font. |
| 8219 | 8688 |
| 8220 @format | 8689 @format |
| 8221 This is an example of text written between an @code{@@format} command | 8690 This is an example of text written between an @code{@@format} command |
| 8222 and an @code{@@end format} command. As you can see | 8691 and an @code{@@end format} command. As you can see |
| 8223 from this example, | 8692 from this example, |
| 8224 the @code{@@format} command does not fill the text. | 8693 the @code{@@format} command does not fill the text. |
| 8225 @end format | 8694 @end format |
| 8226 | 8695 |
| 8227 @findex smallformat | 8696 @findex smallformat |
| 8228 Texinfo also provides a command @code{@@smallformat}, which is like | 8697 Texinfo also provides the environment @code{@@smallformat}, which is |
| 8229 @code{@@format} but uses a smaller font in @code{@@smallbook} format. | 8698 like @code{@@format} but uses a smaller font size. |
| 8230 @xref{small}. | 8699 @xref{@t{@@small@dots{}}}. |
| 8231 | 8700 |
| 8232 | 8701 |
| 8233 | 8702 @node @t{@@exdent} |
| 8234 @node exdent | |
| 8235 @section @code{@@exdent}: Undoing a Line's Indentation | 8703 @section @code{@@exdent}: Undoing a Line's Indentation |
| 8704 | |
| 8705 @anchor{exdent}@c old name | |
| 8706 @findex exdent | |
| 8236 @cindex Indentation undoing | 8707 @cindex Indentation undoing |
| 8237 @findex exdent | |
| 8238 | 8708 |
| 8239 The @code{@@exdent} command removes any indentation a line might have. | 8709 The @code{@@exdent} command removes any indentation a line might have. |
| 8240 The command is written at the beginning of a line and applies only to | 8710 The command is written at the beginning of a line and applies only to |
| 8241 the text that follows the command that is on the same line. Do not use | 8711 the text that follows the command that is on the same line. Do not use |
| 8242 braces around the text. In a printed manual, the text on an | 8712 braces around the text. In a printed manual, the text on an |
| 8243 @code{@@exdent} line is printed in the roman font.@refill | 8713 @code{@@exdent} line is printed in the roman font. |
| 8244 | 8714 |
| 8245 @code{@@exdent} is usually used within examples. Thus,@refill | 8715 @code{@@exdent} is usually used within examples. Thus, |
| 8246 | 8716 |
| 8247 @example | 8717 @example |
| 8248 @group | 8718 @group |
| 8249 @@example | 8719 @@example |
| 8250 This line follows an @@@@example command. | 8720 This line follows an @@@@example command. |
| 8265 This line follows the exdented line. | 8735 This line follows the exdented line. |
| 8266 The @@end example comes on the next line. | 8736 The @@end example comes on the next line. |
| 8267 @end group | 8737 @end group |
| 8268 @end example | 8738 @end example |
| 8269 | 8739 |
| 8270 In practice, the @code{@@exdent} command is rarely used. | 8740 In practice, the @code{@@exdent} command is rarely used. Usually, you |
| 8271 Usually, you un-indent text by ending the example and | 8741 un-indent text by ending the example and returning the page to its |
| 8272 returning the page to its normal width.@refill | 8742 normal width. |
| 8273 | 8743 |
| 8274 | 8744 @code{@@exdent} has no effect in HTML output. |
| 8275 @node flushleft & flushright | 8745 |
| 8746 | |
| 8747 @node @t{@@flushleft @@flushright} | |
| 8276 @section @code{@@flushleft} and @code{@@flushright} | 8748 @section @code{@@flushleft} and @code{@@flushright} |
| 8749 | |
| 8750 @anchor{flushleft & flushright}@c old name | |
| 8277 @findex flushleft | 8751 @findex flushleft |
| 8278 @findex flushright | 8752 @findex flushright |
| 8279 @cindex Ragged right | 8753 @cindex Ragged right, without filling |
| 8280 @cindex Ragged left | 8754 @cindex Ragged left, without filling |
| 8281 | 8755 |
| 8282 The @code{@@flushleft} and @code{@@flushright} commands line up the | 8756 The @code{@@flushleft} and @code{@@flushright} commands line up the |
| 8283 ends of lines on the left and right margins of a page, | 8757 ends of lines on the left and right margins of a page, |
| 8284 but do not fill the text. The commands are written on lines of their | 8758 but do not fill the text. The commands are written on lines of their |
| 8285 own, without braces. The @code{@@flushleft} and @code{@@flushright} | 8759 own, without braces. The @code{@@flushleft} and @code{@@flushright} |
| 8286 commands are ended by @code{@@end flushleft} and @code{@@end | 8760 commands are ended by @code{@@end flushleft} and @code{@@end |
| 8287 flushright} commands on lines of their own.@refill | 8761 flushright} commands on lines of their own. |
| 8288 | 8762 |
| 8289 @need 1500 | 8763 @need 1500 |
| 8290 For example, | 8764 For example, |
| 8291 | 8765 |
| 8292 @example | 8766 @example |
| 8332 right justifies every line but leaves the | 8806 right justifies every line but leaves the |
| 8333 left end ragged. | 8807 left end ragged. |
| 8334 @end flushright | 8808 @end flushright |
| 8335 | 8809 |
| 8336 | 8810 |
| 8337 @node noindent | 8811 @node @t{@@raggedright} |
| 8812 @section @code{@@raggedright}: Ragged Right Text | |
| 8813 | |
| 8814 @anchor{raggedright}@c old name | |
| 8815 @findex raggedright | |
| 8816 @cindex Ragged right, with filling | |
| 8817 | |
| 8818 The @code{@@raggedright} fills text as usual, but the text is only | |
| 8819 justified on the left; the right margin is ragged. The command is | |
| 8820 written on a line of its own, without braces. The | |
| 8821 @code{@@raggedright} command is ended by @code{@@end raggedright} on a | |
| 8822 line of its own. This command has no effect in Info and HTML output, | |
| 8823 where text is always set ragged right. | |
| 8824 | |
| 8825 The @code{@@raggedright} command can be useful with paragraphs | |
| 8826 containing lists of commands with long names, when it is known in | |
| 8827 advance that justifying the text on both margins will make the | |
| 8828 paragraph look bad. | |
| 8829 | |
| 8830 For example, | |
| 8831 | |
| 8832 @example | |
| 8833 @group | |
| 8834 @@raggedright | |
| 8835 Commands for double and single angle quotation marks: | |
| 8836 @@code@{@@@@guillemetleft@@@{@@@}@}, @@code@{@@@@guillemetright@@@{@@@}@}, | |
| 8837 @@code@{@@@@guillemotleft@@@{@@@}@}, @@code@{@@@@guillemotright@@@{@@@}@}, | |
| 8838 @@code@{@@@@guilsinglleft@@@{@@@}@}, @@code@{@@@@guilsinglright@@@{@@@}@}. | |
| 8839 @@end raggedright | |
| 8840 @end group | |
| 8841 @end example | |
| 8842 | |
| 8843 @noindent | |
| 8844 produces | |
| 8845 | |
| 8846 @raggedright | |
| 8847 Commands for double and single angle quotation marks: | |
| 8848 @code{@@guillemetleft@{@}}, @code{@@guillemetright@{@}}, | |
| 8849 @code{@@guillemotleft@{@}}, @code{@@guillemotright@{@}}, | |
| 8850 @code{@@guilsinglleft@{@}}, @code{@@guilsinglright@{@}}. | |
| 8851 @end raggedright | |
| 8852 | |
| 8853 | |
| 8854 @node @t{@@noindent} | |
| 8338 @section @code{@@noindent}: Omitting Indentation | 8855 @section @code{@@noindent}: Omitting Indentation |
| 8856 | |
| 8857 @anchor{noindent}@c old name | |
| 8858 @findex noindent | |
| 8339 @cindex Omitting indentation | 8859 @cindex Omitting indentation |
| 8340 @cindex Suppressing indentation | 8860 @cindex Suppressing indentation |
| 8341 @cindex Indentation, omitting | 8861 @cindex Indentation, omitting |
| 8342 @findex noindent | |
| 8343 | 8862 |
| 8344 An example or other inclusion can break a paragraph into segments. | 8863 An example or other inclusion can break a paragraph into segments. |
| 8345 Ordinarily, the formatters indent text that follows an example as a new | 8864 Ordinarily, the formatters indent text that follows an example as a new |
| 8346 paragraph. You can prevent this on a case-by-case basis by writing | 8865 paragraph. You can prevent this on a case-by-case basis by writing |
| 8347 @code{@@noindent} at the beginning of a line, preceding the continuation | 8866 @code{@@noindent} at the beginning of a line, preceding the continuation |
| 8348 text. You can also disable indentation for all paragraphs globally with | 8867 text. You can also disable indentation for all paragraphs globally with |
| 8349 @code{@@paragraphindent} (@pxref{paragraphindent, Paragraph Indenting}). | 8868 @code{@@paragraphindent} (@pxref{@t{@@paragraphindent}}). |
| 8350 | 8869 |
| 8351 It is best to write @code{@@noindent} on a line by itself, since in most | 8870 It is best to write @code{@@noindent} on a line by itself, since in most |
| 8352 environments, spaces following the command will not be ignored. It's ok | 8871 environments, spaces following the command will not be ignored. It's ok |
| 8353 to use it at the beginning of a line, with text following, outside of | 8872 to use it at the beginning of a line, with text following, outside of |
| 8354 any environment. | 8873 any environment. |
| 8396 Do not put braces after an @code{@@noindent} command; they are not | 8915 Do not put braces after an @code{@@noindent} command; they are not |
| 8397 necessary, since @code{@@noindent} is a command used outside of | 8916 necessary, since @code{@@noindent} is a command used outside of |
| 8398 paragraphs (@pxref{Command Syntax}). | 8917 paragraphs (@pxref{Command Syntax}). |
| 8399 | 8918 |
| 8400 | 8919 |
| 8401 @node indent | 8920 @node @t{@@indent} |
| 8402 @section @code{@@indent}: Forcing Indentation | 8921 @section @code{@@indent}: Forcing Indentation |
| 8922 | |
| 8923 @anchor{indent}@c old name | |
| 8924 @findex indent | |
| 8403 @cindex Forcing indentation | 8925 @cindex Forcing indentation |
| 8404 @cindex Inserting indentation | 8926 @cindex Inserting indentation |
| 8405 @cindex Indentation, forcing | 8927 @cindex Indentation, forcing |
| 8406 @findex indent | |
| 8407 | 8928 |
| 8408 @indent | 8929 @indent |
| 8409 To complement the @code{@@noindent} command (see the previous | 8930 To complement the @code{@@noindent} command (see the previous |
| 8410 section), Texinfo provides the @code{@@indent} command that forces a | 8931 section), Texinfo provides the @code{@@indent} command that forces a |
| 8411 paragraph to be indented. This paragraph, for instance, is indented | 8932 paragraph to be indented. This paragraph, for instance, is indented |
| 8412 using an @code{@@indent} command. The first paragraph of a section is | 8933 using an @code{@@indent} command. The first paragraph of a section is |
| 8413 the most likely place to use @code{@@indent}, to override the normal | 8934 the most likely place to use @code{@@indent}, to override the normal |
| 8414 behavior of no indentation there (@pxref{paragraphindent}). | 8935 behavior of no indentation there (@pxref{@t{@@paragraphindent}}). |
| 8415 | 8936 |
| 8416 It is best to write @code{@@indent} on a line by itself, since in most | 8937 It is best to write @code{@@indent} on a line by itself, since in most |
| 8417 environments, spaces following the command will not be ignored. The | 8938 environments, spaces following the command will not be ignored. The |
| 8418 @code{@@indent} line will not generate a blank line in the Info output | 8939 @code{@@indent} line will not generate a blank line in the Info output |
| 8419 within an environment. | 8940 within an environment. |
| 8424 Do not put braces after an @code{@@indent} command; they are not | 8945 Do not put braces after an @code{@@indent} command; they are not |
| 8425 necessary, since @code{@@indent} is a command used outside of | 8946 necessary, since @code{@@indent} is a command used outside of |
| 8426 paragraphs (@pxref{Command Syntax}). | 8947 paragraphs (@pxref{Command Syntax}). |
| 8427 | 8948 |
| 8428 | 8949 |
| 8429 @node cartouche | 8950 @node @t{@@cartouche} |
| 8430 @section @code{@@cartouche}: Rounded Rectangles Around Examples | 8951 @section @code{@@cartouche}: Rounded Rectangles |
| 8952 | |
| 8953 @anchor{cartouche}@c old name | |
| 8431 @findex cartouche | 8954 @findex cartouche |
| 8432 @cindex Box with rounded corners | 8955 @cindex Box with rounded corners |
| 8433 @cindex Rounded rectangles, around examples | 8956 @cindex Rounded rectangles, around text |
| 8434 | 8957 |
| 8435 In a printed manual, the @code{@@cartouche} command draws a box with | 8958 In a printed manual, the @code{@@cartouche} command draws a box with |
| 8436 rounded corners around its contents. In HTML, a normal rectangle is | 8959 rounded corners around its contents. In HTML, a normal rectangle is |
| 8437 drawn (that's the best HTML can do). @code{@@cartouche} has no effect | 8960 drawn. @code{@@cartouche} has no effect in Info output. |
| 8438 in Info output. | |
| 8439 | 8961 |
| 8440 You can use this command to further highlight an example or quotation. | 8962 You can use this command to further highlight an example or quotation. |
| 8441 For instance, you could write a manual in which one type of example is | 8963 For instance, you could write a manual in which one type of example is |
| 8442 surrounded by a cartouche for emphasis. | 8964 surrounded by a cartouche for emphasis. |
| 8443 | 8965 |
| 8464 % pwd | 8986 % pwd |
| 8465 /usr/local/info | 8987 /usr/local/info |
| 8466 @end example | 8988 @end example |
| 8467 @end cartouche | 8989 @end cartouche |
| 8468 | 8990 |
| 8469 For proper output in HTML, it's necessary to put the | 8991 @code{@@cartouche} also implies @code{@@group} (@pxref{@t{@@group}}). |
| 8470 @code{@@cartouche} around the @code{@@example}, and not the other way | 8992 |
| 8471 around. This limitation of @command{makeinfo} may be removed one day. | |
| 8472 | |
| 8473 @code{@@cartouche} also implies @code{@@group} (@pxref{group}). | |
| 8474 | 8993 |
| 8475 @node Lists and Tables | 8994 @node Lists and Tables |
| 8476 @chapter Lists and Tables | 8995 @chapter Lists and Tables |
| 8477 @cindex Making lists and tables | 8996 @cindex Making lists and tables |
| 8478 @cindex Lists and tables, making | 8997 @cindex Lists and tables, making |
| 8482 bulleted or numbered; two-column tables can highlight the items in | 9001 bulleted or numbered; two-column tables can highlight the items in |
| 8483 the first column; multi-column tables are also supported. | 9002 the first column; multi-column tables are also supported. |
| 8484 | 9003 |
| 8485 @menu | 9004 @menu |
| 8486 * Introducing Lists:: Texinfo formats lists for you. | 9005 * Introducing Lists:: Texinfo formats lists for you. |
| 8487 * itemize:: How to construct a simple list. | 9006 * @t{@@itemize}:: How to construct a simple list. |
| 8488 * enumerate:: How to construct a numbered list. | 9007 * @t{@@enumerate}:: How to construct a numbered list. |
| 8489 * Two-column Tables:: How to construct a two-column table. | 9008 * Two-column Tables:: How to construct a two-column table. |
| 8490 * Multi-column Tables:: How to construct generalized tables. | 9009 * Multi-column Tables:: How to construct generalized tables. |
| 8491 @end menu | 9010 @end menu |
| 8492 | 9011 |
| 8493 @node Introducing Lists | 9012 @node Introducing Lists |
| 8494 @section Introducing Lists | 9013 @section Introducing Lists |
| 8495 | 9014 |
| 8496 Texinfo automatically indents the text in lists or tables, and numbers | 9015 Texinfo automatically indents the text in lists or tables, and numbers |
| 8497 an enumerated list. This last feature is useful if you modify the | 9016 an enumerated list. This last feature is useful if you modify the |
| 8498 list, since you do not need to renumber it yourself.@refill | 9017 list, since you do not need to renumber it yourself. |
| 8499 | 9018 |
| 8500 Numbered lists and tables begin with the appropriate @@-command at the | 9019 Numbered lists and tables begin with the appropriate @@-command at the |
| 8501 beginning of a line, and end with the corresponding @code{@@end} | 9020 beginning of a line, and end with the corresponding @code{@@end} |
| 8502 command on a line by itself. The table and itemized-list commands | 9021 command on a line by itself. The table and itemized-list commands |
| 8503 also require that you write formatting information on the same line as | 9022 also require that you write formatting information on the same line as |
| 8504 the beginning @@-command.@refill | 9023 the beginning @@-command. |
| 8505 | 9024 |
| 8506 Begin an enumerated list, for example, with an @code{@@enumerate} | 9025 Begin an enumerated list, for example, with an @code{@@enumerate} |
| 8507 command and end the list with an @code{@@end enumerate} command. | 9026 command and end the list with an @code{@@end enumerate} command. |
| 8508 Begin an itemized list with an @code{@@itemize} command, followed on | 9027 Begin an itemized list with an @code{@@itemize} command, followed on |
| 8509 the same line by a formatting command such as @code{@@bullet}, and end | 9028 the same line by a formatting command such as @code{@@bullet}, and end |
| 8510 the list with an @code{@@end itemize} command.@refill | 9029 the list with an @code{@@end itemize} command. |
| 8511 @findex end | 9030 @findex end |
| 8512 | 9031 |
| 8513 Precede each element of a list with an @code{@@item} or @code{@@itemx} | 9032 Precede each element of a list with an @code{@@item} or @code{@@itemx} |
| 8514 command.@refill | 9033 command. |
| 8515 | 9034 |
| 8516 @sp 1 | 9035 @sp 1 |
| 8517 @noindent | 9036 @noindent |
| 8518 Here is an itemized list of the different kinds of table and lists:@refill | 9037 Here is an itemized list of the different kinds of table and lists: |
| 8519 | 9038 |
| 8520 @itemize @bullet | 9039 @itemize @bullet |
| 8521 @item | 9040 @item |
| 8522 Itemized lists with and without bullets. | 9041 Itemized lists with and without bullets. |
| 8523 | 9042 |
| 8528 Two-column tables with highlighting. | 9047 Two-column tables with highlighting. |
| 8529 @end itemize | 9048 @end itemize |
| 8530 | 9049 |
| 8531 @sp 1 | 9050 @sp 1 |
| 8532 @noindent | 9051 @noindent |
| 8533 Here is an enumerated list with the same items:@refill | 9052 Here is an enumerated list with the same items: |
| 8534 | 9053 |
| 8535 @enumerate | 9054 @enumerate |
| 8536 @item | 9055 @item |
| 8537 Itemized lists with and without bullets. | 9056 Itemized lists with and without bullets. |
| 8538 | 9057 |
| 8544 @end enumerate | 9063 @end enumerate |
| 8545 | 9064 |
| 8546 @sp 1 | 9065 @sp 1 |
| 8547 @noindent | 9066 @noindent |
| 8548 And here is a two-column table with the same items and their | 9067 And here is a two-column table with the same items and their |
| 8549 @w{@@-commands}:@refill | 9068 @w{@@-commands}: |
| 8550 | 9069 |
| 8551 @table @code | 9070 @table @code |
| 8552 @item @@itemize | 9071 @item @@itemize |
| 8553 Itemized lists with and without bullets. | 9072 Itemized lists with and without bullets. |
| 8554 | 9073 |
| 8560 @itemx @@vtable | 9079 @itemx @@vtable |
| 8561 Two-column tables, optionally with indexing. | 9080 Two-column tables, optionally with indexing. |
| 8562 @end table | 9081 @end table |
| 8563 | 9082 |
| 8564 | 9083 |
| 8565 @node itemize | 9084 @node @t{@@itemize} |
| 8566 @section @code{@@itemize}: Making an Itemized List | 9085 @section @code{@@itemize}: Making an Itemized List |
| 9086 | |
| 9087 @anchor{itemize}@c old name | |
| 9088 @findex itemize | |
| 8567 @cindex Itemization | 9089 @cindex Itemization |
| 8568 @findex itemize | 9090 |
| 8569 | 9091 The @code{@@itemize} command produces a sequence of ``items'', each |
| 8570 The @code{@@itemize} command produces sequences of indented | 9092 starting with a bullet or other mark inside the left margin, and |
| 8571 paragraphs, with a bullet or other mark inside the left margin | 9093 generally indented. |
| 8572 at the beginning of each paragraph for which such a mark is desired.@refill | |
| 8573 | 9094 |
| 8574 @cindex @code{@@w}, for blank items | 9095 @cindex @code{@@w}, for blank items |
| 8575 Begin an itemized list by writing @code{@@itemize} at the beginning of | 9096 Begin an itemized list by writing @code{@@itemize} at the beginning of |
| 8576 a line. Follow the command, on the same line, with a character or a | 9097 a line. Follow the command, on the same line, with a character or a |
| 8577 Texinfo command that generates a mark. Usually, you will write | 9098 Texinfo command that generates a mark. Usually, you will use |
| 8578 @code{@@bullet} after @code{@@itemize}, but you can use | 9099 @code{@@bullet} after @code{@@itemize}, but you can use |
| 8579 @code{@@minus}, or any command or character that results in a single | 9100 @code{@@minus}, or any command or character that results in a single |
| 8580 character in the Info file. If you don't want any mark at all, use | 9101 character in the Info file. (When you write the mark command such as |
| 8581 @code{@@w}. (When you write the mark command such as | |
| 8582 @code{@@bullet} after an @code{@@itemize} command, you may omit the | 9102 @code{@@bullet} after an @code{@@itemize} command, you may omit the |
| 8583 @samp{@{@}}.) If you don't specify a mark command, the default is | 9103 @samp{@{@}}.) If you don't specify a mark command, the default is |
| 8584 @code{@@bullet}. | 9104 @code{@@bullet}. If you don't want any mark at all, but still want |
| 8585 | 9105 logical items, use @code{@@w@{@}} (in this case the braces are |
| 8586 Write the text of the indented paragraphs themselves after the | 9106 required). |
| 8587 @code{@@itemize}, up to another line that says @code{@@end | |
| 8588 itemize}.@refill | |
| 8589 | 9107 |
| 8590 @findex item | 9108 @findex item |
| 8591 At the beginning of each paragraph for which a mark in the margin is | 9109 After the @code{@@itemize}, write your items, each starting with |
| 8592 desired, write a line that starts with @code{@@item}. It is ok to | 9110 @code{@@item}. Text can follow on the same line as the @code{@@item}. |
| 8593 have text following the @code{@@item}. | 9111 The text of an item can continue for more than one paragraph. |
| 8594 | 9112 |
| 8595 Usually, you should put a blank line before an @code{@@item}. This | 9113 There should be at least one @code{@@item} inside the @code{@@itemize} |
| 8596 puts a blank line in the Info file. (@TeX{} inserts the proper | 9114 environment. If none are present, @code{makeinfo} gives a warning. |
| 8597 interline whitespace in either case.) Except when the entries are | 9115 If you just want indented text and not a list of items, use |
| 8598 very brief, these blank lines make the list look better.@refill | 9116 @code{@@indentedblock}; @pxref{@t{@@indentedblock}}. |
| 9117 | |
| 9118 Index entries and comments that are given before an @code{@@item} | |
| 9119 including the first, are automatically moved (internally) to after the | |
| 9120 @code{@@item}, so the output is as expected. Historically this has | |
| 9121 been a common practice. | |
| 9122 | |
| 9123 Usually, you should put a blank line between items. This puts a blank | |
| 9124 line in the Info file. (@TeX{} inserts the proper vertical space in | |
| 9125 any case.) Except when the entries are very brief, these blank lines | |
| 9126 make the list look better. | |
| 8599 | 9127 |
| 8600 Here is an example of the use of @code{@@itemize}, followed by the | 9128 Here is an example of the use of @code{@@itemize}, followed by the |
| 8601 output it produces. @code{@@bullet} produces an @samp{*} in Info and a | 9129 output it produces. @code{@@bullet} produces an @samp{*} in Info and |
| 8602 round dot in @TeX{}. | 9130 a round dot in other output formats. |
| 8603 | 9131 |
| 8604 @example | 9132 @example |
| 8605 @group | 9133 @group |
| 8606 @@itemize @@bullet | 9134 @@itemize @@bullet |
| 8607 @@item | 9135 @@item |
| 8627 for bar. | 9155 for bar. |
| 8628 @end itemize | 9156 @end itemize |
| 8629 @end quotation | 9157 @end quotation |
| 8630 | 9158 |
| 8631 Itemized lists may be embedded within other itemized lists. Here is a | 9159 Itemized lists may be embedded within other itemized lists. Here is a |
| 8632 list marked with dashes embedded in a list marked with bullets:@refill | 9160 list marked with dashes embedded in a list marked with bullets: |
| 8633 | 9161 |
| 8634 @example | 9162 @example |
| 8635 @group | 9163 @group |
| 8636 @@itemize @@bullet | 9164 @@itemize @@bullet |
| 8637 @@item | 9165 @@item |
| 8671 Second outer item. | 9199 Second outer item. |
| 8672 @end itemize | 9200 @end itemize |
| 8673 @end quotation | 9201 @end quotation |
| 8674 | 9202 |
| 8675 | 9203 |
| 8676 @node enumerate | 9204 @node @t{@@enumerate} |
| 8677 @section @code{@@enumerate}: Making a Numbered or Lettered List | 9205 @section @code{@@enumerate}: Making a Numbered or Lettered List |
| 9206 | |
| 9207 @anchor{enumerate}@c old name | |
| 9208 @findex enumerate | |
| 8678 @cindex Enumeration | 9209 @cindex Enumeration |
| 8679 @findex enumerate | 9210 |
| 8680 | 9211 @code{@@enumerate} is like @code{@@itemize} (@pxref{@t{@@itemize}}), |
| 8681 @code{@@enumerate} is like @code{@@itemize} (@pxref{itemize,, | 9212 except that the labels on the items are successive integers or letters |
| 8682 @code{@@itemize}}), except that the labels on the items are | 9213 instead of bullets. |
| 8683 successive integers or letters instead of bullets. | |
| 8684 | 9214 |
| 8685 Write the @code{@@enumerate} command at the beginning of a line. The | 9215 Write the @code{@@enumerate} command at the beginning of a line. The |
| 8686 command does not require an argument, but accepts either a number or a | 9216 command does not require an argument, but accepts either a number or a |
| 8687 letter as an option. Without an argument, @code{@@enumerate} starts the | 9217 letter as an option. Without an argument, @code{@@enumerate} starts the |
| 8688 list with the number @samp{1}. With a numeric argument, such as | 9218 list with the number @samp{1}. With a numeric argument, such as |
| 8689 @samp{3}, the command starts the list with that number. With an upper | 9219 @samp{3}, the command starts the list with that number. With an upper- |
| 8690 or lower case letter, such as @samp{a} or @samp{A}, the command starts | 9220 or lowercase letter, such as @samp{a} or @samp{A}, the command starts |
| 8691 the list with that letter. | 9221 the list with that letter. |
| 8692 | 9222 |
| 8693 Write the text of the enumerated list in the same way as an itemized | 9223 Write the text of the enumerated list in the same way as an itemized |
| 8694 list: write a line starting with @code{@@item} at the beginning of | 9224 list: write a line starting with @code{@@item} at the beginning of |
| 8695 each paragraph that you want enumerated. It is ok to have text | 9225 each item in the enumeration. It is ok to have text following the |
| 8696 following the @code{@@item}. | 9226 @code{@@item}, and the text for an item can continue for several |
| 9227 paragraphs. | |
| 8697 | 9228 |
| 8698 You should put a blank line between entries in the list. | 9229 You should put a blank line between entries in the list. |
| 8699 This generally makes it easier to read the Info file. | 9230 This generally makes it easier to read the Info file. |
| 8700 | 9231 |
| 8701 @need 1500 | 9232 @need 1500 |
| 8722 | 9253 |
| 8723 @item | 9254 @item |
| 8724 Proximate causes. | 9255 Proximate causes. |
| 8725 @end enumerate | 9256 @end enumerate |
| 8726 @sp 1 | 9257 @sp 1 |
| 8727 Here is an example with an argument of @kbd{3}:@refill | 9258 Here is an example with an argument of @kbd{3}: |
| 8728 @sp 1 | 9259 @sp 1 |
| 8729 @example | 9260 @example |
| 8730 @group | 9261 @group |
| 8731 @@enumerate 3 | 9262 @@enumerate 3 |
| 8732 @@item | 9263 @@item |
| 8754 @item | 9285 @item |
| 8755 Perpetuating causes. | 9286 Perpetuating causes. |
| 8756 @end enumerate | 9287 @end enumerate |
| 8757 @sp 1 | 9288 @sp 1 |
| 8758 Here is a brief summary of the alternatives. The summary is constructed | 9289 Here is a brief summary of the alternatives. The summary is constructed |
| 8759 using @code{@@enumerate} with an argument of @kbd{a}.@refill | 9290 using @code{@@enumerate} with an argument of @kbd{a}. |
| 8760 @sp 1 | 9291 @sp 1 |
| 8761 @enumerate a | 9292 @enumerate a |
| 8762 @item | 9293 @item |
| 8763 @code{@@enumerate} | 9294 @code{@@enumerate} |
| 8764 | 9295 |
| 8765 Without an argument, produce a numbered list, starting with the number | 9296 Without an argument, produce a numbered list, starting with the |
| 8766 1.@refill | 9297 number@tie{}1. |
| 8767 | 9298 |
| 8768 @item | 9299 @item |
| 8769 @code{@@enumerate @var{positive-integer}} | 9300 @code{@@enumerate @var{positive-integer}} |
| 8770 | 9301 |
| 8771 With a (positive) numeric argument, start a numbered list with that | 9302 With a (positive) numeric argument, start a numbered list with that |
| 8772 number. You can use this to continue a list that you interrupted with | 9303 number. You can use this to continue a list that you interrupted with |
| 8773 other text.@refill | 9304 other text. |
| 8774 | 9305 |
| 8775 @item | 9306 @item |
| 8776 @code{@@enumerate @var{upper-case-letter}} | 9307 @code{@@enumerate @var{upper-case-letter}} |
| 8777 | 9308 |
| 8778 With an upper case letter as argument, start a list | 9309 With an uppercase letter as argument, start a list |
| 8779 in which each item is marked | 9310 in which each item is marked |
| 8780 by a letter, beginning with that upper case letter.@refill | 9311 by a letter, beginning with that uppercase letter. |
| 8781 | 9312 |
| 8782 @item | 9313 @item |
| 8783 @code{@@enumerate @var{lower-case-letter}} | 9314 @code{@@enumerate @var{lower-case-letter}} |
| 8784 | 9315 |
| 8785 With a lower case letter as argument, start a list | 9316 With a lowercase letter as argument, start a list |
| 8786 in which each item is marked by | 9317 in which each item is marked by |
| 8787 a letter, beginning with that lower case letter.@refill | 9318 a letter, beginning with that lowercase letter. |
| 8788 @end enumerate | 9319 @end enumerate |
| 8789 | 9320 |
| 8790 You can also nest enumerated lists, as in an outline.@refill | 9321 You can also nest enumerated lists, as in an outline. |
| 9322 | |
| 8791 | 9323 |
| 8792 @node Two-column Tables | 9324 @node Two-column Tables |
| 8793 @section Making a Two-column Table | 9325 @section Making a Two-column Table |
| 9326 | |
| 8794 @cindex Tables, making two-column | 9327 @cindex Tables, making two-column |
| 8795 @findex table | 9328 @findex table |
| 8796 | 9329 |
| 8797 @code{@@table} is similar to @code{@@itemize} (@pxref{itemize,, | 9330 @code{@@table} is similar to @code{@@itemize} |
| 8798 @code{@@itemize}}), but allows you to specify a name or heading line for | 9331 (@pxref{@t{@@itemize}}), but allows you to specify a name or |
| 8799 each item. The @code{@@table} command is used to produce two-column | 9332 heading line for each item. The @code{@@table} command is used to |
| 8800 tables, and is especially useful for glossaries, explanatory | 9333 produce two-column tables, and is especially useful for glossaries, |
| 8801 exhibits, and command-line option summaries. | 9334 explanatory exhibits, and command-line option summaries. |
| 8802 | 9335 |
| 8803 @menu | 9336 @menu |
| 8804 * table:: How to construct a two-column table. | 9337 * @t{@@table}:: How to construct a two-column table. |
| 8805 * ftable vtable:: Automatic indexing for two-column tables. | 9338 * @t{@@ftable @@vtable}:: Automatic indexing for two-column tables. |
| 8806 * itemx:: How to put more entries in the first column. | 9339 * @t{@@itemx}:: How to put more entries in the first column. |
| 8807 @end menu | 9340 @end menu |
| 8808 | 9341 |
| 8809 @node table | 9342 @node @t{@@table} |
| 8810 @subsection Using the @code{@@table} Command | 9343 @subsection Using the @code{@@table} Command |
| 9344 | |
| 9345 @anchor{table}@c old name | |
| 8811 | 9346 |
| 8812 @cindex Definition lists, typesetting | 9347 @cindex Definition lists, typesetting |
| 8813 Use the @code{@@table} command to produce two-column tables. It is | 9348 Use the @code{@@table} command to produce two-column tables. It is |
| 8814 usually listed for ``definition lists'' of various sorts, where you | 9349 typically used when you have a list of items and a brief text with |
| 8815 have a list of terms and a brief text with each one. | 9350 each one, such as ``definition lists''. |
| 8816 | 9351 |
| 8817 Write the @code{@@table} command at the beginning of a line, after a | 9352 Write the @code{@@table} command at the beginning of a line, after a |
| 8818 blank line, and follow it on the same line with an argument that is a | 9353 blank line, and follow it on the same line with an argument that is a |
| 8819 Texinfo ``indicating'' command such as @code{@@code}, @code{@@samp}, | 9354 Texinfo ``indicating'' command such as @code{@@code}, @code{@@samp}, |
| 8820 @code{@@var}, @code{@@option}, or @code{@@kbd} (@pxref{Indicating}). | 9355 @code{@@var}, @code{@@option}, or @code{@@kbd} (@pxref{Indicating}). |
| 8821 | 9356 |
| 8822 This command will be applied to the text that goes into the first | 9357 This command will be applied to the text that goes into the first |
| 8823 column of each item and thus determines how it will be highlighted. | 9358 column of each item and thus determines how it will be highlighted. |
| 8824 For example, @code{@@table @@code} will cause the text in the first | 9359 For example, @code{@@table @@code} will cause the text in the first |
| 8825 column to be output as if it @code{@@code} command. | 9360 column to be output as if it had been the argument to an @code{@@code} |
| 8826 | 9361 command. |
| 9362 | |
| 9363 @anchor{@t{@@asis}}@c command name with @, for consistency | |
| 8827 @findex asis | 9364 @findex asis |
| 8828 You may also use the @code{@@asis} command as an argument to | 9365 You may also use the @code{@@asis} command as an argument to |
| 8829 @code{@@table}. @code{@@asis} is a command that does nothing; if you | 9366 @code{@@table}. @code{@@asis} is a command that does nothing; if you |
| 8830 use this command after @code{@@table}, the first column entries are | 9367 use this command after @code{@@table}, the first column entries are |
| 8831 output without added highlighting (``as is''). | 9368 output without added highlighting (``as is''). |
| 8832 | 9369 |
| 8833 The @code{@@table} command works with other commands besides those | 9370 The @code{@@table} command works with other commands besides those |
| 8834 explicitly mentioned here. However, you can only use commands that | 9371 explicitly mentioned here. However, you can only use predefined |
| 8835 normally take arguments in braces. (In this case, however, you use | 9372 Texinfo commands that normally take an argument in braces. You cannot |
| 8836 the command name without an argument, because the subsequent | 9373 reliably use a new command defined with @code{@@macro}, but an |
| 8837 @code{@@item}'s will supply the argument.) | 9374 @code{@@alias} (for a suitable predefined command) is acceptable. |
| 9375 @xref{Defining New Texinfo Commands}. | |
| 8838 | 9376 |
| 8839 @findex item | 9377 @findex item |
| 8840 Begin each table entry with an @code{@@item} command at the beginning | 9378 Begin each table entry with an @code{@@item} command at the beginning |
| 8841 of a line. Write the first column text on the same line as the | 9379 of a line. Write the first column text on the same line as the |
| 8842 @code{@@item} command. Write the second column text on the line | 9380 @code{@@item} command. Write the second column text on the line |
| 8844 need to type anything for an empty second column entry.) You may | 9382 need to type anything for an empty second column entry.) You may |
| 8845 write as many lines of supporting text as you wish, even several | 9383 write as many lines of supporting text as you wish, even several |
| 8846 paragraphs. But only the text on the same line as the @code{@@item} | 9384 paragraphs. But only the text on the same line as the @code{@@item} |
| 8847 will be placed in the first column (including any footnotes). | 9385 will be placed in the first column (including any footnotes). |
| 8848 | 9386 |
| 8849 Normally, you should put a blank line before an @code{@@item} line. | 9387 Normally, you should put a blank line before an @code{@@item} line |
| 8850 This puts a blank line in the Info file. Except when the entries are | 9388 (except the first one). This puts a blank line in the Info file. |
| 8851 very brief, a blank line looks better. | 9389 Except when the entries are very brief, a blank line looks better. |
| 8852 | 9390 |
| 8853 End the table with a line consisting of @code{@@end table}, followed | 9391 End the table with a line consisting of @code{@@end table}, followed |
| 8854 by a blank line. @TeX{} will always start a new paragraph after the | 9392 by a blank line. @TeX{} will always start a new paragraph after the |
| 8855 table, so the blank line is needed for the Info output to be analogous. | 9393 table, so the blank line is needed for the Info output to be analogous. |
| 8856 | 9394 |
| 8881 @item bar | 9419 @item bar |
| 8882 Text for @samp{bar}. | 9420 Text for @samp{bar}. |
| 8883 @end table | 9421 @end table |
| 8884 | 9422 |
| 8885 If you want to list two or more named items with a single block of | 9423 If you want to list two or more named items with a single block of |
| 8886 text, use the @code{@@itemx} command. (@xref{itemx,,@code{@@itemx}}.) | 9424 text, use the @code{@@itemx} command. (@xref{@t{@@itemx}}.) |
| 8887 | 9425 |
| 8888 | 9426 |
| 8889 @node ftable vtable | 9427 @node @t{@@ftable @@vtable} |
| 8890 @subsection @code{@@ftable} and @code{@@vtable} | 9428 @subsection @code{@@ftable} and @code{@@vtable} |
| 8891 @cindex Tables with indexes | 9429 |
| 8892 @cindex Indexing table entries automatically | 9430 @anchor{ftable vtable}@c old name |
| 8893 @findex ftable | 9431 @findex ftable |
| 8894 @findex vtable | 9432 @findex vtable |
| 9433 @cindex Tables with indexing | |
| 9434 @cindex Indexing table entries automatically | |
| 8895 | 9435 |
| 8896 The @code{@@ftable} and @code{@@vtable} commands are the same as the | 9436 The @code{@@ftable} and @code{@@vtable} commands are the same as the |
| 8897 @code{@@table} command except that @code{@@ftable} automatically enters | 9437 @code{@@table} command except that @code{@@ftable} automatically enters |
| 8898 each of the items in the first column of the table into the index of | 9438 each of the items in the first column of the table into the index of |
| 8899 functions and @code{@@vtable} automatically enters each of the items in | 9439 functions and @code{@@vtable} automatically enters each of the items in |
| 8900 the first column of the table into the index of variables. This | 9440 the first column of the table into the index of variables. This |
| 8901 simplifies the task of creating indices. Only the items on the same | 9441 simplifies the task of creating indices. Only the items on the same |
| 8902 line as the @code{@@item} commands are indexed, and they are indexed in | 9442 line as the @code{@@item} commands are indexed, and they are indexed in |
| 8903 exactly the form that they appear on that line. @xref{Indices}, | 9443 exactly the form that they appear on that line. @xref{Indices}, |
| 8904 for more information about indices.@refill | 9444 for more information about indices. |
| 8905 | 9445 |
| 8906 Begin a two-column table using @code{@@ftable} or @code{@@vtable} by | 9446 Begin a two-column table using @code{@@ftable} or @code{@@vtable} by |
| 8907 writing the @@-command at the beginning of a line, followed on the same | 9447 writing the @@-command at the beginning of a line, followed on the same |
| 8908 line by an argument that is a Texinfo command such as @code{@@code}, | 9448 line by an argument that is a Texinfo command such as @code{@@code}, |
| 8909 exactly as you would for an @code{@@table} command; and end the table | 9449 exactly as you would for an @code{@@table} command; and end the table |
| 8910 with an @code{@@end ftable} or @code{@@end vtable} command on a line by | 9450 with an @code{@@end ftable} or @code{@@end vtable} command on a line by |
| 8911 itself. | 9451 itself. |
| 8912 | 9452 |
| 8913 See the example for @code{@@table} in the previous section. | 9453 See the example for @code{@@table} in the previous section. |
| 8914 | 9454 |
| 8915 @node itemx | 9455 |
| 8916 @subsection @code{@@itemx} | 9456 @node @t{@@itemx} |
| 9457 @subsection @code{@@itemx}: Second and Subsequent Items | |
| 9458 | |
| 9459 @anchor{itemx}@c old name | |
| 8917 @cindex Two named items for @code{@@table} | 9460 @cindex Two named items for @code{@@table} |
| 8918 @findex itemx | 9461 @findex itemx |
| 8919 | 9462 |
| 8920 Use the @code{@@itemx} command inside a table when you have two or more | 9463 Use the @code{@@itemx} command inside a table when you have two or more |
| 8921 first column entries for the same item, each of which should appear on a | 9464 first column entries for the same item, each of which should appear on a |
| 8936 @group | 9479 @group |
| 8937 @@table @@code | 9480 @@table @@code |
| 8938 @@item upcase | 9481 @@item upcase |
| 8939 @@itemx downcase | 9482 @@itemx downcase |
| 8940 These two functions accept a character or a string as | 9483 These two functions accept a character or a string as |
| 8941 argument, and return the corresponding upper case (lower | 9484 argument, and return the corresponding uppercase (lowercase) |
| 8942 case) character or string. | 9485 character or string. |
| 8943 @@end table | 9486 @@end table |
| 8944 @end group | 9487 @end group |
| 8945 @end example | 9488 @end example |
| 8946 | 9489 |
| 8947 @noindent | 9490 @noindent |
| 8949 | 9492 |
| 8950 @table @code | 9493 @table @code |
| 8951 @item upcase | 9494 @item upcase |
| 8952 @itemx downcase | 9495 @itemx downcase |
| 8953 These two functions accept a character or a string as | 9496 These two functions accept a character or a string as |
| 8954 argument, and return the corresponding upper case (lower | 9497 argument, and return the corresponding uppercase (lowercase) |
| 8955 case) character or string.@refill | 9498 character or string. |
| 8956 @end table | 9499 @end table |
| 8957 | 9500 |
| 8958 @noindent | 9501 @noindent |
| 8959 (Note also that this example illustrates multi-line supporting text in | 9502 (Note also that this example illustrates multi-line supporting text in |
| 8960 a two-column table.)@refill | 9503 a two-column table.) |
| 8961 | 9504 |
| 8962 | 9505 |
| 8963 @node Multi-column Tables | 9506 @node Multi-column Tables |
| 8964 @section @code{@@multitable}: Multi-column Tables | 9507 @section @code{@@multitable}: Multi-column Tables |
| 9508 | |
| 9509 @findex multitable | |
| 8965 @cindex Tables, making multi-column | 9510 @cindex Tables, making multi-column |
| 8966 @findex multitable | |
| 8967 | 9511 |
| 8968 @code{@@multitable} allows you to construct tables with any number of | 9512 @code{@@multitable} allows you to construct tables with any number of |
| 8969 columns, with each column having any width you like. | 9513 columns, with each column having any width you like. |
| 8970 | 9514 |
| 8971 You define the column widths on the @code{@@multitable} line itself, and | 9515 You define the column widths on the @code{@@multitable} line itself, and |
| 9027 @end enumerate | 9571 @end enumerate |
| 9028 | 9572 |
| 9029 | 9573 |
| 9030 @node Multitable Rows | 9574 @node Multitable Rows |
| 9031 @subsection Multitable Rows | 9575 @subsection Multitable Rows |
| 9576 | |
| 9032 @cindex Multitable rows | 9577 @cindex Multitable rows |
| 9033 @cindex Rows, of a multitable | 9578 @cindex Rows, of a multitable |
| 9034 | 9579 |
| 9035 @findex item | 9580 @findex item |
| 9036 @findex tab | 9581 @findex tab |
| 9040 Line breaks are not special within the table body, and you may break | 9585 Line breaks are not special within the table body, and you may break |
| 9041 input lines in your source file as necessary. | 9586 input lines in your source file as necessary. |
| 9042 | 9587 |
| 9043 @findex headitem | 9588 @findex headitem |
| 9044 @cindex Heading row, in table | 9589 @cindex Heading row, in table |
| 9045 @cindex <thead> HTML tag | 9590 @cindex @code{<thead>} HTML/XML tag |
| 9046 You can also use @code{@@headitem} instead of @code{@@item} to produce | 9591 You can also use @code{@@headitem} instead of @code{@@item} to produce |
| 9047 a @dfn{heading row}. The @TeX{} output for such a row is in bold, and | 9592 a @dfn{heading row}. The @TeX{} output for such a row is in bold, and |
| 9048 the HTML, XML, and Docbook output uses the @code{<thead>} tag. In | 9593 the HTML and Docbook output uses the @code{<thead>} tag. In Info, the |
| 9049 Info, the heading row is followed by a separator line made of dashes | 9594 heading row is followed by a separator line made of dashes (@samp{-} |
| 9050 (@samp{-} characters). | 9595 characters). |
| 9596 | |
| 9597 @findex headitemfont | |
| 9598 @cindex Font for multitable heading rows | |
| 9599 The command @code{@@headitemfont} can be used in templates when the | |
| 9600 entries in an @code{@@headitem} row need to be used in a template. It | |
| 9601 is a synonym for @code{@@b}, but using @code{@@headitemfont} avoids | |
| 9602 any dependency on that particular font style, in case we provide a way | |
| 9603 to change it in the future. | |
| 9051 | 9604 |
| 9052 Here is a complete example of a multi-column table (the text is from | 9605 Here is a complete example of a multi-column table (the text is from |
| 9053 @cite{The XEmacs Users' Manual}, @pxref{Split Window,, Splitting Windows, | 9606 @cite{XEmacs User's Manual}, @pxref{Split Window,, Splitting Windows, |
| 9054 xemacs, XEmacs User's Manual}): | 9607 emacs, XEmacs User's Manual}): |
| 9055 | 9608 |
| 9056 @example | 9609 @example |
| 9057 @@multitable @@columnfractions .15 .45 .4 | 9610 @@multitable @@columnfractions .15 .45 .4 |
| 9058 @@headitem Key @@tab Command @@tab Description | 9611 @@headitem Key @@tab Command @@tab Description |
| 9059 @@item C-x 2 | 9612 @@item C-x 2 |
| 9069 @@tab In the mode line or scroll bar of a window, | 9622 @@tab In the mode line or scroll bar of a window, |
| 9070 split that window. | 9623 split that window. |
| 9071 @@end multitable | 9624 @@end multitable |
| 9072 @end example | 9625 @end example |
| 9073 | 9626 |
| 9074 @noindent | 9627 @noindent produces: |
| 9075 produces: | |
| 9076 | 9628 |
| 9077 @multitable @columnfractions .15 .45 .4 | 9629 @multitable @columnfractions .15 .45 .4 |
| 9078 @headitem Key @tab Command @tab Description | 9630 @headitem Key @tab Command @tab Description |
| 9079 @item C-x 2 | 9631 @item C-x 2 |
| 9080 @tab @code{split-window-vertically} | 9632 @tab @code{split-window-vertically} |
| 9116 @node Floats | 9668 @node Floats |
| 9117 @section Floats | 9669 @section Floats |
| 9118 @cindex Floats, in general | 9670 @cindex Floats, in general |
| 9119 | 9671 |
| 9120 A @dfn{float} is a display which is set off from the main text. It is | 9672 A @dfn{float} is a display which is set off from the main text. It is |
| 9121 typically labelled as being a ``Figure'', ``Table'', ``Example'', or | 9673 typically labeled as being a ``Figure'', ``Table'', ``Example'', or |
| 9122 some similar type. | 9674 some similar type. |
| 9123 | 9675 |
| 9124 @cindex Floating, not yet implemented | 9676 @cindex Floating, not yet implemented |
| 9125 A float is so-named because, in principle, it can be moved to the | 9677 A float is so-named because, in principle, it can be moved to the |
| 9126 bottom or top of the current page, or to a following page, in the | 9678 bottom or top of the current page, or to a following page, in the |
| 9127 printed output. (Floating does not make sense in other output | 9679 printed output. (Floating does not make sense in other output |
| 9128 formats.) In the present version of Texinfo, however, this floating | 9680 formats.) In the present version of Texinfo, however, this floating |
| 9129 is unfortunately not yet implemented. Instead, the floating material | 9681 is unfortunately not yet implemented. Instead, the floating material |
| 9130 is simply output at the current location, more or less as if it were | 9682 is simply output at the current location, more or less as if it were |
| 9131 an @code{@@group} (@pxref{group,,@code{@@group}}). | 9683 an @code{@@group} (@pxref{@t{@@group}}). |
| 9132 | 9684 |
| 9133 @menu | 9685 @menu |
| 9134 * float:: Producing floating material. | 9686 * @t{@@float}:: Producing floating material. |
| 9135 * caption shortcaption:: Specifying descriptions for floats. | 9687 * @t{@@caption @@shortcaption}:: Specifying descriptions for floats. |
| 9136 * listoffloats:: A table of contents for floats. | 9688 * @t{@@listoffloats}:: A table of contents for floats. |
| 9137 @end menu | 9689 @end menu |
| 9138 | 9690 |
| 9139 | 9691 |
| 9140 @node float | 9692 @node @t{@@float} |
| 9141 @subsection @code{@@float} [@var{type}][,@var{label}]: Floating Material | 9693 @subsection @code{@@float} [@var{type}][,@var{label}]: Floating Material |
| 9694 | |
| 9695 @anchor{float}@c old name | |
| 9142 @findex float | 9696 @findex float |
| 9143 @cindex Float environment | 9697 @cindex Float environment |
| 9144 | 9698 |
| 9145 To produce floating material, enclose the material you want to be | 9699 To produce floating material, enclose the material you want to be |
| 9146 displayed separate between @code{@@float} and @code{@@end float} | 9700 displayed separate between @code{@@float} and @code{@@end float} |
| 9147 commands, on lines by themselves. | 9701 commands, on lines by themselves. |
| 9148 | 9702 |
| 9149 Floating material uses @code{@@image} to display an already-existing | 9703 Floating material often uses @code{@@image} to display an |
| 9150 graphic (@pxref{Images}), or @code{@@multitable} to display a table | 9704 already-existing graphic (@pxref{Images}), or @code{@@multitable} to |
| 9151 (@pxref{Multi-column Tables}). However, the contents of the float can | 9705 display a table (@pxref{Multi-column Tables}). However, the contents |
| 9152 be anything. Here's an example with simple text: | 9706 of the float can be anything. Here's an example with simple text: |
| 9153 | 9707 |
| 9154 @example | 9708 @example |
| 9155 @@float Figure,fig:ex1 | 9709 @@float Figure,fig:ex1 |
| 9156 This is an example float. | 9710 This is an example float. |
| 9157 @@end float | 9711 @@end float |
| 9167 by a comma), @var{type} and @var{label}. Both are optional. | 9721 by a comma), @var{type} and @var{label}. Both are optional. |
| 9168 | 9722 |
| 9169 @table @var | 9723 @table @var |
| 9170 @item type | 9724 @item type |
| 9171 Specifies the sort of float this is; typically a word such as | 9725 Specifies the sort of float this is; typically a word such as |
| 9172 ``Figure'', ``Table'', etc. If not given, and @var{label} is, any | 9726 ``Figure'', ``Table'', etc. If this is not given, and @var{label} is, |
| 9173 cross-referencing will simply use a bare number. | 9727 any cross referencing will simply use a bare number. |
| 9174 | 9728 |
| 9175 @item label | 9729 @item label |
| 9176 Specifies a cross-reference label for this float. If given, this | 9730 Specifies a cross reference label for this float. If given, this |
| 9177 float is automatically given a number, and will appear in any | 9731 float is automatically given a number, and will appear in any |
| 9178 @code{@@listoffloats} output (@pxref{listoffloats}). Cross-references | 9732 @code{@@listoffloats} output (@pxref{@t{@@listoffloats}}). Cross |
| 9179 to @var{label} are allowed. | 9733 references to @var{label} are allowed. |
| 9180 | 9734 |
| 9181 @cindex Floats, making unnumbered | 9735 @cindex Floats, making unnumbered |
| 9182 @cindex Unnumbered float, creating | 9736 @cindex Unnumbered float, creating |
| 9183 On the other hand, if @var{label} is not given, then the float will | 9737 On the other hand, if @var{label} is not given, then the float will |
| 9184 not be numbered and consequently will not appear in the | 9738 not be numbered and consequently will not appear in the |
| 9185 @code{@@listoffloats} output or be cross-referenceable. | 9739 @code{@@listoffloats} output or be cross-referenceable. |
| 9186 @end table | 9740 @end table |
| 9187 | 9741 |
| 9188 @noindent Normally, you specify both @var{type} and @var{label}, to get a | 9742 @noindent Ordinarily, you specify both @var{type} and @var{label}, to get a |
| 9189 labeled and numbered float. | 9743 labeled and numbered float. |
| 9190 | 9744 |
| 9191 @cindex Floats, numbering of | 9745 @cindex Floats, numbering of |
| 9192 @cindex Numbering of floats | 9746 @cindex Numbering of floats |
| 9193 In Texinfo, all floats are numbered the same way: with the chapter | 9747 In Texinfo, all floats are numbered in the same way: with the chapter |
| 9194 number (or appendix letter), a period, and the float number, which | 9748 number (or appendix letter), a period, and the float number, which |
| 9195 simply counts 1, 2, 3, @dots{}, and is reset at each chapter. Each | 9749 simply counts 1, 2, 3, @dots{}, and is reset at each chapter. Each |
| 9196 float type is counted independently. | 9750 float type is counted independently. |
| 9197 | 9751 |
| 9198 Floats within an @code{@@unnumbered} are numbered, or outside of any | 9752 Floats within an @code{@@unnumbered}, or outside of any chapter, are |
| 9199 chapter, are simply numbered consecutively from 1. | 9753 simply numbered consecutively from 1. |
| 9200 | 9754 |
| 9201 These numbering conventions are not, at present, changeable. | 9755 These numbering conventions are not, at present, changeable. |
| 9202 | 9756 |
| 9203 | 9757 |
| 9204 @node caption shortcaption | 9758 @node @t{@@caption @@shortcaption} |
| 9205 @subsection @code{@@caption} & @code{@@shortcaption} | 9759 @subsection @code{@@caption} & @code{@@shortcaption} |
| 9760 | |
| 9761 @anchor{caption shortcaption}@c old name | |
| 9206 @findex caption | 9762 @findex caption |
| 9207 @findex shortcaption | 9763 @findex shortcaption |
| 9208 @cindex Captions, for floats | 9764 @cindex Captions, for floats |
| 9209 @cindex Short captions, for lists of floats | 9765 @cindex Short captions, for lists of floats |
| 9210 | 9766 |
| 9211 You may write an @code{@@caption} anywhere within a @code{@@float} | 9767 You may write an @code{@@caption} anywhere within an @code{@@float} |
| 9212 environment, to define a caption for the float. It is not allowed in | 9768 environment, to define a caption for the float. It is not allowed in |
| 9213 any other context. @code{@@caption} takes a single argument, enclosed | 9769 any other context. @code{@@caption} takes a single argument, enclosed |
| 9214 in braces. Here's an example: | 9770 in braces. Here's an example: |
| 9215 | 9771 |
| 9216 @example | 9772 @example |
| 9247 ... as above ... | 9803 ... as above ... |
| 9248 @@shortcaption@{Text for list of floats.@} | 9804 @@shortcaption@{Text for list of floats.@} |
| 9249 @@end float | 9805 @@end float |
| 9250 @end example | 9806 @end example |
| 9251 | 9807 |
| 9252 The text for @code{@@caption} and @code{@@shortcaption} may not | 9808 The text for @code{@@shortcaption} may not contain comments |
| 9253 contain comments (@code{@@c}), verbatim text (@code{@@verb}), | 9809 (@code{@@c}), verbatim text (@code{@@verb}), environments such as |
| 9254 environments such as @code{@@example}, or other complex constructs. | 9810 @code{@@example}, footnotes (@code{@@footnote}) or other complex |
| 9255 | 9811 constructs. The same constraints apply to @code{@@caption} unless |
| 9256 | 9812 there is an @code{@@shortcaption}. |
| 9257 @node listoffloats | 9813 |
| 9814 | |
| 9815 @node @t{@@listoffloats} | |
| 9258 @subsection @code{@@listoffloats}: Tables of Contents for Floats | 9816 @subsection @code{@@listoffloats}: Tables of Contents for Floats |
| 9817 | |
| 9818 @anchor{listoffloats}@c old name | |
| 9259 @findex listoffloats | 9819 @findex listoffloats |
| 9260 @cindex List of floats | 9820 @cindex List of floats |
| 9261 @cindex Floats, list of | 9821 @cindex Floats, list of |
| 9262 @cindex Table of contents, for floats | 9822 @cindex Table of contents, for floats |
| 9263 | 9823 |
| 9264 You can write a @code{@@listoffloats} command to generate a list of | 9824 You can write an @code{@@listoffloats} command to generate a list of |
| 9265 floats for a given float type (@pxref{float}), analogous to the | 9825 floats for a given float type (@pxref{@t{@@float}}), analogous to |
| 9266 document's overall table of contents. Typically, it is written in its | 9826 the document's overall table of contents. Typically, it is written in |
| 9267 own @code{@@unnumbered} node to provide a heading and structure, | 9827 its own @code{@@unnumbered} node to provide a heading and structure, |
| 9268 rather like @code{@@printindex} (@pxref{Printing Indices & Menus}). | 9828 rather like @code{@@printindex} (@pxref{Printing Indices & Menus}). |
| 9269 | 9829 |
| 9270 @code{@@listoffloats} takes one optional argument, the float type. | 9830 @code{@@listoffloats} takes one optional argument, the float type. |
| 9271 Here's an example: | 9831 Here's an example: |
| 9272 | 9832 |
| 9280 | 9840 |
| 9281 @display | 9841 @display |
| 9282 @listoffloats Figure | 9842 @listoffloats Figure |
| 9283 @end display | 9843 @end display |
| 9284 | 9844 |
| 9285 Without any argument, @code{@@listoffloats} generates a list of | 9845 Without any argument, @code{@@listoffloats} generates a list of floats |
| 9286 floats for which no float type was specified, i.e., no first argument | 9846 for which no float type was specified, i.e., no first argument to the |
| 9287 to the @code{@@float} command (@pxref{float}). | 9847 @code{@@float} command (@pxref{@t{@@float}}). |
| 9288 | 9848 |
| 9289 Each line in the list of floats contains the float type (if any), | 9849 Each line in the list of floats contains the float type (if any), |
| 9290 the float number, and the caption, if any---the @code{@@shortcaption} | 9850 the float number, and the caption, if any---the @code{@@shortcaption} |
| 9291 argument, if it was specified, else the @code{@@caption} argument. | 9851 argument, if it was specified, else the @code{@@caption} argument. |
| 9292 In Info, the result is a menu where each float can be selected. In | 9852 In Info, the result is a menu where each float can be selected. In |
| 9293 HTML, each line is a link to the float. In printed output, the page | 9853 HTML, each line is a link to the float. In printed output, the page |
| 9294 number is included. | 9854 number is included. |
| 9295 | 9855 |
| 9296 Unnumbered floats (those without cross-reference labels) are omitted | 9856 Unnumbered floats (those without cross reference labels) are omitted |
| 9297 from the list of floats. | 9857 from the list of floats. |
| 9298 | 9858 |
| 9299 | 9859 |
| 9300 @node Images | 9860 @node Images |
| 9301 @section Inserting Images | 9861 @section Inserting Images |
| 9330 extension, because the different processors support different formats: | 9890 extension, because the different processors support different formats: |
| 9331 | 9891 |
| 9332 @itemize @bullet | 9892 @itemize @bullet |
| 9333 @item | 9893 @item |
| 9334 @pindex eps image format | 9894 @pindex eps image format |
| 9335 @TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript | 9895 @TeX{} (DVI output) reads the file @file{@var{filename}.eps} |
| 9336 format). | 9896 (Encapsulated PostScript format). |
| 9897 | |
| 9337 @item | 9898 @item |
| 9338 @pindex pdftex@r{, and images} | 9899 @pindex pdftex@r{, and images} |
| 9339 @pindex png image format | 9900 @pindex png image format |
| 9340 @pindex jpeg image format | 9901 @pindex jpeg image format |
| 9341 @pindex pdf image inclusions | 9902 @pindex pdf image inclusions |
| 9342 pdf@TeX{} reads @file{@var{filename}.png}, @file{@var{filename}.jpg}, | 9903 pdf@TeX{} reads @file{@var{filename}.pdf}, @file{@var{filename}.png}, |
| 9343 @file{@var{filename}.jpeg}, or @file{@var{filename}.pdf} (in that | 9904 @file{@var{filename}.jpg}, or @file{@var{filename}.jpeg} (in that |
| 9344 order). It also tries uppercase versions of the extensions. The PDF | 9905 order). It also tries uppercase versions of the extensions. The PDF |
| 9345 format cannot support EPS images, so they must be converted first. | 9906 format does not support EPS images, so such must be converted first. |
| 9907 | |
| 9346 @item | 9908 @item |
| 9347 @code{makeinfo} includes @file{@var{filename}.txt} verbatim for | 9909 For Info, @code{makeinfo} includes @file{@var{filename}.txt} verbatim |
| 9348 Info output (more or less as if it was an @code{@@example}). | 9910 (more or less as if it were in @code{@@verbatim}). The Info output |
| 9911 may also include a reference to @file{@var{filename}.png} or | |
| 9912 @file{@var{filename}.jpg}. (See below.) | |
| 9913 | |
| 9349 @item | 9914 @item |
| 9350 @code{makeinfo} uses the optional fifth argument @var{extension} to | 9915 For HTML, @code{makeinfo} outputs a reference to |
| 9351 @code{@@image} for the filename extension, if it is specified. For example: | 9916 @file{@var{filename}.png}, @file{@var{filename}.jpg}, |
| 9917 @file{@var{filename}.jpeg} or @file{@var{filename}.gif} (in that | |
| 9918 order). If none of those exist, it gives an error, and outputs a | |
| 9919 reference to @file{@var{filename}.jpg} anyway. | |
| 9920 | |
| 9921 @item | |
| 9922 @cindex SVG images, used in Docbook | |
| 9923 For Docbook, @code{makeinfo} outputs references to | |
| 9924 @file{@var{filename}.eps}, @file{@var{filename}.gif} | |
| 9925 @file{@var{filename}.jpeg}, @file{@var{filename}.jpg}, | |
| 9926 @file{@var{filename}.pdf}, @file{@var{filename}.png} and | |
| 9927 @file{@var{filename}.svg}, for every file found. Also, | |
| 9928 @file{@var{filename}.txt} is included verbatim, if present. (The | |
| 9929 subsequent Docbook processor is supposed to choose the appropriate one.) | |
| 9930 | |
| 9931 @item | |
| 9932 For Info and HTML output, @code{makeinfo} uses the optional fifth | |
| 9933 argument @var{extension} to @code{@@image} for the filename extension, | |
| 9934 if it is specified and the file is found. Any leading period should | |
| 9935 be included in @var{extension}. For example: | |
| 9352 | 9936 |
| 9353 @pindex XPM image format | 9937 @pindex XPM image format |
| 9354 @example | 9938 @example |
| 9355 @@image@{foo,,,,.xpm@} | 9939 @@image@{foo,,,,.xpm@} |
| 9356 @end example | 9940 @end example |
| 9357 | 9941 |
| 9358 @noindent | |
| 9359 will cause @code{makeinfo} to look for @file{foo.xpm} before any others. | |
| 9360 | |
| 9361 @end itemize | 9942 @end itemize |
| 9943 | |
| 9944 If you want to install image files for use by Info readers too, we | |
| 9945 recommend putting them in a subdirectory like @samp{@var{foo}-figures} | |
| 9946 for a package @var{foo}. Copying the files into | |
| 9947 @code{$(infodir)/@var{foo}-figures/} should be done in your | |
| 9948 @code{Makefile}. | |
| 9362 | 9949 |
| 9363 The @var{width} and @var{height} arguments are described in the next | 9950 The @var{width} and @var{height} arguments are described in the next |
| 9364 section. | 9951 section. |
| 9365 | 9952 |
| 9366 For @TeX{} output, if an image is the only thing in a paragraph it | 9953 For @TeX{} output, if an image is the only thing in a paragraph it |
| 9367 will ordinarily be displayed on a line by itself, respecting the | 9954 will ordinarily be displayed on a line by itself, respecting the |
| 9368 current environment indentation, but without the normal paragraph | 9955 current environment indentation, but without the normal paragraph |
| 9369 indentation. If you want it centered, use @code{@@center} | 9956 indentation. If you want it centered, use @code{@@center} |
| 9370 (@pxref{titlefont center sp,,@code{@@titlefont @@center @@sp}}). | 9957 (@pxref{@t{@@titlefont @@center @@sp}}). |
| 9371 | 9958 |
| 9372 @cindex Alt attribute for images | 9959 @cindex Alt attribute for images |
| 9373 @cindex Images, alternate text for | 9960 @cindex Images, alternate text for |
| 9374 @findex - (in image alt string) | 9961 @findex - (in image alt string) |
| 9375 For HTML output, @code{makeinfo} sets the @dfn{alt attribute} for | 9962 For HTML output, @code{makeinfo} sets the @dfn{alt attribute} for |
| 9376 inline images to the optional @var{alttext} (fourth) argument to | 9963 inline images to the optional @var{alttext} (fourth) argument to |
| 9377 @code{@@image}, if supplied. If not supplied, @code{makeinfo} uses | 9964 @code{@@image}, if supplied. If not supplied, @code{makeinfo} uses |
| 9378 the full file name of the image being displayed. The @var{alttext} is | 9965 the full file name of the image being displayed. The @var{alttext} is |
| 9379 taken as Texinfo text, so special characters such as @samp{"} and | 9966 processed as Texinfo text, so special characters such as @samp{"} and |
| 9380 @samp{<} and @samp{&} are escaped in the HTML and XML output; also, | 9967 @samp{<} and @samp{&} are escaped in the HTML output; also, you can |
| 9381 you can get an empty @code{alt} string with @code{@@-} (a command | 9968 get an empty @code{alt} string with @code{@@-} (a command that |
| 9382 that produces no output; @pxref{- and hyphenation}). | 9969 produces no output; @pxref{@t{@@- @@hyphenation}}). |
| 9383 | 9970 |
| 9384 For Info output, the @code{alt} string is also processed as Texinfo | 9971 For Info output, the @code{alt} string is also processed as Texinfo |
| 9385 text and output. In this case, @samp{\} is escaped as @samp{\\} and | 9972 text and output. In this case, @samp{\} is escaped as @samp{\\} and |
| 9386 @samp{"} as @samp{\"}; no other escapes are done. | 9973 @samp{"} as @samp{\"}; no other escapes are done. |
| 9387 | |
| 9388 @cindex PNG image format | |
| 9389 @cindex JPEG image format | |
| 9390 If you do not supply the optional @var{extension} (fifth) argument, | |
| 9391 @code{makeinfo} first tries @file{@var{filename}.png}; if that does | |
| 9392 not exist, it tries @file{@var{filename}.jpg}. If that does not exist | |
| 9393 either, it complains. | |
| 9394 | 9974 |
| 9395 In Info output, @code{makeinfo} writes a reference to the binary image | 9975 In Info output, @code{makeinfo} writes a reference to the binary image |
| 9396 file (trying @var{filename} suffixed with @file{@var{extension}}, | 9976 file (trying @var{filename} suffixed with @file{@var{extension}}, |
| 9397 @file{@var{.extension}}, @file{.png}, or @file{.jpg}, in that order) | 9977 @file{@var{.extension}}, @file{.png}, or @file{.jpg}, in that order) |
| 9398 if one exists. It also literally includes the @file{.txt} file if one | 9978 if one exists. It also literally includes the @file{.txt} file if one |
| 9428 @cindex Height of images | 10008 @cindex Height of images |
| 9429 @cindex Aspect ratio of images | 10009 @cindex Aspect ratio of images |
| 9430 @cindex Distorting images | 10010 @cindex Distorting images |
| 9431 The optional @var{width} and @var{height} arguments to the | 10011 The optional @var{width} and @var{height} arguments to the |
| 9432 @code{@@image} command (see the previous section) specify the size to | 10012 @code{@@image} command (see the previous section) specify the size to |
| 9433 scale the image to. They are ignored for Info output. If neither is | 10013 which to scale the image. They are only taken into account in @TeX{}. |
| 9434 specified, the image is presented in its natural size (given in the | 10014 If neither is specified, the image is presented in its natural size |
| 9435 file); if only one is specified, the other is scaled proportionately; | 10015 (given in the file); if only one is specified, the other is scaled |
| 9436 and if both are specified, both are respected, thus possibly distorting | 10016 proportionately; and if both are specified, both are respected, thus |
| 9437 the original image by changing its aspect ratio. | 10017 likely distorting the original image by changing its aspect ratio. |
| 9438 | 10018 |
| 9439 @cindex Dimensions and image sizes | 10019 @cindex Dimensions and image sizes |
| 9440 The @var{width} and @var{height} may be specified using any valid @TeX{} | 10020 The @var{width} and @var{height} may be specified using any valid @TeX{} |
| 9441 dimension, namely: | 10021 dimension, namely: |
| 9442 | 10022 |
| 9499 @section Footnotes | 10079 @section Footnotes |
| 9500 @cindex Footnotes | 10080 @cindex Footnotes |
| 9501 @findex footnote | 10081 @findex footnote |
| 9502 | 10082 |
| 9503 A @dfn{footnote} is for a reference that documents or elucidates the | 10083 A @dfn{footnote} is for a reference that documents or elucidates the |
| 9504 primary text.@footnote{A footnote should complement or expand upon | 10084 primary text.@footnote{A footnote should complement or expand upon the |
| 9505 the primary text, but a reader should not need to read a footnote to | 10085 primary text, but a reader should not need to read a footnote to |
| 9506 understand the primary text. For a thorough discussion of footnotes, | 10086 understand the primary text. For a thorough discussion of footnotes, |
| 9507 see @cite{The Chicago Manual of Style}, which is published by the | 10087 see @cite{The Chicago Manual of Style}, which is published by the |
| 9508 University of Chicago Press.} Footnotes are distracting; use them | 10088 University of Chicago Press.} Footnotes are distracting; use them |
| 9509 sparingly, if at all. Standard bibliographical references are better | 10089 sparingly at most, and it is best to avoid them completely. Standard |
| 9510 placed in a bibliography at the end of a document than in footnotes | 10090 bibliographical references are better placed in a bibliography at the |
| 9511 throughout. | 10091 end of a document instead of in footnotes throughout. |
| 9512 | 10092 |
| 9513 @menu | 10093 @menu |
| 9514 * Footnote Commands:: How to write a footnote in Texinfo. | 10094 * Footnote Commands:: How to write a footnote in Texinfo. |
| 9515 * Footnote Styles:: Controlling how footnotes appear in Info. | 10095 * Footnote Styles:: Controlling how footnotes appear in Info. |
| 9516 @end menu | 10096 @end menu |
| 9551 small, superscripted number; the text of the footnote appears at the | 10131 small, superscripted number; the text of the footnote appears at the |
| 9552 bottom of the page, below a horizontal line. | 10132 bottom of the page, below a horizontal line. |
| 9553 | 10133 |
| 9554 In Info, the reference mark for a footnote is a pair of parentheses | 10134 In Info, the reference mark for a footnote is a pair of parentheses |
| 9555 with the footnote number between them, like this: @samp{(1)}. The | 10135 with the footnote number between them, like this: @samp{(1)}. The |
| 9556 reference mark is followed by a cross-reference link to the footnote's | 10136 reference mark is followed by a cross reference link to the footnote |
| 9557 text. | 10137 text if footnotes are put in separate nodes (@pxref{Footnote Styles}). |
| 9558 | 10138 |
| 9559 In the HTML output, footnote references are marked with a small, | 10139 In the HTML output, footnote references are generally marked with a |
| 9560 superscripted number which is rendered as a hypertext link to the | 10140 small, superscripted number which is rendered as a hypertext link to |
| 9561 footnote text. | 10141 the footnote text. |
| 9562 | 10142 |
| 9563 By the way, footnotes in the argument of an @code{@@item} command for a | 10143 By the way, footnotes in the argument of an @code{@@item} command for |
| 9564 @code{@@table} must be on the same line as the @code{@@item} | 10144 an @code{@@table} must be on the same line as the @code{@@item} (as |
| 9565 (as usual). @xref{Two-column Tables}. | 10145 usual). @xref{Two-column Tables}. |
| 9566 | 10146 |
| 9567 | 10147 |
| 9568 @node Footnote Styles | 10148 @node Footnote Styles |
| 9569 @subsection Footnote Styles | 10149 @subsection Footnote Styles |
| 9570 | 10150 |
| 9572 footnote is located: | 10152 footnote is located: |
| 9573 | 10153 |
| 9574 @itemize @bullet | 10154 @itemize @bullet |
| 9575 @cindex @samp{@r{End}} node footnote style | 10155 @cindex @samp{@r{End}} node footnote style |
| 9576 @item | 10156 @item |
| 9577 In the `End' node style, all the footnotes for a single node | 10157 In the `End' node style, all the footnotes for a single node are |
| 9578 are placed at the end of that node. The footnotes are separated from | 10158 placed at the end of that node. The footnotes are separated from the |
| 9579 the rest of the node by a line of dashes with the word | 10159 rest of the node by a line of dashes with the word @samp{Footnotes} |
| 9580 @samp{Footnotes} within it. Each footnote begins with an | 10160 within it. Each footnote begins with an @samp{(@var{n})} reference |
| 9581 @samp{(@var{n})} reference mark. | 10161 mark. |
| 9582 | 10162 |
| 9583 @need 700 | 10163 @need 700 |
| 9584 @noindent | 10164 @noindent |
| 9585 Here is an example of a single footnote in the end of node style:@refill | 10165 Here is an example of the Info output for a single footnote in the |
| 10166 end-of-node style: | |
| 9586 | 10167 |
| 9587 @example | 10168 @example |
| 9588 @group | 10169 @group |
| 9589 --------- Footnotes --------- | 10170 --------- Footnotes --------- |
| 9590 | 10171 |
| 9643 @example | 10224 @example |
| 9644 @@footnotestyle separate | 10225 @@footnotestyle separate |
| 9645 @end example | 10226 @end example |
| 9646 | 10227 |
| 9647 Write an @code{@@footnotestyle} command before or shortly after the | 10228 Write an @code{@@footnotestyle} command before or shortly after the |
| 9648 end-of-header line at the beginning of a Texinfo file. (If you | 10229 end-of-header line at the beginning of a Texinfo file. (You should |
| 9649 include the @code{@@footnotestyle} command between the start-of-header | 10230 include any @code{@@footnotestyle} command between the start-of-header |
| 9650 and end-of-header lines, the region formatting commands will format | 10231 and end-of-header lines, so the region formatting commands will format |
| 9651 footnotes as specified.)@refill | 10232 footnotes as specified.) |
| 9652 | 10233 |
| 9653 If you do not specify a footnote style, the formatting commands use | 10234 In HTML, when the footnote style is @samp{end}, or if the output is |
| 9654 their default style. Currently, @code{texinfo-format-buffer} and | 10235 not split, footnotes are put at the end of the output. If set to |
| 9655 @code{texinfo-format-region} use the `separate' style and | 10236 @samp{separate}, and the output is split, they are placed in a |
| 9656 @code{makeinfo} uses the `end' style. | 10237 separate file. |
| 9657 | 10238 |
| 9658 | 10239 |
| 9659 @node Indices | 10240 @node Indices |
| 9660 @chapter Indices | 10241 @chapter Indices |
| 9661 @cindex Indices | 10242 @cindex Indices |
| 9665 alphabetical order, together with information on how to find the | 10246 alphabetical order, together with information on how to find the |
| 9666 discussion of each entry. In a printed manual, this information | 10247 discussion of each entry. In a printed manual, this information |
| 9667 consists of page numbers. In an Info file, this information is a menu | 10248 consists of page numbers. In an Info file, this information is a menu |
| 9668 entry leading to the first node referenced. | 10249 entry leading to the first node referenced. |
| 9669 | 10250 |
| 9670 Texinfo provides several predefined kinds of index: an index | 10251 Texinfo provides several predefined kinds of index: an index for |
| 9671 for functions, an index for variables, an index for concepts, and so | 10252 functions, an index for variables, an index for concepts, and so on. |
| 9672 on. You can combine indices or use them for other than their | 10253 You can combine indices or use them for other than their canonical |
| 9673 canonical purpose. Lastly, you can define your own new indices. | 10254 purpose. Lastly, you can define your own new indices. |
| 9674 | 10255 |
| 9675 @xref{Printing Indices & Menus}, for information on how to print | 10256 @xref{Printing Indices & Menus}, for information on how to print |
| 9676 indices. | 10257 indices. |
| 9677 | 10258 |
| 9678 @menu | 10259 @menu |
| 9692 | 10273 |
| 9693 When you are making index entries, it is good practice to think of the | 10274 When you are making index entries, it is good practice to think of the |
| 9694 different ways people may look for something. Different people | 10275 different ways people may look for something. Different people |
| 9695 @emph{do not} think of the same words when they look something up. A | 10276 @emph{do not} think of the same words when they look something up. A |
| 9696 helpful index will have items indexed under all the different words | 10277 helpful index will have items indexed under all the different words |
| 9697 that people may use. For example, one reader may think it obvious that | 10278 that people may use. For example, one reader may think it obvious |
| 9698 the two-letter names for indices should be listed under ``Indices, | 10279 that the two-letter names for indices should be listed under |
| 9699 two-letter names'', since the word ``Index'' is the general concept. | 10280 ``Indices, two-letter names, since ``Indices'' are the general |
| 9700 But another reader may remember the specific concept of two-letter | 10281 concept. But another reader may remember the specific concept of |
| 9701 names and search for the entry listed as ``Two letter names for | 10282 two-letter names and search for the entry listed as ``Two letter names |
| 9702 indices''. A good index will have both entries and will help both | 10283 for indices''. A good index will have both entries and will help both |
| 9703 readers.@refill | 10284 readers. |
| 9704 | 10285 |
| 9705 Like typesetting, the construction of an index is a highly skilled, | 10286 Like typesetting, the construction of an index is a skilled art, the |
| 9706 professional art, the subtleties of which are not appreciated until you | 10287 subtleties of which may not be appreciated until you need to do it |
| 9707 need to do it yourself.@refill | 10288 yourself. |
| 9708 | 10289 |
| 9709 @xref{Printing Indices & Menus}, for information about printing an index | 10290 @xref{Printing Indices & Menus}, for information about printing an |
| 9710 at the end of a book or creating an index menu in an Info file.@refill | 10291 index at the end of a book or creating an index menu in an Info file. |
| 9711 | 10292 |
| 9712 | 10293 |
| 9713 @node Predefined Indices | 10294 @node Predefined Indices |
| 9714 @section Predefined Indices | 10295 @section Predefined Indices |
| 9715 | 10296 |
| 9717 meanings, abbreviations, and the corresponding index entry commands: | 10298 meanings, abbreviations, and the corresponding index entry commands: |
| 9718 | 10299 |
| 9719 @table @samp | 10300 @table @samp |
| 9720 @item cp | 10301 @item cp |
| 9721 @cindex @code{cp} (concept) index | 10302 @cindex @code{cp} (concept) index |
| 10303 @findex cindex | |
| 9722 (@code{@@cindex}) concept index, for general concepts. | 10304 (@code{@@cindex}) concept index, for general concepts. |
| 9723 @item fn | 10305 @item fn |
| 9724 @cindex @code{fn} (function) index | 10306 @cindex @code{fn} (function) index |
| 10307 @findex findex | |
| 9725 (@code{@@findex}) function index, for function and function-like | 10308 (@code{@@findex}) function index, for function and function-like |
| 9726 names (such as entry points of libraries). | 10309 names (such as entry points of libraries). |
| 9727 @item ky | 10310 @item ky |
| 9728 @cindex @code{ky} (keystroke) index | 10311 @cindex @code{ky} (keystroke) index |
| 10312 @findex kindex | |
| 9729 (@code{@@kindex}) keystroke index, for keyboard commands. | 10313 (@code{@@kindex}) keystroke index, for keyboard commands. |
| 9730 @item pg | 10314 @item pg |
| 9731 @cindex @code{pg} (program) index | 10315 @cindex @code{pg} (program) index |
| 10316 @findex pindex | |
| 9732 (@code{@@pindex}) program index, for names of programs. | 10317 (@code{@@pindex}) program index, for names of programs. |
| 9733 @item tp | 10318 @item tp |
| 9734 @cindex @code{tp} (data type) index | 10319 @cindex @code{tp} (data type) index |
| 10320 @findex tindex | |
| 9735 (@code{@@tindex}) data type index, for type names (such as structures | 10321 (@code{@@tindex}) data type index, for type names (such as structures |
| 9736 defined in header files). | 10322 defined in header files). |
| 9737 @item vr | 10323 @item vr |
| 9738 @cindex @code{vr} (variable) index | 10324 @cindex @code{vr} (variable) index |
| 10325 @findex vindex | |
| 9739 (@code{@@vindex}) variable index, for variable names (such as global | 10326 (@code{@@vindex}) variable index, for variable names (such as global |
| 9740 variables of libraries). | 10327 variables of libraries). |
| 9741 @end table | 10328 @end table |
| 9742 | 10329 |
| 9743 @noindent | 10330 @noindent |
| 9767 @code{@@syncodeindex} commands (@pxref{Combining Indices}). | 10354 @code{@@syncodeindex} commands (@pxref{Combining Indices}). |
| 9768 | 10355 |
| 9769 | 10356 |
| 9770 @node Indexing Commands | 10357 @node Indexing Commands |
| 9771 @section Defining the Entries of an Index | 10358 @section Defining the Entries of an Index |
| 10359 | |
| 9772 @cindex Defining indexing entries | 10360 @cindex Defining indexing entries |
| 9773 @cindex Index entries | 10361 @cindex Index entries |
| 9774 @cindex Entries for an index | 10362 @cindex Entries for an index |
| 9775 @cindex Specifying index entries | 10363 @cindex Specifying index entries |
| 9776 @cindex Creating index entries | 10364 @cindex Creating index entries |
| 9777 | 10365 |
| 9778 The data to make an index come from many individual indexing commands | 10366 The data to make an index come from many individual indexing commands |
| 9779 scattered throughout the Texinfo source file. Each command says to add | 10367 scattered throughout the Texinfo source file. Each command says to add |
| 9780 one entry to a particular index; after formatting, the index will give | 10368 one entry to a particular index; after formatting, the index will give |
| 9781 the current page number or node name as the reference.@refill | 10369 the current page number or node name as the reference. |
| 9782 | 10370 |
| 9783 An index entry consists of an indexing command at the beginning of a | 10371 An index entry consists of an indexing command at the beginning of a |
| 9784 line followed, on the rest of the line, by the entry.@refill | 10372 line followed, on the rest of the line, by the entry. |
| 9785 | 10373 |
| 9786 For example, this section begins with the following five entries for | 10374 For example, this section begins with the following five entries for |
| 9787 the concept index:@refill | 10375 the concept index: |
| 9788 | 10376 |
| 9789 @example | 10377 @example |
| 9790 @@cindex Defining indexing entries | 10378 @@cindex Defining indexing entries |
| 9791 @@cindex Index entries, defining | 10379 @@cindex Index entries, defining |
| 9792 @@cindex Entries for an index | 10380 @@cindex Entries for an index |
| 9797 Each predefined index has its own indexing command---@code{@@cindex} | 10385 Each predefined index has its own indexing command---@code{@@cindex} |
| 9798 for the concept index, @code{@@findex} for the function index, and so | 10386 for the concept index, @code{@@findex} for the function index, and so |
| 9799 on, as listed in the previous section. | 10387 on, as listed in the previous section. |
| 9800 | 10388 |
| 9801 @cindex Writing index entries | 10389 @cindex Writing index entries |
| 9802 @cindex Index entry writing | 10390 @cindex Index entries, advice on writing |
| 10391 @cindex Advice on writing entries | |
| 10392 @cindex Capitalization of index entries | |
| 9803 Concept index entries consist of text. The best way to write an index | 10393 Concept index entries consist of text. The best way to write an index |
| 9804 is to choose entries that are terse yet clear. If you can do this, | 10394 is to devise entries which are terse yet clear. If you can do this, |
| 9805 the index often looks better if the entries are not capitalized, but | 10395 the index usually looks better if the entries are written just as they |
| 9806 written just as they would appear in the middle of a sentence. | 10396 would appear in the middle of a sentence, that is, capitalizing only |
| 9807 (Capitalize proper names and acronyms that always call for upper case | 10397 proper names and acronyms that always call for uppercase letters. |
| 9808 letters.) This is the case convention we use in most GNU manuals' | 10398 This is the case convention we use in most GNU manuals' indices. |
| 9809 indices. | |
| 9810 | 10399 |
| 9811 If you don't see how to make an entry terse yet clear, make it longer | 10400 If you don't see how to make an entry terse yet clear, make it longer |
| 9812 and clear---not terse and confusing. If many of the entries are several | 10401 and clear---not terse and confusing. If many of the entries are |
| 9813 words long, the index may look better if you use a different convention: | 10402 several words long, the index may look better if you use a different |
| 9814 to capitalize the first word of each entry. But do not capitalize a | 10403 convention: to capitalize the first word of each entry. Whichever |
| 9815 case-sensitive name such as a C or Lisp function name or a shell | 10404 case convention you use, use it consistently. |
| 9816 command; that would be a spelling error. | 10405 |
| 9817 | 10406 In any event, do not ever capitalize a case-sensitive name such as a C |
| 9818 Whichever case convention you use, please use it consistently! | 10407 or Lisp function name or a shell command; that would be a spelling |
| 9819 | 10408 error. Entries in indices other than the concept index are symbol |
| 9820 Entries in indices other than the concept index are symbol names in | 10409 names in programming languages, or program names; these names are |
| 9821 programming languages, or program names; these names are usually | 10410 usually case-sensitive, so likewise use upper- and lowercase as |
| 9822 case-sensitive, so use upper and lower case as required for them. | 10411 required. |
| 10412 | |
| 10413 @cindex Unique index entries | |
| 10414 It is a good idea to make index entries unique wherever feasible. | |
| 10415 That way, people using the printed output or online completion of | |
| 10416 index entries don't see undifferentiated lists. Consider this an | |
| 10417 opportunity to make otherwise-identical index entries be more | |
| 10418 specific, so readers can more easily find the exact place they are | |
| 10419 looking for. | |
| 10420 | |
| 10421 Index entries should precede the visible material that is being | |
| 10422 indexed. For instance: | |
| 10423 | |
| 10424 @example | |
| 10425 @@cindex hello | |
| 10426 Hello, there! | |
| 10427 @end example | |
| 10428 | |
| 10429 @noindent Among other reasons, that way following indexing links (in | |
| 10430 whatever context) ends up before the material, where readers want to | |
| 10431 be, instead of after. | |
| 9823 | 10432 |
| 9824 @cindex Index font types | 10433 @cindex Index font types |
| 9825 By default, entries for a concept index are printed in a small roman | 10434 By default, entries for a concept index are printed in a small roman |
| 9826 font and entries for the other indices are printed in a small | 10435 font and entries for the other indices are printed in a small |
| 9827 @code{@@code} font. You may change the way part of an entry is | 10436 @code{@@code} font. You may change the way part of an entry is |
| 9858 function names appear in the right font in the concept index, you | 10467 function names appear in the right font in the concept index, you |
| 9859 would need to enclose every one of them between the braces of | 10468 would need to enclose every one of them between the braces of |
| 9860 @code{@@code}. | 10469 @code{@@code}. |
| 9861 | 10470 |
| 9862 @menu | 10471 @menu |
| 9863 * syncodeindex:: How to merge two indices, using @code{@@code} | 10472 * @t{@@syncodeindex}:: How to merge two indices, using @code{@@code} |
| 9864 font for the merged-from index. | 10473 font for the merged-from index. |
| 9865 * synindex:: How to merge two indices, using the | 10474 * @t{@@synindex}:: How to merge two indices, using the |
| 9866 default font of the merged-to index. | 10475 roman font for the merged-from index. |
| 9867 @end menu | 10476 @end menu |
| 9868 | 10477 |
| 9869 @node syncodeindex | 10478 |
| 9870 @subsection @code{@@syncodeindex} | 10479 @node @t{@@syncodeindex} |
| 10480 @subsection @code{@@syncodeindex}: Combining indices using @code{@@code} | |
| 10481 | |
| 10482 @anchor{syncodeindex}@c old name | |
| 9871 @findex syncodeindex | 10483 @findex syncodeindex |
| 9872 | 10484 |
| 9873 When you want to combine functions and concepts into one index, you | 10485 When you want to combine functions and concepts into one index, you |
| 9874 should index the functions with @code{@@findex} and index the concepts | 10486 should index the functions with @code{@@findex} and index the concepts |
| 9875 with @code{@@cindex}, and use the @code{@@syncodeindex} command to | 10487 with @code{@@cindex}, and use the @code{@@syncodeindex} command to |
| 9876 redirect the function index entries into the concept index.@refill | 10488 redirect the function index entries into the concept index. |
| 9877 | 10489 |
| 9878 The @code{@@syncodeindex} command takes two arguments; they are the name | 10490 The @code{@@syncodeindex} command takes two arguments; they are the name |
| 9879 of the index to redirect, and the name of the index to redirect it to. | 10491 of the index to redirect, and the name of the index to redirect it to. |
| 9880 The template looks like this:@refill | 10492 The template looks like this: |
| 9881 | 10493 |
| 9882 @example | 10494 @example |
| 9883 @@syncodeindex @var{from} @var{to} | 10495 @@syncodeindex @var{from} @var{to} |
| 9884 @end example | 10496 @end example |
| 9885 | 10497 |
| 9886 @cindex Predefined names for indices | 10498 @cindex Predefined names for indices |
| 9887 @cindex Two letter names for indices | 10499 @cindex Two letter names for indices |
| 9888 @cindex Indices, two letter names | 10500 @cindex Indices, two letter names |
| 9889 @cindex Names for indices | 10501 @cindex Names for indices |
| 9890 For this purpose, the indices are given two-letter names:@refill | 10502 For this purpose, the indices are given two-letter names: |
| 9891 | 10503 |
| 9892 @table @samp | 10504 @table @samp |
| 9893 @item cp | 10505 @item cp |
| 9894 concept index | 10506 concept index |
| 9895 @item fn | 10507 @item fn |
| 9905 @end table | 10517 @end table |
| 9906 | 10518 |
| 9907 Write an @code{@@syncodeindex} command before or shortly after the | 10519 Write an @code{@@syncodeindex} command before or shortly after the |
| 9908 end-of-header line at the beginning of a Texinfo file. For example, | 10520 end-of-header line at the beginning of a Texinfo file. For example, |
| 9909 to merge a function index with a concept index, write the | 10521 to merge a function index with a concept index, write the |
| 9910 following:@refill | 10522 following: |
| 9911 | 10523 |
| 9912 @example | 10524 @example |
| 9913 @@syncodeindex fn cp | 10525 @@syncodeindex fn cp |
| 9914 @end example | 10526 @end example |
| 9915 | 10527 |
| 9916 @noindent | 10528 @noindent |
| 9917 This will cause all entries designated for the function index to merge | 10529 This will cause all entries designated for the function index to merge |
| 9918 in with the concept index instead.@refill | 10530 in with the concept index instead. |
| 9919 | 10531 |
| 9920 To merge both a variables index and a function index into a concept | 10532 To merge both a variables index and a function index into a concept |
| 9921 index, write the following:@refill | 10533 index, write the following: |
| 9922 | 10534 |
| 9923 @example | 10535 @example |
| 9924 @group | 10536 @group |
| 9925 @@syncodeindex vr cp | 10537 @@syncodeindex vr cp |
| 9926 @@syncodeindex fn cp | 10538 @@syncodeindex fn cp |
| 9931 The @code{@@syncodeindex} command puts all the entries from the `from' | 10543 The @code{@@syncodeindex} command puts all the entries from the `from' |
| 9932 index (the redirected index) into the @code{@@code} font, overriding | 10544 index (the redirected index) into the @code{@@code} font, overriding |
| 9933 whatever default font is used by the index to which the entries are | 10545 whatever default font is used by the index to which the entries are |
| 9934 now directed. This way, if you direct function names from a function | 10546 now directed. This way, if you direct function names from a function |
| 9935 index into a concept index, all the function names are printed in the | 10547 index into a concept index, all the function names are printed in the |
| 9936 @code{@@code} font as you would expect.@refill | 10548 @code{@@code} font as you would expect. |
| 9937 | 10549 |
| 9938 @node synindex | 10550 |
| 9939 @subsection @code{@@synindex} | 10551 @node @t{@@synindex} |
| 10552 @subsection @code{@@synindex}: Combining indices | |
| 10553 | |
| 10554 @anchor{synindex}@c old name | |
| 9940 @findex synindex | 10555 @findex synindex |
| 9941 | 10556 |
| 9942 The @code{@@synindex} command is nearly the same as the | 10557 The @code{@@synindex} command is nearly the same as the |
| 9943 @code{@@syncodeindex} command, except that it does not put the | 10558 @code{@@syncodeindex} command, except that it does not put the `from' |
| 9944 `from' index entries into the @code{@@code} font; rather it puts | 10559 index entries into the @code{@@code} font; rather it puts them in the |
| 9945 them in the roman font. Thus, you use @code{@@synindex} when you | 10560 roman font. Thus, you use @code{@@synindex} when you merge a concept |
| 9946 merge a concept index into a function index.@refill | 10561 index into a function index. |
| 9947 | 10562 |
| 9948 @xref{Printing Indices & Menus}, for information about printing an index | 10563 @xref{Printing Indices & Menus}, for information about printing an index |
| 9949 at the end of a book or creating an index menu in an Info file.@refill | 10564 at the end of a book or creating an index menu in an Info file. |
| 9950 | 10565 |
| 9951 | 10566 |
| 9952 @node New Indices | 10567 @node New Indices |
| 9953 @section Defining New Indices | 10568 @section Defining New Indices |
| 10569 | |
| 9954 @cindex Defining new indices | 10570 @cindex Defining new indices |
| 9955 @cindex Indices, defining new | 10571 @cindex Indices, defining new |
| 9956 @cindex New index defining | 10572 @cindex New index defining |
| 9957 @findex defindex | 10573 @findex defindex |
| 9958 @findex defcodeindex | 10574 @findex defcodeindex |
| 9959 | 10575 |
| 9960 In addition to the predefined indices, you may use the | 10576 In addition to the predefined indices (@pxref{Predefined Indices}), |
| 9961 @code{@@defindex} and @code{@@defcodeindex} commands to define new | 10577 you may use the @code{@@defindex} and @code{@@defcodeindex} commands |
| 9962 indices. These commands create new indexing @@-commands with which | 10578 to define new indices. These commands create new indexing @@-commands |
| 9963 you mark index entries. The @code{@@defindex} command is used like | 10579 with which you mark index entries. The @code{@@defindex} command is |
| 9964 this: | 10580 used like this: |
| 9965 | 10581 |
| 9966 @example | 10582 @example |
| 9967 @@defindex @var{name} | 10583 @@defindex @var{name} |
| 9968 @end example | 10584 @end example |
| 9969 | 10585 |
| 9970 The name of an index should be a two letter word, such as @samp{au}. | 10586 New index names are usually two-letter words, such as @samp{au}. |
| 9971 For example: | 10587 For example: |
| 9972 | 10588 |
| 9973 @example | 10589 @example |
| 9974 @@defindex au | 10590 @@defindex au |
| 9975 @end example | 10591 @end example |
| 9990 @end example | 10606 @end example |
| 9991 | 10607 |
| 9992 @noindent | 10608 @noindent |
| 9993 (Evidently, @samp{au} serves here as an abbreviation for ``author''.) | 10609 (Evidently, @samp{au} serves here as an abbreviation for ``author''.) |
| 9994 | 10610 |
| 9995 In general, Texinfo constructs the new indexing command by | 10611 Texinfo constructs the new indexing command by concatenating the name |
| 9996 concatenating the name of the index with @samp{index}; thus, defining | 10612 of the index with @samp{index}; thus, defining an @samp{xy} index |
| 9997 an @samp{xy} index leads to the automatic creation of an | 10613 leads to the automatic creation of an @code{@@xyindex} command. |
| 9998 @code{@@xyindex} command. | |
| 9999 | 10614 |
| 10000 Use the @code{@@printindex} command to print the index, as you do with | 10615 Use the @code{@@printindex} command to print the index, as you do with |
| 10001 the predefined indices. For example: | 10616 the predefined indices. For example: |
| 10002 | 10617 |
| 10003 @example | 10618 @example |
| 10009 @end group | 10624 @end group |
| 10010 @end example | 10625 @end example |
| 10011 | 10626 |
| 10012 The @code{@@defcodeindex} is like the @code{@@defindex} command, | 10627 The @code{@@defcodeindex} is like the @code{@@defindex} command, |
| 10013 except that, in the printed output, it prints entries in an | 10628 except that, in the printed output, it prints entries in an |
| 10014 @code{@@code} font by default instead of a roman font. | 10629 @code{@@code} font by default instead of a roman font. |
| 10015 | 10630 |
| 10016 You should define new indices before the end-of-header line of a | 10631 You should define new indices before the end-of-header line of a |
| 10017 Texinfo file, and (of course) before any @code{@@synindex} or | 10632 Texinfo file, and (of course) before any @code{@@synindex} or |
| 10018 @code{@@syncodeindex} commands (@pxref{Texinfo File Header}). | 10633 @code{@@syncodeindex} commands (@pxref{Texinfo File Header}). |
| 10634 | |
| 10635 As mentioned earlier (@pxref{Predefined Indices}), we recommend having | |
| 10636 a single index in the final document whenever possible, however many | |
| 10637 source indices you use, since then readers have only one place to | |
| 10638 look. | |
| 10639 | |
| 10640 When creating an index, @TeX{} creates a file whose extension is the | |
| 10641 name of the index (@pxref{Names of index files}). Therefore you | |
| 10642 should avoid using index names that collide with extensions used for | |
| 10643 other purposes, such as @samp{.aux} or @samp{.xml}. | |
| 10644 @command{makeinfo} already reports an error if a new index conflicts | |
| 10645 well-known extension name. | |
| 10019 | 10646 |
| 10020 | 10647 |
| 10021 @node Insertions | 10648 @node Insertions |
| 10022 @chapter Special Insertions | 10649 @chapter Special Insertions |
| 10023 @cindex Inserting special characters and symbols | 10650 @cindex Inserting special characters and symbols |
| 10029 | 10656 |
| 10030 @iftex | 10657 @iftex |
| 10031 These are: | 10658 These are: |
| 10032 | 10659 |
| 10033 @itemize @bullet | 10660 @itemize @bullet |
| 10034 @item @samp{@@} and braces and commas. | 10661 @item The Texinfo special characters: @samp{@@ @{@} , \ #}. |
| 10035 @item Whitespace within and around a sentence. | 10662 @item Whitespace within and around a sentence. |
| 10036 @item Accents. | 10663 @item Accents. |
| 10037 @item Dots and bullets. | 10664 @item Dots and bullets. |
| 10038 @item The @TeX{} logo and the copyright symbol. | 10665 @item The @TeX{} logo and the copyright symbol. |
| 10039 @item The euro and pounds currency symbols. | 10666 @item The euro and pounds currency symbols. |
| 10040 @item The degrees symbol. | 10667 @item The degrees symbol. |
| 10041 @item The minus sign. | 10668 @item The minus sign. |
| 10042 @item Mathematical expressions. | 10669 @item Mathematical expressions. |
| 10043 @item Glyphs for evaluation, macros, errors, etc. | 10670 @item Glyphs for examples of programming: evaluation, macros, errors, etc. |
| 10044 @item Footnotes. | 10671 @item Footnotes. |
| 10045 @item Images. | |
| 10046 @end itemize | 10672 @end itemize |
| 10047 @end iftex | 10673 @end iftex |
| 10048 | 10674 |
| 10049 @menu | 10675 @menu |
| 10050 * Atsign Braces Comma:: Inserting @@ and @{@} and ,. | 10676 * Special Characters:: Inserting @@ @{@} , \ # |
| 10051 * Inserting Quote Characters:: Inserting left and right quotes, in code. | 10677 * Inserting Quote Characters:: Inserting left and right quotes, in code. |
| 10052 * Inserting Space:: How to insert the right amount of space | 10678 * Inserting Space:: Inserting the right amount of whitespace. |
| 10053 within a sentence. | 10679 * Inserting Accents:: Inserting accents and special characters. |
| 10054 * Inserting Accents:: How to insert accents and special characters. | 10680 * Inserting Quotation Marks:: Inserting quotation marks. |
| 10055 * Inserting Quotation Marks:: How to insert quotation marks. | 10681 * Inserting Math:: Formatting mathematical expressions. |
| 10056 * Dots Bullets:: How to insert dots and bullets. | 10682 * Glyphs for Text:: Inserting Dots, bullets, currencies, etc. |
| 10057 * TeX and copyright:: How to insert the @TeX{} logo | 10683 * Glyphs for Programming:: Indicating results of evaluation, |
| 10058 and the copyright symbol. | |
| 10059 * euro:: How to insert the Euro currency symbol. | |
| 10060 * pounds:: How to insert the pounds currency symbol. | |
| 10061 * textdegree:: How to insert the degrees symbol. | |
| 10062 * minus:: How to insert a minus sign. | |
| 10063 * geq leq:: How to insert greater/less-than-or-equal signs. | |
| 10064 * math:: How to format a mathematical expression. | |
| 10065 * Click Sequences:: Inserting GUI usage sequences. | |
| 10066 * Glyphs:: How to indicate results of evaluation, | |
| 10067 expansion of macros, errors, etc. | 10684 expansion of macros, errors, etc. |
| 10068 @end menu | 10685 @end menu |
| 10069 | 10686 |
| 10070 | 10687 |
| 10071 @node Atsign Braces Comma | 10688 @node Special Characters |
| 10072 @section Inserting @@ and @{@} and @comma{} | 10689 @section Special Characters: Inserting @@ @{@} , \ # |
| 10690 @anchor{Braces Atsign}@c previous names for this node | |
| 10691 @anchor{Atsign Braces Comma} | |
| 10073 @cindex Special characters, inserting | 10692 @cindex Special characters, inserting |
| 10074 @cindex Commands to insert special characters | 10693 @cindex Commands to insert special characters |
| 10075 | 10694 |
| 10076 @samp{@@} and curly braces are special characters in Texinfo. To insert | 10695 @samp{@@} and curly braces are the basic special characters in |
| 10077 these characters so they appear in text, you must put an @samp{@@} in | 10696 Texinfo. To insert these characters so they appear in text, you must |
| 10078 front of these characters to prevent Texinfo from misinterpreting | 10697 put an @samp{@@} in front of these characters to prevent Texinfo from |
| 10079 them. | 10698 misinterpreting them. Alphabetic commands are also provided. |
| 10080 | 10699 |
| 10081 The comma `,' is a special character only in one uncommon context: | 10700 The other characters (comma, backslash, hash) are special only in |
| 10082 it separates arguments to commands that take multiple arguments. | 10701 restricted contexts, as explained in the respective sections. |
| 10083 | 10702 |
| 10084 @menu | 10703 @menu |
| 10085 * Inserting an Atsign:: | 10704 * Inserting an Atsign:: @code{@@@@}, @code{@@atchar@{@}}. |
| 10086 * Inserting Braces:: | 10705 * Inserting Braces:: @code{@@@{ @@@}}, @code{@@l rbracechar@{@}}. |
| 10087 * Inserting a Comma:: | 10706 * Inserting a Comma:: , and @code{@@comma@{@}}. |
| 10707 * Inserting a Backslash:: \ and @code{@@backslashchar@{@}}. | |
| 10708 * Inserting a Hashsign:: # and @code{@@hashchar@{@}}. | |
| 10088 @end menu | 10709 @end menu |
| 10089 | 10710 |
| 10090 | 10711 |
| 10091 @node Inserting an Atsign | 10712 @node Inserting an Atsign |
| 10092 @subsection Inserting `@@' with @code{@@@@} | 10713 @subsection Inserting `@@' with @code{@@@@} and @code{@@atchar@{@}} |
| 10714 @cindex At sign, inserting | |
| 10715 @cindex Inserting @@ @r{(literal @samp{@@})} | |
| 10093 @findex @@ @r{(literal @samp{@@})} | 10716 @findex @@ @r{(literal @samp{@@})} |
| 10094 @cindex Inserting @@ @r{(literal @samp{@@})} | 10717 @findex @@atchar@{@} @r{(literal @samp{@@})} |
| 10095 | 10718 |
| 10096 @code{@@@@} stands for a single @samp{@@} in either printed or Info | 10719 @code{@@@@} produces a single @samp{@@} character in the output. Do |
| 10097 output. | 10720 not put braces after an @code{@@@@} command. |
| 10098 | 10721 |
| 10099 Do not put braces after an @code{@@@@} command. | 10722 @code{@@atchar@{@}} also produces a single @samp{@@} character in the |
| 10723 output. It does need following braces, as usual for alphabetic | |
| 10724 commands. In inline conditionals (@pxref{Inline Conditionals}), it | |
| 10725 can be necessary to avoid using the literal @samp{@@} character in the | |
| 10726 source (and may be clearer in other contexts). | |
| 10100 | 10727 |
| 10101 | 10728 |
| 10102 @node Inserting Braces | 10729 @node Inserting Braces |
| 10103 @subsection Inserting `@{' and `@}' with @code{@@@{} and @code{@@@}} | 10730 @subsection Inserting `@{ `@}' with @code{@@@{ @@@}} and @code{@@l rbracechar@{@}} |
| 10104 @cindex Braces, inserting | 10731 |
| 10105 @findex @{ @r{(literal @samp{@{})} | 10732 @findex @{ @r{(literal @samp{@{})} |
| 10106 @findex @} @r{(literal @samp{@}})} | 10733 @findex @} @r{(literal @samp{@}})} |
| 10107 | 10734 @findex @@lbracechar@{@} @r{(literal @samp{@{})} |
| 10108 @code{@@@{} stands for a single @samp{@{} in either printed or Info | 10735 @findex @@rbracechar@{@} @r{(literal @samp{@}})} |
| 10109 output. | 10736 @cindex Braces, inserting |
| 10110 | 10737 |
| 10111 @code{@@@}} stands for a single @samp{@}} in either printed or Info | 10738 @code{@@@{} produces a single @samp{@{} in the output, and @code{@@@}} |
| 10112 output. | 10739 produces a single @samp{@}}. Do not put braces after either an |
| 10113 | 10740 @code{@@@{} or an @code{@@@}} command. |
| 10114 Do not put braces after either an @code{@@@{} or an @code{@@@}} | 10741 |
| 10115 command. | 10742 @code{@@lbracechar@{@}} and @code{@@rbracechar@{@}} also produce |
| 10743 single @samp{@{} and @samp{@}} characters in the output. They do need | |
| 10744 following braces, as usual for alphabetic commands. In inline | |
| 10745 conditionals (@pxref{Inline Conditionals}), it can be | |
| 10746 necessary to avoid using literal brace characters in the source (and | |
| 10747 may be clearer in other contexts). | |
| 10116 | 10748 |
| 10117 | 10749 |
| 10118 @node Inserting a Comma | 10750 @node Inserting a Comma |
| 10119 @subsection Inserting `,' with @code{@@comma@{@}} | 10751 @subsection Inserting `,' with @code{@@comma@{@}} |
| 10120 @cindex Commas, inserting | 10752 |
| 10121 @findex comma | 10753 @findex comma |
| 10754 @cindex Comma, inserting | |
| 10122 | 10755 |
| 10123 Ordinarily, a comma `,' is a normal character that can be simply typed | 10756 Ordinarily, a comma `,' is a normal character that can be simply typed |
| 10124 in your input where you need it. | 10757 in your input where you need it. |
| 10125 | 10758 |
| 10126 However, Texinfo uses the comma as a special character in one uncommon | 10759 However, Texinfo uses the comma as a special character only in one |
| 10127 context: some commands, such as @code{@@acronym} (@pxref{acronym}) and | 10760 context: to separate arguments to those Texinfo commands, such as |
| 10128 @code{@@xref} (@pxref{Cross References}), as well as user-defined | 10761 @code{@@acronym} (@pxref{@t{@@acronym}}) and @code{@@xref} |
| 10129 macros (@pxref{Defining Macros}), can take more than one argument. In | 10762 (@pxref{Cross References}), as well as user-defined macros |
| 10130 these cases, the comma character is used to separate arguments. | 10763 (@pxref{Defining Macros}), which take more than one argument. |
| 10131 | 10764 |
| 10132 Since a comma character would confuse Texinfo's parsing for these | 10765 Since a comma character would confuse Texinfo's parsing for these |
| 10133 commands, you must use the command @samp{@@comma@{@}} instead if you want | 10766 commands, you must use the command @samp{@@comma@{@}} instead if you want |
| 10134 to pass an actual comma. Here are some examples: | 10767 to pass an actual comma. Here are some examples: |
| 10135 | 10768 |
| 10137 @@acronym@{ABC, A Bizarre @@comma@{@}@} | 10770 @@acronym@{ABC, A Bizarre @@comma@{@}@} |
| 10138 @@xref@{Comma,, The @@comma@{@} symbol@} | 10771 @@xref@{Comma,, The @@comma@{@} symbol@} |
| 10139 @@mymac@{One argument@@comma@{@} containing a comma@} | 10772 @@mymac@{One argument@@comma@{@} containing a comma@} |
| 10140 @end example | 10773 @end example |
| 10141 | 10774 |
| 10142 Although @comma{} can be used nearly anywhere, there is no need for it | 10775 Although @samp{@@comma@{@}} can be used nearly anywhere, there is no |
| 10143 anywhere except in this unusual case. | 10776 need for it anywhere except in this unusual case. |
| 10777 | |
| 10778 (Incidentally, the name @samp{@@comma} lacks the @samp{char} suffix used | |
| 10779 in its companion commands only for historical reasons. It didn't seem | |
| 10780 important enough to define a synonym.) | |
| 10781 | |
| 10782 | |
| 10783 @node Inserting a Backslash | |
| 10784 @subsection Inserting `\' with @code{@@backslashchar@{@}} | |
| 10785 | |
| 10786 @findex backslash | |
| 10787 @cindex Backslash, inserting | |
| 10788 | |
| 10789 Ordinarily, a backslash `\' is a normal character in Texinfo that can | |
| 10790 be simply typed in your input where you need it. The result is to | |
| 10791 typeset the backslash from the typewriter font. | |
| 10792 | |
| 10793 However, Texinfo uses the backslash as a special character in one | |
| 10794 restricted context: to delimit formal arguments in the bodies of | |
| 10795 user-defined macros (@pxref{Defining Macros}). | |
| 10796 | |
| 10797 Due to the vagaries of macro argument parsing, it is more reliable to | |
| 10798 pass an alphabetic command that produces a backslash instead of using | |
| 10799 a literal \. Hence @code{@@backslashchar@{@}}. Here is an example | |
| 10800 macro call: | |
| 10801 | |
| 10802 @example | |
| 10803 @@mymac@{One argument@@backslashchar@{@} with a backslash@} | |
| 10804 @end example | |
| 10805 | |
| 10806 Texinfo documents may also use \ as a command character inside | |
| 10807 @code{@@math} (@pxref{Inserting Math}). In this case, @code{@@\} or | |
| 10808 @code{\backslash} produces a ``math'' backslash (from the math symbol | |
| 10809 font), while @code{@@backslashchar@{@}} produces a typewriter | |
| 10810 backslash as usual. | |
| 10811 | |
| 10812 Although @samp{@@backslashchar@{@}} can be used nearly anywhere, there | |
| 10813 is no need for it except in these unusual cases. | |
| 10814 | |
| 10815 | |
| 10816 @node Inserting a Hashsign | |
| 10817 @subsection Inserting `#' with @code{@@hashchar@{@}} | |
| 10818 | |
| 10819 @findex @@hashchar@{@} @r{(literal @samp{#})} | |
| 10820 @cindex Inserting # | |
| 10821 @cindex Hash sign, inserting | |
| 10822 | |
| 10823 Ordinarily, a hash `#' is a normal character in Texinfo that can be | |
| 10824 simply typed in your input where you need it. The result is to | |
| 10825 typeset the hash character from the current font. | |
| 10826 | |
| 10827 @cindex Number sign, inserting | |
| 10828 @cindex Octotherp, inserting | |
| 10829 @cindex Sharp sign (not), inserting | |
| 10830 This character has many other names, varying by locale, such as | |
| 10831 ``number sign'', ``pound'', and ``octothorp''. It is also sometimes | |
| 10832 called ``sharp'' or ``sharp sign'' since it vaguely resembles the | |
| 10833 musical symbol by that name. In situations where Texinfo is used, | |
| 10834 ``hash'' is the most common in our experience. | |
| 10835 | |
| 10836 However, Texinfo uses the hash character as a special character in one | |
| 10837 restricted context: to introduce the so-called @code{#line} directive | |
| 10838 and variants (@pxref{External Macro Processors}). | |
| 10839 | |
| 10840 So, in order to typeset an actual hash character in such a place (for | |
| 10841 example, in a program that needs documentation about @code{#line}), | |
| 10842 it's necessary to use @code{@@hashchar@{@}} or some other construct. | |
| 10843 Here's an example: | |
| 10844 | |
| 10845 @example | |
| 10846 @@hashchar@{@} 10 "example.c" | |
| 10847 @end example | |
| 10848 | |
| 10849 Although @samp{@@hashchar@{@}} can be used nearly anywhere, there | |
| 10850 is no need for it anywhere except this unusual case. | |
| 10144 | 10851 |
| 10145 | 10852 |
| 10146 @node Inserting Quote Characters | 10853 @node Inserting Quote Characters |
| 10147 @section Inserting Quote Characters | 10854 @section Inserting Quote Characters |
| 10148 | 10855 |
| 10160 readers are especially likely to cut and paste the text | 10867 readers are especially likely to cut and paste the text |
| 10161 verbatim---and, unfortunately, some document viewers will mangle these | 10868 verbatim---and, unfortunately, some document viewers will mangle these |
| 10162 characters. (The free PDF reader @command{xpdf} works fine, but other | 10869 characters. (The free PDF reader @command{xpdf} works fine, but other |
| 10163 PDF readers, both free and nonfree, have problems.) | 10870 PDF readers, both free and nonfree, have problems.) |
| 10164 | 10871 |
| 10165 If this is a concern for your document, Texinfo provides two special | 10872 If this is a concern for you, Texinfo provides these two commands: |
| 10166 settings via @code{@@set}: | 10873 |
| 10167 | 10874 @ftable @code |
| 10168 @table @code | 10875 @item @@codequoteundirected @var{on-off} |
| 10169 @item @@set txicodequoteundirected | 10876 @cindex undirected single quote |
| 10170 causes the output for the @code{'} character to be the undirected | 10877 causes the output for the @code{'} character in code environments to |
| 10171 single quote, like this: | 10878 be the undirected single quote, like this: |
| 10172 @set txicodequoteundirected | 10879 @set txicodequoteundirected on |
| 10173 @code{'}. | 10880 @code{'}. |
| 10174 @clear txicodequoteundirected | 10881 @set txicodequoteundirected off |
| 10175 | 10882 |
| 10176 @item @@set txicodequotebacktick | 10883 @item @@codequotebacktick @var{on-off} |
| 10177 Cause the output for the @code{`} character to be the standalone grave | 10884 @cindex backtick |
| 10178 accent, like this: | 10885 @cindex grave accent, standalone |
| 10179 @set txicodequotebacktick | 10886 causes the output for the @code{`} character in code environments to |
| 10887 be the backtick character (standalone grave accent), like this: | |
| 10888 @set txicodequotebacktick on | |
| 10180 @code{`}. | 10889 @code{`}. |
| 10181 @clear txicodequotebacktick | 10890 @set txicodequotebacktick off |
| 10182 | 10891 @end ftable |
| 10183 @end table | |
| 10184 | |
| 10185 @code{xyza`'bc} | |
| 10186 | 10892 |
| 10187 If you want these settings for only part of the document, | 10893 If you want these settings for only part of the document, |
| 10188 @code{@@clear} will restore the normal behavior, as in | 10894 @code{@@codequote... off} will restore the normal behavior, as in |
| 10189 @code{@@clear@tie{}txicodequoteundirected}. | 10895 @code{@@codequoteundirected off}. |
| 10190 | 10896 |
| 10191 These settings affect @code{@@code}, @code{@@example}, and | 10897 These settings affect @code{@@code}, @code{@@example}, @code{@@kbd}, |
| 10192 @code{@@verbatim}; they do not affect @code{@@samp}. (@xref{Useful | 10898 @code{@@samp}, @code{@@verb}, and @code{@@verbatim}. @xref{Useful |
| 10193 Highlighting}.) | 10899 Highlighting}. |
| 10900 | |
| 10901 This feature used to be controlled by @code{@@set} variable names; | |
| 10902 they are still supported, but the command interface is preferred. | |
| 10194 | 10903 |
| 10195 | 10904 |
| 10196 @node Inserting Space | 10905 @node Inserting Space |
| 10197 @section Inserting Space | 10906 @section Inserting Space |
| 10198 | 10907 |
| 10200 @cindex Spacing, inserting | 10909 @cindex Spacing, inserting |
| 10201 The following sections describe commands that control spacing of various | 10910 The following sections describe commands that control spacing of various |
| 10202 kinds within and after sentences. | 10911 kinds within and after sentences. |
| 10203 | 10912 |
| 10204 @menu | 10913 @menu |
| 10914 * Multiple Spaces:: Inserting multiple spaces. | |
| 10205 * Not Ending a Sentence:: Sometimes a . doesn't end a sentence. | 10915 * Not Ending a Sentence:: Sometimes a . doesn't end a sentence. |
| 10206 * Ending a Sentence:: Sometimes it does. | 10916 * Ending a Sentence:: Sometimes it does. |
| 10207 * Multiple Spaces:: Inserting multiple spaces. | 10917 * @t{@@frenchspacing}:: Specifying end-of-sentence spacing. |
| 10208 * frenchspacing:: Specifying end-of-sentence spacing. | 10918 * @t{@@dmn}:: Formatting a dimension. |
| 10209 * dmn:: How to format a dimension. | |
| 10210 @end menu | 10919 @end menu |
| 10211 | |
| 10212 | |
| 10213 @node Not Ending a Sentence | |
| 10214 @subsection Not Ending a Sentence | |
| 10215 | |
| 10216 @cindex Not ending a sentence | |
| 10217 @cindex Sentence non-ending punctuation | |
| 10218 @cindex Periods, inserting | |
| 10219 Depending on whether a period or exclamation point or question mark is | |
| 10220 inside or at the end of a sentence, less or more space is inserted after | |
| 10221 a period in a typeset manual. Since it is not always possible | |
| 10222 to determine when a period ends a sentence and when it is used | |
| 10223 in an abbreviation, special commands are needed in some circumstances. | |
| 10224 Usually, Texinfo can guess how to handle periods, so you do not need to | |
| 10225 use the special commands; you just enter a period as you would if you | |
| 10226 were using a typewriter, which means you put two spaces after the | |
| 10227 period, question mark, or exclamation mark that ends a sentence. | |
| 10228 | |
| 10229 @findex <colon> @r{(suppress end-of-sentence space)} | |
| 10230 Use the @code{@@:}@: command after a period, question mark, | |
| 10231 exclamation mark, or colon that should not be followed by extra space. | |
| 10232 For example, use @code{@@:}@: after periods that end abbreviations | |
| 10233 which are not at the ends of sentences. | |
| 10234 | |
| 10235 For example, | |
| 10236 | |
| 10237 @example | |
| 10238 foo vs.@@: bar | |
| 10239 foo vs. bar | |
| 10240 @end example | |
| 10241 | |
| 10242 @noindent | |
| 10243 @ifnottex | |
| 10244 produces | |
| 10245 @end ifnottex | |
| 10246 @iftex | |
| 10247 produces the following. If you look carefully at this printed output, | |
| 10248 you will see a little extraneous space after @samp{vs.}@: in the second | |
| 10249 line. | |
| 10250 @end iftex | |
| 10251 | |
| 10252 @quotation | |
| 10253 foo vs.@: bar @* | |
| 10254 foo vs. bar | |
| 10255 @end quotation | |
| 10256 | |
| 10257 @noindent | |
| 10258 @code{@@:} has no effect on the Info and HTML output. In Docbook and | |
| 10259 XML, the previous punctuation character (.?!:) is output as an entity | |
| 10260 instead of as the normal character: @samp{. ? ! | |
| 10261 :}. This gives further processors a chance to notice and not | |
| 10262 add the usual extra space. | |
| 10263 | |
| 10264 Do not put braces after @code{@@:} (or any non-alphabetic command). | |
| 10265 | |
| 10266 | |
| 10267 @node Ending a Sentence | |
| 10268 @subsection Ending a Sentence | |
| 10269 | |
| 10270 @cindex Ending a Sentence | |
| 10271 @cindex Sentence ending punctuation | |
| 10272 | |
| 10273 @findex . @r{(end of sentence)} | |
| 10274 @findex ! @r{(end of sentence)} | |
| 10275 @findex ? @r{(end of sentence)} | |
| 10276 Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an | |
| 10277 exclamation point, and @code{@@?}@: instead of a question mark at the end | |
| 10278 of a sentence that ends with a capital letter. Otherwise, @TeX{} | |
| 10279 will think the letter is an abbreviation and will not insert the correct | |
| 10280 end-of-sentence spacing. Here is an example: | |
| 10281 | |
| 10282 @example | |
| 10283 Give it to M.I.B. and to M.E.W@@. Also, give it to R.J.C@@. | |
| 10284 Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. | |
| 10285 @end example | |
| 10286 | |
| 10287 @noindent | |
| 10288 @ifnottex | |
| 10289 produces | |
| 10290 @end ifnottex | |
| 10291 @iftex | |
| 10292 produces the following. If you look carefully at this printed output, | |
| 10293 you will see a little more whitespace after the @samp{W} in the first | |
| 10294 line. | |
| 10295 @end iftex | |
| 10296 | |
| 10297 @quotation | |
| 10298 Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@.@* | |
| 10299 Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. | |
| 10300 @end quotation | |
| 10301 | |
| 10302 In the Info file output, @code{@@.}@: is equivalent to a simple | |
| 10303 @samp{.}; likewise for @code{@@!}@: and @code{@@?}@:. | |
| 10304 | |
| 10305 The meanings of @code{@@:} and @code{@@.}@: in Texinfo are designed to | |
| 10306 work well with the XEmacs sentence motion commands (@pxref{Sentences,,, | |
| 10307 xemacs, XEmacs User's Manual}). | |
| 10308 | |
| 10309 Do not put braces after any of these commands. | |
| 10310 | 10920 |
| 10311 | 10921 |
| 10312 @node Multiple Spaces | 10922 @node Multiple Spaces |
| 10313 @subsection Multiple Spaces | 10923 @subsection Multiple Spaces |
| 10314 | 10924 |
| 10317 @cindex Space, inserting horizontal | 10927 @cindex Space, inserting horizontal |
| 10318 @findex <space> | 10928 @findex <space> |
| 10319 @findex <tab> | 10929 @findex <tab> |
| 10320 @findex <newline> | 10930 @findex <newline> |
| 10321 | 10931 |
| 10322 Ordinarily, @TeX{} collapses multiple whitespace characters (space, tab, | 10932 Ordinarily, multiple whitespace characters (space, tab, and newline) |
| 10323 and newline) into a single space. Info output, on the other hand, | 10933 are collapsed into a single space. |
| 10324 preserves whitespace as you type it, except for changing a newline into | 10934 |
| 10325 a space; this is why it is important to put two spaces at the end of | 10935 Occasionally, you may want to produce several consecutive spaces, |
| 10326 sentences in Texinfo documents. | 10936 either for purposes of example (e.g., what your program does with |
| 10327 | |
| 10328 Occasionally, you may want to actually insert several consecutive | |
| 10329 spaces, either for purposes of example (what your program does with | |
| 10330 multiple spaces as input), or merely for purposes of appearance in | 10937 multiple spaces as input), or merely for purposes of appearance in |
| 10331 headings or lists. Texinfo supports three commands: | 10938 headings or lists. Texinfo supports three commands: |
| 10332 @code{@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all of | 10939 @code{@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all |
| 10333 which insert a single space into the output. (Here, | 10940 of which insert a single space into the output. (Here, |
| 10334 @code{@@@kbd{SPACE}} represents an @samp{@@} character followed by a | 10941 @code{@@@kbd{SPACE}} represents an @samp{@@} character followed by a |
| 10335 space, i.e., @samp{@@ }, and @kbd{TAB} and @kbd{NL} represent the tab | 10942 space, i.e., @samp{@@ }, @kbd{TAB} represents an actual tab character, |
| 10336 character and end-of-line, i.e., when @samp{@@} is the last character on | 10943 and @kbd{NL} represent the tab character and end-of-line, i.e., when |
| 10337 a line.) | 10944 @samp{@@} is the last character on a line.) |
| 10338 | 10945 |
| 10339 For example, | 10946 For example, |
| 10340 @example | 10947 @example |
| 10341 Spacey@@ @@ @@ @@ | 10948 Spacey@@ @@ @@ @@ |
| 10342 example. | 10949 example. |
| 10343 @end example | 10950 @end example |
| 10344 | 10951 |
| 10345 @noindent | 10952 @noindent produces |
| 10346 produces | |
| 10347 | 10953 |
| 10348 @example | 10954 @example |
| 10349 Spacey@ @ @ @ | 10955 Spacey@ @ @ @ |
| 10350 example. | 10956 example. |
| 10351 @end example | 10957 @end example |
| 10353 Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by | 10959 Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by |
| 10354 @code{@@multitable} (@pxref{Multi-column Tables}). | 10960 @code{@@multitable} (@pxref{Multi-column Tables}). |
| 10355 | 10961 |
| 10356 Do not follow any of these commands with braces. | 10962 Do not follow any of these commands with braces. |
| 10357 | 10963 |
| 10358 To produce a non-breakable space, see @ref{tie, @code{@@tie}}. | 10964 To produce a non-breakable space, see @ref{@t{@@tie}}. |
| 10359 | 10965 |
| 10360 | 10966 |
| 10361 @node frenchspacing | 10967 @node Not Ending a Sentence |
| 10362 @subsection @code{@@frenchspacing} @var{val}: Control sentence spacing | 10968 @subsection Not Ending a Sentence |
| 10969 | |
| 10970 @cindex Not ending a sentence | |
| 10971 @cindex Sentence non-ending punctuation | |
| 10972 @cindex Periods, inserting | |
| 10973 @cindex Spacing, in the middle of sentences | |
| 10974 Depending on whether a period or exclamation point or question mark is | |
| 10975 inside or at the end of a sentence, slightly less or more space is | |
| 10976 inserted after a period in a typeset manual. Since it is not always | |
| 10977 possible to determine automatically when a period ends a sentence, | |
| 10978 special commands are needed in some circumstances. Usually, Texinfo | |
| 10979 can guess how to handle periods, so you do not need to use the special | |
| 10980 commands; you just enter a period as you would if you were using a | |
| 10981 typewriter: put two spaces after the period, question mark, or | |
| 10982 exclamation mark that ends a sentence. | |
| 10983 | |
| 10984 @findex <colon> @r{(suppress end-of-sentence space)} | |
| 10985 Use the @code{@@:}@: command after a period, question mark, | |
| 10986 exclamation mark, or colon that should not be followed by extra space. | |
| 10987 For example, use @code{@@:}@: after periods that end (lowercase) | |
| 10988 abbreviations which are not at the ends of sentences. | |
| 10989 | |
| 10990 Also, when a parenthetical remark in the middle of a sentence (like | |
| 10991 this one!)@: ends with a period, exclamation point, or question mark, | |
| 10992 @code{@@:} should be used after the right parenthesis. Similarly for | |
| 10993 right brackets and right quotes (both single and double). | |
| 10994 | |
| 10995 For example, | |
| 10996 | |
| 10997 @example | |
| 10998 foo vs.@@: bar (or?)@@: baz | |
| 10999 foo vs. bar (or?) baz | |
| 11000 @end example | |
| 11001 | |
| 11002 @noindent | |
| 11003 @ifnottex | |
| 11004 produces | |
| 11005 @end ifnottex | |
| 11006 @iftex | |
| 11007 produces the following. If you look carefully at this printed output, | |
| 11008 you will see a bit of extraneous space after the @samp{vs.}@: and | |
| 11009 @samp{(or?)}@: in the second line. | |
| 11010 @end iftex | |
| 11011 | |
| 11012 @quotation | |
| 11013 foo vs.@: bar (or?)@: baz@* | |
| 11014 foo vs. bar (or?) baz | |
| 11015 @end quotation | |
| 11016 | |
| 11017 @noindent | |
| 11018 @code{@@:} has no effect on the HTML or Docbook output. | |
| 11019 | |
| 11020 Do not put braces after @code{@@:} (or any non-alphabetic command). | |
| 11021 | |
| 11022 A few Texinfo commands force normal interword spacing, so that you | |
| 11023 don't have to insert @code{@@:} where you otherwise would. These are | |
| 11024 the code-like highlighting commands, @code{@@var}, @code{@@abbr}, and | |
| 11025 @code{@@acronym} (@pxref{Useful Highlighting}). For example, in | |
| 11026 @samp{@@code@{foo. bar@}} the period is not considered the end of a | |
| 11027 sentence, and no extra space is inserted. | |
| 11028 | |
| 11029 | |
| 11030 @node Ending a Sentence | |
| 11031 @subsection Ending a Sentence | |
| 11032 | |
| 11033 @cindex Ending a Sentence | |
| 11034 @cindex Sentence ending punctuation | |
| 11035 | |
| 11036 @findex . @r{(end of sentence)} | |
| 11037 @findex ! @r{(end of sentence)} | |
| 11038 @findex ? @r{(end of sentence)} | |
| 11039 @cindex Spacing, at ends of sentences | |
| 11040 As mentioned above, Texinfo normally inserts additional space after | |
| 11041 the end of a sentence. It uses a simple heuristic for this: a | |
| 11042 sentence ends with a period, exclamation point, or question mark | |
| 11043 followed by optional closing punctuation and then whitespace, and | |
| 11044 @emph{not} preceded by a capital letter. | |
| 11045 | |
| 11046 Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an | |
| 11047 exclamation point, and @code{@@?}@: instead of a question mark at the | |
| 11048 end of a sentence that does end with a capital letter. For example: | |
| 11049 | |
| 11050 @example | |
| 11051 Give it to M.I.B. and to M.E.W@@. Also, give it to R.J.C@@. | |
| 11052 Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. | |
| 11053 @end example | |
| 11054 | |
| 11055 @noindent | |
| 11056 The output follows. In printed output and Info, you can see the | |
| 11057 desired extra whitespace after the @samp{W} in the first line. | |
| 11058 | |
| 11059 @quotation | |
| 11060 Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@.@* | |
| 11061 Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. | |
| 11062 @end quotation | |
| 11063 | |
| 11064 In the HTML output, @code{@@.}@: is equivalent to a simple @samp{.}; | |
| 11065 likewise for @code{@@!}@: and @code{@@?}@:. | |
| 11066 | |
| 11067 The meanings of @code{@@:} and @code{@@.}, etc.@: in Texinfo are | |
| 11068 designed to work well with the XEmacs sentence motion commands | |
| 11069 (@pxref{Sentences,,, xemacs, XEmacs User's Manual}). | |
| 11070 | |
| 11071 Do not put braces after any of these commands. | |
| 11072 | |
| 11073 A few Texinfo commands are not considered as being an abbreviation, | |
| 11074 even though they may end with a capital letter when expanded, so that | |
| 11075 you don't have to insert @code{@@.} and companions. This is the case | |
| 11076 for code-like highlighting commands, @code{@@var} arguments ending | |
| 11077 with a capital letter, and @code{@@TeX}. For example, that sentence | |
| 11078 ended with @samp{@@code@{@@@@TeX@}.}; @code{@@.} was not needed. Also | |
| 11079 in @code{... @@var@{VARNAME@}. Text} the period after @var{VARNAME} | |
| 11080 ends the sentence; there is no need to use @code{@@.}. | |
| 11081 | |
| 11082 | |
| 11083 @node @t{@@frenchspacing} | |
| 11084 @subsection @code{@@frenchspacing} @var{val}: Control Sentence Spacing | |
| 11085 | |
| 11086 @anchor{frenchspacing}@c old name | |
| 10363 @findex frenchspacing | 11087 @findex frenchspacing |
| 10364 @cindex French spacing | 11088 @cindex French spacing |
| 10365 @cindex Sentences, spacing after | 11089 @cindex Sentences, spacing after |
| 10366 @cindex Space, after sentences | 11090 @cindex Space, after sentences |
| 10367 | 11091 |
| 10368 In American typography, it is traditional and correct to put extra | 11092 In American typography, it is traditional and correct to put extra |
| 10369 space at the end of a sentence, after a semi-colon, and so on. This | 11093 space at the end of a sentence. This is the default in Texinfo |
| 10370 is the default in Texinfo. In French typography (and many others), | 11094 (implemented in Info and printed output; for HTML, we don't try to |
| 10371 this extra space is wrong; all spaces are uniform. | 11095 override the browser). In French typography (and others), this extra |
| 11096 space is wrong; all spaces are uniform. | |
| 10372 | 11097 |
| 10373 Therefore Texinfo provides the @code{@@frenchspacing} command to | 11098 Therefore Texinfo provides the @code{@@frenchspacing} command to |
| 10374 control the spacing after punctuation. It reads the rest of the line | 11099 control the spacing after punctuation. It reads the rest of the line |
| 10375 as its argument, which must be the single word @samp{on} or @samp{off} | 11100 as its argument, which must be the single word @samp{on} or @samp{off} |
| 10376 (always these words, regardless of the language) of the document. | 11101 (always these words, regardless of the language of the document). |
| 10377 Here is an example: | 11102 Here is an example: |
| 10378 | 11103 |
| 10379 @example | 11104 @example |
| 10380 @@frenchspacing on | 11105 @@frenchspacing on |
| 10381 This is text. Two sentences. Three sentences. French spacing. | 11106 This is text. Two sentences. Three sentences. French spacing. |
| 10382 | 11107 |
| 10383 @@frenchspacing off | 11108 @@frenchspacing off |
| 10384 This is text. Two sentences. Three sentences. Non-French spacing. | 11109 This is text. Two sentences. Three sentences. Non-French spacing. |
| 10385 @end example | 11110 @end example |
| 10386 | 11111 |
| 10387 @noindent produces (there will be no difference in Info): | 11112 @noindent produces: |
| 10388 | 11113 |
| 10389 @frenchspacing on | 11114 @frenchspacing on |
| 10390 This is text. Two sentences. Three sentences. French spacing. | 11115 This is text. Two sentences. Three sentences. French spacing. |
| 10391 | 11116 |
| 10392 @frenchspacing off | 11117 @frenchspacing off |
| 10393 This is text. Two sentences. Three sentences. Non-French spacing. | 11118 This is text. Two sentences. Three sentences. Non-French spacing. |
| 10394 | 11119 |
| 10395 @code{@@frenchspacing} mainly affects the printed output, including | 11120 @code{@@frenchspacing} also affects the output after @code{@@.}, |
| 10396 the output after @code{@@.}, @code{@@!}, and @code{@@?} (@pxref{Ending | 11121 @code{@@!}, and @code{@@?} (@pxref{Ending a Sentence}). |
| 10397 a Sentence}). | |
| 10398 | |
| 10399 In Info, usually space characters in the input are written unaltered | |
| 10400 to the output, and @code{@@frenchspacing} does not change this. It | |
| 10401 does change the one case where @command{makeinfo} outputs a space on | |
| 10402 its own: when a sentence ends at a newline in the source. Here's an | |
| 10403 example: | |
| 10404 | |
| 10405 @example | |
| 10406 Some sentence. | |
| 10407 Next sentence. | |
| 10408 @end example | |
| 10409 | |
| 10410 @noindent produces in Info output, with @code{@@frenchspacing off} | |
| 10411 (the default), two spaces between the sentences: | |
| 10412 | |
| 10413 @example | |
| 10414 Some sentence. Next sentence. | |
| 10415 @end example | |
| 10416 | |
| 10417 @noindent With @code{@@frenchspacing on}, @command{makeinfo} outputs | |
| 10418 only a single space: | |
| 10419 | |
| 10420 @example | |
| 10421 Some sentence. Next sentence. | |
| 10422 @end example | |
| 10423 | 11122 |
| 10424 @code{@@frenchspacing} has no effect on the HTML or Docbook output; | 11123 @code{@@frenchspacing} has no effect on the HTML or Docbook output; |
| 10425 for XML, it outputs a transliteration of itself (@pxref{Output | 11124 for XML, it outputs a transliteration of itself (@pxref{Output |
| 10426 Formats}). | 11125 Formats}). |
| 10427 | 11126 |
| 10428 | 11127 |
| 10429 @node dmn | 11128 @node @t{@@dmn} |
| 10430 @subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension | 11129 @subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension |
| 11130 | |
| 11131 @anchor{dmn}@c old name | |
| 10431 @cindex Thin space between number, dimension | 11132 @cindex Thin space between number, dimension |
| 10432 @cindex Dimension formatting | 11133 @cindex Dimension formatting |
| 10433 @cindex Format a dimension | 11134 @cindex Format a dimension |
| 10434 @findex dmn | 11135 @findex dmn |
| 10435 | 11136 |
| 10436 At times, you may want to write @samp{12@dmn{pt}} or | 11137 You can use the @code{@@dmn} command to format a dimension with a |
| 10437 @samp{8.5@dmn{in}} with little or no space between the number and the | 11138 little extra space in the printed output. That is, on seeing |
| 10438 abbreviation for the dimension. You can use the @code{@@dmn} command | 11139 @code{@@dmn}, @TeX{} inserts just enough space for proper typesetting; |
| 10439 to do this. On seeing the command, @TeX{} inserts just enough space | 11140 in other output formats, the formatting commands insert no space at |
| 10440 for proper typesetting; the Info formatting commands insert no space | 11141 all. |
| 10441 at all, since the Info file does not require it. | |
| 10442 | 11142 |
| 10443 To use the @code{@@dmn} command, write the number and then follow it | 11143 To use the @code{@@dmn} command, write the number and then follow it |
| 10444 immediately, with no intervening space, by @code{@@dmn}, and then by | 11144 immediately, with no intervening space, by @code{@@dmn}, and then by |
| 10445 the dimension within braces. For example, | 11145 the dimension within braces. For example, |
| 10446 | 11146 |
| 10453 | 11153 |
| 10454 @quotation | 11154 @quotation |
| 10455 A4 paper is 8.27@dmn{in} wide. | 11155 A4 paper is 8.27@dmn{in} wide. |
| 10456 @end quotation | 11156 @end quotation |
| 10457 | 11157 |
| 10458 Not everyone uses this style. Some people prefer @w{@samp{8.27 in.@@:}} | 11158 Not everyone uses this style. Some people prefer `8.27@tie{}in.'@: or |
| 10459 or @w{@samp{8.27 inches}} to @samp{8.27@@dmn@{in@}} in the Texinfo file. | 11159 `8.27@tie{}inches'. In these cases, however, you need to use |
| 10460 In these cases, however, the formatters may insert a line break between | 11160 @code{@@tie} (@pxref{@t{@@tie}}) or @code{@@w} (@pxref{@t{@@w}}) |
| 10461 the number and the dimension, so use @code{@@w} (@pxref{w}). Also, if | 11161 so that no line break can occur between the number and the dimension. |
| 10462 you write a period after an abbreviation within a sentence, you should | 11162 Also, if you write a period after an abbreviation within a sentence |
| 10463 write @samp{@@:} after the period to prevent @TeX{} from inserting extra | 11163 (as with the `in.'@: above), you should write @samp{@@:} after the |
| 10464 whitespace, as shown here. @xref{Not Ending a Sentence}. | 11164 period to prevent @TeX{} from inserting extra whitespace, as shown |
| 11165 here. @xref{Not Ending a Sentence}. | |
| 10465 | 11166 |
| 10466 | 11167 |
| 10467 @node Inserting Accents | 11168 @node Inserting Accents |
| 10468 @section Inserting Accents | 11169 @section Inserting Accents |
| 10469 | 11170 |
| 10490 | 11191 |
| 10491 @findex documentencoding | 11192 @findex documentencoding |
| 10492 To get the true accented characters output in Info, not just the ASCII | 11193 To get the true accented characters output in Info, not just the ASCII |
| 10493 transliterations, it is necessary to specify @code{@@documentencoding} | 11194 transliterations, it is necessary to specify @code{@@documentencoding} |
| 10494 with an encoding which supports the required characters | 11195 with an encoding which supports the required characters |
| 10495 (@pxref{documentencoding,,@code{@@documentencoding}}). In this case, | 11196 (@pxref{@t{@@documentencoding}}). In this case, you can also use |
| 10496 you can also use non-ASCII (e.g., pre-accented) characters in the | 11197 non-ASCII (e.g., pre-accented) characters in the source file. |
| 10497 source file. | |
| 10498 | 11198 |
| 10499 @findex " @r{(umlaut accent)} | 11199 @findex " @r{(umlaut accent)} |
| 10500 @cindex Umlaut accent | 11200 @cindex Umlaut accent |
| 10501 @findex ' @r{(umlaut accent)} | 11201 @findex ' @r{(umlaut accent)} |
| 10502 @cindex Acute accent | 11202 @cindex Acute accent |
| 10512 @cindex Cedilla accent | 11212 @cindex Cedilla accent |
| 10513 @findex dotaccent | 11213 @findex dotaccent |
| 10514 @cindex Dot accent | 11214 @cindex Dot accent |
| 10515 @findex H @r{(Hungarian umlaut accent)} | 11215 @findex H @r{(Hungarian umlaut accent)} |
| 10516 @cindex Hungarian umlaut accent | 11216 @cindex Hungarian umlaut accent |
| 11217 @findex ogonek | |
| 11218 @cindex Ogonek diacritic | |
| 10517 @findex ringaccent | 11219 @findex ringaccent |
| 10518 @cindex Ring accent | 11220 @cindex Ring accent |
| 10519 @findex tieaccent | 11221 @findex tieaccent |
| 10520 @cindex Tie-after accent | 11222 @cindex Tie-after accent |
| 10521 @findex u @r{(breve accent)} | 11223 @findex u @r{(breve accent)} |
| 10537 @item @t{@@^o} @tab @^o @tab circumflex accent | 11239 @item @t{@@^o} @tab @^o @tab circumflex accent |
| 10538 @item @t{@@`o} @tab @`o @tab grave accent | 11240 @item @t{@@`o} @tab @`o @tab grave accent |
| 10539 @item @t{@@~o} @tab @~o @tab tilde accent | 11241 @item @t{@@~o} @tab @~o @tab tilde accent |
| 10540 @item @t{@@dotaccent@{o@}} @tab @dotaccent{o} @tab overdot accent | 11242 @item @t{@@dotaccent@{o@}} @tab @dotaccent{o} @tab overdot accent |
| 10541 @item @t{@@H@{o@}} @tab @H{o} @tab long Hungarian umlaut | 11243 @item @t{@@H@{o@}} @tab @H{o} @tab long Hungarian umlaut |
| 11244 @item @t{@@ogonek@{a@}} @tab @ogonek{a} @tab ogonek | |
| 10542 @item @t{@@ringaccent@{o@}} @tab @ringaccent{o} @tab ring accent | 11245 @item @t{@@ringaccent@{o@}} @tab @ringaccent{o} @tab ring accent |
| 10543 @item @t{@@tieaccent@{oo@}} @tab @tieaccent{oo} @tab tie-after accent | 11246 @item @t{@@tieaccent@{oo@}} @tab @tieaccent{oo} @tab tie-after accent |
| 10544 @item @t{@@u@{o@}} @tab @u{o} @tab breve accent | 11247 @item @t{@@u@{o@}} @tab @u{o} @tab breve accent |
| 10545 @item @t{@@ubaraccent@{o@}} @tab @ubaraccent{o} @tab underbar accent | 11248 @item @t{@@ubaraccent@{o@}} @tab @ubaraccent{o} @tab underbar accent |
| 10546 @item @t{@@udotaccent@{o@}} @tab @udotaccent{o} @tab underdot accent | 11249 @item @t{@@udotaccent@{o@}} @tab @udotaccent{o} @tab underdot accent |
| 10560 @cindex @AA{} | 11263 @cindex @AA{} |
| 10561 @findex ae | 11264 @findex ae |
| 10562 @cindex @ae{} | 11265 @cindex @ae{} |
| 10563 @findex AE | 11266 @findex AE |
| 10564 @cindex @AE{} | 11267 @cindex @AE{} |
| 11268 @cindex Icelandic | |
| 11269 @cindex Eth | |
| 11270 @findex dh | |
| 11271 @cindex @dh{} | |
| 11272 @findex DH | |
| 11273 @cindex @DH{} | |
| 10565 @findex dotless | 11274 @findex dotless |
| 10566 @cindex @dotless{i} (dotless i) | 11275 @cindex @dotless{i} (dotless i) |
| 10567 @cindex @dotless{j} (dotless j) | 11276 @cindex @dotless{j} (dotless j) |
| 10568 @cindex Dotless i, j | 11277 @cindex Dotless i, j |
| 10569 @findex l | 11278 @findex l |
| 10589 @findex ss | 11298 @findex ss |
| 10590 @cindex @ss{} | 11299 @cindex @ss{} |
| 10591 @cindex Es-zet | 11300 @cindex Es-zet |
| 10592 @cindex Sharp S | 11301 @cindex Sharp S |
| 10593 @cindex German S | 11302 @cindex German S |
| 11303 @cindex Thorn | |
| 11304 @findex th | |
| 11305 @cindex @th{} | |
| 11306 @findex TH | |
| 11307 @cindex @TH{} | |
| 10594 @multitable {@t{@@questiondown@{@}}} {oe OE} {es-zet or sharp S} | 11308 @multitable {@t{@@questiondown@{@}}} {oe OE} {es-zet or sharp S} |
| 10595 @item @t{@@exclamdown@{@}} @tab @exclamdown{} @tab upside-down ! | 11309 @item @t{@@exclamdown@{@}} @tab @exclamdown{} @tab upside-down ! |
| 10596 @item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ? | 11310 @item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ? |
| 10597 @item @t{@@aa@{@} @@AA@{@}} @tab @aa{} @AA{} @tab a,A with circle | 11311 @item @t{@@aa@{@} @@AA@{@}} @tab @aa{} @AA{} @tab a,A with circle |
| 10598 @item @t{@@ae@{@} @@AE@{@}} @tab @ae{} @AE{} @tab ae,AE ligatures | 11312 @item @t{@@ae@{@} @@AE@{@}} @tab @ae{} @AE{} @tab ae,AE ligatures |
| 10599 @item @t{@@dotless@{i@}} @tab @dotless{i} @tab dotless i | 11313 @item @t{@@dh@{@} @@DH@{@}} @tab @dh{} @DH{} @tab Icelandic eth |
| 10600 @item @t{@@dotless@{j@}} @tab @dotless{j} @tab dotless j | 11314 @item @t{@@dotless@{i@}} @tab @dotless{i} @tab dotless i |
| 10601 @item @t{@@l@{@} @@L@{@}} @tab @l{} @L{} @tab suppressed-L,l | 11315 @item @t{@@dotless@{j@}} @tab @dotless{j} @tab dotless j |
| 10602 @item @t{@@o@{@} @@O@{@}} @tab @o{} @O{} @tab O,o with slash | 11316 @item @t{@@l@{@} @@L@{@}} @tab @l{} @L{} @tab suppressed-L,l |
| 10603 @item @t{@@oe@{@} @@OE@{@}} @tab @oe{} @OE{} @tab oe,OE ligatures | 11317 @item @t{@@o@{@} @@O@{@}} @tab @o{} @O{} @tab O,o with slash |
| 10604 @item @t{@@ordf@{@} @@ordm@{@}} @tab @ordf{} @ordm{} @tab Spanish ordinals | 11318 @item @t{@@oe@{@} @@OE@{@}} @tab @oe{} @OE{} @tab oe,OE ligatures |
| 10605 @item @t{@@ss@{@}} @tab @ss{} @tab es-zet or sharp S | 11319 @item @t{@@ordf@{@} @@ordm@{@}} @tab @ordf{} @ordm{} @tab Spanish ordinals |
| 11320 @item @t{@@ss@{@}} @tab @ss{} @tab es-zet or sharp S | |
| 11321 @item @t{@@th@{@} @@TH@{@}} @tab @th{} @TH{} @tab Icelandic thorn | |
| 10606 @end multitable | 11322 @end multitable |
| 10607 | 11323 |
| 10608 | 11324 |
| 10609 @node Inserting Quotation Marks | 11325 @node Inserting Quotation Marks |
| 10610 @section Inserting Quotation Marks | 11326 @section Inserting Quotation Marks |
| 10644 @cindex Latin 9 | 11360 @cindex Latin 9 |
| 10645 @cindex ISO 8859-1 | 11361 @cindex ISO 8859-1 |
| 10646 @cindex Latin 1 | 11362 @cindex Latin 1 |
| 10647 In order to get the symbols for the quotation marks in encoded Info | 11363 In order to get the symbols for the quotation marks in encoded Info |
| 10648 output, it is necessary to specify @code{@@documentencoding UTF-8}. | 11364 output, it is necessary to specify @code{@@documentencoding UTF-8}. |
| 10649 (@xref{documentencoding,,@code{@@documentencoding}}.) Double | 11365 (@xref{@t{@@documentencoding}}.) Double guillemets are also |
| 10650 guillemets are also present in ISO 8859-1 (aka Latin@tie{}1) and ISO | 11366 present in ISO 8859-1 (aka Latin@tie{}1) and ISO 8859-15 (aka |
| 10651 8859-15 (aka Latin@tie{}9). | 11367 Latin@tie{}9). |
| 10652 | 11368 |
| 10653 @cindex European Computer Modern fonts | 11369 @cindex European Computer Modern fonts |
| 10654 @cindex EC fonts | 11370 @cindex EC fonts |
| 10655 The standard @TeX{} fonts support the usual quotation marks used in | 11371 The standard @TeX{} fonts support the usual quotation marks used in |
| 10656 English (the ones produced with single and doubled ASCII | 11372 English (the ones produced with single and doubled ASCII |
| 10671 @cindex Single quotation marks | 11387 @cindex Single quotation marks |
| 10672 @cindex Double quotation marks | 11388 @cindex Double quotation marks |
| 10673 @cindex Left quotation marks | 11389 @cindex Left quotation marks |
| 10674 @cindex Right quotation marks | 11390 @cindex Right quotation marks |
| 10675 @findex quotedblleft | 11391 @findex quotedblleft |
| 10676 @cindex `` | 11392 @cindex `@w{}` |
| 10677 @findex quoteleft | 11393 @findex quoteleft |
| 10678 @cindex ` | 11394 @cindex ` |
| 11395 @cindex " (undirected double quote character) | |
| 10679 @findex quotedblright | 11396 @findex quotedblright |
| 10680 @cindex '' | 11397 @cindex '@w{}' |
| 10681 @findex quoteright | 11398 @findex quoteright |
| 10682 @cindex ' | 11399 @cindex ' |
| 10683 @cindex Double low-9 quotation mark | 11400 @cindex Double low-9 quotation mark |
| 10684 @cindex Single low-9 quotation mark | 11401 @cindex Single low-9 quotation mark |
| 10685 @findex quotedblbase | 11402 @findex quotedblbase |
| 10725 @item @t{@@guillemetright@{@}} @tab @guillemetright{} @tab Right-pointing double angle quotation mark (U+00BB) | 11442 @item @t{@@guillemetright@{@}} @tab @guillemetright{} @tab Right-pointing double angle quotation mark (U+00BB) |
| 10726 @item @t{@@guilsinglleft@{@}} @tab @guilsinglleft{} @tab Single left-pointing angle quotation mark (U+2039) | 11443 @item @t{@@guilsinglleft@{@}} @tab @guilsinglleft{} @tab Single left-pointing angle quotation mark (U+2039) |
| 10727 @item @t{@@guilsinglright@{@}} @tab @guilsinglright{} @tab Single right-pointing angle quotation mark (U+203A) | 11444 @item @t{@@guilsinglright@{@}} @tab @guilsinglright{} @tab Single right-pointing angle quotation mark (U+203A) |
| 10728 @end multitable | 11445 @end multitable |
| 10729 | 11446 |
| 11447 @cindex Auk, bird species | |
| 10730 For the double angle quotation marks, Adobe and @LaTeX{} glyph names | 11448 For the double angle quotation marks, Adobe and @LaTeX{} glyph names |
| 10731 are also supported: @code{@@guillemotleft} and | 11449 are also supported: @code{@@guillemotleft} and |
| 10732 @code{@@guillemotright}. These names are actually incorrect; a | 11450 @code{@@guillemotright}. These names are incorrect; a |
| 10733 ``guillemot'' is a bird species (a type of auk). | 11451 ``guillemot'' is a bird species (a type of auk). |
| 10734 | 11452 |
| 10735 Traditions for quotation mark usage vary to a great extent between | 11453 Traditions for quotation mark usage vary to a great extent between |
| 10736 languages (@url{http://@/en.wikipedia.org/@/wiki/@/Quotation_mark%2C_non-English_usage@/#Overview}). | 11454 languages |
| 11455 (@url{http://@/en.wikipedia.org/@/wiki/@/Quotation_mark%2C_non-English_usage@/#Overview}). | |
| 10737 Texinfo does not provide commands for typesetting quotation marks | 11456 Texinfo does not provide commands for typesetting quotation marks |
| 10738 according to the numerous traditions. Therefore, you have to choose | 11457 according to the numerous traditions. Therefore, you have to choose |
| 10739 the commands appropriate for the language of your manual. Sometimes | 11458 the commands appropriate for the language of your manual. Sometimes |
| 10740 aliases (@pxref{alias,,@code{@@alias}}) can simplify the usage and | 11459 aliases (@pxref{@t{@@alias}}) can simplify the usage and make the |
| 10741 make the source code more readable. For example, in German, | 11460 source code more readable. For example, in German, |
| 10742 @code{@@quotedblbase} is used for the left double quote, and the right | 11461 @code{@@quotedblbase} is used for the left double quote, and the right |
| 10743 double quote is actually @code{@@quotedblleft}, which is | 11462 double quote is the glyph produced by @code{@@quotedblleft}, which is |
| 10744 counter-intuitive. Thus, in this case the following aliases would be | 11463 counter-intuitive. Thus, in this case the following aliases would be |
| 10745 convenient: | 11464 convenient: |
| 10746 | 11465 |
| 10747 @example | 11466 @example |
| 10748 @@alias lgqq = quotedblbase | 11467 @@alias lgqq = quotedblbase |
| 10749 @@alias rgqq = quotedblleft | 11468 @@alias rgqq = quotedblleft |
| 10750 @end example | 11469 @end example |
| 10751 | 11470 |
| 10752 | 11471 |
| 10753 @node Dots Bullets | 11472 @node Inserting Math |
| 10754 @section Inserting Ellipsis and Bullets | 11473 @section @code{@@math}: Inserting Mathematical Expressions |
| 10755 @cindex Dots, inserting | 11474 |
| 10756 @cindex Bullets, inserting | 11475 @anchor{math}@c old name |
| 10757 @cindex Ellipsis, inserting | 11476 @findex math |
| 10758 @cindex Inserting ellipsis | 11477 @cindex Mathematical expressions, inserting |
| 10759 @cindex Inserting dots | 11478 @cindex Formulas, mathematical |
| 10760 @cindex Special typesetting commands | 11479 |
| 10761 @cindex Typesetting commands for dots, etc. | 11480 You can write a short mathematical expression with the @code{@@math} |
| 10762 | 11481 command. Write the mathematical expression between braces, like this: |
| 10763 An @dfn{ellipsis} (a line of dots) is not typeset as a string of | 11482 |
| 10764 periods, so a special command is used for ellipsis in Texinfo. The | 11483 @example |
| 10765 @code{@@bullet} command is special, too. Each of these commands is | 11484 @@math@{(a + b)(a + b) = a^2 + 2ab + b^2@} |
| 10766 followed by a pair of braces, @samp{@{@}}, without any whitespace | 11485 @end example |
| 10767 between the name of the command and the braces. (You need to use braces | 11486 |
| 10768 with these commands because you can use them next to other text; without | 11487 @iftex |
| 10769 the braces, the formatters would be confused. @xref{Command Syntax, , | 11488 @noindent This produces the following in @TeX{}: |
| 10770 @@-Command Syntax}, for further information.)@refill | 11489 |
| 11490 @display | |
| 11491 @math{(a + b)(a + b) = a^2 + 2ab + b^2} | |
| 11492 @end display | |
| 11493 | |
| 11494 @noindent and the following in other formats: | |
| 11495 @end iftex | |
| 11496 @ifnottex | |
| 11497 @noindent This produces the following in Info and HTML: | |
| 11498 @end ifnottex | |
| 11499 | |
| 11500 @example | |
| 11501 (a + b)(a + b) = a^2 + 2ab + b^2 | |
| 11502 @end example | |
| 11503 | |
| 11504 The @code{@@math} command has no special effect on the Info and HTML | |
| 11505 output. @command{makeinfo} expands any @@-commands as usual, | |
| 11506 but it does not try to produce good mathematical formatting in any | |
| 11507 way. | |
| 11508 | |
| 11509 However, as far as the @TeX{} output is concerned, plain @TeX{} | |
| 11510 mathematical commands are allowed in @code{@@math}, starting with | |
| 11511 @samp{\}, and the plain @TeX{} math characters like @samp{^} and | |
| 11512 @samp{_} are also recognized. In essence, @code{@@math} drops you | |
| 11513 into plain @TeX{} math mode. | |
| 11514 | |
| 11515 This allows you to conveniently write superscripts and subscripts (as | |
| 11516 in the above example), and also to use all the plain @TeX{} math | |
| 11517 control sequences for symbols, functions, and so on, and thus get | |
| 11518 proper formatting in the @TeX{} output, at least. | |
| 11519 | |
| 11520 It's best to use @samp{\} instead of @samp{@@} for any such | |
| 11521 mathematical commands; otherwise, @command{makeinfo} will complain. | |
| 11522 On the other hand, @command{makeinfo} allows input with matching (but | |
| 11523 unescaped) braces, such as @samp{k_@{75@}}, although it complains | |
| 11524 about such bare braces in regular input. | |
| 11525 | |
| 11526 Here's an example: | |
| 11527 | |
| 11528 @example | |
| 11529 @@math@{\sin 2\pi \equiv \cos 3\pi@} | |
| 11530 @end example | |
| 11531 | |
| 11532 @iftex | |
| 11533 @noindent which looks like this in @TeX{}: | |
| 11534 @display | |
| 11535 @math{\sin 2\pi \equiv \cos 3\pi} | |
| 11536 @end display | |
| 11537 | |
| 11538 @noindent and | |
| 11539 @end iftex | |
| 11540 @noindent which looks like the input in Info and HTML: | |
| 11541 @example | |
| 11542 \sin 2\pi \equiv \cos 3\pi | |
| 11543 @end example | |
| 11544 | |
| 11545 @findex \ @r{(literal \ in @code{@@math})} | |
| 11546 Since @samp{\} is an escape character inside @code{@@math}, you can | |
| 11547 use @code{@@\} to get a literal backslash (@code{\\} will work in | |
| 11548 @TeX{}, but you'd get the literal two characters @samp{\\} in Info). | |
| 11549 @code{@@\} is not defined outside of @code{@@math}, since a @samp{\} | |
| 11550 ordinarily produces a literal (typewriter) @samp{\}. You can also use | |
| 11551 @code{@@backslashchar@{@}} in any mode to get a typewriter backslash. | |
| 11552 @xref{Inserting a Backslash}. | |
| 11553 | |
| 11554 @cindex Displayed equations | |
| 11555 @cindex Equations, displayed | |
| 11556 For displayed equations, you must at present use @TeX{} directly | |
| 11557 (@pxref{Raw Formatter Commands}). | |
| 11558 | |
| 11559 | |
| 11560 @node Glyphs for Text | |
| 11561 @section Glyphs for Text | |
| 11562 | |
| 11563 @anchor{Glyphs}@c old name | |
| 11564 @anchor{TeX and copyright}@c another old node, now split into two | |
| 11565 @cindex Glyphs for text | |
| 11566 @cindex Textual glyphs | |
| 11567 | |
| 11568 Texinfo has support for a few additional glyphs that are commonly used | |
| 11569 in printed text but not available in ASCII@. Of course, there are | |
| 11570 many thousands more. It is possible to use Unicode characters as-is | |
| 11571 as far as @code{makeinfo} is concerned, but @TeX{} is not so lucky. | |
| 10771 | 11572 |
| 10772 @menu | 11573 @menu |
| 10773 * dots:: How to insert dots @dots{} | 11574 * @t{@@TeX @@LaTeX}:: The @TeX{} logos. |
| 10774 * bullet:: How to insert a bullet. | 11575 * @t{@@copyright}:: The copyright symbol (c in a circle). |
| 11576 * @t{@@registeredsymbol}:: The registered symbol (R in a circle). | |
| 11577 * @t{@@dots}:: How to insert ellipses: @dots{} and @enddots{} | |
| 11578 * @t{@@bullet}:: How to insert a bullet: @bullet{} | |
| 11579 * @t{@@euro}:: How to insert the euro currency symbol. | |
| 11580 * @t{@@pounds}:: How to insert the pounds currency symbol. | |
| 11581 * @t{@@textdegree}:: How to insert the degrees symbol. | |
| 11582 * @t{@@minus}:: How to insert a minus sign. | |
| 11583 * @t{@@geq @@leq}:: How to insert greater/less-than-or-equal signs. | |
| 10775 @end menu | 11584 @end menu |
| 10776 | 11585 |
| 10777 | 11586 |
| 10778 @node dots | 11587 @node @t{@@TeX @@LaTeX} |
| 10779 @subsection @code{@@dots}@{@} (@dots{}) and @code{@@enddots}@{@} (@enddots{}) | |
| 10780 @findex dots | |
| 10781 @findex enddots | |
| 10782 @cindex Inserting dots | |
| 10783 @cindex Dots, inserting | |
| 10784 | |
| 10785 Use the @code{@@dots@{@}} command to generate an ellipsis, which is | |
| 10786 three dots in a row, appropriately spaced @dots{} like so. Do | |
| 10787 not simply write three periods in the input file; that would work for | |
| 10788 the Info file output, but would produce the wrong amount of space | |
| 10789 between the periods in the printed manual. | |
| 10790 | |
| 10791 Similarly, the @code{@@enddots@{@}} command generates an | |
| 10792 end-of-sentence ellipsis, which has different spacing afterwards, | |
| 10793 @enddots{} Look closely to see the difference. | |
| 10794 | |
| 10795 @iftex | |
| 10796 Here is an ellipsis: @dots{} | |
| 10797 Here are three periods in a row: ... | |
| 10798 | |
| 10799 In printed output, the three periods in a row are much closer together than | |
| 10800 the dots in the ellipsis. | |
| 10801 @end iftex | |
| 10802 | |
| 10803 | |
| 10804 @node bullet | |
| 10805 @subsection @code{@@bullet}@{@} (@bullet{}) | |
| 10806 @findex bullet | |
| 10807 | |
| 10808 Use the @code{@@bullet@{@}} command to generate a large round dot, or | |
| 10809 the closest possible thing to one. In Info, an asterisk is used.@refill | |
| 10810 | |
| 10811 Here is a bullet: @bullet{} | |
| 10812 | |
| 10813 When you use @code{@@bullet} in @code{@@itemize}, you do not need to | |
| 10814 type the braces, because @code{@@itemize} supplies them. | |
| 10815 (@xref{itemize, , @code{@@itemize}}.)@refill | |
| 10816 | |
| 10817 | |
| 10818 @node TeX and copyright | |
| 10819 @section Inserting @TeX{} and Legal Symbols: @copyright{}, @registeredsymbol{} | |
| 10820 | |
| 10821 The logo `@TeX{}' is typeset in a special fashion and it needs an | |
| 10822 @@-command. The copyright and registered symbols, `@copyright{}' and | |
| 10823 `@registeredsymbol{}', is also special. Each of these commands is | |
| 10824 followed by a pair of braces, @samp{@{@}}, without any whitespace | |
| 10825 between the name of the command and the braces. | |
| 10826 | |
| 10827 @menu | |
| 10828 * tex:: The @TeX{} logos. | |
| 10829 * copyright symbol:: The copyright symbol (c in a circle). | |
| 10830 * registered symbol:: The registered symbol (R in a circle). | |
| 10831 @end menu | |
| 10832 | |
| 10833 | |
| 10834 @node tex | |
| 10835 @subsection @code{@@TeX}@{@} (@TeX{}) and @code{@@LaTeX}@{@} (@LaTeX{}) | 11588 @subsection @code{@@TeX}@{@} (@TeX{}) and @code{@@LaTeX}@{@} (@LaTeX{}) |
| 11589 | |
| 11590 @anchor{tex}@c old name | |
| 10836 @findex TeX | 11591 @findex TeX |
| 10837 @findex LaTeX | 11592 @findex LaTeX |
| 10838 @cindex Logos, @TeX{} | 11593 @cindex Logos, @TeX{} |
| 10839 @cindex @TeX{} logo | 11594 @cindex @TeX{} logo |
| 10840 @cindex @LaTeX{} logo | 11595 @cindex @LaTeX{} logo |
| 10848 incorrect @code{La@@TeX@{@}}. In Info, the result is just | 11603 incorrect @code{La@@TeX@{@}}. In Info, the result is just |
| 10849 @samp{LaTeX}. (@LaTeX{} is another macro package built on top of | 11604 @samp{LaTeX}. (@LaTeX{} is another macro package built on top of |
| 10850 @TeX{}, very loosely analogous to Texinfo in that it emphasizes | 11605 @TeX{}, very loosely analogous to Texinfo in that it emphasizes |
| 10851 logical structure, but much (much) larger.) | 11606 logical structure, but much (much) larger.) |
| 10852 | 11607 |
| 10853 The spelling of these commands are unusual among Texinfo commands in | 11608 The spelling of these commands are unusual for Texinfo, in that they |
| 10854 that they use both uppercase and lowercase letters. | 11609 use both uppercase and lowercase letters. |
| 10855 | 11610 |
| 10856 | 11611 |
| 10857 @node copyright symbol | 11612 @node @t{@@copyright} |
| 10858 @subsection @code{@@copyright@{@}} (@copyright{}) | 11613 @subsection @code{@@copyright@{@}} (@copyright{}) |
| 11614 | |
| 11615 @anchor{copyright symbol}@c old name | |
| 10859 @findex copyright | 11616 @findex copyright |
| 10860 @cindex Copyright symbol | 11617 @cindex Copyright symbol |
| 10861 | 11618 |
| 10862 Use the @code{@@copyright@{@}} command to generate the copyright | 11619 Use the @code{@@copyright@{@}} command to generate the copyright |
| 10863 symbol, `@copyright{}'. Where possible, this is a @samp{c} | 11620 symbol, `@copyright{}'. Where possible, this is a @samp{c} inside a |
| 10864 inside a circle; in Info, this is @samp{(C)}. | 11621 circle; in Info, this is @samp{(C)}. |
| 10865 | 11622 |
| 10866 | 11623 Legally, it's not necessary to use the copyright symbol; the English |
| 10867 @node registered symbol | 11624 word `Copyright' suffices, according to international treaty. |
| 11625 | |
| 11626 | |
| 11627 @node @t{@@registeredsymbol} | |
| 10868 @subsection @code{@@registeredsymbol@{@}} (@registeredsymbol{}) | 11628 @subsection @code{@@registeredsymbol@{@}} (@registeredsymbol{}) |
| 11629 | |
| 11630 @anchor{registered symbol}@c old name | |
| 10869 @findex registeredsymbol | 11631 @findex registeredsymbol |
| 10870 @cindex Registered symbol | 11632 @cindex Registered symbol |
| 10871 | 11633 |
| 10872 Use the @code{@@registeredsymbol@{@}} command to generate the | 11634 Use the @code{@@registeredsymbol@{@}} command to generate the |
| 10873 registered symbol, `@registeredsymbol{}'. Where possible, this is an | 11635 registered symbol, `@registeredsymbol{}'. Where possible, this is an |
| 10874 @samp{R} inside a circle; in Info, this is @samp{(R)}. | 11636 @samp{R} inside a circle; in Info, this is @samp{(R)}. |
| 10875 | 11637 |
| 10876 | 11638 |
| 10877 @node euro | 11639 @node @t{@@dots} |
| 10878 @section @code{@@euro}@{@} (@euro{}): Euro Currency Symbol | 11640 @subsection @code{@@dots} (@dots{}) and @code{@@enddots} (@enddots{}) |
| 11641 | |
| 11642 @anchor{dots}@c old name | |
| 11643 @findex dots | |
| 11644 @findex enddots | |
| 11645 @cindex Inserting dots | |
| 11646 @cindex Inserting ellipsis | |
| 11647 @cindex Dots, inserting | |
| 11648 @cindex Ellipsis, inserting | |
| 11649 | |
| 11650 @anchor{Dots Bullets}@c old name | |
| 11651 | |
| 11652 An @dfn{ellipsis} (a sequence of dots) would be spaced wrong when | |
| 11653 typeset as a string of periods, so a special command is used in | |
| 11654 Texinfo: use the @code{@@dots@{@}} command to generate a normal | |
| 11655 ellipsis, which is three dots in a row, appropriately spaced @dots{} | |
| 11656 like so. To emphasize: do not simply write three periods in the input | |
| 11657 file; that would work for the Info file output, but would produce the | |
| 11658 wrong amount of space between the periods in the printed manual. | |
| 11659 | |
| 11660 The @code{@@enddots@{@}} command generates an end-of-sentence | |
| 11661 ellipsis, which also has three dots, but with different spacing | |
| 11662 afterwards, @enddots{} Look closely to see the difference. | |
| 11663 | |
| 11664 Here is an ellipsis: @dots{} | |
| 11665 Here are three periods in a row: ... | |
| 11666 | |
| 11667 In printed (and usually HTML) output, the three periods in a row are | |
| 11668 much closer together than the dots in the ellipsis. | |
| 11669 | |
| 11670 | |
| 11671 @node @t{@@bullet} | |
| 11672 @subsection @code{@@bullet} (@bullet{}) | |
| 11673 | |
| 11674 @anchor{bullet}@c old name | |
| 11675 @findex bullet | |
| 11676 | |
| 11677 Use the @code{@@bullet@{@}} command to generate a large round dot, or | |
| 11678 the closest possible thing to one. In Info, an asterisk is used. | |
| 11679 Here is a bullet: @bullet{} | |
| 11680 | |
| 11681 When you use @code{@@bullet} in @code{@@itemize}, you do not need to | |
| 11682 type the braces, because @code{@@itemize} supplies them. | |
| 11683 (@pxref{@t{@@itemize}}). | |
| 11684 | |
| 11685 | |
| 11686 @node @t{@@euro} | |
| 11687 @subsection @code{@@euro} (@euro{}): Euro Currency Symbol | |
| 11688 | |
| 11689 @anchor{euro}@c old name | |
| 10879 @findex euro | 11690 @findex euro |
| 10880 @cindex Euro symbol | 11691 @cindex Euro symbol |
| 10881 | 11692 |
| 10882 Use the @code{@@euro@{@}} command to generate `@euro{}'. Where | 11693 Use the @code{@@euro@{@}} command to generate `@euro{}'. Where |
| 10883 possible, this is the symbol for the Euro currency, invented as part | 11694 possible, this is the symbol for the Euro currency. Otherwise, the |
| 10884 of the European economic unification. In plain Info, it is the word | 11695 word @samp{Euro} is used. |
| 10885 @samp{Euro }. A trailing space is included in the text | |
| 10886 transliteration since typically no space is desired after the symbol, | |
| 10887 so it would be inappropriate to have a space in the source document. | |
| 10888 | 11696 |
| 10889 Texinfo cannot magically synthesize support for the Euro symbol where | 11697 Texinfo cannot magically synthesize support for the Euro symbol where |
| 10890 the underlying system (fonts, software, whatever) does not support | 11698 the underlying system (fonts, software, whatever) does not support it. |
| 10891 it. Therefore, in many cases it is preferable to use the word | 11699 Therefore, you may find it preferable to use the word ``Euro''. (In |
| 10892 ``Euro''. (In banking circles, the abbreviation for the Euro is EUR.) | 11700 banking contexts, the abbreviation for the Euro is EUR.) |
| 10893 | 11701 |
| 10894 @cindex ISO 8859-15 | 11702 @cindex ISO 8859-15, and Euro |
| 10895 @cindex Latin 9 | 11703 @cindex Latin 9, and Euro |
| 10896 In order to get the Euro symbol in encoded Info output, for example, | 11704 In order to get the Euro symbol in encoded Info output, for example, |
| 10897 it is necessary to specify @code{@@documentencoding ISO-8859-15}. | 11705 it is necessary to specify @code{@@documentencoding ISO-8859-15} or |
| 10898 (@xref{documentencoding,,@code{@@documentencoding}}.) The Euro symbol | 11706 @code{@@documentencoding UTF-8} (@xref{@t{@@documentencoding}}.) |
| 10899 is in ISO 8859-15 (aka Latin@tie{}9), and is @emph{not} in the more | 11707 The Euro symbol is in ISO 8859-15 (aka Latin@tie{}9), and is |
| 10900 widely-used and supported ISO 8859-1 (Latin@tie{}1). | 11708 @emph{not} in the more widely-used ISO 8859-1 (Latin@tie{}1). |
| 10901 | 11709 |
| 10902 @pindex feymr10 | 11710 @pindex feymr10 |
| 10903 @cindex Euro font | 11711 @cindex Euro font |
| 10904 The Euro symbol does not exist in the standard @TeX{} fonts (which | 11712 The Euro symbol does not exist in the standard @TeX{} fonts (which |
| 10905 were designed before the Euro was legislated into existence). | 11713 were designed before the Euro was legislated into existence). |
| 10908 download it from @url{http://www.ctan.org/tex-archive/fonts/eurosym}, | 11716 download it from @url{http://www.ctan.org/tex-archive/fonts/eurosym}, |
| 10909 among other places. The distribution includes installation | 11717 among other places. The distribution includes installation |
| 10910 instructions. | 11718 instructions. |
| 10911 | 11719 |
| 10912 | 11720 |
| 10913 @node pounds | 11721 @node @t{@@pounds} |
| 10914 @section @code{@@pounds}@{@} (@pounds{}): Pounds Sterling | 11722 @subsection @code{@@pounds} (@pounds{}): Pounds Sterling |
| 11723 | |
| 11724 @anchor{pounds}@c old name | |
| 10915 @findex pounds | 11725 @findex pounds |
| 10916 @cindex Pounds symbol | 11726 @cindex Pounds symbol |
| 10917 | 11727 |
| 10918 Use the @code{@@pounds@{@}} command to generate `@pounds{}'. Where | 11728 Use the @code{@@pounds@{@}} command to generate `@pounds{}'. Where |
| 10919 possible, this is the symbol for the currency pounds sterling. In | 11729 possible, this is the symbol for the pounds sterling British currency. |
| 10920 Info, it is a @samp{#}. | 11730 Otherwise, it is @samp{#}. |
| 10921 | 11731 |
| 10922 | 11732 |
| 10923 @node textdegree | 11733 @node @t{@@textdegree} |
| 10924 @section @code{@@textdegree}@{@} (@textdegree{}): Degrees Symbol | 11734 @subsection @code{@@textdegree} (@textdegree{}): Degrees Symbol |
| 11735 | |
| 11736 @anchor{textdegree}@c old name | |
| 10925 @findex textdegree | 11737 @findex textdegree |
| 10926 @cindex Degree symbol | 11738 @cindex Degree symbol |
| 10927 | 11739 |
| 10928 Use the @code{@@textdegree@{@}} command to generate `@textdegree{}'. | 11740 Use the @code{@@textdegree@{@}} command to generate `@textdegree{}'. |
| 10929 Where possible, this is the normal symbol for degrees. In plain text | 11741 Where possible, this is the normal symbol for degrees. Otherwise, |
| 10930 and Info output, it is an @samp{o}. | 11742 it is an @samp{o}. |
| 10931 | 11743 |
| 10932 | 11744 |
| 10933 @node minus | 11745 @node @t{@@minus} |
| 10934 @section @code{@@minus}@{@} (@minus{}): Inserting a Minus Sign | 11746 @subsection @code{@@minus} (@minus{}): Inserting a Minus Sign |
| 11747 | |
| 11748 @anchor{minus}@c old name | |
| 10935 @findex minus | 11749 @findex minus |
| 10936 @cindex Minus sign | 11750 @cindex Minus sign |
| 10937 | 11751 |
| 10938 @cindex Em dash, compared to minus sign | 11752 @cindex Em dash, compared to minus sign |
| 10939 @cindex Hyphen, compared to minus | 11753 @cindex Hyphen, compared to minus |
| 10956 | 11770 |
| 10957 You should not use @code{@@minus@{@}} inside @code{@@code} or | 11771 You should not use @code{@@minus@{@}} inside @code{@@code} or |
| 10958 @code{@@example} because the width distinction is not made in the | 11772 @code{@@example} because the width distinction is not made in the |
| 10959 fixed-width font they use. | 11773 fixed-width font they use. |
| 10960 | 11774 |
| 10961 When you use @code{@@minus} to specify the mark beginning each entry in | 11775 When you use @code{@@minus} to specify the mark beginning each entry |
| 10962 an itemized list, you do not need to type the braces | 11776 in an itemized list, you do not need to type the braces |
| 10963 (@pxref{itemize, , @code{@@itemize}}). | 11777 (@pxref{@t{@@itemize}}). |
| 10964 | 11778 |
| 10965 | 11779 If you actually want to typeset some math that does a subtraction, it |
| 10966 @node geq leq | 11780 is better to use @code{@@math}. Then the regular @samp{-} character |
| 10967 @section @code{@@geq@{@}} (@geq{}) and @code{@@leq@{@}} (@leq{}): Inserting relations | 11781 produces a minus sign, as in @code{@@math@{a-b@}} (@pxref{Inserting |
| 11782 Math}). | |
| 11783 | |
| 11784 | |
| 11785 @node @t{@@geq @@leq} | |
| 11786 @subsection @code{@@geq} (@geq{}) and @code{@@leq} (@leq{}): Inserting Relations | |
| 11787 | |
| 11788 @anchor{geq leq}@c old name | |
| 10968 @findex geq | 11789 @findex geq |
| 10969 @findex leq | 11790 @findex leq |
| 10970 | 11791 |
| 10971 Use the @code{@@geq@{@}} and @code{@@geq@{@}} commands to generate | 11792 Use the @code{@@geq@{@}} and @code{@@leq@{@}} commands to generate |
| 10972 greater-than-or-equal and less-than-equal-signs, `@geq{}' and | 11793 greater-than-or-equal and less-than-equal-signs, `@geq{}' and |
| 10973 `@leq{}'. In plain text and Info output, these are the ASCII | 11794 `@leq{}'. When those symbols are not available, the ASCII sequences |
| 10974 sequences @samp{>=} and @samp{<=}. The | 11795 @samp{>=} and @samp{<=} are output. |
| 10975 | 11796 |
| 10976 | 11797 |
| 10977 @node math | 11798 @node Glyphs for Programming |
| 10978 @section @code{@@math}: Inserting Mathematical Expressions | 11799 @section Glyphs for Programming |
| 10979 @findex math | 11800 |
| 10980 @cindex Mathematical expressions | 11801 @cindex Glyphs for programming |
| 10981 @cindex Formulas, mathematical | |
| 10982 | |
| 10983 You can write a short mathematical expression with the @code{@@math} | |
| 10984 command. Write the mathematical expression between braces, like this: | |
| 10985 | |
| 10986 @example | |
| 10987 @@math@{(a + b)(a + b) = a^2 + 2ab + b^2@} | |
| 10988 @end example | |
| 10989 | |
| 10990 @iftex | |
| 10991 @noindent This produces the following in @TeX{}: | |
| 10992 | |
| 10993 @display | |
| 10994 @math{(a + b)(a + b) = a^2 + 2ab + b^2} | |
| 10995 @end display | |
| 10996 | |
| 10997 @noindent and the following in other formats: | |
| 10998 @end iftex | |
| 10999 @ifnottex | |
| 11000 @noindent This produces the following in Info and HTML: | |
| 11001 @end ifnottex | |
| 11002 | |
| 11003 @example | |
| 11004 (a + b)(a + b) = a^2 + 2ab + b^2 | |
| 11005 @end example | |
| 11006 | |
| 11007 The @code{@@math} command has no special effect on the Info and HTML | |
| 11008 output. @command{makeinfo} expands any @code{@@}-commands as usual, | |
| 11009 but it does not try to produce good mathematical formatting in any | |
| 11010 way. | |
| 11011 | |
| 11012 However, as far as the @TeX{} output is concerned, plain @TeX{} | |
| 11013 mathematical commands are allowed in @code{@@math}, starting with | |
| 11014 @samp{\}, and the plain @TeX{} math characters like @samp{^} and | |
| 11015 @samp{_} are also recognized. In essence, @code{@@math} drops you | |
| 11016 into plain @TeX{} math mode. | |
| 11017 | |
| 11018 This allows you to conveniently write superscripts and subscripts (as | |
| 11019 in the above example), and also to use all the plain @TeX{} math | |
| 11020 control sequences for symbols, functions, and so on, and thus get | |
| 11021 proper formatting in the @TeX{} output, at least. | |
| 11022 | |
| 11023 It's best to use @samp{\} instead of @samp{@@} for any such | |
| 11024 mathematical commands; otherwise, @command{makeinfo} will complain. | |
| 11025 On the other hand, input with matching (but unescaped) braces, such as | |
| 11026 @samp{k_@{75@}}, is allowed inside @code{@@math}, although | |
| 11027 @command{makeinfo} would complain about the bare braces in regular | |
| 11028 input. | |
| 11029 | |
| 11030 Here's an example: | |
| 11031 | |
| 11032 @example | |
| 11033 @@math@{\sin 2\pi \equiv \cos 3\pi@} | |
| 11034 @end example | |
| 11035 | |
| 11036 @iftex | |
| 11037 @noindent which looks like this in @TeX{}: | |
| 11038 @display | |
| 11039 @math{\sin 2\pi \equiv \cos 3\pi} | |
| 11040 @end display | |
| 11041 | |
| 11042 @noindent and | |
| 11043 @end iftex | |
| 11044 @noindent which looks like the input in Info and HTML: | |
| 11045 @example | |
| 11046 \sin 2\pi \equiv \cos 3\pi | |
| 11047 @end example | |
| 11048 | |
| 11049 @findex \ @r{(literal \ in @code{@@math})} | |
| 11050 Since @samp{\} is an escape character inside @code{@@math}, you can use | |
| 11051 @code{@@\} to get a literal backslash (@code{\\} will work in @TeX{}, | |
| 11052 but you'd get the literal @samp{\\} in Info). @code{@@\} is not | |
| 11053 defined outside of @code{@@math}, since a @samp{\} ordinarily produces a | |
| 11054 literal @samp{\}. | |
| 11055 | |
| 11056 @cindex Displayed equations | |
| 11057 @cindex Equations, displayed | |
| 11058 For displayed equations, you must at present use @TeX{} directly | |
| 11059 (@pxref{Raw Formatter Commands}). | |
| 11060 | |
| 11061 | |
| 11062 @node Click Sequences | |
| 11063 @section Click Sequences | |
| 11064 @cindex Click sequences | |
| 11065 @cindex Sequence of clicks | |
| 11066 @cindex GUI click sequence | |
| 11067 | |
| 11068 @findex clicksequence | |
| 11069 When documenting graphical interfaces, it is necessary to describe | |
| 11070 sequences such as `Click on @samp{File}, then choose @samp{Open}, then | |
| 11071 @dots{}'. Texinfo offers commands @code{@@clicksequence} and | |
| 11072 @code{click} to represent this, typically used like this: | |
| 11073 | |
| 11074 @example | |
| 11075 @dots{} @@clicksequence@{File @@click@{@} Open@} @dots{} | |
| 11076 @end example | |
| 11077 | |
| 11078 @noindent | |
| 11079 which produces: | |
| 11080 | |
| 11081 @display | |
| 11082 @dots{} @clicksequence{File @click{} Open} @dots{} | |
| 11083 @end display | |
| 11084 | |
| 11085 @findex click | |
| 11086 @findex arrow | |
| 11087 The @code{@@click} command produces a simple right arrow (@samp{->} in | |
| 11088 Info) by default; this glyph is also available independently via the | |
| 11089 command @code{@@arrow@{@}}. | |
| 11090 | |
| 11091 @findex clickstyle | |
| 11092 You can change the glyph produced by @code{@@click} with the command | |
| 11093 @code{@@clickstyle}, which takes a command name as its single argument | |
| 11094 on the rest of the line, much like @code{@@itemize} and friends | |
| 11095 (@pxref{itemize,,@code{@@itemize}}). The command should produce a | |
| 11096 glyph, and the usual empty braces @samp{@{@}} are omitted. Here's an | |
| 11097 example: | |
| 11098 | |
| 11099 @example | |
| 11100 @@clickstyle @@result | |
| 11101 @dots{} @@clicksequence@{File @@click@{@} Open@} @dots{} | |
| 11102 @end example | |
| 11103 | |
| 11104 @noindent | |
| 11105 now produces: | |
| 11106 | |
| 11107 @display | |
| 11108 @clickstyle @result | |
| 11109 @dots{} @clicksequence{File @click{} Open} @dots{} | |
| 11110 @end display | |
| 11111 | |
| 11112 | |
| 11113 @node Glyphs | |
| 11114 @section Glyphs for Examples | |
| 11115 @cindex Glyphs | |
| 11116 @cindex Examples, glyphs for | 11802 @cindex Examples, glyphs for |
| 11803 @cindex Programming, glyphs for | |
| 11117 | 11804 |
| 11118 In Texinfo, code is often illustrated in examples that are delimited | 11805 In Texinfo, code is often illustrated in examples that are delimited |
| 11119 by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and | 11806 by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and |
| 11120 @code{@@end lisp}. In such examples, you can indicate the results of | 11807 @code{@@end lisp}. In such examples, you can indicate the results of |
| 11121 evaluation or an expansion using @samp{@result{}} or | 11808 evaluation or an expansion using @samp{@result{}} or |
| 11122 @samp{@expansion{}}. Likewise, there are commands to insert glyphs | 11809 @samp{@expansion{}}. Likewise, there are commands to insert glyphs to |
| 11123 to indicate | 11810 indicate printed output, error messages, equivalence of expressions, |
| 11124 printed output, error messages, equivalence of expressions, and the | 11811 the location of point in an editor, and GUI operation sequences. |
| 11125 location of point. | 11812 |
| 11126 | 11813 The glyph-insertion commands do not need to be used within an example, |
| 11127 The glyph-insertion commands do not need to be used within an example, but | 11814 but most often they are. All glyph-insertion commands are followed by |
| 11128 most often they are. Every glyph-insertion command is followed by a pair of | 11815 empty braces. |
| 11129 left- and right-hand braces.@refill | |
| 11130 | 11816 |
| 11131 @menu | 11817 @menu |
| 11132 * Glyphs Summary:: | 11818 * Glyphs Summary:: |
| 11133 * result:: How to show the result of expression. | 11819 * @t{@@result}:: How to show the result of expression. |
| 11134 * expansion:: How to indicate an expansion. | 11820 * @t{@@expansion}:: How to indicate an expansion. |
| 11135 * Print Glyph:: How to indicate printed output. | 11821 * @t{@@print}:: How to indicate generated output. |
| 11136 * Error Glyph:: How to indicate an error message. | 11822 * @t{@@error}:: How to indicate an error message. |
| 11137 * Equivalence:: How to indicate equivalence. | 11823 * @t{@@equiv}:: How to indicate equivalence. |
| 11138 * Point Glyph:: How to indicate the location of point. | 11824 * @t{@@point}:: How to indicate the location of point. |
| 11825 * Click Sequences:: Inserting GUI usage sequences. | |
| 11139 @end menu | 11826 @end menu |
| 11140 | 11827 |
| 11141 | 11828 |
| 11142 @node Glyphs Summary | 11829 @node Glyphs Summary |
| 11143 @subsection Glyphs Summary | 11830 @subsection Glyphs Summary |
| 11144 | 11831 |
| 11145 Here are the different glyph commands:@refill | 11832 Here is a summary of the glyph commands: |
| 11146 | 11833 |
| 11147 @table @asis | 11834 @table @asis |
| 11148 @item @result{} | 11835 @item @result{} |
| 11149 @code{@@result@{@}} points to the result of an expression.@refill | 11836 @code{@@result@{@}} indicates the result of an expression. |
| 11150 | 11837 |
| 11151 @item @expansion{} | 11838 @item @expansion{} |
| 11152 @code{@@expansion@{@}} shows the results of a macro expansion.@refill | 11839 @code{@@expansion@{@}} indicates the results of a macro expansion. |
| 11153 | 11840 |
| 11154 @item @print{} | 11841 @item @print{} |
| 11155 @code{@@print@{@}} indicates printed output.@refill | 11842 @code{@@print@{@}} indicates printed output. |
| 11156 | 11843 |
| 11157 @item @error{} | 11844 @item @error{} |
| 11158 @code{@@error@{@}} indicates that the following text is an error | 11845 @code{@@error@{@}} indicates the following text is an error message. |
| 11159 message.@refill | |
| 11160 | 11846 |
| 11161 @item @equiv{} | 11847 @item @equiv{} |
| 11162 @code{@@equiv@{@}} indicates the exact equivalence of two forms.@refill | 11848 @code{@@equiv@{@}} indicates the exact equivalence of two forms. |
| 11163 | 11849 |
| 11164 @item @point{} | 11850 @item @point{} |
| 11165 @code{@@point@{@}} shows the location of point.@refill | 11851 @code{@@point@{@}} shows the location of point. |
| 11852 | |
| 11853 @item @clicksequence{A @click{} B} | |
| 11854 @code{@@clicksequence@{A @@click@{@} B} indicates a GUI operation | |
| 11855 sequence: first A, then clicking B, or choosing B from a menu, or | |
| 11856 otherwise selecting it. | |
| 11166 @end table | 11857 @end table |
| 11167 | 11858 |
| 11168 @menu | 11859 |
| 11169 * result:: | 11860 @node @t{@@result} |
| 11170 * expansion:: | 11861 @subsection @code{@@result@{@}} (@result{}): Result of an Expression |
| 11171 * Print Glyph:: | 11862 |
| 11172 * Error Glyph:: | 11863 @anchor{result}@c old name |
| 11173 * Equivalence:: | 11864 @findex result |
| 11174 * Point Glyph:: | |
| 11175 @end menu | |
| 11176 | |
| 11177 | |
| 11178 @node result | |
| 11179 @subsection @code{@@result@{@}} (@result{}): Indicating Evaluation | |
| 11180 @cindex Result of an expression | 11865 @cindex Result of an expression |
| 11181 @cindex Indicating evaluation | 11866 @cindex Indicating evaluation |
| 11182 @cindex Evaluation glyph | 11867 @cindex Evaluation glyph |
| 11183 @cindex Value of an expression, indicating | 11868 @cindex Value of an expression, indicating |
| 11184 @findex result | |
| 11185 | 11869 |
| 11186 Use the @code{@@result@{@}} command to indicate the result of | 11870 Use the @code{@@result@{@}} command to indicate the result of |
| 11187 evaluating an expression.@refill | 11871 evaluating an expression. |
| 11188 | 11872 |
| 11189 @iftex | 11873 The @code{@@result@{@}} command is displayed as @samp{@result{}}, |
| 11190 The @code{@@result@{@}} command is displayed as @samp{@result{}} in | 11874 either a double stemmed arrow or (when that is not available) the |
| 11191 the printed output and as @samp{=>} in other formats. | 11875 ASCII sequence @samp{=>}. |
| 11192 @end iftex | |
| 11193 @ifnottex | |
| 11194 The @code{@@result@{@}} command is displayed as @samp{@result{}} in | |
| 11195 Info and HTML and as a true double stemmed arrow in the printed output. | |
| 11196 @end ifnottex | |
| 11197 | 11876 |
| 11198 Thus, the following, | 11877 Thus, the following, |
| 11199 | 11878 |
| 11200 @lisp | 11879 @lisp |
| 11201 (cdr '(1 2 3)) | 11880 (cdr '(1 2 3)) |
| 11204 | 11883 |
| 11205 @noindent | 11884 @noindent |
| 11206 may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''. | 11885 may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''. |
| 11207 | 11886 |
| 11208 | 11887 |
| 11209 @node expansion | 11888 @node @t{@@expansion} |
| 11210 @subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion | 11889 @subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion |
| 11890 | |
| 11891 @anchor{expansion}@c old name | |
| 11211 @cindex Expansion, indicating | 11892 @cindex Expansion, indicating |
| 11212 @cindex Macro expansion, indicating | 11893 @cindex Macro expansion, indicating |
| 11213 @findex expansion | 11894 @findex expansion |
| 11214 | 11895 |
| 11215 When an expression is a macro call, it expands into a new expression. | 11896 When an expression is a macro call, it expands into a new expression. |
| 11216 You can indicate the result of the expansion with the | 11897 You can indicate the result of the expansion with the |
| 11217 @code{@@expansion@{@}} command.@refill | 11898 @code{@@expansion@{@}} command. |
| 11218 | 11899 |
| 11219 @iftex | 11900 The @code{@@expansion@{@}} command is displayed as |
| 11220 The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}} | 11901 @samp{@expansion{}}, either a long arrow with a flat base or (when |
| 11221 in the printed output and as @samp{==>} in other formats. | 11902 that is not available) the ASCII sequence @samp{==>}. |
| 11222 @end iftex | |
| 11223 @ifnottex | |
| 11224 The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}} | |
| 11225 in Info and HTML, and as a long arrow with a flat base in the printed | |
| 11226 output. | |
| 11227 @end ifnottex | |
| 11228 | 11903 |
| 11229 @need 700 | 11904 @need 700 |
| 11230 For example, the following | 11905 For example, the following |
| 11231 | 11906 |
| 11232 @example | 11907 @example |
| 11261 @noindent | 11936 @noindent |
| 11262 Often, as in this case, an example looks better if the | 11937 Often, as in this case, an example looks better if the |
| 11263 @code{@@expansion@{@}} and @code{@@result@{@}} commands are indented. | 11938 @code{@@expansion@{@}} and @code{@@result@{@}} commands are indented. |
| 11264 | 11939 |
| 11265 | 11940 |
| 11266 @node Print Glyph | 11941 @node @t{@@print} |
| 11267 @subsection @code{@@print@{@}} (@print{}): Indicating Printed Output | 11942 @subsection @code{@@print@{@}} (@print{}): Indicating Generated Output |
| 11943 | |
| 11944 @anchor{Print Glyph}@c old name | |
| 11945 @findex print | |
| 11268 @cindex Printed output, indicating | 11946 @cindex Printed output, indicating |
| 11269 @findex print | 11947 |
| 11270 | 11948 Sometimes an expression will generate output during its execution. |
| 11271 Sometimes an expression will print output during its execution. You | 11949 You can indicate such displayed output with the @code{@@print@{@}} |
| 11272 can indicate the printed output with the @code{@@print@{@}} command.@refill | 11950 command. |
| 11273 | 11951 |
| 11274 @iftex | 11952 The @code{@@print@{@}} command is displayed as @samp{@print{}}, either |
| 11275 The @code{@@print@{@}} command is displayed as @samp{-|} in Info and | 11953 a horizontal dash butting against a vertical bar or (when that is not |
| 11276 HTML and as @samp{@print{}} in the printed output. | 11954 available) the ASCII sequence @samp{-|}. |
| 11277 @end iftex | |
| 11278 @ifnottex | |
| 11279 The @code{@@print@{@}} command is displayed as @samp{@print{}} in Info | |
| 11280 and HTML and (similarly) as a horizontal dash butting against a | |
| 11281 vertical bar in the printed output. | |
| 11282 @end ifnottex | |
| 11283 | 11955 |
| 11284 In the following example, the printed text is indicated with | 11956 In the following example, the printed text is indicated with |
| 11285 @samp{@print{}}, and the value of the expression follows on the | 11957 @samp{@print{}}, and the value of the expression follows on the |
| 11286 last line. | 11958 last line. |
| 11287 | 11959 |
| 11307 @@end lisp | 11979 @@end lisp |
| 11308 @end group | 11980 @end group |
| 11309 @end lisp | 11981 @end lisp |
| 11310 | 11982 |
| 11311 | 11983 |
| 11312 @node Error Glyph | 11984 @node @t{@@error} |
| 11313 @subsection @code{@@error@{@}} (@error{}): Indicating an Error Message | 11985 @subsection @code{@@error@{@}} (@error{}): Indicating an Error Message |
| 11986 | |
| 11987 @anchor{Error Glyph}@c old name | |
| 11314 @cindex Error message, indicating | 11988 @cindex Error message, indicating |
| 11315 @findex error | 11989 @findex error |
| 11316 | 11990 |
| 11317 A piece of code may cause an error when you evaluate it. You can | 11991 A piece of code may cause an error when you evaluate it. You can |
| 11318 designate the error message with the @code{@@error@{@}} command.@refill | 11992 designate the error message with the @code{@@error@{@}} command. |
| 11319 | 11993 |
| 11320 @iftex | 11994 The @code{@@error@{@}} command is displayed as @samp{@error{}}, either |
| 11321 The @code{@@error@{@}} command is displayed as @samp{error-->} in Info | 11995 the word `error' in a box in the printed output, the word error |
| 11322 and HTML and as @samp{@error{}} in the printed output. | 11996 followed by an arrow in other formats or (when no arrow is available) |
| 11323 @end iftex | 11997 @samp{error-->}. |
| 11324 @ifnottex | |
| 11325 The @code{@@error@{@}} command is displayed as @samp{@error{}} in Info | |
| 11326 and HTML and as the word `error' in a box in the printed output. | |
| 11327 @end ifnottex | |
| 11328 | 11998 |
| 11329 @need 700 | 11999 @need 700 |
| 11330 Thus, | 12000 Thus, |
| 11331 | 12001 |
| 11332 @example | 12002 @example |
| 11350 | 12020 |
| 11351 @lisp | 12021 @lisp |
| 11352 Wrong type argument: integer-or-marker-p, x | 12022 Wrong type argument: integer-or-marker-p, x |
| 11353 @end lisp | 12023 @end lisp |
| 11354 | 12024 |
| 11355 @samp{@error{}} itself is not part of the error message. | 12025 The word @samp{@error{}} itself is not part of the error message. |
| 11356 | 12026 |
| 11357 | 12027 |
| 11358 @node Equivalence | 12028 @node @t{@@equiv} |
| 11359 @subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence | 12029 @subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence |
| 12030 | |
| 12031 @anchor{Equivalence}@c oldname | |
| 11360 @cindex Equivalence, indicating | 12032 @cindex Equivalence, indicating |
| 11361 @findex equiv | 12033 @findex equiv |
| 11362 | 12034 |
| 11363 Sometimes two expressions produce identical results. You can indicate the | 12035 Sometimes two expressions produce identical results. You can indicate |
| 11364 exact equivalence of two forms with the @code{@@equiv@{@}} command.@refill | 12036 the exact equivalence of two forms with the @code{@@equiv@{@}} |
| 11365 | 12037 command. The @code{@@equiv@{@}} command is displayed as |
| 11366 @iftex | 12038 @samp{@equiv{}}, either a standard mathematical equivalence sign |
| 11367 The @code{@@equiv@{@}} command is displayed as @samp{==} in Info and | 12039 (three parallel horizontal lines) or (when that is not available) as |
| 11368 HTML and as @samp{@equiv{}} in the printed output. | 12040 the ASCII sequence @samp{==}. |
| 11369 @end iftex | |
| 11370 @ifnottex | |
| 11371 The @code{@@equiv@{@}} command is displayed as @samp{@equiv{}} in Info | |
| 11372 and HTML and as a standard mathematical equivalence sign (three | |
| 11373 parallel horizontal lines) in the printed output. | |
| 11374 @end ifnottex | |
| 11375 | 12041 |
| 11376 Thus, | 12042 Thus, |
| 11377 | 12043 |
| 11378 @example | 12044 @example |
| 11379 @@lisp | 12045 @@lisp |
| 11391 @noindent | 12057 @noindent |
| 11392 This indicates that evaluating @code{(make-sparse-keymap)} produces | 12058 This indicates that evaluating @code{(make-sparse-keymap)} produces |
| 11393 identical results to evaluating @code{(list 'keymap)}. | 12059 identical results to evaluating @code{(list 'keymap)}. |
| 11394 | 12060 |
| 11395 | 12061 |
| 11396 @node Point Glyph | 12062 @node @t{@@point} |
| 11397 @subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer | 12063 @subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer |
| 12064 | |
| 12065 @anchor{Point Glyph}@c old name | |
| 11398 @cindex Point, indicating in a buffer | 12066 @cindex Point, indicating in a buffer |
| 11399 @findex point | 12067 @findex point |
| 11400 | 12068 |
| 11401 Sometimes you need to show an example of text in an XEmacs buffer. In | 12069 Sometimes you need to show an example of text in an XEmacs buffer. In |
| 11402 such examples, the convention is to include the entire contents of the | 12070 such examples, the convention is to include the entire contents of the |
| 11403 buffer in question between two lines of dashes containing the buffer | 12071 buffer in question between two lines of dashes containing the buffer |
| 11404 name.@refill | 12072 name. |
| 11405 | 12073 |
| 11406 You can use the @samp{@@point@{@}} command to show the location of point | 12074 You can use the @samp{@@point@{@}} command to show the location of |
| 11407 in the text in the buffer. (The symbol for point, of course, is not | 12075 point in the text in the buffer. (The symbol for point, of course, is |
| 11408 part of the text in the buffer; it indicates the place @emph{between} | 12076 not part of the text in the buffer; it indicates the place |
| 11409 two characters where point is located.)@refill | 12077 @emph{between} two characters where point is located.) |
| 11410 | 12078 |
| 11411 @iftex | 12079 The @code{@@point@{@}} command is displayed as @samp{@point{}}, either |
| 11412 The @code{@@point@{@}} command is displayed as @samp{-!-} in Info and | 12080 a pointed star or (when that is not available) the ASCII sequence |
| 11413 HTML and as @samp{@point{}} in the printed output. | 12081 @samp{-!-}. |
| 11414 @end iftex | |
| 11415 @ifnottex | |
| 11416 The @code{@@point@{@}} command is displayed as @samp{@point{}} in Info | |
| 11417 and HTML and as a small five pointed star in the printed | |
| 11418 output. | |
| 11419 @end ifnottex | |
| 11420 | 12082 |
| 11421 The following example shows the contents of buffer @file{foo} before | 12083 The following example shows the contents of buffer @file{foo} before |
| 11422 and after evaluating a Lisp command to insert the word @code{changed}.@refill | 12084 and after evaluating a Lisp command to insert the word @code{changed}. |
| 11423 | 12085 |
| 11424 @example | 12086 @example |
| 11425 @group | 12087 @group |
| 11426 ---------- Buffer: foo ---------- | 12088 ---------- Buffer: foo ---------- |
| 11427 This is the @point{}contents of foo. | 12089 This is the @point{}contents of foo. |
| 11439 ---------- Buffer: foo ---------- | 12101 ---------- Buffer: foo ---------- |
| 11440 | 12102 |
| 11441 @end group | 12103 @end group |
| 11442 @end example | 12104 @end example |
| 11443 | 12105 |
| 11444 In a Texinfo source file, the example is written like this:@refill | 12106 In a Texinfo source file, the example is written like this: |
| 11445 | 12107 |
| 11446 @example | 12108 @example |
| 11447 @@example | 12109 @@example |
| 11448 ---------- Buffer: foo ---------- | 12110 ---------- Buffer: foo ---------- |
| 11449 This is the @@point@{@}contents of foo. | 12111 This is the @@point@{@}contents of foo. |
| 11456 ---------- Buffer: foo ---------- | 12118 ---------- Buffer: foo ---------- |
| 11457 @@end example | 12119 @@end example |
| 11458 @end example | 12120 @end example |
| 11459 | 12121 |
| 11460 | 12122 |
| 12123 @node Click Sequences | |
| 12124 @subsection Click Sequences | |
| 12125 | |
| 12126 @cindex Click sequences | |
| 12127 @cindex Sequence of clicks | |
| 12128 @cindex GUI click sequence | |
| 12129 | |
| 12130 @findex clicksequence | |
| 12131 When documenting graphical interfaces, it is necessary to describe | |
| 12132 sequences such as `Click on @samp{File}, then choose @samp{Open}, then | |
| 12133 @dots{}'. Texinfo offers commands @code{@@clicksequence} and | |
| 12134 @code{click} to represent this, typically used like this: | |
| 12135 | |
| 12136 @example | |
| 12137 @dots{} @@clicksequence@{File @@click@{@} Open@} @dots{} | |
| 12138 @end example | |
| 12139 | |
| 12140 @noindent | |
| 12141 which produces: | |
| 12142 | |
| 12143 @display | |
| 12144 @dots{} @clicksequence{File @click{} Open} @dots{} | |
| 12145 @end display | |
| 12146 | |
| 12147 @findex click | |
| 12148 @findex arrow | |
| 12149 The @code{@@click} command produces a right arrow by default; this | |
| 12150 glyph is also available independently via the command | |
| 12151 @code{@@arrow@{@}}. | |
| 12152 | |
| 12153 @findex clickstyle | |
| 12154 You can change the glyph produced by @code{@@click} with the command | |
| 12155 @code{@@clickstyle}, which takes a command name as its single argument | |
| 12156 on the rest of the line, much like @code{@@itemize} and friends | |
| 12157 (@pxref{@t{@@itemize}}). The command should produce a glyph, and | |
| 12158 the usual empty braces @samp{@{@}} are omitted. Here's an example: | |
| 12159 | |
| 12160 @example | |
| 12161 @@clickstyle @@result | |
| 12162 @dots{} @@clicksequence@{File @@click@{@} Open@} @dots{} | |
| 12163 @end example | |
| 12164 | |
| 12165 @noindent | |
| 12166 now produces: | |
| 12167 | |
| 12168 @display | |
| 12169 @clickstyle @result | |
| 12170 @dots{} @clicksequence{File @click{} Open} @dots{} | |
| 12171 @end display | |
| 12172 | |
| 12173 | |
| 11461 @node Breaks | 12174 @node Breaks |
| 11462 @chapter Forcing and Preventing Breaks | 12175 @chapter Forcing and Preventing Breaks |
| 12176 | |
| 11463 @cindex Forcing line and page breaks | 12177 @cindex Forcing line and page breaks |
| 11464 @cindex Making line and page breaks | 12178 @cindex Making line and page breaks |
| 11465 @cindex Preventing line and page breaks | 12179 @cindex Preventing line and page breaks |
| 11466 | 12180 @cindex Line breaks, awkward |
| 11467 @cindex Line breaks | 12181 @cindex Page breaks, awkward |
| 11468 Usually, a Texinfo file is processed both by @TeX{} and by one of the | 12182 |
| 11469 Info formatting commands. Line, paragraph, or page breaks sometimes | 12183 Line and page breaks can sometimes occur in the `wrong' place in one |
| 11470 occur in the `wrong' place in one or other form of output. You must | 12184 or another form of output. It's up to you to ensure that text looks |
| 11471 ensure that text looks right both in the printed manual and in the | 12185 right in all the output formats. |
| 11472 Info file. | 12186 |
| 11473 | |
| 11474 @cindex White space, excessive | |
| 11475 @cindex Page breaks | |
| 11476 For example, in a printed manual, page breaks may occur awkwardly in | 12187 For example, in a printed manual, page breaks may occur awkwardly in |
| 11477 the middle of an example; to prevent this, you can hold text together | 12188 the middle of an example; to prevent this, you can hold text together |
| 11478 using a grouping command that keeps the text from being split across | 12189 using a grouping command that keeps the text from being split across |
| 11479 two pages. Conversely, you may want to force a page break where none | 12190 two pages. Conversely, you may want to force a page break where none |
| 11480 would occur normally. Fortunately, problems like these do not often | 12191 would occur normally. |
| 11481 arise. When they do, use the break, break prevention, or pagination | 12192 |
| 11482 commands. | 12193 You can use the break, break prevention, or pagination commands to fix |
| 12194 problematic line and page breaks. | |
| 11483 | 12195 |
| 11484 @menu | 12196 @menu |
| 11485 * Break Commands:: Summary of break-related commands. | 12197 * Break Commands:: Summary of break-related commands. |
| 11486 * Line Breaks:: Forcing line breaks. | 12198 * Line Breaks:: Forcing line breaks. |
| 11487 * - and hyphenation:: Helping @TeX{} with hyphenation points. | 12199 * @t{@@- @@hyphenation}:: Helping @TeX{} with hyphenation points. |
| 11488 * allowcodebreaks:: Controlling line breaks within @@code text. | 12200 * @t{@@allowcodebreaks}:: Controlling line breaks within @@code text. |
| 11489 * w:: Preventing unwanted line breaks in text. | 12201 * @t{@@w}:: Preventing unwanted line breaks in text. |
| 11490 * tie:: Inserting an unbreakable but varying space. | 12202 * @t{@@tie}:: Inserting an unbreakable but varying space. |
| 11491 * sp:: Inserting blank lines. | 12203 * @t{@@sp}:: Inserting blank lines. |
| 11492 * page:: Forcing the start of a new page. | 12204 * @t{@@page}:: Forcing the start of a new page. |
| 11493 * group:: Preventing unwanted page breaks. | 12205 * @t{@@group}:: Preventing unwanted page breaks. |
| 11494 * need:: Another way to prevent unwanted page breaks. | 12206 * @t{@@need}:: Another way to prevent unwanted page breaks. |
| 11495 @end menu | 12207 @end menu |
| 11496 | 12208 |
| 11497 | 12209 |
| 11498 @node Break Commands | 12210 @node Break Commands |
| 11499 @section Break Commands | 12211 @section Break Commands |
| 11517 These commands hold text together on a single line: | 12229 These commands hold text together on a single line: |
| 11518 | 12230 |
| 11519 @table @code | 12231 @table @code |
| 11520 @item @@w@{@var{text}@} | 12232 @item @@w@{@var{text}@} |
| 11521 Prevent @var{text} from being split and hyphenated across two lines. | 12233 Prevent @var{text} from being split and hyphenated across two lines. |
| 12234 | |
| 11522 @item @@tie@{@} | 12235 @item @@tie@{@} |
| 11523 Insert a normal interword space at which a line break may not occur. | 12236 Insert a normal interword space at which a line break may not occur. |
| 11524 @end table | 12237 @end table |
| 11525 @iftex | 12238 |
| 11526 @sp 1 | 12239 The pagination commands apply only to printed output, since other |
| 11527 @end iftex | 12240 output formats do not have pages. |
| 11528 | |
| 11529 The pagination commands apply only to printed output, since Info | |
| 11530 files do not have pages. | |
| 11531 | 12241 |
| 11532 @table @code | 12242 @table @code |
| 11533 @item @@page | 12243 @item @@page |
| 11534 Start a new page in the printed manual. | 12244 Start a new page. |
| 11535 | 12245 |
| 11536 @item @@group | 12246 @item @@group |
| 11537 Hold text together that must appear on one printed page. | 12247 Hold text together that must appear on one page. |
| 11538 | 12248 |
| 11539 @item @@need @var{mils} | 12249 @item @@need @var{mils} |
| 11540 Start a new printed page if not enough space on this one. | 12250 Start a new page if not enough space on this one. |
| 11541 @end table | 12251 @end table |
| 11542 | 12252 |
| 11543 | 12253 |
| 11544 @node Line Breaks | 12254 @node Line Breaks |
| 11545 @section @code{@@*} and @code{@@/}: Generate and Allow Line Breaks | 12255 @section @code{@@*} and @code{@@/}: Generate and Allow Line Breaks |
| 12256 | |
| 11546 @findex * @r{(force line break)} | 12257 @findex * @r{(force line break)} |
| 11547 @findex / @r{(allow line break)} | 12258 @findex / @r{(allow line break)} |
| 11548 @cindex Line breaks | 12259 @cindex Line breaks, controlling |
| 12260 @cindex Controlling line breaks | |
| 11549 @cindex Breaks in a line | 12261 @cindex Breaks in a line |
| 11550 @cindex Force line break | 12262 @cindex Force line break |
| 11551 @cindex Allow line break | 12263 @cindex Allow line break |
| 11552 | 12264 |
| 11553 The @code{@@*} command forces a line break in both the printed manual and | 12265 The @code{@@*} command forces a line break in all output formats. |
| 11554 in Info. The @code{@@/} command allows a line break (printed manual only). | 12266 The @code{@@/} command allows a line break (printed manual only). |
| 11555 | 12267 |
| 11556 Here is an example with @code{@@*}: | 12268 Here is an example with @code{@@*}: |
| 11557 | 12269 |
| 11558 @example | 12270 @example |
| 11559 This line @@* is broken @@*in two places. | 12271 This sentence is broken @@*into two lines. |
| 11560 @end example | 12272 @end example |
| 11561 | 12273 |
| 11562 @noindent produces | 12274 @noindent produces |
| 11563 | 12275 |
| 11564 @example | 12276 @example |
| 11565 @group | 12277 @group |
| 11566 This line | 12278 This sentence is broken |
| 11567 is broken | 12279 into two lines. |
| 11568 in two places. | |
| 11569 @end group | 12280 @end group |
| 11570 @end example | 12281 @end example |
| 11571 | 12282 |
| 11572 The @code{@@/} command can be useful within a url | 12283 The @code{@@/} command can often be useful within urls |
| 11573 (@pxref{uref,,@code{@@uref}}), which tend to be long and are otherwise | 12284 (@pxref{@t{@@url}}), which tend to be long and are otherwise |
| 11574 unbreakable. For example: | 12285 unbreakable. For example: |
| 11575 | 12286 |
| 11576 @example | 12287 @example |
| 11577 The official Texinfo home page is on the GNU web site: | 12288 The official Texinfo home page is on the GNU web site: |
| 11578 @@uref@{http://www.gnu.org/@@/software/@@/gnu/@@/texinfo@}. | 12289 @@uref@{http://www.gnu.org/@@/software/@@/gnu/@@/texinfo@}. |
| 11579 @end example | 12290 @end example |
| 11580 | 12291 |
| 11581 @noindent produces | 12292 @noindent produces |
| 11582 | 12293 |
| 11583 @display | 12294 @quotation |
| 11584 The official Texinfo home page is on the GNU web site: | 12295 The official Texinfo home page is on the GNU web site: |
| 11585 @uref{http://www.gnu.org/@/software/@/gnu/@/texinfo}. | 12296 @uref{http://www.gnu.org/@/software/@/gnu/@/texinfo}. |
| 11586 @end display | 12297 @end quotation |
| 11587 | 12298 |
| 11588 @noindent Without the @code{@@/} commands, @TeX{} would have nowhere to | 12299 @noindent Without the @code{@@/} commands, @TeX{} would have nowhere to |
| 11589 break the line. @code{@@/} has no effect in the online output. | 12300 break the url. @code{@@/} has no effect in other output formats. |
| 11590 | 12301 |
| 11591 | 12302 |
| 11592 @node - and hyphenation | 12303 @node @t{@@- @@hyphenation} |
| 11593 @section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} Hyphenate | 12304 @section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} Hyphenate |
| 11594 | 12305 |
| 12306 @anchor{- and hyphenation}@c old name | |
| 11595 @findex - @r{(discretionary hyphen)} | 12307 @findex - @r{(discretionary hyphen)} |
| 11596 @findex hyphenation | 12308 @findex hyphenation |
| 11597 @cindex Hyphenation, helping @TeX{} do | 12309 @cindex Hyphenation, helping @TeX{} do |
| 11598 @cindex Fine-tuning, and hyphenation | 12310 @cindex Fine-tuning, and hyphenation |
| 11599 | 12311 |
| 11623 | 12335 |
| 11624 Info, HTML, and other non-@TeX{} output is not hyphenated, so none of | 12336 Info, HTML, and other non-@TeX{} output is not hyphenated, so none of |
| 11625 these commands have any effect there. | 12337 these commands have any effect there. |
| 11626 | 12338 |
| 11627 | 12339 |
| 11628 @node allowcodebreaks | 12340 @node @t{@@allowcodebreaks} |
| 11629 @section @code{@@allowcodebreaks}: Control Line Breaks in @code{@@code} | 12341 @section @code{@@allowcodebreaks}: Control Line Breaks in @code{@@code} |
| 11630 | 12342 |
| 12343 @anchor{allowcodebreaks}@c old name | |
| 11631 @findex allowcodebreaks | 12344 @findex allowcodebreaks |
| 11632 @cindex Breaks, within @code{@@code} | 12345 @cindex Breaks, within @code{@@code} |
| 11633 @cindex -, breakpoint within @code{@@code} | 12346 @cindex -, breakpoint within @code{@@code} |
| 11634 @cindex Hyphen, breakpoint within @code{@@code} | 12347 @cindex Hyphen, breakpoint within @code{@@code} |
| 11635 @cindex Dash, breakpoint within @code{@@code} | 12348 @cindex Dash, breakpoint within @code{@@code} |
| 11636 @cindex _, breakpoint within @code{@@code} | 12349 @cindex _, breakpoint within @code{@@code} |
| 11637 @cindex Underscore, breakpoint within @code{@@code} | 12350 @cindex Underscore, breakpoint within @code{@@code} |
| 11638 | 12351 |
| 11639 Ordinarily, @TeX{} will consider breaking lines at @samp{-} and | 12352 Ordinarily, @TeX{} considers breaking lines at @samp{-} and @samp{_} |
| 11640 @samp{_} characters within @code{@@code} and related commands | 12353 characters within @code{@@code} and related commands |
| 11641 (@pxref{code,,@code{@@code}}), more or less as if they were ``empty'' | 12354 (@pxref{@t{@@code}}), more or less as if they were ``empty'' |
| 11642 hyphenation points. | 12355 hyphenation points. |
| 11643 | 12356 |
| 11644 This is necessary as many manuals, especially for Lisp-family | 12357 This is necessary since many manuals, especially for Lisp-family |
| 11645 languages, must document very long identifiers. On the other hand, | 12358 languages, must document very long identifiers. On the other hand, |
| 11646 other manuals don't have this problems, and you may not wish to allow | 12359 some manuals don't have this problems, and you may not wish to allow a |
| 11647 a line break at the underscore in, for example, @code{SIZE_MAX}, or | 12360 line break at the underscore in, for example, @code{SIZE_MAX}, or even |
| 11648 even worse, after any of the four underscores in @code{__typeof__}. | 12361 worse, after any of the four underscores in @code{__typeof__}. |
| 11649 | 12362 |
| 11650 So Texinfo provides this command: | 12363 So Texinfo provides this command: |
| 11651 | 12364 |
| 11652 @example | 12365 @example |
| 11653 @@allowcodebreaks false | 12366 @@allowcodebreaks false |
| 11654 @end example | 12367 @end example |
| 11655 | 12368 |
| 11656 @noindent to prevent @TeX{} from breaking at @samp{-} or @samp{_} within | 12369 @noindent to prevent from breaking at @samp{-} or @samp{_} within |
| 11657 @code{@@code}. You can go back to allowing such breaks with | 12370 @code{@@code}. You can go back to allowing such breaks with |
| 11658 @code{@@allowcodebreaks true}. Write these commands on lines by | 12371 @code{@@allowcodebreaks true}. Write these commands on lines by |
| 11659 themselves. | 12372 themselves. |
| 11660 | 12373 |
| 11661 These commands can be given anywhere in the document. For example, | 12374 These commands can be given anywhere in the document. For example, |
| 11662 you may have just one problematic paragraph where you need to turn off | 12375 you may have just one problematic paragraph where you need to turn off |
| 11663 the breaks, but want them in general, or vice versa. | 12376 the breaks, but want them in general, or vice versa. |
| 11664 | 12377 |
| 11665 This command has no effect in Info, HTML, and other non-@TeX{} output. | 12378 This command has no effect except in HTML and @TeX{} output. |
| 11666 | 12379 |
| 11667 | 12380 |
| 11668 @node w | 12381 @node @t{@@w} |
| 11669 @section @code{@@w}@{@var{text}@}: Prevent Line Breaks | 12382 @section @code{@@w}@{@var{text}@}: Prevent Line Breaks |
| 12383 | |
| 12384 @anchor{w}@c old name | |
| 11670 @findex w @r{(prevent line break)} | 12385 @findex w @r{(prevent line break)} |
| 11671 @cindex Line breaks, preventing | 12386 @cindex Line breaks, preventing |
| 11672 | 12387 |
| 11673 @code{@@w@{@var{text}@}} outputs @var{text} and prohibits line breaks | 12388 @code{@@w@{@var{text}@}} outputs @var{text}, while prohibiting line |
| 11674 within @var{text}, for both @TeX{} and @command{makeinfo}. | 12389 breaks within @var{text}. |
| 11675 | 12390 |
| 11676 @cindex Non-breakable space, fixed | 12391 @cindex Non-breakable space, fixed |
| 11677 @cindex Unbreakable space, fixed | 12392 @cindex Unbreakable space, fixed |
| 11678 Thus, you can use @code{@@w} to produce a non-breakable space, fixed at | 12393 Thus, you can use @code{@@w} to produce a non-breakable space, fixed at |
| 11679 the width of a normal interword space: | 12394 the width of a normal interword space: |
| 11690 | 12405 |
| 11691 The space from @code{@@w@{@w{ }@}}, as well as being non-breakable, | 12406 The space from @code{@@w@{@w{ }@}}, as well as being non-breakable, |
| 11692 also will not stretch or shrink. Sometimes that is what you want, for | 12407 also will not stretch or shrink. Sometimes that is what you want, for |
| 11693 instance if you're doing manual indenting. However, usually you want | 12408 instance if you're doing manual indenting. However, usually you want |
| 11694 a normal interword space that does stretch and shrink (in the printed | 12409 a normal interword space that does stretch and shrink (in the printed |
| 11695 output); see the @code{@@tie} command in the next section. | 12410 output); for that, see the @code{@@tie} command in the next section. |
| 11696 | 12411 |
| 11697 @cindex Hyphenation, preventing | 12412 @cindex Hyphenation, preventing |
| 11698 You can also use the @code{@@w} command to prevent @TeX{} from | 12413 You can also use the @code{@@w} command to prevent @TeX{} from |
| 11699 automatically hyphenating a long name or phrase that happens to fall | 12414 automatically hyphenating a long name or phrase that happens to fall |
| 11700 near the end of a line. @command{makeinfo} does not ever hyphenate | 12415 near the end of a line. @command{makeinfo} does not ever hyphenate |
| 11703 @cindex Keyword expansion, preventing | 12418 @cindex Keyword expansion, preventing |
| 11704 @cindex Version control keywords, preventing expansion of | 12419 @cindex Version control keywords, preventing expansion of |
| 11705 @cindex $Id expansion, preventing | 12420 @cindex $Id expansion, preventing |
| 11706 You can also use @code{@@w} to avoid unwanted keyword expansion in | 12421 You can also use @code{@@w} to avoid unwanted keyword expansion in |
| 11707 source control systems. For example, to literally write @t{@w{$}Id$} | 12422 source control systems. For example, to literally write @t{@w{$}Id$} |
| 11708 in your document, use @code{@@w@{$@}Id$}. | 12423 in your document, use @code{@@w@{$@}Id$}. This trick isn't effective |
| 11709 | 12424 in Info or plain text output, though. |
| 11710 | 12425 |
| 11711 @node tie | 12426 |
| 12427 @node @t{@@tie} | |
| 11712 @section @code{@@tie@{@}}: Inserting an Unbreakable Space | 12428 @section @code{@@tie@{@}}: Inserting an Unbreakable Space |
| 12429 | |
| 12430 @anchor{tie}@c old name | |
| 11713 @findex tie @r{(unbreakable interword space)} | 12431 @findex tie @r{(unbreakable interword space)} |
| 11714 @cindex Tied space | 12432 @cindex Tied space |
| 11715 @cindex Non-breakable space, variable | 12433 @cindex Non-breakable space, variable |
| 11716 @cindex Unbreakable space, variable | 12434 @cindex Unbreakable space, variable |
| 11717 | 12435 |
| 11745 reasons, namely that it produces an @samp{\hbox}). | 12463 reasons, namely that it produces an @samp{\hbox}). |
| 11746 | 12464 |
| 11747 @end itemize | 12465 @end itemize |
| 11748 | 12466 |
| 11749 | 12467 |
| 11750 @node sp | 12468 @node @t{@@sp} |
| 11751 @section @code{@@sp} @var{n}: Insert Blank Lines | 12469 @section @code{@@sp} @var{n}: Insert Blank Lines |
| 12470 | |
| 12471 @anchor{sp}@c old name | |
| 11752 @findex sp @r{(line spacing)} | 12472 @findex sp @r{(line spacing)} |
| 11753 @cindex Space, inserting vertical | 12473 @cindex Space, inserting vertical |
| 11754 @cindex Blank lines | 12474 @cindex Blank lines |
| 11755 @cindex Line spacing | 12475 @cindex Line spacing |
| 11756 | 12476 |
| 11764 @end example | 12484 @end example |
| 11765 | 12485 |
| 11766 @noindent | 12486 @noindent |
| 11767 generates two blank lines. | 12487 generates two blank lines. |
| 11768 | 12488 |
| 11769 The @code{@@sp} command is most often used in the title page.@refill | 12489 The @code{@@sp} command is most often used in the title page. |
| 11770 | 12490 |
| 11771 @ignore | 12491 |
| 11772 @c node br, page, sp, Breaks | 12492 @node @t{@@page} |
| 11773 @comment node-name, next, previous, up | |
| 11774 @c section @code{@@br}: Generate Paragraph Breaks | |
| 11775 @findex br @r{(paragraph breaks)} | |
| 11776 @cindex Paragraph breaks | |
| 11777 @cindex Breaks in a paragraph | |
| 11778 | |
| 11779 The @code{@@br} command forces a paragraph break. It inserts a blank | |
| 11780 line. You can use the command within or at the end of a line. If | |
| 11781 used within a line, the @code{@@br@{@}} command must be followed by | |
| 11782 left and right braces (as shown here) to mark the end of the | |
| 11783 command.@refill | |
| 11784 | |
| 11785 @need 700 | |
| 11786 For example, | |
| 11787 | |
| 11788 @example | |
| 11789 @group | |
| 11790 This line @@br@{@}contains and is ended by paragraph breaks@@br | |
| 11791 and is followed by another line. | |
| 11792 @end group | |
| 11793 @end example | |
| 11794 | |
| 11795 @noindent | |
| 11796 produces | |
| 11797 | |
| 11798 @example | |
| 11799 @group | |
| 11800 This line | |
| 11801 | |
| 11802 contains and is ended by paragraph breaks | |
| 11803 | |
| 11804 and is followed by another line. | |
| 11805 @end group | |
| 11806 @end example | |
| 11807 | |
| 11808 The @code{@@br} command is seldom used. | |
| 11809 @end ignore | |
| 11810 | |
| 11811 | |
| 11812 @node page | |
| 11813 @section @code{@@page}: Start a New Page | 12493 @section @code{@@page}: Start a New Page |
| 11814 @cindex Page breaks | 12494 |
| 12495 @anchor{page}@c old name | |
| 11815 @findex page | 12496 @findex page |
| 12497 @cindex Page breaks, forcing | |
| 11816 | 12498 |
| 11817 A line containing only @code{@@page} starts a new page in a printed | 12499 A line containing only @code{@@page} starts a new page in a printed |
| 11818 manual. The command has no effect on Info files since they are not | 12500 manual. In other formats, without the concept of pages, it starts a |
| 11819 paginated. An @code{@@page} command is often used in the @code{@@titlepage} | 12501 new paragraph. An @code{@@page} command is often used in the |
| 11820 section of a Texinfo file to start the copyright page. | 12502 @code{@@titlepage} section of a Texinfo file to start the copyright |
| 11821 | 12503 page. |
| 11822 | 12504 |
| 11823 @node group | 12505 |
| 11824 @comment node-name, next, previous, up | 12506 @node @t{@@group} |
| 11825 @section @code{@@group}: Prevent Page Breaks | 12507 @section @code{@@group}: Prevent Page Breaks |
| 12508 | |
| 12509 @anchor{group}@c old name | |
| 12510 @findex group | |
| 11826 @cindex Group (hold text together vertically) | 12511 @cindex Group (hold text together vertically) |
| 11827 @cindex Holding text together vertically | 12512 @cindex Holding text together vertically |
| 11828 @cindex Vertically holding text together | 12513 @cindex Vertically holding text together |
| 11829 @findex group | |
| 11830 | 12514 |
| 11831 The @code{@@group} command (on a line by itself) is used inside an | 12515 The @code{@@group} command (on a line by itself) is used inside an |
| 11832 @code{@@example} or similar construct to begin an unsplittable vertical | 12516 @code{@@example} or similar construct to begin an unsplittable vertical |
| 11833 group, which will appear entirely on one page in the printed output. | 12517 group, which will appear entirely on one page in the printed output. |
| 11834 The group is terminated by a line containing only @code{@@end group}. | 12518 The group is terminated by a line containing only @code{@@end group}. |
| 11835 These two lines produce no output of their own, and in the Info file | 12519 These two lines produce no output of their own, and in the Info file |
| 11836 output they have no effect at all.@refill | 12520 output they have no effect at all. |
| 11837 | 12521 |
| 11838 @c Once said that these environments | 12522 @c Once said that these environments |
| 11839 @c turn off vertical spacing between ``paragraphs''. | 12523 @c turn off vertical spacing between ``paragraphs''. |
| 11840 @c Also, quotation used to work, but doesn't in texinfo-2.72 | 12524 @c Also, quotation used to work, but doesn't in texinfo-2.72 |
| 11841 Although @code{@@group} would make sense conceptually in a wide | 12525 Although @code{@@group} would make sense conceptually in a wide |
| 11843 within @code{@@example} and variants, and within @code{@@display}, | 12527 within @code{@@example} and variants, and within @code{@@display}, |
| 11844 @code{@@format}, @code{@@flushleft} and @code{@@flushright}. | 12528 @code{@@format}, @code{@@flushleft} and @code{@@flushright}. |
| 11845 @xref{Quotations and Examples}. (What all these commands have in | 12529 @xref{Quotations and Examples}. (What all these commands have in |
| 11846 common is that each line of input produces a line of output.) In | 12530 common is that each line of input produces a line of output.) In |
| 11847 other contexts, @code{@@group} can cause anomalous vertical | 12531 other contexts, @code{@@group} can cause anomalous vertical |
| 11848 spacing.@refill | 12532 spacing. |
| 11849 | 12533 |
| 11850 @need 750 | 12534 @need 750 |
| 11851 This formatting requirement means that you should write: | 12535 This formatting requirement means that you should write: |
| 11852 | 12536 |
| 11853 @example | 12537 @example |
| 11873 error messages when you run @TeX{}. This is because @TeX{} keeps | 12557 error messages when you run @TeX{}. This is because @TeX{} keeps |
| 11874 trying to put the rest of the Texinfo file onto the one page and does | 12558 trying to put the rest of the Texinfo file onto the one page and does |
| 11875 not start to generate error messages until it has processed | 12559 not start to generate error messages until it has processed |
| 11876 considerable text. It is a good rule of thumb to look for a missing | 12560 considerable text. It is a good rule of thumb to look for a missing |
| 11877 @code{@@end group} if you get incomprehensible error messages in | 12561 @code{@@end group} if you get incomprehensible error messages in |
| 11878 @TeX{}.@refill | 12562 @TeX{}. |
| 11879 | 12563 |
| 11880 @node need | 12564 |
| 11881 @comment node-name, next, previous, up | 12565 @node @t{@@need} |
| 11882 @section @code{@@need @var{mils}}: Prevent Page Breaks | 12566 @section @code{@@need @var{mils}}: Prevent Page Breaks |
| 12567 | |
| 12568 @anchor{need}@c old name | |
| 12569 @findex need | |
| 11883 @cindex Need space at page bottom | 12570 @cindex Need space at page bottom |
| 11884 @findex need | 12571 @cindex Mils, argument to @code{@@need} |
| 11885 | 12572 |
| 11886 A line containing only @code{@@need @var{n}} starts | 12573 A line containing only @code{@@need @var{n}} starts a new page in a |
| 11887 a new page in a printed manual if fewer than @var{n} mils (thousandths | 12574 printed manual if fewer than @var{n} mils (thousandths of an inch) |
| 11888 of an inch) remain on the current page. Do not use | 12575 remain on the current page. Do not use braces around the argument |
| 11889 braces around the argument @var{n}. The @code{@@need} command has no | 12576 @var{n}. The @code{@@need} command has no effect on other output |
| 11890 effect on Info files since they are not paginated.@refill | 12577 formats since they are not paginated. |
| 11891 | 12578 |
| 11892 @need 800 | 12579 @need 800 |
| 11893 This paragraph is preceded by an @code{@@need} command that tells | 12580 This paragraph is preceded by an @code{@@need} command that tells |
| 11894 @TeX{} to start a new page if fewer than 800 mils (eight-tenths | 12581 @TeX{} to start a new page if fewer than 800 mils (eight-tenths |
| 11895 inch) remain on the page. It looks like this:@refill | 12582 inch) remain on the page. It looks like this: |
| 11896 | 12583 |
| 11897 @example | 12584 @example |
| 11898 @group | 12585 @group |
| 11899 @@need 800 | 12586 @@need 800 |
| 11900 This paragraph is preceded by @dots{} | 12587 This paragraph is preceded by @dots{} |
| 11901 @end group | 12588 @end group |
| 11902 @end example | 12589 @end example |
| 11903 | 12590 |
| 11904 The @code{@@need} command is useful for preventing orphans (single | 12591 @cindex Orphans, preventing |
| 11905 lines at the bottoms of printed pages).@refill | 12592 The @code{@@need} command is useful for preventing orphans: single |
| 12593 lines at the bottoms of printed pages. | |
| 11906 | 12594 |
| 11907 | 12595 |
| 11908 @node Definition Commands | 12596 @node Definition Commands |
| 11909 @chapter Definition Commands | 12597 @chapter Definition Commands |
| 11910 @cindex Definition commands | 12598 @cindex Definition commands |
| 11911 | 12599 |
| 11912 The @code{@@deffn} command and the other @dfn{definition commands} | 12600 The @code{@@deffn} command and the other @dfn{definition commands} |
| 11913 enable you to describe functions, variables, macros, commands, user | 12601 enable you to describe functions, variables, macros, commands, user |
| 11914 options, special forms and other such artifacts in a uniform | 12602 options, special forms and other such artifacts in a uniform |
| 11915 format.@refill | 12603 format. |
| 11916 | 12604 |
| 11917 In the Info file, a definition causes the entity | 12605 In the Info file, a definition causes the entity |
| 11918 category---`Function', `Variable', or whatever---to appear at the | 12606 category---`Function', `Variable', or whatever---to appear at the |
| 11919 beginning of the first line of the definition, followed by the | 12607 beginning of the first line of the definition, followed by the |
| 11920 entity's name and arguments. In the printed manual, the command | 12608 entity's name and arguments. In the printed manual, the command |
| 11926 @code{@@defvr} enters it into the index of variables, and so | 12614 @code{@@defvr} enters it into the index of variables, and so |
| 11927 on (@pxref{Predefined Indices}). | 12615 on (@pxref{Predefined Indices}). |
| 11928 | 12616 |
| 11929 A manual need not and should not contain more than one definition for | 12617 A manual need not and should not contain more than one definition for |
| 11930 a given name. An appendix containing a summary should use | 12618 a given name. An appendix containing a summary should use |
| 11931 @code{@@table} rather than the definition commands.@refill | 12619 @code{@@table} rather than the definition commands. |
| 11932 | 12620 |
| 11933 @menu | 12621 @menu |
| 11934 * Def Cmd Template:: Writing descriptions using definition commands. | 12622 * Def Cmd Template:: Writing descriptions using definition commands. |
| 11935 * Def Cmd Continuation Lines:: Continuing the heading over source lines. | 12623 * Def Cmd Continuation Lines:: Continuing the heading over source lines. |
| 11936 * Optional Arguments:: Handling optional and repeated arguments. | 12624 * Optional Arguments:: Handling optional and repeated arguments. |
| 11937 * deffnx:: Group two or more `first' lines. | 12625 * @t{@@deffnx}:: Group two or more `first' lines. |
| 11938 * Def Cmds in Detail:: Reference for all the definition commands. | 12626 * Def Cmds in Detail:: Reference for all the definition commands. |
| 11939 * Def Cmd Conventions:: Conventions for writing definitions. | 12627 * Def Cmd Conventions:: Conventions for writing definitions. |
| 11940 * Sample Function Definition:: An example. | 12628 * Sample Function Definition:: An example. |
| 11941 @end menu | 12629 @end menu |
| 11942 | 12630 |
| 12027 | 12715 |
| 12028 @xref{Sample Function Definition}, for a detailed example of a | 12716 @xref{Sample Function Definition}, for a detailed example of a |
| 12029 function definition, including the use of @code{@@example} inside the | 12717 function definition, including the use of @code{@@example} inside the |
| 12030 definition. | 12718 definition. |
| 12031 | 12719 |
| 12032 @cindex Macros in definition commands | |
| 12033 Unfortunately, due to implementation difficulties, macros are not expanded | |
| 12034 in @code{@@deffn} and all the other definition commands. | |
| 12035 | |
| 12036 | 12720 |
| 12037 @node Def Cmd Continuation Lines | 12721 @node Def Cmd Continuation Lines |
| 12038 @section Definition Command Continuation Lines | 12722 @section Definition Command Continuation Lines |
| 12039 @cindex Continuation lines in definition commands | 12723 @cindex Continuation lines in definition commands |
| 12040 @cindex Definition command headings, continuing | 12724 @cindex Definition command headings, continuing |
| 12052 @@end defun | 12736 @@end defun |
| 12053 @end example | 12737 @end example |
| 12054 | 12738 |
| 12055 @noindent produces: | 12739 @noindent produces: |
| 12056 | 12740 |
| 12057 @defun fn-name @ | 12741 @defun fn-name arg1 arg2 arg3 |
| 12058 arg1 arg2 arg3 | |
| 12059 This is the basic continued defun. | 12742 This is the basic continued defun. |
| 12060 @end defun | 12743 @end defun |
| 12061 | 12744 |
| 12062 @noindent | 12745 @noindent |
| 12063 As you can see, the continued lines are combined, as if they had been | 12746 As you can see, the continued lines are combined, as if they had been |
| 12064 typed on one source line. | 12747 typed on one source line. |
| 12065 | 12748 |
| 12066 Although this example only shows a one-line continuation, | 12749 Although this example only shows a one-line continuation, |
| 12067 continuations may extend over any number of lines; simply put an | 12750 continuations may extend over any number of lines, in the same way; |
| 12068 @code{@@} at the end of each line to be continued. | 12751 put an @code{@@} at the end of each line to be continued. |
| 12069 | |
| 12070 The @code{@@} character does not have to be the last character on the | |
| 12071 physical line: whitespace is allowed (and ignored) afterwards. | |
| 12072 | 12752 |
| 12073 @cindex Whitespace, collapsed around continuations | 12753 @cindex Whitespace, collapsed around continuations |
| 12074 @cindex Collapsing whitespace around continuations | 12754 @cindex Collapsing whitespace around continuations |
| 12075 In general, any number of spaces or tabs around the @code{@@} | 12755 In general, any number of spaces or tabs before the @code{@@} |
| 12076 continuation character, both on the line with the @code{@@} and on the | 12756 continuation character are collapsed into a single space. There is one |
| 12077 continued line, are collapsed into a single space. There is one | |
| 12078 exception: the Texinfo processors will not fully collapse whitespace | 12757 exception: the Texinfo processors will not fully collapse whitespace |
| 12079 around a continuation inside braces. For example: | 12758 around a continuation inside braces. For example: |
| 12080 | 12759 |
| 12081 @example | 12760 @example |
| 12082 @@deffn @{Category @@ | 12761 @@deffn @{Category @@ |
| 12083 Name@} @dots{} | 12762 Name@} @dots{} |
| 12084 @end example | 12763 @end example |
| 12085 | 12764 |
| 12086 @noindent The output (not shown) has excess space between `Category' | 12765 @noindent The output (not shown) has excess space between `Category' |
| 12087 and `Name'. In this case, simply elide any unwanted whitespace in | 12766 and `Name'. To avoid this, elide the unwanted whitespace in your |
| 12088 your input, or put the continuation @code{@@} outside braces. | 12767 input, or put the continuation @code{@@} outside braces. |
| 12089 | 12768 |
| 12090 @code{@@} does not (currently) function as a continuation character in | 12769 @code{@@} does not function as a continuation character in @emph{any} |
| 12091 @emph{any} other context. Ordinarily, @samp{@@} followed by a | 12770 other context. Ordinarily, @samp{@@} followed by a whitespace |
| 12092 whitespace character (space, tab, newline) produces a normal interword | 12771 character (space, tab, newline) produces a normal interword space |
| 12093 space (@pxref{Multiple Spaces}). | 12772 (@pxref{Multiple Spaces}). |
| 12094 | 12773 |
| 12095 | 12774 |
| 12096 @node Optional Arguments | 12775 @node Optional Arguments |
| 12097 @section Optional and Repeated Arguments | 12776 @section Optional and Repeated Arguments |
| 12098 @cindex Optional and repeated arguments | 12777 @cindex Optional and repeated arguments |
| 12099 @cindex Repeated and optional arguments | 12778 @cindex Repeated and optional arguments |
| 12100 @cindex Arguments, repeated and optional | 12779 @cindex Arguments, repeated and optional |
| 12101 @cindex Syntax, optional & repeated arguments | 12780 @cindex Syntax, optional & repeated arguments |
| 12102 @cindex Meta-syntactic chars for arguments | 12781 @cindex Meta-syntactic chars for arguments |
| 12103 | 12782 |
| 12104 Some entities take optional or repeated arguments, which may be | 12783 @c This is consistent with the XEmacs Lisp Reference Manual. |
| 12105 specified by a distinctive glyph that uses square brackets and | 12784 Some entities take optional or repeated arguments, conventionally |
| 12106 ellipses. For @w{example}, a special form often breaks its argument list | 12785 specified by using square brackets and ellipses: an argument enclosed |
| 12107 into separate arguments in more complicated ways than a | 12786 within square brackets is optional, and an argument followed by an |
| 12108 straightforward function. | 12787 ellipsis is optional and may be repeated more than once. |
| 12109 | 12788 |
| 12110 @c This is consistent with XEmacs Lisp Reference manual | 12789 Thus, [@var{optional-arg}] means that @var{optional-arg} is optional |
| 12111 An argument enclosed within square brackets is optional. | 12790 and @var{repeated-args}@samp{@dots{}} stands for zero or more |
| 12112 Thus, [@var{optional-arg}] means that @var{optional-arg} is optional. | |
| 12113 An argument followed by an ellipsis is optional | |
| 12114 and may be repeated more than once. | |
| 12115 @c This is consistent with XEmacs Lisp Reference manual | |
| 12116 Thus, @var{repeated-args}@samp{@dots{}} stands for zero or more | |
| 12117 arguments. Parentheses are used when several arguments are grouped | 12791 arguments. Parentheses are used when several arguments are grouped |
| 12118 into additional levels of list structure in Lisp. | 12792 into additional levels of list structure in Lisp. |
| 12119 | 12793 |
| 12120 Here is the @code{@@defspec} line of an example of an imaginary | 12794 Here is the @code{@@defspec} line of an example of an imaginary |
| 12121 special form: | 12795 (complicated) special form: |
| 12122 | 12796 |
| 12123 @quotation | 12797 @quotation |
| 12124 @defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} | 12798 @defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} |
| 12125 @end defspec | 12799 @end defspec |
| 12126 @tex | 12800 @c tex |
| 12127 \vskip \parskip | 12801 @c \vskip \parskip |
| 12128 @end tex | 12802 @c end tex |
| 12129 @end quotation | 12803 @end quotation |
| 12130 | 12804 |
| 12131 @noindent | 12805 @noindent |
| 12132 In this example, the arguments @var{from} and @var{to} are optional, | 12806 In this example, the arguments @var{from} and @var{to} are optional, |
| 12133 but must both be present or both absent. If they are present, | 12807 but must both be present or both absent. If they are present, |
| 12134 @var{inc} may optionally be specified as well. These arguments are | 12808 @var{inc} may optionally be specified as well. These arguments are |
| 12135 grouped with the argument @var{var} into a list, to distinguish them | 12809 grouped with the argument @var{var} into a list, to distinguish them |
| 12136 from @var{body}, which includes all remaining elements of the | 12810 from @var{body}, which includes all remaining elements of the |
| 12137 form.@refill | 12811 form. |
| 12138 | 12812 |
| 12139 In a Texinfo source file, this @code{@@defspec} line is written like | 12813 In a Texinfo source file, this @code{@@defspec} line is written like |
| 12140 this (except it would not be split over two lines, as it is in this | 12814 this, including a continuation to avoid a long source line. |
| 12141 example).@refill | |
| 12142 | 12815 |
| 12143 @example | 12816 @example |
| 12144 @group | 12817 @group |
| 12145 @@defspec foobar (@@var@{var@} [@@var@{from@} @@var@{to@} | 12818 @@defspec foobar (@@var@{var@} [@@var@{from@} @@var@{to@} @@ |
| 12146 [@@var@{inc@}]]) @@var@{body@}@@dots@{@} | 12819 [@@var@{inc@}]]) @@var@{body@}@@dots@{@} |
| 12147 @end group | 12820 @end group |
| 12148 @end example | 12821 @end example |
| 12149 | 12822 |
| 12150 @noindent | 12823 @noindent |
| 12151 The function is listed in the Command and Variable Index under | 12824 The function is listed in the Command and Variable Index under |
| 12152 @samp{foobar}.@refill | 12825 @samp{foobar}. |
| 12153 | 12826 |
| 12154 | 12827 |
| 12155 @node deffnx | 12828 @node @t{@@deffnx} |
| 12156 @section Two or More `First' Lines | 12829 @section @code{@@deffnx}, et al.: Two or More `First' Lines |
| 12830 | |
| 12831 @anchor{deffnx}@c old node | |
| 12832 @findex deffnx | |
| 12157 @cindex Two `First' Lines for @code{@@deffn} | 12833 @cindex Two `First' Lines for @code{@@deffn} |
| 12158 @cindex Grouping two definitions together | 12834 @cindex Grouping two definitions together |
| 12159 @cindex Definitions grouped together | 12835 @cindex Definitions grouped together |
| 12160 @findex deffnx | |
| 12161 | 12836 |
| 12162 To create two or more `first' or header lines for a definition, follow | 12837 To create two or more `first' or header lines for a definition, follow |
| 12163 the first @code{@@deffn} line by a line beginning with @code{@@deffnx}. | 12838 the first @code{@@deffn} line by a line beginning with |
| 12164 The @code{@@deffnx} command works exactly like @code{@@deffn} | 12839 @code{@@deffnx}. The @code{@@deffnx} command works exactly like |
| 12165 except that it does not generate extra vertical white space between it | 12840 @code{@@deffn} except that it does not generate extra vertical white |
| 12166 and the preceding line.@refill | 12841 space between it and the preceding line. |
| 12167 | 12842 |
| 12168 @need 1000 | 12843 @need 1000 |
| 12169 For example, | 12844 For example, |
| 12170 | 12845 |
| 12171 @example | 12846 @example |
| 12186 @end deffn | 12861 @end deffn |
| 12187 | 12862 |
| 12188 Each definition command has an `x' form: @code{@@defunx}, | 12863 Each definition command has an `x' form: @code{@@defunx}, |
| 12189 @code{@@defvrx}, @code{@@deftypefunx}, etc. | 12864 @code{@@defvrx}, @code{@@deftypefunx}, etc. |
| 12190 | 12865 |
| 12191 The `x' forms work similarly to @code{@@itemx} (@pxref{itemx}). | 12866 The `x' forms work similarly to @code{@@itemx} |
| 12867 (@pxref{@t{@@itemx}}). | |
| 12192 | 12868 |
| 12193 | 12869 |
| 12194 @node Def Cmds in Detail | 12870 @node Def Cmds in Detail |
| 12195 @section The Definition Commands | 12871 @section The Definition Commands |
| 12196 | 12872 |
| 12197 Texinfo provides more than a dozen definition commands, all of which | 12873 Texinfo provides more than a dozen definition commands, all of which |
| 12198 are described in this section.@refill | 12874 are described in this section. |
| 12199 | 12875 |
| 12200 The definition commands automatically enter the name of the entity in | 12876 The definition commands automatically enter the name of the entity in |
| 12201 the appropriate index: for example, @code{@@deffn}, @code{@@defun}, | 12877 the appropriate index: for example, @code{@@deffn}, @code{@@defun}, |
| 12202 and @code{@@defmac} enter function names in the index of functions; | 12878 and @code{@@defmac} enter function names in the index of functions; |
| 12203 @code{@@defvr} and @code{@@defvar} enter variable names in the index | 12879 @code{@@defvr} and @code{@@defvar} enter variable names in the index |
| 12204 of variables.@refill | 12880 of variables. |
| 12205 | 12881 |
| 12206 Although the examples that follow mostly illustrate Lisp, the commands | 12882 Although the examples that follow mostly illustrate Lisp, the commands |
| 12207 can be used for other programming languages.@refill | 12883 can be used for other programming languages. |
| 12208 | 12884 |
| 12209 @menu | 12885 @menu |
| 12210 * Functions Commands:: Commands for functions and similar entities. | 12886 * Functions Commands:: Commands for functions and similar entities. |
| 12211 * Variables Commands:: Commands for variables and similar entities. | 12887 * Variables Commands:: Commands for variables and similar entities. |
| 12212 * Typed Functions:: Commands for functions in typed languages. | 12888 * Typed Functions:: Commands for functions in typed languages. |
| 12217 | 12893 |
| 12218 @node Functions Commands | 12894 @node Functions Commands |
| 12219 @subsection Functions and Similar Entities | 12895 @subsection Functions and Similar Entities |
| 12220 | 12896 |
| 12221 This section describes the commands for describing functions and similar | 12897 This section describes the commands for describing functions and similar |
| 12222 entities:@refill | 12898 entities: |
| 12223 | 12899 |
| 12224 @table @code | 12900 @table @code |
| 12225 @findex deffn | 12901 @findex deffn |
| 12226 @item @@deffn @var{category} @var{name} @var{arguments}@dots{} | 12902 @item @@deffn @var{category} @var{name} @var{arguments}@dots{} |
| 12227 The @code{@@deffn} command is the general definition command for | 12903 The @code{@@deffn} command is the general definition command for |
| 12230 being defined; for example, ``Function'' could be used if the entity is | 12906 being defined; for example, ``Function'' could be used if the entity is |
| 12231 a function. The @code{@@deffn} command is written at the beginning of a | 12907 a function. The @code{@@deffn} command is written at the beginning of a |
| 12232 line and is followed on the same line by the category of entity being | 12908 line and is followed on the same line by the category of entity being |
| 12233 described, the name of this particular entity, and its arguments, if | 12909 described, the name of this particular entity, and its arguments, if |
| 12234 any. Terminate the definition with @code{@@end deffn} on a line of its | 12910 any. Terminate the definition with @code{@@end deffn} on a line of its |
| 12235 own.@refill | 12911 own. |
| 12236 | 12912 |
| 12237 @need 750 | 12913 @need 750 |
| 12238 For example, here is a definition: | 12914 For example, here is a definition: |
| 12239 | 12915 |
| 12240 @example | 12916 @example |
| 12247 | 12923 |
| 12248 @noindent | 12924 @noindent |
| 12249 This shows a rather terse definition for a ``command'' named | 12925 This shows a rather terse definition for a ``command'' named |
| 12250 @code{forward-char} with one argument, @var{nchars}. | 12926 @code{forward-char} with one argument, @var{nchars}. |
| 12251 | 12927 |
| 12252 @code{@@deffn} and prints argument names such as @var{nchars} in slanted | 12928 @code{@@deffn} prints argument names such as @var{nchars} in slanted |
| 12253 type in the printed output, because we think of these names as | 12929 type in the printed output, because we think of these names as |
| 12254 metasyntactic variables---they stand for the actual argument values. | 12930 metasyntactic variables---they stand for the actual argument values. |
| 12255 Within the text of the description, however, write an argument name | 12931 Within the text of the description, however, write an argument name |
| 12256 explicitly with @code{@@var} to refer to the value of the argument. | 12932 explicitly with @code{@@var} to refer to the value of the argument. |
| 12257 In the example above, we used @samp{@@var@{nchars@}} in this way. | 12933 In the example above, we used @samp{@@var@{nchars@}} in this way. |
| 12258 | 12934 |
| 12259 In the unusual case when an argument name contains @samp{--}, or | 12935 In the extremely unusual case when an argument name contains |
| 12260 another character sequence which is treated specially | 12936 @samp{--}, or another character sequence which is treated specially |
| 12261 (@pxref{Conventions}), use @code{@@var} around the argument. This | 12937 (@pxref{Conventions}), use @code{@@code} around the special |
| 12262 causes the name to be printed in slanted typewriter, instead of the | 12938 characters. This avoids the conversion to typographic en-dashes and |
| 12263 regular slanted font, exactly as input. | 12939 em-dashes. |
| 12264 @c except for ?` and !`, but we won't explain that. | 12940 @c @var also works; that's what we used to recommend. |
| 12265 | 12941 |
| 12266 The template for @code{@@deffn} is: | 12942 The template for @code{@@deffn} is: |
| 12267 | 12943 |
| 12268 @example | 12944 @example |
| 12269 @group | 12945 @group |
| 12295 works like @code{@@defun}. | 12971 works like @code{@@defun}. |
| 12296 | 12972 |
| 12297 @findex defspec | 12973 @findex defspec |
| 12298 @item @@defspec @var{name} @var{arguments}@dots{} | 12974 @item @@defspec @var{name} @var{arguments}@dots{} |
| 12299 The @code{@@defspec} command is the definition command for special | 12975 The @code{@@defspec} command is the definition command for special |
| 12300 forms. (In Lisp, a special form is an entity much like a function, | 12976 forms. (In Lisp, a special form is an entity much like a function; |
| 12301 @pxref{Special Forms,,, lispref, XEmacs Lisp Reference Manual}.) | 12977 @pxref{Special Forms,,, lispref, XEmacs Lisp Reference Manual}.) |
| 12302 @code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@} | 12978 @code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@} |
| 12303 @dots{}} and works like @code{@@defun}. | 12979 @dots{}} and works like @code{@@defun}. |
| 12304 @end table | 12980 @end table |
| 12305 | 12981 |
| 12308 | 12984 |
| 12309 @node Variables Commands | 12985 @node Variables Commands |
| 12310 @subsection Variables and Similar Entities | 12986 @subsection Variables and Similar Entities |
| 12311 | 12987 |
| 12312 Here are the commands for defining variables and similar | 12988 Here are the commands for defining variables and similar |
| 12313 entities:@refill | 12989 entities: |
| 12314 | 12990 |
| 12315 @table @code | 12991 @table @code |
| 12316 @findex defvr | 12992 @findex defvr |
| 12317 @item @@defvr @var{category} @var{name} | 12993 @item @@defvr @var{category} @var{name} |
| 12318 The @code{@@defvr} command is a general definition command for | 12994 The @code{@@defvr} command is a general definition command for |
| 12321 example, ``Variable'' could be used if the entity is a variable. | 12997 example, ``Variable'' could be used if the entity is a variable. |
| 12322 Write the @code{@@defvr} command at the beginning of a line and | 12998 Write the @code{@@defvr} command at the beginning of a line and |
| 12323 follow it on the same line by the category of the entity and the | 12999 follow it on the same line by the category of the entity and the |
| 12324 name of the entity. | 13000 name of the entity. |
| 12325 | 13001 |
| 12326 Capitalize the category name like a title. If the name of the category | 13002 We recommend capitalizing the category name like a title. If the name |
| 12327 contains spaces, as in the name ``User Option'', enclose it in braces. | 13003 of the category contains spaces, as in the name ``User Option'', |
| 12328 Otherwise, the second word will be mistaken for the name of the entity. | 13004 enclose it in braces. Otherwise, the second word will be mistaken for |
| 12329 For example, | 13005 the name of the entity. For example, |
| 12330 | 13006 |
| 12331 @example | 13007 @example |
| 12332 @group | 13008 @group |
| 12333 @@defvr @{User Option@} fill-column | 13009 @@defvr @{User Option@} fill-column |
| 12334 This buffer-local variable specifies | 13010 This buffer-local variable specifies |
| 12337 @@end defvr | 13013 @@end defvr |
| 12338 @end group | 13014 @end group |
| 12339 @end example | 13015 @end example |
| 12340 | 13016 |
| 12341 Terminate the definition with @code{@@end defvr} on a line of its | 13017 Terminate the definition with @code{@@end defvr} on a line of its |
| 12342 own.@refill | 13018 own. |
| 12343 | 13019 |
| 12344 The template is: | 13020 The template is: |
| 12345 | 13021 |
| 12346 @example | 13022 @example |
| 12347 @group | 13023 @group |
| 12355 | 13031 |
| 12356 @findex defvar | 13032 @findex defvar |
| 12357 @item @@defvar @var{name} | 13033 @item @@defvar @var{name} |
| 12358 The @code{@@defvar} command is the definition command for variables. | 13034 The @code{@@defvar} command is the definition command for variables. |
| 12359 @code{@@defvar} is equivalent to @samp{@@defvr Variable | 13035 @code{@@defvar} is equivalent to @samp{@@defvr Variable |
| 12360 @dots{}}.@refill | 13036 @dots{}}. |
| 12361 | 13037 |
| 12362 @need 750 | 13038 @need 750 |
| 12363 For example: | 13039 For example: |
| 12364 | 13040 |
| 12365 @example | 13041 @example |
| 12379 @@end defvar | 13055 @@end defvar |
| 12380 @end group | 13056 @end group |
| 12381 @end example | 13057 @end example |
| 12382 | 13058 |
| 12383 @code{@@defvar} creates an entry in the index of variables for | 13059 @code{@@defvar} creates an entry in the index of variables for |
| 12384 @var{name}.@refill | 13060 @var{name}. |
| 12385 | 13061 |
| 12386 @findex defopt | 13062 @findex defopt |
| 12387 @item @@defopt @var{name} | 13063 @item @@defopt @var{name} |
| 12388 @cindex User options, marking | 13064 @cindex User options, marking |
| 12389 The @code{@@defopt} command is the definition command for @dfn{user | 13065 The @code{@@defopt} command is the definition command for @dfn{user |
| 12396 | 13072 |
| 12397 | 13073 |
| 12398 @node Typed Functions | 13074 @node Typed Functions |
| 12399 @subsection Functions in Typed Languages | 13075 @subsection Functions in Typed Languages |
| 12400 | 13076 |
| 13077 @cindex Typed functions | |
| 13078 @cindex Functions, in typed languages | |
| 13079 | |
| 12401 The @code{@@deftypefn} command and its variations are for describing | 13080 The @code{@@deftypefn} command and its variations are for describing |
| 12402 functions in languages in which you must declare types of variables and | 13081 functions in languages in which you must declare types of variables |
| 12403 functions, such as C and C++. | 13082 and functions, such as C and C++. |
| 12404 | 13083 |
| 12405 @table @code | 13084 @table @code |
| 12406 @findex deftypefn | 13085 @findex deftypefn |
| 12407 @item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{} | 13086 @item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{} |
| 12408 The @code{@@deftypefn} command is the general definition command for | 13087 The @code{@@deftypefn} command is the general definition command for |
| 12409 functions and similar entities that may take arguments and that are | 13088 functions and similar entities that may take arguments and that are |
| 12410 typed. The @code{@@deftypefn} command is written at the beginning of | 13089 typed. The @code{@@deftypefn} command is written at the beginning of |
| 12411 a line and is followed on the same line by the category of entity | 13090 a line and is followed on the same line by the category of entity |
| 12412 being described, the type of the returned value, the name of this | 13091 being described, the type of the returned value, the name of this |
| 12413 particular entity, and its arguments, if any.@refill | 13092 particular entity, and its arguments, if any. |
| 12414 | 13093 |
| 12415 @need 800 | 13094 @need 800 |
| 12416 @noindent | 13095 @noindent |
| 12417 For example, | 13096 For example, |
| 12418 | 13097 |
| 12419 @example | 13098 @example |
| 12420 @group | 13099 @group |
| 12421 @@deftypefn @{Library Function@} int foobar | 13100 @@deftypefn @{Library Function@} int foobar @@ |
| 12422 (int @@var@{foo@}, float @@var@{bar@}) | 13101 (int @@var@{foo@}, float @@var@{bar@}) |
| 12423 @dots{} | 13102 @dots{} |
| 12424 @@end deftypefn | 13103 @@end deftypefn |
| 12425 @end group | 13104 @end group |
| 12426 @end example | 13105 @end example |
| 12427 | 13106 |
| 12428 @need 1000 | 13107 produces: |
| 12429 @noindent | |
| 12430 (where the text before the ``@dots{}'', shown above as two lines, would | |
| 12431 actually be a single line in a real Texinfo file) produces the following | |
| 12432 in Info: | |
| 12433 | |
| 12434 @smallexample | |
| 12435 @group | |
| 12436 -- Library Function: int foobar (int FOO, float BAR) | |
| 12437 @dots{} | |
| 12438 @end group | |
| 12439 @end smallexample | |
| 12440 @iftex | |
| 12441 | |
| 12442 In a printed manual, it produces: | |
| 12443 | 13108 |
| 12444 @quotation | 13109 @quotation |
| 12445 @deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar}) | 13110 @deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar}) |
| 12446 @dots{} | 13111 @dots{} |
| 12447 @end deftypefn | 13112 @end deftypefn |
| 12448 @end quotation | 13113 @end quotation |
| 12449 @end iftex | |
| 12450 | 13114 |
| 12451 This means that @code{foobar} is a ``library function'' that returns an | 13115 This means that @code{foobar} is a ``library function'' that returns an |
| 12452 @code{int}, and its arguments are @var{foo} (an @code{int}) and | 13116 @code{int}, and its arguments are @var{foo} (an @code{int}) and |
| 12453 @var{bar} (a @code{float}).@refill | 13117 @var{bar} (a @code{float}). |
| 12454 | 13118 |
| 12455 Since in typed languages, the actual names of the arguments are | 13119 Since in typed languages, the actual names of the arguments are |
| 12456 typically scattered among data type names and keywords, Texinfo cannot | 13120 typically scattered among data type names and keywords, Texinfo cannot |
| 12457 find them without help. You can either (a)@tie{}write everything | 13121 find them without help. You can either (a)@tie{}write everything as |
| 12458 as straight text, and it will be printed in slanted type; (b)@tie{}use | 13122 straight text, and it will be printed in slanted type; (b)@tie{}use |
| 12459 @code{@@var} for the variable names, which will uppercase the | 13123 @code{@@var} for the variable names, which will uppercase the variable |
| 12460 variable names in Info and use the slanted typewriter font in printed | 13124 names in Info and use the slanted typewriter font in printed output; |
| 12461 output; (c)@tie{}use @code{@@var} for the variable names and | 13125 (c)@tie{}use @code{@@var} for the variable names and @code{@@code} for |
| 12462 @code{@@code} for the type names and keywords, which will be dutifully | 13126 the type names and keywords, which will be dutifully obeyed. |
| 12463 obeyed. | 13127 |
| 12464 | 13128 The template for @code{@@deftypefn} is: |
| 12465 The template for @code{@@deftypefn} is:@refill | |
| 12466 | 13129 |
| 12467 @example | 13130 @example |
| 12468 @group | 13131 @group |
| 12469 @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{} | 13132 @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{} |
| 12470 @var{body-of-description} | 13133 @var{body-of-description} |
| 12472 @end group | 13135 @end group |
| 12473 @end example | 13136 @end example |
| 12474 | 13137 |
| 12475 @noindent | 13138 @noindent |
| 12476 Note that if the @var{category} or @var{data type} is more than one | 13139 Note that if the @var{category} or @var{data type} is more than one |
| 12477 word then it must be enclosed in braces to make it a single argument.@refill | 13140 word then it must be enclosed in braces to make it a single argument. |
| 12478 | 13141 |
| 12479 If you are describing a procedure in a language that has packages, | 13142 If you are describing a procedure in a language that has packages, |
| 12480 such as Ada, you might consider using @code{@@deftypefn} in a manner | 13143 such as Ada, you might consider using @code{@@deftypefn} in a manner |
| 12481 somewhat contrary to the convention described in the preceding | 13144 somewhat contrary to the convention described in the preceding |
| 12482 paragraphs. For example: | 13145 paragraphs. For example: |
| 12490 @@end deftypefn | 13153 @@end deftypefn |
| 12491 @end group | 13154 @end group |
| 12492 @end example | 13155 @end example |
| 12493 | 13156 |
| 12494 @noindent | 13157 @noindent |
| 12495 (The @code{@@deftypefn} arguments are shown using continuations | 13158 (In these examples the @code{@@deftypefn} arguments are shown using |
| 12496 (@pxref{Def Cmd Continuation Lines}), but could be on a single line in | 13159 continuations (@pxref{Def Cmd Continuation Lines}), but could be on a |
| 12497 a real Texinfo file.) | 13160 single line.) |
| 12498 | 13161 |
| 12499 In this instance, the procedure is classified as belonging to the | 13162 In this instance, the procedure is classified as belonging to the |
| 12500 package @code{stacks} rather than classified as a `procedure' and its | 13163 package @code{stacks} rather than classified as a `procedure' and its |
| 12501 data type is described as @code{private}. (The name of the procedure | 13164 data type is described as @code{private}. (The name of the procedure |
| 12502 is @code{push}, and its arguments are @var{s} and @var{n}.)@refill | 13165 is @code{push}, and its arguments are @var{s} and @var{n}.) |
| 12503 | 13166 |
| 12504 @code{@@deftypefn} creates an entry in the index of functions for | 13167 @code{@@deftypefn} creates an entry in the index of functions for |
| 12505 @var{name}. | 13168 @var{name}. |
| 12506 | 13169 |
| 12507 @item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{} | 13170 @item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{} |
| 12521 @code{@@deftypefun} creates an entry in the index of functions for | 13184 @code{@@deftypefun} creates an entry in the index of functions for |
| 12522 @var{name}. | 13185 @var{name}. |
| 12523 | 13186 |
| 12524 @end table | 13187 @end table |
| 12525 | 13188 |
| 13189 @cindex Return type, own line for | |
| 13190 @findex deftypefnnewline | |
| 13191 Ordinarily, the return type is printed on the same line as the | |
| 13192 function name and arguments, as shown above. In source code, GNU | |
| 13193 style is to put the return type on a line by itself. So Texinfo | |
| 13194 provides an option to do that: @code{@@deftypefnnewline on}. | |
| 13195 | |
| 13196 This affects typed functions only---not untyped functions, not typed | |
| 13197 variables, etc.. Specifically, it affects the commands in this | |
| 13198 section, and the analogous commands for object-oriented languages, | |
| 13199 namely @code{@@deftypeop} and @code{@@deftypemethod} | |
| 13200 (@pxref{Object-Oriented Methods}). | |
| 13201 | |
| 13202 Specifying @code{@@deftypefnnewline off} reverts to the default. | |
| 13203 | |
| 12526 | 13204 |
| 12527 @node Typed Variables | 13205 @node Typed Variables |
| 12528 @subsection Variables in Typed Languages | 13206 @subsection Variables in Typed Languages |
| 13207 | |
| 13208 @cindex Typed variables | |
| 13209 @cindex Variables, in typed languages | |
| 12529 | 13210 |
| 12530 Variables in typed languages are handled in a manner similar to | 13211 Variables in typed languages are handled in a manner similar to |
| 12531 functions in typed languages. @xref{Typed Functions}. The general | 13212 functions in typed languages. @xref{Typed Functions}. The general |
| 12532 definition command @code{@@deftypevr} corresponds to | 13213 definition command @code{@@deftypevr} corresponds to |
| 12533 @code{@@deftypefn} and the specialized definition command | 13214 @code{@@deftypefn} and the specialized definition command |
| 12534 @code{@@deftypevar} corresponds to @code{@@deftypefun}.@refill | 13215 @code{@@deftypevar} corresponds to @code{@@deftypefun}. |
| 12535 | 13216 |
| 12536 @table @code | 13217 @table @code |
| 12537 @findex deftypevr | 13218 @findex deftypevr |
| 12538 @item @@deftypevr @var{category} @var{data-type} @var{name} | 13219 @item @@deftypevr @var{category} @var{data-type} @var{name} |
| 12539 The @code{@@deftypevr} command is the general definition command for | 13220 The @code{@@deftypevr} command is the general definition command for |
| 12540 something like a variable in a typed language---an entity that records | 13221 something like a variable in a typed language---an entity that records |
| 12541 a value. You must choose a term to describe the category of the | 13222 a value. You must choose a term to describe the category of the |
| 12542 entity being defined; for example, ``Variable'' could be used if the | 13223 entity being defined; for example, ``Variable'' could be used if the |
| 12543 entity is a variable.@refill | 13224 entity is a variable. |
| 12544 | 13225 |
| 12545 The @code{@@deftypevr} command is written at the beginning of a line | 13226 The @code{@@deftypevr} command is written at the beginning of a line |
| 12546 and is followed on the same line by the category of the entity | 13227 and is followed on the same line by the category of the entity |
| 12547 being described, the data type, and the name of this particular | 13228 being described, the data type, and the name of this particular |
| 12548 entity.@refill | 13229 entity. |
| 12549 | 13230 |
| 12550 @need 800 | 13231 @need 800 |
| 12551 @noindent | 13232 @noindent |
| 12552 For example: | 13233 For example: |
| 12553 | 13234 |
| 12558 @@end deftypevr | 13239 @@end deftypevr |
| 12559 @end group | 13240 @end group |
| 12560 @end example | 13241 @end example |
| 12561 | 13242 |
| 12562 @noindent | 13243 @noindent |
| 12563 produces the following in Info: | 13244 produces the following: |
| 12564 | |
| 12565 @example | |
| 12566 @group | |
| 12567 -- Global Flag: int enable | |
| 12568 @dots{} | |
| 12569 @end group | |
| 12570 @end example | |
| 12571 @iftex | |
| 12572 | |
| 12573 @noindent | |
| 12574 and the following in a printed manual: | |
| 12575 | 13245 |
| 12576 @quotation | 13246 @quotation |
| 12577 @deftypevr {Global Flag} int enable | 13247 @deftypevr {Global Flag} int enable |
| 12578 @dots{} | 13248 @dots{} |
| 12579 @end deftypevr | 13249 @end deftypevr |
| 12580 @end quotation | 13250 @end quotation |
| 12581 @end iftex | |
| 12582 | 13251 |
| 12583 @need 800 | 13252 @need 800 |
| 12584 The template is: | 13253 The template is: |
| 12585 | 13254 |
| 12586 @example | 13255 @example |
| 12604 @end example | 13273 @end example |
| 12605 @end table | 13274 @end table |
| 12606 | 13275 |
| 12607 These commands create entries in the index of variables. | 13276 These commands create entries in the index of variables. |
| 12608 | 13277 |
| 13278 | |
| 12609 @node Data Types | 13279 @node Data Types |
| 12610 @subsection Data Types | 13280 @subsection Data Types |
| 12611 | 13281 |
| 12612 Here is the command for data types:@refill | 13282 Here is the command for data types: |
| 12613 | 13283 |
| 12614 @table @code | 13284 @table @code |
| 12615 @findex deftp | 13285 @findex deftp |
| 12616 @item @@deftp @var{category} @var{name} @var{attributes}@dots{} | 13286 @item @@deftp @var{category} @var{name} @var{attributes}@dots{} |
| 12617 The @code{@@deftp} command is the generic definition command for data | 13287 The @code{@@deftp} command is the generic definition command for data |
| 12620 (which is a word like @code{int} or @code{float}), and then by names of | 13290 (which is a word like @code{int} or @code{float}), and then by names of |
| 12621 attributes of objects of that type. Thus, you could use this command | 13291 attributes of objects of that type. Thus, you could use this command |
| 12622 for describing @code{int} or @code{float}, in which case you could use | 13292 for describing @code{int} or @code{float}, in which case you could use |
| 12623 @code{data type} as the category. (A data type is a category of | 13293 @code{data type} as the category. (A data type is a category of |
| 12624 certain objects for purposes of deciding which operations can be | 13294 certain objects for purposes of deciding which operations can be |
| 12625 performed on them.)@refill | 13295 performed on them.) |
| 12626 | 13296 |
| 12627 In Lisp, for example, @dfn{pair} names a particular data | 13297 In Lisp, for example, @dfn{pair} names a particular data |
| 12628 type, and an object of that type has two slots called the | 13298 type, and an object of that type has two slots called the |
| 12629 @sc{car} and the @sc{cdr}. Here is how you would write the first line | 13299 @sc{car} and the @sc{cdr}. Here is how you would write the first line |
| 12630 of a definition of @code{pair}.@refill | 13300 of a definition of @code{pair}. |
| 12631 | 13301 |
| 12632 @example | 13302 @example |
| 12633 @group | 13303 @group |
| 12634 @@deftp @{Data type@} pair car cdr | 13304 @@deftp @{Data type@} pair car cdr |
| 12635 @dots{} | 13305 @dots{} |
| 12664 variable is a variable that belongs to the class but for which each | 13334 variable is a variable that belongs to the class but for which each |
| 12665 instance has its own value. | 13335 instance has its own value. |
| 12666 | 13336 |
| 12667 @menu | 13337 @menu |
| 12668 * Variables: Object-Oriented Variables. | 13338 * Variables: Object-Oriented Variables. |
| 12669 * Methods: Object-Oriented Methods. | 13339 * Methods: Object-Oriented Methods. |
| 12670 @end menu | 13340 @end menu |
| 12671 | 13341 |
| 12672 | 13342 |
| 12673 @node Object-Oriented Variables | 13343 @node Object-Oriented Variables |
| 12674 @subsubsection Object-Oriented Variables | 13344 @subsubsection Object-Oriented Variables |
| 12775 | 13445 |
| 12776 @code{@@deftypeivar} creates an entry in the index of variables. | 13446 @code{@@deftypeivar} creates an entry in the index of variables. |
| 12777 | 13447 |
| 12778 @end table | 13448 @end table |
| 12779 | 13449 |
| 13450 | |
| 12780 @node Object-Oriented Methods | 13451 @node Object-Oriented Methods |
| 12781 @subsubsection Object-Oriented Methods | 13452 @subsubsection Object-Oriented Methods |
| 12782 | 13453 |
| 12783 @cindex Methods, object-oriented | 13454 @cindex Methods, object-oriented |
| 12784 | 13455 |
| 12795 method-like entities. | 13466 method-like entities. |
| 12796 | 13467 |
| 12797 For example, some systems have constructs called @dfn{wrappers} that | 13468 For example, some systems have constructs called @dfn{wrappers} that |
| 12798 are associated with classes as methods are, but that act more like | 13469 are associated with classes as methods are, but that act more like |
| 12799 macros than like functions. You could use @code{@@defop Wrapper} to | 13470 macros than like functions. You could use @code{@@defop Wrapper} to |
| 12800 describe one of these.@refill | 13471 describe one of these. |
| 12801 | 13472 |
| 12802 Sometimes it is useful to distinguish methods and @dfn{operations}. | 13473 Sometimes it is useful to distinguish methods and @dfn{operations}. |
| 12803 You can think of an operation as the specification for a method. | 13474 You can think of an operation as the specification for a method. |
| 12804 Thus, a window system might specify that all window classes have a | 13475 Thus, a window system might specify that all window classes have a |
| 12805 method named @code{expose}; we would say that this window system | 13476 method named @code{expose}; we would say that this window system |
| 12806 defines an @code{expose} operation on windows in general. Typically, | 13477 defines an @code{expose} operation on windows in general. Typically, |
| 12807 the operation has a name and also specifies the pattern of arguments; | 13478 the operation has a name and also specifies the pattern of arguments; |
| 12808 all methods that implement the operation must accept the same | 13479 all methods that implement the operation must accept the same |
| 12809 arguments, since applications that use the operation do so without | 13480 arguments, since applications that use the operation do so without |
| 12810 knowing which method will implement it.@refill | 13481 knowing which method will implement it. |
| 12811 | 13482 |
| 12812 Often it makes more sense to document operations than methods. For | 13483 Often it makes more sense to document operations than methods. For |
| 12813 example, window application developers need to know about the | 13484 example, window application developers need to know about the |
| 12814 @code{expose} operation, but need not be concerned with whether a | 13485 @code{expose} operation, but need not be concerned with whether a |
| 12815 given class of windows has its own method to implement this operation. | 13486 given class of windows has its own method to implement this operation. |
| 12816 To describe this operation, you would write:@refill | 13487 To describe this operation, you would write: |
| 12817 | 13488 |
| 12818 @example | 13489 @example |
| 12819 @@defop Operation windows expose | 13490 @@defop Operation windows expose |
| 12820 @end example | 13491 @end example |
| 12821 | 13492 |
| 12822 The @code{@@defop} command is written at the beginning of a line and | 13493 The @code{@@defop} command is written at the beginning of a line and |
| 12823 is followed on the same line by the overall name of the category of | 13494 is followed on the same line by the overall name of the category of |
| 12824 operation, the name of the class of the operation, the name of the | 13495 operation, the name of the class of the operation, the name of the |
| 12825 operation, and its arguments, if any.@refill | 13496 operation, and its arguments, if any. |
| 12826 | 13497 |
| 12827 The template is: | 13498 The template is: |
| 12828 @example | 13499 @example |
| 12829 @group | 13500 @group |
| 12830 @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} | 13501 @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} |
| 12832 @@end defop | 13503 @@end defop |
| 12833 @end group | 13504 @end group |
| 12834 @end example | 13505 @end example |
| 12835 | 13506 |
| 12836 @code{@@defop} creates an entry, such as `@code{expose} on | 13507 @code{@@defop} creates an entry, such as `@code{expose} on |
| 12837 @code{windows}', in the index of functions.@refill | 13508 @code{windows}', in the index of functions. |
| 12838 | 13509 |
| 12839 @findex deftypeop | 13510 @findex deftypeop |
| 12840 @item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} | 13511 @item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} |
| 12841 The @code{@@deftypeop} command is the definition command for typed | 13512 The @code{@@deftypeop} command is the definition command for typed |
| 12842 operations in object-oriented programming. It is similar to | 13513 operations in object-oriented programming. It is similar to |
| 12858 @end ignore | 13529 @end ignore |
| 12859 | 13530 |
| 12860 @code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}. | 13531 @code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}. |
| 12861 The command is written at the beginning of a line and is followed by | 13532 The command is written at the beginning of a line and is followed by |
| 12862 the name of the class of the method, the name of the method, and its | 13533 the name of the class of the method, the name of the method, and its |
| 12863 arguments, if any.@refill | 13534 arguments, if any. |
| 12864 | 13535 |
| 12865 @noindent | 13536 @noindent |
| 12866 For example: | 13537 For example: |
| 12867 @example | 13538 @example |
| 12868 @group | 13539 @group |
| 12886 @var{data-type} parameter to specify the return type of the method. | 13557 @var{data-type} parameter to specify the return type of the method. |
| 12887 @code{@@deftypemethod} creates an entry in the index of functions. | 13558 @code{@@deftypemethod} creates an entry in the index of functions. |
| 12888 | 13559 |
| 12889 @end table | 13560 @end table |
| 12890 | 13561 |
| 13562 The typed commands are affected by the @code{@@deftypefnnewline} | |
| 13563 option (@pxref{Typed Functions,, Functions in Typed Languages}). | |
| 13564 | |
| 12891 | 13565 |
| 12892 @node Def Cmd Conventions | 13566 @node Def Cmd Conventions |
| 12893 @section Conventions for Writing Definitions | 13567 @section Conventions for Writing Definitions |
| 12894 @cindex Definition conventions | 13568 @cindex Definition conventions |
| 12895 @cindex Conventions for writing definitions | 13569 @cindex Conventions for writing definitions |
| 12897 When you write a definition using @code{@@deffn}, @code{@@defun}, or | 13571 When you write a definition using @code{@@deffn}, @code{@@defun}, or |
| 12898 one of the other definition commands, please take care to use | 13572 one of the other definition commands, please take care to use |
| 12899 arguments that indicate the meaning, as with the @var{count} argument | 13573 arguments that indicate the meaning, as with the @var{count} argument |
| 12900 to the @code{forward-word} function. Also, if the name of an argument | 13574 to the @code{forward-word} function. Also, if the name of an argument |
| 12901 contains the name of a type, such as @var{integer}, take care that the | 13575 contains the name of a type, such as @var{integer}, take care that the |
| 12902 argument actually is of that type.@refill | 13576 argument actually is of that type. |
| 12903 | 13577 |
| 12904 | 13578 |
| 12905 @node Sample Function Definition | 13579 @node Sample Function Definition |
| 12906 @section A Sample Function Definition | 13580 @section A Sample Function Definition |
| 12907 @cindex Function definitions | 13581 @cindex Function definitions |
| 12908 @cindex Command definitions | 13582 @cindex Command definitions |
| 12909 @cindex Macro definitions | 13583 @cindex Macro definitions, programming-language |
| 12910 @cindex Sample function definition | 13584 @cindex Sample function definition |
| 12911 | 13585 |
| 12912 A function definition uses the @code{@@defun} and @code{@@end defun} | 13586 A function definition uses the @code{@@defun} and @code{@@end defun} |
| 12913 commands. The name of the function follows immediately after the | 13587 commands. The name of the function follows immediately after the |
| 12914 @code{@@defun} command and it is followed, on the same line, by the | 13588 @code{@@defun} command and it is followed, on the same line, by the |
| 12915 parameter list.@refill | 13589 parameter list. |
| 12916 | 13590 |
| 12917 Here is a definition from @ref{Calling Functions,,, lispref, XEmacs Lisp | 13591 Here is a definition from @ref{Calling Functions,,, lispref, XEmacs Lisp |
| 12918 Reference Manual}. | 13592 Reference Manual}. |
| 12919 | 13593 |
| 12920 @quotation | 13594 @quotation |
| 12943 (apply 'append '((a b c) nil (x y z) nil)) | 13617 (apply 'append '((a b c) nil (x y z) nil)) |
| 12944 @result{} (a b c x y z) | 13618 @result{} (a b c x y z) |
| 12945 @end example | 13619 @end example |
| 12946 | 13620 |
| 12947 An interesting example of using @code{apply} is found in the description | 13621 An interesting example of using @code{apply} is found in the description |
| 12948 of @code{mapcar}.@refill | 13622 of @code{mapcar}. |
| 12949 @end defun | 13623 @end defun |
| 12950 @end quotation | 13624 @end quotation |
| 12951 | 13625 |
| 12952 @need 1200 | |
| 12953 In the Texinfo source file, this example looks like this: | 13626 In the Texinfo source file, this example looks like this: |
| 12954 | 13627 |
| 12955 @example | 13628 @example |
| 12956 @group | 13629 @group |
| 12957 @@defun apply function &rest arguments | 13630 @@defun apply function &rest arguments |
| 12994 @end group | 13667 @end group |
| 12995 @end example | 13668 @end example |
| 12996 | 13669 |
| 12997 @noindent | 13670 @noindent |
| 12998 In this manual, this function is listed in the Command and Variable | 13671 In this manual, this function is listed in the Command and Variable |
| 12999 Index under @code{apply}.@refill | 13672 Index under @code{apply}. |
| 13000 | 13673 |
| 13001 Ordinary variables and user options are described using a format like | 13674 Ordinary variables and user options are described using a format like |
| 13002 that for functions except that variables do not take arguments. | 13675 that for functions except that variables do not take arguments. |
| 13676 | |
| 13677 | |
| 13678 @node Internationalization | |
| 13679 @chapter Internationalization | |
| 13680 | |
| 13681 @cindex Internationalization | |
| 13682 Texinfo has some support for writing in languages other than English, | |
| 13683 although this area still needs considerable work. (If you are | |
| 13684 yourself helping to translate the fixed strings written to documents, | |
| 13685 @pxref{Internationalization of Document Strings}.) | |
| 13686 | |
| 13687 For a list of the various accented and special characters Texinfo | |
| 13688 supports, see @ref{Inserting Accents}. | |
| 13689 | |
| 13690 @menu | |
| 13691 * @t{@@documentlanguage}:: Declaring the current language. | |
| 13692 * @t{@@documentencoding}:: Declaring the input encoding. | |
| 13693 @end menu | |
| 13694 | |
| 13695 | |
| 13696 @node @t{@@documentlanguage} | |
| 13697 @section @code{@@documentlanguage @var{ll}[_@var{cc}]}: Set the Document Language | |
| 13698 @anchor{documentlanguage} | |
| 13699 | |
| 13700 @findex documentlanguage | |
| 13701 @cindex Language, declaring | |
| 13702 @cindex Locale, declaring | |
| 13703 @cindex Document language, declaring | |
| 13704 | |
| 13705 The @code{@@documentlanguage} command declares the current document | |
| 13706 locale. Write it on a line by itself, near the beginning of the file, | |
| 13707 but after @code{@@setfilename} (@pxref{@t{@@setfilename}}): | |
| 13708 | |
| 13709 @example | |
| 13710 @@documentlanguage @var{ll}[_@var{cc}] | |
| 13711 @end example | |
| 13712 | |
| 13713 Include a two-letter ISO@tie{}639-2 language code (@var{ll}) following | |
| 13714 the command name, optionally followed by an underscore and two-letter | |
| 13715 ISO@tie{}3166 two-letter country code (@var{cc}). If you have a | |
| 13716 multilingual document, the intent is to be able to use this command | |
| 13717 multiple times, to declare each language change. If the command is | |
| 13718 not used at all, the default is @code{en_US} for US English. | |
| 13719 | |
| 13720 As with GNU Gettext (@pxref{Top,,, gettext, Gettext}), if the country | |
| 13721 code is omitted, the main dialect is assumed where possible. For | |
| 13722 example, @code{de} is equivalent to @code{de_DE} (German as spoken in | |
| 13723 Germany). | |
| 13724 | |
| 13725 @cindex Document strings, translation of | |
| 13726 For Info and other online output, this command changes the translation | |
| 13727 of various @dfn{document strings} such as ``see'' in cross references | |
| 13728 (@pxref{Cross References}), ``Function' in defuns (@pxref{Definition | |
| 13729 Commands}), and so on. Some strings, such as ``Node:'', ``Next:'', | |
| 13730 ``Menu:'', etc., are keywords in Info output, so are not translated | |
| 13731 there; they are translated in other output formats. | |
| 13732 | |
| 13733 @cindex @file{txi-@var{cc}.tex} | |
| 13734 For @TeX{}, this command causes a file @file{txi-@var{locale}.tex} to | |
| 13735 be read (if it exists). If @code{@@documentlanguage} argument | |
| 13736 contains the optional @samp{_@var{cc}} suffix, this is tried first. | |
| 13737 For example, with @code{@@documentlanguage de_DE}, @TeX{} first looks | |
| 13738 for @file{txi-de_DE.tex}, then @file{txi-de.tex}. | |
| 13739 | |
| 13740 Such a @file{txi-*} file is intended to redefine the various English | |
| 13741 words used in @TeX{} output, such as `Chapter', `See', and so on. We | |
| 13742 are aware that individual words like these cannot always be translated | |
| 13743 in isolation, and that a very different strategy would be required for | |
| 13744 ideographic (among other) scripts. Help in improving Texinfo's | |
| 13745 language support is welcome. | |
| 13746 | |
| 13747 @cindex Hyphenation patterns, language-dependent | |
| 13748 @code{@@documentlanguage} also changes @TeX{}'s current hyphenation | |
| 13749 patterns, if the @TeX{} program being run has the necessary support | |
| 13750 included. This will generally not be the case for @command{tex} | |
| 13751 itself, but will usually be the case for up-to-date distributions of | |
| 13752 the extended @TeX{} programs @command{etex} (DVI output) and | |
| 13753 @command{pdftex} (PDF output). @command{texi2dvi} will use the | |
| 13754 extended @TeX{}s if they are available (@pxref{Format with | |
| 13755 @t{texi2dvi}}). | |
| 13756 | |
| 13757 In September 2006, the W3C Internationalization Activity released a | |
| 13758 new recommendation for specifying languages: | |
| 13759 @url{http://www.rfc-editor.org/rfc/bcp/bcp47.txt}. When Gettext | |
| 13760 supports this new scheme, Texinfo will too. | |
| 13761 | |
| 13762 @cindex ISO 639-2 language codes | |
| 13763 @cindex ISO 3166 country codes | |
| 13764 @cindex Language codes | |
| 13765 @cindex Country codes | |
| 13766 Since the lists of language codes and country codes are updated | |
| 13767 relatively frequently, we don't attempt to list them here. The valid | |
| 13768 language codes are on the official home page for ISO@tie{}639, | |
| 13769 @url{http://www.loc.gov/standards/iso639-2/}. The country codes and | |
| 13770 the official web site for ISO@tie{}3166 can be found via | |
| 13771 @url{http://en.wikipedia.org/wiki/ISO_3166}. | |
| 13772 | |
| 13773 | |
| 13774 @node @t{@@documentencoding} | |
| 13775 @section @code{@@documentencoding @var{enc}}: Set Input Encoding | |
| 13776 | |
| 13777 @anchor{documentencoding}@c old name | |
| 13778 @findex documentencoding | |
| 13779 @cindex Encoding, declaring | |
| 13780 @cindex Input encoding, declaring | |
| 13781 @cindex Character set, declaring | |
| 13782 @cindex Document input encoding | |
| 13783 | |
| 13784 The @code{@@documentencoding} command declares the input document | |
| 13785 encoding. Write it on a line by itself, with a valid encoding | |
| 13786 specification following, near the beginning of the file but after | |
| 13787 @code{@@setfilename} (@pxref{@t{@@setfilename}}): | |
| 13788 | |
| 13789 @example | |
| 13790 @@documentencoding @var{enc} | |
| 13791 @end example | |
| 13792 | |
| 13793 At present, Texinfo supports only these encodings: | |
| 13794 | |
| 13795 @table @code | |
| 13796 @item US-ASCII | |
| 13797 This has no particular effect, but it's included for completeness. | |
| 13798 | |
| 13799 @item UTF-8 | |
| 13800 The vast global character encoding, expressed in 8-bit bytes. | |
| 13801 | |
| 13802 @item ISO-8859-2 | |
| 13803 @itemx ISO-8859-1 | |
| 13804 @itemx ISO-8859-15 | |
| 13805 These specify the standard encodings for Western European (the first | |
| 13806 two) and Eastern European languages (the third), respectively. ISO | |
| 13807 8859-15 replaces some little-used characters from 8859-1 (e.g., | |
| 13808 precomposed fractions) with more commonly needed ones, such as the | |
| 13809 Euro symbol (@euro{}). | |
| 13810 | |
| 13811 A full description of the encodings is beyond our scope here; | |
| 13812 one useful reference is @uref{http://czyborra.com/charsets/iso8859.html}. | |
| 13813 | |
| 13814 @item koi8-r | |
| 13815 This is the commonly used encoding for the Russian language. | |
| 13816 | |
| 13817 @item koi8-u | |
| 13818 This is the commonly used encoding for the Ukrainian language. | |
| 13819 | |
| 13820 @end table | |
| 13821 | |
| 13822 Specifying an encoding @var{enc} has the following effects: | |
| 13823 | |
| 13824 @cindex Local Variables section, for encoding | |
| 13825 @cindex Info output, and encoding | |
| 13826 In Info output, a so-called `Local Variables' section (@pxref{File | |
| 13827 Variables,,,xemacs, XEmacs User's Manual}) is output including | |
| 13828 @var{enc}. This allows Info readers to set the encoding | |
| 13829 appropriately. It looks like this: | |
| 13830 | |
| 13831 @example | |
| 13832 Local Variables: | |
| 13833 coding: @var{enc} | |
| 13834 End: | |
| 13835 @end example | |
| 13836 | |
| 13837 Also, in Info and plain text output, unless the option | |
| 13838 @option{--disable-encoding} is given to @command{makeinfo}, accent | |
| 13839 constructs and special characters, such as @code{@@'e}, are output as | |
| 13840 the actual 8-bit or UTF-8 character in the given encoding where | |
| 13841 possible. | |
| 13842 | |
| 13843 @cindex HTML output, and encodings | |
| 13844 @cindex @code{http-equiv}, and charset specification | |
| 13845 @cindex @code{<meta>} HTML tag, and charset specification | |
| 13846 In HTML output, a @samp{<meta>} tag is output, in the @samp{<head>} | |
| 13847 section of the HTML, that specifies @var{enc}. Web servers and | |
| 13848 browsers cooperate to use this information so the correct encoding is | |
| 13849 used to display the page, if supported by the system. That looks like | |
| 13850 this: | |
| 13851 | |
| 13852 @example | |
| 13853 <meta http-equiv="Content-Type" content="text/html; | |
| 13854 charset=@var{enc}"> | |
| 13855 @end example | |
| 13856 | |
| 13857 In XML and Docbook output, UTF-8 is always used for the output file, | |
| 13858 since all XML processors are supposed to be able to process that | |
| 13859 encoding. | |
| 13860 | |
| 13861 @cindex Computer Modern fonts | |
| 13862 In @TeX{} output, the characters which are supported in the standard | |
| 13863 Computer Modern fonts are output accordingly. (For example, this | |
| 13864 means using constructed accents rather than precomposed glyphs.) | |
| 13865 Using a missing character generates a warning message, as does | |
| 13866 specifying an unimplemented encoding. | |
| 13867 | |
| 13868 Although modern @TeX{} systems support nearly every script in use in | |
| 13869 the world, this wide-ranging support is not available in | |
| 13870 @file{texinfo.tex}, and it's not feasible to duplicate or incorporate | |
| 13871 all that effort. Our plan to support other scripts is to create a | |
| 13872 @LaTeX{} back-end to @command{texi2any}, where the support is already | |
| 13873 present. | |
| 13003 | 13874 |
| 13004 | 13875 |
| 13005 @node Conditionals | 13876 @node Conditionals |
| 13006 @chapter Conditionally Visible Text | 13877 @chapter Conditionally Visible Text |
| 13007 @cindex Conditionally visible text | 13878 @cindex Conditionally visible text |
| 13019 @itemize @bullet | 13890 @itemize @bullet |
| 13020 @item | 13891 @item |
| 13021 Commands specific to an output format (Info, @TeX{}, HTML, @dots{}). | 13892 Commands specific to an output format (Info, @TeX{}, HTML, @dots{}). |
| 13022 | 13893 |
| 13023 @item | 13894 @item |
| 13024 Commands specific to any output format @emph{other} than a given | 13895 Commands specific to any output format @emph{excluding} a given |
| 13025 one (not Info, not @TeX{}, @dots{}). | 13896 one (e.g., not Info, not @TeX{}, @dots{}). |
| 13026 | 13897 |
| 13027 @item | 13898 @item |
| 13028 `Raw' formatter text for any output format, passed straight | 13899 `Raw' formatter text for any output format, passed straight |
| 13029 through with no interpretation of @@-commands. | 13900 through with minimal (but not zero) interpretation of @@-commands. |
| 13030 | 13901 |
| 13031 @item | 13902 @item |
| 13032 Format-independent variable substitutions, and testing if a variable | 13903 Format-independent variable substitutions, and testing if a variable |
| 13033 is set or clear. | 13904 is set or clear. |
| 13034 | 13905 |
| 13036 | 13907 |
| 13037 @menu | 13908 @menu |
| 13038 * Conditional Commands:: Text for a given format. | 13909 * Conditional Commands:: Text for a given format. |
| 13039 * Conditional Not Commands:: Text for any format other than a given one. | 13910 * Conditional Not Commands:: Text for any format other than a given one. |
| 13040 * Raw Formatter Commands:: Using raw formatter commands. | 13911 * Raw Formatter Commands:: Using raw formatter commands. |
| 13041 * set clear value:: Variable tests and substitutions. | 13912 * Inline Conditionals:: Brace-delimited conditional text. |
| 13913 * @t{@@set @@clear @@value}:: Variable tests and substitutions. | |
| 13914 * Testing for Texinfo Commands:: Testing if a Texinfo command is available. | |
| 13042 * Conditional Nesting:: Using conditionals inside conditionals. | 13915 * Conditional Nesting:: Using conditionals inside conditionals. |
| 13043 @end menu | 13916 @end menu |
| 13044 | 13917 |
| 13045 | 13918 |
| 13046 @node Conditional Commands | 13919 @node Conditional Commands |
| 13060 @findex ifdocbook | 13933 @findex ifdocbook |
| 13061 @findex ifhtml | 13934 @findex ifhtml |
| 13062 @findex ifplaintext | 13935 @findex ifplaintext |
| 13063 @findex iftex | 13936 @findex iftex |
| 13064 @findex ifxml | 13937 @findex ifxml |
| 13065 The environments for the other formats are analogous: | 13938 The environments for the other formats are analogous, but without the |
| 13939 special historical case: | |
| 13066 | 13940 |
| 13067 @table @code | 13941 @table @code |
| 13068 @item @@ifdocbook @dots{} @@end ifdocbook | 13942 @item @@ifdocbook @dots{} @@end ifdocbook |
| 13069 Text to appear only in the Docbook output. | 13943 Text to appear only in the Docbook output. |
| 13070 | 13944 |
| 13080 @item @@ifxml @dots{} @@end ifxml | 13954 @item @@ifxml @dots{} @@end ifxml |
| 13081 Text to appear only in the XML output. | 13955 Text to appear only in the XML output. |
| 13082 @end table | 13956 @end table |
| 13083 | 13957 |
| 13084 The @code{@@if@dots{}} and @code{@@end if@dots{}} commands must appear | 13958 The @code{@@if@dots{}} and @code{@@end if@dots{}} commands must appear |
| 13085 on lines by themselves in your source file. | 13959 on lines by themselves in your source file. The newlines following |
| 13960 the commands are (more or less) treated as whitespace, so that the | |
| 13961 conditional text is flowed normally into a surrounding paragraph. | |
| 13962 | |
| 13963 The @code{@@if@dots{}} constructs are intended to conditionalize | |
| 13964 normal Texinfo source; @pxref{Raw Formatter Commands}, for using | |
| 13965 underlying format commands directly. | |
| 13086 | 13966 |
| 13087 Here is an example showing all these conditionals: | 13967 Here is an example showing all these conditionals: |
| 13088 | 13968 |
| 13089 @example | 13969 @example |
| 13090 @@iftex | 13970 @@iftex |
| 13098 @@end ifhtml | 13978 @@end ifhtml |
| 13099 @@ifplaintext | 13979 @@ifplaintext |
| 13100 Whereas this text will only appear in plain text. | 13980 Whereas this text will only appear in plain text. |
| 13101 @@end ifplaintext | 13981 @@end ifplaintext |
| 13102 @@ifxml | 13982 @@ifxml |
| 13103 Notwithstanding that this will only appear in XML. | 13983 Notwithstanding that this will only appear in XML@. |
| 13104 @@end ifxml | 13984 @@end ifxml |
| 13105 @@ifdocbook | 13985 @@ifdocbook |
| 13106 Nevertheless, this will only appear in Docbook. | 13986 Nevertheless, this will only appear in Docbook. |
| 13107 @@end ifdocbook | 13987 @@end ifdocbook |
| 13108 @end example | 13988 @end example |
| 13121 @end ifhtml | 14001 @end ifhtml |
| 13122 @ifplaintext | 14002 @ifplaintext |
| 13123 Whereas this text will only appear in plain text. | 14003 Whereas this text will only appear in plain text. |
| 13124 @end ifplaintext | 14004 @end ifplaintext |
| 13125 @ifxml | 14005 @ifxml |
| 13126 Notwithstanding that this will only appear in XML. | 14006 Notwithstanding that this will only appear in XML@. |
| 13127 @end ifxml | 14007 @end ifxml |
| 13128 @ifdocbook | 14008 @ifdocbook |
| 13129 Nevertheless, this will only appear in Docbook. | 14009 Nevertheless, this will only appear in Docbook. |
| 13130 @end ifdocbook | 14010 @end ifdocbook |
| 13131 | 14011 |
| 13132 @noindent | 14012 @noindent |
| 13133 Notice that you only see one of the input lines, depending on which | 14013 Notice that you only see one of the input lines, depending on which |
| 13134 version of the manual you are reading. | 14014 version of the manual you are reading. |
| 14015 | |
| 14016 @findex errormsg | |
| 14017 In complex documents, you may want Texinfo to issue an error message | |
| 14018 in some conditionals that should not ever be processed. The | |
| 14019 @code{@@errormsg@{@var{text}@}} command will do this; it takes one | |
| 14020 argument, the text of the error message, which is expanded more or | |
| 14021 less as if it were Info text. | |
| 14022 | |
| 14023 We mention @code{@@errormsg@{@}} here even though it is not strictly | |
| 14024 related to conditionals, since in practice it is most likely to be | |
| 14025 useful in that context. Technically, it can be used anywhere. | |
| 14026 @xref{External Macro Processors}, for a caveat regarding the line | |
| 14027 numbers which @code{@@errormsg} emits in @TeX{}. | |
| 13135 | 14028 |
| 13136 | 14029 |
| 13137 @node Conditional Not Commands | 14030 @node Conditional Not Commands |
| 13138 @section Conditional Not Commands | 14031 @section Conditional Not Commands |
| 13139 @findex ifnotdocbook | 14032 @findex ifnotdocbook |
| 13181 | 14074 |
| 13182 | 14075 |
| 13183 @node Raw Formatter Commands | 14076 @node Raw Formatter Commands |
| 13184 @section Raw Formatter Commands | 14077 @section Raw Formatter Commands |
| 13185 @cindex Raw formatter commands | 14078 @cindex Raw formatter commands |
| 14079 | |
| 13186 @cindex @TeX{} commands, using ordinary | 14080 @cindex @TeX{} commands, using ordinary |
| 13187 @cindex Ordinary @TeX{} commands, using | 14081 @cindex Ordinary @TeX{} commands, using |
| 13188 @cindex Commands using raw @TeX{} | 14082 @cindex Commands using raw @TeX{} |
| 13189 @cindex Docbook, including raw | |
| 13190 @cindex HTML, including raw | |
| 13191 @cindex XML, including raw | |
| 13192 @cindex Plain @TeX{} | 14083 @cindex Plain @TeX{} |
| 13193 | 14084 |
| 13194 Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, | 14085 The @code{@@if@dots{}} conditionals just described must be used only |
| 13195 you can embed some raw @TeX{} commands. The Texinfo processors will | 14086 with normal Texinfo source. For instance, most features of plain |
| 13196 ignore such a region unless @TeX{} output is being produced. You can | 14087 @TeX{} will not work within @code{@@iftex}. The purpose of |
| 13197 write the @TeX{} commands as you would write them in a normal @TeX{} | 14088 @code{@@if@dots{}} is to provide conditional processing for Texinfo |
| 13198 file, except that you must replace the @samp{\} used by @TeX{} with an | 14089 source, not provide access to underlying formatting features. For |
| 13199 @samp{@@}. For example, in the @code{@@titlepage} section of a | 14090 that, Texinfo provides so-called @dfn{raw formatter commands}. They |
| 13200 Texinfo file, you can use the @TeX{} command @code{@@vskip} to format | 14091 should only be used when truly required (most documents do not need |
| 13201 the copyright page. (The @code{@@titlepage} command causes Info to | 14092 them). |
| 13202 ignore the region automatically, as it does with the @code{@@iftex} | |
| 13203 command.) | |
| 13204 | |
| 13205 However, most features of plain @TeX{} will not work within | |
| 13206 @code{@@iftex}, as they are overridden by Texinfo features. The | |
| 13207 purpose of @code{@@iftex} is to provide conditional processing for the | |
| 13208 Texinfo source, not provide access to underlying formatting features. | |
| 13209 | 14093 |
| 13210 @findex tex | 14094 @findex tex |
| 13211 You can enter plain @TeX{} completely, and use @samp{\} in the @TeX{} | 14095 @cindex Category codes, of plain @TeX{} |
| 13212 commands, by delineating a region with the @code{@@tex} and @code{@@end | 14096 The first raw formatter command is @code{@@tex}. You can enter plain |
| 13213 tex} commands. All plain @TeX{} commands and category codes are | 14097 @TeX{} completely, and use @samp{\} in the @TeX{} commands, by |
| 13214 restored within an @code{@@tex} region. The sole exception is that the | 14098 delineating a region with the @code{@@tex} and @code{@@end tex} |
| 13215 @code{@@} character still introduces a command, so that @code{@@end tex} | 14099 commands. All plain @TeX{} commands and category codes are restored |
| 13216 can be recognized properly. As with @code{@@iftex}, Texinfo | 14100 within an @code{@@tex} region. The sole exception is that the |
| 13217 processors will ignore such a region unless @TeX{} output is being produced. | 14101 @code{@@} character still introduces a command, so that @code{@@end |
| 14102 tex} can be recognized. Texinfo processors will not output material | |
| 14103 in such a region, unless @TeX{} output is being produced. | |
| 13218 | 14104 |
| 13219 @findex \gdef @r{within @code{@@tex}} | 14105 @findex \gdef @r{within @code{@@tex}} |
| 14106 @findex \globaldefs @r{within @code{@@tex}} | |
| 13220 In complex cases, you may wish to define new @TeX{} macros within | 14107 In complex cases, you may wish to define new @TeX{} macros within |
| 13221 @code{@@tex}. You must use @code{\gdef} to do this, not @code{\def}, | 14108 @code{@@tex}. You must use @code{\gdef} to do this, not @code{\def}, |
| 13222 because @code{@@tex} regions are processed in a @TeX{} group. | 14109 because @code{@@tex} regions are processed in a @TeX{} group. If you |
| 13223 | 14110 need to make several definitions, you may wish to set |
| 13224 @cindex Mathematical expressions | 14111 @code{\globaldefs=1} (its value will be restored to zero as usual when |
| 13225 As an example, here is a mathematical expression written in plain @TeX{}: | 14112 the group ends at @code{@@end tex}, so it won't cause problems with |
| 14113 the rest of the document). | |
| 14114 | |
| 14115 @cindex Equation, displayed, in plain @TeX{} | |
| 14116 @cindex Displayed equation, in plain @TeX{} | |
| 14117 As an example, here is a displayed equation written in plain @TeX{}: | |
| 13226 | 14118 |
| 13227 @example | 14119 @example |
| 13228 @@tex | 14120 @@tex |
| 13229 $$ \chi^2 = \sum_@{i=1@}^N | 14121 $$ \chi^2 = \sum_@{i=1@}^N |
| 13230 \left (y_i - (a + b x_i) | 14122 \left (y_i - (a + b x_i) |
| 13232 @@end tex | 14124 @@end tex |
| 13233 @end example | 14125 @end example |
| 13234 | 14126 |
| 13235 @noindent | 14127 @noindent |
| 13236 The output of this example will appear only in a printed manual. If | 14128 The output of this example will appear only in a printed manual. If |
| 13237 you are reading this in Info, you will not see the equation that appears | 14129 you are reading this in a format not generated by @TeX{}, you will not |
| 13238 in the printed manual. | 14130 see the equation that appears in the printed manual. |
| 13239 @iftex | |
| 13240 In a printed manual, the above expression looks like | |
| 13241 this: | |
| 13242 @end iftex | |
| 13243 | 14131 |
| 13244 @tex | 14132 @tex |
| 13245 $$ \chi^2 = \sum_{i=1}^N | 14133 $$ \chi^2 = \sum_{i=1}^N |
| 13246 \left(y_i - (a + b x_i) | 14134 \left(y_i - (a + b x_i) |
| 13247 \over \sigma_i\right)^2 $$ | 14135 \over \sigma_i\right)^2 $$ |
| 13248 @end tex | 14136 @end tex |
| 13249 | 14137 |
| 14138 @cindex HTML, including raw | |
| 13250 @findex ifhtml | 14139 @findex ifhtml |
| 13251 @findex html | 14140 @findex html |
| 13252 Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to delimit | 14141 Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to |
| 13253 a region to be included in HTML output only, and @code{@@html @dots{} | 14142 delimit Texinfo source to be included in HTML output only, and |
| 13254 @@end html} for a region of raw HTML. | 14143 @code{@@html @dots{} @@end html} for a region of raw HTML. |
| 13255 | 14144 |
| 14145 @cindex XML, including raw | |
| 13256 @findex ifxml | 14146 @findex ifxml |
| 13257 @findex xml | 14147 @findex xml |
| 13258 Likewise, you can use @code{@@ifxml @dots{} @@end ifxml} to delimit | 14148 Likewise, you can use @code{@@ifxml @dots{} @@end ifxml} to delimit |
| 13259 a region to be included in XML output only, and @code{@@xml @dots{} | 14149 Texinfo source to be included in XML output only, and @code{@@xml |
| 13260 @@end xml} for a region of raw XML. | 14150 @dots{} @@end xml} for a region of raw XML@. Regions of raw text in |
| 13261 | 14151 other formats will also be present in the XML output, but with |
| 14152 protection of XML characters and within corresponding elements. For | |
| 14153 example, the raw HTML text: | |
| 14154 | |
| 14155 @example | |
| 14156 @group | |
| 14157 @@html | |
| 14158 <br /> | |
| 14159 @@end html | |
| 14160 @end group | |
| 14161 @end example | |
| 14162 | |
| 14163 @noindent | |
| 14164 will be included in the XML output as: | |
| 14165 | |
| 14166 @example | |
| 14167 @group | |
| 14168 <html> | |
| 14169 <br /> | |
| 14170 </html> | |
| 14171 @end group | |
| 14172 @end example | |
| 14173 | |
| 14174 @cindex Docbook, including raw | |
| 13262 @findex ifdocbook | 14175 @findex ifdocbook |
| 13263 @findex docbook | 14176 @findex docbook |
| 13264 Again likewise, you can use @code{@@ifdocbook @dots{} @@end ifdocbook} | 14177 Again likewise, you can use @code{@@ifdocbook @dots{} @@end ifdocbook} |
| 13265 to delimit a region to be included in Docbook output only, and | 14178 to delimit Texinfo source to be included in Docbook output only, and |
| 13266 @code{@@docbook @dots{} @@end docbook} for a region of raw Docbook. | 14179 @code{@@docbook @dots{} @@end docbook} for a region of raw Docbook. |
| 13267 | 14180 |
| 13268 In all cases, the exception to the raw processing is that @code{@@} is | 14181 The behavior of newlines in raw regions is unspecified. |
| 13269 still an escape character, so the @code{@@end} command can be | 14182 |
| 13270 recognized. | 14183 In all cases, in raw processing, @code{@@} retains the same meaning as |
| 13271 | 14184 in the remainder of the document. Thus, the Texinfo processors |
| 13272 | 14185 recognize and even execute, to some extent, the contents of the raw |
| 13273 @node set clear value | 14186 regions, regardless of the final output format. Therefore, specifying |
| 13274 @section @code{@@set}, @code{@@clear}, and @code{@@value} | 14187 changes that globally affect the document inside a raw region leads to |
| 13275 | 14188 unpredictable and generally undesirable behavior. For example, it |
| 14189 using the @code{@@kbdinputstyle} command inside a raw region is undefined. | |
| 14190 | |
| 14191 The remedy is simple: don't do that. Use the raw formatter commands | |
| 14192 for their intended purpose, of providing material directly in the | |
| 14193 underlying format. When you simply want to give different Texinfo | |
| 14194 specifications for different output formats, use the | |
| 14195 @code{@@if@dots{}} conditionals and stay in Texinfo syntax. | |
| 14196 | |
| 14197 | |
| 14198 | |
| 14199 @node Inline Conditionals | |
| 14200 @section Inline Conditionals: @code{@@inline}, @code{@@inlineifelse}, @code{@@inlineraw} | |
| 14201 @findex inlinefmt | |
| 14202 @findex inlinefmtifelse | |
| 14203 @findex inlineraw | |
| 14204 @cindex Inline conditionals | |
| 14205 @cindex Conditional commands, inline | |
| 14206 @cindex Brace-delimited conditional text | |
| 14207 @cindex Newlines, avoiding in conditionals | |
| 14208 @cindex Whitespace, controlling in conditionals | |
| 14209 | |
| 14210 Texinfo provides a set of conditional commands with arguments given | |
| 14211 within braces: | |
| 14212 | |
| 14213 @table @code | |
| 14214 @item @@inlinefmt@{@var{format}, @var{text}@} | |
| 14215 Process the Texinfo @var{text} if @var{format} output is being | |
| 14216 generated. | |
| 14217 | |
| 14218 @item @@inlinefmtifelse@{@var{format}, @var{then-text}, @var{else-text}@} | |
| 14219 Process the Texinfo @var{then-text} if @var{format} output is being | |
| 14220 generated; otherwise, process @var{else-text}. | |
| 14221 | |
| 14222 @item @@inlineraw@{@var{format}, @var{text}@} | |
| 14223 Similar, but for raw @var{text} (@pxref{Raw Formatter Commands}). | |
| 14224 @end table | |
| 14225 | |
| 14226 The supported @var{format} names are: | |
| 14227 | |
| 14228 @example | |
| 14229 docbook html info plaintext tex xml | |
| 14230 @end example | |
| 14231 | |
| 14232 For example, | |
| 14233 | |
| 14234 @example | |
| 14235 @@inlinefmt@{html, @@emph@{HTML-only text@}@} | |
| 14236 @end example | |
| 14237 | |
| 14238 @noindent is nearly equivalent to | |
| 14239 | |
| 14240 @example | |
| 14241 @@ifhtml | |
| 14242 @@emph@{HTML-only text@} | |
| 14243 @@end ifhtml | |
| 14244 @end example | |
| 14245 | |
| 14246 @noindent except that no whitespace is added, as happens in the latter | |
| 14247 (environment) case. | |
| 14248 | |
| 14249 In these commands, whitespace is ignored after the comma separating | |
| 14250 the arguments, as usual, but is @emph{not} ignored at the end of | |
| 14251 @var{text}. | |
| 14252 | |
| 14253 To insert a literal at sign, left brace, or right brace in one of the | |
| 14254 arguments, you must use the alphabetic commands @code{@@atchar@{@}} | |
| 14255 (@pxref{Inserting an Atsign}), and @code{@@lbracechar@{@}} or | |
| 14256 @code{@@rbracechar@{@}} (@pxref{Inserting Braces}), or the parsing | |
| 14257 will become confused. | |
| 14258 | |
| 14259 With @code{@@inlinefmtifelse}, it is also necessary to use | |
| 14260 @code{@@comma@{@}} to avoid mistaking a @samp{,} in the text for the | |
| 14261 delimiter. With @code{@@inlinefmt} and @code{@@inlineraw}, | |
| 14262 @code{@@comma@{@}} is not required (though it's fine to use it), since | |
| 14263 these commands always have exactly two arguments. | |
| 14264 | |
| 14265 For @TeX{}, the processed @var{text} cannot contain newline-delimited | |
| 14266 commands. Text to be ignored (i.e., for non-@TeX{}) can, though. | |
| 14267 | |
| 14268 Two other @code{@@inline...} conditionals complement the | |
| 14269 @code{@@ifset} and @code{@@ifclear} commands; see the next section. | |
| 14270 | |
| 14271 | |
| 14272 @node @t{@@set @@clear @@value} | |
| 14273 @section Flags: @code{@@set}, @code{@@clear}, conditionals, and @code{@@value} | |
| 14274 | |
| 14275 @anchor{set clear value}@c old name | |
| 13276 You can direct the Texinfo formatting commands to format or ignore parts | 14276 You can direct the Texinfo formatting commands to format or ignore parts |
| 13277 of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset}, | 14277 of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset}, |
| 13278 and @code{@@ifclear} commands. | 14278 and @code{@@ifclear} commands. |
| 13279 | 14279 |
| 13280 Here are brief descriptions of these commands, see the following | 14280 Here are brief descriptions of these commands, see the following |
| 13290 @item @@ifset @var{flag} | 14290 @item @@ifset @var{flag} |
| 13291 If @var{flag} is set, text through the next @code{@@end ifset} command | 14291 If @var{flag} is set, text through the next @code{@@end ifset} command |
| 13292 is formatted. If @var{flag} is clear, text through the following | 14292 is formatted. If @var{flag} is clear, text through the following |
| 13293 @code{@@end ifset} command is ignored. | 14293 @code{@@end ifset} command is ignored. |
| 13294 | 14294 |
| 14295 @item @@inlineifset@{@var{flag}, @var{text}@} | |
| 14296 Brace-delimited version of @code{@@ifset}. | |
| 14297 | |
| 13295 @item @@ifclear @var{flag} | 14298 @item @@ifclear @var{flag} |
| 13296 If @var{flag} is set, text through the next @code{@@end ifclear} command | 14299 If @var{flag} is set, text through the next @code{@@end ifclear} command |
| 13297 is ignored. If @var{flag} is clear, text through the following | 14300 is ignored. If @var{flag} is clear, text through the following |
| 13298 @code{@@end ifclear} command is formatted. | 14301 @code{@@end ifclear} command is formatted. |
| 14302 | |
| 14303 @item @@inlineifclear@{@var{flag}, @var{text}@} | |
| 14304 Brace-delimited version of @code{@@ifclear}. | |
| 14305 | |
| 13299 @end table | 14306 @end table |
| 13300 | 14307 |
| 13301 @menu | 14308 @menu |
| 13302 * set value:: Expand a flag variable to a string. | 14309 * @t{@@set @@value}:: Expand a flag variable to a string. |
| 13303 * ifset ifclear:: Format a region if a flag is set. | 14310 * @t{@@ifset @@ifclear}:: Format a region if a flag is set. |
| 13304 * value Example:: An easy way to update edition information. | 14311 * @t{@@inlineifset @@inlineifclear}:: Brace-delimited flag conditionals. |
| 14312 * @t{@@value} Example:: An easy way to update edition information. | |
| 13305 @end menu | 14313 @end menu |
| 13306 | 14314 |
| 13307 | 14315 |
| 13308 @node set value | 14316 @node @t{@@set @@value} |
| 13309 @subsection @code{@@set} and @code{@@value} | 14317 @subsection @code{@@set} and @code{@@value} |
| 14318 | |
| 14319 @anchor{set value}@c old name | |
| 13310 @findex set | 14320 @findex set |
| 13311 @findex value | 14321 @findex value |
| 13312 @findex clear | 14322 @findex clear |
| 13313 | 14323 |
| 13314 You use the @code{@@set} command to specify a value for a flag, which | 14324 You use the @code{@@set} command to specify a value for a flag, which |
| 13315 is later expanded by the @code{@@value} command. | 14325 is later expanded by the @code{@@value} command. |
| 13316 | 14326 |
| 13317 A @dfn{flag} (aka @dfn{variable}) is an identifier. It is best to use | 14327 A @dfn{flag} (aka @dfn{variable}) name is an identifier starting with |
| 13318 only letters and numerals in a flag name, not @samp{-} or | 14328 an alphanumeric, @samp{-}, or @samp{_}. Subsequent characters, if |
| 13319 @samp{_}---they will work in some contexts, but not all, due to | 14329 any, may not be whitespace, @samp{@@}, braces, angle brackets, or any |
| 13320 limitations in @TeX{}. | 14330 of @samp{~`^+|}; other characters, such as @samp{%}, may work. |
| 14331 However, it is best to use only letters and numerals in a flag name, | |
| 14332 not @samp{-} or @samp{_} or others---they will work in some contexts, | |
| 14333 but not all, due to limitations in @TeX{}. | |
| 13321 | 14334 |
| 13322 The value is the remainder of the input line, and can contain anything. | 14335 The value is the remainder of the input line, and can contain anything. |
| 14336 However, unlike most other commands which take the rest of the line as | |
| 14337 a value, @code{@@set} need not appear at the beginning of a line. | |
| 13323 | 14338 |
| 13324 Write the @code{@@set} command like this: | 14339 Write the @code{@@set} command like this: |
| 13325 | 14340 |
| 13326 @example | 14341 @example |
| 13327 @@set foo This is a string. | 14342 @@set foo This is a string. |
| 13389 @exdent @r{into} | 14404 @exdent @r{into} |
| 13390 It is a @{No value for "howmuch"@} wet day. | 14405 It is a @{No value for "howmuch"@} wet day. |
| 13391 @end group | 14406 @end group |
| 13392 @end example | 14407 @end example |
| 13393 | 14408 |
| 13394 | 14409 @code{@@value} cannot be reliably used as the argument to an accent |
| 13395 @node ifset ifclear | 14410 command (@pxref{Inserting Accents}). For example, this fails: |
| 14411 | |
| 14412 @example | |
| 14413 @@set myletter a | |
| 14414 @@'@@value@{myletter@} @c fails! | |
| 14415 @end example | |
| 14416 | |
| 14417 | |
| 14418 @node @t{@@ifset @@ifclear} | |
| 13396 @subsection @code{@@ifset} and @code{@@ifclear} | 14419 @subsection @code{@@ifset} and @code{@@ifclear} |
| 13397 | 14420 |
| 14421 @anchor{ifset ifclear}@c old name | |
| 13398 @findex ifset | 14422 @findex ifset |
| 14423 | |
| 13399 When a @var{flag} is set, the Texinfo formatting commands format text | 14424 When a @var{flag} is set, the Texinfo formatting commands format text |
| 13400 between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end | 14425 between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end |
| 13401 ifset} commands. When the @var{flag} is cleared, the Texinfo formatting | 14426 ifset} commands. When the @var{flag} is cleared, the Texinfo formatting |
| 13402 commands do @emph{not} format the text. @code{@@ifclear} operates | 14427 commands do @emph{not} format the text. @code{@@ifclear} operates |
| 13403 analogously. | 14428 analogously. |
| 13461 @example | 14486 @example |
| 13462 @@ifclear @var{flag} | 14487 @@ifclear @var{flag} |
| 13463 @end example | 14488 @end example |
| 13464 | 14489 |
| 13465 | 14490 |
| 13466 @node value Example | 14491 @node @t{@@inlineifset @@inlineifclear} |
| 14492 @subsection @code{@@inlineifset} and @code{@@inlineifclear} | |
| 14493 | |
| 14494 @findex inlineifset | |
| 14495 @findex inlineifclear | |
| 14496 @cindex Flag conditionals, brace-delimited | |
| 14497 @cindex Brace-delimited flag conditionals | |
| 14498 | |
| 14499 @code{@@inlineifset} and @code{@@inlineifclear} provide | |
| 14500 brace-delimited alternatives to the @code{@@ifset} and | |
| 14501 @code{@@ifclear} forms, similar to the other @code{@@inline...} | |
| 14502 Commands (@pxref{Inline Conditionals}). The same caveats about | |
| 14503 argument parsing given there apply here too. | |
| 14504 | |
| 14505 @table @code | |
| 14506 @item @@inlineifset@{@var{var}, @var{text}@} | |
| 14507 Process the Texinfo @var{text} if the flag @var{var} is defined. | |
| 14508 | |
| 14509 @item @@inlineifclear@{@var{var}, @var{text}@} | |
| 14510 Process the Texinfo @var{text} if the flag @var{var} is not defined. | |
| 14511 @end table | |
| 14512 | |
| 14513 Except for the syntax, their general behavior and purposes is the same | |
| 14514 as with @code{@@ifset} and @code{@@ifclear}, described in the previous | |
| 14515 section. | |
| 14516 | |
| 14517 | |
| 14518 @node @t{@@value} Example | |
| 13467 @subsection @code{@@value} Example | 14519 @subsection @code{@@value} Example |
| 14520 | |
| 14521 @anchor{value Example}@c old name | |
| 13468 | 14522 |
| 13469 You can use the @code{@@value} command to minimize the number of | 14523 You can use the @code{@@value} command to minimize the number of |
| 13470 places you need to change when you record an update to a manual. | 14524 places you need to change when you record an update to a manual. |
| 13471 @xref{GNU Sample Texts}, for the full text of an example of using this | 14525 @xref{GNU Sample Texts}, for the full text of an example of using this |
| 13472 to work with Automake distributions. | 14526 to work with Automake distributions. |
| 13473 | 14527 |
| 13474 This example is adapted from @ref{Top,, Overview, make, The GNU Make | 14528 This example is adapted from @ref{Top,,, make, The GNU Make Manual}. |
| 13475 Manual}. | |
| 13476 | 14529 |
| 13477 @enumerate | 14530 @enumerate |
| 13478 @item | 14531 @item |
| 13479 Set the flags: | 14532 Set the flags: |
| 13480 | 14533 |
| 13486 @@set UPDATE-MONTH August 1992 | 14539 @@set UPDATE-MONTH August 1992 |
| 13487 @end group | 14540 @end group |
| 13488 @end example | 14541 @end example |
| 13489 | 14542 |
| 13490 @item | 14543 @item |
| 13491 Write text for the @code{@@copying} section (@pxref{copying}): | 14544 Write text for the @code{@@copying} section (@pxref{@t{@@copying}}): |
| 13492 | 14545 |
| 13493 @example | 14546 @example |
| 13494 @group | 14547 @group |
| 13495 @@copying | 14548 @@copying |
| 13496 This is Edition @@value@{EDITION@}, | 14549 This is Edition @@value@{EDITION@}, |
| 13554 | 14607 |
| 13555 When you update the manual, you change only the values of the flags; you | 14608 When you update the manual, you change only the values of the flags; you |
| 13556 do not need to edit the three sections. | 14609 do not need to edit the three sections. |
| 13557 | 14610 |
| 13558 | 14611 |
| 14612 @node Testing for Texinfo Commands | |
| 14613 @section Testing for Texinfo Commands: @code{@@ifcommanddefined}, @code{@@ifcommandnotdefined} | |
| 14614 | |
| 14615 @cindex Testing for Texinfo commands | |
| 14616 @cindex Checking for Texinfo commands | |
| 14617 @cindex Texinfo commands, testing for | |
| 14618 @cindex Commands, testing for Texinfo | |
| 14619 @cindex Versions of Texinfo, adapting to | |
| 14620 @cindex Features of Texinfo, adapting to | |
| 14621 | |
| 14622 Occasionally, you may want to arrange for your manual to test if a | |
| 14623 given Texinfo command is available and (presumably) do some sort of | |
| 14624 fallback formatting if not. There are conditionals | |
| 14625 @code{@@ifcommanddefined} and @code{@@ifcommandnotdefined} to do this. | |
| 14626 For example: | |
| 14627 | |
| 14628 @example | |
| 14629 @@ifcommanddefined node | |
| 14630 Good, @@samp@{@@@@node@} is defined. | |
| 14631 @@end ifcommanddefined | |
| 14632 @end example | |
| 14633 | |
| 14634 @noindent will output the expected `Good, @samp{@@node} is defined.'. | |
| 14635 | |
| 14636 This conditional will also consider true any new commands defined by | |
| 14637 the document via @code{@@macro}, @code{@@alias}, | |
| 14638 @code{@@definfoenclose}, and @code{@@def@r{(}code@r{)}index} | |
| 14639 (@pxref{Defining New Texinfo Commands}). Caveat: the @TeX{} | |
| 14640 implementation reports internal @TeX{} commands, in addition to all | |
| 14641 the Texinfo commands, as being ``defined''; the @code{makeinfo} | |
| 14642 implementation is reliable in this regard, however. | |
| 14643 | |
| 14644 @pindex @file{NEWS} file for Texinfo | |
| 14645 You can check the @file{NEWS} file in the Texinfo source distribution | |
| 14646 and linked from the Texinfo home page | |
| 14647 (@url{http://www.gnu.org/software/texinfo}) to see when a particular | |
| 14648 command was added. | |
| 14649 | |
| 14650 These command-checking conditionals themselves were added in | |
| 14651 Texinfo@tie{}5.0, released in 2013---decades after Texinfo's | |
| 14652 inception. In order to test if they themselves are available, | |
| 14653 the predefined flag @code{txicommandconditionals} can be tested, like | |
| 14654 this: | |
| 14655 | |
| 14656 @example | |
| 14657 @@ifset txicommandconditionals | |
| 14658 @@ifcommandnotdefined foobarnode | |
| 14659 (Good, @samp{@@foobarnode} is not defined.) | |
| 14660 @@end ifcommandnotdefined | |
| 14661 @@end ifset | |
| 14662 @end example | |
| 14663 | |
| 14664 Since flags (see the previous section) were added early in the | |
| 14665 existence of Texinfo, there is no problem with assuming they are | |
| 14666 available. | |
| 14667 | |
| 14668 We recommend avoiding these tests whenever possible---which is usually | |
| 14669 the case. For many software packages, it is reasonable for all | |
| 14670 developers to have a given version of Texinfo (or newer) installed, | |
| 14671 and thus no reason to worry about older versions. (It is | |
| 14672 straightforward for anyone to download and install the Texinfo source; | |
| 14673 it does not have any problematic dependencies.) | |
| 14674 | |
| 14675 The issue of Texinfo versions does not generally arise for end-users. | |
| 14676 With properly distributed packages, users need not process the Texinfo | |
| 14677 manual simply to build and install the package; they can use | |
| 14678 preformatted Info (or other) output files. This is desirable in | |
| 14679 general, to avoid unnecessary dependencies between packages | |
| 14680 (@pxref{Releases,,, standard, GNU Coding Standards}). | |
| 14681 | |
| 14682 | |
| 13559 @node Conditional Nesting | 14683 @node Conditional Nesting |
| 13560 @section Conditional Nesting | 14684 @section Conditional Nesting |
| 13561 @cindex Conditionals, nested | 14685 @cindex Conditionals, nested |
| 13562 @cindex Nesting conditionals | 14686 @cindex Nesting conditionals |
| 13563 | 14687 |
| 13601 by themselves, with no text (even spaces) before or after. Otherwise, | 14725 by themselves, with no text (even spaces) before or after. Otherwise, |
| 13602 the processors cannot reliably determine which commands to consider | 14726 the processors cannot reliably determine which commands to consider |
| 13603 for nesting purposes. | 14727 for nesting purposes. |
| 13604 | 14728 |
| 13605 | 14729 |
| 13606 @node Internationalization | |
| 13607 @chapter Internationalization | |
| 13608 | |
| 13609 @cindex Internationalization | |
| 13610 Texinfo has some support for writing in languages other than English, | |
| 13611 although this area still needs considerable work. | |
| 13612 | |
| 13613 For a list of the various accented and special characters Texinfo | |
| 13614 supports, see @ref{Inserting Accents}. | |
| 13615 | |
| 13616 @menu | |
| 13617 * documentlanguage:: Declaring the current language. | |
| 13618 * documentencoding:: Declaring the input encoding. | |
| 13619 @end menu | |
| 13620 | |
| 13621 | |
| 13622 @node documentlanguage | |
| 13623 @section @code{@@documentlanguage @var{ll}[_@var{cc}]}: Set the Document Language | |
| 13624 | |
| 13625 @findex documentlanguage | |
| 13626 @cindex Language, declaring | |
| 13627 @cindex Locale, declaring | |
| 13628 @cindex Document language, declaring | |
| 13629 | |
| 13630 The @code{@@documentlanguage} command declares the current document | |
| 13631 locale. Write it on a line by itself, near the beginning of the | |
| 13632 file, but after @code{@@setfilename} | |
| 13633 (@pxref{setfilename,,@code{@@setfilename}}): | |
| 13634 | |
| 13635 @example | |
| 13636 @@documentlanguage @var{ll}[_@var{cc}] | |
| 13637 @end example | |
| 13638 | |
| 13639 Include a two-letter ISO@tie{}639-2 language code (@var{ll}) following | |
| 13640 the command name, optionally followed by an underscore and two-letter | |
| 13641 ISO@tie{}3166 two-letter country code (@var{cc}). If you have a | |
| 13642 multilingual document, the intent is to be able to use this command | |
| 13643 multiple times, to declare each language change. If the command is | |
| 13644 not used at all, the default is @code{en_US} for US English. | |
| 13645 | |
| 13646 As with GNU Gettext (@pxref{Top,,,gettext, Gettext}), if the country | |
| 13647 code is omitted, the main dialect is assumed where possible. For | |
| 13648 example, @code{de} is equivalent to @code{de_DE} (German as spoken in | |
| 13649 Germany). | |
| 13650 | |
| 13651 @cindex Document strings, translation of | |
| 13652 For Info and other online output, this command changes the translation | |
| 13653 of various @dfn{document strings} such as ``see'' in cross-references | |
| 13654 (@pxref{Cross References}), ``Function' in defuns (@pxref{Definition | |
| 13655 Commands}), and so on. Some strings, such as ``Node:'', ``Next:'', | |
| 13656 ``Menu:'', etc., are keywords in Info output, so are not translated | |
| 13657 there; they are translated in other output formats. | |
| 13658 | |
| 13659 @cindex @file{txi-@var{cc}.tex} | |
| 13660 For @TeX{}, this command causes a file @file{txi-@var{locale}.tex} to | |
| 13661 be read (if it exists). If @code{@@setdocumentlanguage} argument | |
| 13662 contains the optional @samp{_@var{cc}} suffix, this is tried first. | |
| 13663 For example, with @code{@@setdocumentlanguage de_DE}, @TeX{} first | |
| 13664 looks for @file{txi-de_DE.tex}, then @file{txi-de.tex}. | |
| 13665 | |
| 13666 Such a @file{txi-*} file is intended to redefine the various English | |
| 13667 words used in @TeX{} output, such as `Chapter', `See', and so on. We | |
| 13668 are aware that individual words like these cannot always be translated | |
| 13669 in isolation, and that a very different strategy would be required for | |
| 13670 ideographic (among other) scripts. Help in improving Texinfo's | |
| 13671 language support is welcome. | |
| 13672 | |
| 13673 @cindex Hyphenation patterns, language-dependent | |
| 13674 It would also be desirable for this command to also change @TeX{}'s | |
| 13675 ideas of the current hyphenation patterns (via the @TeX{} primitive | |
| 13676 @code{\language}), but this is unfortunately not currently | |
| 13677 implemented. | |
| 13678 | |
| 13679 In September 2006, the W3C Internationalization Activity released a | |
| 13680 new recommendation for specifying languages: | |
| 13681 @url{http://www.rfc-editor.org/rfc/bcp/bcp47.txt}. When Gettext | |
| 13682 supports this new scheme, Texinfo will too. | |
| 13683 | |
| 13684 @cindex ISO 639-2 language codes | |
| 13685 @cindex ISO 3166 country codes | |
| 13686 @cindex Language codes | |
| 13687 @cindex Country codes | |
| 13688 Since the lists of language codes and country codes are updated | |
| 13689 relatively frequently, we don't attempt to list them here. The valid | |
| 13690 language codes are on the official home page for ISO@tie{}639, | |
| 13691 @url{http://www.loc.gov/standards/iso639-2/}. The country codes and | |
| 13692 the official web site for ISO@tie{}3166 can be found via | |
| 13693 @url{http://en.wikipedia.org/wiki/ISO_3166}. | |
| 13694 | |
| 13695 | |
| 13696 @node documentencoding | |
| 13697 @section @code{@@documentencoding @var{enc}}: Set Input Encoding | |
| 13698 | |
| 13699 @findex documentencoding | |
| 13700 @cindex Encoding, declaring | |
| 13701 @cindex Input encoding, declaring | |
| 13702 @cindex Character set, declaring | |
| 13703 @cindex Document input encoding | |
| 13704 | |
| 13705 The @code{@@documentencoding} command declares the input document | |
| 13706 encoding. Write it on a line by itself, with a valid encoding | |
| 13707 specification following, near the beginning of the file but after | |
| 13708 @code{@@setfilename} (@pxref{setfilename,,@code{@@setfilename}}): | |
| 13709 | |
| 13710 @example | |
| 13711 @@documentencoding @var{enc} | |
| 13712 @end example | |
| 13713 | |
| 13714 At present, Texinfo supports only these encodings: | |
| 13715 | |
| 13716 @table @code | |
| 13717 @item US-ASCII | |
| 13718 This has no particular effect, but it's included for completeness. | |
| 13719 | |
| 13720 @item UTF-8 | |
| 13721 The vast global character encoding, expressed in 8-bit bytes. | |
| 13722 The Texinfo processors have no deep knowledge of Unicode; for the most | |
| 13723 part, they just pass along the input they are given to the output. | |
| 13724 | |
| 13725 @item ISO-8859-1 | |
| 13726 @itemx ISO-8859-15 | |
| 13727 @itemx ISO-8859-2 | |
| 13728 These specify the standard encodings for Western European (the first | |
| 13729 two) and Eastern European languages (the third), respectively. ISO | |
| 13730 8859-15 replaces some little-used characters from 8859-1 (e.g., | |
| 13731 precomposed fractions) with more commonly needed ones, such as the | |
| 13732 Euro symbol (@euro{}). | |
| 13733 | |
| 13734 A full description of the encodings is beyond our scope here; | |
| 13735 one useful reference is @uref{http://czyborra.com/charsets/iso8859.html}. | |
| 13736 | |
| 13737 @item koi8-r | |
| 13738 This is the commonly used encoding for the Russian language. | |
| 13739 | |
| 13740 @item koi8-u | |
| 13741 This is the commonly used encoding for the Ukrainian language. | |
| 13742 | |
| 13743 @end table | |
| 13744 | |
| 13745 Specifying an encoding @var{enc} has the following effects: | |
| 13746 | |
| 13747 @opindex --enable-encoding | |
| 13748 @cindex Local Variables: section, for encoding | |
| 13749 @cindex Info output, and encoding | |
| 13750 In Info output, unless the option @option{--disable-encoding} is given | |
| 13751 to @command{makeinfo}, a so-called `Local Variables' section | |
| 13752 (@pxref{File Variables,,,xemacs,XEmacs User's Manual}) is output | |
| 13753 including @var{enc}. This allows Info readers to set the encoding | |
| 13754 appropriately. | |
| 13755 | |
| 13756 @example | |
| 13757 Local Variables: | |
| 13758 coding: @var{enc} | |
| 13759 End: | |
| 13760 @end example | |
| 13761 | |
| 13762 Also, in Info and plain text output (barring | |
| 13763 @option{--disable-encoding}), accent constructs and special | |
| 13764 characters, such as @code{@@'e}, are output as the actual 8-bit | |
| 13765 character in the given encoding. | |
| 13766 | |
| 13767 @cindex HTML output, and encodings | |
| 13768 @cindex @code{http-equiv}, and charset specification | |
| 13769 @cindex @code{<meta>} HTML tag, and charset specification | |
| 13770 In HTML output, a @samp{<meta>} tag is output, in the @samp{<head>} | |
| 13771 section of the HTML, that specifies @var{enc}. Web servers and | |
| 13772 browsers cooperate to use this information so the correct encoding is | |
| 13773 used to display the page, if supported by the system. | |
| 13774 | |
| 13775 @example | |
| 13776 <meta http-equiv="Content-Type" content="text/html; | |
| 13777 charset=@var{enc}"> | |
| 13778 @end example | |
| 13779 | |
| 13780 In split HTML output, if @option{--transliterate-file-names} is | |
| 13781 given (@pxref{HTML Xref 8-bit Character Expansion}), the names of HTML | |
| 13782 files are formed by transliteration of the corresponding node names, | |
| 13783 using the specified encoding. | |
| 13784 | |
| 13785 In XML and Docbook output, the given document encoding is written in | |
| 13786 the output file as usual with those formats. | |
| 13787 | |
| 13788 In @TeX{} output, the characters which are supported in the standard | |
| 13789 Computer Modern fonts are output accordingly. (For example, this | |
| 13790 means using constructed accents rather than precomposed glyphs.) | |
| 13791 Using a missing character generates a warning message, as does | |
| 13792 specifying an unimplemented encoding. | |
| 13793 | |
| 13794 | |
| 13795 @node Defining New Texinfo Commands | 14730 @node Defining New Texinfo Commands |
| 13796 @chapter Defining New Texinfo Commands | 14731 @chapter Defining New Texinfo Commands |
| 14732 | |
| 13797 @cindex Macros | 14733 @cindex Macros |
| 13798 @cindex Defining new Texinfo commands | 14734 @cindex Defining new Texinfo commands |
| 13799 @cindex New Texinfo commands, defining | 14735 @cindex New Texinfo commands, defining |
| 13800 @cindex Texinfo commands, defining new | 14736 @cindex Texinfo commands, defining new |
| 13801 @cindex User-defined Texinfo commands | 14737 @cindex User-defined Texinfo commands |
| 13802 | 14738 |
| 13803 Texinfo provides several ways to define new commands: | 14739 Texinfo provides several ways to define new commands (in all cases, |
| 14740 it's not recommended to try redefining existing commands): | |
| 13804 | 14741 |
| 13805 @itemize @bullet | 14742 @itemize @bullet |
| 13806 @item | 14743 @item |
| 13807 A Texinfo @dfn{macro} allows you to define a new Texinfo command as any | 14744 A Texinfo @dfn{macro} allows you to define a new Texinfo command as any |
| 13808 sequence of text and/or existing commands (including other macros). The | 14745 sequence of text and/or existing commands (including other macros). The |
| 13809 macro can have any number of @dfn{parameters}---text you supply each | 14746 macro can have any number of @dfn{parameters}---text you supply each |
| 13810 time you use the macro. | 14747 time you use the macro. |
| 13811 | 14748 |
| 13812 Incidentally, these macros have nothing to do with the @code{@@defmac} | 14749 Incidentally, these macros have nothing to do with the @code{@@defmac} |
| 13813 command, which is for documenting macros in the subject of the manual | 14750 command, which is for documenting macros in the subject area of the |
| 13814 (@pxref{Def Cmd Template}). | 14751 manual (@pxref{Def Cmd Template}). |
| 13815 | 14752 |
| 13816 @item | 14753 @item |
| 13817 @samp{@@alias} is a convenient way to define a new name for an existing | 14754 @samp{@@alias} is a convenient way to define a new name for an existing |
| 13818 command. | 14755 command. |
| 13819 | 14756 |
| 13820 @item | 14757 @item |
| 13821 @samp{@@definfoenclose} allows you to define new commands with | 14758 @samp{@@definfoenclose} allows you to define new commands with |
| 13822 customized output in the Info file. | 14759 customized output for all non-@TeX{} output formats. |
| 13823 | 14760 |
| 13824 @end itemize | 14761 @end itemize |
| 14762 | |
| 14763 Most generally of all (not just for defining new commands), it is | |
| 14764 possible to invoke any external macro processor and have Texinfo | |
| 14765 recognize so-called @code{#line} directives for error reporting. | |
| 14766 | |
| 14767 If you want to do simple text substitution, @code{@@set} and | |
| 14768 @code{@@value} is the simplest approach (@pxref{@t{@@set @@clear | |
| 14769 @@value}}). | |
| 13825 | 14770 |
| 13826 @menu | 14771 @menu |
| 13827 * Defining Macros:: Defining and undefining new commands. | 14772 * Defining Macros:: Defining and undefining new commands. |
| 13828 * Invoking Macros:: Using a macro, once you've defined it. | 14773 * Invoking Macros:: Using a macro, once you've defined it. |
| 13829 * Macro Details:: Limitations of Texinfo macros. | 14774 * Macro Details:: Limitations of Texinfo macros. |
| 13830 * alias:: Command aliases. | 14775 * @t{@@alias}:: Command aliases. |
| 13831 * definfoenclose:: Customized highlighting. | 14776 * @t{@@definfoenclose}:: Customized highlighting. |
| 14777 * External Macro Processors:: @code{#line} directives. | |
| 13832 @end menu | 14778 @end menu |
| 13833 | 14779 |
| 13834 | 14780 |
| 13835 @node Defining Macros | 14781 @node Defining Macros |
| 13836 @section Defining Macros | 14782 @section Defining Macros |
| 13837 @cindex Defining macros | 14783 @cindex Defining macros |
| 13838 @cindex Macro definitions | 14784 @cindex Macro definitions, Texinfo |
| 13839 | 14785 |
| 13840 @findex macro | 14786 @findex macro |
| 13841 You use the Texinfo @code{@@macro} command to define a macro, like this: | 14787 You use the Texinfo @code{@@macro} command to define a macro, like this: |
| 13842 | 14788 |
| 13843 @example | 14789 @example |
| 13853 @cindex Macro names, valid characters in | 14799 @cindex Macro names, valid characters in |
| 13854 @cindex Names of macros, valid characters of | 14800 @cindex Names of macros, valid characters of |
| 13855 For a macro to work consistently with @TeX{}, @var{macroname} must | 14801 For a macro to work consistently with @TeX{}, @var{macroname} must |
| 13856 consist entirely of letters: no digits, hyphens, underscores, or other | 14802 consist entirely of letters: no digits, hyphens, underscores, or other |
| 13857 special characters. So, we recommend using only letters. However, | 14803 special characters. So, we recommend using only letters. However, |
| 13858 @command{makeinfo} will accept anything except @samp{@{@}_^=}; | 14804 @command{makeinfo} will accept anything consisting of alphanumerics, |
| 13859 @samp{_} and @samp{^} are excluded so that macros can be called in | 14805 and (except as the first character) @samp{-}. The @samp{_} character |
| 13860 @code{@@math} mode without a following space | 14806 is excluded so that macros can be called inside @code{@@math} without |
| 13861 (@pxref{math,,@code{@@math}}). | 14807 a following space (@pxref{Inserting Math}). |
| 13862 | 14808 |
| 13863 If a macro needs no parameters, you can define it either with an empty | 14809 If a macro needs no parameters, you can define it either with an empty |
| 13864 list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro | 14810 list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro |
| 13865 foo}). | 14811 foo}). |
| 13866 | 14812 |
| 13867 @cindex Body of a macro | 14813 @cindex Body of a macro |
| 13868 @cindex Mutually recursive macros | |
| 13869 @cindex Recursion, mutual | |
| 13870 The definition or @dfn{body} of the macro can contain most Texinfo | 14814 The definition or @dfn{body} of the macro can contain most Texinfo |
| 13871 commands, including previously-defined macros. Not-yet-defined macro | 14815 commands, including macro invocations. However, a macro definition |
| 13872 invocations are not allowed; thus, it is not possible to have mutually | 14816 that defines another macro does not work in @TeX{} due to limitations |
| 13873 recursive Texinfo macros. Also, a macro definition that defines another | 14817 in the design of @code{@@macro}. |
| 13874 macro does not work in @TeX{} due to limitations in the design of | |
| 13875 @code{@@macro}. | |
| 13876 | 14818 |
| 13877 @cindex Parameters to macros | 14819 @cindex Parameters to macros |
| 13878 In the macro body, instances of a parameter name surrounded by | 14820 In the macro body, instances of a parameter name surrounded by |
| 13879 backslashes, as in @samp{\@var{param1}\} in the example above, are | 14821 backslashes, as in @samp{\@var{param1}\} in the example above, are |
| 13880 replaced by the corresponding argument from the macro invocation. You | 14822 replaced by the corresponding argument from the macro invocation. You |
| 13884 To get a single @samp{\} in the macro expansion, use @samp{\\}. Any | 14826 To get a single @samp{\} in the macro expansion, use @samp{\\}. Any |
| 13885 other use of @samp{\} in the body yields a warning. | 14827 other use of @samp{\} in the body yields a warning. |
| 13886 | 14828 |
| 13887 @cindex Spaces in macros | 14829 @cindex Spaces in macros |
| 13888 @cindex Whitespace in macros | 14830 @cindex Whitespace in macros |
| 13889 The newlines after the @code{@@macro} line and before the @code{@@end | 14831 The newline characters after the @code{@@macro} line and before the |
| 13890 macro} line are ignored, that is, not included in the macro body. All | 14832 @code{@@end macro} line are ignored, that is, not included in the |
| 13891 other whitespace is treated according to the usual Texinfo rules. | 14833 macro body. All other whitespace is treated according to the usual |
| 14834 Texinfo rules. However, there are still undesirable and unpredictable | |
| 14835 interactions between newlines, macros, and commands which are | |
| 14836 line-delimited, as warned about below (@pxref{Macro Details}). | |
| 13892 | 14837 |
| 13893 @cindex Recursive macro invocations | 14838 @cindex Recursive macro invocations |
| 13894 @findex rmacro | 14839 @findex rmacro |
| 13895 To allow a macro to be used recursively, that is, in an argument to a | 14840 To allow a macro to be used recursively, that is, in an argument to a |
| 13896 call to itself, you must define it with @samp{@@rmacro}, like this: | 14841 call to itself, you must define it with @samp{@@rmacro}, like this: |
| 13918 @end example | 14863 @end example |
| 13919 | 14864 |
| 13920 | 14865 |
| 13921 @node Invoking Macros | 14866 @node Invoking Macros |
| 13922 @section Invoking Macros | 14867 @section Invoking Macros |
| 14868 | |
| 13923 @cindex Invoking macros | 14869 @cindex Invoking macros |
| 13924 @cindex Expanding macros | 14870 @cindex Expanding macros |
| 13925 @cindex Running macros | 14871 @cindex Running macros |
| 13926 @cindex Macro invocation | 14872 @cindex Macro invocation |
| 13927 | 14873 |
| 13928 After a macro is defined (see the previous section), you can use | 14874 After a macro is defined (see the previous section), you can |
| 13929 (@dfn{invoke}) it in your document like this: | 14875 @dfn{invoke} (use) it in your document like this: |
| 13930 | 14876 |
| 13931 @example | 14877 @example |
| 13932 @@@var{macroname} @{@var{arg1}, @var{arg2}, @dots{}@} | 14878 @@@var{macroname} @{@var{arg1}, @var{arg2}, @dots{}@} |
| 13933 @end example | 14879 @end example |
| 13934 | 14880 |
| 13935 @noindent and the result will be just as if you typed the body of | 14881 @noindent and the result will be more or less as if you typed the body of |
| 13936 @var{macroname} at that spot. For example: | 14882 @var{macroname} at that spot. For example: |
| 13937 | 14883 |
| 13938 @example | 14884 @example |
| 13939 @@macro foo @{p, q@} | 14885 @@macro foo @{p, q@} |
| 13940 Together: \p\ & \q\. | 14886 Together: \p\ & \q\. |
| 13947 @display | 14893 @display |
| 13948 Together: a & b. | 14894 Together: a & b. |
| 13949 @end display | 14895 @end display |
| 13950 | 14896 |
| 13951 @cindex Backslash, and macros | 14897 @cindex Backslash, and macros |
| 13952 Thus, the arguments and parameters are separated by commas and delimited | 14898 Thus, the arguments and parameters are separated by commas and |
| 13953 by braces; any whitespace after (but not before) a comma is ignored. | 14899 delimited by braces; any whitespace after (but not before) a comma is |
| 13954 The braces are required in the invocation (but not the definition), even | 14900 ignored. The braces are required in the invocation even when the |
| 13955 when the macro takes no arguments, consistent with all other Texinfo | 14901 macro takes no arguments, consistent with other Texinfo commands. For |
| 13956 commands. For example: | 14902 example: |
| 13957 | 14903 |
| 13958 @example | 14904 @example |
| 13959 @@macro argless @{@} | 14905 @@macro argless @{@} |
| 13960 No arguments here. | 14906 No arguments here. |
| 13961 @@end macro | 14907 @@end macro |
| 13967 @display | 14913 @display |
| 13968 No arguments here. | 14914 No arguments here. |
| 13969 @end display | 14915 @end display |
| 13970 | 14916 |
| 13971 @cindex Comma, in macro arguments | 14917 @cindex Comma, in macro arguments |
| 13972 Passing strings containing commas as macro arguments requires special | 14918 Passing macro arguments containing commas requires special care, since |
| 13973 care, since they should be properly @dfn{quoted} to prevent | 14919 commas also separate the arguments. To include a comma character in |
| 13974 @command{makeinfo} from confusing them with argument separators. To | 14920 an argument, the most reliable method is to use the @code{@@comma@{@}} |
| 13975 manually quote a comma, prepend it with a backslash character, like | 14921 command. For @code{makeinfo}, you can also prepend a backslash |
| 13976 this: @code{\,}. Alternatively, use the @code{@@comma} command | 14922 character, as in @samp{\,}, but this does not work with @TeX{}. |
| 13977 (@pxref{Inserting a Comma}). However, to facilitate use of macros, | 14923 |
| 13978 @command{makeinfo} implements a set of rules called @dfn{automatic | 14924 @cindex Automatic quoting of commas for some macros |
| 13979 quoting}: | 14925 @cindex Quoting, automatic for some macros |
| 14926 It's not always necessary to worry about commas. To facilitate use of | |
| 14927 macros, @command{makeinfo} implements two rules for @dfn{automatic | |
| 14928 quoting} in some circumstances: | |
| 13980 | 14929 |
| 13981 @enumerate 1 | 14930 @enumerate 1 |
| 13982 @item If a macro takes only one argument, all commas in its invocation | 14931 @item If a macro takes only one argument, all commas in its invocation |
| 13983 are quoted by default. For example: | 14932 are quoted by default. For example: |
| 13984 | 14933 |
| 13985 @example | 14934 @example |
| 13986 @group | 14935 @group |
| 13987 @@macro FIXME@{text@} | 14936 @@macro TRYME@{text@} |
| 13988 @@strong@{FIXME: \text\@} | 14937 @@strong@{TRYME: \text\@} |
| 13989 @@end macro | 14938 @@end macro |
| 13990 | 14939 |
| 13991 @@FIXME@{A nice feature, though it can be dangerous.@} | 14940 @@TRYME@{A nice feature, though it can be dangerous.@} |
| 13992 @end group | 14941 @end group |
| 13993 @end example | 14942 @end example |
| 13994 | 14943 |
| 13995 @noindent | 14944 @noindent |
| 13996 will produce the following output | 14945 will produce the following output |
| 13997 | 14946 |
| 13998 @example | 14947 @example |
| 13999 @strong{FIXME: A nice feature, though it can be dangerous.} | 14948 @strong{TRYME: A nice feature, though it can be dangerous.} |
| 14000 @end example | 14949 @end example |
| 14001 | 14950 |
| 14002 And indeed, it can. Namely, @command{makeinfo} | 14951 And indeed, it can. Namely, @command{makeinfo} does not control the |
| 14003 does not control number of arguments passed to one-argument | 14952 number of arguments passed to one-argument macros, so be careful when |
| 14004 macros, so be careful when you invoke them. | 14953 you invoke them. |
| 14005 | 14954 |
| 14006 @item If a macro invocation includes another command (including a | 14955 @item If a macro invocation includes another command (including a |
| 14007 recursive invocation of itself), any commas in the nested command | 14956 recursive invocation of itself), any commas in the nested command |
| 14008 invocation(s) are quoted by default. For example, in | 14957 invocation(s) are quoted by default. For example, in |
| 14009 | 14958 |
| 14025 @end example | 14974 @end example |
| 14026 | 14975 |
| 14027 @noindent | 14976 @noindent |
| 14028 will produce the string @samp{foobarbaz}. | 14977 will produce the string @samp{foobarbaz}. |
| 14029 | 14978 |
| 14030 @item Otherwise, a comma should be explicitly quoted, as above, to be | 14979 @item Otherwise, a comma should be explicitly quoted, as above, for it |
| 14031 treated as a part of an argument. | 14980 to be treated as a part of an argument. |
| 14032 @end enumerate | 14981 @end enumerate |
| 14033 | 14982 |
| 14034 @cindex Braces, in macro arguments | 14983 @cindex Braces, in macro arguments |
| 14035 Other characters that need to be quoted in macro arguments are | 14984 @cindex Backslash, in macro arguments |
| 14036 curly braces and backslash. For example | 14985 In addition to the comma, characters that need to be quoted in macro |
| 14986 arguments are curly braces and backslash. For example: | |
| 14037 | 14987 |
| 14038 @example | 14988 @example |
| 14039 @@@var{macname} @{\\\@{\@}\,@} | 14989 @@@var{macname} @{\\\@{\@}\,@} |
| 14040 @end example | 14990 @end example |
| 14041 | 14991 |
| 14042 @noindent | 14992 @noindent |
| 14043 will pass the (almost certainly error-producing) argument | 14993 will pass the (almost certainly error-producing) argument |
| 14044 @samp{\@{@},} to @var{macname}. However, commas in parameters, even | 14994 @samp{\@{@},} to @var{macname}. |
| 14045 if escaped by a backslash, might cause trouble in @TeX{}. | 14995 |
| 14046 | 14996 Unfortunately, this has not been reliably implemented in @TeX{}. When |
| 14047 If the macro is defined to take a single argument, and is invoked | 14997 macros are used in the argument to other commands, for example, errors |
| 14048 without any braces, the entire rest of the line after the macro name is | 14998 or incorrect output (the @samp{\} ``escape'' being included literally) |
| 14049 supplied as the argument. For example: | 14999 are likely to result. |
| 15000 | |
| 15001 If a macro is defined to take exactly one argument, it can (but need | |
| 15002 not) be invoked without any braces; then the entire rest of the line | |
| 15003 after the macro name is used as the argument. (Braces around the | |
| 15004 argument(s) are required in all other cases, i.e., if the macro takes | |
| 15005 either zero or more than one argument.) For example: | |
| 14050 | 15006 |
| 14051 @example | 15007 @example |
| 14052 @@macro bar @{p@} | 15008 @@macro bar @{p@} |
| 14053 Twice: \p\ & \p\. | 15009 Twice: \p\ & \p\. |
| 14054 @@end macro | 15010 @@end macro |
| 14055 @@bar aah | 15011 @@bar aah |
| 14056 @end example | 15012 @end example |
| 14057 | 15013 |
| 14058 @noindent produces: | 15014 @noindent produces: |
| 14059 | 15015 |
| 14060 @c Sorry for cheating, but let's not require macros to process the manual. | |
| 14061 @display | 15016 @display |
| 14062 Twice: aah & aah. | 15017 Twice: aah & aah. |
| 14063 @end display | 15018 @end display |
| 14064 | 15019 |
| 14065 If the macro is defined to take a single argument, and is invoked with | 15020 Likewise, if a macro is defined to take exactly one argument, and is |
| 14066 braces, the braced text is passed as the argument, regardless of | 15021 invoked with braces, the braced text is passed as the argument, also |
| 14067 commas. For example: | 15022 regardless of commas. For example: |
| 14068 | 15023 |
| 14069 @example | 15024 @example |
| 14070 @@macro bar @{p@} | 15025 @@macro bar @{p@} |
| 14071 Twice: \p\ & \p\. | 15026 Twice: \p\ & \p\. |
| 14072 @@end macro | 15027 @@end macro |
| 14075 | 15030 |
| 14076 @noindent produces: | 15031 @noindent produces: |
| 14077 | 15032 |
| 14078 @display | 15033 @display |
| 14079 Twice: a,b & a,b. | 15034 Twice: a,b & a,b. |
| 15035 @end display | |
| 15036 | |
| 15037 If a macro is defined to take more than one argument, but is called | |
| 15038 with only one (in braces), the remaining arguments are set to the | |
| 15039 empty string, and no error is given. For example: | |
| 15040 | |
| 15041 @example | |
| 15042 @@macro addtwo @{p, q@} | |
| 15043 Both: \p\\q\. | |
| 15044 @@end macro | |
| 15045 @@addtwo@{a@} | |
| 15046 @end example | |
| 15047 | |
| 15048 @noindent produces simply: | |
| 15049 | |
| 15050 @display | |
| 15051 Both: a. | |
| 14080 @end display | 15052 @end display |
| 14081 | 15053 |
| 14082 | 15054 |
| 14083 @node Macro Details | 15055 @node Macro Details |
| 14084 @section Macro Details and Caveats | 15056 @section Macro Details and Caveats |
| 14085 @cindex Macro details | 15057 @cindex Macro details |
| 14086 @cindex Details of macro usage | 15058 @cindex Details of macro usage |
| 14087 @cindex Caveats for macro usage | 15059 @cindex Caveats for macro usage |
| 14088 | 15060 |
| 14089 Due to unavoidable limitations, certain macro-related constructs cause | 15061 @cindex Macro expansion, contexts for |
| 14090 problems with @TeX{}. If you get macro-related errors when producing | 15062 @cindex Expansion of macros, contexts for |
| 14091 the printed version of a manual, try expanding the macros with | 15063 By design, macro expansion does not happen in the following contexts |
| 14092 @command{makeinfo} by invoking @command{texi2dvi} with the @samp{-E} | 15064 in @command{makeinfo}: |
| 14093 option (@pxref{Format with texi2dvi}). | 15065 |
| 15066 @itemize @bullet | |
| 15067 @item @code{@@macro} and @code{@@unmacro} lines; | |
| 15068 | |
| 15069 @item @code{@@if...} lines, including @code{@@ifset} and similar; | |
| 15070 | |
| 15071 @item @code{@@set}, @code{@@clear}, @code{@@value}; | |
| 15072 | |
| 15073 @item @code{@@clickstyle} lines; | |
| 15074 | |
| 15075 @item @code{@@end} lines. | |
| 15076 @end itemize | |
| 15077 | |
| 15078 @noindent Unfortunately, @TeX{} may do some expansion in these situations, | |
| 15079 possibly yielding errors. | |
| 15080 | |
| 15081 Also, quite a few macro-related constructs cause problems with @TeX{}; | |
| 15082 some of the caveats are listed below. Thus, if you get macro-related | |
| 15083 errors when producing the printed version of a manual, you might try | |
| 15084 expanding the macros with @command{makeinfo} by invoking | |
| 15085 @command{texi2dvi} with the @samp{-E} option (@pxref{Format with | |
| 15086 @t{texi2dvi}}). Or, more reliably, eschew Texinfo macros altogether | |
| 15087 and use a language designed for macro processing, such as M4 | |
| 15088 (@pxref{External Macro Processors}). | |
| 14094 | 15089 |
| 14095 @itemize @bullet | 15090 @itemize @bullet |
| 14096 @item | 15091 @item |
| 14097 As mentioned earlier, macro names must consist entirely of letters. | 15092 As mentioned earlier, macro names must consist entirely of letters. |
| 14098 | 15093 |
| 14099 @item | 15094 @item |
| 14100 It is not advisable to redefine any @TeX{} primitive, plain, or | 15095 It is not advisable to redefine any @TeX{} primitive, plain, or |
| 14101 Texinfo command name as a macro. Unfortunately this is a very large | 15096 Texinfo command name as a macro. Unfortunately this is a large and |
| 14102 set of names, and the possible resulting errors are unpredictable. | 15097 open-ended set of names, and the possible resulting errors are |
| 15098 unpredictable. | |
| 14103 | 15099 |
| 14104 @item | 15100 @item |
| 14105 All macros are expanded inside at least one @TeX{} group. This means | 15101 All macros are expanded inside at least one @TeX{} group. |
| 14106 that @code{@@set} and other such commands have no effect inside a | |
| 14107 macro. | |
| 14108 | |
| 14109 @item | |
| 14110 Commas in macro arguments, even if escaped by a backslash, don't | |
| 14111 always work. | |
| 14112 | 15102 |
| 14113 @item | 15103 @item |
| 14114 Macro arguments cannot cross lines. | 15104 Macro arguments cannot cross lines. |
| 14115 | 15105 |
| 14116 @item | 15106 @item |
| 14117 It is (usually) best to avoid comments inside macro definitions, but | 15107 Macros containing a command which must be on a line by itself, such as |
| 15108 a conditional, cannot be invoked in the middle of a line. Similarly, | |
| 15109 macros containing line-oriented commands or text, such as | |
| 15110 @code{@@example} environments, may behave unpredictably in @TeX{}. | |
| 15111 | |
| 15112 @item | |
| 15113 White space is ignored at the beginnings of lines. | |
| 15114 | |
| 15115 @item | |
| 15116 Macros can't be reliably used in the argument to accent commands | |
| 15117 (@pxref{Inserting Accents}). | |
| 15118 | |
| 15119 @item | |
| 15120 The backslash escape for commas in macro arguments does not work; | |
| 15121 @code{@@comma@{@}} must be used. | |
| 15122 | |
| 15123 @item | |
| 15124 As a consequence, if a macro takes two or more arguments, and you want | |
| 15125 to pass an argument with the Texinfo command @code{@@,} (to produce a | |
| 15126 cedilla, @pxref{Inserting Accents}), you have to use @code{@@value} or | |
| 15127 another work-around. Otherwise, @TeX{} takes the comma as separating | |
| 15128 the arguments. Example: | |
| 15129 | |
| 15130 @example | |
| 15131 @@macro mactwo@{argfirst, argsecond@} | |
| 15132 \argfirst\+\argsecond\. | |
| 15133 @@end macro | |
| 15134 @@set fc Fran@@,cois | |
| 15135 @@mactwo@{@@value@{fc@}@} | |
| 15136 @end example | |
| 15137 | |
| 15138 @noindent produces: | |
| 15139 | |
| 15140 @display | |
| 15141 Fran@,cois+. | |
| 15142 @end display | |
| 15143 | |
| 15144 The natural-seeming @code{@@mactwo@{Fran@@,cois@}} passes the two | |
| 15145 arguments @samp{Fran@@} and @samp{cois} to the macro, and nothing good | |
| 15146 results. And, as just mentioned, although the comma can be escaped | |
| 15147 with a backslash for @code{makeinfo} (@samp{@@\,}), that doesn't work | |
| 15148 in @TeX{}, so there is no other solution. | |
| 15149 | |
| 15150 @item | |
| 15151 It is usually best to avoid comments inside macro definitions, but | |
| 14118 see the next item. | 15152 see the next item. |
| 14119 | 15153 |
| 14120 @item | 15154 @item |
| 14121 Macros containing a command which must be on a line by itself, such as | 15155 In general, the interaction of newlines in the macro definitions and |
| 14122 a conditional, cannot be invoked in the middle of a line. In general, | 15156 invocations depends on the precise commands and context, |
| 14123 the interaction of newlines in the macro definitions and invocations | 15157 notwithstanding the previous statements. You may be able to work |
| 14124 depends on the precise commands and context. You may be able to work | |
| 14125 around some problems with judicious use of @code{@@c}. Suppose you | 15158 around some problems with judicious use of @code{@@c}. Suppose you |
| 14126 define a macro that is always intended to be used on a line by itself: | 15159 define a macro that is always used on a line by itself: |
| 14127 | 15160 |
| 14128 @example | 15161 @example |
| 14129 @@macro linemac | 15162 @@macro linemac |
| 14130 @@cindex whatever | 15163 @@cindex whatever @@c |
| 14131 @@c | |
| 14132 @@end macro | 15164 @@end macro |
| 14133 ... | 15165 ... |
| 14134 foo | 15166 foo |
| 14135 @@linemac | 15167 @@linemac |
| 14136 bar | 15168 bar |
| 14137 @end example | 15169 @end example |
| 14138 | 15170 |
| 14139 Without the @code{@@c}, there will be an unwanted blank line between | 15171 Without the @code{@@c}, there will be a unwanted blank line between |
| 14140 the @samp{@@cindex whatever} and the @samp{bar} (one newline comes | 15172 the @samp{@@cindex whatever} and the @samp{bar} (one newline comes |
| 14141 from the macro definition, one from after the invocation), causing a | 15173 from the macro definition, one from after the invocation), causing an |
| 14142 paragraph break. | 15174 unwanted paragraph break. |
| 14143 | 15175 |
| 14144 On the other hand, you wouldn't want the @code{@@c} if the macro was | 15176 On the other hand, you wouldn't want the @code{@@c} if the macro was |
| 14145 sometimes invoked in the middle of a line (the text after the | 15177 sometimes invoked in the middle of a line (the text after the |
| 14146 invocation would be treated as a comment). | 15178 invocation would be treated as a comment). |
| 14147 | 15179 |
| 14148 @item | 15180 @item |
| 14149 In general, you can't arbitrarily substitute a macro call for Texinfo | 15181 In general, you can't arbitrarily substitute a macro (or |
| 14150 command arguments, even when the text is the same. It might work with | 15182 @code{@@value}) call for Texinfo command arguments, even when the text |
| 14151 some commands, it fails with others. Best not to do it at all. For | 15183 is the same. Texinfo is not M4 (or even plain @TeX{}). It might work |
| 14152 instance, this fails: | 15184 with some commands, it fails with others. Best not to do it at all. |
| 15185 For instance, this fails: | |
| 14153 | 15186 |
| 14154 @example | 15187 @example |
| 14155 @@macro offmacro | 15188 @@macro offmacro |
| 14156 off | 15189 off |
| 14157 @@end macro | 15190 @@end macro |
| 14158 @@headings @@offmacro | 15191 @@headings @@offmacro |
| 14159 @end example | 15192 @end example |
| 14160 | 15193 |
| 14161 @noindent | 15194 @noindent |
| 14162 You would expect this to be equivalent to @code{@@headings off}, but | 15195 This looks equivalent to @code{@@headings off}, but for @TeX{}nical |
| 14163 for @TeX{}nical reasons, it fails with a mysterious error message | 15196 reasons, it fails with a mysterious error message (namely, |
| 14164 (@code{Paragraph ended before @@headings was complete}). | 15197 @samp{Paragraph ended before @@headings was complete}). |
| 14165 | 15198 |
| 14166 @item | 15199 @item |
| 14167 Macros cannot define macros in the natural way. To do this, you must | 15200 Macros cannot define macros in the natural way. To do this, you must |
| 14168 use conditionals and raw @TeX{}. For example: | 15201 use conditionals and raw @TeX{}. For example: |
| 14169 | 15202 |
| 14178 @@tex | 15211 @@tex |
| 14179 \gdef\ctor#1@{\ctorx#1,@} | 15212 \gdef\ctor#1@{\ctorx#1,@} |
| 14180 \gdef\ctorx#1,#2,@{\def#1@{something involving #2 somehow@}@} | 15213 \gdef\ctorx#1,#2,@{\def#1@{something involving #2 somehow@}@} |
| 14181 @@end tex | 15214 @@end tex |
| 14182 @end example | 15215 @end example |
| 14183 | |
| 14184 @end itemize | 15216 @end itemize |
| 14185 | 15217 |
| 14186 The @command{makeinfo} implementation also has limitations: | 15218 The @command{makeinfo} implementation also has the following |
| 15219 limitations (by design): | |
| 14187 | 15220 |
| 14188 @itemize | 15221 @itemize |
| 14189 @item | 15222 @item |
| 14190 @code{@@verbatim} and macros do not mix; for instance, you can't start | 15223 @code{@@verbatim} and macros do not mix; for instance, you can't start |
| 14191 a verbatim block inside a macro and end it outside. | 15224 a verbatim block inside a macro and end it outside |
| 14192 (@xref{verbatim}.) Starting any environment inside a macro and ending | 15225 (@pxref{@t{@@verbatim}}). Starting any environment inside a macro |
| 14193 it outside may or may not work, for that matter. | 15226 and ending it outside may or may not work, for that matter. |
| 14194 | 15227 |
| 14195 @item | 15228 @item |
| 14196 Macros that completely define macros are ok, but it's not possible to | 15229 Macros that completely define macros are ok, but it's not possible to |
| 14197 have incorrectly nested macro definitions. That is, @code{@@macro} | 15230 have incompletely nested macro definitions. That is, @code{@@macro} |
| 14198 and @code{@@end macro} (likewise for @code{@@rmacro}) must be | 15231 and @code{@@end macro} (likewise for @code{@@rmacro}) must be |
| 14199 correctly paired. For example, you cannot start a macro definition | 15232 correctly paired. For example, you cannot start a macro definition |
| 14200 within a macro, and then end the nested definition outside the macro. | 15233 within a macro, and then end that nested definition outside the macro. |
| 14201 | |
| 14202 @item | |
| 14203 @code{@@rmacro} is a kludge. | |
| 14204 | |
| 14205 @end itemize | 15234 @end itemize |
| 14206 | 15235 |
| 14207 One more limitation is common to both implementations: white space is | 15236 In the @code{makeinfo} implementation before Texinfo 5.0, ends of |
| 14208 ignored at the beginnings of lines. | 15237 lines from expansion of an @code{@@macro} definition did not end an |
| 14209 | 15238 @@-command line-delimited argument (@code{@@chapter}, @code{@@center}, |
| 14210 Future major revisions of Texinfo may ease some of these limitations | 15239 etc.). This is no longer the case. For example: |
| 14211 (by introducing a new macro syntax). | 15240 |
| 14212 | 15241 @example |
| 14213 | 15242 @@macro twolines@{@} |
| 14214 @node alias | 15243 aaa |
| 15244 bbb | |
| 15245 @@end macro | |
| 15246 @@center @@twolines@{@} | |
| 15247 @end example | |
| 15248 | |
| 15249 In the current @code{makeinfo}, this is equivalent to: | |
| 15250 | |
| 15251 @example | |
| 15252 @@center aaa | |
| 15253 bbb | |
| 15254 @end example | |
| 15255 | |
| 15256 @noindent with just @samp{aaa} as the argument to @code{@@center}. In | |
| 15257 the earlier implementation, it would have been parsed as this: | |
| 15258 | |
| 15259 @example | |
| 15260 @@center aaa bbb | |
| 15261 @end example | |
| 15262 | |
| 15263 | |
| 15264 @node @t{@@alias} | |
| 14215 @section @samp{@@alias @var{new}=@var{existing}} | 15265 @section @samp{@@alias @var{new}=@var{existing}} |
| 15266 | |
| 15267 @anchor{alias}@c old name | |
| 14216 @cindex Aliases, command | 15268 @cindex Aliases, command |
| 14217 @cindex Command aliases | 15269 @cindex Command aliases |
| 14218 @findex alias | 15270 @findex alias |
| 14219 | 15271 |
| 14220 The @samp{@@alias} command defines a new command to be just like an | 15272 The @samp{@@alias} command defines a new command to be just like an |
| 14221 existing one. This is useful for defining additional markup names, thus | 15273 existing one. This is useful for defining additional markup names, |
| 14222 preserving semantic information in the input even though the output | 15274 thus preserving additional semantic information in the input even |
| 14223 result may be the same. | 15275 though the output result may be the same. |
| 14224 | 15276 |
| 14225 Write the @samp{@@alias} command on a line by itself, followed by the | 15277 Write the @samp{@@alias} command on a line by itself, followed by the |
| 14226 new command name, an equals sign, and the existing command name. | 15278 new command name, an equals sign, and the existing command name. |
| 14227 Whitespace around the equals sign is ignored. Thus: | 15279 Whitespace around the equals sign is optional and ignored if present. |
| 15280 Thus: | |
| 15281 | |
| 14228 @example | 15282 @example |
| 14229 @@alias @var{new} = @var{existing} | 15283 @@alias @var{new} = @var{existing} |
| 14230 @end example | 15284 @end example |
| 14231 | 15285 |
| 14232 For example, if your document contains citations for both books and | 15286 For example, if your document contains citations for both books and |
| 14239 @@alias moviecite = cite | 15293 @@alias moviecite = cite |
| 14240 @end example | 15294 @end example |
| 14241 | 15295 |
| 14242 Macros do not always have the same effect as aliases, due to vagaries | 15296 Macros do not always have the same effect as aliases, due to vagaries |
| 14243 of argument parsing. Also, aliases are much simpler to define than | 15297 of argument parsing. Also, aliases are much simpler to define than |
| 14244 macros. So the command is not redundant. (It was also heavily used | 15298 macros. So the command is not redundant. |
| 14245 in the Jargon File!) | 15299 |
| 15300 Unfortunately, it's not possible to alias Texinfo environments; for | |
| 15301 example, @code{@@alias lang=example} is an error. | |
| 14246 | 15302 |
| 14247 Aliases must not be recursive, directly or indirectly. | 15303 Aliases must not be recursive, directly or indirectly. |
| 14248 | 15304 |
| 14249 It is not advisable to redefine any @TeX{} primitive, plain, or | 15305 It is not advisable to redefine any @TeX{} primitive, plain @TeX{}, or |
| 14250 Texinfo command name as an alias. Unfortunately this is a very large | 15306 Texinfo command name as an alias. Unfortunately this is a very large |
| 14251 set of names, and the possible resulting errors are completely random. | 15307 set of names, and the possible resulting errors from @TeX{} are |
| 14252 | 15308 unpredictable. |
| 14253 | 15309 |
| 14254 @node definfoenclose | 15310 @command{makeinfo} will accept the same identifiers for aliases as it |
| 14255 @section @samp{definfoenclose}: Customized Highlighting | 15311 does for macro names, that is, alphanumerics and (except as the first |
| 15312 character) @samp{-}. | |
| 15313 | |
| 15314 | |
| 15315 @node @t{@@definfoenclose} | |
| 15316 @section @code{@@definfoenclose}: Customized Highlighting | |
| 15317 | |
| 15318 @anchor{definfoenclose}@c old name | |
| 14256 @cindex Highlighting, customized | 15319 @cindex Highlighting, customized |
| 14257 @cindex Customized highlighting | 15320 @cindex Customized highlighting |
| 14258 @findex definfoenclose | 15321 @findex definfoenclose |
| 14259 | 15322 |
| 14260 A @code{@@definfoenclose} command may be used to define a highlighting | 15323 An @code{@@definfoenclose} command may be used to define a |
| 14261 command for Info, but not for @TeX{}. A command defined using | 15324 highlighting command for all the non-@TeX{} output formats. A command |
| 14262 @code{@@definfoenclose} marks text by enclosing it in strings that | 15325 defined using @code{@@definfoenclose} marks text by enclosing it in |
| 14263 precede and follow the text. You can use this to get closer control of | 15326 strings that precede and follow the text. You can use this to get |
| 14264 your Info output. | 15327 closer control of your output. |
| 14265 | 15328 |
| 14266 Presumably, if you define a command with @code{@@definfoenclose} for Info, | 15329 Presumably, if you define a command with @code{@@definfoenclose}, you |
| 14267 you will create a corresponding command for @TeX{}, either in | 15330 will create a corresponding command for @TeX{}, either in |
| 14268 @file{texinfo.tex}, @file{texinfo.cnf}, or within an @samp{@@iftex} in | 15331 @file{texinfo.tex}, @file{texinfo.cnf}, or within an @samp{@@iftex} of |
| 14269 your document. | 15332 @samp{@@tex} in your document. |
| 14270 | 15333 |
| 14271 Write a @code{@@definfoenclose} command on a line and follow it with | 15334 Write an @code{@@definfoenclose} command at the beginning of a line |
| 14272 three arguments separated by commas. The first argument to | 15335 followed by three comma-separated arguments. The first argument to |
| 14273 @code{@@definfoenclose} is the @@-command name (without the @code{@@}); | 15336 @code{@@definfoenclose} is the @@-command name (without the |
| 14274 the second argument is the Info start delimiter string; and the third | 15337 @code{@@}); the second argument is the start delimiter string; and the |
| 14275 argument is the Info end delimiter string. The latter two arguments | 15338 third argument is the end delimiter string. The latter two arguments |
| 14276 enclose the highlighted text in the Info file. A delimiter string may | 15339 enclose the highlighted text in the output. |
| 14277 contain spaces. Neither the start nor end delimiter is required. If | 15340 |
| 14278 you do not want a start delimiter but do want an end delimiter, you must | 15341 A delimiter string may contain spaces. Neither the start nor end |
| 14279 follow the command name with two commas in a row; otherwise, the Info | 15342 delimiter is required. If you do not want a start delimiter but do |
| 14280 formatting commands will naturally misinterpret the end delimiter string | 15343 want an end delimiter, you must follow the command name with two |
| 14281 you intended as the start delimiter string. | 15344 commas in a row; otherwise, the end delimiter string you intended will |
| 14282 | 15345 naturally be (mis)interpreted as the start delimiter string. |
| 14283 If you do a @code{@@definfoenclose} on the name of a predefined macro | 15346 |
| 14284 (such as @code{@@emph}, @code{@@strong}, @code{@@t}, or @code{@@i}), the | 15347 If you do an @code{@@definfoenclose} on the name of a predefined |
| 14285 enclosure definition will override the built-in definition. | 15348 command (such as @code{@@emph}, @code{@@strong}, @code{@@t}, or |
| 14286 | 15349 @code{@@i}), the enclosure definition will override the built-in |
| 14287 An enclosure command defined this way takes one argument in braces; this | 15350 definition. We don't recommend this. |
| 14288 is intended for new markup commands (@pxref{Marking Text}). | 15351 |
| 15352 An enclosure command defined this way takes one argument in braces, | |
| 15353 since it is intended for new markup commands (@pxref{Marking Text}). | |
| 14289 | 15354 |
| 14290 @findex phoo | 15355 @findex phoo |
| 14291 For example, you can write: | 15356 For example, you can write: |
| 14292 | 15357 |
| 14293 @example | 15358 @example |
| 14298 near the beginning of a Texinfo file to define @code{@@phoo} as an Info | 15363 near the beginning of a Texinfo file to define @code{@@phoo} as an Info |
| 14299 formatting command that inserts `//' before and `\\' after the argument | 15364 formatting command that inserts `//' before and `\\' after the argument |
| 14300 to @code{@@phoo}. You can then write @code{@@phoo@{bar@}} wherever you | 15365 to @code{@@phoo}. You can then write @code{@@phoo@{bar@}} wherever you |
| 14301 want `//bar\\' highlighted in Info. | 15366 want `//bar\\' highlighted in Info. |
| 14302 | 15367 |
| 14303 Also, for @TeX{} formatting, you could write | 15368 For @TeX{} formatting, you could write |
| 14304 | 15369 |
| 14305 @example | 15370 @example |
| 14306 @@iftex | 15371 @@iftex |
| 14307 @@global@@let@@phoo=@@i | 15372 @@global@@let@@phoo=@@i |
| 14308 @@end iftex | 15373 @@end iftex |
| 14310 | 15375 |
| 14311 @noindent | 15376 @noindent |
| 14312 to define @code{@@phoo} as a command that causes @TeX{} to typeset the | 15377 to define @code{@@phoo} as a command that causes @TeX{} to typeset the |
| 14313 argument to @code{@@phoo} in italics. | 15378 argument to @code{@@phoo} in italics. |
| 14314 | 15379 |
| 14315 Each definition applies to its own formatter: one for @TeX{}, the other | 15380 Each definition applies to its own formatter: one for @TeX{}, the |
| 14316 for @code{texinfo-format-buffer} or @code{texinfo-format-region}. The | 15381 other for everything else. The raw @TeX{} commands need to be in |
| 14317 @code{@@definfoenclose} command need not be within @samp{@@ifinfo}, but | 15382 @samp{@@iftex}. @code{@@definfoenclose} command need not be within |
| 14318 the raw @TeX{} commands do need to be in @samp{@@iftex}. | 15383 @samp{@@ifinfo}, unless you want to use different definitions for |
| 15384 different output formats. | |
| 14319 | 15385 |
| 14320 @findex headword | 15386 @findex headword |
| 14321 Here is another example: write | 15387 Here is another example: write |
| 14322 | 15388 |
| 14323 @example | 15389 @example |
| 14329 formatting command that inserts nothing before and a colon after the | 15395 formatting command that inserts nothing before and a colon after the |
| 14330 argument to @code{@@headword}. | 15396 argument to @code{@@headword}. |
| 14331 | 15397 |
| 14332 @samp{@@definfoenclose} definitions must not be recursive, directly or | 15398 @samp{@@definfoenclose} definitions must not be recursive, directly or |
| 14333 indirectly. | 15399 indirectly. |
| 15400 | |
| 15401 | |
| 15402 @node External Macro Processors | |
| 15403 @section External Macro Processors: Line Directives | |
| 15404 @cindex External macro processors | |
| 15405 @cindex Macro processors, external | |
| 15406 | |
| 15407 Texinfo macros (and its other text substitution facilities) work fine | |
| 15408 in straightforward cases. If your document needs unusually complex | |
| 15409 processing, however, their fragility and limitations can be a problem. | |
| 15410 In this case, you may want to use a different macro processor | |
| 15411 altogether, such as M4 (@pxref{Top,,, m4, M4}) or CPP (@pxref{Top,,, | |
| 15412 cpp, The C Preprocessor}). | |
| 15413 | |
| 15414 With one exception, Texinfo does not need to know whether its input is | |
| 15415 ``original'' source or preprocessed from some other source file. | |
| 15416 Therefore, you can arrange your build system to invoke whatever | |
| 15417 programs you like to handle macro expansion or other preprocessing | |
| 15418 needs. Texinfo does not offer built-in support for any particular | |
| 15419 preprocessor, since no one program seemed likely to suffice for the | |
| 15420 requirements of all documents. | |
| 15421 | |
| 15422 @cindex Line numbers, in error messages | |
| 15423 @cindex Error messages, line numbers in | |
| 15424 The one exception is line numbers in error messages. In that case, | |
| 15425 the line number should refer to the original source file, whatever it | |
| 15426 may be. There's a well-known mechanism for this: the so-called | |
| 15427 @samp{#line} directive. Texinfo supports this. | |
| 15428 | |
| 15429 @menu | |
| 15430 * @t{#line} Directive:: | |
| 15431 * TeX: @t{#line} and @TeX{}. | |
| 15432 * Syntax: @t{#line} Syntax Details. | |
| 15433 @end menu | |
| 15434 | |
| 15435 | |
| 15436 @node @t{#line} Directive | |
| 15437 @subsection @samp{#line} Directive | |
| 15438 | |
| 15439 @cindex @samp{#line} directive | |
| 15440 | |
| 15441 An input line such as this: | |
| 15442 | |
| 15443 @example | |
| 15444 @hashchar{}line 100 "foo.ptexi" | |
| 15445 @end example | |
| 15446 | |
| 15447 @noindent indicates that the next line was line 100 of the file | |
| 15448 @file{foo.ptexi}, and so that's what an error message should refer to. | |
| 15449 Both M4 (@pxref{Preprocessor features,,, m4, GNU M4}) and CPP | |
| 15450 (@pxref{Line Control,,, cpp, The C Preprocessor}, and | |
| 15451 @ref{Preprocessor Output,,, cpp, The C Preprocessor}) can generate | |
| 15452 such lines. | |
| 15453 | |
| 15454 @vindex CPP_LINE_DIRECTIVES | |
| 15455 The @command{makeinfo} program recognizes these lines by default, | |
| 15456 except within @code{@@verbatim} blocks (@pxref{@t{@@verbatim}}. | |
| 15457 Their recognition can be turned off completely with | |
| 15458 @code{CPP_LINE_DIRECTIVES} (@pxref{Other Customization Variables}), | |
| 15459 though there is normally no reason to do so. | |
| 15460 | |
| 15461 For those few programs (M4, CPP, Texinfo) which need to document | |
| 15462 @samp{#line} directives and therefore have examples which would | |
| 15463 otherwise match the pattern, the command @code{@@hashchar@{@}} can be | |
| 15464 used (@pxref{Inserting a Hashsign}). The example line above looks | |
| 15465 like this in the source for this manual: | |
| 15466 | |
| 15467 @example | |
| 15468 @@hashchar@{@}line 100 "foo.ptexi" | |
| 15469 @end example | |
| 15470 | |
| 15471 The @code{@@hashchar} command was added to Texinfo in 2013. If you | |
| 15472 don't want to rely on it, you can also use @code{@@set} and | |
| 15473 @code{@@value} to insert the literal @samp{#}: | |
| 15474 | |
| 15475 @example | |
| 15476 @@set hash # | |
| 15477 @@value@{hash@}line 1 "example.c" | |
| 15478 @end example | |
| 15479 | |
| 15480 Or, if suitable, an @code{@@verbatim} environment can be used instead | |
| 15481 of @code{@@example}. As mentioned above, @code{#line}-recognition is | |
| 15482 disabled inside verbatim blocks. | |
| 15483 | |
| 15484 | |
| 15485 @node @t{#line} and @TeX{} | |
| 15486 @subsection @samp{#line} and @TeX{} | |
| 15487 | |
| 15488 @cindex @TeX{} and @samp{#line} directives | |
| 15489 @cindex @samp{#line} directives, not processing with @TeX{} | |
| 15490 | |
| 15491 As mentioned, @command{makeinfo} recognizes the @samp{#line} | |
| 15492 directives described in the previous section. However, | |
| 15493 @file{texinfo.tex} does not and cannot. Therefore, such a line will | |
| 15494 be incorrectly typeset verbatim if @TeX{} sees it. The solution is to | |
| 15495 use @command{makeinfo}'s macro expansion options before running | |
| 15496 @TeX{}. There are three approaches: | |
| 15497 | |
| 15498 @itemize @bullet | |
| 15499 @item | |
| 15500 If you run @command{texi2dvi} or its variants (@pxref{Format with | |
| 15501 @t{texi2dvi}}), you can pass @option{-E} and @command{texi2dvi} | |
| 15502 will run @command{makeinfo} first to expand macros and eliminate | |
| 15503 @samp{#line}. | |
| 15504 | |
| 15505 @item | |
| 15506 If you run @command{makeinfo} or its variants (@pxref{Generic | |
| 15507 Translator @t{texi2any}}), you can specify @option{--no-ifinfo | |
| 15508 --iftex -E somefile.out}, and then give @file{somefile.out} to | |
| 15509 @code{texi2dvi} in a separate command. | |
| 15510 | |
| 15511 @item | |
| 15512 Or you can run @option{makeinfo --dvi --Xopt -E}. (Or @option{--pdf} | |
| 15513 instead of @option{--dvi}.) @command{makeinfo} will then call | |
| 15514 @command{texi2dvi -E}. | |
| 15515 @end itemize | |
| 15516 | |
| 15517 @findex errormsg@r{, and line numbers in @TeX{}} | |
| 15518 One last caveat regarding use with @TeX{}: since the @code{#line} | |
| 15519 directives are not recognized, the line numbers emitted by the | |
| 15520 @code{@@errormsg@{@}} command (@pxref{Conditional Commands}), or by | |
| 15521 @TeX{} itself, are the (incorrect) line numbers from the derived file | |
| 15522 which @TeX{} is reading, rather than the preprocessor-specified line | |
| 15523 numbers. This is another example of why we recommend running | |
| 15524 @command{makeinfo} for the best diagnostics (@pxref{@t{makeinfo} | |
| 15525 Advantages}). | |
| 15526 | |
| 15527 | |
| 15528 @node @t{#line} Syntax Details | |
| 15529 @subsection @samp{#line} Syntax Details | |
| 15530 | |
| 15531 @cindex @samp{#line} syntax details | |
| 15532 @cindex Syntax details, @samp{#line} | |
| 15533 @cindex Regular expression, for @samp{#line} | |
| 15534 | |
| 15535 Syntax details for the @samp{#line} directive: the @samp{#} character | |
| 15536 can be preceded or followed by whitespace, the word @samp{line} is | |
| 15537 optional, and the file name can be followed by a whitespace-separated | |
| 15538 list of integers (these are so-called ``flags'' output by CPP in some | |
| 15539 cases). For those who like to know the gory details, the actual | |
| 15540 (Perl) regular expression which is matched is this: | |
| 15541 | |
| 15542 @example | |
| 15543 /^\s*#\s*(line)? (\d+)(( "([^"]+)")(\s+\d+)*)?\s*$/ | |
| 15544 @end example | |
| 15545 | |
| 15546 As far as we've been able to tell, the trailing integer flags only | |
| 15547 occur in conjunction with a filename, so that is reflected in the | |
| 15548 regular expression. | |
| 15549 | |
| 15550 As an example, the following is a syntactically valid @samp{#line} | |
| 15551 directive, meaning line 1 of @file{/usr/include/stdio.h}: | |
| 15552 | |
| 15553 @example | |
| 15554 @hashchar{} 1 "/usr/include/stdio.h" 2 3 4 | |
| 15555 @end example | |
| 15556 | |
| 15557 Unfortunately, the quoted filename (@samp{"..."}) has to be optional, | |
| 15558 because M4 (especially) can often generate @samp{#line} directives | |
| 15559 within a single file. Since the @samp{line} is also optional, the | |
| 15560 result is that lines might match which you wouldn't expect, e.g., | |
| 15561 | |
| 15562 @example | |
| 15563 @hashchar{} 1 | |
| 15564 @end example | |
| 15565 | |
| 15566 The possible solutions are described above (@pxref{@t{#line} Directive}). | |
| 15567 | |
| 15568 | |
| 15569 @node Include Files | |
| 15570 @chapter Include Files | |
| 15571 | |
| 15572 @cindex Include files | |
| 15573 | |
| 15574 When a Texinfo processor sees an @code{@@include} command in a Texinfo | |
| 15575 file, it processes the contents of the file named by the | |
| 15576 @code{@@include} and incorporates them into the output files being | |
| 15577 created. Include files thus let you keep a single large document as a | |
| 15578 collection of conveniently small parts. | |
| 15579 | |
| 15580 @menu | |
| 15581 * Using Include Files:: How to use the @code{@@include} command. | |
| 15582 * @t{texinfo-multiple-files-update}:: How to create and update nodes and | |
| 15583 menus when using included files. | |
| 15584 * Include Files Requirements:: @code{texinfo-multiple-files-update} needs. | |
| 15585 * Sample Include File:: A sample outer file with included files | |
| 15586 within it; and a sample included file. | |
| 15587 * Include Files Evolution:: How use of the @code{@@include} command | |
| 15588 has changed over time. | |
| 15589 @end menu | |
| 15590 | |
| 15591 | |
| 15592 @node Using Include Files | |
| 15593 @section How to Use Include Files | |
| 15594 | |
| 15595 @findex include | |
| 15596 | |
| 15597 To include another file within a Texinfo file, write the | |
| 15598 @code{@@include} command at the beginning of a line and follow it on | |
| 15599 the same line by the name of a file to be included. For example: | |
| 15600 | |
| 15601 @example | |
| 15602 @@include buffers.texi | |
| 15603 @end example | |
| 15604 | |
| 15605 @@-commands are expanded in file names. The one most likely to be | |
| 15606 useful is @code{@@value} (@pxref{@t{@@set @@value}}), and even then | |
| 15607 only in complicated situations. | |
| 15608 | |
| 15609 An included file should simply be a segment of text that you expect to | |
| 15610 be included as is into the overall or @dfn{outer} Texinfo file; it | |
| 15611 should not contain the standard beginning and end parts of a Texinfo | |
| 15612 file. In particular, you should not start an included file with a | |
| 15613 line saying @samp{\input texinfo}; if you do, that text is inserted | |
| 15614 into the output file literally. Likewise, you should not end an | |
| 15615 included file with an @code{@@bye} command; nothing after @code{@@bye} | |
| 15616 is formatted. | |
| 15617 | |
| 15618 In the long-ago past, you were required to write an | |
| 15619 @code{@@setfilename} line at the beginning of an included file, but no | |
| 15620 longer. Now, it does not matter whether you write such a line. If an | |
| 15621 @code{@@setfilename} line exists in an included file, it is ignored. | |
| 15622 | |
| 15623 | |
| 15624 @node @t{texinfo-multiple-files-update} | |
| 15625 @section @code{texinfo-multiple-files-update} | |
| 15626 | |
| 15627 @findex texinfo-multiple-files-update | |
| 15628 | |
| 15629 XEmacs Texinfo mode provides the | |
| 15630 @code{texinfo-multiple-files-update} command. This command creates or | |
| 15631 updates `Next', `Previous', and `Up' pointers of included files as | |
| 15632 well as those in the outer or overall Texinfo file, and it creates or | |
| 15633 updates a main menu in the outer file. Depending on whether you call | |
| 15634 it with optional arguments, the command updates only the pointers in | |
| 15635 the first @code{@@node} line of the included files or all of them: | |
| 15636 | |
| 15637 @table @kbd | |
| 15638 @item M-x texinfo-multiple-files-update | |
| 15639 Called without any arguments: | |
| 15640 | |
| 15641 @itemize @minus | |
| 15642 @item | |
| 15643 Create or update the `Next', `Previous', and `Up' pointers of the | |
| 15644 first @code{@@node} line in each file included in an outer or overall | |
| 15645 Texinfo file. | |
| 15646 | |
| 15647 @item | |
| 15648 Create or update the `Top' level node pointers of the outer or | |
| 15649 overall file. | |
| 15650 | |
| 15651 @item | |
| 15652 Create or update a main menu in the outer file. | |
| 15653 @end itemize | |
| 15654 | |
| 15655 @item C-u M-x texinfo-multiple-files-update | |
| 15656 Called with @kbd{C-u} as a prefix argument: | |
| 15657 | |
| 15658 @itemize @minus{} | |
| 15659 @item | |
| 15660 Create or update pointers in the first @code{@@node} line in each | |
| 15661 included file. | |
| 15662 | |
| 15663 @item | |
| 15664 Create or update the `Top' level node pointers of the outer file. | |
| 15665 | |
| 15666 @item | |
| 15667 Create and insert a master menu in the outer file. The master menu | |
| 15668 is made from all the menus in all the included files. | |
| 15669 @end itemize | |
| 15670 | |
| 15671 @item C-u 8 M-x texinfo-multiple-files-update | |
| 15672 Called with a numeric prefix argument, such as @kbd{C-u 8}: | |
| 15673 | |
| 15674 @itemize @minus | |
| 15675 @item | |
| 15676 Create or update @strong{all} the `Next', `Previous', and `Up' pointers | |
| 15677 of all the included files. | |
| 15678 | |
| 15679 @item | |
| 15680 Create or update @strong{all} the menus of all the included | |
| 15681 files. | |
| 15682 | |
| 15683 @item | |
| 15684 Create or update the `Top' level node pointers of the outer or | |
| 15685 overall file. | |
| 15686 | |
| 15687 @item | |
| 15688 And then create a master menu in the outer file. This is similar to | |
| 15689 invoking @code{texinfo-master-menu} with an argument when you are | |
| 15690 working with just one file. | |
| 15691 @end itemize | |
| 15692 @end table | |
| 15693 | |
| 15694 Note the use of the prefix argument in interactive use: with a regular | |
| 15695 prefix argument, just @w{@kbd{C-u}}, the | |
| 15696 @code{texinfo-multiple-files-update} command inserts a master menu; | |
| 15697 with a numeric prefix argument, such as @kbd{C-u 8}, the command | |
| 15698 updates @strong{every} pointer and menu in @strong{all} the files and | |
| 15699 then inserts a master menu. | |
| 15700 | |
| 15701 | |
| 15702 @node Include Files Requirements | |
| 15703 @section Include Files Requirements | |
| 15704 @cindex Include files requirements | |
| 15705 @cindex Requirements for include files | |
| 15706 | |
| 15707 If you plan to use the @code{texinfo-multiple-files-update} command, | |
| 15708 the outer Texinfo file that lists included files within it should | |
| 15709 contain nothing but the beginning and end parts of a Texinfo file, and | |
| 15710 a number of @code{@@include} commands listing the included files. It | |
| 15711 should not even include indices, which should be listed in an included | |
| 15712 file of their own. | |
| 15713 | |
| 15714 Moreover, each of the included files must contain exactly one highest | |
| 15715 level node (conventionally, @code{@@chapter} or equivalent), | |
| 15716 and this node must be the first node in the included file. | |
| 15717 Furthermore, each of these highest level nodes in each included file | |
| 15718 must be at the same hierarchical level in the file structure. | |
| 15719 Usually, each is an @code{@@chapter}, an @code{@@appendix}, or an | |
| 15720 @code{@@unnumbered} node. Thus, normally, each included file contains | |
| 15721 one, and only one, chapter or equivalent-level node. | |
| 15722 | |
| 15723 The outer file should contain only @emph{one} node, the `Top' node. It | |
| 15724 should @emph{not} contain any nodes besides the single `Top' node. The | |
| 15725 @code{texinfo-multiple-files-update} command will not process | |
| 15726 them. | |
| 15727 | |
| 15728 | |
| 15729 @node Sample Include File | |
| 15730 @section Sample File with @code{@@include} | |
| 15731 @cindex Sample @code{@@include} file | |
| 15732 @cindex Include file sample | |
| 15733 @cindex @code{@@include} file sample | |
| 15734 | |
| 15735 Here is an example of an outer Texinfo file with @code{@@include} files | |
| 15736 within it before running @code{texinfo-multiple-files-update}, which | |
| 15737 would insert a main or master menu: | |
| 15738 | |
| 15739 @example | |
| 15740 @group | |
| 15741 \input texinfo @@c -*-texinfo-*- | |
| 15742 @c %**start of header | |
| 15743 @@setfilename include-example.info | |
| 15744 @@settitle Include Example | |
| 15745 @c %**end of header | |
| 15746 @end group | |
| 15747 | |
| 15748 ... @xref{Sample Texinfo Files}, for | |
| 15749 examples of the rest of the frontmatter ... | |
| 15750 | |
| 15751 @group | |
| 15752 @@ifnottex | |
| 15753 @@node Top | |
| 15754 @@top Include Example | |
| 15755 @@end ifnottex | |
| 15756 @end group | |
| 15757 | |
| 15758 @group | |
| 15759 @@include foo.texinfo | |
| 15760 @@include bar.texinfo | |
| 15761 @@include concept-index.texinfo | |
| 15762 @@bye | |
| 15763 @end group | |
| 15764 @end example | |
| 15765 | |
| 15766 An included file, such as @file{foo.texinfo}, might look like this: | |
| 15767 | |
| 15768 @example | |
| 15769 @group | |
| 15770 @@node First | |
| 15771 @@chapter First Chapter | |
| 15772 | |
| 15773 Contents of first chapter @dots{} | |
| 15774 @end group | |
| 15775 @end example | |
| 15776 | |
| 15777 The full contents of @file{concept-index.texinfo} might be as simple as this: | |
| 15778 | |
| 15779 @example | |
| 15780 @group | |
| 15781 @@node Concept Index | |
| 15782 @@unnumbered Concept Index | |
| 15783 | |
| 15784 @@printindex cp | |
| 15785 @end group | |
| 15786 @end example | |
| 15787 | |
| 15788 The outer Texinfo source file for @cite{The XEmacs Lisp Reference | |
| 15789 Manual} is named @file{lispref.texi}. This outer file contains a master | |
| 15790 menu with 417 entries and a list of 41 @code{@@include} | |
| 15791 files. | |
| 15792 | |
| 15793 | |
| 15794 @node Include Files Evolution | |
| 15795 @section Evolution of Include Files | |
| 15796 | |
| 15797 When Info was first created, it was customary to create many small | |
| 15798 Info files on one subject. Each Info file was formatted from its own | |
| 15799 Texinfo source file. This custom meant that XEmacs did not need to | |
| 15800 make a large buffer to hold the whole of a large Info file when | |
| 15801 someone wanted information; instead, XEmacs allocated just enough | |
| 15802 memory for the small Info file that contained the particular | |
| 15803 information sought. This way, XEmacs could avoid wasting memory. | |
| 15804 | |
| 15805 References from one file to another were made by referring to the file | |
| 15806 name as well as the node name. (@xref{Other Info Files, , Referring to | |
| 15807 Other Info Files}. Also, see @ref{Four and Five Arguments, , | |
| 15808 @code{@@xref} with Four and Five Arguments}.) | |
| 15809 | |
| 15810 Include files were designed primarily as a way to create a single, | |
| 15811 large printed manual out of several smaller Info files. In a printed | |
| 15812 manual, all the references were within the same document, so @TeX{} | |
| 15813 could automatically determine the references' page numbers. The Info | |
| 15814 formatting commands used include files only for creating joint | |
| 15815 indices; each of the individual Texinfo files had to be formatted for | |
| 15816 Info individually. (Each, therefore, required its own | |
| 15817 @code{@@setfilename} line.) | |
| 15818 | |
| 15819 However, because large Info files are now split automatically, it is | |
| 15820 no longer necessary to keep them small. | |
| 15821 | |
| 15822 Nowadays, multiple Texinfo files are used mostly for large documents, | |
| 15823 such as @cite{The XEmacs Lisp Reference Manual}, and for projects | |
| 15824 in which several different people write different sections of a | |
| 15825 document simultaneously. | |
| 15826 | |
| 15827 In addition, the Info formatting commands have been extended to work | |
| 15828 with the @code{@@include} command so as to create a single large Info | |
| 15829 file that is split into smaller files if necessary. This means that | |
| 15830 you can write menus and cross references without naming the different | |
| 15831 Texinfo files. | |
| 14334 | 15832 |
| 14335 | 15833 |
| 14336 @node Hardcopy | 15834 @node Hardcopy |
| 14337 @chapter Formatting and Printing Hardcopy | 15835 @chapter Formatting and Printing Hardcopy |
| 14338 @cindex Format and print hardcopy | 15836 @cindex Format and print hardcopy |
| 14340 @cindex Hardcopy, printing it | 15838 @cindex Hardcopy, printing it |
| 14341 @cindex Making a printed manual | 15839 @cindex Making a printed manual |
| 14342 @cindex Sorting indices | 15840 @cindex Sorting indices |
| 14343 @cindex Indices, sorting | 15841 @cindex Indices, sorting |
| 14344 @cindex @TeX{} index sorting | 15842 @cindex @TeX{} index sorting |
| 14345 @pindex texindex | 15843 |
| 14346 | 15844 Running the @command{texi2dvi} or @command{texi2pdf} command is the |
| 14347 There are three major shell commands for making a printed manual from a | 15845 simplest way to create printable output. These commands are installed |
| 14348 Texinfo file: one for converting the Texinfo file into a file that will be | 15846 as part of the Texinfo package. |
| 14349 printed, a second for sorting indices, and a third for printing the | 15847 |
| 14350 formatted document. When you use the shell commands, you can either | 15848 More specifically, three major shell commands are used to print |
| 14351 work directly in the operating system shell or work within a shell | 15849 formatted output from a Texinfo manual: one converts the Texinfo |
| 14352 inside XEmacs. | 15850 source into something printable, a second sorts indices, and a third |
| 15851 actually prints the formatted document. When you use the shell | |
| 15852 commands, you can either work directly in the operating system shell | |
| 15853 or work within a shell inside XEmacs (or some other computing | |
| 15854 environment). | |
| 14353 | 15855 |
| 14354 If you are using XEmacs, you can use commands provided by Texinfo | 15856 If you are using XEmacs, you can use commands provided by Texinfo |
| 14355 mode instead of shell commands. In addition to the three commands to | 15857 mode instead of shell commands. In addition to the three commands to |
| 14356 format a file, sort the indices, and print the result, Texinfo mode | 15858 format a file, sort the indices, and print the result, Texinfo mode |
| 14357 offers key bindings for commands to recenter the output buffer, show the | 15859 offers key bindings for commands to recenter the output buffer, show the |
| 14358 print queue, and delete a job from the print queue. | 15860 print queue, and delete a job from the print queue. |
| 14359 | 15861 |
| 15862 Details are in the following sections. | |
| 15863 | |
| 14360 @menu | 15864 @menu |
| 14361 * Use TeX:: Use @TeX{} to format for hardcopy. | 15865 * Use @TeX{}:: Use @TeX{} to format for hardcopy. |
| 14362 * Format with tex/texindex:: How to format with explicit shell commands. | 15866 * Format with @t{tex}/@t{texindex}:: How to format with explicit shell commands. |
| 14363 * Format with texi2dvi:: A simpler way to format. | 15867 * Format with @t{texi2dvi}:: A simpler way to format. |
| 14364 * Print with lpr:: How to print. | 15868 * Print with @t{lpr}:: How to print. |
| 14365 * Within XEmacs:: How to format and print from an XEmacs shell. | 15869 * Within XEmacs:: How to format and print from an XEmacs shell. |
| 14366 * Texinfo Mode Printing:: How to format and print in Texinfo mode. | 15870 * Texinfo Mode Printing:: How to format and print in Texinfo mode. |
| 14367 * Compile-Command:: How to print using XEmacs's compile command. | 15871 * Compile-Command:: How to print using XEmacs's compile command. |
| 14368 * Requirements Summary:: @TeX{} formatting requirements summary. | 15872 * Requirements Summary:: @TeX{} formatting requirements summary. |
| 14369 * Preparing for TeX:: What to do before you use @TeX{}. | 15873 * Preparing for @TeX{}:: What to do before you use @TeX{}. |
| 14370 * Overfull hboxes:: What are and what to do with overfull hboxes. | 15874 * Overfull hboxes:: What are and what to do with overfull hboxes. |
| 14371 * smallbook:: How to print small format books and manuals. | 15875 * @t{@@smallbook}:: How to print small format books and manuals. |
| 14372 * A4 Paper:: How to print on A4 or A5 paper. | 15876 * A4 Paper:: How to print on A4 or A5 paper. |
| 14373 * pagesizes:: How to print with customized page sizes. | 15877 * @t{@@pagesizes}:: How to print with customized page sizes. |
| 14374 * Cropmarks and Magnification:: How to print marks to indicate the size | 15878 * Cropmarks and Magnification:: How to print marks to indicate the size |
| 14375 of pages and how to print scaled up output. | 15879 of pages and how to print scaled up output. |
| 14376 * PDF Output:: Portable Document Format output. | 15880 * PDF Output:: Portable Document Format output. |
| 14377 * Obtaining TeX:: How to Obtain @TeX{}. | 15881 * Obtaining @TeX{}:: How to obtain @TeX{}. |
| 14378 @end menu | 15882 @end menu |
| 14379 | 15883 |
| 14380 @node Use TeX | 15884 |
| 15885 @node Use @TeX{} | |
| 14381 @section Use @TeX{} | 15886 @section Use @TeX{} |
| 14382 | 15887 |
| 14383 The typesetting program called @TeX{} is used for formatting a Texinfo | 15888 The typesetting program called @TeX{} is used for formatting a Texinfo |
| 14384 file. @TeX{} is a very powerful typesetting program and, if used correctly, | 15889 file. @TeX{} is a very powerful typesetting program and, when used |
| 14385 does an exceptionally good job. (@xref{Obtaining TeX, , How to Obtain | 15890 correctly, does an exceptionally good job. |
| 14386 @TeX{}}, for information on how to obtain @TeX{}.) | 15891 |
| 14387 | 15892 @xref{Obtaining @TeX{}}, for information on how to obtain @TeX{}. It |
| 14388 The standalone @code{makeinfo} program and XEmacs functions | 15893 is not included in the Texinfo package, being a vast suite of software |
| 14389 @code{texinfo-format-region} and @code{texinfo-format-buffer} commands | 15894 itself. |
| 14390 read the very same @@-commands in the Texinfo file as does @TeX{}, but | 15895 |
| 14391 process them differently to make an Info file (@pxref{Creating an Info | 15896 |
| 14392 File}). | 15897 @node Format with @t{tex}/@t{texindex} |
| 14393 | 15898 @section Format with @code{tex}/@code{texindex} |
| 14394 | 15899 |
| 14395 @node Format with tex/texindex | |
| 14396 @section Format with @code{tex} and @code{texindex} | |
| 14397 @cindex Shell formatting with @code{tex} and @code{texindex} | 15900 @cindex Shell formatting with @code{tex} and @code{texindex} |
| 14398 @cindex Formatting with @code{tex} and @code{texindex} | 15901 @cindex Formatting with @code{tex} and @code{texindex} |
| 14399 @cindex DVI file | 15902 @cindex DVI file |
| 14400 | 15903 |
| 14401 You can format the Texinfo file with the shell command @code{tex} | 15904 You can format the Texinfo file with the shell command @code{tex} |
| 14403 | 15906 |
| 14404 @example | 15907 @example |
| 14405 tex foo.texi | 15908 tex foo.texi |
| 14406 @end example | 15909 @end example |
| 14407 | 15910 |
| 14408 @noindent | 15911 @noindent @TeX{} will produce a @dfn{DVI file} as well as several auxiliary |
| 14409 @TeX{} will produce a @dfn{DVI file} as well as several auxiliary | |
| 14410 files containing information for indices, cross references, etc. The | 15912 files containing information for indices, cross references, etc. The |
| 14411 DVI file (for @dfn{DeVice Independent} file) can be printed on virtually | 15913 DVI file (for @dfn{DeVice Independent} file) can be printed on virtually |
| 14412 any device (see the following sections). | 15914 any device (see the following sections). |
| 14413 | 15915 |
| 14414 @pindex texindex | 15916 @pindex texindex |
| 14418 index to work from. The @command{texindex} command sorts indices. | 15920 index to work from. The @command{texindex} command sorts indices. |
| 14419 (The source file @file{texindex.c} comes as part of the standard | 15921 (The source file @file{texindex.c} comes as part of the standard |
| 14420 Texinfo distribution, among other places.) (@command{texi2dvi} runs | 15922 Texinfo distribution, among other places.) (@command{texi2dvi} runs |
| 14421 @command{tex} and @command{texindex} as necessary.) | 15923 @command{tex} and @command{texindex} as necessary.) |
| 14422 | 15924 |
| 15925 @anchor{Names of index files} | |
| 14423 @cindex Names of index files | 15926 @cindex Names of index files |
| 14424 @cindex Index file names | 15927 @cindex Index file names |
| 14425 The @code{tex} formatting command outputs unsorted index files under | 15928 @code{tex} formatting command outputs unsorted index files under names |
| 14426 names that obey a standard convention: the name of your main input file | 15929 that obey a standard convention: the name of your main input file with |
| 14427 with any @samp{.tex} (or similar, @pxref{tex invocation,,, web2c, | 15930 any @samp{.texinfo} (or similar, @pxref{Minimum,, What a Texinfo File |
| 14428 Web2c}) extension removed, followed by the two letter names of indices. | 15931 Must Have}), followed by the two letter names of indices. For |
| 14429 For example, the raw index output files for the input file | 15932 example, the raw index output files for the input file |
| 14430 @file{foo.texinfo} would be @file{foo.cp}, @file{foo.vr}, @file{foo.fn}, | 15933 @file{foo.texinfo} would be @file{foo.cp}, @file{foo.vr}, |
| 14431 @file{foo.tp}, @file{foo.pg} and @file{foo.ky}. Those are exactly the | 15934 @file{foo.fn}, @file{foo.tp}, @file{foo.pg} and @file{foo.ky}. Those |
| 14432 arguments to give to @code{texindex}. | 15935 are exactly the arguments to give to @code{texindex}. |
| 14433 | 15936 |
| 14434 @need 1000 | 15937 @need 1000 |
| 14435 @cindex Wildcards | 15938 @cindex Wildcards |
| 14436 @cindex Globbing | 15939 @cindex Globbing |
| 14437 Instead of specifying all the unsorted index file names explicitly, you | 15940 Instead of specifying all the unsorted index file names explicitly, you |
| 14442 texindex foo.?? | 15945 texindex foo.?? |
| 14443 @end example | 15946 @end example |
| 14444 | 15947 |
| 14445 @noindent | 15948 @noindent |
| 14446 This command will run @code{texindex} on all the unsorted index files, | 15949 This command will run @code{texindex} on all the unsorted index files, |
| 14447 including any that you have defined yourself using @code{@@defindex} | 15950 including any two letter indices that you have defined yourself using |
| 14448 or @code{@@defcodeindex}. (You may execute @samp{texindex foo.??} | 15951 @code{@@defindex} or @code{@@defcodeindex}. You can safely run |
| 14449 even if there are similarly named files with two letter extensions | 15952 @samp{texindex foo.??} even if there are files with two letter |
| 14450 that are not index files, such as @samp{foo.el}. The @code{texindex} | 15953 extensions that are not index files, such as @samp{foo.el}. The |
| 14451 command reports but otherwise ignores such files.) | 15954 @code{texindex} command reports but otherwise ignores such files. |
| 14452 | 15955 |
| 14453 For each file specified, @code{texindex} generates a sorted index file | 15956 For each file specified, @code{texindex} generates a sorted index file |
| 14454 whose name is made by appending @samp{s} to the input file name. The | 15957 whose name is made by appending @samp{s} to the input file name. The |
| 14455 @code{@@printindex} command looks for a file with that name | 15958 @code{@@printindex} command looks for a file with that name |
| 14456 (@pxref{Printing Indices & Menus}). @code{texindex} does not alter the | 15959 (@pxref{Printing Indices & Menus}). @code{texindex} does not alter the |
| 14459 After you have sorted the indices, you need to rerun @code{tex} on the | 15962 After you have sorted the indices, you need to rerun @code{tex} on the |
| 14460 Texinfo file. This regenerates the DVI file, this time with | 15963 Texinfo file. This regenerates the DVI file, this time with |
| 14461 up-to-date index entries. | 15964 up-to-date index entries. |
| 14462 | 15965 |
| 14463 Finally, you may need to run @code{tex} one more time, to get the page | 15966 Finally, you may need to run @code{tex} one more time, to get the page |
| 14464 numbers in the cross-references correct. | 15967 numbers in the cross references correct. |
| 14465 | 15968 |
| 14466 To summarize, this is a five step process: | 15969 To summarize, this is a five step process: |
| 14467 | 15970 |
| 14468 @enumerate | 15971 @enumerate |
| 14469 @item | 15972 @item |
| 14470 Run @code{tex} on your Texinfo file. This generates a DVI file (with | 15973 Run @code{tex} on your Texinfo file. This generates a DVI file (with |
| 14471 undefined cross-references and no indices), and the raw index files | 15974 undefined cross references and no indices), and the raw index files |
| 14472 (with two letter extensions). | 15975 (with two letter extensions). |
| 14473 | 15976 |
| 14474 @item | 15977 @item |
| 14475 Run @code{texindex} on the raw index files. This creates the | 15978 Run @code{texindex} on the raw index files. This creates the |
| 14476 corresponding sorted index files (with three letter extensions). | 15979 corresponding sorted index files (with three letter extensions). |
| 14477 | 15980 |
| 14478 @item | 15981 @item |
| 14479 Run @code{tex} again on your Texinfo file. This regenerates the DVI | 15982 Run @code{tex} again on your Texinfo file. This regenerates the DVI |
| 14480 file, this time with indices and defined cross-references, but with page | 15983 file, this time with indices and defined cross references, but with |
| 14481 numbers for the cross-references from last time, generally incorrect. | 15984 page numbers for the cross references from the previous run, generally |
| 15985 incorrect. | |
| 14482 | 15986 |
| 14483 @item | 15987 @item |
| 14484 Sort the indices again, with @code{texindex}. | 15988 Sort the indices again, with @code{texindex}. |
| 14485 | 15989 |
| 14486 @item | 15990 @item |
| 14487 Run @code{tex} one last time. This time the correct page numbers are | 15991 Run @code{tex} one last time. This time the correct page numbers are |
| 14488 written for the cross-references. | 15992 written for the cross references. |
| 14489 @end enumerate | 15993 @end enumerate |
| 14490 | 15994 |
| 14491 @pindex texi2dvi | 15995 @pindex texi2dvi |
| 14492 Alternatively, it's a one-step process: run @code{texi2dvi} | 15996 Alternatively, it's a one-step process: run @code{texi2dvi} |
| 14493 (@pxref{Format with texi2dvi}). | 15997 (@pxref{Format with @t{texi2dvi}}). |
| 14494 | 15998 |
| 14495 You need not run @code{texindex} each time after you run @code{tex}. If | 15999 You need not run @code{texindex} each time after you run @code{tex}. If |
| 14496 you do not, on the next run, the @code{tex} formatting command will use | 16000 you do not, on the next run, the @code{tex} formatting command will use |
| 14497 whatever sorted index files happen to exist from the previous use of | 16001 whatever sorted index files happen to exist from the previous use of |
| 14498 @code{texindex}. This is usually ok while you are debugging. | 16002 @code{texindex}. This is usually ok while you are debugging. |
| 14501 @findex novalidate | 16005 @findex novalidate |
| 14502 @cindex Pointer validation, suppressing | 16006 @cindex Pointer validation, suppressing |
| 14503 @cindex Chapters, formatting one at a time | 16007 @cindex Chapters, formatting one at a time |
| 14504 Sometimes you may wish to print a document while you know it is | 16008 Sometimes you may wish to print a document while you know it is |
| 14505 incomplete, or to print just one chapter of a document. In that case, | 16009 incomplete, or to print just one chapter of a document. In that case, |
| 14506 the usual auxiliary files that @TeX{} creates and warnings @TeX{} gives | 16010 the usual auxiliary files that @TeX{} creates and warnings @TeX{} |
| 14507 when cross-references are not satisfied are just nuisances. You can | 16011 gives when cross references are not satisfied are just nuisances. You |
| 14508 avoid them with the @code{@@novalidate} command, which you must give | 16012 can avoid them with the @code{@@novalidate} command, which you must |
| 14509 @emph{before} the @code{@@setfilename} command | 16013 give @emph{before} the @code{@@setfilename} command |
| 14510 (@pxref{setfilename,,@code{@@setfilename}}). Thus, the beginning of | 16014 (@pxref{@t{@@setfilename}}). Thus, the beginning of your file |
| 14511 your file would look approximately like this: | 16015 would look approximately like this: |
| 14512 | 16016 |
| 14513 @example | 16017 @example |
| 14514 \input texinfo | 16018 \input texinfo |
| 14515 @@novalidate | 16019 @@novalidate |
| 14516 @@setfilename myfile.info | 16020 @@setfilename myfile.info |
| 14520 @noindent @code{@@novalidate} also turns off validation in | 16024 @noindent @code{@@novalidate} also turns off validation in |
| 14521 @code{makeinfo}, just like its @code{--no-validate} option | 16025 @code{makeinfo}, just like its @code{--no-validate} option |
| 14522 (@pxref{Pointer Validation}). | 16026 (@pxref{Pointer Validation}). |
| 14523 | 16027 |
| 14524 | 16028 |
| 14525 @node Format with texi2dvi | 16029 @node Format with @t{texi2dvi} |
| 14526 @section Format with @code{texi2dvi} | 16030 @section Format with @code{texi2dvi} |
| 16031 | |
| 14527 @pindex texi2dvi @r{(shell script)} | 16032 @pindex texi2dvi @r{(shell script)} |
| 14528 | 16033 |
| 14529 The @code{texi2dvi} command automatically runs both @TeX{} and | 16034 The @code{texi2dvi} command automatically runs both @TeX{} and |
| 14530 @command{texindex} as many times as necessary to produce a DVI file | 16035 @command{texindex} as many times as necessary to produce a DVI file |
| 14531 with sorted indices and all cross-references resolved. It is | 16036 with sorted indices and all cross references resolved. It is |
| 14532 therefore simpler than manually executing the | 16037 therefore simpler than manually executing the |
| 14533 @code{tex}---@code{texindex}---@code{tex}---@code{tex} sequence | 16038 @code{tex}---@code{texindex}---@code{tex}---@code{tex} sequence |
| 14534 described in the previous section. | 16039 described in the previous section. |
| 14535 | 16040 |
| 14536 To run @code{texi2dvi} on an input file @file{foo.texi}, do this (where | 16041 To run @code{texi2dvi} on an input file @file{foo.texi}, do this (where |
| 14544 include any extension (@samp{.texi}, @samp{.texinfo}, etc.). Under | 16049 include any extension (@samp{.texi}, @samp{.texinfo}, etc.). Under |
| 14545 MS-DOS and perhaps in other circumstances, you may need to run @samp{sh | 16050 MS-DOS and perhaps in other circumstances, you may need to run @samp{sh |
| 14546 texi2dvi foo.texi} instead of relying on the operating system to invoke | 16051 texi2dvi foo.texi} instead of relying on the operating system to invoke |
| 14547 the shell on the @samp{texi2dvi} script. | 16052 the shell on the @samp{texi2dvi} script. |
| 14548 | 16053 |
| 14549 @opindex --command @r{(@command{texi2dvi})} | 16054 @opindex --command@r{, for @command{texi2dvi}} |
| 14550 One useful option to @code{texi2dvi} is @samp{--command=@var{cmd}}. | 16055 One useful option to @code{texi2dvi} is @samp{--command=@var{cmd}}. |
| 14551 This inserts @var{cmd} on a line by itself after the | 16056 This inserts @var{cmd} on a line by itself after the |
| 14552 @code{@@setfilename} in a temporary copy of the input file before | 16057 @code{@@setfilename} in a temporary copy of the input file before |
| 14553 running @TeX{}. With this, you can specify different printing | 16058 running @TeX{}. With this, you can specify different printing |
| 14554 formats, such as @code{@@smallbook} (@pxref{smallbook}), | 16059 formats, such as @code{@@smallbook} (@pxref{@t{@@smallbook}}), |
| 14555 @code{@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes} | 16060 @code{@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes} |
| 14556 (@pxref{pagesizes}), without actually changing the document source. | 16061 (@pxref{@t{@@pagesizes}}), without actually changing the document |
| 14557 (You can also do this on a site-wide basis with @file{texinfo.cnf}; | 16062 source. (You can also do this on a site-wide basis with |
| 14558 @pxref{Preparing for TeX,,Preparing for @TeX{}}). | 16063 @file{texinfo.cnf}; @pxref{Preparing for @TeX{}}). |
| 14559 | 16064 |
| 14560 @opindex --pdf @r{(@command{texi2dvi})} | 16065 @opindex --pdf@r{, for @command{texi2dvi}} |
| 16066 @pindex pdftexi2dvi | |
| 14561 With the @option{--pdf} option, @command{texi2dvi} produces PDF output | 16067 With the @option{--pdf} option, @command{texi2dvi} produces PDF output |
| 14562 instead of DVI (@pxref{PDF Output}), by running @command{pdftex} | 16068 instead of DVI (@pxref{PDF Output}), by running @command{pdftex} |
| 14563 instead of @command{tex}. Alternatively, the command | 16069 instead of @command{tex}. Alternatively, the command |
| 14564 @command{texi2pdf} is an abbreviation for running @samp{texi2dvi | 16070 @command{texi2pdf} is an abbreviation for running @samp{texi2dvi |
| 14565 --pdf}. The command @command{pdftexi2dvi} is also supported as a | 16071 --pdf}. The command @command{pdftexi2dvi} is also supported as a |
| 14566 convenience to AUC-@TeX{} users, since the latter merely prepends | 16072 convenience to AUC-@TeX{} users (@pxref{Top,,, auctex, AUC-@TeX{}}, since |
| 14567 @samp{pdf} to DVI producing tools to have PDF producing tools. | 16073 that program merely prepends @samp{pdf} to DVI producing tools to have |
| 16074 PDF producing tools. | |
| 16075 | |
| 16076 @opindex --dvipdf@r{, for @command{texi2dvi}} | |
| 16077 @pindex dvipdfmx | |
| 16078 With the @option{--dvipdf} option, @command{texi2dvi} produces PDF | |
| 16079 output by running @TeX{} and then a DVI-to-PDF program: if the | |
| 16080 @env{DVIPDF} environment variable is set, that value is used, else | |
| 16081 the first extant among @code{dvipdfmx}, @code{dvipdfm}, @code{dvipdf}, | |
| 16082 @code{dvi2pdf}, @code{dvitopdf}. This method can support CJK | |
| 16083 typesetting better than @command{pdftex}. | |
| 16084 | |
| 16085 @opindex --ps@r{, for @command{texi2dvi}} | |
| 16086 @pindex dvips | |
| 16087 With the @option{--ps} option, @command{texi2dvi} produces PostScript | |
| 16088 instead of DVI, by running @command{tex} and then @command{dvips} | |
| 16089 (@pxref{Top,,, dvips, Dvips}). (Or the value of the @env{DVIPS} | |
| 16090 environment variable, if set.) | |
| 14568 | 16091 |
| 14569 @cindex @LaTeX{}, processing with @command{texi2dvi} | 16092 @cindex @LaTeX{}, processing with @command{texi2dvi} |
| 14570 @command{texi2dvi} can also be used to process @LaTeX{} files; simply | 16093 @command{texi2dvi} can also be used to process @LaTeX{} files; simply |
| 14571 run @samp{texi2dvi filename.ext}. | 16094 run @samp{texi2dvi filename.ext}. |
| 14572 | 16095 |
| 14573 @opindex --language @r{(@command{texi2dvi})} | 16096 @opindex --language@r{, for @command{texi2dvi}} |
| 14574 Normally @command{texi2dvi} is able to guess the input file language | 16097 Normally @command{texi2dvi} is able to guess the input file language |
| 14575 by its contents and file name suffix. If, however, it fails to do so | 16098 by its contents and file name suffix. If, however, it fails to do so |
| 14576 you can specify the input language using | 16099 you can specify the input language using |
| 14577 @option{--language=@var{lang}} command line option, where @var{lang} | 16100 @option{--language=@var{lang}} command line option, where @var{lang} |
| 14578 is either @samp{latex} or @samp{texinfo}. | 16101 is either @samp{latex} or @samp{texinfo}. |
| 14581 they are available; these extended versions of @TeX{} are not | 16104 they are available; these extended versions of @TeX{} are not |
| 14582 required, and the DVI (or PDF) output is identical, but they simplify | 16105 required, and the DVI (or PDF) output is identical, but they simplify |
| 14583 the @TeX{} programming in some cases, and provide additional tracing | 16106 the @TeX{} programming in some cases, and provide additional tracing |
| 14584 information when debugging @file{texinfo.tex}. | 16107 information when debugging @file{texinfo.tex}. |
| 14585 | 16108 |
| 14586 @opindex --translate-file @r{(@command{texi2dvi})} | 16109 @opindex --translate-file@r{, for @command{texi2dvi}} |
| 14587 Several options are provided for handling documents, written in | 16110 Several options are provided for handling documents, written in |
| 14588 character sets other than ASCII. The | 16111 character sets other than ASCII@. The |
| 14589 @option{--translate-file=@var{file}} option instructs | 16112 @option{--translate-file=@var{file}} option instructs |
| 14590 @command{texi2dvi} to translate input into internal @TeX{} character | 16113 @command{texi2dvi} to translate input into internal @TeX{} character |
| 14591 set using @dfn{translation file} @var{file} (@pxref{TCX files, TCX | 16114 set using @dfn{translation file} @var{file} (@pxref{TCX files, TCX |
| 14592 files, TCX files: Character translations, web2c, Web2c: A @TeX{} | 16115 files, TCX files: Character translations, web2c, Web2c: A @TeX{} |
| 14593 implementation}). | 16116 implementation}). |
| 14594 | 16117 |
| 14595 @opindex --recode @r{(@command{texi2dvi})} | 16118 @opindex --recode@r{, for @command{texi2dvi}} |
| 14596 The options @option{--recode} and @option{--recode-from=@var{enc}} | 16119 The options @option{--recode} and @option{--recode-from=@var{enc}} |
| 14597 allow conversion of an input document before running @TeX{}. The | 16120 allow conversion of an input document before running @TeX{}. The |
| 14598 @option{--recode} option recodes the document from encoding specified | 16121 @option{--recode} option recodes the document from encoding specified |
| 14599 by @samp{@@documentencoding} command | 16122 by @samp{@@documentencoding} command |
| 14600 (@pxref{documentencoding,,@code{documentencoding}}) to plain 7-bit | 16123 (@pxref{@t{@@documentencoding}}) to plain 7-bit @samp{texinfo} |
| 14601 @samp{texinfo} encoding. | 16124 encoding. |
| 14602 | 16125 |
| 14603 @opindex --recode-from @r{(@command{texi2dvi})} | 16126 @opindex --recode-from@r{, for @command{texi2dvi}} |
| 14604 The option @option{--recode-from=@var{enc}} recodes the document from | 16127 The option @option{--recode-from=@var{enc}} recodes the document from |
| 14605 @var{enc} encoding to the encoding specified by | 16128 @var{enc} encoding to the encoding specified by |
| 14606 @samp{@@documentencoding}. This is useful, for example, if the | 16129 @samp{@@documentencoding}. This is useful, for example, if the |
| 14607 document is written in @samp{UTF-8} encoding and an equivalent 8-bit | 16130 document is written in @samp{UTF-8} encoding and an equivalent 8-bit |
| 14608 encoding is supported by @command{makeinfo}. | 16131 encoding is supported by @command{makeinfo}. |
| 14609 | 16132 |
| 14610 Both @option{--recode} and @option{--recode-from=@var{enc}} use | 16133 Both @option{--recode} and @option{--recode-from=@var{enc}} use |
| 14611 @command{recode} utility to perform the conversion. If | 16134 @command{recode} utility to perform the conversion. If |
| 14612 @command{recode} fails to process the file, @command{texi2dvi} prints | 16135 @command{recode} fails to process the file, @command{texi2dvi} prints |
| 14613 a warning and continues using unmodified input file. | 16136 a warning and continues, using the unmodified input file. |
| 14614 | 16137 |
| 14615 For a list of other options, run @samp{texi2dvi --help}. | 16138 The option @option{-E} (equivalently, @option{-e} and |
| 14616 | 16139 @option{--expand}) does Texinfo macro expansion using |
| 14617 | 16140 @command{makeinfo} instead of the @TeX{} implementation (@pxref{Macro |
| 14618 @node Print with lpr | 16141 Details}). Each implementation has its own limitations and |
| 14619 @section Shell Print Using @code{lpr -d} | 16142 advantages. If this option is used, the string |
| 16143 @code{@@c@tie{}_texi2dvi} must not appear at the beginning of a line | |
| 16144 in the source file. | |
| 16145 | |
| 16146 For the list of all options, run @samp{texi2dvi --help}. | |
| 16147 | |
| 16148 | |
| 16149 @node Print with @t{lpr} | |
| 16150 @section Print With @code{lpr -d} From Shell | |
| 16151 | |
| 14620 @pindex lpr @r{(DVI print command)} | 16152 @pindex lpr @r{(DVI print command)} |
| 14621 | 16153 |
| 14622 The precise command to print a DVI file depends on your system | 16154 The precise command to print a DVI file depends on your system |
| 14623 installation. Two common ones are @samp{dvips foo.dvi -o} and @samp{lpr | 16155 installation. Two common ones are @samp{dvips foo.dvi -o} and @samp{lpr |
| 14624 -d foo.dvi}. | 16156 -d foo.dvi}. |
| 14695 shell, you can format and print the document. @xref{Hardcopy, , Format | 16227 shell, you can format and print the document. @xref{Hardcopy, , Format |
| 14696 and Print Hardcopy}, for details. | 16228 and Print Hardcopy}, for details. |
| 14697 | 16229 |
| 14698 You can switch to and from the shell buffer while @code{tex} is | 16230 You can switch to and from the shell buffer while @code{tex} is |
| 14699 running and do other editing. If you are formatting a long document | 16231 running and do other editing. If you are formatting a long document |
| 14700 on a slow machine, this can be very convenient.@refill | 16232 on a slow machine, this can be very convenient. |
| 14701 | 16233 |
| 14702 You can also use @code{texi2dvi} from an XEmacs shell. For example, | 16234 You can also use @code{texi2dvi} from an XEmacs shell. For example, |
| 14703 here is how to use @code{texi2dvi} to format and print @cite{Using and | 16235 here is how to use @code{texi2dvi} to format and print @cite{Using and |
| 14704 Porting GNU CC} from a shell within XEmacs: | 16236 Porting GNU CC} from a shell within XEmacs: |
| 14705 | 16237 |
| 14722 | 16254 |
| 14723 Texinfo mode provides several predefined key commands for @TeX{} | 16255 Texinfo mode provides several predefined key commands for @TeX{} |
| 14724 formatting and printing. These include commands for sorting indices, | 16256 formatting and printing. These include commands for sorting indices, |
| 14725 looking at the printer queue, killing the formatting job, and | 16257 looking at the printer queue, killing the formatting job, and |
| 14726 recentering the display of the buffer in which the operations | 16258 recentering the display of the buffer in which the operations |
| 14727 occur.@refill | 16259 occur. |
| 14728 | 16260 |
| 14729 @table @kbd | 16261 @table @kbd |
| 14730 @item C-c C-t C-b | 16262 @item C-c C-t C-b |
| 14731 @itemx M-x texinfo-tex-buffer | 16263 @itemx M-x texinfo-tex-buffer |
| 14732 Run @code{texi2dvi} on the current buffer.@refill | 16264 Run @code{texi2dvi} on the current buffer. |
| 14733 | 16265 |
| 14734 @item C-c C-t C-r | 16266 @item C-c C-t C-r |
| 14735 @itemx M-x texinfo-tex-region | 16267 @itemx M-x texinfo-tex-region |
| 14736 Run @TeX{} on the current region.@refill | 16268 Run @TeX{} on the current region. |
| 14737 | 16269 |
| 14738 @item C-c C-t C-i | 16270 @item C-c C-t C-i |
| 14739 @itemx M-x texinfo-texindex | 16271 @itemx M-x texinfo-texindex |
| 14740 Sort the indices of a Texinfo file formatted with | 16272 Sort the indices of a Texinfo file formatted with |
| 14741 @code{texinfo-tex-region}.@refill | 16273 @code{texinfo-tex-region}. |
| 14742 | 16274 |
| 14743 @item C-c C-t C-p | 16275 @item C-c C-t C-p |
| 14744 @itemx M-x texinfo-tex-print | 16276 @itemx M-x texinfo-tex-print |
| 14745 Print a DVI file that was made with @code{texinfo-tex-region} or | 16277 Print a DVI file that was made with @code{texinfo-tex-region} or |
| 14746 @code{texinfo-tex-buffer}.@refill | 16278 @code{texinfo-tex-buffer}. |
| 14747 | 16279 |
| 14748 @item C-c C-t C-q | 16280 @item C-c C-t C-q |
| 14749 @itemx M-x tex-show-print-queue | 16281 @itemx M-x tex-show-print-queue |
| 14750 Show the print queue.@refill | 16282 Show the print queue. |
| 14751 | 16283 |
| 14752 @item C-c C-t C-d | 16284 @item C-c C-t C-d |
| 14753 @itemx M-x texinfo-delete-from-print-queue | 16285 @itemx M-x texinfo-delete-from-print-queue |
| 14754 Delete a job from the print queue; you will be prompted for the job | 16286 Delete a job from the print queue; you will be prompted for the job |
| 14755 number shown by a preceding @kbd{C-c C-t C-q} command | 16287 number shown by a preceding @kbd{C-c C-t C-q} command |
| 14756 (@code{texinfo-show-tex-print-queue}).@refill | 16288 (@code{texinfo-show-tex-print-queue}). |
| 14757 | 16289 |
| 14758 @item C-c C-t C-k | 16290 @item C-c C-t C-k |
| 14759 @itemx M-x tex-kill-job | 16291 @itemx M-x tex-kill-job |
| 14760 Kill the currently running @TeX{} job started by either | 16292 Kill the currently running @TeX{} job started by either |
| 14761 @code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other | 16293 @code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other |
| 14762 process running in the Texinfo shell buffer.@refill | 16294 process running in the Texinfo shell buffer. |
| 14763 | 16295 |
| 14764 @item C-c C-t C-x | 16296 @item C-c C-t C-x |
| 14765 @itemx M-x texinfo-quit-job | 16297 @itemx M-x texinfo-quit-job |
| 14766 Quit a @TeX{} formatting job that has stopped because of an error by | 16298 Quit a @TeX{} formatting job that has stopped because of an error by |
| 14767 sending an @key{x} to it. When you do this, @TeX{} preserves a record | 16299 sending an @key{x} to it. When you do this, @TeX{} preserves a record |
| 14768 of what it did in a @file{.log} file.@refill | 16300 of what it did in a @file{.log} file. |
| 14769 | 16301 |
| 14770 @item C-c C-t C-l | 16302 @item C-c C-t C-l |
| 14771 @itemx M-x tex-recenter-output-buffer | 16303 @itemx M-x tex-recenter-output-buffer |
| 14772 Redisplay the shell buffer in which the @TeX{} printing and formatting | 16304 Redisplay the shell buffer in which the @TeX{} printing and formatting |
| 14773 commands are run to show its most recent output.@refill | 16305 commands are run to show its most recent output. |
| 14774 @end table | 16306 @end table |
| 14775 | 16307 |
| 14776 @need 1000 | 16308 @need 1000 |
| 14777 Thus, the usual sequence of commands for formatting a buffer is as | 16309 Thus, the usual sequence of commands for formatting a buffer is as |
| 14778 follows (with comments to the right):@refill | 16310 follows (with comments to the right): |
| 14779 | 16311 |
| 14780 @example | 16312 @example |
| 14781 @group | 16313 @group |
| 14782 C-c C-t C-b @r{Run @code{texi2dvi} on the buffer.} | 16314 C-c C-t C-b @r{Run @code{texi2dvi} on the buffer.} |
| 14783 C-c C-t C-p @r{Print the DVI file.} | 16315 C-c C-t C-p @r{Print the DVI file.} |
| 14790 @code{texinfo-texindex-command}, and @code{tex-dvi-print-command} | 16322 @code{texinfo-texindex-command}, and @code{tex-dvi-print-command} |
| 14791 commands are all run in this shell. | 16323 commands are all run in this shell. |
| 14792 | 16324 |
| 14793 You can watch the commands operate in the @samp{*tex-shell*} buffer, | 16325 You can watch the commands operate in the @samp{*tex-shell*} buffer, |
| 14794 and you can switch to and from and use the @samp{*tex-shell*} buffer | 16326 and you can switch to and from and use the @samp{*tex-shell*} buffer |
| 14795 as you would any other shell buffer.@refill | 16327 as you would any other shell buffer. |
| 14796 | 16328 |
| 14797 @need 1500 | 16329 @need 1500 |
| 14798 The formatting and print commands depend on the values of several variables. | 16330 The formatting and print commands depend on the values of several variables. |
| 14799 The default values are:@refill | 16331 The default values are: |
| 14800 | 16332 |
| 14801 @example | 16333 @example |
| 14802 @group | 16334 @group |
| 14803 @r{Variable} @r{Default value} | 16335 @r{Variable} @r{Default value} |
| 14804 | 16336 |
| 14815 @end example | 16347 @end example |
| 14816 | 16348 |
| 14817 You can change the values of these variables with the @kbd{M-x | 16349 You can change the values of these variables with the @kbd{M-x |
| 14818 set-variable} command (@pxref{Examining, , Examining and Setting | 16350 set-variable} command (@pxref{Examining, , Examining and Setting |
| 14819 Variables, xemacs, XEmacs User's Manual}), or with your @file{init.el} | 16351 Variables, xemacs, XEmacs User's Manual}), or with your @file{init.el} |
| 14820 initialization file (@pxref{Init File, , , xemacs, The XEmacs | 16352 initialization file (@pxref{Init File, , , xemacs, XEmacs User's |
| 14821 Manual}). | 16353 Manual}). |
| 14822 | 16354 |
| 14823 @cindex Customize XEmacs package (@t{Development/Docs/Texinfo}) | 16355 @cindex Customize XEmacs package (@t{Development/Docs/Texinfo}) |
| 14824 Beginning with version 20, XEmacs offers a user-friendly interface, | 16356 Beginning with version 20, XEmacs offers a user-friendly interface, |
| 14825 called @dfn{Customize}, for changing values of user-definable variables. | 16357 called @dfn{Customize}, for changing values of user-definable variables. |
| 14840 Texinfo file. You can then specify the @code{tex} or @code{texi2dvi} | 16372 Texinfo file. You can then specify the @code{tex} or @code{texi2dvi} |
| 14841 commands as a @code{compile-command} and have XEmacs run it by typing | 16373 commands as a @code{compile-command} and have XEmacs run it by typing |
| 14842 @kbd{M-x compile}. This creates a special shell called the | 16374 @kbd{M-x compile}. This creates a special shell called the |
| 14843 @file{*compilation*} buffer in which XEmacs runs the compile command. | 16375 @file{*compilation*} buffer in which XEmacs runs the compile command. |
| 14844 For example, at the end of the @file{gdb.texinfo} file, after the | 16376 For example, at the end of the @file{gdb.texinfo} file, after the |
| 14845 @code{@@bye}, you could put the following:@refill | 16377 @code{@@bye}, you could put the following: |
| 14846 | 16378 |
| 14847 @example | 16379 @example |
| 14848 @group | 16380 @group |
| 14849 Local Variables: | 16381 Local Variables: |
| 14850 compile-command: "texi2dvi gdb.texinfo" | 16382 compile-command: "texi2dvi gdb.texinfo" |
| 14852 @end group | 16384 @end group |
| 14853 @end example | 16385 @end example |
| 14854 | 16386 |
| 14855 @noindent | 16387 @noindent |
| 14856 This technique is most often used by programmers who also compile programs | 16388 This technique is most often used by programmers who also compile programs |
| 14857 this way; see @ref{Compilation, , , xemacs, XEmacs User's Manual}.@refill | 16389 this way; see @ref{Compilation, , , xemacs, XEmacs User's Manual}. |
| 14858 | 16390 |
| 14859 | 16391 |
| 14860 @node Requirements Summary | 16392 @node Requirements Summary |
| 14861 @section @TeX{} Formatting Requirements Summary | 16393 @section @TeX{} Formatting Requirements Summary |
| 14862 @cindex Requirements for formatting | 16394 @cindex Requirements for formatting |
| 14866 Every Texinfo file that is to be input to @TeX{} must begin with a | 16398 Every Texinfo file that is to be input to @TeX{} must begin with a |
| 14867 @code{\input} command and must contain an @code{@@setfilename} command: | 16399 @code{\input} command and must contain an @code{@@setfilename} command: |
| 14868 | 16400 |
| 14869 @example | 16401 @example |
| 14870 \input texinfo | 16402 \input texinfo |
| 14871 @@setfilename @var{arg-not-used-by-@@TeX@{@}} | 16403 @@setfilename @var{arg-not-used-by-@TeX{}} |
| 14872 @end example | 16404 @end example |
| 14873 | 16405 |
| 14874 @noindent | 16406 @noindent |
| 14875 The first command instructs @TeX{} to load the macros it needs to | 16407 The first command instructs @TeX{} to load the macros it needs to |
| 14876 process a Texinfo file and the second command opens auxiliary files. | 16408 process a Texinfo file and the second command opens auxiliary files. |
| 14892 contents. (And of course most manuals contain a body of text as well.) | 16424 contents. (And of course most manuals contain a body of text as well.) |
| 14893 | 16425 |
| 14894 For more information, see: | 16426 For more information, see: |
| 14895 | 16427 |
| 14896 @itemize @bullet | 16428 @itemize @bullet |
| 14897 @item @ref{settitle, , @code{@@settitle}}. | 16429 @item @ref{@t{@@settitle}}. |
| 14898 @item @ref{setchapternewpage, , @code{@@setchapternewpage}}. | 16430 @item @ref{@t{@@setchapternewpage}}. |
| 14899 @item @ref{Headings, ,Page Headings}. | 16431 @item @ref{Headings}. |
| 14900 @item @ref{Titlepage & Copyright Page}. | 16432 @item @ref{Titlepage & Copyright Page}. |
| 14901 @item @ref{Printing Indices & Menus}. | 16433 @item @ref{Printing Indices & Menus}. |
| 14902 @item @ref{Contents}. | 16434 @item @ref{Contents}. |
| 14903 @end itemize | 16435 @end itemize |
| 14904 | 16436 |
| 14905 | 16437 |
| 14906 @node Preparing for TeX | 16438 @node Preparing for @TeX{} |
| 14907 @section Preparing for @TeX{} | 16439 @section Preparing for @TeX{} |
| 14908 @cindex Preparing for @TeX{} | 16440 @cindex Preparing for @TeX{} |
| 14909 @cindex @TeX{} input initialization | 16441 @cindex @TeX{} input initialization |
| 14910 @cindex @b{.profile} initialization file | 16442 @cindex @b{.profile} initialization file |
| 14911 @cindex @b{.cshrc} initialization file | 16443 @cindex @b{.cshrc} initialization file |
| 14943 Quotation Marks}). | 16475 Quotation Marks}). |
| 14944 | 16476 |
| 14945 @pindex feymr10@r{, installing} | 16477 @pindex feymr10@r{, installing} |
| 14946 @cindex Euro font, installing | 16478 @cindex Euro font, installing |
| 14947 If you intend to use the @code{@@euro} command, you should install the | 16479 If you intend to use the @code{@@euro} command, you should install the |
| 14948 Euro font, if it is not already installed. @xref{euro}. | 16480 Euro font, if it is not already installed. @xref{@t{@@euro}}. |
| 14949 | 16481 |
| 14950 @pindex texinfo.cnf @r{installation} | 16482 @pindex texinfo.cnf @r{installation} |
| 14951 @cindex Customizing of @TeX{} for Texinfo | 16483 @cindex Customizing of @TeX{} for Texinfo |
| 14952 @cindex Site-wide Texinfo configuration file | 16484 @cindex Site-wide Texinfo configuration file |
| 14953 Optionally, you may create an additional @file{texinfo.cnf}, and install | 16485 Optionally, you may create a file @file{texinfo.cnf} for site |
| 14954 it as well. This file is read by @TeX{} when the @code{@@setfilename} | 16486 configuration. This file is read by @TeX{} when the |
| 14955 command is executed (@pxref{setfilename,, @code{@@setfilename}}). You can put any | 16487 @code{@@setfilename} command is executed (@pxref{@t{@@setfilename}}). |
| 14956 commands you like there, according to local site-wide conventions. They | 16488 You can put any commands you like there, according to local site-wide |
| 14957 will be read by @TeX{} when processing any Texinfo document. For | 16489 conventions. They will be read by @TeX{} when processing any Texinfo |
| 14958 example, if @file{texinfo.cnf} contains the line @samp{@@afourpaper} | 16490 document. For example, if @file{texinfo.cnf} contains the line |
| 14959 (@pxref{A4 Paper}), then all Texinfo documents will be processed with | 16491 @samp{@@afourpaper} (@pxref{A4 Paper}), then all Texinfo documents |
| 14960 that page size in effect. If you have nothing to put in | 16492 will be processed with that page size in effect. If you have nothing |
| 14961 @file{texinfo.cnf}, you do not need to create it. | 16493 to put in @file{texinfo.cnf}, you do not need to create it. |
| 14962 | 16494 |
| 14963 @cindex Environment variable @code{TEXINPUTS} | 16495 @cindex Environment variable @code{TEXINPUTS} |
| 14964 @vindex TEXINPUTS | 16496 @vindex TEXINPUTS |
| 14965 If neither of the above locations for these system files suffice for | 16497 If neither of the above locations for these system files suffice for |
| 14966 you, you can specify the directories explicitly. For | 16498 you, you can specify the directories explicitly. For |
| 14967 @file{texinfo.tex}, you can do this by writing the complete path for the | 16499 @file{texinfo.tex}, you can do this by writing the complete path for the |
| 14968 file after the @code{\input} command. Another way, that works for both | 16500 file after the @code{\input} command. Another way, that works for both |
| 14969 @file{texinfo.tex} and @file{texinfo.cnf} (and any other file @TeX{} | 16501 @file{texinfo.tex} and @file{texinfo.cnf} (and any other file @TeX{} |
| 14970 might read), is to set the @code{TEXINPUTS} environment variable in your | 16502 might read), is to set the @code{TEXINPUTS} environment variable in your |
| 14971 @file{.cshrc} or @file{.profile} file. | 16503 @file{.profile} or @file{.cshrc} file. |
| 14972 | 16504 |
| 14973 Which you use of @file{.cshrc} or @file{.profile} depends on | 16505 Whether you use @file{.profile} or @file{.cshrc} depends on |
| 14974 whether you use a Bourne shell-compatible (@code{sh}, @code{bash}, | 16506 whether you use a Bourne shell-compatible (@code{sh}, @code{bash}, |
| 14975 @code{ksh}, @dots{}) or C shell-compatible (@code{csh}, @code{tcsh}) | 16507 @code{ksh}, @dots{}) or C shell-compatible (@code{csh}, @code{tcsh}) |
| 14976 command interpreter. The latter read the @file{.cshrc} file for | 16508 command interpreter, respeictvely. |
| 14977 initialization information, and the former read @file{.profile}. | 16509 |
| 14978 | |
| 14979 In a @file{.cshrc} file, you could use the following @code{csh} command | |
| 14980 sequence: | |
| 14981 | |
| 14982 @example | |
| 14983 setenv TEXINPUTS .:/home/me/mylib: | |
| 14984 @end example | |
| 14985 | |
| 14986 @need 1000 | |
| 14987 In a @file{.profile} file, you could use the following @code{sh} command | 16510 In a @file{.profile} file, you could use the following @code{sh} command |
| 14988 sequence: | 16511 sequence: |
| 14989 | 16512 |
| 14990 @example | 16513 @example |
| 14991 @group | 16514 @group |
| 14992 TEXINPUTS=.:/home/me/mylib: | 16515 TEXINPUTS=.:/home/me/mylib: |
| 14993 export TEXINPUTS | 16516 export TEXINPUTS |
| 14994 @end group | 16517 @end group |
| 14995 @end example | 16518 @end example |
| 14996 | 16519 |
| 16520 @need 1000 | |
| 16521 While in a @file{.cshrc} file, you could use the following @code{csh} | |
| 16522 command sequence: | |
| 16523 | |
| 16524 @example | |
| 16525 setenv TEXINPUTS .:/home/me/mylib: | |
| 16526 @end example | |
| 16527 | |
| 16528 | |
| 14997 On MS-DOS/MS-Windows, you would say it like this@footnote{Note the use | 16529 On MS-DOS/MS-Windows, you would say it like this@footnote{Note the use |
| 14998 of the @samp{;} character, instead of @samp{:}, as directory separator | 16530 of the @samp{;} character as directory separator, instead of @samp{:}.}: |
| 14999 on these systems.}: | |
| 15000 | 16531 |
| 15001 @example | 16532 @example |
| 15002 @group | 16533 @group |
| 15003 set TEXINPUTS=.;d:/home/me/mylib;c: | 16534 set TEXINPUTS=.;d:/home/me/mylib;c: |
| 15004 @end group | 16535 @end group |
| 15005 @end example | 16536 @end example |
| 15006 | 16537 |
| 15007 @noindent | 16538 @noindent |
| 15008 It is customary for DOS/Windows users to put such commands in the | 16539 It is customary for DOS/Windows users to put such commands in the |
| 15009 @file{autoexec.bat} file, or in the Windows Registry. | 16540 @file{autoexec.bat} file, or in the Windows registry. |
| 15010 | 16541 |
| 15011 @noindent | 16542 @noindent |
| 15012 These settings would cause @TeX{} to look for @file{\input} file first | 16543 These settings would cause @TeX{} to look for @file{\input} file first |
| 15013 in the current directory, indicated by the @samp{.}, then in a | 16544 in the current directory, indicated by the @samp{.}, then in a |
| 15014 hypothetical user @samp{me}'s @file{mylib} directory, and finally in | 16545 hypothetical user @samp{me}'s @file{mylib} directory, and finally in |
| 15016 indicates searching the system directories at that point.) | 16547 indicates searching the system directories at that point.) |
| 15017 | 16548 |
| 15018 @cindex Dumping a .fmt file | 16549 @cindex Dumping a .fmt file |
| 15019 @cindex Format file, dumping | 16550 @cindex Format file, dumping |
| 15020 Finally, you may wish to dump a @file{.fmt} file (@pxref{Memory dumps,,, | 16551 Finally, you may wish to dump a @file{.fmt} file (@pxref{Memory dumps,,, |
| 15021 web2c, Web2c}) so that @TeX{} can load Texinfo faster. (The | 16552 web2c, Web2C}) so that @TeX{} can load Texinfo faster. (The |
| 15022 disadvantage is that then updating @file{texinfo.tex} requires | 16553 disadvantage is that then updating @file{texinfo.tex} requires |
| 15023 redumping.) You can do this by running this command, assuming | 16554 redumping.) You can do this by running this command, assuming |
| 15024 @file{epsf.tex} is findable by @TeX{}: | 16555 @file{epsf.tex} is findable by @TeX{}: |
| 15025 | 16556 |
| 15026 @example | 16557 @example |
| 15034 | 16565 |
| 15035 | 16566 |
| 15036 @node Overfull hboxes | 16567 @node Overfull hboxes |
| 15037 @section Overfull ``hboxes'' | 16568 @section Overfull ``hboxes'' |
| 15038 @cindex Overfull @samp{hboxes} | 16569 @cindex Overfull @samp{hboxes} |
| 15039 @cindex @samp{hboxes}, overfull | 16570 @cindex @samp{hbox}, overfull |
| 15040 @cindex Final output | 16571 @cindex Final output |
| 15041 | 16572 |
| 15042 @TeX{} is sometimes unable to typeset a line without extending it into | 16573 @TeX{} is sometimes unable to typeset a line without extending it into |
| 15043 the right margin. This can occur when @TeX{} comes upon what it | 16574 the right margin. This can occur when @TeX{} comes upon what it |
| 15044 interprets as a long word that it cannot hyphenate, such as an | 16575 interprets as a long word that it cannot hyphenate, such as an |
| 15050 @end example | 16581 @end example |
| 15051 | 16582 |
| 15052 @findex hbox | 16583 @findex hbox |
| 15053 @noindent | 16584 @noindent |
| 15054 (In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''. | 16585 (In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''. |
| 15055 @samp{@@hbox} is a @TeX{} primitive not needed in the Texinfo language.) | 16586 @samp{@@hbox} is a @TeX{} primitive not used in the Texinfo language.) |
| 15056 | 16587 |
| 15057 @TeX{} also provides the line number in the Texinfo source file and | 16588 @TeX{} also provides the line number in the Texinfo source file and |
| 15058 the text of the offending line, which is marked at all the places that | 16589 the text of the offending line, which is marked at all the places that |
| 15059 @TeX{} considered hyphenation. | 16590 @TeX{} considered hyphenation. |
| 15060 @xref{Debugging with TeX, , Catching Errors with @TeX{} Formatting}, | 16591 @xref{Debugging with @TeX{}}, |
| 15061 for more information about typesetting errors. | 16592 for more information about typesetting errors. |
| 15062 | 16593 |
| 15063 If the Texinfo file has an overfull hbox, you can rewrite the sentence | 16594 If the Texinfo file has an overfull hbox, you can rewrite the sentence |
| 15064 so the overfull hbox does not occur, or you can decide to leave it. A | 16595 so the overfull hbox does not occur, or you can decide to leave it. A |
| 15065 small excursion into the right margin often does not matter and may not | 16596 small excursion into the right margin often does not matter and may not |
| 15101 @example | 16632 @example |
| 15102 @@finalout | 16633 @@finalout |
| 15103 @end example | 16634 @end example |
| 15104 | 16635 |
| 15105 | 16636 |
| 15106 @node smallbook | 16637 @node @t{@@smallbook} |
| 15107 @section Printing ``Small'' Books | 16638 @section @code{@@smallbook}: Printing ``Small'' Books |
| 16639 | |
| 16640 @anchor{smallbook}@c old name | |
| 15108 @findex smallbook | 16641 @findex smallbook |
| 15109 @cindex Small book size | 16642 @cindex Small book size |
| 15110 @cindex Book, printing small | 16643 @cindex Book, printing small |
| 15111 @cindex Page sizes for books | 16644 @cindex Page sizes for books |
| 15112 @cindex Size of printed book | 16645 @cindex Size of printed book |
| 15113 | 16646 |
| 15114 By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch | 16647 By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch |
| 15115 format. However, you can direct @TeX{} to typeset a document in a 7 by | 16648 format. However, you can direct @TeX{} to typeset a document in a 7 by |
| 15116 9.25 inch format that is suitable for bound books by inserting the | 16649 9.25 inch format that is suitable for bound books by inserting the |
| 15117 following command on a line by itself at the beginning of the Texinfo | 16650 following command on a line by itself at the beginning of the Texinfo |
| 15118 file, before the title page:@refill | 16651 file, before the title page: |
| 15119 | 16652 |
| 15120 @example | 16653 @example |
| 15121 @@smallbook | 16654 @@smallbook |
| 15122 @end example | 16655 @end example |
| 15123 | 16656 |
| 15128 inch format.) | 16661 inch format.) |
| 15129 | 16662 |
| 15130 If you write the @code{@@smallbook} command between the | 16663 If you write the @code{@@smallbook} command between the |
| 15131 start-of-header and end-of-header lines, the Texinfo mode @TeX{} | 16664 start-of-header and end-of-header lines, the Texinfo mode @TeX{} |
| 15132 region formatting command, @code{texinfo-tex-region}, will format the | 16665 region formatting command, @code{texinfo-tex-region}, will format the |
| 15133 region in ``small'' book size (@pxref{Start of Header}).@refill | 16666 region in ``small'' book size (@pxref{Start of Header}). |
| 15134 | 16667 |
| 15135 @xref{small}, for information about | 16668 @xref{@t{@@small@dots{}}}, for information about commands that make |
| 15136 commands that make it easier to produce examples for a smaller manual. | 16669 it easier to produce examples for a smaller manual. |
| 15137 | 16670 |
| 15138 @xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for | 16671 @xref{Format with @t{texi2dvi}}, and @ref{Preparing for @TeX{}}, |
| 15139 @TeX{}}, for other ways to format with @code{@@smallbook} that do not | 16672 for other ways to format with @code{@@smallbook} that do not require |
| 15140 require changing the source file. | 16673 changing the source file. |
| 15141 | 16674 |
| 15142 | 16675 |
| 15143 @node A4 Paper | 16676 @node A4 Paper |
| 15144 @section Printing on A4 Paper | 16677 @section Printing on A4 Paper |
| 15145 @cindex A4 paper, printing on | 16678 @cindex A4 paper, printing on |
| 15163 @@afourpaper | 16696 @@afourpaper |
| 15164 @@c %**end of header | 16697 @@c %**end of header |
| 15165 @end group | 16698 @end group |
| 15166 @end example | 16699 @end example |
| 15167 | 16700 |
| 15168 @xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for | 16701 @xref{Format with @t{texi2dvi}}, and @ref{Preparing for @TeX{}}, |
| 15169 @TeX{}}, for other ways to format for different paper sizes that do not | 16702 for other ways to format for different paper sizes that do not require |
| 15170 require changing the source file. | 16703 changing the source file. |
| 15171 | 16704 |
| 15172 @findex afourlatex | 16705 @findex afourlatex |
| 15173 @findex afourwide | 16706 @findex afourwide |
| 15174 You may or may not prefer the formatting that results from the command | 16707 You may or may not prefer the formatting that results from the command |
| 15175 @code{@@afourlatex}. There's also @code{@@afourwide} for A4 paper in | 16708 @code{@@afourlatex}. There's also @code{@@afourwide} for A4 paper in |
| 15176 wide format. | 16709 wide format. |
| 15177 | 16710 |
| 15178 @node pagesizes | 16711 |
| 16712 @node @t{@@pagesizes} | |
| 15179 @section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom Page Sizes | 16713 @section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom Page Sizes |
| 16714 @anchor{pagesizes}@c old node name | |
| 16715 | |
| 15180 @findex pagesizes | 16716 @findex pagesizes |
| 15181 @cindex Custom page sizes | 16717 @cindex Custom page sizes |
| 15182 @cindex Page sizes, customized | 16718 @cindex Page sizes, customized |
| 15183 @cindex Text width and height | 16719 @cindex Text width and height |
| 15184 @cindex Width of text area | 16720 @cindex Width of text area |
| 15206 the paper (which is 250@dmn{mm} by 177@dmn{mm} for B5, 14@dmn{in} by | 16742 the paper (which is 250@dmn{mm} by 177@dmn{mm} for B5, 14@dmn{in} by |
| 15207 8.5@dmn{in} for legal). | 16743 8.5@dmn{in} for legal). |
| 15208 | 16744 |
| 15209 @cindex Margins on page, not controllable | 16745 @cindex Margins on page, not controllable |
| 15210 To make more elaborate changes, such as changing any of the page | 16746 To make more elaborate changes, such as changing any of the page |
| 15211 margins, you must define a new command in @file{texinfo.tex} (or | 16747 margins, you must define a new command in @file{texinfo.tex} or |
| 15212 @file{texinfo.cnf}, @pxref{Preparing for TeX,,Preparing for @TeX{}}). | 16748 @file{texinfo.cnf}. |
| 15213 | 16749 |
| 15214 @xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for | 16750 @xref{Format with @t{texi2dvi}}, and @ref{Preparing for @TeX{}}, |
| 15215 @TeX{}}, for other ways to specify @code{@@pagesizes} that do not | 16751 for other ways to specify @code{@@pagesizes} that do not require |
| 15216 require changing the source file. | 16752 changing the source file. |
| 15217 | 16753 |
| 15218 @code{@@pagesizes} is ignored by @code{makeinfo}. | 16754 @code{@@pagesizes} is ignored by @code{makeinfo}. |
| 15219 | 16755 |
| 15220 | 16756 |
| 15221 @node Cropmarks and Magnification | 16757 @node Cropmarks and Magnification |
| 15222 @section Cropmarks and Magnification | 16758 @section Cropmarks and Magnification |
| 16759 | |
| 15223 @findex cropmarks | 16760 @findex cropmarks |
| 15224 @cindex Cropmarks for printing | 16761 @cindex Cropmarks for printing |
| 15225 @cindex Printing cropmarks | 16762 @cindex Printing cropmarks |
| 15226 You can (attempt to) direct @TeX{} to print cropmarks at the corners of | 16763 You can (attempt to) direct @TeX{} to print cropmarks at the corners |
| 15227 pages with the @code{@@cropmarks} command. Write the @code{@@cropmarks} | 16764 of pages with the @code{@@cropmarks} command. Write the |
| 15228 command on a line by itself between @code{@@iftex} and @code{@@end | 16765 @code{@@cropmarks} command on a line by itself near the beginning of |
| 15229 iftex} lines near the beginning of the Texinfo file, before the title | 16766 the Texinfo file, before the title page, like this: |
| 15230 page, like this:@refill | 16767 |
| 15231 | 16768 @example |
| 15232 @example | |
| 15233 @group | |
| 15234 @@iftex | |
| 15235 @@cropmarks | 16769 @@cropmarks |
| 15236 @@end iftex | |
| 15237 @end group | |
| 15238 @end example | 16770 @end example |
| 15239 | 16771 |
| 15240 This command is mainly for printers that typeset several pages on one | 16772 This command is mainly for printers that typeset several pages on one |
| 15241 sheet of film; but you can attempt to use it to mark the corners of a | 16773 sheet of film; but you can attempt to use it to mark the corners of a |
| 15242 book set to 7 by 9.25 inches with the @code{@@smallbook} command. | 16774 book set to 7 by 9.25 inches with the @code{@@smallbook} command. |
| 15243 (Printers will not produce cropmarks for regular sized output that is | 16775 (Printers will not produce cropmarks for regular sized output that is |
| 15244 printed on regular sized paper.) Since different printing machines work | 16776 printed on regular sized paper.) Since different printing machines |
| 15245 in different ways, you should explore the use of this command with a | 16777 work in different ways, you should explore the use of this command |
| 15246 spirit of adventure. You may have to redefine the command in | 16778 with a spirit of adventure. You may have to redefine the command in |
| 15247 @file{texinfo.tex}. | 16779 @file{texinfo.tex}. |
| 16780 | |
| 16781 The @code{@@cropmarks} command is recognized and ignored in non-@TeX{} | |
| 16782 output formats. | |
| 15248 | 16783 |
| 15249 @findex \mag @r{(raw @TeX{} magnification)} | 16784 @findex \mag @r{(raw @TeX{} magnification)} |
| 15250 @cindex Magnified printing | 16785 @cindex Magnified printing |
| 15251 @cindex Larger or smaller pages | 16786 @cindex Larger or smaller pages |
| 15252 You can attempt to direct @TeX{} to typeset pages larger or smaller than | 16787 You can attempt to direct @TeX{} to typeset pages larger or smaller |
| 15253 usual with the @code{\mag} @TeX{} command. Everything that is typeset | 16788 than usual with the @code{\mag} @TeX{} command. Everything that is |
| 15254 is scaled proportionally larger or smaller. (@code{\mag} stands for | 16789 typeset is scaled proportionally larger or smaller. (@code{\mag} |
| 15255 ``magnification''.) This is @emph{not} a Texinfo @@-command, but is a | 16790 stands for ``magnification''.) This is @emph{not} a Texinfo |
| 15256 plain @TeX{} command that is prefixed with a backslash. You have to | 16791 @@-command, but is a raw @TeX{} command that is prefixed with a |
| 15257 write this command between @code{@@tex} and @code{@@end tex} | 16792 backslash. You have to write this command between @code{@@tex} and |
| 15258 (@pxref{Raw Formatter Commands}). | 16793 @code{@@end tex} (@pxref{Raw Formatter Commands}). |
| 15259 | 16794 |
| 15260 Follow the @code{\mag} command with an @samp{=} and then a number that | 16795 Follow the @code{\mag} command with an @samp{=} and then a number that |
| 15261 is 1000 times the magnification you desire. For example, to print pages | 16796 is 1000 times the magnification you desire. For example, to print pages |
| 15262 at 1.2 normal size, write the following near the beginning of the | 16797 at 1.2 normal size, write the following near the beginning of the |
| 15263 Texinfo file, before the title page: | 16798 Texinfo file, before the title page: |
| 15285 @cindex PDF output | 16820 @cindex PDF output |
| 15286 | 16821 |
| 15287 @pindex pdftex | 16822 @pindex pdftex |
| 15288 The simplest way to generate PDF output from Texinfo source is to run | 16823 The simplest way to generate PDF output from Texinfo source is to run |
| 15289 the convenience script @command{texi2pdf} (or @command{pdftexi2dvi}); | 16824 the convenience script @command{texi2pdf} (or @command{pdftexi2dvi}); |
| 15290 this simply executes the @command{texi2dvi} script with the | 16825 this executes the @command{texi2dvi} script with the @option{--pdf} |
| 15291 @option{--pdf} option (@pxref{Format with texi2dvi}). If for some | 16826 option (@pxref{Format with @t{texi2dvi}}). If for some reason you |
| 15292 reason you want to process the document by hand, simply run the | 16827 want to process the document by hand, you can run the @command{pdftex} |
| 15293 @command{pdftex} program instead of plain @command{tex}. That is, run | 16828 program instead of plain @command{tex}. That is, run @samp{pdftex |
| 15294 @samp{pdftex foo.texi} instead of @samp{tex foo.texi}. | 16829 foo.texi} instead of @samp{tex foo.texi}. |
| 15295 | 16830 |
| 15296 @dfn{PDF} stands for `Portable Document Format'. It was invented by | 16831 @dfn{PDF} stands for `Portable Document Format'. It was invented by |
| 15297 Adobe Systems some years ago for document interchange, based on their | 16832 Adobe Systems some years ago for document interchange, based on their |
| 15298 PostScript language. Related links: | 16833 PostScript language. Related links: |
| 15299 | 16834 |
| 15300 @itemize | 16835 @itemize |
| 15301 @item | 16836 @item |
| 15302 GNU GV, a @uref{http://www.foolabs.com/xpdf/, Ghostscript-based PDF | 16837 GNU GV, a @uref{http://www.gnu.org/software/gv/, Ghostscript-based PDF |
| 15303 reader}. (It can also preview PostScript documents.) | 16838 reader}. (It can also preview PostScript documents.) |
| 15304 | 16839 |
| 15305 @item | 16840 @item |
| 15306 A freely available standalone @uref{http://www.foolabs.com/xpdf/, | 16841 @code{xpdf}, a freely available standalone |
| 15307 PDF reader} for the X window system. | 16842 @uref{http://www.foolabs.com/xpdf/, PDF reader} for the X window |
| 16843 system. | |
| 15308 | 16844 |
| 15309 @item | 16845 @item |
| 15310 @uref{http://partners.adobe.com/asn/acrobat/sdk/public/docs/, PDF definition}. | 16846 @uref{http://partners.adobe.com/asn/acrobat/sdk/public/docs/, PDF definition}. |
| 15311 | 16847 |
| 15312 @end itemize | 16848 @end itemize |
| 15313 | 16849 |
| 15314 At present, Texinfo does not provide | 16850 At present, Texinfo does not provide @samp{@@ifpdf} or @samp{@@pdf} |
| 15315 @samp{@@ifpdf} or @samp{@@pdf} commands as for the other output | 16851 commands as for the other output formats, since PDF documents contain |
| 15316 formats, since PDF documents contain many internal links that would be | 16852 many internal low-level offsets and references that would be hard or |
| 15317 hard or impossible to get right at the Texinfo source level. | 16853 impossible to get right at the Texinfo source level. |
| 15318 | 16854 |
| 15319 PDF files require special software to be displayed, unlike the plain | 16855 PDF files require dedicated software to be displayed, unlike the plain |
| 15320 ASCII formats (Info, HTML) that Texinfo supports. They also tend to | 16856 ASCII formats (Info, HTML) that Texinfo supports. They also tend to |
| 15321 be much larger than the DVI files output by @TeX{} by default. | 16857 be much larger than the DVI files output by @TeX{} by default. |
| 15322 Nevertheless, a PDF file does define an actual typeset document in a | 16858 Nevertheless, a PDF file does define an actual typeset document in a |
| 15323 self-contained file, so it has its place. | 16859 self-contained file, so it has its place. |
| 15324 | 16860 |
| 15325 | 16861 |
| 15326 @node Obtaining TeX | 16862 @node Obtaining @TeX{} |
| 15327 @section How to Obtain @TeX{} | 16863 @section Obtaining @TeX{} |
| 15328 @cindex Obtaining @TeX{} | 16864 @cindex Obtaining @TeX{} |
| 15329 @cindex @TeX{}, how to obtain | 16865 @cindex @TeX{}, how to obtain |
| 15330 | 16866 |
| 15331 @c !!! Here is information about obtaining TeX. Update it whenever. | 16867 @TeX{} is a document formatter that is used by the FSF for its |
| 15332 @c !!! Also consider updating TeX.README on ftp.gnu.org. | 16868 documentation. It is the easiest way to get printed output (e.g., PDF |
| 15333 @c Updated by RJC on 1 March 1995, conversation with MacKay. | 16869 and PostScript) for Texinfo manuals. TeX is freely redistributable, |
| 15334 @c Updated by kb@cs.umb.edu on 29 July 1996. | 16870 and you can get it over the Internet or on physical media. See |
| 15335 @c Updated by kb@cs.umb.edu on 25 April 1997. | 16871 @url{http://tug.org/texlive}. |
| 15336 @c Updated by kb@cs.umb.edu on 27 February 1998. | 16872 |
| 15337 @TeX{} is freely redistributable. You can obtain @TeX{} for Unix | 16873 @c please keep that text in sync with www.gnu.org/prep/FTP |
| 15338 systems via anonymous ftp or on physical media. The core material | 16874 |
| 15339 consists of the Web2c @TeX{} distribution (@uref{http://tug.org/web2c}). | 16875 |
| 15340 | 16876 @node Generic Translator @t{texi2any} |
| 15341 Instructions for retrieval by anonymous ftp and information on other | 16877 @chapter @code{texi2any}: The Generic Translator for Texinfo |
| 15342 available distributions: | 16878 |
| 15343 @uref{http://tug.org/unixtex.ftp}. | 16879 @command{texi2any} is the generic translator for Texinfo that can |
| 15344 | 16880 produce different output formats and is highly customizable. It |
| 15345 The Free Software Foundation provides a core distribution on its Source | 16881 supports these formats: |
| 15346 Code CD-ROM suitable for printing Texinfo manuals. To order it, contact: | 16882 |
| 15347 | 16883 @table @asis |
| 15348 @display | 16884 @item Info (by default, or with @option{--info}), |
| 15349 @group | 16885 |
| 15350 Free Software Foundation, Inc. | 16886 @item HTML (with @option{--html}), |
| 15351 51 Franklin St, Fifth Floor | 16887 |
| 15352 Boston, MA @ @ 02110-1301 | 16888 @item plain text (with @option{--plaintext}), |
| 15353 USA | 16889 |
| 15354 Telephone: @w{+1-617-542-5942} | 16890 @item Docbook (with @option{--docbook}), |
| 15355 Fax: (including Japan) @w{+1-617-542-2652} | 16891 |
| 15356 Free Dial Fax (in Japan): | 16892 @item Texinfo XML (with @option{--xml}). |
| 15357 @w{ } @w{ } @w{ } 0031-13-2473 (KDD) | 16893 @end table |
| 15358 @w{ } @w{ } @w{ } 0066-3382-0158 (IDC) | 16894 |
| 15359 Electronic mail: @code{gnu@@gnu.org} | 16895 @command{makeinfo} is an alias for @command{texi2any}. By default, |
| 15360 @end group | 16896 both @command{texi2any} and @command{makeinfo} generate Info output; |
| 15361 @end display | 16897 indeed, there are no differences in behavior based on the name. |
| 15362 | 16898 |
| 15363 Many other @TeX{} distributions are available; see | 16899 Beside these default formats, command line options to |
| 15364 @uref{http://tug.org/}. | 16900 @command{texi2any} can change many aspects of the output. Beyond |
| 15365 | 16901 that, initialization files provide even more control over the final |
| 15366 | 16902 output---nearly anything not specified in the Texinfo input file. |
| 15367 @node Creating and Installing Info Files | 16903 Initialization files are written in Perl, like the main program, and |
| 15368 @chapter Creating and Installing Info Files | 16904 anything which can be specified on the command line can also be |
| 15369 | 16905 specified within a initialization file. |
| 15370 This chapter describes how to create and install Info files. @xref{Info | 16906 |
| 15371 Files}, for general information about the file format itself. | 16907 The rest of this chapter goes into the details. |
| 15372 | 16908 |
| 15373 @menu | 16909 @menu |
| 15374 * Creating an Info File:: | 16910 * Reference Implementation:: @command{texi2any}: the reference implementation. |
| 15375 * Installing an Info File:: | 16911 * Invoking @t{texi2any}:: Running the translator from a shell. |
| 16912 * @t{texi2any} Printed Output:: Calling @command{texi2dvi}. | |
| 16913 * Pointer Validation:: How to check that pointers point somewhere. | |
| 16914 * Customization Variables:: Configuring @command{texi2any}. | |
| 16915 * Internationalization of Document Strings:: Translating program-inserted text. | |
| 16916 * Invoking @t{pod2texi}:: Translating Perl pod to Texinfo. | |
| 16917 * @t{texi2html}:: An ancestor of @command{texi2any}. | |
| 15376 @end menu | 16918 @end menu |
| 15377 | 16919 |
| 15378 | 16920 |
| 15379 @node Creating an Info File | 16921 @node Reference Implementation |
| 15380 @section Creating an Info File | 16922 @section @command{texi2any}: A Texinfo Reference Implementation |
| 15381 @cindex Creating an Info file | 16923 |
| 15382 @cindex Info, creating an online file | 16924 @cindex @command{texi2any}, as reference implementation |
| 15383 @cindex Formatting a file for Info | 16925 @cindex Reference implementation |
| 15384 | 16926 @cindex Implementation, @command{texi2any} as reference |
| 15385 @code{makeinfo} is a program that converts a Texinfo file into an Info | 16927 |
| 15386 file, HTML file, or plain text. @code{texinfo-format-region} and | 16928 Above, we called @command{texi2any} ``the'' translator for Texinfo |
| 15387 @code{texinfo-format-buffer} are XEmacs functions that convert | 16929 instead of just ``a'' translator, even though (of course) it's |
| 15388 Texinfo to Info. | 16930 technically and legally possible for other implementations to be |
| 15389 | 16931 written. The reason is that alternative implementations are very |
| 15390 For information on installing the Info file in the Info system, | 16932 likely to have subtle, or not-so-subtle, differences in behavior, and |
| 15391 @pxref{Installing an Info File}. | 16933 thus Texinfo documents would become dependent on the processor. |
| 15392 | 16934 Therefore, it is important to have a reference implementation that |
| 15393 @menu | 16935 defines parts of the language not fully specified by the manual (often |
| 15394 * makeinfo advantages:: @code{makeinfo} provides better error checking. | 16936 intentionally so). It is equally important to have consistent |
| 15395 * Invoking makeinfo:: How to run @code{makeinfo} from a shell. | 16937 command-line options and other behavior for all processors. |
| 15396 * makeinfo options:: Specify fill-column and other options. | 16938 |
| 15397 * Pointer Validation:: How to check that pointers point somewhere. | 16939 @cindex Tree representation of documents |
| 15398 * makeinfo in XEmacs:: How to run @code{makeinfo} from XEmacs. | 16940 @cindex Syntax tree representation of documents |
| 15399 * texinfo-format commands:: Two Info formatting commands written | 16941 @cindex Abstract syntax tree representation of documents |
| 15400 in XEmacs Lisp are an alternative | 16942 For this reason, the once-independent @command{texi2html} Perl Texinfo |
| 15401 to @code{makeinfo}. | 16943 processor was made compatible with the C implementation of |
| 15402 * Batch Formatting:: How to format for Info in XEmacs Batch mode. | 16944 @command{makeinfo}, to avoid continuing with two different |
| 15403 * Tag and Split Files:: How tagged and split files help Info | 16945 implementations (@pxref{History}). The current implementation, |
| 15404 to run better. | 16946 @command{texi2any}, serves as the reference implementation. It |
| 15405 @end menu | 16947 inherited the design of customization and other features from |
| 15406 | 16948 @command{texi2html} (for more on @command{texi2html} compatibility, |
| 15407 | 16949 @pxref{@t{texi2html}}). However, @code{texi2any} is a full |
| 15408 @node makeinfo advantages | 16950 reimplementation: it constructs a tree-based representation of the |
| 15409 @subsection @code{makeinfo} Preferred | 16951 input document for all back-ends to work from. |
| 15410 | 16952 |
| 15411 The @code{makeinfo} utility creates an Info file from a Texinfo source | 16953 @cindex Texinfo language tests |
| 15412 file more quickly than either of the XEmacs formatting commands and | 16954 @cindex Tests, of Texinfo language |
| 15413 provides better error messages. We recommend it. @code{makeinfo} is a | 16955 Extensive tests of the language were developed at the same time as |
| 15414 C program that is independent of XEmacs. You do not need to run XEmacs to | 16956 @command{texi2any}; we plead with anyone thinking of writing a program |
| 15415 use @code{makeinfo}, which means you can use @code{makeinfo} on machines | 16957 to parse Texinfo input to at least make use of these tests. |
| 15416 that are too small to run XEmacs. You can run @code{makeinfo} in any one | 16958 |
| 15417 of three ways: from an operating system shell, from a shell inside | 16959 @cindex Examples of using @command{texi2any} |
| 15418 XEmacs, or by typing the @kbd{C-c C-m C-r} or the @kbd{C-c C-m C-b} | 16960 @findex Texinfo::Parser module |
| 15419 command in Texinfo mode in XEmacs. | 16961 The @command{texi2html} wrapper script (@pxref{@t{texi2html}}) |
| 15420 | 16962 provides a very simple example of calling @command{texi2any} from a |
| 15421 The @code{texinfo-format-region} and the @code{texinfo-format-buffer} | 16963 shell script; it's in @file{util/texi2html} in the Texinfo sources. |
| 15422 commands are useful if you cannot run @code{makeinfo}. Also, in some | 16964 More consequentially, @command{texi-elements-by-size} is an example |
| 15423 circumstances, they format short regions or buffers more quickly than | 16965 Perl script using the @code{Texinfo::Parser} module interface; it's |
| 15424 @code{makeinfo}. | 16966 also in the @file{util} source directory. (Its functionality may also |
| 15425 | 16967 be useful to authors; @pxref{texi-elements-by-size}.) |
| 15426 | 16968 |
| 15427 @node Invoking makeinfo | 16969 @cindex Future of Texinfo implementations |
| 15428 @subsection Running @code{makeinfo} from a Shell | 16970 With the release of @command{texi2any} as the reference |
| 16971 implementation, development of both the C implementation of | |
| 16972 @command{makeinfo} and @command{texi2html} has been halted. Going | |
| 16973 forward, we ask authors of Texinfo documents to use only | |
| 16974 @command{texi2any}. | |
| 16975 | |
| 16976 | |
| 16977 @node Invoking @t{texi2any} | |
| 16978 @section Invoking @command{texi2any}/@code{makeinfo} from a Shell | |
| 16979 | |
| 16980 @anchor{Invoking makeinfo} | |
| 15429 @pindex makeinfo | 16981 @pindex makeinfo |
| 15430 | 16982 @pindex texi2any |
| 15431 To create an Info file from a Texinfo file, invoke @command{makeinfo} | 16983 |
| 15432 followed by the name of the Texinfo file. Thus, to create the Info | 16984 To process a Texinfo file, invoke @command{texi2any} or |
| 15433 file for Bison, type the following to the shell: | 16985 @command{makeinfo} (the two names are synonyms for the same program; |
| 15434 | 16986 we'll use the names interchangeably) followed by the name of the |
| 15435 @example | 16987 Texinfo file. Also select the format you want to output with the |
| 15436 makeinfo bison.texinfo | 16988 appropriate command line option (default is Info). Thus, to create |
| 15437 @end example | 16989 the Info file for Bison, type the following to the shell: |
| 15438 | 16990 |
| 15439 (You can run a shell inside XEmacs by typing @kbd{M-x shell}.) | 16991 @example |
| 15440 | 16992 texi2any --info bison.texinfo |
| 15441 @command{makeinfo} has many options to control its actions and output; | 16993 @end example |
| 15442 see the next section. | 16994 |
| 15443 | 16995 You can specify more than one input file name; each is processed in |
| 15444 You can give @command{makeinfo} more than one input file name; each is | 16996 turn. If an input file name is @samp{-}, standard input is read. |
| 15445 processed in turn. If an input file name is @samp{-}, or no input | 16997 |
| 15446 file names are given at all, standard input is read. | 16998 @anchor{@t{makeinfo} Options} |
| 15447 | 16999 @c anchor{makeinfo options}@c prev name, but case-insensitive clash |
| 15448 | |
| 15449 @node makeinfo options | |
| 15450 @subsection Options for @code{makeinfo} | |
| 15451 @cindex @code{makeinfo} options | 17000 @cindex @code{makeinfo} options |
| 15452 @cindex Options for @code{makeinfo} | 17001 @cindex Options for @code{makeinfo} |
| 15453 | 17002 @anchor{texi2any Options} |
| 15454 The @command{makeinfo} program accepts many options. Perhaps the most | 17003 @cindex @code{texi2any} options |
| 15455 commonly needed are those that change the output format. By default, | 17004 @cindex Options for @code{texi2any} |
| 15456 @command{makeinfo} outputs Info files. | 17005 |
| 15457 | 17006 The @command{texi2any} program accept many options. Perhaps the |
| 15458 Each command line option is a word preceded by @samp{--} or a letter | 17007 most basic are those that change the output format. By default, |
| 15459 preceded by @samp{-}. You can use abbreviations for the long option | 17008 @command{texi2any} outputs Info. |
| 15460 names as long as they are unique. | 17009 |
| 15461 | 17010 Each command line option is either a long name preceded by @samp{--} |
| 15462 For example, you could use the following shell command to create an Info | 17011 or a single letter preceded by @samp{-}. You can use abbreviations |
| 15463 file for @file{bison.texinfo} in which each line is filled to only 68 | 17012 for the long option names as long as they are unique. |
| 15464 columns: | 17013 |
| 15465 | 17014 For example, you could use the following shell command to create an |
| 15466 @example | 17015 Info file for @file{bison.texinfo} in which lines are filled to only |
| 15467 makeinfo --fill-column=68 bison.texinfo | 17016 68 columns: |
| 15468 @end example | 17017 |
| 15469 | 17018 @example |
| 15470 You can write two or more options in sequence, like this:@refill | 17019 texi2any --fill-column=68 bison.texinfo |
| 15471 | 17020 @end example |
| 15472 @example | 17021 |
| 15473 makeinfo --no-split --fill-column=70 @dots{} | 17022 You can write two or more options in sequence, like this: |
| 15474 @end example | 17023 |
| 15475 | 17024 @example |
| 15476 @noindent | 17025 texi2any --no-split --fill-column=70 @dots{} |
| 15477 This would keep the Info file together as one possibly very long | 17026 @end example |
| 15478 file and would also set the fill column to 70. | 17027 |
| 15479 | 17028 @noindent |
| 15480 The options are: | 17029 (This would keep the Info file together as one possibly very long |
| 17030 file and would also set the fill column to 70.) | |
| 17031 | |
| 17032 The options are (approximately in alphabetical order): | |
| 15481 | 17033 |
| 15482 @table @code | 17034 @table @code |
| 17035 @item --commands-in-node-names | |
| 17036 @opindex --commands-in-node-names | |
| 17037 This option now does nothing, but remains for compatibility. (It used | |
| 17038 to ensure that @@-commands in node names were expanded throughout the | |
| 17039 document, especially @code{@@value}. This is now done by default.) | |
| 17040 | |
| 17041 @item --conf-dir=@var{path} | |
| 17042 @opindex --conf-dir=@var{path} | |
| 17043 Prepend @var{path} to the directory search list for finding | |
| 17044 customization files that may be loaded with @option{--init-file} (see | |
| 17045 below). The @var{path} value can be a single directory, or a list of | |
| 17046 several directories separated by the usual path separator character | |
| 17047 (@samp{:} on Unix-like systems, @samp{;} on Windows). @c @xref{Loading | |
| 17048 @c Init Files}. | |
| 17049 | |
| 17050 @item --css-include=@var{file} | |
| 17051 @opindex --css-include | |
| 17052 When producing HTML, literally include the contents of @var{file}, | |
| 17053 which should contain W3C cascading style sheets specifications, in the | |
| 17054 @samp{<style>} block of the HTML output. If @var{file} is @samp{-}, | |
| 17055 read standard input. @xref{HTML CSS}. | |
| 17056 | |
| 17057 @item --css-ref=@var{url} | |
| 17058 @opindex --css-ref | |
| 17059 When producing HTML, add a @samp{<link>} tag to the output which | |
| 17060 references a cascading style sheet at @var{url}. This allows using | |
| 17061 standalone style sheets. | |
| 15483 | 17062 |
| 15484 @item -D @var{var} | 17063 @item -D @var{var} |
| 15485 @opindex -D @var{var} | 17064 @opindex -D @var{var} |
| 15486 Cause the variable @var{var} to be defined. This is equivalent to | 17065 Cause the Texinfo variable @var{var} to be defined. This is |
| 15487 @code{@@set @var{var}} in the Texinfo file (@pxref{set clear value}). | 17066 equivalent to @code{@@set @var{var}} in the Texinfo file |
| 15488 | 17067 (@pxref{@t{@@set @@clear @@value}}). |
| 15489 @item --commands-in-node-names | |
| 15490 @opindex --commands-in-node-names | |
| 15491 Allow @code{@@}-commands in node names. This is not recommended, as it | |
| 15492 can probably never be implemented in @TeX{}. It also makes | |
| 15493 @code{makeinfo} much slower. Also, this option is ignored when | |
| 15494 @samp{--no-validate} is used. @xref{Pointer Validation}, for more | |
| 15495 details. | |
| 15496 | |
| 15497 @item --css-include=@var{file} | |
| 15498 @opindex --css-include | |
| 15499 Include the contents of @var{file}, which should contain cascading | |
| 15500 style sheets specifications, in the @samp{<style>} block of the HTML | |
| 15501 output. @xref{HTML CSS}. If @var{file} is @samp{-}, read standard | |
| 15502 input. | |
| 15503 | |
| 15504 @item --css-ref=@var{url} | |
| 15505 @opindex --css-ref | |
| 15506 In HTML mode, add a @samp{<link>} tag to the HTML output which | |
| 15507 references a cascading style sheet at @var{url}. This allows using | |
| 15508 standalone style sheets. | |
| 15509 | 17068 |
| 15510 @item --disable-encoding | 17069 @item --disable-encoding |
| 15511 @itemx --enable-encoding | 17070 @itemx --enable-encoding |
| 15512 @opindex --disable-encoding | 17071 @opindex --disable-encoding |
| 15513 @opindex --enable-encoding | 17072 @opindex --enable-encoding |
| 15514 By default, or with @option{--enable-encoding}, output accented and | 17073 By default, or with @option{--enable-encoding}, output accented and |
| 15515 special characters in Info or plain text output based on | 17074 special characters in Info and plain text output based on |
| 15516 @samp{@@documentencoding}. With @option{--disable-encoding}, 7-bit | 17075 @samp{@@documentencoding}. With @option{--disable-encoding}, 7-bit |
| 15517 ASCII transliterations are output. | 17076 ASCII transliterations are output. @xref{@t{@@documentencoding}}, |
| 15518 @xref{documentencoding,,@code{documentencoding}}, and @ref{Inserting | 17077 and @ref{Inserting Accents}. |
| 15519 Accents}. | |
| 15520 | 17078 |
| 15521 @item --docbook | 17079 @item --docbook |
| 15522 @opindex --docbook | 17080 @opindex --docbook |
| 15523 Generate Docbook output rather than Info. | 17081 Generate Docbook output (rather than Info). |
| 15524 | 17082 |
| 15525 @item --document-language=@var{lang} | 17083 @item --document-language=@var{lang} |
| 15526 @opindex --document-language | 17084 @opindex --document-language |
| 15527 @vindex LANG | |
| 15528 Use @var{lang} to translate Texinfo keywords which end up in the | 17085 Use @var{lang} to translate Texinfo keywords which end up in the |
| 15529 output document. The default is the locale specified by the | 17086 output document. The default is the locale specified by the |
| 15530 @code{@@documentlanguage} command if there is one | 17087 @code{@@documentlanguage} command if there is one, otherwise English |
| 15531 (@pxref{documentlanguage}). | 17088 (@pxref{@t{@@documentlanguage}}). |
| 17089 | |
| 17090 @item --dvi | |
| 17091 @opindex --dvi | |
| 17092 Generate a TeX DVI file using @command{texi2dvi}, rather than Info | |
| 17093 (@pxref{@t{texi2any} Printed Output}). | |
| 17094 | |
| 17095 @item --dvipdf | |
| 17096 @opindex --dvipdf | |
| 17097 Generate a PDF file using @command{texi2dvi --dvipdf}, rather than | |
| 17098 Info (@pxref{@t{texi2any} Printed Output}). | |
| 15532 | 17099 |
| 15533 @item --error-limit=@var{limit} | 17100 @item --error-limit=@var{limit} |
| 15534 @itemx -e @var{limit} | 17101 @itemx -e @var{limit} |
| 15535 @opindex --error-limit=@var{limit} | 17102 @opindex --error-limit=@var{limit} |
| 15536 @opindex -e @var{limit} | 17103 @opindex -e @var{limit} |
| 15537 Set the maximum number of errors that @code{makeinfo} will report | 17104 Report @var{LIMIT} errors before aborting (on the assumption that |
| 15538 before exiting (on the assumption that continuing would be useless); | 17105 continuing would be useless); default 100. |
| 15539 default 100. | |
| 15540 | 17106 |
| 15541 @item --fill-column=@var{width} | 17107 @item --fill-column=@var{width} |
| 15542 @itemx -f @var{width} | 17108 @itemx -f @var{width} |
| 15543 @opindex --fill-column=@var{width} | 17109 @opindex --fill-column=@var{width} |
| 15544 @opindex -f @var{width} | 17110 @opindex -f @var{width} |
| 15545 Specify the maximum number of columns in a line; this is the right-hand | 17111 Specify the maximum number of columns in a line; this is the |
| 15546 edge of a line. Paragraphs that are filled will be filled to this | 17112 right-hand edge of a line. Paragraphs that are filled will be filled |
| 15547 width. (Filling is the process of breaking up and connecting lines so | 17113 to this width. (Filling is the process of breaking up and connecting |
| 15548 that lines are the same length as or shorter than the number specified | 17114 lines so that lines are the same length as or shorter than the number |
| 15549 as the fill column. Lines are broken between words.) The default value | 17115 specified as the fill column. Lines are broken between words.) The |
| 15550 is 72. Ignored with @samp{--html}. | 17116 default value is 72. |
| 15551 | 17117 |
| 15552 @item --footnote-style=@var{style} | 17118 @item --footnote-style=@var{style} |
| 15553 @itemx -s @var{style} | 17119 @itemx -s @var{style} |
| 15554 @opindex --footnote-style=@var{style} | 17120 @opindex --footnote-style=@var{style} |
| 15555 @opindex -s @var{style} | 17121 @opindex -s @var{style} |
| 15556 Set the footnote style to @var{style}, either @samp{end} for the end | 17122 Set the footnote style to @var{style}: either @samp{end} for the end |
| 15557 node style (the default) or @samp{separate} for the separate node style. | 17123 node style (the default) or @samp{separate} for the separate node |
| 15558 The value set by this option overrides the value set in a Texinfo file | 17124 style. The value set by this option overrides the value set in a |
| 15559 by an @code{@@footnotestyle} command (@pxref{Footnotes}). When the | 17125 Texinfo file by an @code{@@footnotestyle} command (@pxref{Footnote |
| 15560 footnote style is @samp{separate}, @code{makeinfo} makes a new node | 17126 Styles}). |
| 15561 containing the footnotes found in the current node. When the footnote | 17127 |
| 15562 style is @samp{end}, @code{makeinfo} places the footnote references at | 17128 When the footnote style is @samp{separate}, @code{makeinfo} makes a |
| 15563 the end of the current node. Ignored with @samp{--html}. | 17129 new node containing the footnotes found in the current node. When the |
| 17130 footnote style is @samp{end}, @code{makeinfo} places the footnote | |
| 17131 references at the end of the current node. | |
| 17132 | |
| 17133 In HTML, when the footnote style is @samp{end}, or if the output is | |
| 17134 not split, footnotes are put at the end of the output. If set to | |
| 17135 @samp{separate}, and the output is split, they are placed in a | |
| 17136 separate file. | |
| 15564 | 17137 |
| 15565 @item --force | 17138 @item --force |
| 15566 @itemx -F | 17139 @itemx -F |
| 15567 @opindex --force | 17140 @opindex --force |
| 15568 @opindex -F | 17141 @opindex -F |
| 15569 Ordinarily, if the input file has errors, the output files are not | 17142 Ordinarily, if the input file has errors, the output files are not |
| 15570 created. With this option, they are preserved. | 17143 created. With this option, they are preserved. |
| 15571 | 17144 |
| 15572 @item --help | 17145 @item --help |
| 15573 @itemx -h | 17146 @itemx -h |
| 15574 @opindex --help | 17147 @opindex --help@r{, for @command{texi2any}} |
| 15575 @opindex -h | 17148 @opindex -h |
| 15576 Print a usage message listing all available options, then exit successfully. | 17149 Print a message with available options and basic usage, then exit |
| 17150 successfully. | |
| 15577 | 17151 |
| 15578 @item --html | 17152 @item --html |
| 15579 @opindex --html | 17153 @opindex --html |
| 15580 Generate HTML output rather than Info. @xref{Generating HTML}. By | 17154 Generate HTML output (rather than Info). By default, the HTML output |
| 15581 default, the HTML output is split into one output file per Texinfo | 17155 is split into one output file per Texinfo source node, and the split |
| 15582 source node, and the split output is written into a subdirectory with | 17156 output is written into a subdirectory based on the name of the |
| 15583 the name of the top-level info file. | 17157 top-level Info file. @xref{Generating HTML}. |
| 15584 | 17158 |
| 15585 @item -I @var{dir} | 17159 @item -I @var{path} |
| 15586 @opindex -I @var{dir} | 17160 @opindex -I @var{path} |
| 15587 Append @var{dir} to the directory search list for finding files that | 17161 Append @var{path} to the directory search list for finding files that |
| 15588 are included using the @code{@@include} command. By default, | 17162 are included using the @code{@@include} command. By default, |
| 15589 @code{makeinfo} searches only the current directory. If @var{dir} is | 17163 @code{texi2any} searches only the current directory. If @var{path} is |
| 15590 not given, the current directory @file{.} is appended. Note that | 17164 not given, the current directory is appended. The @var{path} value |
| 15591 @var{dir} can actually be a list of several directories separated by the | 17165 can be a single directory or a list of several directories separated |
| 15592 usual path separator character (@samp{:} on Unix, @samp{;} on | 17166 by the usual path separator character (@samp{:} on Unix-like systems, |
| 15593 MS-DOS/MS-Windows). | 17167 @samp{;} on Windows). |
| 15594 | 17168 |
| 15595 @item --ifdocbook | 17169 @item --ifdocbook |
| 15596 @opindex --ifdocbook | 17170 @opindex --ifdocbook |
| 15597 @itemx --ifhtml | 17171 @itemx --ifhtml |
| 15598 @opindex --ifhtml | 17172 @opindex --ifhtml |
| 15602 @opindex --ifplaintext | 17176 @opindex --ifplaintext |
| 15603 @itemx --iftex | 17177 @itemx --iftex |
| 15604 @opindex --iftex | 17178 @opindex --iftex |
| 15605 @itemx --ifxml | 17179 @itemx --ifxml |
| 15606 @opindex --ifxml | 17180 @opindex --ifxml |
| 15607 For the specified format, process @samp{@@if@var{format}} and | 17181 For the given format, process @samp{@@if@var{format}} and |
| 15608 @samp{@@@var{format}} commands even if not generating the given output | 17182 @samp{@@@var{format}} commands, and do not process |
| 15609 format. For instance, if @option{--iftex} is specified, then | 17183 @samp{@@ifnot@var{format}}, regardless of the format being output. |
| 15610 @samp{@@iftex} and @samp{@@tex} blocks will be read. | 17184 For instance, if @option{--iftex} is given, then @samp{@@iftex} and |
| 15611 | 17185 @samp{@@tex} blocks will be read, and @samp{@@ifnottex} blocks will be |
| 15612 @item --internal-links=@var{file} | 17186 ignored. |
| 17187 | |
| 17188 @item --info | |
| 17189 @opindex --info | |
| 17190 Generate Info output. By default, if the output file contains more | |
| 17191 than about 300,000 bytes, it is split into shorter subfiles of about | |
| 17192 that size. The name of the output file and any subfiles is determined | |
| 17193 by @code{@@setfilename} (@pxref{@t{@@setfilename}}). @xref{Tag and | |
| 17194 Split Files}. | |
| 17195 | |
| 17196 @item --init-file=@var{file} | |
| 17197 @opindex --init-file=@var{file} | |
| 17198 Load @var{file} as code to modify the behavior and output of the | |
| 17199 generated manual. It is customary to use the @code{.pm} or the | |
| 17200 @code{.init} extensions for these customization files, but that is not | |
| 17201 enforced; the @var{file} name can be anything. The | |
| 17202 @option{--conf-dir} option (see above) can be used to add to the list | |
| 17203 of directories in which these customization files are searched for. | |
| 17204 @c @xref{Loading Init Files}. | |
| 17205 | |
| 17206 @item --internal-links=@var{file} | |
| 15613 @opindex --internal-links=@var{file} | 17207 @opindex --internal-links=@var{file} |
| 15614 In HTML mode, output a tab separated file containing three columns: | 17208 @cindex Internal links, of HTML |
| 15615 the internal link to an indexed item or item in the table of contents, | 17209 In HTML mode, output a tab-separated file containing three columns: |
| 15616 the name of the index (or "toc") in which it occurs, and the term | 17210 the internal link to an indexed item or item in the table of contents, |
| 15617 which was indexed or entered. | 17211 the name of the index (or table of contents) in which it occurs, and |
| 17212 the term which was indexed or entered. The items are in the natural | |
| 17213 sorting order for the given element. This dump can be useful for | |
| 17214 post-processors. | |
| 15618 | 17215 |
| 15619 @item --macro-expand=@var{file} | 17216 @item --macro-expand=@var{file} |
| 15620 @itemx -E @var{file} | 17217 @itemx -E @var{file} |
| 15621 @opindex --macro-expand=@var{file} | 17218 @opindex --macro-expand=@var{file} |
| 15622 @opindex -E @var{file} | 17219 @opindex -E @var{file} |
| 15623 Output the Texinfo source with all the macros expanded to the named | 17220 Output the Texinfo source, with all Texinfo macros expanded, to |
| 15624 file. Normally, the results of macro expansion are used internally by | 17221 @var{file}. Normally, the result of macro expansion is used |
| 15625 @code{makeinfo} and then discarded. This option is used by | 17222 internally by @code{makeinfo} and then discarded. |
| 15626 @command{texi2dvi}. | |
| 15627 | 17223 |
| 15628 @item --no-headers | 17224 @item --no-headers |
| 15629 @item --plaintext | |
| 15630 @opindex --no-headers | 17225 @opindex --no-headers |
| 15631 @opindex --plaintext | 17226 @cindex Node separators, omitting with @option{--no-headers} |
| 15632 @cindex Plain text output | 17227 @cindex Generating plain text files with @option{--no-headers} |
| 15633 @cindex ASCII text output | 17228 @cindex Menus, omitting with @option{--no-headers} |
| 15634 @cindex Generating plain text files | 17229 Do not include menus or node separator lines in the output. |
| 15635 @cindex @file{INSTALL} file, generating | 17230 |
| 15636 @cindex Node separators, omitting | 17231 When generating Info, this is the same as using @option{--plaintext}, |
| 15637 @cindex Menus, omitting | 17232 resulting in a simple plain text file. Furthermore, |
| 15638 Do not include menus or node separator lines in the output, and | 17233 @code{@@setfilename} is ignored, and output is to standard output |
| 15639 implicitly @option{--enable-encoding} (see above). This results in a | 17234 unless overridden with @option{-o}. (This behavior is for backward |
| 15640 simple plain text file that you can (for example) send in email | 17235 compatibility.) |
| 15641 without complications, or include in a distribution (as in an | |
| 15642 @file{INSTALL} file). | |
| 15643 | 17236 |
| 15644 @cindex Navigation links, omitting | 17237 @cindex Navigation links, omitting |
| 15645 For HTML output, likewise omit menus. And if @samp{--no-split} is also | 17238 When generating HTML, and output is split, also output navigation |
| 15646 specified, do not include a navigation links at the top of each node | 17239 links only at the beginning of each file. If output is not split, do |
| 15647 (these are never included in the default case of split output). | 17240 not include navigation links at the top of each node at all. |
| 15648 @xref{Generating HTML}. | 17241 @xref{Generating HTML}. |
| 15649 | |
| 15650 In both cases, ignore @code{@@setfilename} and write to standard | |
| 15651 output by default---can be overridden with @option{-o}. | |
| 15652 | 17242 |
| 15653 @item --no-ifdocbook | 17243 @item --no-ifdocbook |
| 15654 @opindex --no-ifdocbook | 17244 @opindex --no-ifdocbook |
| 15655 @itemx --no-ifhtml | 17245 @itemx --no-ifhtml |
| 15656 @opindex --no-ifhtml | 17246 @opindex --no-ifhtml |
| 15660 @opindex --no-ifplaintext | 17250 @opindex --no-ifplaintext |
| 15661 @itemx --no-iftex | 17251 @itemx --no-iftex |
| 15662 @opindex --no-iftex | 17252 @opindex --no-iftex |
| 15663 @itemx --no-ifxml | 17253 @itemx --no-ifxml |
| 15664 @opindex --no-ifxml | 17254 @opindex --no-ifxml |
| 15665 Do not process @samp{@@if@var{format}} and @samp{@@@var{format}} | 17255 For the given format, do not process @samp{@@if@var{format}} and |
| 15666 commands, and do process @samp{@@ifnot@var{format}}, even if | 17256 @samp{@@@var{format}} commands, and do process |
| 15667 generating the given format. For instance, if @option{--no-ifhtml} is | 17257 @samp{@@ifnot@var{format}}, regardless of the format being output. |
| 15668 specified, then @samp{@@ifhtml} and @samp{@@html} blocks will not be | 17258 For instance, if @option{--no-ifhtml} is given, then @samp{@@ifhtml} |
| 15669 read, and @samp{@@ifnothtml} blocks will be. | 17259 and @samp{@@html} blocks will not be read, and @samp{@@ifnothtml} |
| 17260 blocks will be. | |
| 17261 | |
| 17262 @item --no-node-files | |
| 17263 @itemx --node-files | |
| 17264 @opindex --no-node-files | |
| 17265 @opindex --node-files | |
| 17266 When generating HTML, create redirection files for anchors and any | |
| 17267 nodes not already output with the file name corresponding to the node | |
| 17268 name (@pxref{HTML Xref Node Name Expansion}). This makes it possible | |
| 17269 for section- and chapter-level cross-manual references to succeed | |
| 17270 (@pxref{HTML Xref Configuration}). | |
| 17271 | |
| 17272 If the output is split, this is enabled by default. If the output is | |
| 17273 not split, @option{--node-files} enables the creation of the | |
| 17274 redirection files, in addition to the monolithic main output file. | |
| 17275 @option{--no-node-files} suppresses the creation of redirection files | |
| 17276 in any case. This option has no effect with any output format other | |
| 17277 than HTML@. @xref{Generating HTML}. | |
| 15670 | 17278 |
| 15671 @item --no-number-footnotes | 17279 @item --no-number-footnotes |
| 15672 @opindex --no-number-footnotes | 17280 @opindex --no-number-footnotes |
| 15673 Suppress automatic footnote numbering. By default, @code{makeinfo} | 17281 Suppress automatic footnote numbering. By default, footnotes are |
| 15674 numbers each footnote sequentially in a single node, resetting the | 17282 numbered sequentially within a node, i.e., the current footnote number |
| 15675 current footnote number to 1 at the start of each node. | 17283 is reset to 1 at the start of each node. |
| 15676 | 17284 |
| 15677 @item --no-number-sections | 17285 @item --no-number-sections |
| 17286 @itemx --number-sections | |
| 15678 @opindex --no-number-sections | 17287 @opindex --no-number-sections |
| 15679 Do not output chapter, section, and appendix numbers. | 17288 @opindex --number-sections |
| 15680 You need to specify this if your manual is not hierarchically-structured. | 17289 With @option{--number_sections} (the default), output chapter, |
| 15681 | 17290 section, and appendix numbers as in printed manuals. This works only |
| 15682 @item --no-split | 17291 with hierarchically-structured manuals. You should specify |
| 15683 @opindex --no-split | 17292 @code{--no-number-sections} if your manual is not normally structured. |
| 15684 @cindex Splitting of output files | |
| 15685 @cindex Output file splitting | |
| 15686 Suppress the splitting stage of @code{makeinfo}. By default, large | |
| 15687 output files (where the size is greater than 70k bytes) are split into | |
| 15688 smaller subfiles. For Info output, each one is approximately 50k bytes. | |
| 15689 For HTML output, each file contains one node (@pxref{Generating HTML}). | |
| 15690 | 17293 |
| 15691 @item --no-pointer-validate | 17294 @item --no-pointer-validate |
| 15692 @itemx --no-validate | 17295 @itemx --no-validate |
| 15693 @opindex --no-pointer-validate | 17296 @opindex --no-pointer-validate |
| 15694 @opindex --no-validate | 17297 @opindex --no-validate |
| 15695 @cindex Pointer validation, suppressing | 17298 @cindex Pointer validation, suppressing from command line |
| 15696 Suppress the pointer-validation phase of @code{makeinfo}---a dangerous | 17299 Suppress the pointer-validation phase of @code{makeinfo}---a dangerous |
| 15697 thing to do. This can also be done with the @code{@@novalidate} | 17300 thing to do. This can also be done with the @code{@@novalidate} |
| 15698 command (@pxref{Use TeX,,Use @TeX{}}). Normally, after a Texinfo file | 17301 command (@pxref{Use @TeX{}}). Normally, consistency checks are made |
| 15699 is processed, some consistency checks are made to ensure that cross | 17302 to ensure that cross references can be resolved, etc. @xref{Pointer |
| 15700 references can be resolved, etc. @xref{Pointer Validation}. | 17303 Validation}. |
| 15701 | 17304 |
| 15702 @item --no-warn | 17305 @item --no-warn |
| 15703 @opindex --no-warn | 17306 @opindex --no-warn |
| 15704 Suppress warning messages (but @emph{not} error messages). | 17307 Suppress warning messages (but not error messages). |
| 15705 | |
| 15706 @item --number-sections | |
| 15707 @opindex --number-sections | |
| 15708 Output chapter, section, and appendix numbers as in printed manuals. | |
| 15709 This is the default. It works only with hierarchically-structured | |
| 15710 manuals. | |
| 15711 | 17308 |
| 15712 @item --output=@var{file} | 17309 @item --output=@var{file} |
| 15713 @itemx -o @var{file} | 17310 @itemx -o @var{file} |
| 15714 @opindex --output=@var{file} | 17311 @opindex --output=@var{file} |
| 15715 @opindex -o @var{file} | 17312 @opindex -o @var{file} |
| 15716 Specify that the output should be directed to @var{file} and not to the | 17313 Specify that the output should be directed to @var{file}. This |
| 15717 file name specified in the @code{@@setfilename} command found in the | 17314 overrides any file name specified in an @code{@@setfilename} command |
| 15718 Texinfo source (@pxref{setfilename}). If @var{file} is @samp{-}, output | 17315 found in the Texinfo source. If neither @code{@@setfilename} nor this |
| 15719 goes to standard output and @samp{--no-split} is implied. For split | 17316 option are specified, the input file name is used to determine the |
| 15720 HTML output, @var{file} is the name for the directory into which all | 17317 output name. @xref{@t{@@setfilename}}. |
| 15721 HTML nodes are written (@pxref{Generating HTML}). | 17318 |
| 15722 | 17319 If @var{file} is @samp{-}, output goes to standard output and |
| 15723 @item -P @var{dir} | 17320 @samp{--no-split} is implied. |
| 15724 @opindex -P @var{dir} | 17321 |
| 15725 Prepend @var{dir} to the directory search list for @code{@@include}. | 17322 If @var{file} is a directory or ends with a @samp{/} the usual rules |
| 15726 If @var{dir} is not given, the current directory @file{.} is prepended. | 17323 are used to determine the output file name (namely, use |
| 15727 See @samp{-I} for more details. | 17324 @code{@@setfilename} or the input file name) but the files are written |
| 17325 to the @var{file} directory. For example, @samp{makeinfo -o bar/ | |
| 17326 foo.texi}, with or without @option{--no-split}, will write | |
| 17327 @file{bar/foo.info}, and possibly other files, under @file{bar/}. | |
| 17328 | |
| 17329 When generating HTML and output is split, @var{file} is used as the | |
| 17330 name for the directory into which all files are written. For example, | |
| 17331 @samp{makeinfo -o bar --html foo.texi} will write | |
| 17332 @file{bar/index.html}, among other files. | |
| 17333 | |
| 17334 @item --output-indent=@var{val} | |
| 17335 @opindex --outputindent | |
| 17336 This option now does nothing, but remains for compatibility. (It used | |
| 17337 to alter indentation in XML/Docbook output.) | |
| 17338 | |
| 17339 @item -P @var{path} | |
| 17340 @opindex -P @var{path} | |
| 17341 Prepend @var{path} to the directory search list for @code{@@include}. | |
| 17342 If @var{path} is not given, the current directory is prepended. See | |
| 17343 @samp{-I} above. | |
| 15728 | 17344 |
| 15729 @item --paragraph-indent=@var{indent} | 17345 @item --paragraph-indent=@var{indent} |
| 15730 @itemx -p @var{indent} | 17346 @itemx -p @var{indent} |
| 15731 @opindex --paragraph-indent=@var{indent} | 17347 @opindex --paragraph-indent=@var{indent} |
| 15732 @opindex -p @var{indent} | 17348 @opindex -p @var{indent} |
| 15733 Set the paragraph indentation style to @var{indent}. The value set by | 17349 Set the paragraph indentation style to @var{indent}. The value set by |
| 15734 this option overrides the value set in a Texinfo file by an | 17350 this option overrides the value set in a Texinfo file by an |
| 15735 @code{@@paragraphindent} command (@pxref{paragraphindent}). The value | 17351 @code{@@paragraphindent} command (@pxref{@t{@@paragraphindent}}). |
| 15736 of @var{indent} is interpreted as follows: | 17352 The value of @var{indent} is interpreted as follows: |
| 15737 | 17353 |
| 15738 @table @asis | 17354 @table @asis |
| 15739 @item @samp{asis} | 17355 @item @samp{asis} |
| 15740 Preserve any existing indentation at the starts of paragraphs. | 17356 Preserve any existing indentation (or lack thereof) at the beginnings |
| 17357 of paragraphs. | |
| 15741 | 17358 |
| 15742 @item @samp{0} or @samp{none} | 17359 @item @samp{0} or @samp{none} |
| 15743 Delete any existing indentation. | 17360 Delete any existing indentation. |
| 15744 | 17361 |
| 15745 @item @var{num} | 17362 @item @var{num} |
| 15746 Indent each paragraph by @var{num} spaces. | 17363 Indent each paragraph by @var{num} spaces. |
| 15747 @end table | 17364 @end table |
| 15748 | 17365 |
| 17366 The default is to indent by two spaces, except for paragraphs | |
| 17367 following a section heading, which are not indented. | |
| 17368 | |
| 17369 @item --pdf | |
| 17370 @opindex --pdf | |
| 17371 Generate a PDF file using @command{texi2dvi --pdf}, rather than Info | |
| 17372 (@pxref{@t{texi2any} Printed Output}). | |
| 17373 | |
| 17374 @item --plaintext | |
| 17375 @opindex --plaintext | |
| 17376 @cindex Plain text output with @option{--plaintext} | |
| 17377 @cindex ASCII text output with @option{--plaintext} | |
| 17378 @cindex Generating plain text files with @option{--plaintext} | |
| 17379 @cindex Node separators, omitting with @option{--plaintext} | |
| 17380 @cindex Menus, omitting with @option{--plaintext} | |
| 17381 @cindex @file{INSTALL} file, generating | |
| 17382 Output a plain text file (rather than Info): do not include menus or | |
| 17383 node separator lines in the output. This results in a straightforward | |
| 17384 plain text file that you can (for example) send in email without | |
| 17385 complications, or include in a distribution (for example, an | |
| 17386 @file{INSTALL} file). | |
| 17387 | |
| 17388 With this option, @code{@@setfilename} is ignored and the output goes | |
| 17389 to standard output by default; this can be overridden with @option{-o}. | |
| 17390 | |
| 17391 @item --ps | |
| 17392 @opindex --ps | |
| 17393 Generate a PostScript file using @command{texi2dvi --ps}, rather than | |
| 17394 Info (@pxref{@t{texi2any} Printed Output}). | |
| 17395 | |
| 17396 @item --set-customization-variable @var{var}=@var{value} | |
| 17397 @itemx -c @var{var}=@var{value} | |
| 17398 @opindex --set-customization-variable @var{var}=@var{value} | |
| 17399 @opindex -c @var{var}=@var{value} | |
| 17400 Set the customization variable @var{var} to @var{value}. The @code{=} | |
| 17401 is optional, but both @var{var} and @var{value} must be quoted to the | |
| 17402 shell as necessary so the result is a single word. Many aspects of | |
| 17403 @command{texi2any} behavior and output may be controlled by | |
| 17404 customization variables, beyond what can be set in the document by | |
| 17405 @@-commands and with other command line switches. @xref{Customization | |
| 17406 Variables}. | |
| 17407 | |
| 17408 @item --split=@var{how} | |
| 17409 @itemx --no-split | |
| 17410 @opindex --split=@var{how} | |
| 17411 @opindex --no-split | |
| 17412 @cindex Splitting of output files | |
| 17413 @cindex Output file splitting | |
| 17414 @anchor{Splitting Output} | |
| 17415 @c | |
| 17416 When generating Info, by default large output files are split into | |
| 17417 smaller subfiles, of approximately 300k bytes. When generating HTML, | |
| 17418 by default each output file contains one node (@pxref{Generating | |
| 17419 HTML}). @option{--no-split} suppresses this splitting of the output. | |
| 17420 | |
| 17421 Alternatively, @option{--split=@var{how}} may be used to specify at | |
| 17422 which level the HTML output should be split. The possible values for | |
| 17423 @var{how} are: | |
| 17424 | |
| 17425 @table @samp | |
| 17426 @item chapter | |
| 17427 The output is split at @code{@@chapter} and other sectioning | |
| 17428 @@-commands at this level (@code{@@appendix}, etc.). | |
| 17429 | |
| 17430 @item section | |
| 17431 The output is split at @code{@@section} and similar. | |
| 17432 | |
| 17433 @item node | |
| 17434 The output is split at every node. This is the default. | |
| 17435 @end table | |
| 17436 | |
| 15749 @item --split-size=@var{num} | 17437 @item --split-size=@var{num} |
| 15750 @opindex --split-size=@var{num} | 17438 @opindex --split-size=@var{num} |
| 15751 Keep Info files to at most @var{num} characters; default is 300,000. | 17439 Keep Info files to at most @var{num} characters if possible; default |
| 17440 is 300,000. (However, a single node will never be split across Info | |
| 17441 files.) | |
| 15752 | 17442 |
| 15753 @item --transliterate-file-names | 17443 @item --transliterate-file-names |
| 15754 @opindex --transliterate-file-names | 17444 @opindex --transliterate-file-names |
| 15755 Enable transliteration of 8-bit characters in node names for the | 17445 Enable transliteration of 8-bit characters in node names for the |
| 15756 purpose of file name creation. @xref{HTML Xref 8-bit Character Expansion}. | 17446 purpose of file name creation. @xref{HTML Xref 8-bit Character Expansion}. |
| 15757 | 17447 |
| 15758 @item -U @var{var} | 17448 @item -U @var{var} |
| 15759 Cause @var{var} to be undefined. This is equivalent to | 17449 Cause @var{var} to be undefined. This is equivalent to @code{@@clear |
| 15760 @code{@@clear @var{var}} in the Texinfo file (@pxref{set clear value}). | 17450 @var{var}} in the Texinfo file (@pxref{@t{@@set @@clear @@value}}). |
| 15761 | 17451 |
| 15762 @item --verbose | 17452 @item --verbose |
| 15763 @opindex --verbose | 17453 @opindex --verbose |
| 15764 Cause @code{makeinfo} to display messages saying what it is doing. | 17454 Cause @code{makeinfo} to display messages saying what it is doing. |
| 15765 Normally, @code{makeinfo} only outputs messages if there are errors or | 17455 Normally, @code{makeinfo} only outputs messages if there are errors or |
| 15766 warnings. | 17456 warnings. |
| 15767 | 17457 |
| 15768 @item --version | 17458 @item --version |
| 15769 @itemx -V | 17459 @itemx -V |
| 15770 @opindex --version | 17460 @opindex --version@r{, for @command{texi2any}} |
| 15771 @opindex -V | 17461 @opindex -V |
| 15772 Print the version number, then exit successfully. | 17462 Print the version number, then exit successfully. |
| 15773 | 17463 |
| 17464 @item --Xopt @var{str} | |
| 17465 @opindex --Xopt @var{str} | |
| 17466 Pass @var{str} (a single shell word) to @command{texi2dvi}; may be | |
| 17467 repeated (@pxref{@t{texi2any} Printed Output}). | |
| 17468 | |
| 15774 @item --xml | 17469 @item --xml |
| 15775 @opindex --xml | 17470 @opindex --xml |
| 15776 Generate XML output rather than Info. | 17471 Generate Texinfo XML output (rather than Info). |
| 15777 | 17472 |
| 15778 @end table | 17473 @end table |
| 15779 | 17474 |
| 15780 @vindex TEXINFO_OUTPUT_FORMAT | 17475 @vindex TEXINFO_OUTPUT_FORMAT |
| 15781 @cindex Environment variable @code{TEXINFO_OUTPUT_FORMAT} | 17476 @cindex Environment variable @code{TEXINFO_OUTPUT_FORMAT} |
| 15782 @command{makeinfo} also reads the environment variable | 17477 @command{makeinfo} also reads the environment variable |
| 15783 @env{TEXINFO_OUTPUT_FORMAT} to determine the output format, if not | 17478 @env{TEXINFO_OUTPUT_FORMAT} to determine the output format, if not |
| 15784 overridden by a command line option. The possible values are: | 17479 overridden by a command line option. The value should be one of: |
| 15785 | 17480 |
| 15786 @example | 17481 @example |
| 15787 docbook html info plaintext xml | 17482 docbook dvi dvipdf html info pdf plaintext ps xml |
| 15788 @end example | 17483 @end example |
| 15789 | 17484 |
| 15790 If not set, Info output is the default. | 17485 If not set or otherwise specified, Info output is the default. |
| 17486 | |
| 17487 The customization variable of the same name is also read; if set, that | |
| 17488 overrides an environment variable setting, but not a command-line | |
| 17489 option. @xref{Customization Variables for @@-Commands}. | |
| 17490 | |
| 17491 | |
| 17492 @node @t{texi2any} Printed Output | |
| 17493 @section @command{texi2any} Printed Output | |
| 17494 | |
| 17495 @cindex Printed output, through @command{texi2any} | |
| 17496 @cindex Output, printed through @command{texi2any} | |
| 17497 | |
| 17498 To justify the name Texinfo-to-@emph{any}, @command{texi2any} has | |
| 17499 basic support for creating printed output in the various formats: | |
| 17500 @TeX{} DVI, PDF, and PostScript. This is done via the simple method | |
| 17501 of executing the @command{texi2dvi} program when those outputs are | |
| 17502 requested. | |
| 17503 | |
| 17504 The output format options for this are @option{--dvi}, | |
| 17505 @option{--dvipdf}, @option{--pdf}, and @option{--ps}. @xref{Format | |
| 17506 with @t{texi2dvi}}, for more details on these options and general | |
| 17507 @command{texi2dvi} operation. In addition, the @option{--verbose}, | |
| 17508 @option{--silent}, and @option{--quiet} options are passed on if | |
| 17509 specified; the @option{-I} and @option{-o} options are likewise passed | |
| 17510 on with their arguments, and @option{--debug} without its argument. | |
| 17511 | |
| 17512 The only option remaining that is related to the @command{texi2dvi} | |
| 17513 invocation is @option{--Xopt}. Here, just the argument is passed on | |
| 17514 and multiple @option{--Xopt} options accumulate. This provides a way | |
| 17515 to construct an arbitrary command line for @command{texi2dvi}. For | |
| 17516 example, running | |
| 17517 | |
| 17518 @example | |
| 17519 texi2any --Xopt -t --Xopt @@a4paper --pdf foo.texi | |
| 17520 @end example | |
| 17521 | |
| 17522 @noindent is equivalent to running | |
| 17523 | |
| 17524 @example | |
| 17525 texi2dvi -t @@a4paper --pdf foo.texi | |
| 17526 @end example | |
| 17527 | |
| 17528 Although one might wish that other options to @command{texi2any} would | |
| 17529 take effect, they don't. For example, running @samp{texi2any | |
| 17530 --no-number-sections --dvi foo.texi} still results in a DVI file with | |
| 17531 numbered sections. (Perhaps this could be improved in the future, if | |
| 17532 requests are received.) | |
| 17533 | |
| 17534 The actual name of the command that is invoked is specified by the | |
| 17535 @code{TEXI2DVI} customization variable (@pxref{Other Customization | |
| 17536 Variables}). As you might guess, the default is @samp{texi2dvi}. | |
| 17537 | |
| 17538 @command{texi2any} itself does not generate any output when it invokes | |
| 17539 @command{texi2dvi}. | |
| 15791 | 17540 |
| 15792 | 17541 |
| 15793 @node Pointer Validation | 17542 @node Pointer Validation |
| 15794 @subsection Pointer Validation | 17543 @section Pointer Validation |
| 15795 @cindex Pointer validation with @code{makeinfo} | 17544 @cindex Pointer validation with @code{makeinfo} |
| 15796 @cindex Validation of pointers | 17545 @cindex Validation of pointers |
| 15797 | 17546 |
| 15798 If you do not suppress pointer validation with the @samp{--no-validate} | 17547 If you do not suppress pointer validation with the |
| 15799 option or the @code{@@novalidate} command in the source file (@pxref{Use | 17548 @samp{--no-validate} option or the @code{@@novalidate} command in the |
| 15800 TeX,,Use @TeX{}}), @code{makeinfo} will check the validity of the final | 17549 source file (@pxref{Use @TeX{}}), @code{makeinfo} will check the |
| 15801 Info file. Mostly, this means ensuring that nodes you have referenced | 17550 validity of the Texinfo file. |
| 15802 really exist. Here is a complete list of what is checked: | 17551 |
| 17552 Most validation checks are different depending on whether node | |
| 17553 pointers are explicitly or implicitly determined. With explicit node | |
| 17554 pointers, here is the list of what is checked: | |
| 15803 | 17555 |
| 15804 @enumerate | 17556 @enumerate |
| 15805 @item | 17557 @item |
| 15806 If a `Next', `Previous', or `Up' node reference is a reference to a | 17558 If a `Next', `Previous', or `Up' node reference is a reference to a |
| 15807 node in the current file and is not an external reference such as to | 17559 node in the current file and is not an external reference such as to |
| 15808 @file{(dir)}, then the referenced node must exist.@refill | 17560 @file{(dir)}, then the referenced node must exist. |
| 15809 | 17561 |
| 15810 @item | 17562 @item |
| 15811 In every node, if the `Previous' node is different from the `Up' node, | 17563 Every node except the `Top' node must have an `Up' pointer. |
| 15812 then the node pointed to by the `Previous' field must have a `Next' | |
| 15813 field which points back to this node.@refill | |
| 15814 | 17564 |
| 15815 @item | 17565 @item |
| 15816 Every node except the `Top' node must have an `Up' pointer.@refill | 17566 The node referenced by an `Up' pointer must itself reference the |
| 15817 | 17567 current node through a menu item, unless the node referenced by `Up' |
| 17568 has the form @samp{(@var{file})}. | |
| 17569 @end enumerate | |
| 17570 | |
| 17571 With implicit node pointers, the above error cannot occur, as such. | |
| 17572 (Which is a major reason why we recommend using this feature of | |
| 17573 @code{makeinfo}, and not specifying any node pointers yourself.) | |
| 17574 | |
| 17575 Instead, @code{makeinfo} checks that the tree constructed from the | |
| 17576 document's menus matches the tree constructed from the sectioning | |
| 17577 commands. For example, if a chapter-level menu mentions nodes | |
| 17578 @var{n1} and @var{n2}, in that order, nodes @var{n1} and @var{n2} must | |
| 17579 be associated with @code{@@section} commands in the chapter. | |
| 17580 | |
| 17581 Finally, with both explicit and implicit node pointers, | |
| 17582 @code{makeinfo} checks that every node except the `Top' node is | |
| 17583 referenced in a menu. | |
| 17584 | |
| 17585 | |
| 17586 @node Customization Variables | |
| 17587 @section Customization Variables | |
| 17588 | |
| 17589 @quotation Warning | |
| 17590 These customization variable names and meanings may change in any | |
| 17591 Texinfo release. We always try to avoid incompatible changes, but we | |
| 17592 cannot absolutely promise, since needs change over time. | |
| 17593 @end quotation | |
| 17594 | |
| 17595 Many aspects of the behavior and output of @command{texi2any} may be | |
| 17596 modified by modifying so-called @dfn{customization variables}. These | |
| 17597 fall into a few general categories: | |
| 17598 | |
| 17599 @itemize @bullet | |
| 15818 @item | 17600 @item |
| 15819 The node referenced by an `Up' pointer must itself reference the current | 17601 Those associated with @@-commands; for example, |
| 15820 node through a menu item, unless the node referenced by `Up' | 17602 @code{@@documentlanguage}. |
| 15821 has the form `(@var{file})'. | |
| 15822 | 17603 |
| 15823 @item | 17604 @item |
| 15824 If the `Next' reference of a node is not the same as the `Next' reference | 17605 Those associated with command-line options; for example, the |
| 15825 of the `Up' reference, then the node referenced by the `Next' pointer | 17606 customization variable @code{SPLIT} is associated with the |
| 15826 must have a `Previous' pointer that points back to the current node. | 17607 @option{--split} command-line option, and @code{TEXINFO_OUTPUT_FORMAT} |
| 15827 This rule allows the last node in a section to point to the first node | 17608 allows specifying the output format. |
| 15828 of the next chapter.@refill | |
| 15829 | 17609 |
| 15830 @item | 17610 @item |
| 15831 Every node except `Top' should be referenced by at least one other node, | 17611 Those associated with customizing the HTML output. |
| 15832 either via the `Previous' or `Next' links, or via a menu or a | 17612 |
| 15833 cross-reference.@refill | 17613 @item |
| 17614 Other ad hoc variables. | |
| 17615 @end itemize | |
| 17616 | |
| 17617 Customization variables may set on the command line using | |
| 17618 @code{--set-customization-variable '@var{var} @var{value}'} (quoting | |
| 17619 the variable/value pair to the shell) or | |
| 17620 @code{--set-customization-variable @var{var}=@var{value}} (using | |
| 17621 @code{=}). A special @var{value} is @samp{undef}, which sets the | |
| 17622 variable to this special ``undefined'' Perl value. | |
| 17623 | |
| 17624 The sections below give the details for each of these. | |
| 17625 | |
| 17626 @menu | |
| 17627 * Commands: Customization Variables for @@-Commands. | |
| 17628 * Options: Customization Variables and Options. | |
| 17629 * HTML: HTML Customization Variables. | |
| 17630 * Other: Other Customization Variables. | |
| 17631 @end menu | |
| 17632 | |
| 17633 | |
| 17634 @node Customization Variables for @@-Commands | |
| 17635 @subsection Customization Variables for @@-Commands | |
| 17636 | |
| 17637 @cindex Customization variables for @@-commands | |
| 17638 @cindex @@-commands, customization variables for | |
| 17639 | |
| 17640 Each of the following @@-commands has an associated customization | |
| 17641 variable with the same name (minus the leading @code{@@}): | |
| 17642 | |
| 17643 @smallexample | |
| 17644 @@allowcodebreaks @@clickstyle @@codequotebacktick | |
| 17645 @@codequoteundirected @@contents @@deftypefnnewline | |
| 17646 @@documentdescription @@documentencoding @@documentlanguage | |
| 17647 @@evenfooting @@evenfootingmarks | |
| 17648 @@evenheading @@evenheadingmarks | |
| 17649 @@everyfooting @@everyfootingmarks | |
| 17650 @@everyheading @@everyheadingmarks | |
| 17651 @@exampleindent @@firstparagraphindent | |
| 17652 @@fonttextsize @@footnotestyle @@frenchspacing @@headings | |
| 17653 @@kbdinputstyle @@novalidate | |
| 17654 @@oddfooting @@oddfootingmarks | |
| 17655 @@oddheading @@oddheadingmarks | |
| 17656 @@pagesizes @@paragraphindent | |
| 17657 @@setchapternewpage @@setcontentsaftertitlepage | |
| 17658 @@setfilename | |
| 17659 @@setshortcontentsaftertitlepage @@shortcontents | |
| 17660 @@urefbreakstyle @@xrefautomaticsectiontitle | |
| 17661 @end smallexample | |
| 17662 | |
| 17663 Setting such a customization variable to a value @samp{foo} is similar | |
| 17664 to executing @code{@@@var{cmd} foo}. It is not exactly the same, | |
| 17665 though, since any side effects of parsing the Texinfo source are not | |
| 17666 redone. Also, some variables do not take Texinfo code when generating | |
| 17667 particular formats, but an argument that is already formatted. This | |
| 17668 is the case, for example, for HTML for @code{documentdescription}. | |
| 17669 | |
| 17670 | |
| 17671 @node Customization Variables and Options | |
| 17672 @subsection Customization Variables and Options | |
| 17673 | |
| 17674 @cindex Customization variables for options | |
| 17675 @cindex Options, customization variables for | |
| 17676 | |
| 17677 The following table gives the customization variables associated with | |
| 17678 some command line options. @xref{Invoking @t{texi2any}}, for the | |
| 17679 meaning of the options. | |
| 17680 | |
| 17681 @multitable @columnfractions 0.5 0.5 | |
| 17682 @headitem Option @tab Variable | |
| 17683 @vindex ENABLE_ENCODING | |
| 17684 @item @option{--enable-encoding} @tab @code{ENABLE_ENCODING} | |
| 17685 @vindex documentlanguage | |
| 17686 @item @option{--document-language} @tab @code{documentlanguage} | |
| 17687 @vindex ERROR_LIMIT | |
| 17688 @item @option{--error-limit} @tab @code{ERROR_LIMIT} | |
| 17689 @vindex FILLCOLUMN | |
| 17690 @item @option{--fill-column} @tab @code{FILLCOLUMN} | |
| 17691 @vindex footnotestyle | |
| 17692 @item @option{--footnote-style} @tab @code{footnotestyle} | |
| 17693 @vindex FORCE | |
| 17694 @item @option{--force} @tab @code{FORCE} | |
| 17695 @vindex INTERNAL_LINKS | |
| 17696 @item @option{--internal-links} @tab @code{INTERNAL_LINKS} | |
| 17697 @vindex MACRO_EXPAND | |
| 17698 @item @option{--macro-expand} @tab @code{MACRO_EXPAND} | |
| 17699 @vindex HEADERS | |
| 17700 @vindex SHOW_MENU | |
| 17701 @item @option{--headers} @tab @code{HEADERS}, @code{SHOW_MENU} | |
| 17702 @vindex NO_WARN | |
| 17703 @item @option{--no-warn} @tab @code{NO_WARN} | |
| 17704 @vindex novalidate | |
| 17705 @item @option{--no-validate} @tab @code{novalidate} | |
| 17706 @vindex NUMBER_FOOTNOTES | |
| 17707 @item @option{--number-footnotes} @tab @code{NUMBER_FOOTNOTES} | |
| 17708 @vindex NUMBER_SECTIONS | |
| 17709 @item @option{--number-sections} @tab @code{NUMBER_SECTIONS} | |
| 17710 @vindex NODE_FILES | |
| 17711 @item @option{--node-files} @tab @code{NODE_FILES} | |
| 17712 @vindex OUT | |
| 17713 @vindex OUTFILE | |
| 17714 @vindex SUBDIR | |
| 17715 @item @option{--output} @tab @code{OUT}, @code{OUTFILE}, | |
| 17716 @code{SUBDIR} | |
| 17717 @vindex paragraphindent | |
| 17718 @item @option{--paragraph-indent} @tab @code{paragraphindent} | |
| 17719 @vindex SILENT | |
| 17720 @item @option{--silent} @tab @code{SILENT} | |
| 17721 @vindex SPLIT | |
| 17722 @item @option{--split} @tab @code{SPLIT} | |
| 17723 @vindex SPLIT_SIZE | |
| 17724 @item @option{--split-size} @tab @code{SPLIT_SIZE} | |
| 17725 @vindex TRANSLITERATE_FILE_NAMES | |
| 17726 @item @option{--transliterate-file-names} @tab @code{TRANSLITERATE_FILE_NAMES} | |
| 17727 @vindex VERBOSE | |
| 17728 @item @option{--verbose} @tab @code{VERBOSE} | |
| 17729 @end multitable | |
| 17730 | |
| 17731 Setting such a customization variable to a value @samp{foo} is | |
| 17732 essentially the same as specifying the @code{--@var{opt}=foo} if the | |
| 17733 option takes an argument, or @code{--@var{opt}} if not. | |
| 17734 | |
| 17735 @vindex TEXINFO_OUTPUT_FORMAT | |
| 17736 In addition, the customization variable @code{TEXINFO_OUTPUT_FORMAT} | |
| 17737 allows specifying what @code{makeinfo} outputs, either one of the usual | |
| 17738 output formats that can be specified with options, or various other | |
| 17739 forms: | |
| 17740 | |
| 17741 @ftable @samp | |
| 17742 @item docbook | |
| 17743 @itemx dvi | |
| 17744 @itemx dvipdf | |
| 17745 @itemx html | |
| 17746 @itemx info | |
| 17747 @itemx pdf | |
| 17748 @itemx plaintext | |
| 17749 @itemx ps | |
| 17750 @itemx xml | |
| 17751 These correspond to the command-line options (and | |
| 17752 @code{TEXINFO_OUTPUT_FORMAT} environment variable values) of the same | |
| 17753 name. @xref{Invoking @t{texi2any}}. | |
| 17754 | |
| 17755 @item debugcount | |
| 17756 Instead of generating a regular output format, output the count of | |
| 17757 bytes and lines obtained when converting to Info, and other information. | |
| 17758 | |
| 17759 @item debugtree | |
| 17760 @cindex tree representation, for debugging | |
| 17761 @cindex debugging document, with tree representation | |
| 17762 Instead of generating a regular output format, output a text representation | |
| 17763 of the tree obtained by parsing the input texinfo document. | |
| 17764 | |
| 17765 @item parse | |
| 17766 Do only Texinfo source parsing; there is no output. | |
| 17767 | |
| 17768 @item plaintexinfo | |
| 17769 Output the Texinfo source with all the macros, @code{@@include} and | |
| 17770 @code{@@value@{@}} expanded. This is similar to setting | |
| 17771 @option{--macro-expand}, but instead of being output in addition to | |
| 17772 the normal conversion, output of Texinfo is the main output. | |
| 17773 | |
| 17774 @item rawtext | |
| 17775 @cindex raw text output | |
| 17776 Output raw text, with minimal formatting. For example, footnotes are | |
| 17777 ignored and there is no paragraph filling. This is used by the parser | |
| 17778 for file names and copyright text in HTML comments, for example. | |
| 17779 | |
| 17780 @item structure | |
| 17781 Do only Texinfo source parsing and determination of the document | |
| 17782 structure; there is no output. | |
| 17783 | |
| 17784 @item texinfosxml | |
| 17785 @cindex SXML output | |
| 17786 @cindex S-expressions, output format | |
| 17787 Output the document in TexinfoSXML representation, a syntax for | |
| 17788 writing XML data using Lisp S-expressions. | |
| 17789 | |
| 17790 @item textcontent | |
| 17791 @cindex spell checking | |
| 17792 @cindex word counting | |
| 17793 @pindex detexinfo | |
| 17794 @cindex stripping Texinfo commands | |
| 17795 Output the text content only, stripped of commands; this is useful for | |
| 17796 spell checking or word counting, for example. The trivial | |
| 17797 @code{detexinfo} script setting this is in the @file{util} directory | |
| 17798 of the Texinfo source as an example. It's one line: | |
| 17799 | |
| 17800 @example | |
| 17801 exec texi2any -c TEXINPUT_OUTPUT_FORMAT=textcontent "$@@" | |
| 17802 @end example | |
| 17803 @end ftable | |
| 17804 | |
| 17805 | |
| 17806 @node HTML Customization Variables | |
| 17807 @subsection HTML Customization Variables | |
| 17808 | |
| 17809 This table gives the customization variables which apply to HTML | |
| 17810 output only. A few other customization variable apply to both HTML | |
| 17811 and other output formats; those are given in the next section. | |
| 17812 | |
| 17813 @vtable @code | |
| 17814 @item AVOID_MENU_REDUNDANCY | |
| 17815 For HTML@. If set, and the menu entry and menu description are the | |
| 17816 same, then do not print the menu description; default false. | |
| 17817 | |
| 17818 @item AFTER_BODY_OPEN | |
| 17819 For HTML@. If set, the corresponding text will appear at the | |
| 17820 beginning of each HTML file; default unset. | |
| 17821 | |
| 17822 @item AFTER_ABOUT | |
| 17823 For HTML, when an About-element is output. If set, the corresponding | |
| 17824 text will appear at the end of the About element; default unset. | |
| 17825 | |
| 17826 @item AFTER_OVERVIEW | |
| 17827 @itemx AFTER_TOC_LINES | |
| 17828 For HTML@. If set, the corresponding text is output after the short | |
| 17829 table of contents for @code{AFTER_OVERVIEW} and after the table of | |
| 17830 contents for @code{AFTER_TOC_LINES}; otherwise, a default string is | |
| 17831 used. At the time of writing, a @code{</div>} element is closed. | |
| 17832 | |
| 17833 In general, you should set @code{BEFORE_OVERVIEW} if | |
| 17834 @code{AFTER_OVERVIEW} is set, and you should set | |
| 17835 @code{BEFORE_TOC_LINES} if @code{AFTER_TOC_LINES} is set. | |
| 17836 | |
| 17837 | |
| 17838 @item BASEFILENAME_LENGTH | |
| 17839 For HTML@. The maximum length of the base filenames; default 245. | |
| 17840 Changing this would make cross-manual references to such long node | |
| 17841 names invalid (@pxref{HTML Xref Link Basics}). | |
| 17842 | |
| 17843 @item BEFORE_OVERVIEW | |
| 17844 @itemx BEFORE_TOC_LINES | |
| 17845 For HTML@. If set, the corresponding text is output before the short | |
| 17846 table of contents for @code{BEFORE_OVERVIEW} and before the table of | |
| 17847 contents for @code{BEFORE_TOC_LINES}, otherwise a default string is | |
| 17848 used. At the time of writing, a @code{<div ...>} element is opened. | |
| 17849 | |
| 17850 In general you should set @code{AFTER_OVERVIEW} if | |
| 17851 @code{BEFORE_OVERVIEW} is set, and you should set | |
| 17852 @code{AFTER_TOC_LINES} if @code{BEFORE_TOC_LINES} is set. | |
| 17853 | |
| 17854 | |
| 17855 @item BIG_RULE | |
| 17856 For HTML@. Rule used after and before the top element and before | |
| 17857 special elements, but not for footers and headers; default | |
| 17858 @code{<hr>}. | |
| 17859 | |
| 17860 @item BODYTEXT | |
| 17861 @cindex @code{<body>} text, customizing | |
| 17862 For HTML, the text appearing in @code{<body>}. By default, set | |
| 17863 automatically, taking into account the document language | |
| 17864 (@pxref{@t{@@documentlanguage}}). | |
| 17865 | |
| 17866 @item CASE_INSENSITIVE_FILENAMES | |
| 17867 For HTML@. Construct output file names as if the filesystem were case | |
| 17868 insensitive (@pxref{HTML Splitting}); default false. | |
| 17869 | |
| 17870 @item CHAPTER_HEADER_LEVEL | |
| 17871 For HTML@. Header formatting level used for chapter level sectioning | |
| 17872 commands; default @samp{2}. | |
| 17873 | |
| 17874 @item CHECK_HTMLXREF | |
| 17875 For HTML@. Check that manuals which are the target of external | |
| 17876 cross references (@pxref{Four and Five Arguments}) are present in | |
| 17877 @file{htmlxref.cnf} (@pxref{HTML Xref Configuration}); default false. | |
| 17878 | |
| 17879 @item COMPLEX_FORMAT_IN_TABLE | |
| 17880 For HTML@. If set, use tables for indentation of complex formats; default | |
| 17881 false. | |
| 17882 | |
| 17883 @item CSS_LINES | |
| 17884 For HTML@. CSS output, automatically determined by default (@pxref{HTML CSS}). | |
| 17885 | |
| 17886 @item DATE_IN_HEADER | |
| 17887 For HTML@. Put the document generation date in the header; off by default. | |
| 17888 | |
| 17889 @item DEF_TABLE | |
| 17890 For HTML@. If set, a @code{<table>} construction for @code{@@deffn} | |
| 17891 and similar @@-commands is used (looking more like the @TeX{} output), | |
| 17892 instead of definition lists; default false. | |
| 17893 | |
| 17894 @item DEFAULT_RULE | |
| 17895 For HTML@. Rule used between element, except before and after the | |
| 17896 top element, and before special elements, and for footers and headers; | |
| 17897 default @code{<hr>}. | |
| 17898 | |
| 17899 @item DO_ABOUT | |
| 17900 For HTML@. If set to 0 never do an About special element; | |
| 17901 if set to 1 always do an About special element; | |
| 17902 default 0. | |
| 17903 @c @xref{Output Elements Defined}. | |
| 17904 | |
| 17905 @item EXTERNAL_DIR | |
| 17906 For HTML@. Base directory for external manuals; default none. It is | |
| 17907 better to use the general external cross reference mechanism | |
| 17908 (@pxref{HTML Xref Configuration}) than this variable. | |
| 17909 | |
| 17910 @item EXTRA_HEAD | |
| 17911 For HTML@. Additional text appearing within @code{<head>}; default unset. | |
| 17912 | |
| 17913 @item FOOTNOTE_END_HEADER_LEVEL | |
| 17914 For HTML@. Header formatting level used for the footnotes header with | |
| 17915 the `end' footnotestyle; default @samp{4}. @xref{Footnote Styles}. | |
| 17916 | |
| 17917 @item FOOTNOTE_SEPARATE_HEADER_LEVEL | |
| 17918 For HTML@. Header formatting level used for the footnotes header with | |
| 17919 the `separate' footnotestyle; default @samp{4}. @xref{Footnote | |
| 17920 Styles}. | |
| 17921 | |
| 17922 @item FRAMES | |
| 17923 For HTML@. If set, a file describing the frame layout is generated, | |
| 17924 together with a file with the short table of contents; default false. | |
| 17925 | |
| 17926 @item FRAMESET_DOCTYPE | |
| 17927 For HTML@. Same as DOCTYPE, but for the file containing the frame | |
| 17928 description. | |
| 17929 | |
| 17930 @item HEADER_IN_TABLE | |
| 17931 For HTML@. Use tables for header formatting rather than a simple | |
| 17932 @code{<div>} element; default false. | |
| 17933 | |
| 17934 @item ICONS | |
| 17935 For HTML@. Use icons for the navigation panel; default false. | |
| 17936 | |
| 17937 @item IMAGE_LINK_PREFIX | |
| 17938 For HTML@. If set, the associated value is prepended to the image file | |
| 17939 links; default unset. | |
| 17940 | |
| 17941 @item INLINE_CONTENTS | |
| 17942 For HTML@. If set, output the contents where the @code{@@contents} and | |
| 17943 similar @@-commands are located; default true. This is ignored if | |
| 17944 @code{@@set*contentsaftertitlepage} is set (@pxref{Contents}). | |
| 17945 | |
| 17946 @item INLINE_CSS_STYLE | |
| 17947 For HTML@. Put CSS directly in HTML elements rather than at the | |
| 17948 beginning of the output; default false. | |
| 17949 | |
| 17950 @item KEEP_TOP_EXTERNAL_REF | |
| 17951 For HTML@. If set, do not ignore @samp{Top} as the first | |
| 17952 argument for an external ref to a manual, as is done by default. | |
| 17953 @xref{Top Node Naming}. | |
| 17954 | |
| 17955 @item L2H | |
| 17956 For HTML@. If set, @command{latex2html} is used to convert @code{@@math} | |
| 17957 and @code{@@tex} sections; default false. Best used with @option{--iftex}. | |
| 17958 | |
| 17959 @item L2H_CLEAN | |
| 17960 (Relevant only if @code{L2H} is set.) If set, the intermediate files | |
| 17961 generated in relation with @command{latex2html} are removed; default | |
| 17962 true. | |
| 17963 | |
| 17964 @item L2H_FILE | |
| 17965 (Relevant only if @code{L2H} is set.) If set, the given file is used | |
| 17966 as @command{latex2html}'s init file; default unset. | |
| 17967 | |
| 17968 @item L2H_HTML_VERSION | |
| 17969 (Relevant only if @code{L2H} is set.) The HTML version used in the | |
| 17970 @command{latex2html} call; default unset. | |
| 17971 | |
| 17972 @item L2H_L2H | |
| 17973 (Relevant only if @code{L2H} is set.) The program invoked as | |
| 17974 @command{latex2html}; default is @code{latex2html}. | |
| 17975 | |
| 17976 @item L2H_SKIP | |
| 17977 (Relevant only if @code{L2H} is set.) If set to a true value, the | |
| 17978 actual call to @command{latex2html} is skipped; previously generated | |
| 17979 content is reused instead. If set to 0, the cache is not used at all. | |
| 17980 If set to @samp{undef}, the cache is used for as many @TeX{} fragments as | |
| 17981 possible and for any remaining the command is run. The default is | |
| 17982 @samp{undef}. | |
| 17983 | |
| 17984 @item L2H_TMP | |
| 17985 (Relevant only if @code{L2H} is set.) Set the directory used for | |
| 17986 temporary files. None of the file name components in this directory | |
| 17987 name may start with @samp{.}; otherwise, @command{latex2html} will | |
| 17988 fail (because of @command{dvips}). The default is the empty string, | |
| 17989 which means the current directory. | |
| 17990 | |
| 17991 @item MAX_HEADER_LEVEL | |
| 17992 For HTML@. Maximum header formatting level used (higher header | |
| 17993 formatting level numbers correspond to lower sectioning levels); | |
| 17994 default @samp{4}. | |
| 17995 | |
| 17996 @item MENU_SYMBOL | |
| 17997 For HTML@. Symbol used in front of menu entries when node names are used | |
| 17998 for menu entries formatting; default @samp{•}. | |
| 17999 | |
| 18000 @item MONOLITHIC | |
| 18001 For HTML@. Output only one file including the table of contents. Set | |
| 18002 by default, but only relevant when the output is not split. | |
| 18003 | |
| 18004 @item NO_CSS | |
| 18005 For HTML@. Do not use CSS; default false. @xref{HTML CSS}. | |
| 18006 | |
| 18007 @item NODE_FILE_EXTENSION | |
| 18008 For HTML@. Extension for node files if @code{NODE_FILENAMES} is set; | |
| 18009 default @samp{html}. | |
| 18010 | |
| 18011 @item PRE_ABOUT | |
| 18012 For HTML, when an About element is output. If set to a text string, | |
| 18013 this text will appear at the beginning of the About element. If set | |
| 18014 to a reference on a subroutine, the result of the subroutine call will | |
| 18015 appear at the beginning of the About element. If not set (the | |
| 18016 default), default text is used. | |
| 18017 | |
| 18018 @item PRE_BODY_CLOSE | |
| 18019 For HTML@. If set, the given text will appear at the footer of each | |
| 18020 HTML file; default unset. | |
| 18021 | |
| 18022 @item PROGRAM_NAME_IN_FOOTER | |
| 18023 For HTML@. If set, output the program name and miscellaneous related | |
| 18024 information in the page footers; default false. | |
| 18025 | |
| 18026 @item SHORTEXTN | |
| 18027 For HTML@. If set, use @samp{.htm} as extension; default false. | |
| 18028 | |
| 18029 @item SHOW_TITLE | |
| 18030 For HTML@. If set, output the title at the beginning of the document; | |
| 18031 default true. | |
| 18032 | |
| 18033 @item SIMPLE_MENU | |
| 18034 For HTML@. If set, use a simple preformatted style for the menu, | |
| 18035 instead of breaking down the different parts of the menu; default false. | |
| 18036 @xref{Menu Parts}. | |
| 18037 | |
| 18038 @item TOC_LINKS | |
| 18039 For HTML@. If set, links from headings to toc entries are created; | |
| 18040 default false. | |
| 18041 | |
| 18042 @item TOP_FILE | |
| 18043 This file name may be used for the top-level file. The extension is | |
| 18044 set appropriately, if necessary. This is used to override the default, | |
| 18045 and is, in general, only taken into account when output is split, and | |
| 18046 for HTML@. | |
| 18047 | |
| 18048 @item TOP_NODE_FILE | |
| 18049 For HTML@. File name used for the Top node, if @code{NODE_FILENAMES} | |
| 18050 is set; default is @code{index}. | |
| 18051 | |
| 18052 @item TOP_NODE_FILE_TARGET | |
| 18053 For HTML@. File name used for the Top node in cross references; | |
| 18054 default is @code{index}. | |
| 18055 | |
| 18056 @item TOP_NODE_UP_URL | |
| 18057 For HTML@. The url used for the Up pointer of the Top node; default | |
| 18058 @code{undef}, meaning no link is generated. | |
| 18059 | |
| 18060 @item USE_ACCESSKEY | |
| 18061 @cindex @code{accesskey}, customization variable for | |
| 18062 For HTML@. Use @code{accesskey} in cross references; default true. | |
| 18063 | |
| 18064 @item USE_ISO | |
| 18065 For HTML@. Use entities for doubled single-quote characters | |
| 18066 (@pxref{Inserting Quotation Marks}), and @samp{---} and @samp{--} | |
| 18067 (@pxref{Conventions}); default true. | |
| 18068 | |
| 18069 @item USE_LINKS | |
| 18070 @cindex @code{<link>} HTML tag, in @code{<head>} | |
| 18071 @cindex @code{<head>} HTML tag, and @code{<link>} | |
| 18072 For HTML@. Generate @code{<link>} elements in the HTML @code{<head>} | |
| 18073 output; default true. | |
| 18074 | |
| 18075 @item USE_REL_REV | |
| 18076 For HTML@. Use @code{rel} in cross references; default true. | |
| 18077 | |
| 18078 @item VERTICAL_HEAD_NAVIGATION | |
| 18079 For HTML@. If set, a vertical navigation panel is used; default false. | |
| 18080 | |
| 18081 @item WORDS_IN_PAGE | |
| 18082 @cindex Navigation panel, bottom of page | |
| 18083 For HTML, with output split at nodes. Specifies the approximate | |
| 18084 minimum page length at which a navigation panel is placed at the | |
| 18085 bottom of a page. To avoid ever having the navigation buttons at the | |
| 18086 bottom of a page, set this to a sufficiently large number. The | |
| 18087 default is 300. | |
| 18088 | |
| 18089 @item XREF_USE_FLOAT_LABEL | |
| 18090 For HTML@. If set, for the float name in cross references, use the | |
| 18091 float label instead of the type followed by the float number | |
| 18092 (@pxref{@t{@@float}}). The default is off. | |
| 18093 | |
| 18094 @item XREF_USE_NODE_NAME_ARG | |
| 18095 For HTML@. Only relevant for cross reference commands with no cross | |
| 18096 reference name (second argument). If set to@tie{}1, use the node name | |
| 18097 (first) argument in cross reference @@-commands for the text displayed | |
| 18098 as the hyperlink. If set to@tie{}0, use the node name if | |
| 18099 @code{USE_NODES} is set, otherwise the section name. If set to | |
| 18100 @samp{undef}, use the first argument in preformatted environments, | |
| 18101 otherwise use the node name or section name depending on | |
| 18102 @code{USE_NODES}. The default is @samp{undef}. | |
| 18103 | |
| 18104 @end vtable | |
| 18105 | |
| 18106 | |
| 18107 @node Other Customization Variables | |
| 18108 @subsection Other Customization Variables | |
| 18109 | |
| 18110 This table gives the remaining customization variables, which apply to | |
| 18111 multiple formats, or affect global behavior, or otherwise don't fit | |
| 18112 into the categories of the previous sections. | |
| 18113 | |
| 18114 @vtable @code | |
| 18115 @item CLOSE_QUOTE_SYMBOL | |
| 18116 When a closing quote is needed, use this character; default @code{’} | |
| 18117 in HTML, @code{’} in Docbook. The default for Info is the same | |
| 18118 as @code{OPEN_QUOTE_SYMBOL} (see below). | |
| 18119 | |
| 18120 @c @item COMPLETE_IMAGE_PATHS | |
| 18121 @c If set, the image files are computed to be relative from the document | |
| 18122 @c directory to the source manual directory, and then to the image. | |
| 18123 | |
| 18124 @item CPP_LINE_DIRECTIVES | |
| 18125 Recognize @code{#line} directives in a ``preprocessing'' pass | |
| 18126 (@pxref{External Macro Processors}); on by default. | |
| 18127 | |
| 18128 @item DEBUG | |
| 18129 If set, debugging output is generated; default is off (zero). | |
| 18130 @c The integer value specifies what kinds of debugging output are | |
| 18131 @c generated. It is a bitmask. Setting it to 255 ensures having all | |
| 18132 @c available debugging output. | |
| 18133 | |
| 18134 @item DOCTYPE | |
| 18135 @vindex SystemLiteral | |
| 18136 For Docbook, HTML, XML@. Specifies the @code{SystemLiteral}, the | |
| 18137 entity's system identifier. This is a URI which may be used to | |
| 18138 retrieve the entity, and identifies the canonical DTD for the | |
| 18139 document. The default value is different for each of HTML, Docbook | |
| 18140 and Texinfo@tie{}XML. | |
| 18141 | |
| 18142 @item DUMP_TEXI | |
| 18143 For debugging. If set, no conversion is done, only parsing and macro | |
| 18144 expansion. If the option @option{--macro-expand} is set, the Texinfo | |
| 18145 source is also expanded to the corresponding file. Default false. | |
| 18146 | |
| 18147 @item DUMP_TREE | |
| 18148 For debugging. If set, the tree constructed upon parsing a Texinfo | |
| 18149 document is output to standard error; default false. | |
| 18150 | |
| 18151 @item ENABLE_ENCODING_USE_ENTITY | |
| 18152 For HTML, XML@. If @option{--enable-encoding} is set, and there is an | |
| 18153 entity corresponding with the letter or the symbol being output, | |
| 18154 prefer the entity. Set by default for HTML, but not XML. | |
| 18155 | |
| 18156 @item EXTERNAL_CROSSREF_SPLIT | |
| 18157 For cross references to other manuals, this determines if the other | |
| 18158 manual is considered to be split or monolithic. By default, it is set | |
| 18159 based on the value of @code{SPLIT}. @xref{HTML Xref}, and @pxref{HTML | |
| 18160 Xref Configuration}. | |
| 18161 | |
| 18162 @item EXTENSION | |
| 18163 The extension added to the output file name. The default is different | |
| 18164 for each output format. | |
| 18165 | |
| 18166 @item FIX_TEXINFO | |
| 18167 For ``plain Texinfo'' (see the @code{PLAINTEXINFO} item). If set to | |
| 18168 false, the resulting Texinfo does not have all errors corrected, such | |
| 18169 as missing @samp{@@end}; default true. This variable is only | |
| 18170 relevant when expanding Texinfo; other converters always try to | |
| 18171 output something sane even if the input is erroneous. | |
| 18172 | |
| 18173 @c @item IDX_SUMMARY | |
| 18174 @c If set, for each @code{@@printindex} a file named | |
| 18175 @c @file{@var{docname}_@var{idxname}.idx} is created, containing lines of | |
| 18176 @c the form: | |
| 18177 @c | |
| 18178 @c @example | |
| 18179 @c @var{key} @var{reference} | |
| 18180 @c @end example | |
| 18181 @c | |
| 18182 @c @noindent sorted alphabetically (case matters). | |
| 18183 | |
| 18184 @item IGNORE_BEFORE_SETFILENAME | |
| 18185 If set, begin outputting at @code{@@setfilename}, if | |
| 18186 @code{@@setfilename} is present; default true. | |
| 18187 | |
| 18188 @item IGNORE_SPACE_AFTER_BRACED_COMMAND_NAME | |
| 18189 If set, spaces are ignored after an @@-command that takes braces. | |
| 18190 Default true, matching the @TeX{} behavior. | |
| 18191 | |
| 18192 @item INDEX_ENTRY_COLON | |
| 18193 Symbol used between the index entry and the associated node or section; | |
| 18194 default @samp{:}. | |
| 18195 | |
| 18196 @item INFO_SPECIAL_CHARS_WARNING | |
| 18197 If set, warn about problematic constructs for Info output (such as the | |
| 18198 string @samp{::}) in node names, menu items, and cross references; | |
| 18199 default true. Do not warn about index entries, since parsing problems | |
| 18200 there don't prevent navigation; readers can still relatively easily | |
| 18201 find their way to the node in question. | |
| 18202 | |
| 18203 @item INLINE_INSERTCOPYING | |
| 18204 If set, @code{@@insertcopying} is replaced by the @code{@@copying} | |
| 18205 content (@pxref{@t{@@copying}}) as if @code{@@insertcopying} were a | |
| 18206 user-defined macro; default false. | |
| 18207 | |
| 18208 @item INPUT_ENCODING_NAME | |
| 18209 Normalized encoding name suitable for output. Should be a usable | |
| 18210 charset name in HTML, typically one of the preferred IANA encoding | |
| 18211 names. You should not need to use this variable, since it is set by | |
| 18212 @code{@@documentencoding} (@pxref{@t{@@documentencoding}}). | |
| 18213 | |
| 18214 @item INPUT_PERL_ENCODING | |
| 18215 Perl encoding used to process the Texinfo source. You should not need | |
| 18216 to use that variable, since it is set by @code{@@documentencoding} | |
| 18217 (@pxref{@t{@@documentencoding}}). | |
| 18218 | |
| 18219 @item MACRO_BODY_IGNORES_LEADING_SPACE | |
| 18220 Ignore white space at the beginning of user defined macro body line, | |
| 18221 mimicking a @TeX{} limitation (@pxref{Macro Details}). Default off. | |
| 18222 | |
| 18223 @item MAX_MACRO_CALL_NESTING | |
| 18224 The maximal number of recursive calls of @@-commands defined through | |
| 18225 @code{@@rmacro}; default 100000. The purpose of this variable is to | |
| 18226 avoid infinite recursions. | |
| 18227 | |
| 18228 @item MENU_ENTRY_COLON | |
| 18229 Symbol used between the menu entry and the description; default | |
| 18230 @samp{:}. | |
| 18231 | |
| 18232 @item NO_USE_SETFILENAME | |
| 18233 If set, do not use @code{@@setfilename} to set the document name; | |
| 18234 instead, base the output document name only on the input file name. | |
| 18235 The default is false. | |
| 18236 | |
| 18237 @item NODE_FILENAMES | |
| 18238 If set, node names are used to construct file names. By default, it | |
| 18239 is set if the output is split by node, or if @code{NODE_FILES} is set | |
| 18240 and the output is split in any way. | |
| 18241 | |
| 18242 @item NODE_NAME_IN_INDEX | |
| 18243 If set, use node names in index entries, otherwise prefer section names; | |
| 18244 default true. | |
| 18245 | |
| 18246 @item NODE_NAME_IN_MENU | |
| 18247 If set, use node names in menu entries, otherwise prefer section names; | |
| 18248 default true. | |
| 18249 | |
| 18250 @item OPEN_QUOTE_SYMBOL | |
| 18251 When an opening quote is needed, e.g., for @samp{@@samp} output, use | |
| 18252 the specified character; default @code{‘} for HTML, | |
| 18253 @code{‘} for Docbook. For Info, the default depends on the | |
| 18254 enabled document encoding (@pxref{@t{@@documentencoding}}); if no | |
| 18255 document encoding is set, or the encoding is US-ASCII, etc., @samp{'} | |
| 18256 is used. This character usually appears as an undirected single quote | |
| 18257 on modern systems. If the document encoding is Unicode, the Info | |
| 18258 output uses a Unicode left quote. | |
| 18259 | |
| 18260 @item OUTPUT_ENCODING_NAME | |
| 18261 Normalized encoding name used for output files. Should be a usable | |
| 18262 charset name in HTML, typically one of the preferred IANA encoding | |
| 18263 names. By default, if an input encoding is set (typically through | |
| 18264 @code{@@documentencoding} or @code{INPUT_ENCODING_NAME}), this | |
| 18265 information is used to set the output encoding name. If no input | |
| 18266 encoding is specified, the default output encoding name may be set by | |
| 18267 the output format. In particular, the XML-based formats use | |
| 18268 @code{utf-8} for @code{OUTPUT_ENCODING_NAME} if the encoding is not | |
| 18269 otherwise specified. @xref{@t{@@documentencoding}}. | |
| 18270 | |
| 18271 @item OVERVIEW_LINK_TO_TOC | |
| 18272 If set, the cross references in the Overview link to the corresponding | |
| 18273 Table of Contents entries; default true. | |
| 18274 | |
| 18275 @item PACKAGE | |
| 18276 @itemx PACKAGE_VERSION | |
| 18277 @itemx PACKAGE_AND_VERSION | |
| 18278 @itemx PACKAGE_URL | |
| 18279 @itemx PACKAGE_NAME | |
| 18280 The implementation's short package name, package version, package name | |
| 18281 and version concatenated, package url, and full package name, | |
| 18282 respectively. By default, these variables are all set through | |
| 18283 Autoconf, Automake, and @code{configure}. | |
| 18284 | |
| 18285 @item PREFIX | |
| 18286 The output file prefix, which is prepended to some output file names. | |
| 18287 By default it is set by @code{@@setfilename} or from the input file | |
| 18288 (@pxref{@t{@@setfilename}}). How this value is used depends on the | |
| 18289 value of other customization variables or command line options, such | |
| 18290 as whether the output is split and @code{NODE_FILENAMES}. The default | |
| 18291 is unset. | |
| 18292 | |
| 18293 @item PROGRAM | |
| 18294 Name of the program used. By default, it is set to the name of the | |
| 18295 program launched, with a trailing @samp{.pl} removed. | |
| 18296 | |
| 18297 @item RENAMED_NODES_FILE | |
| 18298 If set, use the value for the renamed nodes description file. If not | |
| 18299 set, the file is @file{@var{doc_basename}-noderename.cnf}. | |
| 18300 @xref{HTML Xref Link Preservation}. | |
| 18301 | |
| 18302 @item RENAMED_NODES_REDIRECTIONS | |
| 18303 If set, create redirection files for renamed nodes. Set by default | |
| 18304 when generating HTML@. | |
| 18305 | |
| 18306 @item SHOW_MENU | |
| 18307 @opindex --no-headers | |
| 18308 If set, Texinfo menus are output. By default, it is set unless | |
| 18309 generating Docbook or if @option{--no-headers} is specified. | |
| 18310 | |
| 18311 @item SORT_ELEMENT_COUNT | |
| 18312 @pindex texi-elements-by-size | |
| 18313 @cindex Longest nodes, finding | |
| 18314 @cindex Sorting nodes by size | |
| 18315 If set, the name of a file to which a list of elements (nodes or | |
| 18316 sections, depending on the output format) is dumped, sorted by the | |
| 18317 number of lines they contain after removal of @@-commands; default | |
| 18318 unset. This is used by the program @code{texi-elements-by-size} in | |
| 18319 the @file{util/} directory of the Texinfo source distribution | |
| 18320 (@pxref{texi-elements-by-size}). | |
| 18321 | |
| 18322 @item SORT_ELEMENT_COUNT_WORDS | |
| 18323 When dumping the elements-by-size file (see preceding item), use word | |
| 18324 counts instead of line counts; default false. | |
| 18325 | |
| 18326 @c @item SPLIT_INDEX | |
| 18327 @c For HTML@. If set, the output is split, and the output from | |
| 18328 @c @code{@@printindex} happens in a sectioning element at the level of | |
| 18329 @c splitting, then split index pages at the next letter after they have | |
| 18330 @c more than that many entries. If set to 0, no index splitting. | |
| 18331 | |
| 18332 @item TEST | |
| 18333 If set to true, some variables which are normally dynamically | |
| 18334 generated anew for each run (date, program name, version) are set to | |
| 18335 fixed and given values. This is useful to compare the output to a | |
| 18336 reference file, as is done for the tests. The default is false. | |
| 18337 | |
| 18338 @item TEXI2DVI | |
| 18339 Name of the command used to produce PostScript, PDF, and DVI; default | |
| 18340 @samp{texi2dvi}. @xref{@t{texi2any} Printed Output}. | |
| 18341 | |
| 18342 @item TEXI2HTML | |
| 18343 @cindex compatibility, with @command{texi2html} | |
| 18344 Generate HTML and try to be as compatible as possible with | |
| 18345 @command{texi2html}; default false. | |
| 18346 | |
| 18347 @item TEXINFO_COLUMN_FOR_DESCRIPTION | |
| 18348 Used with the @code{indent_menu_descriptions} tree transformation, | |
| 18349 described below; default 32 (matching | |
| 18350 @code{texinfo-column-for-description} in XEmacs)). | |
| 18351 | |
| 18352 @item TEXINFO_DTD_VERSION | |
| 18353 For XML@. Version of the DTD used in the XML output preamble. The | |
| 18354 default is set based on a variable in @file{configure.ac}. | |
| 18355 | |
| 18356 @item TEXTCONTENT_COMMENT | |
| 18357 For stripped text content output (i.e., when | |
| 18358 @code{TEXINFO_OUTPUT_FORMAT} is set to @code{textcontent}). If set, | |
| 18359 also output comments. Default false. | |
| 18360 | |
| 18361 @item TOP_NODE_UP | |
| 18362 Up node for the Top node; default @samp{(dir)}. | |
| 18363 | |
| 18364 @item TREE_TRANSFORMATIONS | |
| 18365 The associated value is a comma separated list of transformations that | |
| 18366 can be applied to the Texinfo tree prior to outputting the result. If | |
| 18367 more than one is specified, the ordering is irrelevant; each is always | |
| 18368 applied at the necessary point during processing. | |
| 18369 | |
| 18370 The only one executed by default is | |
| 18371 @samp{move_index_entries_after_items} for HTML and Docbook output. | |
| 18372 Here's an example of updating the master menu in a document: | |
| 18373 | |
| 18374 @example | |
| 18375 makeinfo \ | |
| 18376 -c TREE_TRANSFORMATIONS=regenerate_master_menu \ | |
| 18377 -c PLAINTEXINFO=1 \ | |
| 18378 mydoc.texi \ | |
| 18379 -o /tmp/out | |
| 18380 @end example | |
| 18381 | |
| 18382 @noindent (Caveat: Since @code{PLAINTEXINFO} output does expand | |
| 18383 Texinfo macros and conditionals, it's necessary to remove any such | |
| 18384 differences before installing the updates in the original document. | |
| 18385 This will be remedied in a future release.) | |
| 18386 | |
| 18387 The following transformations are currently supported (many are used | |
| 18388 in the @code{pod2texi} utility distributed with Texinfo; | |
| 18389 @pxref{Invoking @t{pod2texi}}): | |
| 18390 | |
| 18391 @ftable @samp | |
| 18392 @item complete_tree_nodes_menus | |
| 18393 Add menu entries or whole menus for nodes associated with sections of | |
| 18394 any level, based on the sectioning tree. | |
| 18395 | |
| 18396 @item fill_gaps_in_sectioning | |
| 18397 Adds empty @code{@@unnumbered...} sections in a tree to fill gaps in | |
| 18398 sectioning. For example, an @code{@@unnumberedsec} will be inserted | |
| 18399 if an @code{@@chapter} is followed by an @code{@@subsection}. | |
| 18400 | |
| 18401 @item indent_menu_descriptions | |
| 18402 Reformat menus so that descriptions start at column | |
| 18403 @code{TEXINFO_COLUMN_DESCRIPTION}. | |
| 18404 | |
| 18405 @item insert_nodes_for_sectioning_commands | |
| 18406 Insert nodes for sectioning commands lacking a corresponding node. | |
| 18407 | |
| 18408 @item move_index_entries_after_items | |
| 18409 In @code{@@enumerate} and @code{@@itemize}, move index entries | |
| 18410 appearing just before an @code{@@item} to just after the | |
| 18411 @code{@@item}. Comment lines between index entries are moved too. As | |
| 18412 mentioned, this is always done for HTML and Docbook output. | |
| 18413 | |
| 18414 @item regenerate_master_menu | |
| 18415 Update the Top node master menu, either replacing the (first) | |
| 18416 @code{@@detailmenu} in the Top node menu, or creating it at the end of | |
| 18417 the Top node menu. | |
| 18418 | |
| 18419 @item simple_menu | |
| 18420 Mostly the same as @code{SIMPLE_MENU}: use a simple preformatted style | |
| 18421 for the menu. It differs from setting @code{SIMPLE_MENU} in that | |
| 18422 @code{SIMPLE_MENU} only has an effect in HTML output. | |
| 18423 | |
| 18424 @end ftable | |
| 18425 | |
| 18426 @item USE_NODES | |
| 18427 Preferentially use nodes to decide where elements are separated. If | |
| 18428 set to false, preferentially use sectioning to decide where elements | |
| 18429 are separated. The default is true. | |
| 18430 | |
| 18431 @item USE_NODE_TARGET | |
| 18432 If set, use the node associated with a section for the section target | |
| 18433 in cross references; default true. | |
| 18434 | |
| 18435 @item USE_NUMERIC_ENTITY | |
| 18436 For HTML and XML@. If set, use numeric entities instead of ASCII | |
| 18437 characters when there is no named entity. By default, set to true for | |
| 18438 HTML. | |
| 18439 | |
| 18440 @item USE_UP_NODE_FOR_ELEMENT_UP | |
| 18441 Fill in up sectioning direction with node direction when there is no | |
| 18442 sectioning up direction. In practice this can only happen when there | |
| 18443 is no @@top section. Not set by default. | |
| 18444 | |
| 18445 @item USE_SETFILENAME_EXTENSION | |
| 18446 Default is on for Info, off for other output. If set, use exactly | |
| 18447 what @code{@@setfilename} gives for the output file name, including | |
| 18448 the extension. You should not need to explicitly set this variable. | |
| 18449 | |
| 18450 @item USE_TITLEPAGE_FOR_TITLE | |
| 18451 Use the full @code{@@titlepage} as the title, not a simple title string; | |
| 18452 default false. | |
| 18453 | |
| 18454 @item USE_UNIDECODE | |
| 18455 @pindex Text::Unidecode | |
| 18456 If set to false, do not use the @code{Text::Unidecode} Perl module to | |
| 18457 transliterate more characters; default true. | |
| 18458 | |
| 18459 @end vtable | |
| 18460 | |
| 18461 | |
| 18462 @node Internationalization of Document Strings | |
| 18463 @section Internationalization of Document Strings | |
| 18464 | |
| 18465 @cindex I18n, of document strings | |
| 18466 @cindex Internationalization of document strings | |
| 18467 @cindex Document strings, internationalization of | |
| 18468 @cindex Output document strings, internationalization of | |
| 18469 @cindex Translating strings in output documents | |
| 18470 | |
| 18471 @vindex documentlanguage @r{customization variable} | |
| 18472 @command{texi2any} writes fixed strings into the output document at | |
| 18473 various places: cross references, page footers, the help page, | |
| 18474 alternate text for images, and so on. The string chosen depends on | |
| 18475 the value of the @code{documentlanguage} at the time of the string | |
| 18476 being output (@pxref{@t{@@documentlanguage}}, for the Texinfo | |
| 18477 command interface). | |
| 18478 | |
| 18479 @pindex libintl-perl @r{Gettext implementation} | |
| 18480 The Gettext framework is used for those strings (@pxref{Top,,, | |
| 18481 gettext, Gettext}). The @code{libintl-perl} package is used as the | |
| 18482 @code{gettext} implementation; more specifically, the pure Perl | |
| 18483 implementation is used, so Texinfo can support consistent behavior | |
| 18484 across all platforms and installations, which would not otherwise be | |
| 18485 possible. @code{libintl-perl} is included in the Texinfo distribution | |
| 18486 and always installed, to ensure that it is available if needed. It is | |
| 18487 also possible to use the system @code{gettext} (the choice can be made | |
| 18488 at build-time). | |
| 18489 | |
| 18490 @vindex texinfo_document @r{Gettext domain} | |
| 18491 @cindex Perl format strings for translation | |
| 18492 The Gettext domain @samp{texinfo_document} is used for the strings. | |
| 18493 Translated strings are written as Texinfo, and may include | |
| 18494 @@-commands. In translated strings, the varying parts of the string | |
| 18495 are not usually denoted by @code{%s} and the like, but by | |
| 18496 @samp{@{arg_name@}}. (This convention is common for @code{gettext} in | |
| 18497 Perl and is fully supported in GNU Gettext; @pxref{perl-format,, Perl | |
| 18498 Format Strings, gettext, GNU Gettext}.) For example, in the | |
| 18499 following, @samp{@{section@}} will be replaced by the section name: | |
| 18500 | |
| 18501 @example | |
| 18502 see @{section@} | |
| 18503 @end example | |
| 18504 | |
| 18505 These Perl-style brace format strings are used for two reasons: first, | |
| 18506 changing the order of @code{printf} arguments is only available since | |
| 18507 Perl@tie{}5.8.0; second, and more importantly, the order of arguments | |
| 18508 is unpredictable, since @@-command expansion may lead to different | |
| 18509 orders depending on the output format. | |
| 18510 | |
| 18511 The expansion of a translation string is done like this: | |
| 18512 | |
| 18513 @enumerate | |
| 18514 @item First, the string is translated. The locale | |
| 18515 is @var{@@documentlanguage}@code{.}@var{@@documentencoding}. | |
| 18516 | |
| 18517 @cindex @code{us-ascii} encoding, and translations | |
| 18518 If the @var{@@documentlanguage} has the form @samp{ll_CC}, that is | |
| 18519 tried first, and then just @samp{ll}. If that does not exist, and the | |
| 18520 encoding is not @code{us-ascii}, then @code{us-ascii} is tried. | |
| 18521 | |
| 18522 The idea is that if there is a @code{us-ascii} encoding, it means that | |
| 18523 all the characters in the charset may be expressed as @@-commands. | |
| 18524 For example, there is a @code{fr.us-ascii} locale that can accommodate | |
| 18525 any encoding, since all the Latin@tie{}1 characters have associated | |
| 18526 @@-commands. On the other hand, Japanese has only a translation | |
| 18527 @code{ja.utf-8}, since there are no @@-commands for Japanese | |
| 18528 characters. | |
| 18529 | |
| 18530 @item Next, the string is expanded as Texinfo, and converted. | |
| 18531 The arguments are substituted; for example, @samp{@{arg_name@}} is | |
| 18532 replaced by the corresponding actual argument. | |
| 18533 | |
| 15834 @end enumerate | 18534 @end enumerate |
| 15835 | 18535 |
| 15836 @cindex @@-commands in @@node, limited support | 18536 In the following example, @samp{@{date@}}, @samp{@{program_homepage@}} |
| 15837 Some Texinfo documents might fail during the validation phase because | 18537 and @samp{@{program@}} are the arguments of the string. Since they |
| 15838 they use commands like @code{@@value} and @code{@@definfoenclose} in | 18538 are used in @code{@@uref}, their order is not predictable. |
| 15839 node definitions and cross-references inconsistently. (Your best bet | 18539 @samp{@{date@}}, @samp{@{program_homepage@}} and @samp{@{program@}} are |
| 15840 is to avoid using @@-commands in node names.) Consider the | 18540 substituted after the expansion: |
| 15841 following example: | 18541 |
| 15842 | 18542 @example |
| 15843 @example | 18543 Generated on @@emph@{@{date@}@} using |
| 15844 @group | 18544 @@uref@{@{program_homepage@}, @@emph@{@{program@}@}@}. |
| 15845 @@set nodename Node 1 | 18545 @end example |
| 15846 | 18546 |
| 15847 @@node @@value@{nodename@}, Node 2, Top, Top | 18547 This approach is admittedly a bit complicated. Its usefulness is that |
| 15848 | 18548 it supports having translations available in different encodings for |
| 15849 This is node 1. | 18549 encodings which can be covered by @@-commands, and also specifying how |
| 15850 | 18550 the formatting for some commands is done, independently of the output |
| 15851 @@node Node 2, , Node 1, Top | 18551 format---yet still be language-dependent. For example, the |
| 15852 | 18552 @samp{@@pxref} translation string can be like this: |
| 15853 This is node 2. | 18553 |
| 15854 @end group | 18554 @example |
| 15855 @end example | 18555 see @{node_file_href@} section `@{section@}\' in @@cite@{@{book@}@} |
| 15856 | 18556 @end example |
| 15857 @noindent | 18557 |
| 15858 Here, the node ``Node 1'' was referenced both verbatim and through | 18558 @noindent |
| 15859 @code{@@value}. | 18559 which allows for specifying a string independently of the output |
| 15860 | 18560 format, while nevertheless with rich formatting it may be translated |
| 15861 By default, @code{makeinfo} fails such cases, because node names are not | 18561 appropriately in many languages. |
| 15862 fully expanded until they are written to the output file. You should | 18562 |
| 15863 always try to reference nodes consistently; e.g., in the above example, | 18563 |
| 15864 the second @code{@@node} line should have also used @code{@@value}. | 18564 @node Invoking @t{pod2texi} |
| 15865 However, if, for some reason, you @emph{must} reference node names | 18565 @section Invoking @t{pod2texi}: Convert POD to Texinfo |
| 15866 inconsistently, and @code{makeinfo} fails to validate the file, you can | 18566 |
| 15867 use the @samp{--commands-in-node-names} option to force @code{makeinfo} | 18567 @pindex pod2texi |
| 15868 to perform the expensive expansion of all node names it finds in the | 18568 @cindex Invoking @code{pod2texi} |
| 15869 document. This might considerably slow down the program, though; | 18569 @cindex POD, converting to Texinfo |
| 15870 twofold increase in conversion time was measured for large documents | 18570 @cindex Perl POD, converting to Texinfo |
| 15871 such as the Jargon file. | 18571 |
| 15872 | 18572 The @code{pod2texi} program translates Perl pod documentation file(s) |
| 15873 @cindex @@value in @@node lines | 18573 to Texinfo. There are two basic modes of operation: generating a |
| 15874 The support for @code{@@}-commands in @code{@@node} directives is not | 18574 standalone manual from each input pod, or (if @code{--base-level=1} or |
| 15875 general enough to be freely used. For example, if the example above | 18575 higher is given) generating Texinfo subfiles suitable for use |
| 15876 redefined @code{nodename} somewhere in the document, @code{makeinfo} | 18576 with @code{@@include}. |
| 15877 will fail to convert it, even if invoked with the | 18577 |
| 15878 @samp{--commands-in-node-names} option. | 18578 Although ordinarily this documentation in the Texinfo manual would be |
| 15879 | 18579 the best place to look, in this case we have documented all the |
| 15880 @samp{--commands-in-node-names} has no effect if the @samp{--no-validate} | 18580 options and examples in the @code{pod2texi} program itself, since it |
| 15881 option is given. | 18581 may be useful outside of the rest of Texinfo. Thus, please see the |
| 15882 | 18582 output of @code{pod2texi --help}, the version on the web at |
| 15883 | 18583 @url{http://www.gnu.org/software/texinfo/manual/pod2texi.html}, etc. |
| 15884 @node makeinfo in XEmacs | 18584 |
| 18585 For an example of using @code{pod2texi} to make Texinfo out of the | |
| 18586 Perl documentation itself, see | |
| 18587 @url{http://svn.savannah.gnu.org/viewvc/trunk/contrib/perldoc-all/?root=texinfo, | |
| 18588 @file{contrib/perldoc-all}} in the Texinfo source distribution (the | |
| 18589 output is available at @url{http://www.gnu.org/software/perl/manual}). | |
| 18590 | |
| 18591 | |
| 18592 @node @t{texi2html} | |
| 18593 @section @code{texi2html}: Ancestor of @code{texi2any} | |
| 18594 | |
| 18595 @pindex texi2html | |
| 18596 | |
| 18597 @cindex Cons, Lionel | |
| 18598 Conceptually, the @command{texi2html} program is the parent of today's | |
| 18599 @command{texi2any} program. @command{texi2html} was developed | |
| 18600 independently, originally by Lionel Cons in 1998; at the time, | |
| 18601 @command{makeinfo} could not generate HTML@. Many other people | |
| 18602 contributed to @command{texi2html} over the years. | |
| 18603 | |
| 18604 The present @command{texi2any} uses little of the actual code of | |
| 18605 @command{texi2html}, and has quite a different basic approach to the | |
| 18606 implementation (namely, parsing the Texinfo document into a tree), but | |
| 18607 still, there is a family resemblance. | |
| 18608 | |
| 18609 By design, @command{texi2any} supports nearly all the features of | |
| 18610 @command{texi2html} in some way. However, we did not attempt to | |
| 18611 maintain strict compatibility, so no @command{texi2html} executable is | |
| 18612 installed by the Texinfo package. An approximation can be run with an | |
| 18613 invocation like this (available as @file{util/texi2html} in the | |
| 18614 Texinfo source): | |
| 18615 | |
| 18616 @example | |
| 18617 texi2any --set-customization-variable TEXI2HTML=1 ... | |
| 18618 @end example | |
| 18619 | |
| 18620 @noindent but, to emphasize, this is @emph{not} a drop-in replacement | |
| 18621 for the previous @command{texi2html}. Here are the biggest differences: | |
| 18622 | |
| 18623 @itemize @bullet | |
| 18624 @item Most blatantly, the command line options of @command{texi2html} | |
| 18625 are now customization variables, for the most part. A table of | |
| 18626 approximate equivalents is given below. | |
| 18627 | |
| 18628 @item The program-level customization API is very different in | |
| 18629 @command{texi2any}. | |
| 18630 | |
| 18631 @item Indices cannot be split. | |
| 18632 | |
| 18633 @item Translated strings cannot be customized; we hope to introduce | |
| 18634 this feature in @command{texi2any} in the future. | |
| 18635 | |
| 18636 @end itemize | |
| 18637 | |
| 18638 Aside from the last, we do not intend to reimplement these | |
| 18639 differences. Therefore, the route forward for authors is alter | |
| 18640 manuals and build processes as necessary to use the new features and | |
| 18641 methods of @command{texi2any}. The @command{texi2html} maintainers | |
| 18642 (one of whom is the principal author of @command{texi2any}) do not | |
| 18643 intend to make further releases. | |
| 18644 | |
| 18645 @cindex Options of @command{texi2html} | |
| 18646 @cindex Command-line options of @command{texi2html} | |
| 18647 Here is the table showing @command{texi2html} options and | |
| 18648 corresponding @command{texi2any} customization variables. | |
| 18649 @c (@pxref{texi2any Output Customization,, @command{texi2any} Output | |
| 18650 @c Customization}). | |
| 18651 | |
| 18652 @multitable {@option{--ignore-preamble-text}} {@code{IGNORE_PREAMBLE_TEXT}} | |
| 18653 @item @option{--toc-links} @tab @code{TOC_LINKS} | |
| 18654 @item @option{--short-ext} @tab @code{SHORTEXTN} | |
| 18655 @item @option{--prefix} @tab @code{PREFIX} | |
| 18656 @item @option{--short-ref} @tab @code{SHORT_REF} | |
| 18657 @item @option{--idx-sum} @tab @code{IDX_SUMMARY} | |
| 18658 @item @option{--def-table} @tab @code{DEF_TABLE} | |
| 18659 @item @option{--ignore-preamble-text} @tab @code{IGNORE_PREAMBLE_TEXT} | |
| 18660 @item @option{--html-xref-prefix} @tab @code{EXTERNAL_DIR} | |
| 18661 @item @option{--l2h} @tab @code{L2H} | |
| 18662 @item @option{--l2h-l2h} @tab @code{L2H_L2H} | |
| 18663 @item @option{--l2h-skip} @tab @code{L2H_SKIP} | |
| 18664 @item @option{--l2h-tmp} @tab @code{L2H_TMP} | |
| 18665 @item @option{--l2h-file} @tab @code{L2H_FILE} | |
| 18666 @item @option{--l2h-clean} @tab @code{L2H_CLEAN} | |
| 18667 @item @option{--use-nodes} @tab @code{USE_NODES} | |
| 18668 @item @option{--monolithic} @tab @code{MONOLITHIC} | |
| 18669 @item @option{--top-file} @tab @code{TOP_FILE} | |
| 18670 @item @option{--toc-file} @tab @code{TOC_FILE} | |
| 18671 @item @option{--frames} @tab @code{FRAMES} | |
| 18672 @item @option{--menu} @tab @code{SHOW_MENU} | |
| 18673 @item @option{--debug} @tab @code{DEBUG} | |
| 18674 @item @option{--doctype} @tab @code{DOCTYPE} | |
| 18675 @item @option{--frameset-doctype} @tab @code{FRAMESET_DOCTYPE} | |
| 18676 @item @option{--test} @tab @code{TEST} | |
| 18677 @end multitable | |
| 18678 | |
| 18679 @cindex @file{texi2oldapi.texi}, for @command{texi2any} | |
| 18680 Finally, any @command{texi2html} users seeking more detailed | |
| 18681 information can check the draft file @file{doc/texi2oldapi.texi} in | |
| 18682 the Texinfo source repository. It consists mainly of very rough | |
| 18683 notes, but may still be useful to some. | |
| 18684 | |
| 18685 | |
| 18686 @node Creating and Installing Info Files | |
| 18687 @chapter Creating and Installing Info Files | |
| 18688 | |
| 18689 This chapter describes how to create and install Info files. | |
| 18690 @xref{Info Files}, for general information about the file format | |
| 18691 itself. | |
| 18692 | |
| 18693 @menu | |
| 18694 * Creating an Info File:: | |
| 18695 * Installing an Info File:: | |
| 18696 @end menu | |
| 18697 | |
| 18698 | |
| 18699 @node Creating an Info File | |
| 18700 @section Creating an Info File | |
| 18701 @cindex Creating an Info file | |
| 18702 @cindex Info, creating an online file | |
| 18703 @cindex Formatting a file for Info | |
| 18704 | |
| 18705 @code{makeinfo} is a program that converts a Texinfo file into an Info | |
| 18706 file, HTML file, or plain text. @code{texinfo-format-region} and | |
| 18707 @code{texinfo-format-buffer} are XEmacs functions that convert | |
| 18708 Texinfo to Info. | |
| 18709 | |
| 18710 For information on installing the Info file in the Info system, | |
| 18711 @pxref{Installing an Info File}. | |
| 18712 | |
| 18713 @menu | |
| 18714 * @t{makeinfo} Advantages:: @code{makeinfo} provides better error checking. | |
| 18715 * @t{makeinfo} in XEmacs:: How to run @code{makeinfo} from XEmacs. | |
| 18716 * @t{texinfo-format} commands:: Two Info formatting commands written | |
| 18717 in Emacs Lisp are an alternative | |
| 18718 to @code{makeinfo}. | |
| 18719 * Batch Formatting:: How to format for Info in XEmacs Batch mode. | |
| 18720 * Tag and Split Files:: How tagged and split files help Info | |
| 18721 to run better. | |
| 18722 @end menu | |
| 18723 | |
| 18724 | |
| 18725 @node @t{makeinfo} Advantages | |
| 18726 @subsection @code{makeinfo} Advantages | |
| 18727 | |
| 18728 @anchor{makeinfo advantages}@c old name | |
| 18729 | |
| 18730 The @code{makeinfo} utility creates an Info file from a Texinfo source | |
| 18731 providing better error messages than either of the XEmacs formatting | |
| 18732 commands. We recommend it. The @code{makeinfo} program is | |
| 18733 independent of XEmacs. You can run @code{makeinfo} in any of three | |
| 18734 ways: from an operating system shell, from a shell inside XEmacs, or by | |
| 18735 typing the @kbd{C-c C-m C-r} or the @kbd{C-c C-m C-b} command in | |
| 18736 Texinfo mode in XEmacs. | |
| 18737 | |
| 18738 The @code{texinfo-format-region} and the @code{texinfo-format-buffer} | |
| 18739 commands may be useful if you cannot run @code{makeinfo}. | |
| 18740 | |
| 18741 | |
| 18742 @node @t{makeinfo} in XEmacs | |
| 15885 @subsection Running @code{makeinfo} Within XEmacs | 18743 @subsection Running @code{makeinfo} Within XEmacs |
| 18744 | |
| 18745 @c anchor{makeinfo in XEmacs}@c prev name | |
| 15886 @cindex Running @code{makeinfo} in XEmacs | 18746 @cindex Running @code{makeinfo} in XEmacs |
| 15887 @cindex @code{makeinfo} inside XEmacs | 18747 @cindex @code{makeinfo} inside XEmacs |
| 15888 @cindex Shell, running @code{makeinfo} in | 18748 @cindex Shell, running @code{makeinfo} in |
| 15889 | 18749 |
| 15890 You can run @code{makeinfo} in XEmacs Texinfo mode by using either the | 18750 You can run @code{makeinfo} in XEmacs Texinfo mode by using either the |
| 15891 @code{makeinfo-region} or the @code{makeinfo-buffer} commands. In | 18751 @code{makeinfo-region} or the @code{makeinfo-buffer} commands. In |
| 15892 Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c | 18752 Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c |
| 15893 C-m C-b} by default.@refill | 18753 C-m C-b} by default. |
| 15894 | 18754 |
| 15895 @table @kbd | 18755 @table @kbd |
| 15896 @item C-c C-m C-r | 18756 @item C-c C-m C-r |
| 15897 @itemx M-x makeinfo-region | 18757 @itemx M-x makeinfo-region |
| 15898 Format the current region for Info.@refill | 18758 Format the current region for Info. |
| 15899 @findex makeinfo-region | 18759 @findex makeinfo-region |
| 15900 | 18760 |
| 15901 @item C-c C-m C-b | 18761 @item C-c C-m C-b |
| 15902 @itemx M-x makeinfo-buffer | 18762 @itemx M-x makeinfo-buffer |
| 15903 Format the current buffer for Info.@refill | 18763 Format the current buffer for Info. |
| 15904 @findex makeinfo-buffer | 18764 @findex makeinfo-buffer |
| 15905 @end table | 18765 @end table |
| 15906 | 18766 |
| 15907 When you invoke @code{makeinfo-region} the output goes to a temporary | 18767 When you invoke @code{makeinfo-region} the output goes to a temporary |
| 15908 buffer. When you invoke @code{makeinfo-buffer} output goes to the | 18768 buffer. When you invoke @code{makeinfo-buffer} output goes to the |
| 15909 file set with @code{@@setfilename} (@pxref{setfilename}). | 18769 file set with @code{@@setfilename} (@pxref{@t{@@setfilename}}). |
| 15910 | 18770 |
| 15911 The XEmacs @code{makeinfo-region} and @code{makeinfo-buffer} commands | 18771 The XEmacs @code{makeinfo-region} and @code{makeinfo-buffer} commands |
| 15912 run the @code{makeinfo} program in a temporary shell buffer. If | 18772 run the @code{makeinfo} program in a temporary shell buffer. If |
| 15913 @code{makeinfo} finds any errors, XEmacs displays the error messages in | 18773 @code{makeinfo} finds any errors, XEmacs displays the error messages in |
| 15914 the temporary buffer.@refill | 18774 the temporary buffer. |
| 15915 | 18775 |
| 15916 @cindex Errors, parsing | 18776 @cindex Errors, parsing |
| 15917 @cindex Parsing errors | 18777 @cindex Parsing errors |
| 15918 @findex next-error | 18778 @findex next-error |
| 15919 You can parse the error messages by typing @kbd{C-x `} | 18779 You can parse the error messages by typing @kbd{C-x `} |
| 15920 (@code{next-error}). This causes XEmacs to go to and position the | 18780 (@code{next-error}). This causes XEmacs to go to and position the |
| 15921 cursor on the line in the Texinfo source that @code{makeinfo} thinks | 18781 cursor on the line in the Texinfo source that @code{makeinfo} thinks |
| 15922 caused the error. @xref{Compilation, , Running @code{make} or | 18782 caused the error. @xref{Compilation, , Running @code{make} or |
| 15923 Compilers Generally, xemacs, XEmacs User's Manual}, for more | 18783 Compilers Generally, xemacs, XEmacs User's Manual}, for more |
| 15924 information about using the @code{next-error} command.@refill | 18784 information about using the @code{next-error} command. |
| 15925 | 18785 |
| 15926 In addition, you can kill the shell in which the @code{makeinfo} | 18786 In addition, you can kill the shell in which the @code{makeinfo} |
| 15927 command is running or make the shell buffer display its most recent | 18787 command is running or make the shell buffer display its most recent |
| 15928 output.@refill | 18788 output. |
| 15929 | 18789 |
| 15930 @table @kbd | 18790 @table @kbd |
| 15931 @item C-c C-m C-k | 18791 @item C-c C-m C-k |
| 15932 @itemx M-x makeinfo-kill-job | 18792 @itemx M-x makeinfo-kill-job |
| 15933 @findex makeinfo-kill-job | 18793 @findex makeinfo-kill-job |
| 15934 Kill the current running @code{makeinfo} job | 18794 Kill the current running @code{makeinfo} job |
| 15935 (from @code{makeinfo-region} or @code{makeinfo-buffer}).@refill | 18795 (from @code{makeinfo-region} or @code{makeinfo-buffer}). |
| 15936 | 18796 |
| 15937 @item C-c C-m C-l | 18797 @item C-c C-m C-l |
| 15938 @itemx M-x makeinfo-recenter-output-buffer | 18798 @itemx M-x makeinfo-recenter-output-buffer |
| 15939 @findex makeinfo-recenter-output-buffer | 18799 @findex makeinfo-recenter-output-buffer |
| 15940 Redisplay the @code{makeinfo} shell buffer to display its most recent | 18800 Redisplay the @code{makeinfo} shell buffer to display its most recent |
| 15941 output.@refill | 18801 output. |
| 15942 @end table | 18802 @end table |
| 15943 | 18803 |
| 15944 @noindent | 18804 @noindent |
| 15945 (Note that the parallel commands for killing and recentering a @TeX{} | 18805 (Note that the parallel commands for killing and recentering a @TeX{} |
| 15946 job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode | 18806 job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode |
| 15947 Printing}.)@refill | 18807 Printing}.) |
| 15948 | 18808 |
| 15949 You can specify options for @code{makeinfo} by setting the | 18809 You can specify options for @code{makeinfo} by setting the |
| 15950 @code{makeinfo-options} variable with either the @kbd{M-x | 18810 @code{makeinfo-options} variable with either the @kbd{M-x |
| 15951 customize} or the @kbd{M-x set-variable} command, or by setting the | 18811 customize} or the @kbd{M-x set-variable} command, or by setting the |
| 15952 variable in your @file{init.el} initialization file. | 18812 variable in your @file{init.el} initialization file. |
| 15953 | 18813 |
| 15954 For example, you could write the following in your @file{init.el} file:@refill | 18814 For example, you could write the following in your @file{init.el} file: |
| 15955 | 18815 |
| 15956 @example | 18816 @example |
| 15957 @group | 18817 @group |
| 15958 (setq makeinfo-options | 18818 (setq makeinfo-options |
| 15959 "--paragraph-indent=0 --no-split | 18819 "--paragraph-indent=0 --no-split |
| 15960 --fill-column=70 --verbose") | 18820 --fill-column=70 --verbose") |
| 15961 @end group | 18821 @end group |
| 15962 @end example | 18822 @end example |
| 15963 | 18823 |
| 15964 @noindent | 18824 @noindent |
| 15965 @c If you write these three cross references using xref, you see | 18825 @c Writing these three cross references using xref results in |
| 15966 @c three references to the same named manual, which looks strange. | 18826 @c three references to the same named manual, which looks strange. |
| 15967 @iftex | 18827 @iftex |
| 15968 For more information, see @ref{makeinfo options, , Options for | 18828 For more information, see @ref{@t{makeinfo} Options}, as well as |
| 15969 @code{makeinfo}}, as well as ``Easy Customization Interface,'' ``Examining | 18829 ``Easy Customization Interface,'' ``Examining and Setting Variables,'' |
| 15970 and Setting Variables,'' and ``Init File'' in @cite{The XEmacs | 18830 and ``Init File'' in @cite{XEmacs User's Manual}. |
| 15971 Manual}. | |
| 15972 @end iftex | 18831 @end iftex |
| 15973 @ifnottex | 18832 @ifnottex |
| 15974 For more information, see@* | 18833 For more information, see@* |
| 15975 @ref{Easy Customization, , Easy Customization Interface, xemacs, XEmacs User's Manual},@* | 18834 @ref{Easy Customization, , Easy Customization Interface, xemacs, XEmacs User's Manual},@* |
| 15976 @ref{Examining, , Examining and Setting Variables, xemacs, XEmacs User's Manual},@* | 18835 @ref{Examining, , Examining and Setting Variables, xemacs, XEmacs User's Manual},@* |
| 15977 @ref{Init File, , , xemacs, XEmacs User's Manual}, and@* | 18836 @ref{Init File, , , xemacs, XEmacs User's Manual}, and@* |
| 15978 @ref{makeinfo options, , Options for @code{makeinfo}}. | 18837 @ref{@t{makeinfo} Options}. |
| 15979 @end ifnottex | 18838 @end ifnottex |
| 15980 | 18839 |
| 15981 @node texinfo-format commands | 18840 |
| 18841 @node @t{texinfo-format} commands | |
| 15982 @subsection The @code{texinfo-format@dots{}} Commands | 18842 @subsection The @code{texinfo-format@dots{}} Commands |
| 18843 | |
| 18844 @c anchor{texinfo-format commands}@c prev name | |
| 15983 | 18845 |
| 15984 In XEmacs in Texinfo mode, you can format part or all of a Texinfo | 18846 In XEmacs in Texinfo mode, you can format part or all of a Texinfo |
| 15985 file with the @code{texinfo-format-region} command. This formats the | 18847 file with the @code{texinfo-format-region} command. This formats the |
| 15986 current region and displays the formatted text in a temporary buffer | 18848 current region and displays the formatted text in a temporary buffer |
| 15987 called @samp{*Info Region*}.@refill | 18849 called @samp{*Info Region*}. |
| 15988 | 18850 |
| 15989 Similarly, you can format a buffer with the | 18851 Similarly, you can format a buffer with the |
| 15990 @code{texinfo-format-buffer} command. This command creates a new | 18852 @code{texinfo-format-buffer} command. This command creates a new |
| 15991 buffer and generates the Info file in it. Typing @kbd{C-x C-s} will | 18853 buffer and generates the Info file in it. Typing @kbd{C-x C-s} will |
| 15992 save the Info file under the name specified by the | 18854 save the Info file under the name specified by the |
| 15993 @code{@@setfilename} line which must be near the beginning of the | 18855 @code{@@setfilename} line which must be near the beginning of the |
| 15994 Texinfo file.@refill | 18856 Texinfo file. |
| 15995 | 18857 |
| 15996 @table @kbd | 18858 @table @kbd |
| 15997 @item C-c C-e C-r | 18859 @item C-c C-e C-r |
| 15998 @itemx @code{texinfo-format-region} | 18860 @itemx @code{texinfo-format-region} |
| 15999 @findex texinfo-format-region | 18861 @findex texinfo-format-region |
| 16007 | 18869 |
| 16008 The @code{texinfo-format-region} and @code{texinfo-format-buffer} | 18870 The @code{texinfo-format-region} and @code{texinfo-format-buffer} |
| 16009 commands provide you with some error checking, and other functions can | 18871 commands provide you with some error checking, and other functions can |
| 16010 provide you with further help in finding formatting errors. These | 18872 provide you with further help in finding formatting errors. These |
| 16011 procedures are described in an appendix; see @ref{Catching Mistakes}. | 18873 procedures are described in an appendix; see @ref{Catching Mistakes}. |
| 16012 However, the @code{makeinfo} program is often faster and | 18874 However, the @code{makeinfo} program provides better error checking |
| 16013 provides better error checking (@pxref{makeinfo in XEmacs}).@refill | 18875 (@pxref{@t{makeinfo} in XEmacs}). |
| 18876 | |
| 16014 | 18877 |
| 16015 @node Batch Formatting | 18878 @node Batch Formatting |
| 16016 @comment node-name, next, previous, up | |
| 16017 @subsection Batch Formatting | 18879 @subsection Batch Formatting |
| 16018 @cindex Batch formatting for Info | 18880 @cindex Batch formatting for Info |
| 16019 @cindex Info batch formatting | 18881 @cindex Info batch formatting |
| 16020 | 18882 |
| 16021 You can format Texinfo files for Info using @code{batch-texinfo-format} | 18883 You can format Texinfo files for Info using @code{batch-texinfo-format} |
| 16030 xemacs -batch -funcall batch-texinfo-format *.texinfo | 18892 xemacs -batch -funcall batch-texinfo-format *.texinfo |
| 16031 @end example | 18893 @end example |
| 16032 | 18894 |
| 16033 @noindent | 18895 @noindent |
| 16034 XEmacs processes all the files listed on the command line, even if an | 18896 XEmacs processes all the files listed on the command line, even if an |
| 16035 error occurs while attempting to format some of them.@refill | 18897 error occurs while attempting to format some of them. |
| 16036 | 18898 |
| 16037 Run @code{batch-texinfo-format} only with XEmacs in Batch mode as shown; | 18899 Run @code{batch-texinfo-format} only with XEmacs in Batch mode as shown; |
| 16038 it is not interactive. It kills the Batch mode XEmacs on completion.@refill | 18900 it is not interactive. It kills the Batch mode XEmacs on completion. |
| 16039 | 18901 |
| 16040 @code{batch-texinfo-format} is convenient if you lack @code{makeinfo} | 18902 @code{batch-texinfo-format} is convenient if you lack @code{makeinfo} |
| 16041 and want to format several Texinfo files at once. When you use Batch | 18903 and want to format several Texinfo files at once. When you use Batch |
| 16042 mode, you create a new XEmacs process. This frees your current XEmacs, so | 18904 mode, you create a new XEmacs process. This frees your current XEmacs, so |
| 16043 you can continue working in it. (When you run | 18905 you can continue working in it. (When you run |
| 16044 @code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot | 18906 @code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot |
| 16045 use that XEmacs for anything else until the command finishes.)@refill | 18907 use that XEmacs for anything else until the command finishes.) |
| 16046 | 18908 |
| 16047 @node Tag and Split Files | 18909 @node Tag and Split Files |
| 16048 @comment node-name, next, previous, up | |
| 16049 @subsection Tag Files and Split Files | 18910 @subsection Tag Files and Split Files |
| 16050 @cindex Making a tag table automatically | 18911 @cindex Making a tag table automatically |
| 16051 @cindex Tag table, making automatically | 18912 @cindex Tag table, making automatically |
| 16052 | 18913 |
| 16053 If a Texinfo file has more than 30,000 bytes, | 18914 If a Texinfo file has more than 30,000 bytes, |
| 16054 @code{texinfo-format-buffer} automatically creates a tag table | 18915 @code{texinfo-format-buffer} automatically creates a tag table |
| 16055 for its Info file; @code{makeinfo} always creates a tag table. With | 18916 for its Info file; @code{makeinfo} always creates a tag table. With |
| 16056 a @dfn{tag table}, Info can jump to new nodes more quickly than it can | 18917 a @dfn{tag table}, Info can jump to new nodes more quickly than it can |
| 16057 otherwise.@refill | 18918 otherwise. |
| 16058 | 18919 |
| 16059 @cindex Indirect subfiles | 18920 @cindex Indirect subfiles |
| 16060 In addition, if the Texinfo file contains more than about 300,000 | 18921 In addition, if the Texinfo file contains more than about 300,000 |
| 16061 bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the | 18922 bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the |
| 16062 large Info file into shorter @dfn{indirect} subfiles of about 300,000 | 18923 large Info file into shorter @dfn{indirect} subfiles of about 300,000 |
| 16067 memory when you run Info. (Before splitting was implemented, Info | 18928 memory when you run Info. (Before splitting was implemented, Info |
| 16068 files were always kept short and @dfn{include files} were designed as | 18929 files were always kept short and @dfn{include files} were designed as |
| 16069 a way to create a single, large printed manual out of the smaller Info | 18930 a way to create a single, large printed manual out of the smaller Info |
| 16070 files. @xref{Include Files}, for more information. Include files are | 18931 files. @xref{Include Files}, for more information. Include files are |
| 16071 still used for very large documents, such as @cite{The XEmacs Lisp | 18932 still used for very large documents, such as @cite{The XEmacs Lisp |
| 16072 Reference Manual}, in which each chapter is a separate file.)@refill | 18933 Reference Manual}, in which each chapter is a separate file.) |
| 16073 | 18934 |
| 16074 When a file is split, Info itself makes use of a shortened version of | 18935 When a file is split, Info itself makes use of a shortened version of |
| 16075 the original file that contains just the tag table and references to | 18936 the original file that contains just the tag table and references to |
| 16076 the files that were split off. The split-off files are called | 18937 the files that were split off. The split-off files are called |
| 16077 @dfn{indirect} files.@refill | 18938 @dfn{indirect} files. |
| 16078 | 18939 |
| 16079 The split-off files have names that are created by appending @w{@samp{-1}}, | 18940 The split-off files have names that are created by appending @w{@samp{-1}}, |
| 16080 @w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the | 18941 @w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the |
| 16081 @code{@@setfilename} command. The shortened version of the original file | 18942 @code{@@setfilename} command. The shortened version of the original file |
| 16082 continues to have the name specified by @code{@@setfilename}.@refill | 18943 continues to have the name specified by @code{@@setfilename}. |
| 16083 | 18944 |
| 16084 At one stage in writing this document, for example, the Info file was saved | 18945 At one stage in writing this document, for example, the Info file was saved |
| 16085 as the file @file{test-texinfo} and that file looked like this:@refill | 18946 as the file @file{test-texinfo} and that file looked like this: |
| 16086 | 18947 |
| 16087 @example | 18948 @example |
| 16088 @group | 18949 @group |
| 16089 Info file: test-texinfo, -*-Text-*- | 18950 Info file: test-texinfo, -*-Text-*- |
| 16090 produced by texinfo-format-buffer | 18951 produced by texinfo-format-buffer |
| 16113 @noindent | 18974 @noindent |
| 16114 (But @file{test-texinfo} had far more nodes than are shown here.) Each of | 18975 (But @file{test-texinfo} had far more nodes than are shown here.) Each of |
| 16115 the split-off, indirect files, @file{test-texinfo-1}, | 18976 the split-off, indirect files, @file{test-texinfo-1}, |
| 16116 @file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file | 18977 @file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file |
| 16117 after the line that says @samp{Indirect:}. The tag table is listed after | 18978 after the line that says @samp{Indirect:}. The tag table is listed after |
| 16118 the line that says @samp{Tag table:}. @refill | 18979 the line that says @samp{Tag table:}. |
| 16119 | 18980 |
| 16120 In the list of indirect files, the number following the file name | 18981 In the list of indirect files, the number following the file name |
| 16121 records the cumulative number of bytes in the preceding indirect files, | 18982 records the cumulative number of bytes in the preceding indirect |
| 16122 not counting the file list itself, the tag table, or the permissions | 18983 files, not counting the file list itself, the tag table, or any |
| 16123 text in each file. In the tag table, the number following the node name | 18984 permissions text in the first file. In the tag table, the number |
| 16124 records the location of the beginning of the node, in bytes from the | 18985 following the node name records the location of the beginning of the |
| 16125 beginning of the (unsplit) output. | 18986 node, in bytes from the beginning of the (unsplit) output. |
| 16126 | 18987 |
| 16127 If you are using @code{texinfo-format-buffer} to create Info files, | 18988 If you are using @code{texinfo-format-buffer} to create Info files, |
| 16128 you may want to run the @code{Info-validate} command. (The | 18989 you may want to run the @code{Info-validate} command. (The |
| 16129 @code{makeinfo} command does such a good job on its own, you do not | 18990 @code{makeinfo} command does such a good job on its own, you do not |
| 16130 need @code{Info-validate}.) However, you cannot run the @kbd{M-x | 18991 need @code{Info-validate}.) However, you cannot run the @kbd{M-x |
| 16131 Info-validate} node-checking command on indirect files. For | 18992 Info-validate} node-checking command on indirect files. For |
| 16132 information on how to prevent files from being split and how to | 18993 information on how to prevent files from being split and how to |
| 16133 validate the structure of the nodes, see @ref{Using Info-validate}. | 18994 validate the structure of the nodes, see @ref{Using |
| 18995 @t{Info-validate}}. | |
| 16134 | 18996 |
| 16135 | 18997 |
| 16136 @node Installing an Info File | 18998 @node Installing an Info File |
| 16137 @section Installing an Info File | 18999 @section Installing an Info File |
| 16138 @cindex Installing an Info file | 19000 @cindex Installing an Info file |
| 16139 @cindex Info file installation | 19001 @cindex Info file installation |
| 16140 @cindex @file{dir} directory for Info installation | 19002 @cindex @file{dir} directory for Info installation |
| 16141 | 19003 |
| 16142 Info files are usually kept in the @file{info} directory. You can read | 19004 Info files are usually kept in the @file{info} directory. You can |
| 16143 Info files using the standalone Info program or the Info reader built | 19005 read Info files using the standalone Info program or the Info reader |
| 16144 into XEmacs. (@inforef{Top, info, info}, for an introduction to Info.) | 19006 built into XEmacs. (@xref{Top,,, info, Info}, for an introduction to |
| 19007 Info.) | |
| 16145 | 19008 |
| 16146 @menu | 19009 @menu |
| 16147 * Directory File:: The top level menu for all Info files. | 19010 * Directory File:: The top level menu for all Info files. |
| 16148 * New Info File:: Listing a new Info file. | 19011 * New Info File:: Listing a new Info file. |
| 16149 * Other Info Directories:: How to specify Info files that are | 19012 * Other Info Directories:: How to specify Info files that are |
| 16150 located in other directories. | 19013 located in other directories. |
| 16151 * Installing Dir Entries:: How to specify what menu entry to add | 19014 * Installing Dir Entries:: How to specify what menu entry to add |
| 16152 to the Info directory. | 19015 to the Info directory. |
| 16153 * Invoking install-info:: @code{install-info} options. | 19016 * Invoking @t{install-info}:: @code{install-info} options. |
| 16154 @end menu | 19017 @end menu |
| 16155 | 19018 |
| 16156 | 19019 |
| 16157 @node Directory File | 19020 @node Directory File |
| 16158 @subsection The Directory File @file{dir} | 19021 @subsection The Directory File @file{dir} |
| 16163 within XEmacs by typing @kbd{C-h i} to enter Info and then typing | 19026 within XEmacs by typing @kbd{C-h i} to enter Info and then typing |
| 16164 @kbd{C-x C-f} to see the pathname to the @file{info} directory.) | 19027 @kbd{C-x C-f} to see the pathname to the @file{info} directory.) |
| 16165 | 19028 |
| 16166 The @file{dir} file is itself an Info file. It contains the top level | 19029 The @file{dir} file is itself an Info file. It contains the top level |
| 16167 menu for all the Info files in the system. The menu looks like | 19030 menu for all the Info files in the system. The menu looks like |
| 16168 this:@refill | 19031 this: |
| 16169 | 19032 |
| 16170 @example | 19033 @example |
| 16171 @group | 19034 @group |
| 16172 * Menu: | 19035 * Menu: |
| 16173 * Info: (info). Documentation browsing system. | 19036 * Info: (info). Documentation browsing system. |
| 16174 * XEmacs: (xemacs). The extensible, self-documenting | 19037 * XEmacs: (xemacs). The extensible, self-documenting |
| 16175 text editor. | 19038 text editor. |
| 16176 * Texinfo: (texinfo). With one source file, make | 19039 * Texinfo: (texinfo). With one source file, make |
| 16177 either a printed manual using | 19040 either a printed manual using |
| 16178 @@TeX@{@} or an Info file. | 19041 @@TeX@{@} or an Info file. |
| 16179 @dots{} | 19042 @dots{} |
| 16180 @end group | 19043 @end group |
| 16181 @end example | 19044 @end example |
| 16182 | 19045 |
| 16183 Each of these menu entries points to the `Top' node of the Info file | 19046 Each of these menu entries points to the `Top' node of the Info file |
| 16184 that is named in parentheses. (The menu entry does not need to | 19047 that is named in parentheses. (The menu entry does not need to |
| 16185 specify the `Top' node, since Info goes to the `Top' node if no node | 19048 specify the `Top' node, since Info goes to the `Top' node if no node |
| 16186 name is mentioned. @xref{Other Info Files, , Nodes in Other Info | 19049 name is mentioned. @xref{Other Info Files, , Nodes in Other Info |
| 16187 Files}.)@refill | 19050 Files}.) |
| 16188 | 19051 |
| 16189 Thus, the @samp{Info} entry points to the `Top' node of the | 19052 Thus, the @samp{Info} entry points to the `Top' node of the |
| 16190 @file{info} file and the @samp{XEmacs} entry points to the `Top' node | 19053 @file{info} file and the @samp{XEmacs} entry points to the `Top' node |
| 16191 of the @file{xemacs} file.@refill | 19054 of the @file{xemacs} file. |
| 16192 | 19055 |
| 16193 In each of the Info files, the `Up' pointer of the `Top' node refers | 19056 In each of the Info files, the `Up' pointer of the `Top' node refers |
| 16194 back to the @code{dir} file. For example, the line for the `Top' | 19057 back to the @code{dir} file. For example, the line for the `Top' |
| 16195 node of the XEmacs manual looks like this in Info:@refill | 19058 node of the Emacs manual looks like this in Info: |
| 16196 | 19059 |
| 16197 @example | 19060 @example |
| 16198 File: xemacs Node: Top, Up: (DIR), Next: Distrib | 19061 File: xemacs Node: Top, Up: (DIR), Next: Distrib |
| 16199 @end example | 19062 @end example |
| 16200 | 19063 |
| 16201 @noindent | 19064 @noindent |
| 16202 In this case, the @file{dir} file name is written in upper case | 19065 In this case, the @file{dir} file name is written in uppercase |
| 16203 letters---it can be written in either upper or lower case. This is not | 19066 letters---it can be written in either upper- or lowercase. This is not |
| 16204 true in general, it is a special case for @file{dir}. | 19067 true in general, it is a special case for @file{dir}. |
| 16205 | 19068 |
| 16206 | 19069 |
| 16207 @node New Info File | 19070 @node New Info File |
| 16208 @subsection Listing a New Info File | 19071 @subsection Listing a New Info File |
| 16213 @cindex @file{dir} file listing | 19076 @cindex @file{dir} file listing |
| 16214 | 19077 |
| 16215 To add a new Info file to your system, you must write a menu entry to | 19078 To add a new Info file to your system, you must write a menu entry to |
| 16216 add to the menu in the @file{dir} file in the @file{info} directory. | 19079 add to the menu in the @file{dir} file in the @file{info} directory. |
| 16217 For example, if you were adding documentation for GDB, you would write | 19080 For example, if you were adding documentation for GDB, you would write |
| 16218 the following new entry:@refill | 19081 the following new entry: |
| 16219 | 19082 |
| 16220 @example | 19083 @example |
| 16221 * GDB: (gdb). The source-level C debugger. | 19084 * GDB: (gdb). The source-level C debugger. |
| 16222 @end example | 19085 @end example |
| 16223 | 19086 |
| 16242 @cindex Info installed in another directory | 19105 @cindex Info installed in another directory |
| 16243 @cindex Another Info directory | 19106 @cindex Another Info directory |
| 16244 @cindex @file{dir} files and Info directories | 19107 @cindex @file{dir} files and Info directories |
| 16245 | 19108 |
| 16246 If an Info file is not in the @file{info} directory, there are three | 19109 If an Info file is not in the @file{info} directory, there are three |
| 16247 ways to specify its location:@refill | 19110 ways to specify its location: |
| 16248 | 19111 |
| 16249 @enumerate | 19112 @enumerate |
| 16250 @item | 19113 @item |
| 16251 Write the pathname in the @file{dir} file as the second part of the menu. | 19114 Write the pathname in the @file{dir} file as the second part of the menu. |
| 19115 | |
| 19116 @item | |
| 19117 Specify the Info directory name in the @code{INFOPATH} environment | |
| 19118 variable in your @file{.profile} or @file{.cshrc} initialization file. | |
| 19119 (Only you and others who set this environment variable will be able to | |
| 19120 find Info files whose location is specified this way.) | |
| 16252 | 19121 |
| 16253 @item | 19122 @item |
| 16254 If you are using XEmacs, list the name of the file in a second @file{dir} | 19123 If you are using XEmacs, list the name of the file in a second @file{dir} |
| 16255 file, in its directory; and then add the name of that directory to the | 19124 file, in its directory; and then add the name of that directory to the |
| 16256 @code{Info-directory-list} variable in your personal or site | 19125 @code{Info-directory-list} variable in your personal or site |
| 16258 | 19127 |
| 16259 This variable tells XEmacs where to look for @file{dir} files (the files | 19128 This variable tells XEmacs where to look for @file{dir} files (the files |
| 16260 must be named @file{dir}). XEmacs merges the files named @file{dir} from | 19129 must be named @file{dir}). XEmacs merges the files named @file{dir} from |
| 16261 each of the listed directories. (In XEmacs version 18, you can set the | 19130 each of the listed directories. (In XEmacs version 18, you can set the |
| 16262 @code{Info-directory} variable to the name of only one | 19131 @code{Info-directory} variable to the name of only one |
| 16263 directory.)@refill | 19132 directory.) |
| 16264 | |
| 16265 @item | |
| 16266 Specify the Info directory name in the @code{INFOPATH} environment | |
| 16267 variable in your @file{.profile} or @file{.cshrc} initialization file. | |
| 16268 (Only you and others who set this environment variable will be able to | |
| 16269 find Info files whose location is specified this way.) | |
| 16270 @end enumerate | 19133 @end enumerate |
| 16271 | 19134 |
| 16272 For example, to reach a test file in the @file{/home/bob/info} | 19135 For example, to reach a test file in the @file{/home/bob/info} |
| 16273 directory, you could add an entry like this to the menu in the | 19136 directory, you could add an entry like this to the menu in the |
| 16274 standard @file{dir} file:@refill | 19137 standard @file{dir} file: |
| 16275 | 19138 |
| 16276 @example | 19139 @example |
| 16277 * Test: (/home/bob/info/info-test). Bob's own test file. | 19140 * Test: (/home/bob/info/info-test). Bob's own test file. |
| 16278 @end example | 19141 @end example |
| 16279 | 19142 |
| 16280 @noindent | 19143 @noindent |
| 16281 In this case, the absolute file name of the @file{info-test} file is | 19144 In this case, the absolute file name of the @file{info-test} file is |
| 16282 written as the second part of the menu entry.@refill | 19145 written as the second part of the menu entry. |
| 16283 | |
| 16284 Alternatively, you could write the following in your @file{init.el} file: | |
| 16285 | |
| 16286 @vindex Info-directory-list | |
| 16287 @example | |
| 16288 @group | |
| 16289 (require 'info) | |
| 16290 (setq Info-directory-list | |
| 16291 (cons (expand-file-name "/home/bob/info") | |
| 16292 Info-directory-list)) | |
| 16293 @end group | |
| 16294 @end example | |
| 16295 | |
| 16296 This tells XEmacs to merge the system @file{dir} file with the @file{dir} | |
| 16297 file in @file{/home/bob/info}. Thus, Info will list the | |
| 16298 @file{/home/bob/info/info-test} file as a menu entry in the | |
| 16299 @file{/home/bob/info/dir} file. XEmacs does the merging only when | |
| 16300 @kbd{M-x info} is first run, so if you want to set | |
| 16301 @code{Info-directory-list} in an XEmacs session where you've already run | |
| 16302 @code{info}, you must @code{(setq Info-dir-contents nil)} to force XEmacs | |
| 16303 to recompose the @file{dir} file. | |
| 16304 | 19146 |
| 16305 @vindex INFOPATH | 19147 @vindex INFOPATH |
| 16306 @cindex Environment variable @code{INFOPATH} | 19148 @cindex Environment variable @code{INFOPATH} |
| 16307 Finally, you can tell Info where to look by setting the @code{INFOPATH} | 19149 If you don't want to edit the system @file{dir} file, you can tell |
| 16308 environment variable in your shell startup file, such as @file{.cshrc}, | 19150 Info where to look by setting the @code{INFOPATH} environment variable |
| 16309 @file{.profile} or @file{autoexec.bat}. If you use a Bourne-compatible | 19151 in your shell startup file. This works with both the XEmacs and |
| 16310 shell such as @code{sh} or @code{bash} for your shell command | 19152 standalone Info readers. |
| 16311 interpreter, you set the @code{INFOPATH} environment variable in the | 19153 |
| 16312 @file{.profile} initialization file; but if you use @code{csh} or | 19154 Specifically, if you use a Bourne-compatible shell such as @code{sh} |
| 16313 @code{tcsh}, you set the variable in the @file{.cshrc} initialization | 19155 or @code{bash} for your shell command interpreter, you set the |
| 16314 file. On MS-DOS/MS-Windows systems, you must set @code{INFOPATH} in | 19156 @code{INFOPATH} environment variable in the @file{.profile} |
| 16315 your @file{autoexec.bat} file or in the Registry. Each type of shell | 19157 initialization file; but if you use @code{csh} or @code{tcsh}, you set |
| 16316 uses a different syntax. | 19158 the variable in the @file{.cshrc} initialization file. On |
| 19159 MS-DOS/MS-Windows systems, you must set @code{INFOPATH} in your | |
| 19160 @file{autoexec.bat} file or in the registry. Each type of shell uses | |
| 19161 a different syntax. | |
| 16317 | 19162 |
| 16318 @itemize @bullet | 19163 @itemize @bullet |
| 16319 @item | 19164 @item |
| 16320 In a @file{.cshrc} file, you could set the @code{INFOPATH} | 19165 In a @file{.cshrc} file, you could set the @code{INFOPATH} |
| 16321 variable as follows:@refill | 19166 variable as follows: |
| 16322 | 19167 |
| 16323 @smallexample | 19168 @smallexample |
| 16324 setenv INFOPATH .:~/info:/usr/local/xemacs/info | 19169 setenv INFOPATH .:~/info:/usr/local/xemacs/info |
| 16325 @end smallexample | 19170 @end smallexample |
| 16326 | 19171 |
| 16327 @item | 19172 @item |
| 16328 In a @file{.profile} file, you would achieve the same effect by | 19173 In a @file{.profile} file, you would achieve the same effect by writing: |
| 16329 writing:@refill | |
| 16330 | 19174 |
| 16331 @smallexample | 19175 @smallexample |
| 16332 INFOPATH=.:$HOME/info:/usr/local/xemacs/info | 19176 INFOPATH=.:$HOME/info:/usr/local/xemacs/info |
| 16333 export INFOPATH | 19177 export INFOPATH |
| 16334 @end smallexample | 19178 @end smallexample |
| 16335 | 19179 |
| 16336 @item | 19180 @item |
| 16337 @pindex autoexec.bat | 19181 @pindex autoexec.bat |
| 16338 In a @file{autoexec.bat} file, you write this command@footnote{Note the | 19182 In a @file{autoexec.bat} file, you write this command (note the |
| 16339 use of @samp{;} as the directory separator, and a different syntax for | 19183 use of @samp{;} as the directory separator, and a different syntax for |
| 16340 using values of other environment variables.}: | 19184 using values of other environment variables): |
| 16341 | 19185 |
| 16342 @smallexample | 19186 @smallexample |
| 16343 set INFOPATH=.;%HOME%/info;c:/usr/local/xemacs/info | 19187 set INFOPATH=.;%HOME%/info;c:/usr/local/Xemacs/info |
| 16344 @end smallexample | 19188 @end smallexample |
| 16345 @end itemize | 19189 @end itemize |
| 16346 | 19190 |
| 16347 @noindent | 19191 @noindent |
| 16348 The @samp{.} indicates the current directory as usual. XEmacs uses the | 19192 The @samp{.} indicates the current directory as usual. XEmacs uses the |
| 16349 @code{INFOPATH} environment variable to initialize the value of XEmacs's | 19193 @code{INFOPATH} environment variable to initialize the value of XEmacs's |
| 16350 own @code{Info-directory-list} variable. The stand-alone Info reader | 19194 own @code{Info-directory-list} variable. The standalone Info reader |
| 16351 merges any files named @file{dir} in any directory listed in the | 19195 merges any files named @file{dir} in any directory listed in the |
| 16352 @env{INFOPATH} variable into a single menu presented to you in the node | 19196 @env{INFOPATH} variable into a single menu presented to you in the node |
| 16353 called @samp{(dir)Top}. | 19197 called @samp{(dir)Top}. |
| 16354 | 19198 |
| 16355 @cindex Colon, last in @env{INFOPATH} | 19199 @cindex Colon, last in @env{INFOPATH} |
| 16356 However you set @env{INFOPATH}, if its last character is a | 19200 However you set @env{INFOPATH}, if its last character is a colon (on |
| 16357 colon@footnote{On MS-DOS/MS-Windows systems, use semi-colon instead.}, this | 19201 MS-DOS/MS-Windows systems, use a semicolon instead), this is replaced |
| 16358 is replaced by the default (compiled-in) path. This gives you a way to | 19202 by the default (compiled-in) path. This gives you a way to augment |
| 16359 augment the default path with new directories without having to list all | 19203 the default path with new directories without having to list all the |
| 16360 the standard places. For example (using @code{sh} syntax): | 19204 standard places. For example (using @code{sh} syntax): |
| 16361 | 19205 |
| 16362 @example | 19206 @example |
| 16363 INFOPATH=/local/info: | 19207 INFOPATH=/home/bob/info: |
| 16364 export INFOPATH | 19208 export INFOPATH |
| 16365 @end example | 19209 @end example |
| 16366 | 19210 |
| 16367 @noindent | 19211 @noindent |
| 16368 will search @file{/local/info} first, then the standard directories. | 19212 will search @file{/home/bob/info} first, then the standard directories. |
| 16369 Leading or doubled colons are not treated specially. | 19213 Leading or doubled colons are not treated specially. |
| 16370 | 19214 |
| 16371 @cindex @file{dir} file, creating your own | 19215 @cindex @file{dir} file, creating your own |
| 16372 When you create your own @file{dir} file for use with | 19216 When you create your own @file{dir} file for use with |
| 16373 @code{Info-directory-list} or @env{INFOPATH}, it's easiest to start by | 19217 @code{Info-directory-list} or @env{INFOPATH}, it's easiest to start by |
| 16374 copying an existing @file{dir} file and replace all the text after the | 19218 copying an existing @file{dir} file and replace all the text after the |
| 16375 @samp{* Menu:} with your desired entries. That way, the punctuation and | 19219 @samp{* Menu:} with your desired entries. That way, the punctuation |
| 16376 special CTRL-_ characters that Info needs will be present. | 19220 and special @kbd{CTRL-_} characters that Info needs will be present. |
| 19221 | |
| 19222 As one final alternative, which works only with XEmacs Info, you can | |
| 19223 change the @code{Info-directory-list} variable. For example: | |
| 19224 | |
| 19225 @example | |
| 19226 (add-hook 'Info-mode-hook '(lambda () | |
| 19227 (add-to-list 'Info-directory-list | |
| 19228 (expand-file-name "~/info")))) | |
| 19229 @end example | |
| 16377 | 19230 |
| 16378 | 19231 |
| 16379 @node Installing Dir Entries | 19232 @node Installing Dir Entries |
| 16380 @subsection Installing Info Directory Files | 19233 @subsection Installing Info Directory Files |
| 16381 | 19234 |
| 16429 start at column 32, starting at zero (as in | 19282 start at column 32, starting at zero (as in |
| 16430 @code{what-cursor-position} in XEmacs). This will make it align with | 19283 @code{what-cursor-position} in XEmacs). This will make it align with |
| 16431 most others. Description for individual utilities best start in | 19284 most others. Description for individual utilities best start in |
| 16432 column 48, where possible. For more information about formatting see | 19285 column 48, where possible. For more information about formatting see |
| 16433 the @samp{--calign}, @samp{--align}, and @samp{--max-width} options in | 19286 the @samp{--calign}, @samp{--align}, and @samp{--max-width} options in |
| 16434 @ref{Invoking install-info}. | 19287 @ref{Invoking @t{install-info}}. |
| 16435 | 19288 |
| 16436 If you use @code{@@dircategory} more than once in the Texinfo source, | 19289 If you use @code{@@dircategory} more than once in the Texinfo source, |
| 16437 each usage specifies the `current' category; any subsequent | 19290 each usage specifies the `current' category; any subsequent |
| 16438 @code{@@direntry} commands will add to that category. | 19291 @code{@@direntry} commands will add to that category. |
| 16439 | 19292 |
| 16464 corresponding @code{@@direntry}. This lets users easily find the | 19317 corresponding @code{@@direntry}. This lets users easily find the |
| 16465 documentation for the different programs they can run, as with the | 19318 documentation for the different programs they can run, as with the |
| 16466 traditional @command{man} system. | 19319 traditional @command{man} system. |
| 16467 | 19320 |
| 16468 | 19321 |
| 16469 @node Invoking install-info | 19322 @node Invoking @t{install-info} |
| 16470 @subsection Invoking @command{install-info} | 19323 @subsection Invoking @command{install-info} |
| 19324 | |
| 16471 @pindex install-info | 19325 @pindex install-info |
| 16472 | 19326 |
| 16473 @code{install-info} inserts menu entries from an Info file into the | 19327 @code{install-info} inserts menu entries from an Info file into the |
| 16474 top-level @file{dir} file in the Info system (see the previous sections | 19328 top-level @file{dir} file in the Info system (see the previous sections |
| 16475 for an explanation of how the @file{dir} file works). @code{install-info} | 19329 for an explanation of how the @file{dir} file works). @code{install-info} |
| 16476 also removes menu entries from the @file{dir} file. It's most often | 19330 also removes menu entries from the @file{dir} file. It's most often |
| 16477 run as part of software installation, or when constructing a @file{dir} file | 19331 run as part of software installation, or when constructing a @file{dir} file |
| 16478 for all manuals on a system. Synopsis: | 19332 for all manuals on a system. Synopsis: |
| 16479 | 19333 |
| 16480 @example | 19334 @example |
| 16489 @cindex @file{dir}, created by @code{install-info} | 19343 @cindex @file{dir}, created by @code{install-info} |
| 16490 If @var{dir-file} (however specified) does not exist, | 19344 If @var{dir-file} (however specified) does not exist, |
| 16491 @code{install-info} creates it if possible (with no entries). | 19345 @code{install-info} creates it if possible (with no entries). |
| 16492 | 19346 |
| 16493 @cindex Compressed dir files, reading | 19347 @cindex Compressed dir files, reading |
| 19348 @cindex XZ-compressed dir files, reading | |
| 16494 @cindex Bzipped dir files, reading | 19349 @cindex Bzipped dir files, reading |
| 19350 @cindex Lzip-compressed dir files, reading | |
| 16495 @cindex LZMA-compressed dir files, reading | 19351 @cindex LZMA-compressed dir files, reading |
| 16496 @cindex Dir files, compressed | 19352 @cindex Dir files, compressed |
| 16497 If any input file is compressed with @code{gzip} (@pxref{Top,,,gzip, | 19353 If any input file is compressed with @code{gzip} (@pxref{Top,,, gzip, |
| 16498 Gzip}), @code{install-info} automatically uncompresses it | 19354 Gzip}), @code{install-info} automatically uncompresses it for reading. |
| 16499 for reading. And if @var{dir-file} is compressed, @code{install-info} | 19355 And if @var{dir-file} is compressed, @code{install-info} also |
| 16500 also automatically leaves it compressed after writing any changes. | 19356 automatically leaves it compressed after writing any changes. If |
| 16501 If @var{dir-file} itself does not exist, @code{install-info} tries to | 19357 @var{dir-file} itself does not exist, @code{install-info} tries to |
| 16502 open @file{@var{dir-file}.gz}, @file{@var{dir-file}.bz2}, and | 19358 open @file{@var{dir-file}.gz}, @file{@var{dir-file}.xz}, |
| 19359 @file{@var{dir-file}.bz2}, @file{@var{dir-file}.lz}, and | |
| 16503 @file{@var{dir-file}.lzma}, in that order. | 19360 @file{@var{dir-file}.lzma}, in that order. |
| 16504 | 19361 |
| 16505 Options: | 19362 Options: |
| 16506 | 19363 |
| 16507 @table @code | 19364 @table @code |
| 16508 @item --add-once | 19365 @item --add-once |
| 19366 @opindex --add-once@r{, for @command{install-info}} | |
| 16509 Specifies that the entry or entries will only be put into a single section. | 19367 Specifies that the entry or entries will only be put into a single section. |
| 16510 | 19368 |
| 16511 @item --align=@var{column} | 19369 @item --align=@var{column} |
| 16512 @opindex --align=@var{column} | 19370 @opindex --align=@var{column}@r{, for @command{install-info}} |
| 16513 Specifies the column that the second and subsequent lines of menu entry's | 19371 Specifies the column that the second and subsequent lines of menu entry's |
| 16514 description will be formatted to begin at. The default for this option is | 19372 description will be formatted to begin at. The default for this option is |
| 16515 @samp{35}. It is used in conjunction with the @samp{--max-width} option. | 19373 @samp{35}. It is used in conjunction with the @samp{--max-width} option. |
| 16516 @var{column} starts counting at 1. | 19374 @var{column} starts counting at 1. |
| 16517 | 19375 |
| 16518 @item --append-new-sections | 19376 @item --append-new-sections |
| 19377 @opindex --append-new-sections@r{, for @command{install-info}} | |
| 16519 Instead of alphabetizing new sections, place them at the end of the DIR file. | 19378 Instead of alphabetizing new sections, place them at the end of the DIR file. |
| 16520 | 19379 |
| 16521 @item --calign=@var{column} | 19380 @item --calign=@var{column} |
| 16522 @opindex --calign=@var{column} | 19381 @opindex --calign=@var{column}@r{, for @command{install-info}} |
| 16523 Specifies the column that the first line of menu entry's description will | 19382 Specifies the column that the first line of menu entry's description will |
| 16524 be formatted to begin at. The default for this option is @samp{33}. It is | 19383 be formatted to begin at. The default for this option is @samp{33}. It is |
| 16525 used in conjunction with the @samp{--max-width} option. | 19384 used in conjunction with the @samp{--max-width} option. |
| 16526 When the name of the menu entry exceeds this column, entry's description | 19385 When the name of the menu entry exceeds this column, entry's description |
| 16527 will start on the following line. | 19386 will start on the following line. |
| 16528 @var{column} starts counting at 1. | 19387 @var{column} starts counting at 1. |
| 16529 | 19388 |
| 16530 @item --debug | 19389 @item --debug |
| 16531 @opindex --debug | 19390 @opindex --debug@r{, for @command{install-info}} |
| 16532 Report what is being done. | 19391 Report what is being done. |
| 16533 | 19392 |
| 16534 @item --delete | 19393 @item --delete |
| 16535 @opindex --delete | 19394 @opindex --delete@r{, for @command{install-info}} |
| 16536 Delete the entries in @var{info-file} from @var{dir-file}. The file | 19395 Delete the entries in @var{info-file} from @var{dir-file}. The file |
| 16537 name in the entry in @var{dir-file} must be @var{info-file} (except for | 19396 name in the entry in @var{dir-file} must be @var{info-file} (except for |
| 16538 an optional @samp{.info} in either one). Don't insert any new entries. | 19397 an optional @samp{.info} in either one). Don't insert any new entries. |
| 16539 Any empty sections that result from the removal are also removed. | 19398 Any empty sections that result from the removal are also removed. |
| 16540 | 19399 |
| 16541 @item --description=@var{text} | 19400 @item --description=@var{text} |
| 16542 @opindex --description=@var{text} | 19401 @opindex --description=@var{text}@r{, for @command{install-info}} |
| 16543 Specify the explanatory portion of the menu entry. If you don't specify | 19402 Specify the explanatory portion of the menu entry. If you don't specify |
| 16544 a description (either via @samp{--entry}, @samp{--item} or this option), | 19403 a description (either via @samp{--entry}, @samp{--item} or this option), |
| 16545 the description is taken from the Info file itself. | 19404 the description is taken from the Info file itself. |
| 16546 | 19405 |
| 16547 @item --dir-file=@var{name} | 19406 @item --dir-file=@var{name} |
| 16548 @opindex --dir-file=@var{name} | 19407 @opindex --dir-file=@var{name}@r{, for @command{install-info}} |
| 16549 Specify file name of the Info directory file. This is equivalent to | 19408 Specify file name of the Info directory file. This is equivalent to |
| 16550 using the @var{dir-file} argument. | 19409 using the @var{dir-file} argument. |
| 16551 | 19410 |
| 16552 @item --dry-run | 19411 @item --dry-run |
| 16553 @opindex --dry-run | 19412 @opindex --dry-run@r{, for @command{install-info}} |
| 16554 Same as @samp{--test}. | 19413 Same as @samp{--test}. |
| 16555 | 19414 |
| 16556 @item --entry=@var{text} | 19415 @item --entry=@var{text} |
| 16557 @opindex --entry=@var{text} | 19416 @opindex --entry=@var{text}@r{, for @command{install-info}} |
| 16558 Insert @var{text} as an Info directory entry; @var{text} should have the | 19417 Insert @var{text} as an Info directory entry; @var{text} should have the |
| 16559 form of an Info menu item line plus zero or more extra lines starting | 19418 form of an Info menu item line plus zero or more extra lines starting |
| 16560 with whitespace. If you specify more than one entry, they are all | 19419 with whitespace. If you specify more than one entry, they are all |
| 16561 added. If you don't specify any entries, they are determined from | 19420 added. If you don't specify any entries, they are determined from |
| 16562 information in the Info file itself. | 19421 information in the Info file itself. |
| 16563 | 19422 |
| 16564 @item --help | 19423 @item --help |
| 16565 @opindex --help | 19424 @opindex --help@r{, for @command{texindex}} |
| 16566 Display a usage message with basic usage and all available options, | 19425 Display a usage message with basic usage and all available options, |
| 16567 then exit successfully. | 19426 then exit successfully. |
| 16568 | 19427 |
| 16569 @item --info-file=@var{file} | 19428 @item --info-file=@var{file} |
| 16570 @opindex --info-file=@var{file} | 19429 @opindex --info-file=@var{file}@r{, for @command{install-info}} |
| 16571 Specify Info file to install in the directory. This is | 19430 Specify Info file to install in the directory. This is |
| 16572 equivalent to using the @var{info-file} argument. | 19431 equivalent to using the @var{info-file} argument. |
| 16573 | 19432 |
| 16574 @item --info-dir=@var{dir} | 19433 @item --info-dir=@var{dir} |
| 16575 @opindex --info-dir=@var{dir} | 19434 @opindex --info-dir=@var{dir}@r{, for @command{install-info}} |
| 16576 Specify the directory where the directory file @file{dir} resides. | 19435 Specify the directory where the directory file @file{dir} resides. |
| 16577 Equivalent to @samp{--dir-file=@var{dir}/dir}. | 19436 Equivalent to @samp{--dir-file=@var{dir}/dir}. |
| 16578 | 19437 |
| 16579 @item --infodir=@var{dir} | 19438 @item --infodir=@var{dir} |
| 16580 @opindex --infodir=@var{dir} | 19439 @opindex --infodir=@var{dir}@r{, for @command{install-info}} |
| 16581 Same as @samp{--info-dir}. | 19440 Same as @samp{--info-dir}. |
| 16582 | 19441 |
| 16583 @item --item=@var{text} | 19442 @item --item=@var{text} |
| 16584 @opindex --item=@var{text} | 19443 @opindex --item=@var{text}@r{, for @command{install-info}} |
| 16585 Same as @samp{--entry=@var{text}}. An Info directory entry is actually | 19444 Same as @samp{--entry=@var{text}}. An Info directory entry is actually |
| 16586 a menu item. | 19445 a menu item. |
| 16587 | 19446 |
| 16588 @item --keep-old | 19447 @item --keep-old |
| 16589 @opindex --keep-old | 19448 @opindex --keep-old@r{, for @command{install-info}} |
| 16590 Do not replace pre-existing menu entries. When @samp{--remove} is specified, | 19449 Do not replace pre-existing menu entries. When @samp{--remove} is specified, |
| 16591 this option means that empty sections are not removed. | 19450 this option means that empty sections are not removed. |
| 16592 | 19451 |
| 16593 @item --max-width=@var{column} | 19452 @item --max-width=@var{column} |
| 16594 @opindex --max-width=@var{column} | 19453 @opindex --max-width=@var{column}@r{, for @command{install-info}} |
| 16595 Specifies the column that the menu entry's description will be word-wrapped | 19454 Specifies the column that the menu entry's description will be word-wrapped |
| 16596 at. @var{column} starts counting at 1. | 19455 at. @var{column} starts counting at 1. |
| 16597 | 19456 |
| 16598 @item --maxwidth=@var{column} | 19457 @item --maxwidth=@var{column} |
| 16599 @opindex --maxwidth=@var{column} | 19458 @opindex --maxwidth=@var{column}@r{, for @command{install-info}} |
| 16600 Same as @samp{--max-width}. | 19459 Same as @samp{--max-width}. |
| 16601 | 19460 |
| 16602 @item --menuentry=@var{text} | 19461 @item --menuentry=@var{text} |
| 16603 @opindex --menuentry=@var{text} | 19462 @opindex --menuentry=@var{text}@r{, for @command{install-info}} |
| 16604 Same as @samp{--name}. | 19463 Same as @samp{--name}. |
| 16605 | 19464 |
| 16606 @item --name=@var{text} | 19465 @item --name=@var{text} |
| 16607 @opindex --name=@var{text} | 19466 @opindex --name=@var{text}@r{, for @command{install-info}} |
| 16608 Specify the name portion of the menu entry. If the @var{text} does | 19467 Specify the name portion of the menu entry. If the @var{text} does |
| 16609 not start with an asterisk @samp{*}, it is presumed to be the text | 19468 not start with an asterisk @samp{*}, it is presumed to be the text |
| 16610 after the @samp{*} and before the parentheses that specify the Info | 19469 after the @samp{*} and before the parentheses that specify the Info |
| 16611 file. Otherwise @var{text} is taken verbatim, and is taken as | 19470 file. Otherwise @var{text} is taken verbatim, and is taken as |
| 16612 defining the text up to and including the first period (a space is | 19471 defining the text up to and including the first period (a space is |
| 16614 @samp{--entry}, @samp{--item} or this option), it is taken from the | 19473 @samp{--entry}, @samp{--item} or this option), it is taken from the |
| 16615 Info file itself. If the Info does not contain the name, the basename | 19474 Info file itself. If the Info does not contain the name, the basename |
| 16616 of the Info file is used. | 19475 of the Info file is used. |
| 16617 | 19476 |
| 16618 @item --no-indent | 19477 @item --no-indent |
| 16619 @opindex --no-indent | 19478 @opindex --no-indent@r{, for @command{install-info}} |
| 16620 Suppress formatting of new entries into the @file{dir} file. | 19479 Suppress formatting of new entries into the @file{dir} file. |
| 16621 | 19480 |
| 16622 @item --quiet | 19481 @item --quiet |
| 16623 @opindex --quiet | |
| 16624 @itemx --silent | 19482 @itemx --silent |
| 16625 @opindex --silent | 19483 @opindex --quiet@r{, for @command{install-info}} |
| 19484 @opindex --silent@r{, for @command{install-info}} | |
| 16626 Suppress warnings, etc., for silent operation. | 19485 Suppress warnings, etc., for silent operation. |
| 16627 | 19486 |
| 16628 @item --remove | 19487 @item --remove |
| 16629 @opindex --remove | 19488 @opindex --remove@r{, for @command{install-info}} |
| 16630 Same as @samp{--delete}. | 19489 Same as @samp{--delete}. |
| 16631 | 19490 |
| 16632 @item --remove-exactly | 19491 @item --remove-exactly |
| 16633 @opindex --remove-exactly | 19492 @opindex --remove-exactly@r{, for @command{install-info}} |
| 16634 Also like @samp{--delete}, but only entries if the Info file name | 19493 Also like @samp{--delete}, but only entries if the Info file name |
| 16635 matches exactly; @code{.info} and/or @code{.gz} suffixes are | 19494 matches exactly; @code{.info} and/or @code{.gz} suffixes are |
| 16636 @emph{not} ignored. | 19495 @emph{not} ignored. |
| 16637 | 19496 |
| 16638 @item --section=@var{sec} | 19497 @item --section=@var{sec} |
| 16639 @opindex --section=@var{sec} | 19498 @opindex --section=@var{sec}@r{, for @command{install-info}} |
| 16640 Put this file's entries in section @var{sec} of the directory. If you | 19499 Put this file's entries in section @var{sec} of the directory. If you |
| 16641 specify more than one section, all the entries are added in each of the | 19500 specify more than one section, all the entries are added in each of the |
| 16642 sections. If you don't specify any sections, they are determined from | 19501 sections. If you don't specify any sections, they are determined from |
| 16643 information in the Info file itself. If the Info file doesn't specify | 19502 information in the Info file itself. If the Info file doesn't specify |
| 16644 a section, the menu entries are put into the Miscellaneous section. | 19503 a section, the menu entries are put into the Miscellaneous section. |
| 16645 | 19504 |
| 16646 @item --section @var{regex} @var{sec} | 19505 @item --section @var{regex} @var{sec} |
| 16647 @opindex --section @var{regex} @var{sec} | 19506 @opindex --section @var{regex} @var{sec}@r{, for @command{install-info}} |
| 16648 Same as @samp{--regex=@var{regex} --section=@var{sec} --add-once}. | 19507 Same as @samp{--regex=@var{regex} --section=@var{sec} --add-once}. |
| 16649 | 19508 |
| 16650 @code{install-info} tries to detect when this alternate syntax is used, | 19509 @code{install-info} tries to detect when this alternate syntax is used, |
| 16651 but does not always guess correctly. Here is the heuristic that | 19510 but does not always guess correctly. Here is the heuristic that |
| 16652 @code{install-info} uses: | 19511 @code{install-info} uses: |
| 16653 @enumerate | 19512 @enumerate |
| 16654 @item | 19513 @item |
| 16655 If the second argument to @code{--section} starts with a hyphen, the | 19514 If the second argument to @code{--section} starts with a hyphen, the |
| 16656 original syntax is presumed. | 19515 original syntax is presumed. |
| 19516 | |
| 16657 @item | 19517 @item |
| 16658 If the second argument to @code{--section} is a file that can be | 19518 If the second argument to @code{--section} is a file that can be |
| 16659 opened, the original syntax is presumed. | 19519 opened, the original syntax is presumed. |
| 19520 | |
| 16660 @item | 19521 @item |
| 16661 Otherwise the alternate syntax is used. | 19522 Otherwise the alternate syntax is used. |
| 16662 @end enumerate | 19523 @end enumerate |
| 16663 | 19524 |
| 16664 When heuristic fails because your section title starts with a hyphen, or it | 19525 When the heuristic fails because your section title starts with a |
| 16665 happens to be a filename that can be opened, the syntax should be changed | 19526 hyphen, or it happens to be a filename that can be opened, the syntax |
| 16666 to @samp{--regex=@var{regex} --section=@var{sec} --add-once}. | 19527 should be changed to @samp{--regex=@var{regex} --section=@var{sec} |
| 16667 | 19528 --add-once}. |
| 16668 | 19529 |
| 16669 @item --regex=@var{regex} | 19530 @item --regex=@var{regex} |
| 16670 @opindex --regex=@var{regex} | 19531 @opindex --regex=@var{regex}@r{, for @command{install-info}} |
| 16671 Put this file's entries into any section that matches @var{regex}. If | 19532 Put this file's entries into any section that matches @var{regex}. If |
| 16672 more than one section matches, all of the entries are added in each of the | 19533 more than one section matches, all of the entries are added in each of the |
| 16673 sections. Specify @var{regex} using basic regular expression syntax, more | 19534 sections. Specify @var{regex} using basic regular expression syntax, more |
| 16674 or less as used with @command{grep}, for example. | 19535 or less as used with @command{grep}, for example. |
| 16675 | 19536 |
| 16676 @item --test | 19537 @item --test |
| 16677 @opindex --test | 19538 @opindex --test@r{, for @command{install-info}} |
| 16678 Suppress updating of the directory file. | 19539 Suppress updating of the directory file. |
| 16679 | 19540 |
| 16680 @item --version | 19541 @item --version |
| 16681 @opindex --version | 19542 @opindex --version@r{, for @command{install-info}} |
| 16682 @cindex Version number, for install-info | 19543 @cindex Version number, for install-info |
| 16683 Display version information and exit successfully. | 19544 Display version information and exit successfully. |
| 16684 | 19545 |
| 16685 @end table | 19546 @end table |
| 16686 | 19547 |
| 16687 | 19548 |
| 16688 @node Generating HTML | 19549 @node Generating HTML |
| 16689 @chapter Generating HTML | 19550 @chapter Generating HTML |
| 16690 @cindex HTML output | 19551 |
| 19552 @cindex Generating HTML | |
| 19553 @cindex Outputting HTML | |
| 16691 | 19554 |
| 16692 @command{makeinfo} generates Info output by default, but given the | 19555 @command{makeinfo} generates Info output by default, but given the |
| 16693 @option{--html} option, it will generate HTML, for web browsers and | 19556 @option{--html} option, it will generate HTML, for web browsers and |
| 16694 other programs. This chapter gives some details on such HTML output. | 19557 other programs. This chapter gives some details on such HTML output. |
| 16695 | 19558 |
| 16696 | 19559 @command{makeinfo} has many user-definable customization variables |
| 16697 @command{makeinfo} can also write in XML and Docbook format, but we do | 19560 with which you can influence the HTML output. @xref{Customization |
| 16698 not as yet describe these further. @xref{Output Formats}, for a brief | 19561 Variables}. |
| 16699 overview of all the output formats. | 19562 |
| 19563 @command{makeinfo} can also produce output in XML and Docbook formats, | |
| 19564 but we do not as yet describe these in detail. @xref{Output Formats}, | |
| 19565 for a brief overview of all the output formats. | |
| 16700 | 19566 |
| 16701 @menu | 19567 @menu |
| 16702 * HTML Translation:: Details of the HTML output. | 19568 * HTML Translation:: Details of the HTML output. |
| 16703 * HTML Splitting:: How HTML output is split. | 19569 * HTML Splitting:: How HTML output is split. |
| 16704 * HTML CSS:: Influencing HTML output with Cascading Style Sheets. | 19570 * HTML CSS:: Influencing HTML output with Cascading Style Sheets. |
| 16705 * HTML Xref:: Cross-references in HTML output. | 19571 * HTML Xref:: Cross references in HTML output. |
| 16706 @end menu | 19572 @end menu |
| 16707 | 19573 |
| 16708 | 19574 |
| 16709 @node HTML Translation | 19575 @node HTML Translation |
| 16710 @section HTML Translation | 19576 @section HTML Translation |
| 16715 @code{@@html} and @code{@@end html} is passed without change to the | 19581 @code{@@html} and @code{@@end html} is passed without change to the |
| 16716 output (i.e., suppressing the normal escaping of input @samp{<}, | 19582 output (i.e., suppressing the normal escaping of input @samp{<}, |
| 16717 @samp{>} and @samp{&} characters which have special significance in | 19583 @samp{>} and @samp{&} characters which have special significance in |
| 16718 HTML). @xref{Conditional Commands}. | 19584 HTML). @xref{Conditional Commands}. |
| 16719 | 19585 |
| 16720 @opindex --footnote-style@r{, ignored in HTML output} | |
| 16721 The @option{--footnote-style} option is currently ignored for HTML output; | |
| 16722 footnotes are always linked to the end of the output file. | |
| 16723 | |
| 16724 @cindex Navigation bar, in HTML output | 19586 @cindex Navigation bar, in HTML output |
| 16725 By default, a navigation bar is inserted at the start of each node, | 19587 By default, a navigation bar is inserted at the start of each node, |
| 16726 analogous to Info output. The @samp{--no-headers} option suppresses | 19588 analogous to Info output. If the @samp{--no-headers} option is used, |
| 16727 this if used with @samp{--no-split}. Header @code{<link>} elements in | 19589 the navigation bar is only inserted at the beginning of split files. |
| 16728 split output can support info-like navigation with browsers like Lynx | 19590 Header @code{<link>} elements in split output can support Info-like |
| 16729 and @w{Emacs W3} which implement this HTML@tie{}1.0 feature. | 19591 navigation with browsers like Lynx and @w{XEmacs W3} which implement |
| 19592 this HTML@tie{}1.0 feature. | |
| 19593 | |
| 19594 @cindex Footnote styles, in HTML | |
| 19595 In HTML, when the footnote style is @samp{end}, or if the output is | |
| 19596 not split, footnotes are put at the end of the output. If set to | |
| 19597 @samp{separate}, and the output is split, they are placed in a | |
| 19598 separate file. @xref{Footnote Styles}. | |
| 16730 | 19599 |
| 16731 @cindex HTML output, browser compatibility of | 19600 @cindex HTML output, browser compatibility of |
| 16732 The HTML generated is mostly standard (i.e., HTML@tie{}2.0, RFC-1866). | 19601 The HTML generated is standard HTML@tie{}4. It also tries to be as |
| 16733 One exception is that HTML@tie{}3.2 tables are generated from the | 19602 compatible as possible with earlier standards (e.g., HTML@tie{}2.0, |
| 16734 @code{@@multitable} command, but tagged to degrade as well as possible | 19603 RFC-1866). Some minor exceptions: 1)@tie{}HTML@tie{}3.2 tables are |
| 16735 in browsers without table support. The HTML@tie{}4 @samp{lang} | 19604 generated for the @code{@@multitable} command (@pxref{Multi-column |
| 16736 attribute on the @samp{<html>} attribute is also used. (Please report | 19605 Tables}), but they should degrade reasonably in browsers without table |
| 16737 output from an error-free run of @code{makeinfo} which has browser | 19606 support; 2)@tie{}The HTML@tie{}4 @samp{lang} attribute on the |
| 16738 portability problems as a bug.) | 19607 @samp{<html>} attribute is used; 3)@tie{} Entities that are not in the |
| 19608 HTML@tie{}3.2 standard are also used. 4)@tie{} CSS is used | |
| 19609 (@pxref{HTML CSS}). 5)@tie{} A few HTML@tie{}4 elements are used | |
| 19610 (@code{thead}, @code{abbr}, @code{acronym}). | |
| 19611 | |
| 19612 Using @samp{--init-file=html32.pm} produces strict HTML@tie{}3.2 | |
| 19613 output (@pxref{Invoking @t{texi2any}}). | |
| 19614 | |
| 19615 Please report output from an error-free run of @code{makeinfo} which | |
| 19616 has browser portability problems as a bug (@pxref{Reporting Bugs}). | |
| 16739 | 19617 |
| 16740 | 19618 |
| 16741 @node HTML Splitting | 19619 @node HTML Splitting |
| 16742 @section HTML Splitting | 19620 @section HTML Splitting |
| 16743 @cindex Split HTML output | 19621 @cindex Split HTML output |
| 16744 @cindex HTML output, split | 19622 @cindex HTML output, split |
| 16745 | 19623 |
| 16746 When splitting output (which is the default), @command{makeinfo} | 19624 When splitting output at nodes (which is the default), |
| 16747 writes HTML output into (generally) one output file per Texinfo source | 19625 @command{makeinfo} writes HTML output into (basically) one output file |
| 16748 @code{@@node}. | 19626 per Texinfo source @code{@@node}. |
| 16749 | 19627 |
| 16750 The output file name is the node name with special characters replaced | 19628 Each output file name is the node name with spaces replaced by |
| 16751 by @samp{-}'s, so it can work as a filename. In the unusual case of | 19629 @samp{-}'s and special characters changed to @samp{_} followed by |
| 16752 two different nodes having the same name after this treatment, they | 19630 their code point in hex (@pxref{HTML Xref}). This is to make it |
| 16753 are written consecutively to the same file, with HTML anchors so each | 19631 portable and easy to use as a filename. In the unusual case of two |
| 16754 can be referred to separately. If @command{makeinfo} is run on a | 19632 different nodes having the same name after this treatment, they are |
| 16755 system which does not distinguish case in filenames, nodes which are | 19633 written consecutively to the same file, with HTML anchors so each can |
| 16756 the same except for case will also be folded into the same output | 19634 be referred to independently. |
| 16757 file. | 19635 |
| 19636 If @command{makeinfo} is run on a system which does not distinguish | |
| 19637 case in file names, nodes which are the same except for case (e.g., | |
| 19638 @samp{index} and @samp{Index}) will also be folded into the same | |
| 19639 output file with anchors. You can also pretend to be on a case | |
| 19640 insensitive filesystem by setting the customization variable | |
| 19641 @code{CASE_INSENSITIVE_FILENAMES}. | |
| 19642 | |
| 19643 It is also possible to split at chapters or sections with | |
| 19644 @option{--split} (@pxref{Invoking @t{texi2any}}). In that case, | |
| 19645 the file names are constructed after the name of the node associated | |
| 19646 with the relevant sectioning command. Also, unless | |
| 19647 @option{--no-node-files} is specified, a redirection file is output | |
| 19648 for every node in order to more reliably support cross references to | |
| 19649 that manual (@pxref{HTML Xref}). | |
| 16758 | 19650 |
| 16759 When splitting, the HTML output files are written into a subdirectory, | 19651 When splitting, the HTML output files are written into a subdirectory, |
| 16760 with the name chosen as follows: | 19652 with the name chosen as follows: |
| 19653 | |
| 16761 @enumerate | 19654 @enumerate |
| 16762 @item | 19655 @item |
| 16763 @command{makeinfo} first tries the subdirectory with the base name | 19656 @command{makeinfo} first tries the subdirectory with the base name |
| 16764 from @code{@@setfilename} (that is, any extension is removed). For | 19657 from @code{@@setfilename} (that is, any extension is removed). For |
| 16765 example, HTML output for @code{@@setfilename gcc.info} would be | 19658 example, HTML output for @code{@@setfilename gcc.info} would be |
| 16766 written into a subdirectory named @samp{gcc}. | 19659 written into a subdirectory named @samp{gcc/}. |
| 16767 | 19660 |
| 16768 @item | 19661 @item |
| 16769 If that directory cannot be created for any reason, then | 19662 If that directory cannot be created for any reason, then |
| 16770 @command{makeinfo} tries appending @samp{.html} to the directory name. | 19663 @command{makeinfo} tries appending @samp{.html} to the directory name. |
| 16771 For example, output for @code{@@setfilename texinfo} would be written | 19664 For example, output for @code{@@setfilename texinfo} would be written |
| 16772 to @samp{texinfo.html}. | 19665 to @samp{texinfo.html/}. |
| 16773 | 19666 |
| 16774 @item | 19667 @item |
| 16775 If the @samp{@var{name}.html} directory can't be | 19668 If the @samp{@var{name}.html} directory can't be created either, |
| 16776 created either, @code{makeinfo} gives up. | 19669 @code{makeinfo} gives up. |
| 16777 | 19670 |
| 16778 @end enumerate | 19671 @end enumerate |
| 16779 | 19672 |
| 16780 @noindent In any case, the top-level output file within the directory | 19673 @noindent In any case, the top-level output file within the directory |
| 16781 is always named @samp{index.html}. | 19674 is always named @samp{index.html}. |
| 16782 | 19675 |
| 16783 Monolithic output (@code{--no-split}) is named according to | 19676 Monolithic output (@code{--no-split}) is named according to |
| 16784 @code{@@setfilename} (with any @samp{.info} extension is replaced with | 19677 @code{@@setfilename} (with any @samp{.info} extension is replaced with |
| 16785 @samp{.html}) or @code{--output} (the argument is used literally). | 19678 @samp{.html}), @code{--output} (the argument is used literally), or |
| 19679 based on the input file name as a last resort | |
| 19680 (@pxref{@t{@@setfilename}}). | |
| 16786 | 19681 |
| 16787 | 19682 |
| 16788 @node HTML CSS | 19683 @node HTML CSS |
| 16789 @section HTML CSS | 19684 @section HTML CSS |
| 16790 @cindex HTML, and CSS | 19685 @cindex HTML, and CSS |
| 16794 Cascading Style Sheets (CSS for short) is an Internet standard for | 19689 Cascading Style Sheets (CSS for short) is an Internet standard for |
| 16795 influencing the display of HTML documents: see | 19690 influencing the display of HTML documents: see |
| 16796 @uref{http://www.w3.org/Style/CSS/}. | 19691 @uref{http://www.w3.org/Style/CSS/}. |
| 16797 | 19692 |
| 16798 By default, @command{makeinfo} includes a few simple CSS commands to | 19693 By default, @command{makeinfo} includes a few simple CSS commands to |
| 16799 better implement the appearance of some of the environments. Here | 19694 better implement the appearance of some Texinfo environments. Here |
| 16800 are two of them, as an example: | 19695 are two of them, as an example: |
| 16801 | 19696 |
| 16802 @example | 19697 @example |
| 16803 pre.display @{ font-family:inherit @} | 19698 pre.display @{ font-family:inherit @} |
| 16804 pre.smalldisplay @{ font-family:inherit; font-size:smaller @} | 19699 pre.smalldisplay @{ font-family:inherit; font-size:smaller @} |
| 16805 @end example | 19700 @end example |
| 16806 | 19701 |
| 16807 A full explanation of CSS is (far) beyond this manual; please see the | 19702 A full explanation of CSS is (far) beyond this manual; please see the |
| 16808 reference above. In brief, however, this specification tells the web | 19703 reference above. In brief, however, the above tells the web browser |
| 16809 browser to use a `smaller' font size for @code{@@smalldisplay} text, | 19704 to use a `smaller' font size for @code{@@smalldisplay} text, and to |
| 16810 and to use the `inherited' font (generally a regular roman typeface) | 19705 use the same font as the main document for both @code{@@smalldisplay} |
| 16811 for both @code{@@smalldisplay} and @code{@@display}. By default, the | 19706 and @code{@@display}. By default, the HTML @samp{<pre>} command uses |
| 16812 HTML @samp{<pre>} command uses a monospaced font. | 19707 a monospaced font. |
| 16813 | 19708 |
| 16814 You can influence the CSS in the HTML output with two | 19709 You can influence the CSS in the HTML output with two |
| 16815 @command{makeinfo} options: @option{--css-include=@var{file}} and | 19710 @command{makeinfo} options: @option{--css-include=@var{file}} and |
| 16816 @option{--css-ref=@var{url}}. | 19711 @option{--css-ref=@var{url}}. |
| 16817 | 19712 |
| 19713 @pindex texinfo-bright-colors.css | |
| 19714 @cindex Visualizing Texinfo CSS | |
| 16818 The option @option{--css-ref=@var{url}} adds to each output HTML file | 19715 The option @option{--css-ref=@var{url}} adds to each output HTML file |
| 16819 a @samp{<link>} tag referencing a CSS at the given @var{url}. This | 19716 a @samp{<link>} tag referencing a CSS at the given @var{url}. This |
| 16820 allows using external style sheets. | 19717 allows using external style sheets. You may find the file |
| 19718 @file{texi2html/examples/texinfo-bright-colors.css} useful for | |
| 19719 visualizing the CSS elements in Texinfo output. | |
| 16821 | 19720 |
| 16822 The option @option{--css-include=@var{file}} includes the contents | 19721 The option @option{--css-include=@var{file}} includes the contents |
| 16823 @var{file} in the HTML output, as you might expect. However, the | 19722 @var{file} in the HTML output, as you might expect. However, the |
| 16824 details are somewhat tricky, as described in the following, to provide | 19723 details are somewhat tricky, as described in the following, to provide |
| 16825 maximum flexibility. | 19724 maximum flexibility. |
| 16826 | 19725 |
| 16827 @cindex @@import specifications, in CSS files | 19726 @cindex @@import specifications, in CSS files |
| 16828 The CSS file may begin with so-called @samp{@@import} directives, | 19727 The CSS file may begin with so-called @samp{@@import} directives, |
| 16829 which link to external CSS specifications for browsers to use when | 19728 which link to external CSS specifications for browsers to use when |
| 16830 interpreting the document. Again, a full description is beyond our | 19729 interpreting the document. Again, a full description is beyond our |
| 16836 first in the file, with only whitespace and comments interspersed, no | 19735 first in the file, with only whitespace and comments interspersed, no |
| 16837 normal definitions. (Technical exception: an @samp{@@charset} | 19736 normal definitions. (Technical exception: an @samp{@@charset} |
| 16838 directive may precede the @samp{@@import}'s. This does not alter | 19737 directive may precede the @samp{@@import}'s. This does not alter |
| 16839 @command{makeinfo}'s behavior, it just copies the @samp{@@charset} if | 19738 @command{makeinfo}'s behavior, it just copies the @samp{@@charset} if |
| 16840 present.) Comments in CSS files are delimited by @samp{/* ... */}, as | 19739 present.) Comments in CSS files are delimited by @samp{/* ... */}, as |
| 16841 in C. An @samp{@@import} directive must be in one of these two forms: | 19740 in C@. An @samp{@@import} directive must be in one of these two forms: |
| 16842 | 19741 |
| 16843 @example | 19742 @example |
| 16844 @@import url(http://example.org/foo.css); | 19743 @@import url(http://example.org/foo.css); |
| 16845 @@import "http://example.net/bar.css"; | 19744 @@import "http://example.net/bar.css"; |
| 16846 @end example | 19745 @end example |
| 16870 @var{file}. | 19769 @var{file}. |
| 16871 | 19770 |
| 16872 @item Any @@-directive other than @samp{@@import} and @samp{@@charset} | 19771 @item Any @@-directive other than @samp{@@import} and @samp{@@charset} |
| 16873 is treated as a CSS declaration, meaning @command{makeinfo} includes | 19772 is treated as a CSS declaration, meaning @command{makeinfo} includes |
| 16874 its default CSS and then the rest of the file. | 19773 its default CSS and then the rest of the file. |
| 16875 | |
| 16876 @end itemize | 19774 @end itemize |
| 16877 | 19775 |
| 16878 If the CSS file is malformed or erroneous, @command{makeinfo}'s output | 19776 If the CSS file is malformed or erroneous, @command{makeinfo}'s output |
| 16879 is unspecified. @command{makeinfo} does not try to interpret the | 19777 is unspecified. @command{makeinfo} does not try to interpret the |
| 16880 meaning of the CSS file in any way; it just looks for the special | 19778 meaning of the CSS file in any way; it just looks for the special |
| 16881 @samp{@@} and @samp{;} characters and blindly copies the text into the | 19779 @samp{@@} and @samp{;} characters and blindly copies the text into the |
| 16882 output. Comments in the CSS file may or may not be included in the | 19780 output. Comments in the CSS file may or may not be included in the |
| 16883 output. | 19781 output. |
| 16884 | 19782 |
| 19783 In addition to the possibilities offered by CSS, @command{makeinfo} | |
| 19784 has many user-definable customization variables with which you can | |
| 19785 influence the HTML output. @xref{Customization Variables}. | |
| 19786 | |
| 16885 | 19787 |
| 16886 @node HTML Xref | 19788 @node HTML Xref |
| 16887 @section HTML Cross-references | 19789 @section HTML Cross References |
| 16888 @cindex HTML cross-references | 19790 @cindex HTML cross references |
| 16889 @cindex Cross-references, in HTML output | 19791 @cindex Cross references, in HTML output |
| 16890 | 19792 |
| 16891 Cross-references between Texinfo manuals in HTML format amount, in the | 19793 Cross references between Texinfo manuals in HTML format become, in the |
| 16892 end, to a standard HTML @code{<a>} link, but the details are | 19794 end, a standard HTML @code{<a>} link, but the details are |
| 16893 unfortunately complex. This section describes the algorithm used in | 19795 unfortunately complex. This section describes the algorithm used in |
| 16894 detail, so that Texinfo can cooperate with other programs, such as | 19796 detail, so that Texinfo can cooperate with other programs, such as |
| 16895 @command{texi2html}, by writing mutually compatible HTML files. | 19797 @command{texi2html}, by writing mutually compatible HTML files. |
| 16896 | 19798 |
| 16897 This algorithm may or may not be used for links @emph{within} HTML | 19799 This algorithm may or may not be used for links @emph{within} HTML |
| 16902 monolithic and split forms. A @dfn{monolithic} (mono) manual is | 19804 monolithic and split forms. A @dfn{monolithic} (mono) manual is |
| 16903 entirely contained in one file, and a @dfn{split} manual has a file | 19805 entirely contained in one file, and a @dfn{split} manual has a file |
| 16904 for each node. (@xref{HTML Splitting}.) | 19806 for each node. (@xref{HTML Splitting}.) |
| 16905 | 19807 |
| 16906 @cindex Dumas, Patrice | 19808 @cindex Dumas, Patrice |
| 16907 Acknowledgement: this algorithm was primarily devised by Patrice Dumas | 19809 The algorithm was primarily devised by Patrice Dumas in 2003--04. |
| 16908 in 2003--04. | |
| 16909 | 19810 |
| 16910 @menu | 19811 @menu |
| 16911 * Link Basics: HTML Xref Link Basics. | 19812 * Link Basics: HTML Xref Link Basics. |
| 16912 * Node Expansion: HTML Xref Node Name Expansion. | 19813 * Node Expansion: HTML Xref Node Name Expansion. |
| 16913 * Command Expansion: HTML Xref Command Expansion. | 19814 * Command Expansion: HTML Xref Command Expansion. |
| 16914 * 8-bit Expansion: HTML Xref 8-bit Character Expansion. | 19815 * 8-bit Expansion: HTML Xref 8-bit Character Expansion. |
| 16915 * Mismatch: HTML Xref Mismatch. | 19816 * Mismatch: HTML Xref Mismatch. |
| 19817 * Configuration: HTML Xref Configuration. htmlxref.cnf. | |
| 19818 * Preserving links: HTML Xref Link Preservation. MANUAL-noderename.cnf. | |
| 16916 @end menu | 19819 @end menu |
| 16917 | 19820 |
| 16918 | 19821 |
| 16919 @node HTML Xref Link Basics | 19822 @node HTML Xref Link Basics |
| 16920 @subsection HTML Cross-reference Link Basics | 19823 @subsection HTML Cross Reference Link Basics |
| 16921 @cindex HTML cross-reference link basics | 19824 @cindex HTML cross reference link basics |
| 16922 | 19825 |
| 16923 For our purposes, an HTML link consists of four components: a host | 19826 For our purposes, an HTML link consists of four components: a host |
| 16924 name, a directory part, a file part, and a target part. We | 19827 name, a directory part, a file part, and a target part. We |
| 16925 always assume the @code{http} protocol. For example: | 19828 always assume the @code{http} protocol. For example: |
| 16926 | 19829 |
| 16927 @example | 19830 @example |
| 16928 http://@var{host}/@var{dir}/@var{file}.html#@var{target} | 19831 http://@var{host}/@var{dir}/@var{file}.html#@var{target} |
| 16929 @end example | 19832 @end example |
| 16930 | 19833 |
| 16931 The information to construct a link comes from the node name and | 19834 The information to construct a link comes from the node name and |
| 16932 manual name in the cross-reference command in the Texinfo source | 19835 manual name in the cross reference command in the Texinfo source |
| 16933 (@pxref{Cross References}), and from @dfn{external information}, which | 19836 (@pxref{Cross References}), and from @dfn{external information} |
| 16934 is currently simply hardwired. In the future, it may come from an | 19837 (@pxref{HTML Xref Configuration}). |
| 16935 external data file. | |
| 16936 | 19838 |
| 16937 We now consider each part in turn. | 19839 We now consider each part in turn. |
| 16938 | 19840 |
| 16939 The @var{host} is hardwired to be the local host. This could either | 19841 The @var{host} is hardwired to be the local host. This could either |
| 16940 be the literal string @samp{localhost}, or, according to the rules for | 19842 be the literal string @samp{localhost}, or, according to the rules for |
| 16941 HTML links, the @samp{http://localhost/} could be omitted entirely. | 19843 HTML links, the @samp{http://localhost/} could be omitted entirely. |
| 16942 | 19844 |
| 16943 The @var{dir} and @var{file} parts are more complicated, and depend on | 19845 The @var{dir} and @var{file} parts are more complicated, and depend on |
| 16944 the relative split/mono nature of both the manual being processed and | 19846 the relative split/mono nature of both the manual being processed and |
| 16945 the manual that the cross-reference refers to. The underlying idea is | 19847 the manual that the cross reference refers to. The underlying idea is |
| 16946 that there is one directory for Texinfo manuals in HTML, and a given | 19848 that there is one directory for Texinfo manuals in HTML, and a given |
| 16947 @var{manual} is either available as a monolithic file | 19849 @var{manual} is either available as a monolithic file |
| 16948 @file{@var{manual}.html}, or a split subdirectory | 19850 @file{@var{manual}.html}, or a split subdirectory |
| 16949 @file{@var{manual}/*.html}. Here are the cases: | 19851 @file{@var{manual}/*.html}. Here are the cases: |
| 16950 | 19852 |
| 16968 the directory is @file{./} (or just the empty string), and the file is | 19870 the directory is @file{./} (or just the empty string), and the file is |
| 16969 @file{@var{referent}.html}. | 19871 @file{@var{referent}.html}. |
| 16970 | 19872 |
| 16971 @end itemize | 19873 @end itemize |
| 16972 | 19874 |
| 16973 One exception: the algorithm for node name expansion prefixes the | 19875 @vindex BASEFILENAME_LENGTH |
| 16974 string @samp{g_t} when the node name begins with a non-letter. This | 19876 Another rule, that only holds for filenames, is that base filenames |
| 16975 kludge (due to XHTML rules) is not necessary for filenames, and is | 19877 are truncated to 245 characters, to allow for an extension to be |
| 16976 therefore omitted. | 19878 appended and still comply with the 255-character limit which is common |
| 16977 | 19879 to many filesystems. Although technically this can be changed with |
| 16978 Any directory part in the filename argument of the source | 19880 the @code{BASEFILENAME_LENGTH} customization variable (@pxref{Other |
| 16979 cross-reference command is ignored. Thus, @code{@@xref@{,,,../foo@}} | 19881 Customization Variables}), doing so would make cross-manual references |
| 16980 and @code{@@xref@{,,,foo@}} both use @samp{foo} as the manual name. | 19882 to such nodes invalid. |
| 16981 This is because any such attempted hardwiring of the directory is very | 19883 |
| 19884 Any directory part in the filename argument of the source cross | |
| 19885 reference command is ignored. Thus, @code{@@xref@{,,,../foo@}} and | |
| 19886 @code{@@xref@{,,,foo@}} both use @samp{foo} as the manual name. This | |
| 19887 is because any such attempted hardwiring of the directory is very | |
| 16982 unlikely to be useful for both Info and HTML output. | 19888 unlikely to be useful for both Info and HTML output. |
| 16983 | 19889 |
| 16984 Finally, the @var{target} part is always the expanded node name. | 19890 Finally, the @var{target} part is always the expanded node name. |
| 16985 | 19891 |
| 16986 Whether the present manual is split or mono is determined by user | 19892 Whether the present manual is split or mono is determined by user |
| 16987 option; @command{makeinfo} defaults to split, with the | 19893 option; @command{makeinfo} defaults to split, with the |
| 16988 @option{--no-split} option overriding this. | 19894 @option{--no-split} option overriding this. |
| 16989 | 19895 |
| 16990 Whether the referent manual is split or mono is another bit of the | 19896 Whether the referent manual is split or mono, however, is another bit |
| 16991 external information. For now, @command{makeinfo} simply assumes the | 19897 of the external information (@pxref{HTML Xref Configuration}). By |
| 16992 referent manual is the same as the present manual. | 19898 default, @command{makeinfo} uses the same form of the referent manual |
| 16993 | 19899 as the present manual. |
| 16994 There can be a mismatch between the format of the referent manual that | 19900 |
| 16995 the generating software assumes, and the format it's actually present | 19901 Thus, there can be a mismatch between the format of the referent |
| 16996 in. @xref{HTML Xref Mismatch}. | 19902 manual that the generating software assumes, and the format it's |
| 19903 actually present in. @xref{HTML Xref Mismatch}. | |
| 16997 | 19904 |
| 16998 | 19905 |
| 16999 @node HTML Xref Node Name Expansion | 19906 @node HTML Xref Node Name Expansion |
| 17000 @subsection HTML Cross-reference Node Name Expansion | 19907 @subsection HTML Cross Reference Node Name Expansion |
| 17001 @cindex HTML cross-reference node name expansion | 19908 @cindex HTML cross reference node name expansion |
| 17002 @cindex node name expansion, in HTML cross-references | 19909 @cindex node name expansion, in HTML cross references |
| 17003 @cindex expansion, of node names in HTML cross-references | 19910 @cindex expansion, of node names in HTML cross references |
| 17004 | 19911 |
| 17005 As mentioned in the previous section, the key part of the HTML | 19912 As mentioned in the previous section, the key part of the HTML cross |
| 17006 cross-reference algorithm is the conversion of node names in the | 19913 reference algorithm is the conversion of node names in the Texinfo |
| 17007 Texinfo source into strings suitable for XHTML identifiers and | 19914 source into strings suitable for XHTML identifiers and filenames. The |
| 17008 filenames. The restrictions are similar for each: plain ASCII | 19915 restrictions are similar for each: plain ASCII letters, numbers, and |
| 17009 letters, numbers, and the @samp{-} and @samp{_} characters are all | 19916 the @samp{-} and @samp{_} characters are all that can be used. |
| 17010 that can be used. (Although HTML anchors can contain most characters, | 19917 (Although HTML anchors can contain most characters, XHTML is more |
| 17011 XHTML is more restrictive.) | 19918 restrictive.) |
| 17012 | 19919 |
| 17013 Cross-references in Texinfo can actually refer either to nodes or | 19920 Cross references in Texinfo can refer either to nodes or anchors |
| 17014 anchors (@pxref{anchor}), but anchors are treated identically to nodes | 19921 (@pxref{@t{@@anchor}}). However, anchors are treated identically |
| 17015 in this context, so we'll continue to say ``node'' names for | 19922 to nodes in this context, so we'll continue to say ``node'' names for |
| 17016 simplicity. | 19923 simplicity. |
| 17017 | |
| 17018 (@@-commands and 8-bit characters are not presently handled by | |
| 17019 @command{makeinfo} for HTML cross-references. See the next section.) | |
| 17020 | 19924 |
| 17021 A special exception: the Top node (@pxref{The Top Node}) is always | 19925 A special exception: the Top node (@pxref{The Top Node}) is always |
| 17022 mapped to the file @file{index.html}, to match web server software. | 19926 mapped to the file @file{index.html}, to match web server software. |
| 17023 However, the HTML @emph{target} is @samp{Top}. Thus (in the split case): | 19927 However, the HTML @emph{target} is @samp{Top}. Thus (in the split case): |
| 17024 | 19928 |
| 17025 @example | 19929 @example |
| 17026 @@xref@{Top, Introduction,, xemacs, XEmacs User's Manual@}. | 19930 @@xref@{Top,,, xemacs, XEmacs User's Manual@}. |
| 17027 @result{} <a href="xemacs/index.html#Top"> | 19931 @result{} <a href="xemacs/index.html#Top"> |
| 17028 @end example | 19932 @end example |
| 17029 | 19933 |
| 17030 @enumerate | 19934 @enumerate |
| 17031 @item | 19935 @item |
| 17032 The standard ASCII letters (a-z and A-Z) are not modified. All other | 19936 The standard ASCII letters (a-z and A-Z) are not modified. All other |
| 17033 characters are changed as specified below. | 19937 characters may be changed as specified below. |
| 17034 | 19938 |
| 17035 @item | 19939 @item |
| 17036 The standard ASCII numbers (0-9) are not modified except when a number | 19940 The standard ASCII numbers (0-9) are not modified except when a number |
| 17037 is the first character of the node name. In that case, see below. | 19941 is the first character of the node name. In that case, see below. |
| 17038 | 19942 |
| 17077 @item @samp{-} @result{} @samp{_002d} | 19981 @item @samp{-} @result{} @samp{_002d} |
| 17078 @item @samp{A node} @result{} @samp{A-node} | 19982 @item @samp{A node} @result{} @samp{A-node} |
| 17079 @end itemize | 19983 @end itemize |
| 17080 | 19984 |
| 17081 On case-folding computer systems, nodes differing only by case will be | 19985 On case-folding computer systems, nodes differing only by case will be |
| 17082 mapped to the same file. | 19986 mapped to the same file. In particular, as mentioned above, Top |
| 17083 | 19987 always maps to the file @file{index.html}. Thus, on a case-folding |
| 17084 In particular, as mentioned above, Top always maps to the file | 19988 system, Top and a node named `Index' will both be written to |
| 17085 @file{index.html}. Thus, on a case-folding system, Top and a node | 19989 @file{index.html}. Fortunately, the targets serve to distinguish |
| 17086 named `Index' will both be written to @file{index.html}. | 19990 these cases, since HTML target names are always case-sensitive, |
| 17087 | 19991 independent of operating system. |
| 17088 Fortunately, the targets serve to distinguish these cases, since HTML | |
| 17089 target names are always case-sensitive, independent of operating | |
| 17090 system. | |
| 17091 | 19992 |
| 17092 | 19993 |
| 17093 @node HTML Xref Command Expansion | 19994 @node HTML Xref Command Expansion |
| 17094 @subsection HTML Cross-reference Command Expansion | 19995 @subsection HTML Cross Reference Command Expansion |
| 17095 @cindex HTML cross-reference command expansion | 19996 @cindex HTML cross reference command expansion |
| 17096 | 19997 |
| 17097 In standard Texinfo, node names may not contain @@-commands. | 19998 Node names may contain @@-commands (@pxref{Node Line Requirements}). |
| 17098 @command{makeinfo} has an option @option{--commands-in-node-names} | 19999 This section describes how they are handled. |
| 17099 which partially supports it (@pxref{Invoking makeinfo}), but it is not | |
| 17100 robust and not recommended. | |
| 17101 | |
| 17102 Thus, @command{makeinfo} does not fully implement this part of the | |
| 17103 HTML cross-reference algorithm, but it is documented here for the sake | |
| 17104 of completeness. | |
| 17105 | 20000 |
| 17106 First, comments are removed. | 20001 First, comments are removed. |
| 17107 | 20002 |
| 17108 Next, any @code{@@value} commands (@pxref{set value}) and macro invocations | 20003 Next, any @code{@@value} commands (@pxref{@t{@@set @@value}}) and |
| 17109 (@pxref{Invoking Macros}) are fully expanded. | 20004 macro invocations (@pxref{Invoking Macros}) are fully expanded. |
| 17110 | 20005 |
| 17111 Then, for the following commands, the command name and braces are removed, | 20006 Then, for the following commands, the command name and braces are removed, |
| 17112 the text of the argument is recursively transformed: | 20007 and the text of the argument is recursively transformed: |
| 20008 | |
| 17113 @example | 20009 @example |
| 17114 @@asis @@b @@cite @@code @@command @@dfn @@dmn @@dotless | 20010 @@asis @@b @@cite @@code @@command @@dfn @@dmn @@dotless |
| 17115 @@emph @@env @@file @@indicateurl @@kbd @@key | 20011 @@emph @@env @@file @@i @@indicateurl @@kbd @@key |
| 17116 @@samp @@sc @@slanted @@strong @@t @@var @@w | 20012 @@samp @@sansserif @@sc @@slanted @@strong @@t @@var @@verb @@w |
| 17117 @end example | 20013 @end example |
| 17118 | 20014 |
| 17119 @noindent For @code{@@sc}, any letters are capitalized. | 20015 @noindent For @code{@@sc}, any letters are capitalized. |
| 17120 | 20016 |
| 17121 The following commands are replaced by constant text, as shown. If | 20017 In addition, the following commands are replaced by constant text, as |
| 17122 any of these commands have non-empty arguments, as in | 20018 shown below. If any of these commands have non-empty arguments, as in |
| 17123 @code{@@TeX@{bad@}}, it is an error, and the result is unspecified. | 20019 @code{@@TeX@{bad@}}, it is an error, and the result is unspecified. |
| 17124 `(space)' means a space character, `(nothing)' means the empty string, | 20020 In this table, `(space)' means a space character and `(nothing)' means |
| 17125 etc. The notation `U+@var{xxxx}' means Unicode code point @var{xxxx} | 20021 the empty string. The notation `U+@var{hhhh}' means Unicode code |
| 17126 (in hex, as usual). There are further transformations of many of | 20022 point @var{hhhh} (in hex, as usual). There are further |
| 17127 these expansions for the final file or target name, such as space | 20023 transformations of many of these expansions for the final file or |
| 17128 characters to @samp{-}, etc., according to the other rules. | 20024 target name, such as space characters to @samp{-}, etc., according to |
| 20025 the other rules. | |
| 17129 | 20026 |
| 17130 @multitable @columnfractions .3 .5 | 20027 @multitable @columnfractions .3 .5 |
| 17131 @item @code{@@(newline)} @tab (space) | 20028 @item @code{@@(newline)} @tab (space) |
| 17132 @item @code{@@(space)} @tab (space) | 20029 @item @code{@@(space)} @tab (space) |
| 17133 @item @code{@@(tab)} @tab (space) | 20030 @item @code{@@(tab)} @tab (space) |
| 17150 @item @code{@@enddots} @tab @samp{...} | 20047 @item @code{@@enddots} @tab @samp{...} |
| 17151 @item @code{@@equiv} @tab U+2261 | 20048 @item @code{@@equiv} @tab U+2261 |
| 17152 @item @code{@@error} @tab @samp{error-->} | 20049 @item @code{@@error} @tab @samp{error-->} |
| 17153 @item @code{@@euro} @tab U+20AC | 20050 @item @code{@@euro} @tab U+20AC |
| 17154 @item @code{@@exclamdown} @tab U+00A1 | 20051 @item @code{@@exclamdown} @tab U+00A1 |
| 17155 @item @code{@@expansion} @tab U+2192 | 20052 @item @code{@@expansion} @tab U+21A6 |
| 17156 @item @code{@@geq} @tab U+2265 | 20053 @item @code{@@geq} @tab U+2265 |
| 17157 @item @code{@@leq} @tab U+2264 | 20054 @item @code{@@leq} @tab U+2264 |
| 17158 @item @code{@@minus} @tab U+2212 | 20055 @item @code{@@minus} @tab U+2212 |
| 17159 @item @code{@@ordf} @tab U+00AA | 20056 @item @code{@@ordf} @tab U+00AA |
| 17160 @item @code{@@ordm} @tab U+00BA | 20057 @item @code{@@ordm} @tab U+00BA |
| 17166 @item @code{@@result} @tab U+21D2 | 20063 @item @code{@@result} @tab U+21D2 |
| 17167 @item @code{@@textdegree} @tab U+00B0 | 20064 @item @code{@@textdegree} @tab U+00B0 |
| 17168 @item @code{@@tie} @tab (space) | 20065 @item @code{@@tie} @tab (space) |
| 17169 @end multitable | 20066 @end multitable |
| 17170 | 20067 |
| 17171 Quotation mark commands are likewise replaced by their Unicode values | 20068 Quotation mark @@-commands (@code{@@quotedblright@{@}} and the like), |
| 17172 (@pxref{Inserting Quotation Marks}). | 20069 are likewise replaced by their Unicode values. Normal quotation |
| 17173 | 20070 @emph{characters} (e.g., ASCII ` and ') are not altered. |
| 17174 An @code{@@acronym} or @code{@@abbr} command is replaced by the first | 20071 @xref{Inserting Quotation Marks}. |
| 17175 argument, followed by the second argument in parentheses, if present. | 20072 |
| 17176 @xref{acronym}. | 20073 Any @code{@@acronym}, @code{@@abbr}, @code{@@email}, and |
| 17177 | 20074 @code{@@image} commands are replaced by their first argument. (For |
| 17178 An @code{@@email} command is replaced by the @var{text} argument if | 20075 these commands, all subsequent arguments are optional, and ignored |
| 17179 present, else the address. @xref{email}. | 20076 here.) @xref{@t{@@acronym}}, and @ref{@t{@@email}}, and @ref{Images}. |
| 17180 | |
| 17181 An @code{@@image} command is replaced by the filename (first) | |
| 17182 argument. @xref{Images}. | |
| 17183 | |
| 17184 A @code{@@verb} command is replaced by its transformed argument. | |
| 17185 @xref{verb}. | |
| 17186 | 20077 |
| 17187 Any other command is an error, and the result is unspecified. | 20078 Any other command is an error, and the result is unspecified. |
| 17188 | 20079 |
| 17189 | 20080 |
| 17190 @node HTML Xref 8-bit Character Expansion | 20081 @node HTML Xref 8-bit Character Expansion |
| 17191 @subsection HTML Cross-reference 8-bit Character Expansion | 20082 @subsection HTML Cross Reference 8-bit Character Expansion |
| 17192 @cindex HTML cross-reference 8-bit character expansion | 20083 @cindex HTML cross reference 8-bit character expansion |
| 17193 @cindex 8-bit characters, in HTML cross-references | 20084 @cindex 8-bit characters, in HTML cross references |
| 17194 @cindex Expansion of 8-bit characters in HTML cross-references | 20085 @cindex Expansion of 8-bit characters in HTML cross references |
| 17195 @cindex Transliteration of 8-bit characters in HTML cross-references | 20086 @cindex Transliteration of 8-bit characters in HTML cross references |
| 17196 | 20087 |
| 17197 Usually, characters other than plain 7-bit ASCII are transformed into | 20088 Usually, characters other than plain 7-bit ASCII are transformed into |
| 17198 the corresponding Unicode code point(s) in Normalization Form C, which | 20089 the corresponding Unicode code point(s) in Normalization Form@tie{}C, |
| 17199 uses precomposed characters where available. (This is the | 20090 which uses precomposed characters where available. (This is the |
| 17200 normalization form recommended by the W3C and other bodies.) This | 20091 normalization form recommended by the W3C and other bodies.) This |
| 17201 holds when that code point is 0xffff or less, as it almost always is. | 20092 holds when that code point is @code{0xffff} or less, as it almost |
| 20093 always is. | |
| 17202 | 20094 |
| 17203 These will then be further transformed by the rules above into the | 20095 These will then be further transformed by the rules above into the |
| 17204 string @samp{_@var{xxxx}}, where @var{xxxx} is the code point in hex. | 20096 string @samp{_@var{hhhh}}, where @var{hhhh} is the code point in hex. |
| 17205 | 20097 |
| 17206 For example, combining this rule and the previous section: | 20098 For example, combining this rule and the previous section: |
| 17207 | 20099 |
| 17208 @example | 20100 @example |
| 17209 @@node @@b@{A@} @@TeX@{@} @@u@{B@} @@point@{@}@@enddots@{@} | 20101 @@node @@b@{A@} @@TeX@{@} @@u@{B@} @@point@{@}@@enddots@{@} |
| 17214 turn expands to three @samp{_002e}'s; 2)@tie{}@code{@@u@{B@}} is a `B' | 20106 turn expands to three @samp{_002e}'s; 2)@tie{}@code{@@u@{B@}} is a `B' |
| 17215 with a breve accent, which does not exist as a pre-accented Unicode | 20107 with a breve accent, which does not exist as a pre-accented Unicode |
| 17216 character, therefore expands to @samp{B_0306} (B with combining | 20108 character, therefore expands to @samp{B_0306} (B with combining |
| 17217 breve). | 20109 breve). |
| 17218 | 20110 |
| 17219 When the Unicode code point is above 0xffff, the transformation is | 20111 When the Unicode code point is above @code{0xffff}, the transformation |
| 17220 @samp{__@var{xxxxxx}}, that is, two leading underscores followed by | 20112 is @samp{__@var{xxxxxx}}, that is, two leading underscores followed by |
| 17221 six hex digits. Since Unicode has declared that their highest code | 20113 six hex digits. Since Unicode has declared that their highest code |
| 17222 point is 0x10ffff, this is sufficient. (We felt it was better to | 20114 point is @code{0x10ffff}, this is sufficient. (We felt it was better |
| 17223 define this extra escape than to always use six hex digits, since the | 20115 to define this extra escape than to always use six hex digits, since |
| 17224 first two would nearly always be zeros.) | 20116 the first two would nearly always be zeros.) |
| 17225 | 20117 |
| 17226 This method works fine if the node name consists mostly of ASCII | 20118 This method works fine if the node name consists mostly of ASCII |
| 17227 characters and contains only few 8-bit ones. If the document is | 20119 characters and contains only few 8-bit ones. If the document is |
| 17228 written in a language whose script is not based on the Latin alphabet | 20120 written in a language whose script is not based on the Latin alphabet |
| 17229 (such as, e.g. Ukrainian), it will create file names consisting | 20121 (for example, Ukrainian), it will create file names consisting |
| 17230 entirely of @samp{_@var{xxxx}} notations, which is inconvenient. | 20122 entirely of @samp{_@var{xxxx}} notations, which is inconvenient and |
| 17231 | 20123 all but unreadable. |
| 17232 To handle such cases, @command{makeinfo} offers | 20124 |
| 17233 @option{--transliterate-file-names} command line option. This option | 20125 To handle such cases, @command{makeinfo} offers the |
| 20126 @option{--transliterate-file-names} command line option. This option | |
| 17234 enables @dfn{transliteration} of node names into ASCII characters for | 20127 enables @dfn{transliteration} of node names into ASCII characters for |
| 17235 the purposes of file name creation and referencing. The | 20128 the purposes of file name creation and referencing. The |
| 17236 transliteration is based on phonetic principle, which makes the | 20129 transliteration is based on phonetic principles, which makes the |
| 17237 produced file names easily readable. | 20130 generated file names more easily understanable. |
| 17238 | 20131 |
| 17239 For the definition of Unicode Normalization Form C, see Unicode report | 20132 @cindex Normalization Form C, Unicode |
| 17240 UAX#15, @uref{http://www.unicode.org/reports/tr15/}. Many related | 20133 For the definition of Unicode Normalization Form@tie{}C, see Unicode |
| 17241 documents and implementations are available elsewhere on the web. | 20134 report UAX#15, @uref{http://www.unicode.org/reports/tr15/}. Many |
| 20135 related documents and implementations are available elsewhere on the | |
| 20136 web. | |
| 17242 | 20137 |
| 17243 | 20138 |
| 17244 @node HTML Xref Mismatch | 20139 @node HTML Xref Mismatch |
| 17245 @subsection HTML Cross-reference Mismatch | 20140 @subsection HTML Cross Reference Mismatch |
| 17246 @cindex HTML cross-reference mismatch | 20141 @cindex HTML cross reference mismatch |
| 17247 @cindex Mismatched HTML cross-reference source and target | 20142 @cindex Mismatched HTML cross reference source and target |
| 17248 | 20143 |
| 17249 As mentioned earlier (@pxref{HTML Xref Link Basics}), the generating | 20144 As mentioned earlier (@pxref{HTML Xref Link Basics}), the generating |
| 17250 software has to guess whether a given manual being cross-referenced is | 20145 software may need to guess whether a given manual being cross |
| 17251 available in split or monolithic form---and, inevitably, it might | 20146 referenced is available in split or monolithic form---and, inevitably, |
| 17252 guess wrong. However, it is possible when the referent manual itself | 20147 it might guess wrong. However, when the @emph{referent} manual is |
| 17253 is generated, it is possible to handle at least some mismatches. | 20148 generated, it is possible to handle at least some mismatches. |
| 17254 | 20149 |
| 17255 In the case where we assume the referent is split, but it is actually | 20150 In the case where we assume the referent is split, but it is actually |
| 17256 available in mono, the only recourse would be to generate a | 20151 available in mono, the only recourse would be to generate a |
| 17257 @file{manual/} subdirectory full of HTML files which redirect back to | 20152 @file{manual/} subdirectory full of HTML files which redirect back to |
| 17258 the monolithic @file{manual.html}. Since this is essentially the same | 20153 the monolithic @file{manual.html}. Since this is essentially the same |
| 17283 <body onLoad="redirect();"> | 20178 <body onLoad="redirect();"> |
| 17284 @end example | 20179 @end example |
| 17285 | 20180 |
| 17286 Once again, this is something the software which generated the | 20181 Once again, this is something the software which generated the |
| 17287 @emph{referent} manual has to do in advance, it's not something the | 20182 @emph{referent} manual has to do in advance, it's not something the |
| 17288 software generating the actual cross-reference in the present manual | 20183 software generating the cross reference in the present manual can |
| 17289 can control. | 20184 control. |
| 17290 | 20185 |
| 17291 Ultimately, we hope to allow for an external configuration file to | 20186 |
| 17292 control which manuals are available from where, and how. | 20187 @node HTML Xref Configuration |
| 17293 | 20188 @subsection HTML Cross Reference Configuration: @file{htmlxref.cnf} |
| 17294 | 20189 |
| 17295 @ignore | 20190 @pindex htmlxref.cnf |
| 17296 -- not yet -- | 20191 @cindex HTML cross reference configuration |
| 17297 | 20192 @cindex Cross reference configuration, for HTML |
| 17298 external information | 20193 @cindex Configuration, for HTML cross-manual references |
| 17299 -------------------- | 20194 |
| 17300 | 20195 @command{makeinfo} reads a file named @file{htmlxref.cnf} to gather |
| 17301 The information for the reference is searched in the file | 20196 information for cross references to other manuals in HTML output. It |
| 17302 `htmlxref.cnf' present in the following directories: | 20197 is looked for in the following directories: |
| 17303 <srcdir>/.texinfo/, ~/.texinfo/, SYSCONFDIR/texinfo/, | 20198 |
| 17304 DATADIR/texinfo/ | 20199 @table @file |
| 17305 The first match should be used. | 20200 @item ./ |
| 17306 | 20201 (the current directory) |
| 17307 The file is line-oriented, with the following format: | 20202 |
| 17308 <manualname> <whitespace> <keyword> <whitespace> <urlprefix> | 20203 @item ./.texinfo/ |
| 17309 with <keyword> being "mono" or "split". Thus | 20204 (under the current directory) |
| 17310 texinfo split http://www.gnu.org/software/texinfo/manual/texinfo/html_node/ | 20205 |
| 17311 texinfo mono http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html | 20206 @item ~/.texinfo/ |
| 17312 | 20207 (where @code{~} is the current user's home directory) |
| 17313 If the keyword is 'split', that is the target is split, the urlprefix gives | 20208 |
| 17314 the directory and host name. | 20209 @item @var{sysconfdir}/texinfo/ |
| 17315 If the keyword is 'mono', that is the target is mono, the urlprefix gives | 20210 (where @var{sysconfdir} is the system configuration directory |
| 17316 directory, host and file name. | 20211 specified at compile-time, e.g., @file{/usr/local/etc}) |
| 17317 | 20212 |
| 17318 '#' followed by a space begins comments. '#' followed by another character | 20213 @item @var{datadir}/texinfo/ |
| 17319 cannot begin comments as there are # in urls. | 20214 (likewise specified at compile time, e.g., @file{/usr/local/share}) |
| 17320 | 20215 @end table |
| 17321 @end ignore | 20216 |
| 20217 All files found are used, with earlier entries overriding later ones. | |
| 20218 The Texinfo distribution includes a default file which handles many | |
| 20219 GNU manuals; it is installed in the last of the above directories, | |
| 20220 i.e., @file{@var{datadir}/texinfo/htmlxref.cnf}. | |
| 20221 | |
| 20222 The file is line-oriented. Lines consisting only of whitespace are | |
| 20223 ignored. Comments are indicated with a @samp{#} at the beginning of a | |
| 20224 line, optionally preceded by whitespace. Since @samp{#} can occur in | |
| 20225 urls (like almost any character), it does not otherwise start a | |
| 20226 comment. | |
| 20227 | |
| 20228 Each non-blank non-comment line must be either a @dfn{variable | |
| 20229 assignment} or @dfn{manual information}. | |
| 20230 | |
| 20231 A variable assignment line looks like this: | |
| 20232 | |
| 20233 @example | |
| 20234 @var{varname} = @var{varvalue} | |
| 20235 @end example | |
| 20236 | |
| 20237 Whitespace around the @samp{=} is optional and ignored. The | |
| 20238 @var{varname} should consist of letters; case is significant. The | |
| 20239 @var{varvalue} is an arbitrary string, continuing to the end of the | |
| 20240 line. Variables are then referenced with @samp{$@{@var{varname}@}}; | |
| 20241 variable references can occur in the @var{varvalue}. | |
| 20242 | |
| 20243 A manual information line looks like this: | |
| 20244 | |
| 20245 @example | |
| 20246 @var{manual} @var{keyword} @var{urlprefix} | |
| 20247 @end example | |
| 20248 | |
| 20249 @noindent | |
| 20250 with @var{manual} the short identifier for a manual, @var{keyword} | |
| 20251 being one of: @code{mono}, @code{node}, @code{section}, | |
| 20252 @code{chapter}, and @var{urlprefix} described below. Variable | |
| 20253 references can occur only in the @var{urlprefix}. For example (used | |
| 20254 in the canonical @file{htmlxref.cnf}): | |
| 20255 | |
| 20256 @smallexample | |
| 20257 G = http://www.gnu.org | |
| 20258 GS = $@{G@}/software | |
| 20259 hello mono $@{GS@}/hello/manual/hello.html | |
| 20260 hello chapter $@{GS@}/hello/manual/html_chapter/ | |
| 20261 hello section $@{GS@}/hello/manual/html_section/ | |
| 20262 hello node $@{GS@}/hello/manual/html_node/ | |
| 20263 @end smallexample | |
| 20264 | |
| 20265 @cindex monolithic manuals, for HTML cross references | |
| 20266 If the keyword is @code{mono}, @var{urlprefix} gives the host, | |
| 20267 directory, and file name for @var{manual} as one monolithic file. | |
| 20268 | |
| 20269 @cindex split manuals, for HTML cross references | |
| 20270 If the keyword is @code{node}, @code{section}, or @code{chapter}, | |
| 20271 @var{urlprefix} gives the host and directory for @var{manual} split | |
| 20272 into nodes, sections, or chapters, respectively. | |
| 20273 | |
| 20274 When available, @command{makeinfo} will use the ``corresponding'' | |
| 20275 value for cross references between manuals. That is, when generating | |
| 20276 monolithic output (@option{--no-split}), the @code{mono} url will be | |
| 20277 used, when generating output that is split by node, the @code{node} | |
| 20278 url will be used, etc. However, if a manual is not available in that | |
| 20279 form, anything that is available can be used. Here is the search | |
| 20280 order for each style: | |
| 20281 | |
| 20282 @smallexample | |
| 20283 node @result{} node, section, chapter, mono | |
| 20284 section @result{} section, chapter, node, mono | |
| 20285 chapter @result{} chapter, section, node, mono | |
| 20286 mono @result{} mono, chapter, section, node | |
| 20287 @end smallexample | |
| 20288 | |
| 20289 @opindex --node-files@r{, and HTML cross references} | |
| 20290 These section- and chapter-level cross-manual references can succeed | |
| 20291 only when the target manual was created using @option{--node-files}; | |
| 20292 this is the default for split output. | |
| 20293 | |
| 20294 If you have additions or corrections to the @file{htmlxref.cnf} | |
| 20295 distributed with Texinfo, please email @email{bug-texinfo@@gnu.org} as | |
| 20296 usual. You can get the latest version from | |
| 20297 @url{http://ftpmirror.gnu.org/@/texinfo/@/htmlxref.cnf}. | |
| 20298 | |
| 20299 | |
| 20300 @node HTML Xref Link Preservation | |
| 20301 @subsection HTML Cross Reference Link Preservation: @var{manual}@file{-noderename.cnf} | |
| 20302 | |
| 20303 @pindex noderename.cnf | |
| 20304 @pindex @var{manual}-noderename.cnf | |
| 20305 @cindex HTML cross reference link preservation | |
| 20306 @cindex Preserving HTML links to old nodes | |
| 20307 @cindex Old nodes, preserving links to | |
| 20308 @cindex Renaming nodes, and preserving links | |
| 20309 @cindex Links, preserving to renamed nodes | |
| 20310 @cindex Node renaming, and preserving links | |
| 20311 | |
| 20312 Occasionally changes in a program require removing (or renaming) nodes | |
| 20313 in the manual in order to have the best documentation. Given the | |
| 20314 nature of the web, however, links may exist anywhere to such a removed | |
| 20315 node (renaming appears the same as removal for this purpose), and it's | |
| 20316 not ideal for those links to simply break. | |
| 20317 | |
| 20318 @vindex RENAMED_NODES_FILE | |
| 20319 Therefore, Texinfo provides a way for manual authors to specify old | |
| 20320 node names and the new nodes to which the old names should be | |
| 20321 redirected, via the file @var{manual}@file{-noderename.cnf}, where | |
| 20322 @var{manual} is the base name of the manual. For example, the manual | |
| 20323 @file{texinfo.texi} would be supplemented by a file | |
| 20324 @file{texinfo-noderename}.cnf. (This name can be overridden by | |
| 20325 setting the @file{RENAMED_NODES_FILE} customization variable; | |
| 20326 @pxref{Customization Variables}). | |
| 20327 | |
| 20328 The file is read in pairs of lines, as follows: | |
| 20329 | |
| 20330 @example | |
| 20331 @var{old-node-name} | |
| 20332 @@@@@{@} @var{new-node-name} | |
| 20333 @end example | |
| 20334 | |
| 20335 The usual conversion from Texinfo node names to HTML names is applied; | |
| 20336 see this entire section for details (@pxref{HTML Xref}). The unusual | |
| 20337 @samp{@@@@@{@}} separator is used because it is not a valid Texinfo | |
| 20338 construct, so can't appear in the node names. | |
| 20339 | |
| 20340 The effect is that @command{makeinfo} generates a redirect from | |
| 20341 @var{old-node-name} to @var{new-node-name} when producing HTML output. | |
| 20342 Thus, external links to the old node are preserved. | |
| 20343 | |
| 20344 Lines consisting only of whitespace are ignored. Comments are | |
| 20345 indicated with an @samp{@@c} at the beginning of a line, optionally | |
| 20346 preceded by whitespace. | |
| 20347 | |
| 20348 Another approach to preserving links to deleted or renamed nodes is to | |
| 20349 use anchors (@pxref{@t{@@anchor}}). There is no effective | |
| 20350 difference between the two approaches. | |
| 17322 | 20351 |
| 17323 | 20352 |
| 17324 @node Command List | 20353 @node Command List |
| 17325 @appendix @@-Command List | 20354 @appendix @@-Command List |
| 17326 @cindex Alphabetical @@-command list | 20355 @cindex Alphabetical @@-command list |
| 17327 @cindex List of @@-commands | 20356 @cindex List of @@-commands |
| 17328 @cindex @@-command list | 20357 @cindex @@-command list |
| 17329 @cindex Reference to @@-commands | 20358 @cindex Reference to @@-commands |
| 17330 | 20359 |
| 17331 Here is an alphabetical list of the @@-commands in Texinfo. Square | 20360 Here is an alphabetical list of the @@-commands in Texinfo. Square |
| 17332 brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis, | 20361 brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis, |
| 17334 | 20363 |
| 17335 More specifics on the general syntax of different @@-commands are | 20364 More specifics on the general syntax of different @@-commands are |
| 17336 given in the section below. | 20365 given in the section below. |
| 17337 | 20366 |
| 17338 @menu | 20367 @menu |
| 17339 * Command Syntax:: General syntax for varieties of @@-commands. | 20368 * Command Syntax:: General syntax for varieties of @@-commands. |
| 20369 * Command Contexts:: Guidelines for which commands can be used where. | |
| 17340 @end menu | 20370 @end menu |
| 17341 | 20371 |
| 17342 @sp 1 | 20372 @sp 1 |
| 17343 @table @code | 20373 @table @code |
| 17344 @item @@@var{whitespace} | 20374 @item @@@var{whitespace} |
| 17360 @item @@,@{@var{c}@} | 20390 @item @@,@{@var{c}@} |
| 17361 Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting | 20391 Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting |
| 17362 Accents}. | 20392 Accents}. |
| 17363 | 20393 |
| 17364 @item @@- | 20394 @item @@- |
| 17365 Insert a discretionary hyphenation point. @xref{- and hyphenation}. | 20395 Insert a discretionary hyphenation point. @xref{@t{@@- @@hyphenation}}. |
| 17366 | 20396 |
| 17367 @item @@. | 20397 @item @@. |
| 17368 Produce a period that ends a sentence (usually after an | 20398 Produce a period that ends a sentence (usually after an |
| 17369 end-of-sentence capital letter). @xref{Ending a Sentence}. | 20399 end-of-sentence capital letter). @xref{Ending a Sentence}. |
| 17370 | 20400 |
| 17383 @item @@? | 20413 @item @@? |
| 17384 Produce a question mark that ends a sentence (usually after an | 20414 Produce a question mark that ends a sentence (usually after an |
| 17385 end-of-sentence capital letter). @xref{Ending a Sentence}. | 20415 end-of-sentence capital letter). @xref{Ending a Sentence}. |
| 17386 | 20416 |
| 17387 @item @@@@ | 20417 @item @@@@ |
| 17388 Stands for an at sign, @samp{@@}. | 20418 @itemx @@atchar@{@} |
| 17389 @xref{Atsign Braces Comma, , Inserting @@ and @{@} and @comma{}}. | 20419 Insert an at sign, @samp{@@}. @xref{Inserting an Atsign}. |
| 17390 | 20420 |
| 17391 @item @@\ | 20421 @item @@\ |
| 17392 Stands for a backslash (@samp{\}) inside @code{@@math}. | 20422 @itemx @@backslashchar@{@} |
| 17393 @xref{math,,@code{math}}. | 20423 Insert a backslash, @samp{\}; @code{@@backslashchar@{@}} works |
| 20424 anywhere, while @code{@@\} works only inside @code{@@math}. | |
| 20425 @xref{Inserting a Backslash}, and @ref{Inserting Math}. | |
| 17394 | 20426 |
| 17395 @item @@^ | 20427 @item @@^ |
| 17396 @itemx @@` | 20428 @itemx @@` |
| 17397 Generate a circumflex (hat) or grave accent, respectively, over the next | 20429 Generate a circumflex (hat) or grave accent, respectively, over the next |
| 17398 character, as in @^o and @`e. | 20430 character, as in @^o and @`e. |
| 17399 @xref{Inserting Accents}. | 20431 @xref{Inserting Accents}. |
| 17400 | 20432 |
| 17401 @item @@@{ | 20433 @item @@@{ |
| 17402 Stands for a left brace, @samp{@{}. | 20434 @itemx @@lbracechar@{@} |
| 17403 @xref{Atsign Braces Comma, , Inserting @@ and @{@} and @comma{}}. | 20435 Insert a left brace, @samp{@{}. @xref{Inserting Braces}. |
| 17404 | 20436 |
| 17405 @item @@@} | 20437 @item @@@} |
| 17406 Stands for a right-hand brace, @samp{@}}.@* | 20438 @itemx @@rbracechar@{@} |
| 17407 @xref{Atsign Braces Comma, , Inserting @@ and @{@} and @comma{}}. | 20439 Insert a right brace, @samp{@}}. @xref{Inserting Braces}. |
| 17408 | 20440 |
| 17409 @item @@~ | 20441 @item @@~ |
| 17410 Generate a tilde accent over the next character, as in @~N. | 20442 Generate a tilde accent over the next character, as in @~N. |
| 17411 @xref{Inserting Accents}. | 20443 @xref{Inserting Accents}. |
| 17412 | 20444 |
| 17414 @itemx @@aa@{@} | 20446 @itemx @@aa@{@} |
| 17415 Generate the uppercase and lowercase Scandinavian A-ring letters, | 20447 Generate the uppercase and lowercase Scandinavian A-ring letters, |
| 17416 respectively: @AA{}, @aa{}. @xref{Inserting Accents}. | 20448 respectively: @AA{}, @aa{}. @xref{Inserting Accents}. |
| 17417 | 20449 |
| 17418 @item @@abbr@{@var{abbreviation}@} | 20450 @item @@abbr@{@var{abbreviation}@} |
| 17419 Indicate a general abbreviation, such as `Comput.'. @xref{abbr,, | 20451 Indicate a general abbreviation, such as `Comput.'. |
| 17420 @code{abbr}}. | 20452 @xref{@t{@@abbr}}. |
| 17421 | 20453 |
| 17422 @item @@acronym@{@var{acronym}@} | 20454 @item @@acronym@{@var{acronym}@} |
| 17423 Indicate an acronym in all capital letters, such as `NASA'. | 20455 Indicate an acronym in all capital letters, such as `NASA'. |
| 17424 @xref{acronym,, @code{acronym}}. | 20456 @xref{@t{@@acronym}}. |
| 17425 | 20457 |
| 17426 @item @@AE@{@} | 20458 @item @@AE@{@} |
| 17427 @itemx @@ae@{@} | 20459 @itemx @@ae@{@} |
| 17428 Generate the uppercase and lowercase AE ligatures, respectively: | 20460 Generate the uppercase and lowercase AE ligatures, respectively: |
| 17429 @AE{}, @ae{}. @xref{Inserting Accents}. | 20461 @AE{}, @ae{}. @xref{Inserting Accents}. |
| 17436 @itemx @@afourwide | 20468 @itemx @@afourwide |
| 17437 Change page dimensions for the A4 paper size. @xref{A4 Paper}. | 20469 Change page dimensions for the A4 paper size. @xref{A4 Paper}. |
| 17438 | 20470 |
| 17439 @item @@alias @var{new}=@var{existing} | 20471 @item @@alias @var{new}=@var{existing} |
| 17440 Make the command @samp{@@@var{new}} a synonym for the existing command | 20472 Make the command @samp{@@@var{new}} a synonym for the existing command |
| 17441 @samp{@@@var{existing}}. @xref{alias}. | 20473 @samp{@@@var{existing}}. @xref{@t{@@alias}}. |
| 20474 | |
| 20475 @item @@allowcodebreaks @var{true-false} | |
| 20476 Control breaking at @samp{-} and @samp{_} in @TeX{}. | |
| 20477 @xref{@t{@@allowcodebreaks}}. | |
| 17442 | 20478 |
| 17443 @item @@anchor@{@var{name}@} | 20479 @item @@anchor@{@var{name}@} |
| 17444 Define @var{name} as the current location for use as a cross-reference | 20480 Define @var{name} as the current location for use as a cross reference |
| 17445 target. @xref{anchor,, @code{@@anchor}}. | 20481 target. @xref{@t{@@anchor}}. |
| 17446 | 20482 |
| 17447 @item @@appendix @var{title} | 20483 @item @@appendix @var{title} |
| 17448 Begin an appendix. The title appears in the table of contents. In | 20484 Begin an appendix. The title appears in the table of contents. In |
| 17449 Info, the title is underlined with asterisks. @xref{unnumbered & | 20485 Info, the title is underlined with asterisks. |
| 17450 appendix, , The @code{@@unnumbered} and @code{@@appendix} Commands}. | 20486 @xref{@t{@@unnumbered @@appendix}}. |
| 17451 | 20487 |
| 17452 @item @@appendixsec @var{title} | 20488 @item @@appendixsec @var{title} |
| 17453 @itemx @@appendixsection @var{title} | 20489 @itemx @@appendixsection @var{title} |
| 17454 Begin an appendix section within an appendix. The section title | 20490 Begin an appendix section within an appendix. The section title |
| 17455 appears in the table of contents. In Info, the title is underlined | 20491 appears in the table of contents. In Info, the title is underlined |
| 17456 with equal signs. @code{@@appendixsection} is a longer spelling of | 20492 with equal signs. @code{@@appendixsection} is a longer spelling of |
| 17457 the @code{@@appendixsec} command. @xref{unnumberedsec appendixsec | 20493 the @code{@@appendixsec} command. @xref{@t{@@unnumberedsec |
| 17458 heading, , Section Commands}. | 20494 @@appendixsec @@heading}}. |
| 17459 | 20495 |
| 17460 @item @@appendixsubsec @var{title} | 20496 @item @@appendixsubsec @var{title} |
| 17461 Begin an appendix subsection. The title appears in the table of | 20497 Begin an appendix subsection. The title appears in the table of |
| 17462 contents. In Info, the title is underlined with hyphens. | 20498 contents. In Info, the title is underlined with hyphens. |
| 17463 @xref{unnumberedsubsec appendixsubsec subheading, , Subsection | 20499 @xref{@t{@@unnumberedsubsec @@appendixsubsec @@subheading}}. |
| 17464 Commands}. | |
| 17465 | 20500 |
| 17466 @item @@appendixsubsubsec @var{title} | 20501 @item @@appendixsubsubsec @var{title} |
| 17467 Begin an appendix subsubsection. The title appears in the table of | 20502 Begin an appendix subsubsection. The title appears in the table of |
| 17468 contents. In Info, the title is underlined with periods. | 20503 contents. In Info, the title is underlined with periods. |
| 17469 @xref{subsubsection,, The `subsub' Commands}. | 20504 @xref{@t{@@subsubsection}}. |
| 17470 | 20505 |
| 17471 @item @@arrow@{@} | 20506 @item @@arrow@{@} |
| 17472 Generate a right arrow glyph: @samp{@arrow{}}. Used by default | 20507 Generate a right arrow glyph: @samp{@arrow{}}. Used by default |
| 17473 for @code{@@click}. @xref{Click Sequences}. | 20508 for @code{@@click}. @xref{Click Sequences}. |
| 17474 | 20509 |
| 17475 @item @@asis | 20510 @item @@asis |
| 17476 Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to | 20511 Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to |
| 17477 print the table's first column without highlighting (``as is''). | 20512 print the table's first column without highlighting (``as is''). |
| 17478 @xref{Two-column Tables}. | 20513 @xref{@t{@@asis}}. |
| 17479 | 20514 |
| 17480 @item @@author @var{author} | 20515 @item @@author @var{author} |
| 17481 Typeset @var{author} flushleft and underline it. @xref{title | 20516 Typeset @var{author} flushleft and underline it. @xref{@t{@@title |
| 17482 subtitle author, , The @code{@@title} and @code{@@author} | 20517 @@subtitle @@author}}. |
| 17483 Commands}.@refill | |
| 17484 | 20518 |
| 17485 @item @@b@{@var{text}@} | 20519 @item @@b@{@var{text}@} |
| 17486 Set @var{text} in a @b{bold} font. No effect in Info. @xref{Fonts}. | 20520 Set @var{text} in a @b{bold} font. No effect in Info. @xref{Fonts}. |
| 17487 | 20521 |
| 17488 @ignore | |
| 17489 @item @@br | |
| 17490 Force a paragraph break. If used within a line, follow @code{@@br} | |
| 17491 with braces. @xref{br, , @code{@@br}}.@refill | |
| 17492 @end ignore | |
| 17493 | |
| 17494 @item @@bullet@{@} | 20522 @item @@bullet@{@} |
| 17495 Generate a large round dot, @bullet{} (@samp{*} in Info). Often used | 20523 Generate a large round dot, @bullet{} (@samp{*} in Info). Often used |
| 17496 with @code{@@table}. @xref{bullet, , @code{@@bullet}}. | 20524 with @code{@@table}. @xref{@t{@@bullet}}. |
| 17497 | 20525 |
| 17498 @item @@bye | 20526 @item @@bye |
| 17499 Stop formatting a file. The formatters do not see anything in the | 20527 Stop formatting a file. The formatters do not see anything in the |
| 17500 input file following @code{@@bye}. @xref{Ending a File}. | 20528 input file following @code{@@bye}. @xref{Ending a File}. |
| 17501 | 20529 |
| 17502 @item @@c @var{comment} | 20530 @item @@c @var{comment} |
| 17503 Begin a comment in Texinfo. The rest of the line does not appear in | 20531 Begin a comment in Texinfo. The rest of the line does not appear in |
| 17504 any output. A synonym for | 20532 any output. A synonym for @code{@@comment}. @kbd{DEL} also |
| 17505 @code{@@comment}. @xref{Comments}. | 20533 starts a comment. @xref{Comments}. |
| 17506 | 20534 |
| 17507 @item @@caption | 20535 @item @@caption |
| 17508 Define the full caption for a @code{@@float}. @xref{caption shortcaption}. | 20536 Define the full caption for an @code{@@float}. @xref{@t{@@caption |
| 20537 @@shortcaption}}. | |
| 17509 | 20538 |
| 17510 @item @@cartouche | 20539 @item @@cartouche |
| 17511 Highlight an example or quotation by drawing a box with rounded | 20540 Highlight an example or quotation by drawing a box with rounded |
| 17512 corners around it. Pair with @code{@@end cartouche}. No effect in | 20541 corners around it. Pair with @code{@@end cartouche}. No effect in |
| 17513 Info. @xref{cartouche, , Drawing Cartouches Around Examples}.)@refill | 20542 Info. @xref{@t{@@cartouche}}. |
| 17514 | 20543 |
| 17515 @item @@center @var{line-of-text} | 20544 @item @@center @var{line-of-text} |
| 17516 Center the line of text following the command. | 20545 Center the line of text following the command. |
| 17517 @xref{titlefont center sp, , @code{@@center}}.@refill | 20546 @xref{@t{@@titlefont @@center @@sp}}. |
| 17518 | 20547 |
| 17519 @item @@centerchap @var{line-of-text} | 20548 @item @@centerchap @var{line-of-text} |
| 17520 Like @code{@@chapter}, but centers the chapter title. @xref{chapter,, | 20549 Like @code{@@chapter}, but centers the chapter title. @xref{@t{@@chapter}}. |
| 17521 @code{@@chapter}}. | |
| 17522 | 20550 |
| 17523 @item @@chapheading @var{title} | 20551 @item @@chapheading @var{title} |
| 17524 Print an unnumbered chapter-like heading, but omit from the table of | 20552 Print an unnumbered chapter-like heading, but omit from the table of |
| 17525 contents. In Info, the title is underlined with asterisks. | 20553 contents. In Info, the title is underlined with asterisks. |
| 17526 @xref{majorheading & chapheading, , @code{@@majorheading} and | 20554 @xref{@t{@@majorheading @@chapheading}}. |
| 17527 @code{@@chapheading}}. | |
| 17528 | 20555 |
| 17529 @item @@chapter @var{title} | 20556 @item @@chapter @var{title} |
| 17530 Begin a numbered chapter. The chapter title appears in the table of | 20557 Begin a numbered chapter. The chapter title appears in the table of |
| 17531 contents. In Info, the title is underlined with asterisks. | 20558 contents. In Info, the title is underlined with asterisks. |
| 17532 @xref{chapter, , @code{@@chapter}}. | 20559 @xref{@t{@@chapter}}. |
| 17533 | 20560 |
| 17534 @item @@cindex @var{entry} | 20561 @item @@cindex @var{entry} |
| 17535 Add @var{entry} to the index of concepts. @xref{Index Entries, , | 20562 Add @var{entry} to the index of concepts. @xref{Index Entries, , |
| 17536 Defining the Entries of an Index}.@refill | 20563 Defining the Entries of an Index}. |
| 17537 | 20564 |
| 17538 @item @@cite@{@var{reference}@} | 20565 @item @@cite@{@var{reference}@} |
| 17539 Highlight the name of a book or other reference that has no companion | 20566 Highlight the name of a book or other reference that has no companion |
| 17540 Info file. @xref{cite, , @code{@@cite}}. | 20567 Info file. @xref{@t{@@cite}}. |
| 17541 | |
| 17542 @item @@click@{@} | |
| 17543 Represent a single ``click'' in a GUI. Used within | |
| 17544 @code{@@clicksequence}. @xref{Click Sequences}. | |
| 17545 | |
| 17546 @item @@clicksequence@{@var{action} @@click@{@} @var{action}@} | |
| 17547 Represent a sequence of clicks in a GUI. @xref{Click Sequences}. | |
| 17548 | |
| 17549 @item @@clickstyle @@@var{cmd} | |
| 17550 Execute @@@var{cmd} for each @code{@@click}; the default is | |
| 17551 @code{@@arrow}. The usual following empty braces on @@@var{cmd} are | |
| 17552 omitted. @xref{Click Sequences}. | |
| 17553 | 20568 |
| 17554 @item @@clear @var{flag} | 20569 @item @@clear @var{flag} |
| 17555 Unset @var{flag}, preventing the Texinfo formatting commands from | 20570 Unset @var{flag}, preventing the Texinfo formatting commands from |
| 17556 formatting text between subsequent pairs of @code{@@ifset @var{flag}} | 20571 formatting text between subsequent pairs of @code{@@ifset @var{flag}} |
| 17557 and @code{@@end ifset} commands, and preventing | 20572 and @code{@@end ifset} commands, and preventing |
| 17558 @code{@@value@{@var{flag}@}} from expanding to the value to which | 20573 @code{@@value@{@var{flag}@}} from expanding to the value to which |
| 17559 @var{flag} is set. | 20574 @var{flag} is set. @xref{@t{@@set @@clear @@value}}. |
| 17560 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill | 20575 |
| 20576 @item @@click@{@} | |
| 20577 Represent a single ``click'' in a GUI@. Used within | |
| 20578 @code{@@clicksequence}. @xref{Click Sequences}. | |
| 20579 | |
| 20580 @item @@clicksequence@{@var{action} @@click@{@} @var{action}@} | |
| 20581 Represent a sequence of clicks in a GUI@. @xref{Click Sequences}. | |
| 20582 | |
| 20583 @item @@clickstyle @@@var{cmd} | |
| 20584 Execute @@@var{cmd} for each @code{@@click}; the default is | |
| 20585 @code{@@arrow}. The usual following empty braces on @@@var{cmd} are | |
| 20586 omitted. @xref{Click Sequences}. | |
| 17561 | 20587 |
| 17562 @item @@code@{@var{sample-code}@} | 20588 @item @@code@{@var{sample-code}@} |
| 17563 Indicate an expression, a syntactically complete token of a program, | 20589 Indicate an expression, a syntactically complete token of a program, |
| 17564 or a program name. Unquoted in Info output. @xref{code, , | 20590 or a program name. Unquoted in Info output. @xref{@t{@@code}}. |
| 17565 @code{@@code}}. | 20591 |
| 20592 @item @@codequotebacktick @var{on-off} | |
| 20593 @itemx @@codequoteundirected @var{on-off} | |
| 20594 Control output of @code{`} and @code{'} in code examples. | |
| 20595 @xref{Inserting Quote Characters}. | |
| 17566 | 20596 |
| 17567 @item @@comma@{@} | 20597 @item @@comma@{@} |
| 17568 Insert a comma `,' character; only needed when a literal comma would | 20598 Insert a comma `,' character; only needed when a literal comma would |
| 17569 be taken as an argument separator. @xref{Inserting a Comma}. | 20599 be taken as an argument separator. @xref{Inserting a Comma}. |
| 17570 | 20600 |
| 17571 @item @@command@{@var{command-name}@} | 20601 @item @@command@{@var{command-name}@} |
| 17572 Indicate a command name, such as @command{ls}. | 20602 Indicate a command name, such as @command{ls}. @xref{@t{@@command}}. |
| 17573 @xref{command,, @code{@@command}}. | |
| 17574 | 20603 |
| 17575 @item @@comment @var{comment} | 20604 @item @@comment @var{comment} |
| 17576 Begin a comment in Texinfo. The rest of the line does not appear in | 20605 Begin a comment in Texinfo. The rest of the line does not appear in |
| 17577 any output. A synonym for @code{@@c}. | 20606 any output. A synonym for @code{@@c}. |
| 17578 @xref{Comments}. | 20607 @xref{Comments}. |
| 17579 | 20608 |
| 17580 @item @@contents | 20609 @item @@contents |
| 17581 Print a complete table of contents. Has no effect in Info, which uses | 20610 Print a complete table of contents. Has no effect in Info, which uses |
| 17582 menus instead. @xref{Contents, , Generating a Table of | 20611 menus instead. @xref{Contents, , Generating a Table of Contents}. |
| 17583 Contents}.@refill | 20612 |
| 20613 @item @@copying | |
| 20614 Specify copyright holders and copying conditions for the document Pair | |
| 20615 with @code{@@end cartouche}. @xref{@t{@@copying}}. | |
| 17584 | 20616 |
| 17585 @item @@copyright@{@} | 20617 @item @@copyright@{@} |
| 17586 Generate the copyright symbol @copyright{}. @xref{copyright symbol,, | 20618 Generate the copyright symbol @copyright{}. |
| 17587 @code{@@copyright@{@}}}. | 20619 @xref{@t{@@copyright}}. |
| 17588 | |
| 17589 @ignore | |
| 17590 @item @@ctrl@{@var{ctrl-char}@} | |
| 17591 Describe an ASCII control character. Insert actual control character | |
| 17592 into Info file. @xref{ctrl, , @code{@@ctrl}}. | |
| 17593 @end ignore | |
| 17594 | 20620 |
| 17595 @item @@defcodeindex @var{index-name} | 20621 @item @@defcodeindex @var{index-name} |
| 17596 Define a new index and its indexing command. Print entries in an | 20622 Define a new index and its indexing command. Print entries in an |
| 17597 @code{@@code} font. @xref{New Indices, , Defining New Indices}. | 20623 @code{@@code} font. @xref{New Indices, , Defining New Indices}. |
| 17598 | 20624 |
| 17599 @item @@defcv @var{category} @var{class} @var{name} | 20625 @item @@defcv @var{category} @var{class} @var{name} |
| 17600 @itemx @@defcvx @var{category} @var{class} @var{name} | 20626 @itemx @@defcvx @var{category} @var{class} @var{name} |
| 17601 Format a description for a variable associated with a class in | 20627 Format a description for a variable associated with a class in |
| 17602 object-oriented programming. Takes three arguments: the category of | 20628 object-oriented programming. Takes three arguments: the category of |
| 17603 thing being defined, the class to which it belongs, and its name. | 20629 thing being defined, the class to which it belongs, and its name. |
| 17604 @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. | 20630 @xref{Definition Commands}. |
| 17605 | 20631 |
| 17606 @item @@deffn @var{category} @var{name} @var{arguments}@dots{} | 20632 @item @@deffn @var{category} @var{name} @var{arguments}@dots{} |
| 17607 @itemx @@deffnx @var{category} @var{name} @var{arguments}@dots{} | 20633 @itemx @@deffnx @var{category} @var{name} @var{arguments}@dots{} |
| 17608 Format a description for a function, interactive command, or similar | 20634 Format a description for a function, interactive command, or similar |
| 17609 entity that may take arguments. @code{@@deffn} takes as arguments the | 20635 entity that may take arguments. @code{@@deffn} takes as arguments the |
| 17610 category of entity being described, the name of this particular | 20636 category of entity being described, the name of this particular |
| 17611 entity, and its arguments, if any. @xref{Definition Commands}.@refill | 20637 entity, and its arguments, if any. @xref{Definition Commands}. |
| 17612 | 20638 |
| 17613 @item @@defindex @var{index-name} | 20639 @item @@defindex @var{index-name} |
| 17614 Define a new index and its indexing command. Print entries in a roman | 20640 Define a new index and its indexing command. Print entries in a roman |
| 17615 font. @xref{New Indices, , Defining New Indices}.@refill | 20641 font. @xref{New Indices, , Defining New Indices}. |
| 17616 | 20642 |
| 17617 @item @@definfoenclose @var{newcmd}, @var{before}, @var{after} | 20643 @item @@definfoenclose @var{newcmd}, @var{before}, @var{after} |
| 17618 Must be used within @code{@@ifinfo}; create a new command | 20644 Must be used within @code{@@ifinfo}; create a new command |
| 17619 @code{@@@var{newcmd}} for Info that marks text by enclosing it in | 20645 @code{@@@var{newcmd}} for Info that marks text by enclosing it in |
| 17620 strings that precede and follow the text. @xref{definfoenclose}. | 20646 strings that precede and follow the text. |
| 20647 @xref{@t{@@definfoenclose}}. | |
| 17621 | 20648 |
| 17622 @item @@defivar @var{class} @var{instance-variable-name} | 20649 @item @@defivar @var{class} @var{instance-variable-name} |
| 17623 @itemx @@defivarx @var{class} @var{instance-variable-name} | 20650 @itemx @@defivarx @var{class} @var{instance-variable-name} |
| 17624 Format a description for an instance variable in object-oriented | 20651 Format a description for an instance variable in object-oriented |
| 17625 programming. The command is equivalent to @samp{@@defcv @{Instance | 20652 programming. The command is equivalent to @samp{@@defcv @{Instance |
| 17626 Variable@} @dots{}}. @xref{Definition Commands}, and @ref{deffnx,, | 20653 Variable@} @dots{}}. @xref{Definition Commands}. |
| 17627 Def Cmds in Detail}. | |
| 17628 | 20654 |
| 17629 @item @@defmac @var{macroname} @var{arguments}@dots{} | 20655 @item @@defmac @var{macroname} @var{arguments}@dots{} |
| 17630 @itemx @@defmacx @var{macroname} @var{arguments}@dots{} | 20656 @itemx @@defmacx @var{macroname} @var{arguments}@dots{} |
| 17631 Format a description for a macro; equivalent to @samp{@@deffn Macro | 20657 Format a description for a macro; equivalent to @samp{@@deffn Macro |
| 17632 @dots{}}. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in | 20658 @dots{}}. @xref{Definition Commands}. |
| 17633 Detail}. | |
| 17634 | 20659 |
| 17635 @item @@defmethod @var{class} @var{method-name} @var{arguments}@dots{} | 20660 @item @@defmethod @var{class} @var{method-name} @var{arguments}@dots{} |
| 17636 @itemx @@defmethodx @var{class} @var{method-name} @var{arguments}@dots{} | 20661 @itemx @@defmethodx @var{class} @var{method-name} @var{arguments}@dots{} |
| 17637 Format a description for a method in object-oriented programming; | 20662 Format a description for a method in object-oriented programming; |
| 17638 equivalent to @samp{@@defop Method @dots{}}. @xref{Definition | 20663 equivalent to @samp{@@defop Method @dots{}}. @xref{Definition |
| 17639 Commands}, and @ref{deffnx,, Def Cmds in Detail}. | 20664 Commands}. |
| 17640 | 20665 |
| 17641 @item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} | 20666 @item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} |
| 17642 @itemx @@defopx @var{category} @var{class} @var{name} @var{arguments}@dots{} | 20667 @itemx @@defopx @var{category} @var{class} @var{name} @var{arguments}@dots{} |
| 17643 Format a description for an operation in object-oriented programming. | 20668 Format a description for an operation in object-oriented programming. |
| 17644 @code{@@defop} takes as arguments the name of the category of | 20669 @code{@@defop} takes as arguments the name of the category of |
| 17647 @ref{Abstract Objects}. | 20672 @ref{Abstract Objects}. |
| 17648 | 20673 |
| 17649 @item @@defopt @var{option-name} | 20674 @item @@defopt @var{option-name} |
| 17650 @itemx @@defoptx @var{option-name} | 20675 @itemx @@defoptx @var{option-name} |
| 17651 Format a description for a user option; equivalent to @samp{@@defvr | 20676 Format a description for a user option; equivalent to @samp{@@defvr |
| 17652 @{User Option@} @dots{}}. @xref{Definition Commands}, and | 20677 @{User Option@} @dots{}}. @xref{Definition Commands}. |
| 17653 @ref{deffnx,, Def Cmds in Detail}. | |
| 17654 | 20678 |
| 17655 @item @@defspec @var{special-form-name} @var{arguments}@dots{} | 20679 @item @@defspec @var{special-form-name} @var{arguments}@dots{} |
| 17656 @itemx @@defspecx @var{special-form-name} @var{arguments}@dots{} | 20680 @itemx @@defspecx @var{special-form-name} @var{arguments}@dots{} |
| 17657 Format a description for a special form; equivalent to @samp{@@deffn | 20681 Format a description for a special form; equivalent to @samp{@@deffn |
| 17658 @{Special Form@} @dots{}}. @xref{Definition Commands}, and | 20682 @{Special Form@} @dots{}}. @xref{Definition Commands}. |
| 17659 @ref{deffnx,, Def Cmds in Detail}. | |
| 17660 | 20683 |
| 17661 @item @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{} | 20684 @item @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{} |
| 17662 @itemx @@deftpx @var{category} @var{name-of-type} @var{attributes}@dots{} | 20685 @itemx @@deftpx @var{category} @var{name-of-type} @var{attributes}@dots{} |
| 17663 Format a description for a data type; its arguments are the category, | 20686 Format a description for a data type; its arguments are the category, |
| 17664 the name of the type (e.g., @samp{int}) , and then the names of | 20687 the name of the type (e.g., @samp{int}) , and then the names of |
| 17673 @item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{} | 20696 @item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{} |
| 17674 @itemx @@deftypefnx @var{category} @var{data-type} @var{name} @var{arguments}@dots{} | 20697 @itemx @@deftypefnx @var{category} @var{data-type} @var{name} @var{arguments}@dots{} |
| 17675 Format a description for a function or similar entity that may take | 20698 Format a description for a function or similar entity that may take |
| 17676 arguments and that is typed. @code{@@deftypefn} takes as arguments the | 20699 arguments and that is typed. @code{@@deftypefn} takes as arguments the |
| 17677 category of entity being described, the type, the name of the | 20700 category of entity being described, the type, the name of the |
| 17678 entity, and its arguments, if any. @xref{Definition Commands}, and | 20701 entity, and its arguments, if any. @xref{Definition Commands}. |
| 17679 @ref{deffnx,, Def Cmds in Detail}. | 20702 |
| 20703 @item @@deftypefnnewline @var{on-off} | |
| 20704 Specifies whether return types for @code{@@deftypefn} and similar are | |
| 20705 printed on lines by themselves; default is off. @xref{Typed | |
| 20706 Functions,, Functions in Typed Languages}. | |
| 17680 | 20707 |
| 17681 @item @@deftypefun @var{data-type} @var{function-name} @var{arguments}@dots{} | 20708 @item @@deftypefun @var{data-type} @var{function-name} @var{arguments}@dots{} |
| 17682 @itemx @@deftypefunx @var{data-type} @var{function-name} @var{arguments}@dots{} | 20709 @itemx @@deftypefunx @var{data-type} @var{function-name} @var{arguments}@dots{} |
| 17683 Format a description for a function in a typed language. | 20710 Format a description for a function in a typed language. |
| 17684 The command is equivalent to @samp{@@deftypefn Function @dots{}}. | 20711 The command is equivalent to @samp{@@deftypefn Function @dots{}}. |
| 17685 @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. | 20712 @xref{Definition Commands}. |
| 17686 | 20713 |
| 17687 @item @@deftypeivar @var{class} @var{data-type} @var{variable-name} | 20714 @item @@deftypeivar @var{class} @var{data-type} @var{variable-name} |
| 17688 @itemx @@deftypeivarx @var{class} @var{data-type} @var{variable-name} | 20715 @itemx @@deftypeivarx @var{class} @var{data-type} @var{variable-name} |
| 17689 Format a description for a typed instance variable in object-oriented | 20716 Format a description for a typed instance variable in object-oriented |
| 17690 programming. @xref{Definition Commands}, and @ref{Abstract Objects}. | 20717 programming. @xref{Definition Commands}, and @ref{Abstract Objects}. |
| 17691 | 20718 |
| 17692 @item @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{} | 20719 @item @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{} |
| 17693 @itemx @@deftypemethodx @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{} | 20720 @itemx @@deftypemethodx @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{} |
| 17694 Format a description for a typed method in object-oriented programming. | 20721 Format a description for a typed method in object-oriented programming. |
| 17695 @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. | 20722 @xref{Definition Commands}. |
| 17696 | 20723 |
| 17697 @item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} | 20724 @item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} |
| 17698 @itemx @@deftypeopx @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} | 20725 @itemx @@deftypeopx @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} |
| 17699 Format a description for a typed operation in object-oriented programming. | 20726 Format a description for a typed operation in object-oriented programming. |
| 17700 @xref{Definition Commands}, and @ref{Abstract Objects}. | 20727 @xref{Definition Commands}, and @ref{Abstract Objects}. |
| 17701 | 20728 |
| 17702 @item @@deftypevar @var{data-type} @var{variable-name} | 20729 @item @@deftypevar @var{data-type} @var{variable-name} |
| 17703 @itemx @@deftypevarx @var{data-type} @var{variable-name} | 20730 @itemx @@deftypevarx @var{data-type} @var{variable-name} |
| 17704 Format a description for a variable in a typed language. The command is | 20731 Format a description for a variable in a typed language. The command is |
| 17705 equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition | 20732 equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition |
| 17706 Commands}, and @ref{deffnx,, Def Cmds in Detail}. | 20733 Commands}. |
| 17707 | 20734 |
| 17708 @item @@deftypevr @var{category} @var{data-type} @var{name} | 20735 @item @@deftypevr @var{category} @var{data-type} @var{name} |
| 17709 @itemx @@deftypevrx @var{category} @var{data-type} @var{name} | 20736 @itemx @@deftypevrx @var{category} @var{data-type} @var{name} |
| 17710 Format a description for something like a variable in a typed | 20737 Format a description for something like a variable in a typed |
| 17711 language---an entity that records a value. Takes as arguments the | 20738 language---an entity that records a value. Takes as arguments the |
| 17712 category of entity being described, the type, and the name of the | 20739 category of entity being described, the type, and the name of the |
| 17713 entity. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in | 20740 entity. @xref{Definition Commands}. |
| 17714 Detail}. | |
| 17715 | 20741 |
| 17716 @item @@defun @var{function-name} @var{arguments}@dots{} | 20742 @item @@defun @var{function-name} @var{arguments}@dots{} |
| 17717 @itemx @@defunx @var{function-name} @var{arguments}@dots{} | 20743 @itemx @@defunx @var{function-name} @var{arguments}@dots{} |
| 17718 Format a description for a function; equivalent to | 20744 Format a description for a function; equivalent to |
| 17719 @samp{@@deffn Function @dots{}}. @xref{Definition Commands}, and | 20745 @samp{@@deffn Function @dots{}}. @xref{Definition Commands}. |
| 17720 @ref{deffnx,, Def Cmds in Detail}. | |
| 17721 | 20746 |
| 17722 @item @@defvar @var{variable-name} | 20747 @item @@defvar @var{variable-name} |
| 17723 @itemx @@defvarx @var{variable-name} | 20748 @itemx @@defvarx @var{variable-name} |
| 17724 Format a description for a variable; equivalent to @samp{@@defvr | 20749 Format a description for a variable; equivalent to @samp{@@defvr |
| 17725 Variable @dots{}}. @xref{Definition Commands}, and @ref{deffnx,, Def | 20750 Variable @dots{}}. @xref{Definition Commands}. |
| 17726 Cmds in Detail}. | |
| 17727 | 20751 |
| 17728 @item @@defvr @var{category} @var{name} | 20752 @item @@defvr @var{category} @var{name} |
| 17729 @itemx @@defvrx @var{category} @var{name} | 20753 @itemx @@defvrx @var{category} @var{name} |
| 17730 Format a description for any kind of variable. @code{@@defvr} takes | 20754 Format a description for any kind of variable. @code{@@defvr} takes |
| 17731 as arguments the category of the entity and the name of the entity. | 20755 as arguments the category of the entity and the name of the entity. |
| 17732 @xref{Definition Commands}, | 20756 @xref{Definition Commands}. |
| 17733 and @ref{deffnx,, Def Cmds in Detail}. | |
| 17734 | 20757 |
| 17735 @item @@detailmenu | 20758 @item @@detailmenu |
| 17736 Mark the (optional) detailed node listing in a master menu. | 20759 Mark the (optional) detailed node listing in a master menu. |
| 17737 @xref{Master Menu Parts}. | 20760 @xref{Master Menu Parts}. |
| 17738 | 20761 |
| 17739 @item @@dfn@{@var{term}@} | 20762 @item @@dfn@{@var{term}@} |
| 17740 Indicate the introductory or defining use of a term. @xref{dfn, , | 20763 Indicate the introductory or defining use of a term. @xref{@t{@@dfn}}. |
| 17741 @code{@@dfn}}. | 20764 |
| 20765 @item @@DH@{@} | |
| 20766 @itemx @@dh@{@} | |
| 20767 Generate the uppercase and lowercase Icelandic letter eth, respectively: | |
| 20768 @DH{}, @dh{}. @xref{Inserting Accents}. | |
| 17742 | 20769 |
| 17743 @item @@dircategory @var{dirpart} | 20770 @item @@dircategory @var{dirpart} |
| 17744 Specify a part of the Info directory menu where this file's entry should | 20771 Specify a part of the Info directory menu where this file's entry should |
| 17745 go. @xref{Installing Dir Entries}. | 20772 go. @xref{Installing Dir Entries}. |
| 17746 | 20773 |
| 17749 @code{@@end direntry}. @xref{Installing Dir Entries}. | 20776 @code{@@end direntry}. @xref{Installing Dir Entries}. |
| 17750 | 20777 |
| 17751 @item @@display | 20778 @item @@display |
| 17752 Begin a kind of example. Like @code{@@example} (indent text, do not | 20779 Begin a kind of example. Like @code{@@example} (indent text, do not |
| 17753 fill), but do not select a new font. Pair with @code{@@end display}. | 20780 fill), but do not select a new font. Pair with @code{@@end display}. |
| 17754 @xref{display, , @code{@@display}}. | 20781 @xref{@t{@@display}}. |
| 17755 | 20782 |
| 17756 @item @@dmn@{@var{dimension}@} | 20783 @item @@dmn@{@var{dimension}@} |
| 17757 Format a unit of measure, as in 12@dmn{pt}. Causes @TeX{} to insert a | 20784 Format a unit of measure, as in 12@dmn{pt}. Causes @TeX{} to insert a |
| 17758 thin space before @var{dimension}. No effect in Info. | 20785 thin space before @var{dimension}. No effect in Info. |
| 17759 @xref{dmn, , @code{@@dmn}}. | 20786 @xref{@t{@@dmn}}. |
| 17760 | 20787 |
| 17761 @item @@docbook | 20788 @item @@docbook |
| 17762 Enter Docbook completely. Pair with @code{@@end docbook}. @xref{Raw | 20789 Enter Docbook completely. Pair with @code{@@end docbook}. @xref{Raw |
| 17763 Formatter Commands}. | 20790 Formatter Commands}. |
| 17764 | 20791 |
| 17765 @item @@documentdescription | 20792 @item @@documentdescription |
| 17766 Set the document description text, included in the HTML output. Pair | 20793 Set the document description text, included in the HTML output. Pair |
| 17767 with @code{@@end documentdescription}. @xref{documentdescription,, | 20794 with @code{@@end documentdescription}. @xref{@t{@@documentdescription}}. |
| 17768 @code{@@documentdescription}}. | |
| 17769 | 20795 |
| 17770 @item @@documentencoding @var{enc} | 20796 @item @@documentencoding @var{enc} |
| 17771 Declare the input encoding to be @var{enc}. | 20797 Declare the input encoding to be @var{enc}. |
| 17772 @xref{documentencoding,, @code{@@documentencoding}}. | 20798 @xref{@t{@@documentencoding}}. |
| 17773 | 20799 |
| 17774 @item @@documentlanguage @var{CC} | 20800 @item @@documentlanguage @var{CC} |
| 17775 Declare the document language as the two-character ISO-639 abbreviation | 20801 Declare the document language as the two-character ISO-639 abbreviation |
| 17776 @var{CC}. @xref{documentlanguage,, @code{@@documentlanguage}}. | 20802 @var{CC}. @xref{@t{@@documentlanguage}}. |
| 17777 | 20803 |
| 17778 @item @@dotaccent@{@var{c}@} | 20804 @item @@dotaccent@{@var{c}@} |
| 17779 Generate a dot accent over the character @var{c}, as in @dotaccent{o}. | 20805 Generate a dot accent over the character @var{c}, as in @dotaccent{o}. |
| 17780 @xref{Inserting Accents}. | 20806 @xref{Inserting Accents}. |
| 17781 | 20807 |
| 20808 @item @@dotless@{@var{i-or-j}@} | |
| 20809 Generate dotless i (`@dotless{i}') and dotless j (`@dotless{j}'). | |
| 20810 @xref{Inserting Accents}. | |
| 20811 | |
| 17782 @item @@dots@{@} | 20812 @item @@dots@{@} |
| 17783 Generate an ellipsis, @samp{@dots{}}. | 20813 Generate an ellipsis, @samp{@dots{}}. |
| 17784 @xref{dots, , @code{@@dots}}.@refill | 20814 @xref{@t{@@dots}}. |
| 17785 | 20815 |
| 17786 @item @@email@{@var{address}[, @var{displayed-text}]@} | 20816 @item @@email@{@var{address}[, @var{displayed-text}]@} |
| 17787 Indicate an electronic mail address. | 20817 Indicate an electronic mail address. @xref{@t{@@email}}. |
| 17788 @xref{email, , @code{@@email}}. | |
| 17789 | 20818 |
| 17790 @item @@emph@{@var{text}@} | 20819 @item @@emph@{@var{text}@} |
| 17791 Emphasize @var{text}, by using @emph{italics} where possible, and | 20820 Emphasize @var{text}, by using @emph{italics} where possible, and |
| 17792 enclosing in asterisks in Info. @xref{Emphasis, , Emphasizing Text}. | 20821 enclosing in asterisks in Info. @xref{Emphasis, , Emphasizing Text}. |
| 17793 | 20822 |
| 17794 @item @@end @var{environment} | 20823 @item @@end @var{environment} |
| 17795 Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting | 20824 Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting |
| 17796 Commands,,@@-commands}. | 20825 Commands,,@@-commands}. |
| 17797 | 20826 |
| 17798 @item @@env@{@var{environment-variable}@} | |
| 17799 Indicate an environment variable name, such as @env{PATH}. | |
| 17800 @xref{env,, @code{@@env}}. | |
| 17801 | |
| 17802 @item @@enddots@{@} | 20827 @item @@enddots@{@} |
| 17803 Generate an end-of-sentence ellipsis, like this: @enddots{} | 20828 Generate an end-of-sentence ellipsis, like this: @enddots{} |
| 17804 @xref{dots,,@code{@@dots@{@}}}. | 20829 @xref{@t{@@dots}}. |
| 17805 | 20830 |
| 17806 @item @@enumerate [@var{number-or-letter}] | 20831 @item @@enumerate [@var{number-or-letter}] |
| 17807 Begin a numbered list, using @code{@@item} for each entry. | 20832 Begin a numbered list, using @code{@@item} for each entry. |
| 17808 Optionally, start list with @var{number-or-letter}. Pair with | 20833 Optionally, start list with @var{number-or-letter}. Pair with |
| 17809 @code{@@end enumerate}. @xref{enumerate, , | 20834 @code{@@end enumerate}. @xref{@t{@@enumerate}}. |
| 17810 @code{@@enumerate}}.@refill | 20835 |
| 20836 @item @@env@{@var{environment-variable}@} | |
| 20837 Indicate an environment variable name, such as @env{PATH}. | |
| 20838 @xref{@t{@@env}}. | |
| 17811 | 20839 |
| 17812 @item @@equiv@{@} | 20840 @item @@equiv@{@} |
| 17813 Indicate to the reader the exact equivalence of two forms with a | 20841 Indicate to the reader the exact equivalence of two forms with a |
| 17814 glyph: @samp{@equiv{}}. @xref{Equivalence}.@refill | 20842 glyph: @samp{@equiv{}}. @xref{@t{@@equiv}}. |
| 17815 | |
| 17816 @item @@euro@{@} | |
| 17817 Generate the Euro currency sign. | |
| 17818 @xref{euro,,@code{@@euro@{@}}}. | |
| 17819 | 20843 |
| 17820 @item @@error@{@} | 20844 @item @@error@{@} |
| 17821 Indicate to the reader with a glyph that the following text is | 20845 Indicate to the reader with a glyph that the following text is |
| 17822 an error message: @samp{@error{}}. @xref{Error Glyph}.@refill | 20846 an error message: @samp{@error{}}. @xref{@t{@@error}}. |
| 17823 | 20847 |
| 17824 @item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] | 20848 @item @@errormsg@{@var{msg}@} |
| 20849 Report @var{msg} as an error to standard error, and exit unsuccessfully. | |
| 20850 Texinfo commands within @var{msg} are expanded to plain text. | |
| 20851 @xref{Conditionals}, and @ref{External Macro Processors}. | |
| 20852 | |
| 20853 @item @@euro@{@} | |
| 20854 Generate the Euro currency sign. @xref{@t{@@euro}}. | |
| 20855 | |
| 20856 @item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] | |
| 17825 @itemx @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}] | 20857 @itemx @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}] |
| 17826 Specify page footings resp.@: headings for even-numbered (left-hand) | 20858 Specify page footings resp.@: headings for even-numbered (left-hand) |
| 17827 pages. @xref{Custom Headings, , | 20859 pages. @xref{Custom Headings, , |
| 17828 How to Make Your Own Headings}.@refill | 20860 How to Make Your Own Headings}. |
| 17829 | 20861 |
| 17830 @item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] | 20862 @item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] |
| 17831 @itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}] | 20863 @itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}] |
| 17832 Specify page footings resp.@: headings for every page. Not relevant to | 20864 Specify page footings resp.@: headings for every page. Not relevant to |
| 17833 Info. @xref{Custom Headings, , How to Make Your Own Headings}. | 20865 Info. @xref{Custom Headings, , How to Make Your Own Headings}. |
| 17834 | 20866 |
| 17835 @item @@example | 20867 @item @@example |
| 17836 Begin an example. Indent text, do not fill, and select fixed-width | 20868 Begin an example. Indent text, do not fill, and select fixed-width |
| 17837 font. Pair with @code{@@end example}. @xref{example,, @code{@@example}}. | 20869 font. Pair with @code{@@end example}. @xref{@t{@@example}}. |
| 17838 | 20870 |
| 17839 @item @@exampleindent @var{indent} | 20871 @item @@exampleindent @var{indent} |
| 17840 Indent example-like environments by @var{indent} number of spaces | 20872 Indent example-like environments by @var{indent} number of spaces |
| 17841 (perhaps 0). @xref{exampleindent,, Paragraph Indenting}. | 20873 (perhaps 0). @xref{@t{@@exampleindent}}. |
| 17842 | 20874 |
| 17843 @item @@exclamdown@{@} | 20875 @item @@exclamdown@{@} |
| 17844 Generate an upside-down exclamation point. @xref{Inserting Accents}. | 20876 Generate an upside-down exclamation point. @xref{Inserting Accents}. |
| 17845 | 20877 |
| 17846 @item @@exdent @var{line-of-text} | 20878 @item @@exdent @var{line-of-text} |
| 17847 Remove any indentation a line might have. @xref{exdent, , | 20879 Remove any indentation a line might have. @xref{@t{@@exdent}}. |
| 17848 Undoing the Indentation of a Line}.@refill | |
| 17849 | 20880 |
| 17850 @item @@expansion@{@} | 20881 @item @@expansion@{@} |
| 17851 Indicate the result of a macro expansion to the reader with a special | 20882 Indicate the result of a macro expansion to the reader with a special |
| 17852 glyph: @samp{@expansion{}}. | 20883 glyph: @samp{@expansion{}}. @xref{@t{@@expansion}}. |
| 17853 @xref{expansion, , @expansion{} Indicating an Expansion}.@refill | |
| 17854 | 20884 |
| 17855 @item @@file@{@var{filename}@} | 20885 @item @@file@{@var{filename}@} |
| 17856 Highlight the name of a file, buffer, node, directory, etc. @xref{file, , | 20886 Highlight the name of a file, buffer, node, directory, etc. |
| 17857 @code{@@file}}. | 20887 @xref{@t{@@file}}. |
| 17858 | 20888 |
| 17859 @item @@finalout | 20889 @item @@finalout |
| 17860 Prevent @TeX{} from printing large black warning rectangles beside | 20890 Prevent @TeX{} from printing large black warning rectangles beside |
| 17861 over-wide lines. @xref{Overfull hboxes}.@refill | 20891 over-wide lines. @xref{Overfull hboxes}. |
| 17862 | 20892 |
| 17863 @item @@findex @var{entry} | 20893 @item @@findex @var{entry} |
| 17864 Add @var{entry} to the index of functions. @xref{Index Entries, , | 20894 Add @var{entry} to the index of functions. @xref{Index Entries, , |
| 17865 Defining the Entries of an Index}.@refill | 20895 Defining the Entries of an Index}. |
| 20896 | |
| 20897 @item @@firstparagraphindent @var{word} | |
| 20898 Control indentation of the first paragraph after section headers | |
| 20899 according to @var{word}, one of `none' or `insert'. | |
| 20900 @xref{@t{@@firstparagraphindent}}. | |
| 17866 | 20901 |
| 17867 @item @@float | 20902 @item @@float |
| 17868 Environment to define floating material. Pair with @code{@@end float}. | 20903 Environment to define floating material. Pair with @code{@@end float}. |
| 17869 @xref{Floats}. | 20904 @xref{Floats}. |
| 17870 | 20905 |
| 17871 @item @@flushleft | 20906 @item @@flushleft |
| 17872 @itemx @@flushright | 20907 @itemx @@flushright |
| 17873 Do not fill text; left (right) justify every line while leaving the | 20908 Do not fill text; left (right) justify every line while leaving the |
| 17874 right (left) end ragged. Leave font as is. Pair with @code{@@end | 20909 right (left) end ragged. Leave font as is. Pair with @code{@@end |
| 17875 flushleft} (@code{@@end flushright}). @code{@@flushright} analogous. | 20910 flushleft} (@code{@@end flushright}). @xref{@t{@@flushleft |
| 17876 @xref{flushleft & flushright, , @code{@@flushleft} and | 20911 @@flushright}}. |
| 17877 @code{@@flushright}}. | 20912 |
| 20913 @item @@fonttextsize @var{10-11} | |
| 20914 Change the size of the main body font in the @TeX{} output. | |
| 20915 @xref{Fonts}. | |
| 17878 | 20916 |
| 17879 @item @@footnote@{@var{text-of-footnote}@} | 20917 @item @@footnote@{@var{text-of-footnote}@} |
| 17880 Enter a footnote. Footnote text is printed at the bottom of the page | 20918 Enter a footnote. Footnote text is printed at the bottom of the page |
| 17881 by @TeX{}; Info may format in either `End' node or `Separate' node style. | 20919 by @TeX{}; Info may format in either `End' node or `Separate' node style. |
| 17882 @xref{Footnotes}. | 20920 @xref{Footnotes}. |
| 17886 node style or @samp{separate} for the separate node style. | 20924 node style or @samp{separate} for the separate node style. |
| 17887 @xref{Footnotes}. | 20925 @xref{Footnotes}. |
| 17888 | 20926 |
| 17889 @item @@format | 20927 @item @@format |
| 17890 Begin a kind of example. Like @code{@@display}, but do not indent. | 20928 Begin a kind of example. Like @code{@@display}, but do not indent. |
| 17891 Pair with @code{@@end format}. @xref{example,, @code{@@example}}. | 20929 Pair with @code{@@end format}. @xref{@t{@@example}}. |
| 20930 | |
| 20931 @item @@frenchspacing @var{on-off} | |
| 20932 Control spacing after punctuation. @xref{@t{@@frenchspacing}}. | |
| 17892 | 20933 |
| 17893 @item @@ftable @var{formatting-command} | 20934 @item @@ftable @var{formatting-command} |
| 17894 Begin a two-column table, using @code{@@item} for each entry. | 20935 Begin a two-column table, using @code{@@item} for each entry. |
| 17895 Automatically enter each of the items in the first column into the | 20936 Automatically enter each of the items in the first column into the |
| 17896 index of functions. Pair with @code{@@end ftable}. The same as | 20937 index of functions. Pair with @code{@@end ftable}. The same as |
| 17897 @code{@@table}, except for indexing. @xref{ftable vtable, , | 20938 @code{@@table}, except for indexing. @xref{@t{@@ftable @@vtable}}. |
| 17898 @code{@@ftable} and @code{@@vtable}}.@refill | |
| 17899 | 20939 |
| 17900 @item @@geq@{@} | 20940 @item @@geq@{@} |
| 17901 Generate a greater-than-or-equal sign, `@geq{}'. @xref{geq leq}. | 20941 Generate a greater-than-or-equal sign, `@geq{}'. @xref{@t{@@geq @@leq}}. |
| 17902 | 20942 |
| 17903 @item @@group | 20943 @item @@group |
| 17904 Disallow page breaks within following text. Pair with @code{@@end | 20944 Disallow page breaks within following text. Pair with @code{@@end |
| 17905 group}. Ignored in Info. @xref{group, , @code{@@group}}. | 20945 group}. Ignored in Info. @xref{@t{@@group}}. |
| 20946 | |
| 20947 @item @@guillemetleft@{@} | |
| 20948 @itemx @@guillemetright@{@} | |
| 20949 @item @@guillemotleft@{@} | |
| 20950 @itemx @@guillemotright@{@} | |
| 20951 @itemx @@guilsinglleft@{@} | |
| 20952 @itemx @@guilsinglright@{@} | |
| 20953 Double and single angle quotation marks: @guillemetleft{} | |
| 20954 @guillemetright{} @guilsinglleft{} @guilsinglright{}. | |
| 20955 @code{@@guillemotleft} and @code{@@guillemotright} are synonyms for | |
| 20956 @code{@@guillemetleft} and @code{@@guillemetright}. @xref{Inserting | |
| 20957 Quotation Marks}. | |
| 17906 | 20958 |
| 17907 @item @@H@{@var{c}@} | 20959 @item @@H@{@var{c}@} |
| 17908 Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}. | 20960 Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}. |
| 20961 | |
| 20962 @item @@hashchar@{@} | |
| 20963 Insert a hash `#' character; only needed when a literal hash would | |
| 20964 introduce @code{#line} directive. @xref{Inserting a Hashsign}, and | |
| 20965 @ref{External Macro Processors}. | |
| 17909 | 20966 |
| 17910 @item @@heading @var{title} | 20967 @item @@heading @var{title} |
| 17911 Print an unnumbered section-like heading, but omit from the table of | 20968 Print an unnumbered section-like heading, but omit from the table of |
| 17912 contents. In Info, the title is underlined with equal signs. | 20969 contents. In Info, the title is underlined with equal signs. |
| 17913 @xref{unnumberedsec appendixsec heading, , Section Commands}. | 20970 @xref{@t{@@unnumberedsec @@appendixsec @@heading}}. |
| 17914 | 20971 |
| 17915 @item @@headings @var{on-off-single-double} | 20972 @item @@headings @var{on-off-single-double} |
| 17916 Turn page headings on or off, and/or specify single-sided or double-sided | 20973 Turn page headings on or off, and/or specify single-sided or double-sided |
| 17917 page headings for printing. @xref{headings on off, , The | 20974 page headings for printing. @xref{@t{@@headings}}. |
| 17918 @code{@@headings} Command}. | |
| 17919 | 20975 |
| 17920 @item @@headitem | 20976 @item @@headitem |
| 17921 Begin a heading row in a multitable. @xref{Multitable Rows}. | 20977 Begin a heading row in a multitable. @xref{Multitable Rows}. |
| 20978 | |
| 20979 @item @@headitemfont@{@var{text}@} | |
| 20980 Set @var{text} in the font used for multitable heading rows; mostly | |
| 20981 useful in multitable templates. @xref{Multitable Rows}. | |
| 17922 | 20982 |
| 17923 @item @@html | 20983 @item @@html |
| 17924 Enter HTML completely. Pair with @code{@@end html}. @xref{Raw | 20984 Enter HTML completely. Pair with @code{@@end html}. @xref{Raw |
| 17925 Formatter Commands}. | 20985 Formatter Commands}. |
| 17926 | 20986 |
| 17927 @item @@hyphenation@{@var{hy-phen-a-ted words}@} | 20987 @item @@hyphenation@{@var{hy-phen-a-ted words}@} |
| 17928 Explicitly define hyphenation points. @xref{- and hyphenation,, | 20988 Explicitly define hyphenation points. @xref{@t{@@- @@hyphenation}}. |
| 17929 @code{@@-} and @code{@@hyphenation}}. | |
| 17930 | 20989 |
| 17931 @item @@i@{@var{text}@} | 20990 @item @@i@{@var{text}@} |
| 17932 Set @var{text} in an @i{italic} font. No effect in Info. @xref{Fonts}. | 20991 Set @var{text} in an @i{italic} font. No effect in Info. @xref{Fonts}. |
| 17933 | 20992 |
| 17934 @item @@ifclear @var{txivar} | 20993 @item @@ifclear @var{txivar} |
| 17935 If the Texinfo variable @var{txivar} is not set, format the following | 20994 If the Texinfo variable @var{txivar} is not set, format the following |
| 17936 text. Pair with @code{@@end ifclear}. @xref{set clear value, , | 20995 text. Pair with @code{@@end ifclear}. @xref{@t{@@set @@clear |
| 17937 @code{@@set} @code{@@clear} @code{@@value}}. | 20996 @@value}}. |
| 20997 | |
| 20998 @item @@ifcommanddefined @var{txicmd} | |
| 20999 @itemx @@ifcommandnotdefined @var{txicmd} | |
| 21000 If the Texinfo code @samp{@@@var{txicmd}} is (not) defined, format the | |
| 21001 follow text. Pair with the corresponding @code{@@end ifcommand...}. | |
| 21002 @xref{Testing for Texinfo Commands}. | |
| 17938 | 21003 |
| 17939 @item @@ifdocbook | 21004 @item @@ifdocbook |
| 17940 @itemx @@ifhtml | 21005 @itemx @@ifhtml |
| 17941 @itemx @@ifinfo | 21006 @itemx @@ifinfo |
| 17942 Begin text that will appear only in the given output format. | 21007 Begin text that will appear only in the given output format. |
| 17964 Begin text that will appear only in the plain text output. | 21029 Begin text that will appear only in the plain text output. |
| 17965 Pair with @code{@@end ifplaintext}. @xref{Conditionals}. | 21030 Pair with @code{@@end ifplaintext}. @xref{Conditionals}. |
| 17966 | 21031 |
| 17967 @item @@ifset @var{txivar} | 21032 @item @@ifset @var{txivar} |
| 17968 If the Texinfo variable @var{txivar} is set, format the following | 21033 If the Texinfo variable @var{txivar} is set, format the following |
| 17969 text. Pair with @code{@@end ifset}. @xref{set clear value, , | 21034 text. Pair with @code{@@end ifset}. @xref{@t{@@set @@clear |
| 17970 @code{@@set} @code{@@clear} @code{@@value}}. | 21035 @@value}}. |
| 17971 | 21036 |
| 17972 @item @@iftex | 21037 @item @@iftex |
| 17973 Begin text to appear only in the @TeX{} output. Pair with @code{@@end | 21038 Begin text to appear only in the @TeX{} output. Pair with @code{@@end |
| 17974 iftex}. @xref{Conditionals, , Conditionally Visible Text}.@refill | 21039 iftex}. @xref{Conditionals, , Conditionally Visible Text}. |
| 17975 | 21040 |
| 17976 @item @@ifxml | 21041 @item @@ifxml |
| 17977 Begin text that will appear only in the XML output. Pair with | 21042 Begin text that will appear only in the XML output. Pair with |
| 17978 @code{@@end ifxml}. @xref{Conditionals}. | 21043 @code{@@end ifxml}. @xref{Conditionals}. |
| 17979 | 21044 |
| 17982 ignore}. @xref{Comments, , Comments and Ignored Text}. | 21047 ignore}. @xref{Comments, , Comments and Ignored Text}. |
| 17983 | 21048 |
| 17984 @item @@image@{@var{filename}, [@var{width}], [@var{height}], [@var{alt}], [@var{ext}]@} | 21049 @item @@image@{@var{filename}, [@var{width}], [@var{height}], [@var{alt}], [@var{ext}]@} |
| 17985 Include graphics image in external @var{filename} scaled to the given | 21050 Include graphics image in external @var{filename} scaled to the given |
| 17986 @var{width} and/or @var{height}, using @var{alt} text and looking for | 21051 @var{width} and/or @var{height}, using @var{alt} text and looking for |
| 17987 @samp{@var{filename}.@var{ext}} in HTML. @xref{Images}. | 21052 @samp{@var{filename}.@var{ext}} in HTML@. @xref{Images}. |
| 17988 | 21053 |
| 17989 @item @@include @var{filename} | 21054 @item @@include @var{filename} |
| 17990 Read the contents of Texinfo source file @var{filename}. @xref{Include Files}. | 21055 Read the contents of Texinfo source file @var{filename}. @xref{Include Files}. |
| 17991 | 21056 |
| 21057 @item @@indent | |
| 21058 Insert paragraph indentation. @xref{@t{@@indent}}. | |
| 21059 | |
| 21060 @item @@indentedblock | |
| 21061 Indent a block of arbitary text on the left. Pair with @code{@@end | |
| 21062 indentedblock}. @xref{@t{@@indentedblock}}. | |
| 21063 | |
| 17992 @item @@indicateurl@{@var{indicateurl}@} | 21064 @item @@indicateurl@{@var{indicateurl}@} |
| 17993 Indicate text that is a uniform resource locator for the World Wide | 21065 Indicate text that is a uniform resource locator for the World Wide |
| 17994 Web. @xref{indicateurl, , @code{@@indicateurl}}. | 21066 Web. @xref{@t{@@indicateurl}}. |
| 17995 | 21067 |
| 17996 @item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@} | 21068 @item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@} |
| 17997 Make a cross reference to an Info file for which there is no printed | 21069 Make a cross reference to an Info file for which there is no printed |
| 17998 manual. @xref{inforef, , Cross references using | 21070 manual. @xref{@t{@@inforef}}. |
| 17999 @code{@@inforef}}.@refill | 21071 |
| 21072 @item @@inlinefmt@{@var{fmt}, @var{text}@} | |
| 21073 Insert @var{text} only if the output format is @var{fmt}. | |
| 21074 @xref{Inline Conditionals}. | |
| 21075 | |
| 21076 @item @@inlinefmtifelse@{@var{fmt}, @var{text}, @var{else-text}@} | |
| 21077 Insert @var{text} if the output format is @var{fmt}, else @var{else-text}. | |
| 21078 | |
| 21079 @item @@inlineifclear@{@var{var}, @var{text}@} | |
| 21080 @itemx @@inlineifset@{@var{var}, @var{text}@} | |
| 21081 Insert @var{text} only if the Texinfo variable @var{var} is (not) set. | |
| 21082 | |
| 21083 @item @@inlineraw@{@var{fmt}, @var{raw-text}@} | |
| 21084 Insert @var{text} as in a raw conditional, only if the output format | |
| 21085 is @var{fmt}. | |
| 18000 | 21086 |
| 18001 @item \input @var{macro-definitions-file} | 21087 @item \input @var{macro-definitions-file} |
| 18002 Use the specified macro definitions file. This command is used only | 21088 Use the specified macro definitions file. This command is used only |
| 18003 in the first line of a Texinfo file to cause @TeX{} to make use of the | 21089 in the first line of a Texinfo file to cause @TeX{} to make use of the |
| 18004 @file{texinfo} macro definitions file. The backslash in @code{\input} | 21090 @file{texinfo} macro definitions file. The @code{\} in @code{\input} |
| 18005 is used instead of an @code{@@} because @TeX{} does not | 21091 is used instead of an @code{@@} because @TeX{} does not recognize |
| 18006 recognize @code{@@} until after it has read the definitions file. | 21092 @code{@@} until after it has read the definitions file. @xref{Texinfo |
| 18007 @xref{Texinfo File Header}. | 21093 File Header}. |
| 21094 | |
| 21095 @item @@insertcopying | |
| 21096 Insert the text previously defined with the @code{@@copying} | |
| 21097 environment. @xref{@t{@@insertcopying}}. | |
| 18008 | 21098 |
| 18009 @item @@item | 21099 @item @@item |
| 18010 Indicate the beginning of a marked paragraph for @code{@@itemize} and | 21100 Indicate the beginning of a marked paragraph for @code{@@itemize} and |
| 18011 @code{@@enumerate}; indicate the beginning of the text of a first column | 21101 @code{@@enumerate}; indicate the beginning of the text of a first column |
| 18012 entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}. | 21102 entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}. |
| 18013 @xref{Lists and Tables}. | 21103 @xref{Lists and Tables}. |
| 18014 | 21104 |
| 18015 @item @@itemize @var{mark-generating-character-or-command} | 21105 @item @@itemize @var{mark-generating-character-or-command} |
| 18016 Begin an unordered list: indented paragraphs with a mark, such as | 21106 Begin an unordered list: indented paragraphs with a mark, such as |
| 18017 @code{@@bullet}, inside the left margin at the beginning of each | 21107 @code{@@bullet}, inside the left margin at the beginning of each item. |
| 18018 item. Pair with @code{@@end itemize}. @xref{itemize, , | 21108 Pair with @code{@@end itemize}. @xref{@t{@@itemize}}. |
| 18019 @code{@@itemize}}. | |
| 18020 | 21109 |
| 18021 @item @@itemx | 21110 @item @@itemx |
| 18022 Like @code{@@item} but do not generate extra vertical space above the | 21111 Like @code{@@item} but do not generate extra vertical space above the |
| 18023 item text. Thus, when several items have the same description, use | 21112 item text. Thus, when several items have the same description, use |
| 18024 @code{@@item} for the first and @code{@@itemx} for the others. | 21113 @code{@@item} for the first and @code{@@itemx} for the others. |
| 18025 @xref{itemx, , @code{@@itemx}}. | 21114 @xref{@t{@@itemx}}. |
| 18026 | 21115 |
| 18027 @item @@kbd@{@var{keyboard-characters}@} | 21116 @item @@kbd@{@var{keyboard-characters}@} |
| 18028 Indicate characters of input to be typed by users. @xref{kbd, , | 21117 Indicate characters of input to be typed by users. @xref{@t{@@kbd}}. |
| 18029 @code{@@kbd}}. | |
| 18030 | 21118 |
| 18031 @item @@kbdinputstyle @var{style} | 21119 @item @@kbdinputstyle @var{style} |
| 18032 Specify when @code{@@kbd} should use a font distinct from | 21120 Specify when @code{@@kbd} should use a font distinct from |
| 18033 @code{@@code}. @xref{kbd, , @code{@@kbd}}. | 21121 @code{@@code} according to @var{style}: @code{code}, @code{distinct}, |
| 21122 @code{example}. @xref{@t{@@kbd}}. | |
| 18034 | 21123 |
| 18035 @item @@key@{@var{key-name}@} | 21124 @item @@key@{@var{key-name}@} |
| 18036 Indicate the name of a key on a keyboard. @xref{key, , @code{@@key}}. | 21125 Indicate the name of a key on a keyboard. @xref{@t{@@key}}. |
| 18037 | 21126 |
| 18038 @item @@kindex @var{entry} | 21127 @item @@kindex @var{entry} |
| 18039 Add @var{entry} to the index of keys. | 21128 Add @var{entry} to the index of keys. |
| 18040 @xref{Index Entries, , Defining the Entries of an Index}.@refill | 21129 @xref{Index Entries, , Defining the Entries of an Index}. |
| 18041 | 21130 |
| 18042 @item @@L@{@} | 21131 @item @@L@{@} |
| 18043 @itemx @@l@{@} | 21132 @itemx @@l@{@} |
| 18044 Generate the uppercase and lowercase Polish suppressed-L letters, | 21133 Generate the uppercase and lowercase Polish suppressed-L letters, |
| 18045 respectively: @L{}, @l{}. | 21134 respectively: @L{}, @l{}. |
| 18046 | 21135 |
| 18047 @item @@LaTeX@{@} | 21136 @item @@LaTeX@{@} |
| 18048 Generate the @LaTeX{} logo. @xref{tex, , @TeX{} and @LaTeX{}}. | 21137 Generate the @LaTeX{} logo. @xref{@t{@@TeX @@LaTeX}}. |
| 18049 | 21138 |
| 18050 @item @@leq@{@} | 21139 @item @@leq@{@} |
| 18051 Generate a less-than-or-equal sign, `@leq{}'. @xref{geq leq}. | 21140 Generate a less-than-or-equal sign, `@leq{}'. @xref{@t{@@geq @@leq}}. |
| 18052 | 21141 |
| 18053 @item @@lisp | 21142 @item @@lisp |
| 18054 Begin an example of Lisp code. Indent text, do not fill, and select | 21143 Begin an example of Lisp code. Indent text, do not fill, and select |
| 18055 fixed-width font. Pair with @code{@@end lisp}. @xref{lisp, , @code{@@lisp}}. | 21144 fixed-width font. Pair with @code{@@end lisp}. @xref{@t{@@lisp}}. |
| 18056 | 21145 |
| 18057 @item @@listoffloats | 21146 @item @@listoffloats |
| 18058 Produce a table-of-contents-like listing of @code{@@float}s. | 21147 Produce a table-of-contents-like listing of @code{@@float}s. |
| 18059 @xref{listoffloats}. | 21148 @xref{@t{@@listoffloats}}. |
| 18060 | 21149 |
| 18061 @item @@lowersections | 21150 @item @@lowersections |
| 18062 Change subsequent chapters to sections, sections to subsections, and so | 21151 Change subsequent chapters to sections, sections to subsections, and so |
| 18063 on. @xref{Raise/lower sections, , @code{@@raisesections} and | 21152 on. @xref{Raise/lower sections, , @code{@@raisesections} and |
| 18064 @code{@@lowersections}}.@refill | 21153 @code{@@lowersections}}. |
| 18065 | 21154 |
| 18066 @item @@macro @var{macroname} @{@var{params}@} | 21155 @item @@macro @var{macroname} @{@var{params}@} |
| 18067 Define a new Texinfo command @code{@@@var{macroname}@{@var{params}@}}. | 21156 Define a new Texinfo command @code{@@@var{macroname}@{@var{params}@}}. |
| 18068 Pair with @code{@@end macro}. @xref{Defining Macros}. | 21157 Pair with @code{@@end macro}. @xref{Defining Macros}. |
| 18069 | 21158 |
| 18070 @item @@majorheading @var{title} | 21159 @item @@majorheading @var{title} |
| 18071 Print an unnumbered chapter-like heading, but omit from | 21160 Print an unnumbered chapter-like heading, but omit from the table of |
| 18072 the table of contents. This generates more vertical whitespace before | 21161 contents. This generates more vertical whitespace before the heading |
| 18073 the heading than the @code{@@chapheading} command. @xref{majorheading | 21162 than the @code{@@chapheading} command. @xref{@t{@@majorheading |
| 18074 & chapheading, , @code{@@majorheading} and @code{@@chapheading}}. | 21163 @@chapheading}}. |
| 18075 | 21164 |
| 18076 @item @@math@{@var{mathematical-expression}@} | 21165 @item @@math@{@var{mathematical-expression}@} |
| 18077 Format a mathematical expression. | 21166 Format a mathematical expression. @xref{Inserting Math}. |
| 18078 @xref{math, , @code{@@math} - Inserting Mathematical Expressions}. | |
| 18079 | 21167 |
| 18080 @item @@menu | 21168 @item @@menu |
| 18081 Mark the beginning of a menu of nodes. No effect in a printed manual. | 21169 Mark the beginning of a menu of nodes. No effect in a printed manual. |
| 18082 Pair with @code{@@end menu}. @xref{Menus}. | 21170 Pair with @code{@@end menu}. @xref{Menus}. |
| 18083 | 21171 |
| 18084 @item @@minus@{@} | 21172 @item @@minus@{@} |
| 18085 Generate a minus sign, `@minus{}'. @xref{minus, , @code{@@minus}}. | 21173 Generate a minus sign, `@minus{}'. @xref{@t{@@minus}}. |
| 18086 | 21174 |
| 18087 @item @@multitable @var{column-width-spec} | 21175 @item @@multitable @var{column-width-spec} |
| 18088 Begin a multi-column table. Begin each row with @code{@@item} or | 21176 Begin a multi-column table. Begin each row with @code{@@item} or |
| 18089 @code{@@headitem}, and separate columns with @code{@@tab}. Pair with | 21177 @code{@@headitem}, and separate columns with @code{@@tab}. Pair with |
| 18090 @code{@@end multitable}. @xref{Multitable Column Widths}. | 21178 @code{@@end multitable}. @xref{Multitable Column Widths}. |
| 18091 | 21179 |
| 18092 @item @@need @var{n} | 21180 @item @@need @var{n} |
| 18093 Start a new page in a printed manual if fewer than @var{n} mils | 21181 Start a new page in a printed manual if fewer than @var{n} mils |
| 18094 (thousandths of an inch) remain on the current page. @xref{need, , | 21182 (thousandths of an inch) remain on the current page. |
| 18095 @code{@@need}}. | 21183 @xref{@t{@@need}}. |
| 18096 | 21184 |
| 18097 @item @@node @var{name}, @var{next}, @var{previous}, @var{up} | 21185 @item @@node @var{name}, @var{next}, @var{previous}, @var{up} |
| 18098 Begin a new node. @xref{node, , @code{@@node}}. | 21186 Begin a new node. @xref{@t{@@node}}. |
| 18099 | 21187 |
| 18100 @item @@noindent | 21188 @item @@noindent |
| 18101 Prevent text from being indented as if it were a new paragraph. | 21189 Prevent text from being indented as if it were a new paragraph. |
| 18102 @xref{noindent, , @code{@@noindent}}. | 21190 @xref{@t{@@noindent}}. |
| 18103 | 21191 |
| 18104 @item @@novalidate | 21192 @item @@novalidate |
| 18105 Suppress validation of node references and omit creation of auxiliary | 21193 Suppress validation of node references and omit creation of auxiliary |
| 18106 files with @TeX{}. Use before @code{@@setfilename}. @xref{Pointer | 21194 files with @TeX{}. Use before @code{@@setfilename}. @xref{Pointer |
| 18107 Validation}. | 21195 Validation}. |
| 18113 | 21201 |
| 18114 @item @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] | 21202 @item @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] |
| 18115 @itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}] | 21203 @itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}] |
| 18116 Specify page footings resp.@: headings for odd-numbered (right-hand) | 21204 Specify page footings resp.@: headings for odd-numbered (right-hand) |
| 18117 pages. @xref{Custom Headings, , | 21205 pages. @xref{Custom Headings, , |
| 18118 How to Make Your Own Headings}.@refill | 21206 How to Make Your Own Headings}. |
| 18119 | 21207 |
| 18120 @item @@OE@{@} | 21208 @item @@OE@{@} |
| 18121 @itemx @@oe@{@} | 21209 @itemx @@oe@{@} |
| 18122 Generate the uppercase and lowercase OE ligatures, respectively: | 21210 Generate the uppercase and lowercase OE ligatures, respectively: |
| 18123 @OE{}, @oe{}. @xref{Inserting Accents}. | 21211 @OE{}, @oe{}. @xref{Inserting Accents}. |
| 18124 | 21212 |
| 21213 @item @@ogonek@{@var{c}@} | |
| 21214 Generate an ogonek diacritic under the next character, as in | |
| 21215 @ogonek{a}. @xref{Inserting Accents}. | |
| 21216 | |
| 18125 @item @@option@{@var{option-name}@} | 21217 @item @@option@{@var{option-name}@} |
| 18126 Indicate a command-line option, such as @option{-l} or @option{--help}. | 21218 Indicate a command-line option, such as @option{-l} or |
| 18127 @xref{option,, @code{@@option}}. | 21219 @option{--help}. @xref{@t{@@option}}. |
| 21220 | |
| 21221 @item @@ordf@{@} | |
| 21222 @itemx @@ordm@{@} | |
| 21223 Generate the feminine and masculine Spanish ordinals, respectively: | |
| 21224 @ordf{}, @ordm{}. @xref{Inserting Accents}. | |
| 18128 | 21225 |
| 18129 @item @@page | 21226 @item @@page |
| 18130 Start a new page in a printed manual. No effect in Info. | 21227 Start a new page in a printed manual. No effect in Info. |
| 18131 @xref{page, , @code{@@page}}.@refill | 21228 @xref{@t{@@page}}. |
| 18132 | 21229 |
| 18133 @item @@pagesizes [@var{width}][, @var{height}] | 21230 @item @@pagesizes [@var{width}][, @var{height}] |
| 18134 Change page dimensions. @xref{pagesizes}. | 21231 Change page dimensions. @xref{pagesizes}. |
| 18135 | 21232 |
| 18136 @item @@paragraphindent @var{indent} | 21233 @item @@paragraphindent @var{indent} |
| 18137 Indent paragraphs by @var{indent} number of spaces (perhaps 0); preserve | 21234 Indent paragraphs by @var{indent} number of spaces (perhaps 0); preserve |
| 18138 source file indentation if @var{indent} is @code{asis}. | 21235 source file indentation if @var{indent} is @code{asis}. |
| 18139 @xref{paragraphindent,, Paragraph Indenting}. | 21236 @xref{@t{@@paragraphindent}}. |
| 21237 | |
| 21238 @item @@part @var{title} | |
| 21239 Begin a group of chapters or appendixes; included in the tables of | |
| 21240 contents and produces a page of its own in printed output. | |
| 21241 @xref{@t{@@part}}. | |
| 18140 | 21242 |
| 18141 @item @@pindex @var{entry} | 21243 @item @@pindex @var{entry} |
| 18142 Add @var{entry} to the index of programs. @xref{Index Entries, , Defining | 21244 Add @var{entry} to the index of programs. @xref{Index Entries, , Defining |
| 18143 the Entries of an Index}.@refill | 21245 the Entries of an Index}. |
| 18144 | 21246 |
| 18145 @item @@point@{@} | 21247 @item @@point@{@} |
| 18146 Indicate the position of point in a buffer to the reader with a | 21248 Indicate the position of point in a buffer to the reader with a glyph: |
| 18147 glyph: @samp{@point{}}. @xref{Point Glyph, , Indicating | 21249 @samp{@point{}}. @xref{@t{@@point}}. |
| 18148 Point in a Buffer}.@refill | |
| 18149 | 21250 |
| 18150 @item @@pounds@{@} | 21251 @item @@pounds@{@} |
| 18151 Generate the pounds sterling currency sign. | 21252 Generate the pounds sterling currency sign. |
| 18152 @xref{pounds,,@code{@@pounds@{@}}}. | 21253 @xref{@t{@@pounds}}. |
| 18153 | 21254 |
| 18154 @item @@print@{@} | 21255 @item @@print@{@} |
| 18155 Indicate printed output to the reader with a glyph: | 21256 Indicate printed output to the reader with a glyph: @samp{@print{}}. |
| 18156 @samp{@print{}}. @xref{Print Glyph}.@refill | 21257 @xref{@t{@@print}}. |
| 18157 | 21258 |
| 18158 @item @@printindex @var{index-name} | 21259 @item @@printindex @var{index-name} |
| 18159 Generate the alphabetized index for @var{index-name} (using two columns in a printed | 21260 Generate the alphabetized index for @var{index-name} (using two |
| 18160 manual). @xref{Printing Indices & Menus}. | 21261 columns in a printed manual). @xref{Printing Indices & Menus}. |
| 18161 | 21262 |
| 18162 @item @@pxref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@} | 21263 @item @@pxref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@} |
| 18163 Make a reference that starts with a lower case `see' in a printed | 21264 Make a reference that starts with a lowercase `see' in a printed |
| 18164 manual. Use within parentheses only. Only the first argument is | 21265 manual. Use within parentheses only. Only the first argument is |
| 18165 mandatory. @xref{pxref, , @code{@@pxref}}. | 21266 mandatory. @xref{@t{@@pxref}}. |
| 18166 | 21267 |
| 18167 @item @@questiondown@{@} | 21268 @item @@questiondown@{@} |
| 18168 Generate an upside-down question mark. @xref{Inserting Accents}. | 21269 Generate an upside-down question mark. @xref{Inserting Accents}. |
| 18169 | 21270 |
| 18170 @item @@quotation | 21271 @item @@quotation |
| 18171 Narrow the margins to indicate text that is quoted from another work. | 21272 Narrow the margins to indicate text that is quoted from another work. |
| 18172 Takes optional argument of prefix text. Pair with @code{@@end | 21273 Takes optional argument specifying prefix text, e.g., an author name. |
| 18173 quotation}. @xref{quotation, , @code{@@quotation}}. | 21274 Pair with @code{@@end quotation}. @xref{@t{@@quotation}}. |
| 21275 | |
| 21276 @item @@quotedblleft@{@} | |
| 21277 @itemx @@quotedblright@{@} | |
| 21278 @itemx @@quoteleft@{@} | |
| 21279 @itemx @@quoteright@{@} | |
| 21280 @itemx @@quotedblbase@{@} | |
| 21281 @itemx @@quotesinglbase@{@} | |
| 21282 Produce various quotation marks: @quotedblleft{} @quotedblright{} | |
| 21283 @quoteleft{} @quoteright{} @quotedblbase{} @quotesinglbase{}. | |
| 21284 @xref{Inserting Quotation Marks}. | |
| 18174 | 21285 |
| 18175 @item @@r@{@var{text}@} | 21286 @item @@r@{@var{text}@} |
| 18176 Set @var{text} in the regular @r{roman} font. No effect in Info. | 21287 Set @var{text} in the regular @r{roman} font. No effect in Info. |
| 18177 @xref{Fonts}. | 21288 @xref{Fonts}. |
| 18178 | 21289 |
| 21290 @item @@raggedright | |
| 21291 Fill text; left justify every line while leaving the right end ragged. | |
| 21292 Leave font as is. Pair with @code{@@end raggedright}. No effect in | |
| 21293 Info. @xref{@t{@@raggedright}}. | |
| 21294 | |
| 18179 @item @@raisesections | 21295 @item @@raisesections |
| 18180 Change subsequent sections to chapters, subsections to sections, and so | 21296 Change subsequent sections to chapters, subsections to sections, and so |
| 18181 on. @xref{Raise/lower sections, , @code{@@raisesections} and | 21297 on. @xref{Raise/lower sections}. |
| 18182 @code{@@lowersections}}.@refill | |
| 18183 | 21298 |
| 18184 @item @@ref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@} | 21299 @item @@ref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@} |
| 18185 Make a plain reference that does not start with any special text. | 21300 Make a plain reference that does not start with any special text. |
| 18186 Follow command with a punctuation mark. Only the first argument is | 21301 Follow command with a punctuation mark. Only the first argument is |
| 18187 mandatory. @xref{ref, , @code{@@ref}}. | 21302 mandatory. @xref{@t{@@ref}}. |
| 18188 | 21303 |
| 18189 @item @@refill | 21304 @item @@refill |
| 21305 @findex refill | |
| 18190 This command used to refill and indent the paragraph after all the | 21306 This command used to refill and indent the paragraph after all the |
| 18191 other processing has been done. It is no longer needed, since all | 21307 other processing has been done. It is no longer needed, since all |
| 18192 formatters now automatically refill as needed, but you may still see | 21308 formatters now automatically refill as needed, but you may still see |
| 18193 it in the source to some manuals, as it does no harm. | 21309 it in the source to some manuals, as it does no harm. |
| 18194 | 21310 |
| 18195 @item @@registeredsymbol@{@} | 21311 @item @@registeredsymbol@{@} |
| 18196 Generate the legal symbol @registeredsymbol{}. @xref{registered | 21312 Generate the legal symbol @registeredsymbol{}. |
| 18197 symbol,, @code{@@registeredsymbol@{@}}}. | 21313 @xref{@t{@@registeredsymbol}}. |
| 18198 | 21314 |
| 18199 @item @@result@{@} | 21315 @item @@result@{@} |
| 18200 Indicate the result of an expression to the reader with a special | 21316 Indicate the result of an expression to the reader with a special |
| 18201 glyph: @samp{@result{}}. @xref{result, , @code{@@result}}.@refill | 21317 glyph: @samp{@result{}}. @xref{@t{@@result}}. |
| 18202 | 21318 |
| 18203 @item @@ringaccent@{@var{c}@} | 21319 @item @@ringaccent@{@var{c}@} |
| 18204 Generate a ring accent over the next character, as in @ringaccent{o}. | 21320 Generate a ring accent over the next character, as in @ringaccent{o}. |
| 18205 @xref{Inserting Accents}. | 21321 @xref{Inserting Accents}. |
| 18206 | 21322 |
| 18207 @item @@samp@{@var{text}@} | 21323 @item @@samp@{@var{text}@} |
| 18208 Indicate a literal example of a sequence of characters, in general. | 21324 Indicate a literal example of a sequence of characters, in general. |
| 18209 Quoted in Info output. @xref{samp, , @code{@@samp}}. | 21325 Quoted in Info output. @xref{@t{@@samp}}. |
| 18210 | 21326 |
| 18211 @item @@sansserif@{@var{text}@} | 21327 @item @@sansserif@{@var{text}@} |
| 18212 Set @var{text} in a @sansserif{sans serif} font if possible. No | 21328 Set @var{text} in a @sansserif{sans serif} font if possible. No |
| 18213 effect in Info. @xref{Fonts}. | 21329 effect in Info. @xref{Fonts}. |
| 18214 | 21330 |
| 18219 @item @@section @var{title} | 21335 @item @@section @var{title} |
| 18220 Begin a section within a chapter. The section title appears in the | 21336 Begin a section within a chapter. The section title appears in the |
| 18221 table of contents. In Info, the title is underlined with equal signs. | 21337 table of contents. In Info, the title is underlined with equal signs. |
| 18222 Within @code{@@chapter} and @code{@@appendix}, the section title is | 21338 Within @code{@@chapter} and @code{@@appendix}, the section title is |
| 18223 numbered; within @code{@@unnumbered}, the section is unnumbered. | 21339 numbered; within @code{@@unnumbered}, the section is unnumbered. |
| 18224 @xref{section, , @code{@@section}}. | 21340 @xref{@t{@@section}}. |
| 18225 | 21341 |
| 18226 @item @@set @var{txivar} [@var{string}] | 21342 @item @@set @var{txivar} [@var{string}] |
| 18227 Define the Texinfo variable @var{txivar}, optionally to the value | 21343 Define the Texinfo variable @var{txivar}, optionally to the value |
| 18228 @var{string}. @xref{set clear value, , @code{@@set} @code{@@clear} | 21344 @var{string}. @xref{@t{@@set @@clear @@value}}. |
| 18229 @code{@@value}}. | |
| 18230 | 21345 |
| 18231 @item @@setchapternewpage @var{on-off-odd} | 21346 @item @@setchapternewpage @var{on-off-odd} |
| 18232 Specify whether chapters start on new pages, and if so, whether on | 21347 Specify whether chapters start on new pages, and if so, whether on |
| 18233 odd-numbered (right-hand) new pages. @xref{setchapternewpage, , | 21348 odd-numbered (right-hand) new pages. @xref{@t{@@setchapternewpage}}. |
| 18234 @code{@@setchapternewpage}}. | |
| 18235 | 21349 |
| 18236 @item @@setcontentsaftertitlepage | 21350 @item @@setcontentsaftertitlepage |
| 18237 Put the table of contents after the @samp{@@end titlepage} even if the | 21351 Put the table of contents after the @samp{@@end titlepage} even if the |
| 18238 @code{@@contents} command is at the end. @xref{Contents}. | 21352 @code{@@contents} command is at the end. @xref{Contents}. |
| 18239 | 21353 |
| 18240 @item @@setfilename @var{info-file-name} | 21354 @item @@setfilename @var{info-file-name} |
| 18241 Provide a name to be used for the output files. This command is essential | 21355 Provide a name to be used for the output files. This command is essential |
| 18242 for @TeX{} formatting as well, even though it produces no output of | 21356 for @TeX{} formatting as well, even though it produces no output of |
| 18243 its own. @xref{setfilename, , @code{@@setfilename}}. | 21357 its own. @xref{@t{@@setfilename}}. |
| 18244 | 21358 |
| 18245 @item @@setshortcontentsaftertitlepage | 21359 @item @@setshortcontentsaftertitlepage |
| 18246 Place the short table of contents after the @samp{@@end titlepage} | 21360 Place the short table of contents after the @samp{@@end titlepage} |
| 18247 command even if the @code{@@shortcontents} command is at the end. | 21361 command even if the @code{@@shortcontents} command is at the end. |
| 18248 @xref{Contents}. | 21362 @xref{Contents}. |
| 18249 | 21363 |
| 18250 @item @@settitle @var{title} | 21364 @item @@settitle @var{title} |
| 18251 Specify the title for page headers in a printed manual, and the | 21365 Specify the title for page headers in a printed manual, and the |
| 18252 default document description for HTML @samp{<head>}. @xref{settitle,, | 21366 default document title for HTML @samp{<head>}. |
| 18253 @code{@@settitle}}. | 21367 @xref{@t{@@settitle}}. |
| 18254 | 21368 |
| 18255 @item @@shortcaption | 21369 @item @@shortcaption |
| 18256 Define the short caption for a @code{@@float}. @xref{caption shortcaption}. | 21370 Define the short caption for an @code{@@float}. @xref{@t{@@caption |
| 21371 @@shortcaption}}. | |
| 18257 | 21372 |
| 18258 @item @@shortcontents | 21373 @item @@shortcontents |
| 18259 Print a short table of contents, with chapter-level entries only. Not | 21374 Print a short table of contents, with chapter-level entries only. Not |
| 18260 relevant to Info, which uses menus rather than tables of contents. | 21375 relevant to Info, which uses menus rather than tables of contents. |
| 18261 @xref{Contents, , Generating a Table of Contents}. | 21376 @xref{Contents, , Generating a Table of Contents}. |
| 18262 | 21377 |
| 18263 @item @@shorttitlepage @var{title} | 21378 @item @@shorttitlepage @var{title} |
| 18264 Generate a minimal title page. @xref{titlepage,,@code{@@titlepage}}. | 21379 Generate a minimal title page. @xref{@t{@@titlepage}}. |
| 18265 | 21380 |
| 18266 @item @@slanted@{@var{text}@} | 21381 @item @@slanted@{@var{text}@} |
| 18267 Set @var{text} in a @slanted{slanted} font if possible. No effect | 21382 Set @var{text} in a @slanted{slanted} font if possible. No effect |
| 18268 in Info. @xref{Fonts}. | 21383 in Info. @xref{Fonts}. |
| 18269 | 21384 |
| 18270 @item @@smallbook | 21385 @item @@smallbook |
| 18271 Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format | 21386 Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format |
| 18272 rather than the regular 8.5 by 11 inch format. @xref{smallbook, , | 21387 rather than the regular 8.5 by 11 inch format. |
| 18273 Printing Small Books}. Also, see @ref{small}. | 21388 @xref{@t{@@smallbook}}. Also, see @ref{@t{@@small@dots{}}}. |
| 18274 | 21389 |
| 18275 @item @@smalldisplay | 21390 @item @@smalldisplay |
| 18276 Begin a kind of example. Like @code{@@smallexample} (narrow margins, no | 21391 Begin a kind of example. Like @code{@@display}, but use a smaller |
| 18277 filling), but do not select the fixed-width font. Pair with @code{@@end | 21392 font size where possible. Pair with @code{@@end smalldisplay}. |
| 18278 smalldisplay}. @xref{small}. | 21393 @xref{@t{@@small@dots{}}}. |
| 18279 | 21394 |
| 18280 @item @@smallexample | 21395 @item @@smallexample |
| 18281 Begin an example. Do not fill, select fixed-width font, narrow the | 21396 Begin an example. Like @code{@@example}, but use a smaller font size |
| 18282 margins. Where possible, print text in a smaller font than with | 21397 where possible. Pair with @code{@@end smallexample}. |
| 18283 @code{@@example}. Pair with @code{@@end smallexample}. @xref{small}. | 21398 @xref{@t{@@small@dots{}}}. |
| 18284 | 21399 |
| 18285 @item @@smallformat | 21400 @item @@smallformat |
| 18286 Begin a kind of example. Like @code{@@smalldisplay}, but do not narrow | 21401 Begin a kind of example. Like @code{@@format}, but use a smaller font |
| 18287 the margins. Pair with @code{@@end smallformat}. @xref{small}. | 21402 size where possible. Pair with @code{@@end smallformat}. |
| 21403 @xref{@t{@@small@dots{}}}. | |
| 21404 | |
| 21405 @item @@smallindentedblock | |
| 21406 Like @code{@@indentedblock}, but use a smaller font size where | |
| 21407 possible. Pair with @code{@@end smallindentedblock}. | |
| 21408 @xref{@t{@@small@dots{}}}. | |
| 18288 | 21409 |
| 18289 @item @@smalllisp | 21410 @item @@smalllisp |
| 18290 Begin an example of Lisp code. Same as @code{@@smallexample}. Pair | 21411 Begin an example of Lisp code. Same as @code{@@smallexample}. Pair |
| 18291 with @code{@@end smalllisp}. @xref{small}. | 21412 with @code{@@end smalllisp}. @xref{@t{@@small@dots{}}}. |
| 21413 | |
| 21414 @item @@smallquotation | |
| 21415 Like @code{@@quotation}, but use a smaller font size where possible. | |
| 21416 Pair with @code{@@end smallquotation}. @xref{@t{@@small@dots{}}}. | |
| 18292 | 21417 |
| 18293 @item @@sp @var{n} | 21418 @item @@sp @var{n} |
| 18294 Skip @var{n} blank lines. @xref{sp, , @code{@@sp}}.@refill | 21419 Skip @var{n} blank lines. @xref{@t{@@sp}}. |
| 18295 | 21420 |
| 18296 @item @@ss@{@} | 21421 @item @@ss@{@} |
| 18297 Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}. | 21422 Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}. |
| 18298 | 21423 |
| 18299 @item @@strong @{@var{text}@} | 21424 @item @@strong @{@var{text}@} |
| 18302 @xref{emph & strong, , Emphasizing Text}. | 21427 @xref{emph & strong, , Emphasizing Text}. |
| 18303 | 21428 |
| 18304 @item @@subheading @var{title} | 21429 @item @@subheading @var{title} |
| 18305 Print an unnumbered subsection-like heading, but omit from the table | 21430 Print an unnumbered subsection-like heading, but omit from the table |
| 18306 of contents of a printed manual. In Info, the title is underlined | 21431 of contents of a printed manual. In Info, the title is underlined |
| 18307 with hyphens. @xref{unnumberedsubsec appendixsubsec subheading, , | 21432 with hyphens. @xref{@t{@@unnumberedsubsec @@appendixsubsec @@subheading}}. |
| 18308 @code{@@unnumberedsubsec} @code{@@appendixsubsec} | |
| 18309 @code{@@subheading}}. | |
| 18310 | 21433 |
| 18311 @item @@subsection @var{title} | 21434 @item @@subsection @var{title} |
| 18312 Begin a subsection within a section. The subsection title appears in | 21435 Begin a subsection within a section. The subsection title appears in |
| 18313 the table of contents. In Info, the title is underlined with hyphens. | 21436 the table of contents. In Info, the title is underlined with hyphens. |
| 18314 Same context-dependent numbering as @code{@@section}. @xref{subsection, , | 21437 Same context-dependent numbering as @code{@@section}. |
| 18315 @code{@@subsection}}. | 21438 @xref{@t{@@subsection}}. |
| 18316 | 21439 |
| 18317 @item @@subsubheading @var{title} | 21440 @item @@subsubheading @var{title} |
| 18318 Print an unnumbered subsubsection-like heading, but omit from the | 21441 Print an unnumbered subsubsection-like heading, but omit from the |
| 18319 table of contents of a printed manual. In Info, the title is | 21442 table of contents of a printed manual. In Info, the title is |
| 18320 underlined with periods. @xref{subsubsection, , The `subsub' | 21443 underlined with periods. @xref{@t{@@subsubsection}}. |
| 18321 Commands}. | |
| 18322 | 21444 |
| 18323 @item @@subsubsection @var{title} | 21445 @item @@subsubsection @var{title} |
| 18324 Begin a subsubsection within a subsection. The subsubsection title | 21446 Begin a subsubsection within a subsection. The subsubsection title |
| 18325 appears in the table of contents. In Info, the title is underlined | 21447 appears in the table of contents. In Info, the title is underlined |
| 18326 with periods. Same context-dependent numbering as @code{@@section}. | 21448 with periods. Same context-dependent numbering as @code{@@section}. |
| 18327 @xref{subsubsection, , The `subsub' Commands}. | 21449 @xref{@t{@@subsubsection}}. |
| 18328 | 21450 |
| 18329 @item @@subtitle @var{title} | 21451 @item @@subtitle @var{title} |
| 18330 In a printed manual, set a subtitle in a normal sized font flush to | 21452 In a printed manual, set a subtitle in a normal sized font flush to |
| 18331 the right-hand side of the page. Not relevant to Info, which does not | 21453 the right-hand side of the page. Not relevant to Info, which does not |
| 18332 have title pages. @xref{title subtitle author, , @code{@@title} | 21454 have title pages. @xref{@t{@@title @@subtitle @@author}}. |
| 18333 @code{@@subtitle} and @code{@@author} Commands}. | |
| 18334 | 21455 |
| 18335 @item @@summarycontents | 21456 @item @@summarycontents |
| 18336 Print a short table of contents. Synonym for @code{@@shortcontents}. | 21457 Print a short table of contents. Synonym for @code{@@shortcontents}. |
| 18337 @xref{Contents, , Generating a Table of Contents}. | 21458 @xref{Contents, , Generating a Table of Contents}. |
| 18338 | 21459 |
| 18339 @item @@syncodeindex @var{from-index} @var{to-index} | 21460 @item @@syncodeindex @var{from-index} @var{to-index} |
| 18340 Merge the index named in the first argument into the index named in | 21461 Merge the index named in the first argument into the index named in |
| 18341 the second argument, formatting the entries from the first index with | 21462 the second argument, formatting the entries from the first index with |
| 18342 @code{@@code} . @xref{Combining Indices}.@refill | 21463 @code{@@code}. @xref{Combining Indices}. |
| 18343 | 21464 |
| 18344 @item @@synindex @var{from-index} @var{to-index} | 21465 @item @@synindex @var{from-index} @var{to-index} |
| 18345 Merge the index named in the first argument into the index named in | 21466 Merge the index named in the first argument into the index named in |
| 18346 the second argument. Do not change the font of @var{from-index} | 21467 the second argument. Do not change the font of @var{from-index} |
| 18347 entries. @xref{Combining Indices}. | 21468 entries. @xref{Combining Indices}. |
| 18357 Begin a two-column table (description list), using @code{@@item} for | 21478 Begin a two-column table (description list), using @code{@@item} for |
| 18358 each entry. Write each first column entry on the same line as | 21479 each entry. Write each first column entry on the same line as |
| 18359 @code{@@item}. First column entries are printed in the font resulting | 21480 @code{@@item}. First column entries are printed in the font resulting |
| 18360 from @var{formatting-command}. Pair with @code{@@end table}. | 21481 from @var{formatting-command}. Pair with @code{@@end table}. |
| 18361 @xref{Two-column Tables, , Making a Two-column Table}. Also see | 21482 @xref{Two-column Tables, , Making a Two-column Table}. Also see |
| 18362 @ref{ftable vtable, , @code{@@ftable} and @code{@@vtable}}, and | 21483 @ref{@t{@@ftable @@vtable}}, and @ref{@t{@@itemx}}. |
| 18363 @ref{itemx, , @code{@@itemx}}. | |
| 18364 | 21484 |
| 18365 @item @@TeX@{@} | 21485 @item @@TeX@{@} |
| 18366 Generate the @TeX{} logo. @xref{tex, , @TeX{} and @LaTeX{}}. | 21486 Generate the @TeX{} logo. @xref{@t{@@TeX @@LaTeX}}. |
| 18367 | 21487 |
| 18368 @item @@tex | 21488 @item @@tex |
| 18369 Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Raw | 21489 Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Raw |
| 18370 Formatter Commands}. | 21490 Formatter Commands}. |
| 21491 | |
| 21492 @item @@textdegree@{@} | |
| 21493 Generate the degree symbol. @xref{@t{@@textdegree}}. | |
| 18371 | 21494 |
| 18372 @item @@thischapter | 21495 @item @@thischapter |
| 18373 @itemx @@thischaptername | 21496 @itemx @@thischaptername |
| 18374 @itemx @@thischapternum | 21497 @itemx @@thischapternum |
| 18375 @itemx @@thisfile | 21498 @itemx @@thisfile |
| 18380 Title'), the current chapter name only, the current chapter number | 21503 Title'), the current chapter name only, the current chapter number |
| 18381 only, the filename, the current page number, and the title of the | 21504 only, the filename, the current page number, and the title of the |
| 18382 document, respectively. @xref{Custom Headings, , How to Make Your Own | 21505 document, respectively. @xref{Custom Headings, , How to Make Your Own |
| 18383 Headings}. | 21506 Headings}. |
| 18384 | 21507 |
| 21508 @item @@TH@{@} | |
| 21509 @itemx @@th@{@} | |
| 21510 Generate the uppercase and lowercase Icelandic letter thorn, respectively: | |
| 21511 @TH{}, @th{}. @xref{Inserting Accents}. | |
| 21512 | |
| 18385 @item @@tie@{@} | 21513 @item @@tie@{@} |
| 18386 Generate a normal interword space at which a line break is not allowed. | 21514 Generate a normal interword space at which a line break is not |
| 18387 @xref{tie,, @code{@@tie@{@}}}. | 21515 allowed. @xref{@t{@@tie}}. |
| 18388 | 21516 |
| 18389 @item @@tieaccent@{@var{cc}@} | 21517 @item @@tieaccent@{@var{cc}@} |
| 18390 Generate a tie-after accent over the next two characters @var{cc}, as in | 21518 Generate a tie-after accent over the next two characters @var{cc}, as in |
| 18391 `@tieaccent{oo}'. @xref{Inserting Accents}. | 21519 `@tieaccent{oo}'. @xref{Inserting Accents}. |
| 18392 | 21520 |
| 18393 @item @@tindex @var{entry} | 21521 @item @@tindex @var{entry} |
| 18394 Add @var{entry} to the index of data types. @xref{Index Entries, , | 21522 Add @var{entry} to the index of data types. @xref{Index Entries, , |
| 18395 Defining the Entries of an Index}.@refill | 21523 Defining the Entries of an Index}. |
| 18396 | 21524 |
| 18397 @item @@title @var{title} | 21525 @item @@title @var{title} |
| 18398 In a printed manual, set a title flush to the left-hand side of the | 21526 In a printed manual, set a title flush to the left-hand side of the |
| 18399 page in a larger than normal font and underline it with a black rule. | 21527 page in a larger than normal font and underline it with a black rule. |
| 18400 Not relevant to Info, which does not have title pages. @xref{title | 21528 Not relevant to Info, which does not have title pages. |
| 18401 subtitle author, , The @code{@@title} @code{@@subtitle} and | 21529 @xref{@t{@@title @@subtitle @@author}}. |
| 18402 @code{@@author} Commands}.@refill | |
| 18403 | 21530 |
| 18404 @item @@titlefont@{@var{text}@} | 21531 @item @@titlefont@{@var{text}@} |
| 18405 In a printed manual, print @var{text} in a larger than normal font. | 21532 In a printed manual, print @var{text} in a larger than normal font. |
| 18406 @xref{titlefont center sp, , The @code{@@titlefont} @code{@@center} | 21533 @xref{@t{@@titlefont @@center @@sp}}. |
| 18407 and @code{@@sp} Commands}. | |
| 18408 | 21534 |
| 18409 @item @@titlepage | 21535 @item @@titlepage |
| 18410 Begin the title page. Write the command on a line of its own, paired | 21536 Begin the title page. Write the command on a line of its own, paired |
| 18411 with @code{@@end titlepage}. Nothing between @code{@@titlepage} and | 21537 with @code{@@end titlepage}. Nothing between @code{@@titlepage} and |
| 18412 @code{@@end titlepage} appears in Info. @xref{titlepage, , | 21538 @code{@@end titlepage} appears in Info. @xref{@t{@@titlepage}}. |
| 18413 @code{@@titlepage}}.@refill | |
| 18414 | 21539 |
| 18415 @item @@today@{@} | 21540 @item @@today@{@} |
| 18416 Insert the current date, in `1 Jan 1900' style. @xref{Custom | 21541 Insert the current date, in `1 Jan 1900' style. @xref{Custom |
| 18417 Headings, , How to Make Your Own Headings}.@refill | 21542 Headings, , How to Make Your Own Headings}. |
| 18418 | 21543 |
| 18419 @item @@top @var{title} | 21544 @item @@top @var{title} |
| 18420 Mark the topmost @code{@@node} in the file, which must be defined on | 21545 Mark the topmost @code{@@node} in the file, which must be defined on |
| 18421 the line immediately preceding the @code{@@top} command. The title is | 21546 the line immediately preceding the @code{@@top} command. The title is |
| 18422 formatted as a chapter-level heading. The entire top node, including | 21547 formatted as a chapter-level heading. The entire top node, including |
| 18423 the @code{@@node} and @code{@@top} lines, are normally enclosed with | 21548 the @code{@@node} and @code{@@top} lines, are normally enclosed with |
| 18424 @code{@@ifnottex ... @@end ifnottex}. In @TeX{} and | 21549 @code{@@ifnottex ... @@end ifnottex}. In @TeX{} and |
| 18425 @code{texinfo-format-buffer}, the @code{@@top} command is merely a | 21550 @code{texinfo-format-buffer}, the @code{@@top} command is merely a |
| 18426 synonym for @code{@@unnumbered}. @xref{makeinfo Pointer Creation, , | 21551 synonym for @code{@@unnumbered}. @xref{@t{makeinfo} Pointer |
| 18427 Creating Pointers with @code{makeinfo}}. | 21552 Creation}. |
| 18428 | 21553 |
| 18429 @item @@u@{@var{c}@} | 21554 @item @@u@{@var{c}@} |
| 18430 @itemx @@ubaraccent@{@var{c}@} | 21555 @itemx @@ubaraccent@{@var{c}@} |
| 18431 @itemx @@udotaccent@{@var{c}@} | 21556 @itemx @@udotaccent@{@var{c}@} |
| 18432 Generate a breve, underbar, or underdot accent, respectively, over or | 21557 Generate a breve, underbar, or underdot accent, respectively, over or |
| 18433 under the character @var{c}, as in @u{o}, @ubaraccent{o}, | 21558 under the character @var{c}, as in @u{o}, @ubaraccent{o}, |
| 18434 @udotaccent{o}. @xref{Inserting Accents}. | 21559 @udotaccent{o}. @xref{Inserting Accents}. |
| 18435 | 21560 |
| 21561 @item @@unmacro @var{macroname} | |
| 21562 Undefine the macro @code{@@@var{macroname}} if it has been defined. | |
| 21563 @xref{Defining Macros}. | |
| 21564 | |
| 18436 @item @@unnumbered @var{title} | 21565 @item @@unnumbered @var{title} |
| 18437 Begin a chapter that appears without chapter numbers of any kind. The | 21566 Begin a chapter that appears without chapter numbers of any kind. The |
| 18438 title appears in the table of contents. In Info, the title is | 21567 title appears in the table of contents. In Info, the title is |
| 18439 underlined with asterisks. @xref{unnumbered & appendix, , | 21568 underlined with asterisks. @xref{@t{@@unnumbered @@appendix}}. |
| 18440 @code{@@unnumbered} and @code{@@appendix}}. | |
| 18441 | 21569 |
| 18442 @item @@unnumberedsec @var{title} | 21570 @item @@unnumberedsec @var{title} |
| 18443 Begin a section that appears without section numbers of any kind. The | 21571 Begin a section that appears without section numbers of any kind. The |
| 18444 title appears in the table of contents of a printed manual. In Info, | 21572 title appears in the table of contents of a printed manual. In Info, |
| 18445 the title is underlined with equal signs. @xref{unnumberedsec | 21573 the title is underlined with equal signs. @xref{@t{@@unnumberedsec |
| 18446 appendixsec heading, , Section Commands}. | 21574 @@appendixsec @@heading}}. |
| 18447 | 21575 |
| 18448 @item @@unnumberedsubsec @var{title} | 21576 @item @@unnumberedsubsec @var{title} |
| 18449 Begin an unnumbered subsection. The title appears in the table of | 21577 Begin an unnumbered subsection. The title appears in the table of |
| 18450 contents. In Info, the title is underlined with hyphens. | 21578 contents. In Info, the title is underlined with hyphens. |
| 18451 @xref{unnumberedsubsec appendixsubsec subheading, , | 21579 @xref{@t{@@unnumberedsubsec @@appendixsubsec @@subheading}}. |
| 18452 @code{@@unnumberedsubsec} @code{@@appendixsubsec} | |
| 18453 @code{@@subheading}}. | |
| 18454 | 21580 |
| 18455 @item @@unnumberedsubsubsec @var{title} | 21581 @item @@unnumberedsubsubsec @var{title} |
| 18456 Begin an unnumbered subsubsection. The title appears in the table of | 21582 Begin an unnumbered subsubsection. The title appears in the table of |
| 18457 contents. In Info, the title is underlined with periods. | 21583 contents. In Info, the title is underlined with periods. |
| 18458 @xref{subsubsection, , The `subsub' Commands}. | 21584 @xref{@t{@@subsubsection}}. |
| 18459 | 21585 |
| 18460 @item @@uref@{@var{url}[, @var{displayed-text}][, @var{replacement}@} | 21586 @item @@uref@{@var{url}[, @var{displayed-text}][, @var{replacement}@} |
| 18461 @itemx @@url@{@var{url}[, @var{displayed-text}][, @var{replacement}@} | 21587 @itemx @@url@{@var{url}[, @var{displayed-text}][, @var{replacement}@} |
| 18462 Define a cross reference to an external uniform resource locator, | 21588 Define a cross reference to an external uniform resource locator, |
| 18463 e.g., for the World Wide Web. @xref{uref, , @code{@@uref}}. | 21589 e.g., for the World Wide Web. @xref{@t{@@url}}. |
| 21590 | |
| 21591 @item @@urefbreakstyle @var{style} | |
| 21592 Specify how @code{@@uref}/@code{@@url} should break at special | |
| 21593 characters: @code{after}, @code{before}, @code{none}. | |
| 21594 @xref{@t{@@url}}. | |
| 18464 | 21595 |
| 18465 @item @@v@{@var{c}@} | 21596 @item @@v@{@var{c}@} |
| 18466 Generate check accent over the character @var{c}, as in @v{o}. | 21597 Generate check accent over the character @var{c}, as in @v{o}. |
| 18467 @xref{Inserting Accents}. | 21598 @xref{Inserting Accents}. |
| 18468 | 21599 |
| 18469 @item @@value@{@var{txivar}@} | 21600 @item @@value@{@var{txivar}@} |
| 18470 Insert the value, if any, of the Texinfo variable @var{txivar}, | 21601 Insert the value, if any, of the Texinfo variable @var{txivar}, |
| 18471 previously defined by @code{@@set}. @xref{set clear value, , | 21602 previously defined by @code{@@set}. @xref{@t{@@set @@clear |
| 18472 @code{@@set} @code{@@clear} @code{@@value}}. | 21603 @@value}}. |
| 18473 | 21604 |
| 18474 @item @@var@{@var{metasyntactic-variable}@} | 21605 @item @@var@{@var{metasyntactic-variable}@} |
| 18475 Highlight a metasyntactic variable, which is something that stands for | 21606 Highlight a metasyntactic variable, which is something that stands for |
| 18476 another piece of text. @xref{var, , Indicating Metasyntactic | 21607 another piece of text. @xref{@t{@@var}}. |
| 18477 Variables}. | |
| 18478 | 21608 |
| 18479 @item @@verb@{@var{delim} @var{literal} @var{delim}@} | 21609 @item @@verb@{@var{delim} @var{literal} @var{delim}@} |
| 18480 Output @var{literal}, delimited by the single character @var{delim}, | 21610 Output @var{literal}, delimited by the single character @var{delim}, |
| 18481 exactly as is (in the fixed-width font), including any whitespace or | 21611 exactly as is (in the fixed-width font), including any whitespace or |
| 18482 Texinfo special characters. @xref{verb,,@code{verb}}. | 21612 Texinfo special characters. @xref{@t{@@verb}}. |
| 18483 | 21613 |
| 18484 @item @@verbatim | 21614 @item @@verbatim |
| 18485 Output the text of the environment exactly as is (in the fixed-width | 21615 Output the text of the environment exactly as is (in the fixed-width |
| 18486 font). Pair with @code{@@end verbatim}. @xref{verbatim,,@code{verbatim}}. | 21616 font). Pair with @code{@@end verbatim}. @xref{@t{@@verbatim}}. |
| 18487 | 21617 |
| 18488 @item @@verbatiminclude @var{filename} | 21618 @item @@verbatiminclude @var{filename} |
| 18489 Output the contents of @var{filename} exactly as is (in the fixed-width font). | 21619 Output the contents of @var{filename} exactly as is (in the |
| 18490 @xref{verbatiminclude,,@code{verbatiminclude}}. | 21620 fixed-width font). @xref{@t{@@verbatiminclude}}. |
| 18491 | 21621 |
| 18492 @item @@vindex @var{entry} | 21622 @item @@vindex @var{entry} |
| 18493 Add @var{entry} to the index of variables. @xref{Index Entries, , | 21623 Add @var{entry} to the index of variables. @xref{Index Entries, , |
| 18494 Defining the Entries of an Index}.@refill | 21624 Defining the Entries of an Index}. |
| 18495 | 21625 |
| 18496 @item @@vskip @var{amount} | 21626 @item @@vskip @var{amount} |
| 18497 In a printed manual, insert whitespace so as to push text on the | 21627 In a printed manual, insert whitespace so as to push text on the |
| 18498 remainder of the page towards the bottom of the page. Used in | 21628 remainder of the page towards the bottom of the page. Used in |
| 18499 formatting the copyright page with the argument @samp{0pt plus | 21629 formatting the copyright page with the argument @samp{0pt plus |
| 18502 | 21632 |
| 18503 @item @@vtable @var{formatting-command} | 21633 @item @@vtable @var{formatting-command} |
| 18504 Begin a two-column table, using @code{@@item} for each entry. | 21634 Begin a two-column table, using @code{@@item} for each entry. |
| 18505 Automatically enter each of the items in the first column into the | 21635 Automatically enter each of the items in the first column into the |
| 18506 index of variables. Pair with @code{@@end vtable}. The same as | 21636 index of variables. Pair with @code{@@end vtable}. The same as |
| 18507 @code{@@table}, except for indexing. @xref{ftable vtable, , | 21637 @code{@@table}, except for indexing. @xref{@t{@@ftable @@vtable}}. |
| 18508 @code{@@ftable} and @code{@@vtable}}.@refill | |
| 18509 | 21638 |
| 18510 @item @@w@{@var{text}@} | 21639 @item @@w@{@var{text}@} |
| 18511 Disallow line breaks within @var{text}. @xref{w, , @code{@@w}}. | 21640 Disallow line breaks within @var{text}. @xref{@t{@@w}}. |
| 18512 | 21641 |
| 18513 @item @@xml | 21642 @item @@xml |
| 18514 Enter XML completely. Pair with @code{@@end xml}. @xref{Raw | 21643 Enter XML completely. Pair with @code{@@end xml}. @xref{Raw |
| 18515 Formatter Commands}. | 21644 Formatter Commands}. |
| 18516 | 21645 |
| 18517 @item @@xref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@} | 21646 @item @@xref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@} |
| 18518 Make a reference that starts with `See' in a printed manual. Follow | 21647 Make a reference that starts with `See' in a printed manual. Follow |
| 18519 command with a punctuation mark. Only the first argument is | 21648 command with a punctuation mark. Only the first argument is |
| 18520 mandatory. @xref{xref, , @code{@@xref}}. | 21649 mandatory. @xref{@t{@@xref}}. |
| 21650 | |
| 21651 @item @@xrefautomaticsectiontitle @var{on-off} | |
| 21652 By default, use the section title instead of the node name in cross | |
| 21653 references. @xref{Three Arguments}. | |
| 18521 | 21654 |
| 18522 @end table | 21655 @end table |
| 18523 | 21656 |
| 18524 | 21657 |
| 18525 @node Command Syntax | 21658 @node Command Syntax |
| 18526 @section @@-Command Syntax | 21659 @section @@-Command Syntax |
| 18527 @cindex @@-command syntax | 21660 @cindex @@-command syntax |
| 18528 @cindex Syntax, of @@-commands | 21661 @cindex Syntax, of @@-commands |
| 18529 @cindex Command syntax | 21662 @cindex Command syntax |
| 18530 | 21663 |
| 18531 The character @samp{@@} is used to start special Texinfo commands. | 21664 The character @samp{@@} is used to start all Texinfo commands. (It |
| 18532 (It has the same meaning that @samp{\} has in plain @TeX{}.) Texinfo | 21665 has the same meaning that @samp{\} has in plain @TeX{}.) Texinfo has |
| 18533 has four types of @@-command:@refill | 21666 four types of @@-command: |
| 18534 | 21667 |
| 18535 @table @asis | 21668 @table @asis |
| 18536 @item 1. Non-alphabetic commands. | 21669 @item 1. Non-alphabetic commands. |
| 18537 These commands consist of an @@ followed by a punctuation mark or | 21670 These commands consist of an @@ followed by a punctuation mark or |
| 18538 other character that is not part of the alphabet. Non-alphabetic | 21671 other character that is not part of the Latin alphabet. Non-alphabetic |
| 18539 commands are almost always part of the text within a paragraph. The | 21672 commands are almost always part of the text within a paragraph. The |
| 18540 non-alphabetic commands include @code{@@@@}, @code{@@@{}, @code{@@@}}, | 21673 non-alphabetic commands include @code{@@@@}, @code{@@@{}, @code{@@@}}, |
| 18541 @code{@@.}, @code{@@@kbd{SPACE}}, most of the accent commands, and | 21674 @code{@@.}, @code{@@@kbd{SPACE}}, most of the accent commands, and |
| 18542 many more. | 21675 many more. |
| 18543 | 21676 |
| 18544 @item 2. Alphabetic commands that do not require arguments. | 21677 @item 2. Alphabetic commands that do not require arguments. |
| 18545 These commands start with @@ followed by a word followed by left- and | 21678 These commands start with @@ followed by a word followed by a |
| 18546 right-hand braces. These commands insert special symbols in the | 21679 left and right- brace. These commands insert special symbols in |
| 18547 document; they do not require arguments. For example, | 21680 the document; they do not take arguments. Some examples: |
| 18548 @code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}} | 21681 @code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}} |
| 18549 @result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}', | 21682 @result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}', and |
| 18550 and @code{@@bullet@{@}} @result{} @samp{@bullet{}}.@refill | 21683 @code{@@bullet@{@}} @result{} @samp{@bullet{}}. |
| 18551 | 21684 |
| 18552 @item 3. Alphabetic commands that require arguments within braces. | 21685 @item 3. Alphabetic commands that require arguments within braces. |
| 18553 These commands start with @@ followed by a letter or a word, followed by an | 21686 These commands start with @@ followed by a letter or a word, followed by an |
| 18554 argument within braces. For example, the command @code{@@dfn} indicates | 21687 argument within braces. For example, the command @code{@@dfn} indicates |
| 18555 the introductory or defining use of a term; it is used as follows: @samp{In | 21688 the introductory or defining use of a term; it is used as follows: @samp{In |
| 18556 Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.}@refill | 21689 Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.} |
| 18557 | 21690 |
| 18558 @item 4. Alphabetic commands that occupy an entire line. | 21691 @item 4. Alphabetic commands that occupy an entire line. |
| 18559 These commands occupy an entire line. The line starts with @@, | 21692 These commands occupy an entire line. The line starts with @@, |
| 18560 followed by the name of the command (a word); for example, @code{@@center} | 21693 followed by the name of the command (a word); for example, @code{@@center} |
| 18561 or @code{@@cindex}. If no argument is needed, the word is followed by | 21694 or @code{@@cindex}. If no argument is needed, the word is followed by |
| 18562 the end of the line. If there is an argument, it is separated from | 21695 the end of the line. If there is an argument, it is separated from |
| 18563 the command name by a space. Braces are not used.@refill | 21696 the command name by a space. Braces are not used. |
| 18564 @end table | 21697 @end table |
| 21698 | |
| 21699 Whitespace following an @@-command name are optional and (usually) | |
| 21700 ignored if present. The exceptions are contexts whee whitespace is | |
| 21701 significant, e.g., an @code{@@example} environment. | |
| 18565 | 21702 |
| 18566 @cindex Braces and argument syntax | 21703 @cindex Braces and argument syntax |
| 18567 Thus, the alphabetic commands fall into classes that have | 21704 Thus, the alphabetic commands fall into classes that have |
| 18568 different argument syntaxes. You cannot tell to which class a command | 21705 different argument syntaxes. You cannot tell to which class a command |
| 18569 belongs by the appearance of its name, but you can tell by the | 21706 belongs by the appearance of its name, but you can tell by the |
| 18570 command's meaning: if the command stands for a glyph, it is in | 21707 command's meaning: if the command stands for a glyph, it is in |
| 18571 class 2 and does not require an argument; if it makes sense to use the | 21708 class 2 and does not require an argument; if it makes sense to use the |
| 18572 command together with other text as part of a paragraph, the command | 21709 command among other text as part of a paragraph, the command |
| 18573 is in class 3 and must be followed by an argument in braces; | 21710 is in class 3 and must be followed by an argument in braces; |
| 18574 otherwise, it is in class 4 and uses the rest of the line as its | 21711 otherwise, it is in class 4 and uses the rest of the line as its |
| 18575 argument.@refill | 21712 argument. |
| 18576 | 21713 |
| 18577 The purpose of having a different syntax for commands of classes 3 and | 21714 The purpose of having a different syntax for commands of classes 3 |
| 18578 4 is to make Texinfo files easier to read, and also to help the GNU | 21715 and@tie{}4 is to make Texinfo files easier to read, and also to help |
| 18579 XEmacs paragraph and filling commands work properly. There is only one | 21716 the XEmacs paragraph and filling commands work properly. There is |
| 18580 exception to this rule: the command @code{@@refill}, which is always | 21717 only one exception to this rule: the command @code{@@refill}, which is |
| 18581 used at the end of a paragraph immediately following the final period | 21718 always used at the end of a paragraph immediately following the final |
| 18582 or other punctuation character. @code{@@refill} takes no argument and | 21719 period or other punctuation character. @code{@@refill} takes no |
| 18583 does @emph{not} require braces. @code{@@refill} never confuses the | 21720 argument and does @emph{not} require braces. @code{@@refill} never |
| 18584 XEmacs paragraph commands because it cannot appear at the beginning of | 21721 confuses the XEmacs paragraph commands because it cannot appear at the |
| 18585 a line. It is also no longer needed, since all formatters now refill | 21722 beginning of a line. It is also no longer needed, since all |
| 18586 paragraphs automatically. | 21723 formatters now refill paragraphs automatically. |
| 21724 | |
| 21725 | |
| 21726 @node Command Contexts | |
| 21727 @section @@-Command Contexts | |
| 21728 | |
| 21729 @cindex Contexts, of @@-commands | |
| 21730 | |
| 21731 Here we describe approximately which @@-commands can be used in which | |
| 21732 contexts. It merely gives the general idea and is not exhaustive or | |
| 21733 meant to be a complete reference. Discrepancies between the | |
| 21734 information here and the @code{makeinfo} or @TeX{} implementations | |
| 21735 are most likely to be resolved in favor of the implementation. | |
| 21736 | |
| 21737 By @dfn{general text} below, we mean anything except sectioning and | |
| 21738 other such outer-level document commands, such as @code{@@section}, | |
| 21739 @code{@@node}, and @code{@@setfilename}. | |
| 21740 | |
| 21741 @code{@@c}, @code{@@comment} and @code{@@if ... @@end if} conditional | |
| 21742 commands may appear anywhere (except the conditionals must still be on | |
| 21743 lines by themselves). @code{@@caption} may only appear in | |
| 21744 @code{@@float} but may contain general text. @code{@@footnote} | |
| 21745 content likewise. | |
| 21746 | |
| 21747 @@-commands with braces marking text (such as @code{@@strong}, | |
| 21748 @code{@@sc}, @code{@@asis}) may contain raw formatter commands such as | |
| 21749 @code{@@html} but no other block commands (other commands terminated | |
| 21750 by @code{@@end}) and may not be split across paragraphs, but may | |
| 21751 otherwise contain general text. | |
| 21752 | |
| 21753 In addition to the block command restriction, on @code{@@center}, | |
| 21754 @code{@@exdent} and @code{@@item} in @code{@@table} lines, @@-commands | |
| 21755 that makes only sense in a paragraph are not accepted, such as | |
| 21756 @code{@@indent}. | |
| 21757 | |
| 21758 In addition to the above, sectioning commands cannot contain | |
| 21759 @code{@@anchor}, @code{@@footnote} or @code{@@verb}. | |
| 21760 | |
| 21761 In addition to the above, remaining commands (@code{@@node}, | |
| 21762 @code{@@anchor}, @code{@@printindex}, @code{@@ref}, @code{@@math}, | |
| 21763 @code{@@cindex}, @code{@@url}, @code{@@image}, and so on) cannot | |
| 21764 contain cross reference commands (@code{@@ref}, @code{@@xref}, | |
| 21765 @code{@@pxref} and @code{@@inforef}). In one last addition, | |
| 21766 @code{@@shortcaption} may only appear inside @code{@@float}. | |
| 21767 | |
| 21768 For precise and complete information, we suggest looking into the | |
| 21769 extensive test suite in the sources, which exhaustively try | |
| 21770 combinations. | |
| 18587 | 21771 |
| 18588 | 21772 |
| 18589 @node Tips | 21773 @node Tips |
| 18590 @appendix Tips and Hints | 21774 @appendix Tips and Hints |
| 18591 | 21775 |
| 18592 Here are some tips for writing Texinfo documentation:@refill | 21776 Here are some tips for writing Texinfo documentation: |
| 18593 | 21777 |
| 18594 @cindex Tips | 21778 @cindex Tips |
| 18595 @cindex Usage tips | 21779 @cindex Usage tips |
| 18596 @cindex Hints | 21780 @cindex Hints |
| 18597 @itemize @bullet | 21781 @itemize @bullet |
| 18607 | 21791 |
| 18608 @item | 21792 @item |
| 18609 Include a copyright notice and copying permissions. | 21793 Include a copyright notice and copying permissions. |
| 18610 @end itemize | 21794 @end itemize |
| 18611 | 21795 |
| 21796 | |
| 18612 @subsubheading Index, Index, Index! | 21797 @subsubheading Index, Index, Index! |
| 18613 | 21798 |
| 18614 Write many index entries, in different ways. | 21799 Write many index entries, in different ways. |
| 18615 Readers like indices; they are helpful and convenient. | 21800 Readers like indices; they are helpful and convenient. |
| 18616 | 21801 |
| 18618 the text, some people prefer to write entries afterwards. In either | 21803 the text, some people prefer to write entries afterwards. In either |
| 18619 case, write an entry before the paragraph to which it applies. This | 21804 case, write an entry before the paragraph to which it applies. This |
| 18620 way, an index entry points to the first page of a paragraph that is | 21805 way, an index entry points to the first page of a paragraph that is |
| 18621 split across pages. | 21806 split across pages. |
| 18622 | 21807 |
| 18623 Here are more hints we have found valuable: | 21808 Here are more index-related hints we have found valuable: |
| 18624 | 21809 |
| 18625 @itemize @bullet | 21810 @itemize @bullet |
| 18626 @item | 21811 @item |
| 18627 Write each index entry differently, so each entry refers to a different | 21812 Write each index entry differently, so each entry refers to a different |
| 18628 place in the document. | 21813 place in the document. |
| 18633 chapter on reporting bugs. Someone who wants to know about debugging | 21818 chapter on reporting bugs. Someone who wants to know about debugging |
| 18634 information will certainly not find it in that chapter. | 21819 information will certainly not find it in that chapter. |
| 18635 | 21820 |
| 18636 @item | 21821 @item |
| 18637 Consistently capitalize the first word of every concept index entry, | 21822 Consistently capitalize the first word of every concept index entry, |
| 18638 or else consistently use lower case. Terse entries often call for | 21823 or else consistently use lowercase. Terse entries often call for |
| 18639 lower case; longer entries for capitalization. Whichever case | 21824 lowercase; longer entries for capitalization. Whichever case |
| 18640 convention you use, please use one or the other consistently! Mixing | 21825 convention you use, please use one or the other consistently! Mixing |
| 18641 the two styles looks bad. | 21826 the two styles looks bad. |
| 18642 | 21827 |
| 18643 @item | 21828 @item |
| 18644 Always capitalize or use upper case for those words in an index for | 21829 Always capitalize or use uppercase for those words in an index for |
| 18645 which this is proper, such as names of countries or acronyms. Always | 21830 which this is proper, such as names of countries or acronyms. Always |
| 18646 use the appropriate case for case-sensitive names, such as those in C or | 21831 use the appropriate case for case-sensitive names, such as those in C or |
| 18647 Lisp. | 21832 Lisp. |
| 18648 | 21833 |
| 18649 @item | 21834 @item |
| 18672 (Note that the example shows entries for the same concept that are | 21857 (Note that the example shows entries for the same concept that are |
| 18673 written in different ways---@samp{Lazy dog}, and @samp{Dog, lazy}---so | 21858 written in different ways---@samp{Lazy dog}, and @samp{Dog, lazy}---so |
| 18674 readers can look up the concept in different ways.) | 21859 readers can look up the concept in different ways.) |
| 18675 @end itemize | 21860 @end itemize |
| 18676 | 21861 |
| 21862 | |
| 18677 @subsubheading Blank Lines | 21863 @subsubheading Blank Lines |
| 18678 | 21864 |
| 18679 @itemize @bullet | 21865 @itemize @bullet |
| 18680 @item | 21866 @item |
| 18681 Insert a blank line between a sectioning command and the first following | 21867 Insert a blank line between a sectioning command and the first following |
| 18682 sentence or paragraph, or between the indexing commands associated with | 21868 sentence or paragraph, or between the indexing commands associated with |
| 18683 the sectioning command and the first following sentence or paragraph, as | 21869 the sectioning command and the first following sentence or paragraph, as |
| 18684 shown in the tip on indexing. Otherwise, a formatter may fold title and | 21870 shown in the tip on indexing. It makes the source easier to read. |
| 18685 paragraph together. | |
| 18686 | 21871 |
| 18687 @item | 21872 @item |
| 18688 Always insert a blank line before an @code{@@table} command and after an | 21873 Always insert a blank line before an @code{@@table} command and after an |
| 18689 @code{@@end table} command; but never insert a blank line after an | 21874 @code{@@end table} command; but never insert a blank line after an |
| 18690 @code{@@table} command or before an @code{@@end table} command. | 21875 @code{@@table} command. |
| 18691 | 21876 |
| 18692 @need 1000 | 21877 @need 1000 |
| 18693 For example, | 21878 For example, |
| 18694 | 21879 |
| 18695 @example | 21880 @example |
| 18716 Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end | 21901 Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end |
| 18717 itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the | 21902 itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the |
| 18718 same way. | 21903 same way. |
| 18719 @end itemize | 21904 @end itemize |
| 18720 | 21905 |
| 21906 | |
| 18721 @subsubheading Complete Phrases | 21907 @subsubheading Complete Phrases |
| 18722 | 21908 |
| 18723 Complete phrases are easier to read than @dots{} | 21909 Complete phrases are easier to read than @dots{} |
| 18724 | 21910 |
| 18725 @itemize @bullet | 21911 @itemize @bullet |
| 18732 Write the prefatory sentence or phrase for a multi-item list or table as | 21918 Write the prefatory sentence or phrase for a multi-item list or table as |
| 18733 a complete expression. Do not write ``You can set:''; instead, write | 21919 a complete expression. Do not write ``You can set:''; instead, write |
| 18734 ``You can set these variables:''. The former expression sounds cut off. | 21920 ``You can set these variables:''. The former expression sounds cut off. |
| 18735 @end itemize | 21921 @end itemize |
| 18736 | 21922 |
| 21923 | |
| 18737 @subsubheading Editions, Dates and Versions | 21924 @subsubheading Editions, Dates and Versions |
| 18738 | 21925 |
| 18739 Include edition numbers, version numbers, and dates in the | 21926 Include edition numbers, version numbers, and dates in the |
| 18740 @code{@@copying} text (for people reading the Texinfo file, and for the | 21927 @code{@@copying} text (for people reading the Texinfo file, and for the |
| 18741 legal copyright in the output files). Then use @code{@@insertcopying} | 21928 legal copyright in the output files). Then use @code{@@insertcopying} |
| 18742 in the @code{@@titlepage} section (for people reading the printed | 21929 in the @code{@@titlepage} section for people reading the printed |
| 18743 output) and the Top node (for people reading the online output). | 21930 output (@pxref{Short Sample}). |
| 18744 | 21931 |
| 18745 It is easiest to do this using @code{@@set} and @code{@@value}. | 21932 It is easiest to handle such version information using @code{@@set} |
| 18746 @xref{value Example, , @code{@@value} Example}, and @ref{GNU Sample Texts}. | 21933 and @code{@@value}. @xref{@t{@@value} Example}, and @ref{GNU |
| 21934 Sample Texts}. | |
| 18747 | 21935 |
| 18748 | 21936 |
| 18749 @subsubheading Definition Commands | 21937 @subsubheading Definition Commands |
| 18750 | 21938 |
| 18751 Definition commands are @code{@@deffn}, @code{@@defun}, | 21939 Definition commands are @code{@@deffn}, @code{@@defun}, |
| 18752 @code{@@defmac}, and the like, and enable you to write descriptions in | 21940 @code{@@defmac}, and the like, and enable you to write descriptions in |
| 18753 a uniform format.@refill | 21941 a uniform format. |
| 18754 | 21942 |
| 18755 @itemize @bullet | 21943 @itemize @bullet |
| 18756 @item | 21944 @item |
| 18757 Write just one definition command for each entity you define with a | 21945 Write just one definition command for each entity you define with a |
| 18758 definition command. The automatic indexing feature creates an index | 21946 definition command. The automatic indexing feature creates an index |
| 18762 Use @code{@@table} @dots{} @code{@@end table} in an appendix that | 21950 Use @code{@@table} @dots{} @code{@@end table} in an appendix that |
| 18763 contains a summary of functions, not @code{@@deffn} or other definition | 21951 contains a summary of functions, not @code{@@deffn} or other definition |
| 18764 commands. | 21952 commands. |
| 18765 @end itemize | 21953 @end itemize |
| 18766 | 21954 |
| 21955 | |
| 18767 @subsubheading Capitalization | 21956 @subsubheading Capitalization |
| 18768 | 21957 |
| 18769 @itemize @bullet | 21958 @itemize @bullet |
| 18770 @item | 21959 @item |
| 18771 Capitalize ``Texinfo''; it is a name. Do not write the @samp{x} or | 21960 Capitalize ``Texinfo''; it is a name. Do not write the @samp{x} or |
| 18772 @samp{i} in upper case. | 21961 @samp{i} in uppercase. |
| 18773 | 21962 |
| 18774 @item | 21963 @item |
| 18775 Capitalize ``Info''; it is a name. | 21964 Capitalize ``Info''; it is a name. |
| 18776 | 21965 |
| 18777 @item | 21966 @item |
| 18778 Write @TeX{} using the @code{@@TeX@{@}} command. Note the uppercase | 21967 Write @TeX{} using the @code{@@TeX@{@}} command. Note the uppercase |
| 18779 @samp{T} and @samp{X}. This command causes the formatters to | 21968 @samp{T} and @samp{X}. This command causes the formatters to |
| 18780 typeset the name according to the wishes of Donald Knuth, who wrote | 21969 typeset the name according to the wishes of Donald Knuth, who wrote |
| 18781 @TeX{}. | 21970 @TeX{}. (Likewise @code{@@LaTeX@{@}} for @LaTeX{}.) |
| 18782 @end itemize | 21971 @end itemize |
| 21972 | |
| 18783 | 21973 |
| 18784 @subsubheading Spaces | 21974 @subsubheading Spaces |
| 18785 | 21975 |
| 18786 Do not use spaces to format a Texinfo file, except inside of | 21976 Do not use spaces to format a Texinfo file, except inside of |
| 18787 @code{@@example} @dots{} @code{@@end example} and other literal | 21977 @code{@@example} @dots{} @code{@@end example} and other literal |
| 18847 Use three hyphens in a row, @samp{---}, to indicate a long dash. @TeX{} | 22037 Use three hyphens in a row, @samp{---}, to indicate a long dash. @TeX{} |
| 18848 typesets these as a long dash and the Info formatters reduce three | 22038 typesets these as a long dash and the Info formatters reduce three |
| 18849 hyphens to two. | 22039 hyphens to two. |
| 18850 @end itemize | 22040 @end itemize |
| 18851 | 22041 |
| 22042 | |
| 18852 @subsubheading Periods Outside of Quotes | 22043 @subsubheading Periods Outside of Quotes |
| 18853 | 22044 |
| 18854 Place periods and other punctuation marks @emph{outside} of quotations, | 22045 Place periods and other punctuation marks @emph{outside} of quotations, |
| 18855 unless the punctuation is part of the quotation. This practice goes | 22046 unless the punctuation is part of the quotation. This practice goes |
| 18856 against publishing conventions in the United States, but enables the | 22047 against some publishing conventions in the United States, but enables the |
| 18857 reader to distinguish between the contents of the quotation and the | 22048 reader to distinguish between the contents of the quotation and the |
| 18858 whole passage. | 22049 whole passage. |
| 18859 | 22050 |
| 18860 For example, you should write the following sentence with the period | 22051 For example, you should write the following sentence with the period |
| 18861 outside the end quotation marks: | 22052 outside the end quotation marks: |
| 18863 @example | 22054 @example |
| 18864 Evidently, @samp{au} is an abbreviation for ``author''. | 22055 Evidently, @samp{au} is an abbreviation for ``author''. |
| 18865 @end example | 22056 @end example |
| 18866 | 22057 |
| 18867 @noindent | 22058 @noindent |
| 18868 since @samp{au} does @emph{not} serve as an abbreviation for | 22059 since @samp{au} does @emph{not} serve as an abbreviation for |
| 18869 @samp{author.} (with a period following the word). | 22060 @samp{author.} (with a period following the word). |
| 22061 | |
| 18870 | 22062 |
| 18871 @subsubheading Introducing New Terms | 22063 @subsubheading Introducing New Terms |
| 18872 | 22064 |
| 18873 @itemize @bullet | 22065 @itemize @bullet |
| 18874 @item | 22066 @item |
| 18889 Use the @code{@@dfn} command around a word being introduced, to indicate | 22081 Use the @code{@@dfn} command around a word being introduced, to indicate |
| 18890 that the reader should not expect to know the meaning already, and | 22082 that the reader should not expect to know the meaning already, and |
| 18891 should expect to learn the meaning from this passage. | 22083 should expect to learn the meaning from this passage. |
| 18892 @end itemize | 22084 @end itemize |
| 18893 | 22085 |
| 18894 @subsubheading @@pxref | 22086 |
| 18895 | 22087 @subsubheading Program Invocation Nodes |
| 18896 @c !!! maybe include this in the tips on pxref | |
| 18897 @ignore | |
| 18898 By the way, it is okay to use pxref with something else in front of | |
| 18899 it within the parens, as long as the pxref is followed by the close | |
| 18900 paren, and the material inside the parens is not part of a larger | |
| 18901 sentence. Also, you can use xref inside parens as part of a complete | |
| 18902 sentence so long as you terminate the cross reference with punctuation. | |
| 18903 @end ignore | |
| 18904 Absolutely never use @code{@@pxref} except in the special context for | |
| 18905 which it is designed: inside parentheses, with the closing parenthesis | |
| 18906 following immediately after the closing brace. One formatter | |
| 18907 automatically inserts closing punctuation and the other does not. This | |
| 18908 means that the output looks right both in printed output and in an Info | |
| 18909 file, but only when the command is used inside parentheses. | |
| 18910 | |
| 18911 @subsubheading Invoking from a Shell | |
| 18912 | 22088 |
| 18913 You can invoke programs such as XEmacs, GCC, and @code{gawk} from a | 22089 You can invoke programs such as XEmacs, GCC, and @code{gawk} from a |
| 18914 shell. The documentation for each program should contain a section that | 22090 shell. The documentation for each program should contain a section that |
| 18915 describes this. Unfortunately, if the node names and titles for these | 22091 describes this. Unfortunately, if the node names and titles for these |
| 18916 sections are all different, they are difficult for users to find. | 22092 sections are all different, they are difficult for users to find. |
| 18921 | 22097 |
| 18922 | 22098 |
| 18923 @subsubheading ANSI C Syntax | 22099 @subsubheading ANSI C Syntax |
| 18924 | 22100 |
| 18925 When you use @code{@@example} to describe a C function's calling | 22101 When you use @code{@@example} to describe a C function's calling |
| 18926 conventions, use the ANSI C syntax, like this:@refill | 22102 conventions, use the ANSI C syntax, like this: |
| 18927 | 22103 |
| 18928 @example | 22104 @example |
| 18929 void dld_init (char *@@var@{path@}); | 22105 void dld_init (char *@@var@{path@}); |
| 18930 @end example | 22106 @end example |
| 18931 | 22107 |
| 18932 @noindent | 22108 @noindent |
| 18933 And in the subsequent discussion, refer to the argument values by | 22109 And in the subsequent discussion, refer to the argument values by |
| 18934 writing the same argument names, again highlighted with | 22110 writing the same argument names, again highlighted with |
| 18935 @code{@@var}.@refill | 22111 @code{@@var}. |
| 18936 | 22112 |
| 18937 @need 800 | 22113 @need 800 |
| 18938 Avoid the obsolete style that looks like this:@refill | 22114 Avoid the obsolete style that looks like this: |
| 18939 | 22115 |
| 18940 @example | 22116 @example |
| 18941 #include <dld.h> | 22117 #include <dld.h> |
| 18942 | 22118 |
| 18943 dld_init (path) | 22119 dld_init (path) |
| 18944 char *path; | 22120 char *path; |
| 18945 @end example | 22121 @end example |
| 18946 | 22122 |
| 18947 Also, it is best to avoid writing @code{#include} above the | 22123 Also, it is best to avoid writing @code{#include} above the |
| 18948 declaration just to indicate that the function is declared in a | 22124 declaration just to indicate that the function is declared in a |
| 18949 header file. The practice may give the misimpression that the | 22125 header file. The practice may give the misimpression that the |
| 18950 @code{#include} belongs near the declaration of the function. Either | 22126 @code{#include} belongs near the declaration of the function. Either |
| 18951 state explicitly which header file holds the declaration or, better | 22127 state explicitly which header file holds the declaration or, better |
| 18952 yet, name the header file used for a group of functions at the | 22128 yet, name the header file used for a group of functions at the |
| 18953 beginning of the section that describes the functions.@refill | 22129 beginning of the section that describes the functions. |
| 22130 | |
| 22131 @anchor{texi-elements-by-size} | |
| 22132 @subsubheading Node Length | |
| 22133 | |
| 22134 Keep nodes (sections) to a reasonable length, whatever reasonable | |
| 22135 might be in the given context. Don't hesitate break up long nodes | |
| 22136 into subnodes and have an extensive tree structure; that's what it's | |
| 22137 there for. Many times, readers will probably try to find a single | |
| 22138 specific point in the manual, using search, indexing, or just plain | |
| 22139 guessing, rather than reading the whole thing from beginning to end. | |
| 22140 | |
| 22141 You can use the @command{texi-elements-by-size} utility to see a list | |
| 22142 of all nodes (or sections) in the document, sorted by size (either | |
| 22143 lines or words), to find candidates for splitting. It's in the | |
| 22144 @file{util/} subdirectory of the Texinfo sources. | |
| 22145 | |
| 18954 | 22146 |
| 18955 @subsubheading Bad Examples | 22147 @subsubheading Bad Examples |
| 18956 | 22148 |
| 18957 Here are several examples of bad writing to avoid: | 22149 Here are several examples of bad writing to avoid: |
| 18958 | 22150 |
| 18977 | 22169 |
| 18978 @quotation | 22170 @quotation |
| 18979 If you are working with other people, it assists in coordinating | 22171 If you are working with other people, it assists in coordinating |
| 18980 everyone's changes so they do not step on each other. | 22172 everyone's changes so they do not step on each other. |
| 18981 @end quotation | 22173 @end quotation |
| 22174 | |
| 18982 | 22175 |
| 18983 @subsubheading And Finally @dots{} | 22176 @subsubheading And Finally @dots{} |
| 18984 | 22177 |
| 18985 @itemize @bullet | 22178 @itemize @bullet |
| 18986 @item | 22179 @item |
| 19034 @@c %**end of header | 22227 @@c %**end of header |
| 19035 | 22228 |
| 19036 @@copying | 22229 @@copying |
| 19037 This is a short example of a complete Texinfo file. | 22230 This is a short example of a complete Texinfo file. |
| 19038 | 22231 |
| 19039 Copyright @copyright{} 2005 Free Software Foundation, Inc. | 22232 Copyright @@copyright@{@} 2013 Free Software Foundation, Inc. |
| 19040 @@end copying | 22233 @@end copying |
| 19041 | 22234 |
| 19042 @@titlepage | 22235 @@titlepage |
| 19043 @@title Sample Title | 22236 @@title Sample Title |
| 19044 @@page | 22237 @@page |
| 19097 @cindex GNU sample texts | 22290 @cindex GNU sample texts |
| 19098 @cindex Sample texts, GNU | 22291 @cindex Sample texts, GNU |
| 19099 @cindex Full texts, GNU | 22292 @cindex Full texts, GNU |
| 19100 | 22293 |
| 19101 Following is a sample Texinfo document with the full texts that should | 22294 Following is a sample Texinfo document with the full texts that should |
| 19102 be used in GNU manuals. | 22295 be used (adapted as necessary) in GNU manuals. |
| 19103 | 22296 |
| 19104 As well as the legal texts, it also serves as a practical example of how | 22297 As well as the legal texts, it also serves as a practical example of how |
| 19105 many elements in a GNU system can affect the manual. If you're not | 22298 many elements in a GNU system can affect the manual. If you're not |
| 19106 familiar with all these different elements, don't worry. They're not | 22299 familiar with all these different elements, don't worry. They're not |
| 19107 required and a perfectly good manual can be written without them. | 22300 required and a perfectly good manual can be written without them. |
| 19119 @cindex $Id | 22312 @cindex $Id |
| 19120 @cindex CVS $Id | 22313 @cindex CVS $Id |
| 19121 @cindex RCS $Id | 22314 @cindex RCS $Id |
| 19122 @cindex Documentation identification | 22315 @cindex Documentation identification |
| 19123 @cindex Identification of documentation | 22316 @cindex Identification of documentation |
| 19124 The @samp{$Id:} comment is for the CVS (@pxref{Top,, Overview, cvs, | 22317 The @samp{$Id:} comment is for the CVS (@pxref{Top,,, cvs, Concurrent |
| 19125 Concurrent Versions System}) or RCS | 22318 Versions System}), RCS (@pxref{Top,,, rcs, Revision Control System}) |
| 19126 (@url{http://www.gnu.org/software/rcs}) version control systems, which | 22319 and other version control systems, which expand it into a string such |
| 19127 expand it into a string such as: | 22320 as: |
| 19128 @example | 22321 |
| 19129 $Id: texinfo.txi,v 1.225 2008/09/07 22:47:46 karl Exp $ | 22322 @example |
| 19130 @end example | 22323 $Id: texinfo.texi 5381 2013-09-26 23:03:58Z karl $ |
| 19131 (This is useful in all sources that use version control, not just manuals.) | 22324 @end example |
| 19132 You may wish to include the @samp{$Id:} comment in the @code{@@copying} | 22325 |
| 19133 text, if you want a completely unambiguous reference to the | 22326 (This is potentially useful in all sources that use version control, |
| 19134 documentation version. | 22327 not just manuals.) You may wish to include the @samp{$Id:} comment in |
| 22328 the @code{@@copying} text, if you want a completely unambiguous | |
| 22329 reference to the documentation source version. | |
| 19135 | 22330 |
| 19136 If you want to literally write @t{@w{$}Id$}, use @code{@@w}: | 22331 If you want to literally write @t{@w{$}Id$}, use @code{@@w}: |
| 19137 @code{@@w@{$@}Id$}. Unfortunately, this technique does not currently | 22332 @code{@@w@{$@}Id$}. Unfortunately, this technique does not work in |
| 19138 work in plain text output, since it's not clear what should be done. | 22333 plain text output, where it's not clear what should be done. |
| 19139 We hope to find a solution in a future release. | |
| 19140 | 22334 |
| 19141 @item | 22335 @item |
| 19142 @pindex automake@r{, and version info} | 22336 @pindex automake@r{, and version info} |
| 19143 @vindex UPDATED @r{Automake variable} | 22337 @vindex UPDATED @r{Automake variable} |
| 19144 @vindex VERSION @r{Automake variable} | 22338 @vindex VERSION @r{Automake variable} |
| 19145 @pindex time-stamp.el | 22339 @pindex time-stamp.el |
| 19146 The @file{version.texi} in the @code{@@include} command is maintained | 22340 The @file{version.texi} in the @code{@@include} command is maintained |
| 19147 automatically by Automake (@pxref{Top,, Introduction, automake, GNU | 22341 automatically by Automake (@pxref{Top,,, automake, GNU Automake}). It |
| 19148 Automake}). It sets the @samp{VERSION} and @samp{UPDATED} values used | 22342 sets the @samp{VERSION} and @samp{UPDATED} values used elsewhere. If |
| 19149 elsewhere. If your distribution doesn't use Automake, but you do use | 22343 your distribution doesn't use Automake, but you do use XEmacs, you may |
| 19150 XEmacs, you may find the time-stamp.el package helpful (@pxref{Time | 22344 find the time-stamp.el package helpful (@pxref{Time Stamps,,, xemacs, |
| 19151 Stamps,,,xemacs,XEmacs User's Manual}). | 22345 XEmacs User's Manual}). |
| 19152 | 22346 |
| 19153 @item | 22347 @item |
| 19154 The @code{@@syncodeindex} command reflects the recommendation to use | 22348 The @code{@@syncodeindex} command reflects the recommendation to use |
| 19155 only one index where possible, to make it easier for readers to look up | 22349 only one index where possible, to make it easier for readers to look up |
| 19156 index entries. | 22350 index entries. |
| 19161 category names. | 22355 category names. |
| 19162 | 22356 |
| 19163 @item | 22357 @item |
| 19164 The `Invoking' node is a GNU standard to help users find the basic | 22358 The `Invoking' node is a GNU standard to help users find the basic |
| 19165 information about command-line usage of a given program. @xref{Manual | 22359 information about command-line usage of a given program. @xref{Manual |
| 19166 Structure Details,,,standards, GNU Coding Standards}. | 22360 Structure Details,,, standards, GNU Coding Standards}. |
| 19167 | 22361 |
| 19168 @item | 22362 @item |
| 19169 @cindex GNU Free Documentation License, including entire | 22363 @cindex GNU Free Documentation License, including entire |
| 19170 @cindex Free Documentation License, including entire | 22364 @cindex Free Documentation License, including entire |
| 19171 It is best to include the entire GNU Free Documentation License in a GNU | 22365 It is best to include the entire GNU Free Documentation License in a GNU |
| 19181 | 22375 |
| 19182 @item | 22376 @item |
| 19183 If the FSF is not the copyright holder, then use the appropriate name. | 22377 If the FSF is not the copyright holder, then use the appropriate name. |
| 19184 | 22378 |
| 19185 @item | 22379 @item |
| 19186 If your manual is not published on paper by the FSF, then omit the | 22380 If your manual is published on paper by the FSF or is longer than 400 |
| 19187 last sentence in the Back-Cover Text that talks about copies from GNU | 22381 pages, you should include the standard FSF cover texts (@pxref{License |
| 19188 Press. | 22382 Notices for Documentation,,, maintain, GNU Maintainer Information}). |
| 19189 | 22383 |
| 19190 @item | 22384 @item |
| 19191 If your manual has Invariant Sections (again, see the license itself | 22385 For documents that express your personal views, feelings or |
| 19192 for details), then change the text here accordingly. | 22386 experiences, it is more appropriate to use a license permitting only |
| 19193 | 22387 verbatim copying, rather than the FDL@. @xref{Verbatim Copying |
| 19194 @item | 22388 License}. |
| 19195 For documents that express your personal views, feelings or experiences, | |
| 19196 it is more appropriate to use a license permitting only verbatim | |
| 19197 copying, rather than the FDL. @xref{Verbatim Copying License}. | |
| 19198 | 22389 |
| 19199 @end itemize | 22390 @end itemize |
| 19200 | 22391 |
| 19201 Here is the sample document: | 22392 Here is the sample document: |
| 19202 | 22393 |
| 19203 @verbatim | 22394 @verbatim |
| 19204 \input texinfo @c -*-texinfo-*- | 22395 \input texinfo @c -*-texinfo-*- |
| 19205 @comment $Id: texinfo.txi,v 1.225 2008/09/07 22:47:46 karl Exp $ | 22396 @comment $Id@w{$} |
| 19206 @comment %**start of header | 22397 @comment %**start of header |
| 19207 @setfilename sample.info | 22398 @setfilename sample.info |
| 19208 @include version.texi | 22399 @include version.texi |
| 19209 @settitle GNU Sample @value{VERSION} | 22400 @settitle GNU Sample @value{VERSION} |
| 19210 @syncodeindex pg cp | 22401 @syncodeindex pg cp |
| 19211 @comment %**end of header | 22402 @comment %**end of header |
| 19212 @copying | 22403 @copying |
| 19213 This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}), | 22404 This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}), |
| 19214 which is an example in the Texinfo documentation. | 22405 which is an example in the Texinfo documentation. |
| 19215 | 22406 |
| 19216 Copyright @copyright{} 2007 Free Software Foundation, Inc. | 22407 Copyright @copyright{} 2013 Free Software Foundation, Inc. |
| 19217 | 22408 |
| 19218 @quotation | 22409 @quotation |
| 19219 Permission is granted to copy, distribute and/or modify this document | 22410 Permission is granted to copy, distribute and/or modify this document |
| 19220 under the terms of the GNU Free Documentation License, Version 1.2 or | 22411 under the terms of the GNU Free Documentation License, Version 1.3 or |
| 19221 any later version published by the Free Software Foundation; with no | 22412 any later version published by the Free Software Foundation; with no |
| 19222 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' | 22413 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover |
| 19223 and with the Back-Cover Texts as in (a) below. A copy of the | 22414 Texts. A copy of the license is included in the section entitled |
| 19224 license is included in the section entitled ``GNU Free Documentation | 22415 ``GNU Free Documentation License''. |
| 19225 License.'' | |
| 19226 | |
| 19227 (a) The FSF's Back-Cover Text is: ``You have the freedom to | |
| 19228 copy and modify this GNU manual. Buying copies from the FSF | |
| 19229 supports it in developing GNU and promoting software freedom.'' | |
| 19230 @end quotation | 22416 @end quotation |
| 19231 @end copying | 22417 @end copying |
| 19232 | 22418 |
| 19233 @dircategory Texinfo documentation system | 22419 @dircategory Texinfo documentation system |
| 19234 @direntry | 22420 @direntry |
| 19236 @end direntry | 22422 @end direntry |
| 19237 | 22423 |
| 19238 @titlepage | 22424 @titlepage |
| 19239 @title GNU Sample | 22425 @title GNU Sample |
| 19240 @subtitle for version @value{VERSION}, @value{UPDATED} | 22426 @subtitle for version @value{VERSION}, @value{UPDATED} |
| 19241 @author A.U. Thor (@email{bug-texinfo@@gnu.org}) | 22427 @author A.U. Thor (@email{bug-sample@@gnu.org}) |
| 19242 @page | 22428 @page |
| 19243 @vskip 0pt plus 1filll | 22429 @vskip 0pt plus 1filll |
| 19244 @insertcopying | 22430 @insertcopying |
| 19245 @end titlepage | 22431 @end titlepage |
| 19246 | 22432 |
| 19253 This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}). | 22439 This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}). |
| 19254 @end ifnottex | 22440 @end ifnottex |
| 19255 | 22441 |
| 19256 @menu | 22442 @menu |
| 19257 * Invoking sample:: | 22443 * Invoking sample:: |
| 19258 * Copying This Manual:: | 22444 * GNU Free Documentation License:: |
| 19259 * Index:: | 22445 * Index:: |
| 19260 @end menu | 22446 @end menu |
| 19261 | 22447 |
| 19262 | 22448 |
| 19263 @node Invoking sample | 22449 @node Invoking sample |
| 19265 | 22451 |
| 19266 @pindex sample | 22452 @pindex sample |
| 19267 @cindex invoking @command{sample} | 22453 @cindex invoking @command{sample} |
| 19268 | 22454 |
| 19269 This is a sample manual. There is no sample program to | 22455 This is a sample manual. There is no sample program to |
| 19270 invoke, but if there was, you could see its basic usage | 22456 invoke, but if there were, you could see its basic usage |
| 19271 and command line options here. | 22457 and command line options here. |
| 19272 | 22458 |
| 19273 | 22459 |
| 19274 @node GNU Free Documentation License | 22460 @node GNU Free Documentation License |
| 19275 @appendix GNU Free Documentation License | 22461 @appendix GNU Free Documentation License |
| 19290 @section Verbatim Copying License | 22476 @section Verbatim Copying License |
| 19291 | 22477 |
| 19292 @cindex Verbatim copying license | 22478 @cindex Verbatim copying license |
| 19293 @cindex License for verbatim copying | 22479 @cindex License for verbatim copying |
| 19294 | 22480 |
| 19295 For software manuals and other documentation, it is important to use a | 22481 For software manuals and other documentation, it is critical to use a |
| 19296 license permitting free redistribution and updating, so that when a free | 22482 license permitting free redistribution and updating, so that when a free |
| 19297 program is changed, the documentation can be updated as well. | 22483 program is changed, the documentation can be updated as well. |
| 19298 | 22484 |
| 19299 On the other hand, for documents that express your personal views, | 22485 On the other hand, for documents that express your personal views, |
| 19300 feelings or experiences, it is more appropriate to use a license | 22486 feelings or experiences, it is more appropriate to use a license |
| 19306 | 22492 |
| 19307 @verbatim | 22493 @verbatim |
| 19308 @copying | 22494 @copying |
| 19309 This document is a sample for allowing verbatim copying only. | 22495 This document is a sample for allowing verbatim copying only. |
| 19310 | 22496 |
| 19311 Copyright @copyright{} 2005 Free Software Foundation, Inc. | 22497 Copyright @copyright{} 2013 Free Software Foundation, Inc. |
| 19312 | 22498 |
| 19313 @quotation | 22499 @quotation |
| 19314 Permission is granted to make and distribute verbatim copies | 22500 Permission is granted to make and distribute verbatim copies |
| 19315 of this entire document without royalty provided the | 22501 of this entire document without royalty provided the |
| 19316 copyright notice and this permission notice are preserved. | 22502 copyright notice and this permission notice are preserved. |
| 19337 Here is sample text for such an all-permissive license. This is just | 22523 Here is sample text for such an all-permissive license. This is just |
| 19338 the license text itself. For a complete sample document, see the | 22524 the license text itself. For a complete sample document, see the |
| 19339 previous sections. | 22525 previous sections. |
| 19340 | 22526 |
| 19341 @example | 22527 @example |
| 19342 Copyright @copyright{} 2005 Free Software Foundation, Inc. | 22528 Copyright @@copyright@{@} 2013 Free Software Foundation, Inc. |
| 19343 | 22529 |
| 19344 Copying and distribution of this file, with or without modification, | 22530 Copying and distribution of this file, with or without modification, |
| 19345 are permitted in any medium without royalty provided the copyright | 22531 are permitted in any medium without royalty provided the copyright |
| 19346 notice and this notice are preserved. | 22532 notice and this notice are preserved. |
| 19347 @end example | 22533 @end example |
| 19348 | |
| 19349 | |
| 19350 @node Include Files | |
| 19351 @appendix Include Files | |
| 19352 @cindex Include files | |
| 19353 | |
| 19354 When @TeX{} or an Info formatting command sees an @code{@@include} | |
| 19355 command in a Texinfo file, it processes the contents of the file named | |
| 19356 by the command and incorporates them into the DVI or Info file being | |
| 19357 created. Index entries from the included file are incorporated into | |
| 19358 the indices of the output file. | |
| 19359 | |
| 19360 Include files let you keep a single large document as a collection of | |
| 19361 conveniently small parts. | |
| 19362 | |
| 19363 @menu | |
| 19364 * Using Include Files:: How to use the @code{@@include} command. | |
| 19365 * texinfo-multiple-files-update:: How to create and update nodes and | |
| 19366 menus when using included files. | |
| 19367 * Include Files Requirements:: @code{texinfo-multiple-files-update} needs. | |
| 19368 * Sample Include File:: A sample outer file with included files | |
| 19369 within it; and a sample included file. | |
| 19370 * Include Files Evolution:: How use of the @code{@@include} command | |
| 19371 has changed over time. | |
| 19372 @end menu | |
| 19373 | |
| 19374 @node Using Include Files | |
| 19375 @section How to Use Include Files | |
| 19376 @findex include | |
| 19377 | |
| 19378 To include another file within a Texinfo file, write the | |
| 19379 @code{@@include} command at the beginning of a line and follow it on | |
| 19380 the same line by the name of a file to be included. For example: | |
| 19381 | |
| 19382 @example | |
| 19383 @@include buffers.texi | |
| 19384 @end example | |
| 19385 | |
| 19386 The name of the file is taken literally, with a single exception: | |
| 19387 @code{@@value@{@var{var}@}} references are expanded. This makes it | |
| 19388 possible to reliably include files in other directories in a | |
| 19389 distribution. @xref{verbatiminclude,,@code{@@verbatiminclude}}, for | |
| 19390 an example. | |
| 19391 | |
| 19392 An included file should simply be a segment of text that you expect to | |
| 19393 be included as is into the overall or @dfn{outer} Texinfo file; it | |
| 19394 should not contain the standard beginning and end parts of a Texinfo | |
| 19395 file. In particular, you should not start an included file with a | |
| 19396 line saying @samp{\input texinfo}; if you do, that phrase is inserted | |
| 19397 into the output file as is. Likewise, you should not end an included | |
| 19398 file with an @code{@@bye} command; nothing after @code{@@bye} is | |
| 19399 formatted. | |
| 19400 | |
| 19401 In the past, you were required to write an @code{@@setfilename} line at the | |
| 19402 beginning of an included file, but no longer. Now, it does not matter | |
| 19403 whether you write such a line. If an @code{@@setfilename} line exists | |
| 19404 in an included file, it is ignored.@refill | |
| 19405 | |
| 19406 Conventionally, an included file begins with an @code{@@node} line that | |
| 19407 is followed by an @code{@@chapter} line. Each included file is one | |
| 19408 chapter. This makes it easy to use the regular node and menu creating | |
| 19409 and updating commands to create the node pointers and menus within the | |
| 19410 included file. However, the simple XEmacs node and menu creating and | |
| 19411 updating commands do not work with multiple Texinfo files. Thus you | |
| 19412 cannot use these commands to fill in the `Next', `Previous', and `Up' | |
| 19413 pointers of the @code{@@node} line that begins the included file. Also, | |
| 19414 you cannot use the regular commands to create a master menu for the | |
| 19415 whole file. Either you must insert the menus and the `Next', | |
| 19416 `Previous', and `Up' pointers by hand, or you must use the XEmacs | |
| 19417 Texinfo mode command, @code{texinfo-multiple-files-update}, that is | |
| 19418 designed for @code{@@include} files.@refill | |
| 19419 | |
| 19420 When an included file does not have any node lines in it, the | |
| 19421 multiple files update command does not try to create a menu entry | |
| 19422 for it. Consequently, you can include any file, such as a | |
| 19423 version or an update file without node lines, not just files that | |
| 19424 are chapters. Small includable files like this are created by | |
| 19425 Automake (@pxref{GNU Sample Texts}). | |
| 19426 | |
| 19427 | |
| 19428 @node texinfo-multiple-files-update | |
| 19429 @section @code{texinfo-multiple-files-update} | |
| 19430 @findex texinfo-multiple-files-update | |
| 19431 | |
| 19432 XEmacs Texinfo mode provides the @code{texinfo-multiple-files-update} | |
| 19433 command. This command creates or updates `Next', `Previous', and `Up' | |
| 19434 pointers of included files as well as those in the outer or overall | |
| 19435 Texinfo file, and it creates or updates a main menu in the outer file. | |
| 19436 Depending whether you call it with optional arguments, the command | |
| 19437 updates only the pointers in the first @code{@@node} line of the | |
| 19438 included files or all of them:@refill | |
| 19439 | |
| 19440 @table @kbd | |
| 19441 @item M-x texinfo-multiple-files-update | |
| 19442 Called without any arguments:@refill | |
| 19443 | |
| 19444 @itemize @minus | |
| 19445 @item | |
| 19446 Create or update the `Next', `Previous', and `Up' pointers of the | |
| 19447 first @code{@@node} line in each file included in an outer or overall | |
| 19448 Texinfo file.@refill | |
| 19449 | |
| 19450 @item | |
| 19451 Create or update the `Top' level node pointers of the outer or | |
| 19452 overall file.@refill | |
| 19453 | |
| 19454 @item | |
| 19455 Create or update a main menu in the outer file.@refill | |
| 19456 @end itemize | |
| 19457 | |
| 19458 @item C-u M-x texinfo-multiple-files-update | |
| 19459 Called with @kbd{C-u} as a prefix argument: | |
| 19460 | |
| 19461 @itemize @minus{} | |
| 19462 @item | |
| 19463 Create or update pointers in the first @code{@@node} line in each | |
| 19464 included file. | |
| 19465 | |
| 19466 @item | |
| 19467 Create or update the `Top' level node pointers of the outer file. | |
| 19468 | |
| 19469 @item | |
| 19470 Create and insert a master menu in the outer file. The master menu | |
| 19471 is made from all the menus in all the included files.@refill | |
| 19472 @end itemize | |
| 19473 | |
| 19474 @item C-u 8 M-x texinfo-multiple-files-update | |
| 19475 Called with a numeric prefix argument, such as @kbd{C-u 8}: | |
| 19476 | |
| 19477 @itemize @minus | |
| 19478 @item | |
| 19479 Create or update @strong{all} the `Next', `Previous', and `Up' pointers | |
| 19480 of all the included files.@refill | |
| 19481 | |
| 19482 @item | |
| 19483 Create or update @strong{all} the menus of all the included | |
| 19484 files.@refill | |
| 19485 | |
| 19486 @item | |
| 19487 Create or update the `Top' level node pointers of the outer or | |
| 19488 overall file.@refill | |
| 19489 | |
| 19490 @item | |
| 19491 And then create a master menu in the outer file. This is similar to | |
| 19492 invoking @code{texinfo-master-menu} with an argument when you are | |
| 19493 working with just one file.@refill | |
| 19494 @end itemize | |
| 19495 @end table | |
| 19496 | |
| 19497 Note the use of the prefix argument in interactive use: with a regular | |
| 19498 prefix argument, just @w{@kbd{C-u}}, the | |
| 19499 @code{texinfo-multiple-files-update} command inserts a master menu; | |
| 19500 with a numeric prefix argument, such as @kbd{C-u 8}, the command | |
| 19501 updates @strong{every} pointer and menu in @strong{all} the files and then inserts a | |
| 19502 master menu.@refill | |
| 19503 | |
| 19504 | |
| 19505 @node Include Files Requirements | |
| 19506 @section Include Files Requirements | |
| 19507 @cindex Include files requirements | |
| 19508 @cindex Requirements for include files | |
| 19509 | |
| 19510 If you plan to use the @code{texinfo-multiple-files-update} command, | |
| 19511 the outer Texinfo file that lists included files within it should | |
| 19512 contain nothing but the beginning and end parts of a Texinfo file, and | |
| 19513 a number of @code{@@include} commands listing the included files. It | |
| 19514 should not even include indices, which should be listed in an included | |
| 19515 file of their own.@refill | |
| 19516 | |
| 19517 Moreover, each of the included files must contain exactly one highest | |
| 19518 level node (conventionally, @code{@@chapter} or equivalent), | |
| 19519 and this node must be the first node in the included file. | |
| 19520 Furthermore, each of these highest level nodes in each included file | |
| 19521 must be at the same hierarchical level in the file structure. | |
| 19522 Usually, each is an @code{@@chapter}, an @code{@@appendix}, or an | |
| 19523 @code{@@unnumbered} node. Thus, normally, each included file contains | |
| 19524 one, and only one, chapter or equivalent-level node.@refill | |
| 19525 | |
| 19526 The outer file should contain only @emph{one} node, the `Top' node. It | |
| 19527 should @emph{not} contain any nodes besides the single `Top' node. The | |
| 19528 @code{texinfo-multiple-files-update} command will not process | |
| 19529 them.@refill | |
| 19530 | |
| 19531 | |
| 19532 @node Sample Include File | |
| 19533 @section Sample File with @code{@@include} | |
| 19534 @cindex Sample @code{@@include} file | |
| 19535 @cindex Include file sample | |
| 19536 @cindex @code{@@include} file sample | |
| 19537 | |
| 19538 Here is an example of an outer Texinfo file with @code{@@include} files | |
| 19539 within it before running @code{texinfo-multiple-files-update}, which | |
| 19540 would insert a main or master menu: | |
| 19541 | |
| 19542 @example | |
| 19543 @group | |
| 19544 \input texinfo @@c -*-texinfo-*- | |
| 19545 @c %**start of header | |
| 19546 @@setfilename include-example.info | |
| 19547 @@settitle Include Example | |
| 19548 @c %**end of header | |
| 19549 @end group | |
| 19550 | |
| 19551 ... @xref{Sample Texinfo Files}, for | |
| 19552 examples of the rest of the frontmatter ... | |
| 19553 | |
| 19554 @group | |
| 19555 @@ifnottex | |
| 19556 @@node Top | |
| 19557 @@top Include Example | |
| 19558 @@end ifnottex | |
| 19559 @end group | |
| 19560 | |
| 19561 @group | |
| 19562 @@include foo.texinfo | |
| 19563 @@include bar.texinfo | |
| 19564 @@include concept-index.texinfo | |
| 19565 @@bye | |
| 19566 @end group | |
| 19567 @end example | |
| 19568 | |
| 19569 An included file, such as @file{foo.texinfo}, might look like this: | |
| 19570 | |
| 19571 @example | |
| 19572 @group | |
| 19573 @@node First | |
| 19574 @@chapter First Chapter | |
| 19575 | |
| 19576 Contents of first chapter @dots{} | |
| 19577 @end group | |
| 19578 @end example | |
| 19579 | |
| 19580 The full contents of @file{concept-index.texinfo} might be as simple as this: | |
| 19581 | |
| 19582 @example | |
| 19583 @group | |
| 19584 @@node Concept Index | |
| 19585 @@unnumbered Concept Index | |
| 19586 | |
| 19587 @@printindex cp | |
| 19588 @end group | |
| 19589 @end example | |
| 19590 | |
| 19591 The outer Texinfo source file for @cite{The XEmacs Lisp Reference | |
| 19592 Manual} is named @file{elisp.texi}. This outer file contains a master | |
| 19593 menu with 417 entries and a list of 41 @code{@@include} | |
| 19594 files. | |
| 19595 | |
| 19596 | |
| 19597 @node Include Files Evolution | |
| 19598 @section Evolution of Include Files | |
| 19599 | |
| 19600 When Info was first created, it was customary to create many small | |
| 19601 Info files on one subject. Each Info file was formatted from its own | |
| 19602 Texinfo source file. This custom meant that XEmacs did not need to | |
| 19603 make a large buffer to hold the whole of a large Info file when | |
| 19604 someone wanted information; instead, XEmacs allocated just enough | |
| 19605 memory for the small Info file that contained the particular | |
| 19606 information sought. This way, XEmacs could avoid wasting memory.@refill | |
| 19607 | |
| 19608 References from one file to another were made by referring to the file | |
| 19609 name as well as the node name. (@xref{Other Info Files, , Referring to | |
| 19610 Other Info Files}. Also, see @ref{Four and Five Arguments, , | |
| 19611 @code{@@xref} with Four and Five Arguments}.)@refill | |
| 19612 | |
| 19613 Include files were designed primarily as a way to create a single, | |
| 19614 large printed manual out of several smaller Info files. In a printed | |
| 19615 manual, all the references were within the same document, so @TeX{} | |
| 19616 could automatically determine the references' page numbers. The Info | |
| 19617 formatting commands used include files only for creating joint | |
| 19618 indices; each of the individual Texinfo files had to be formatted for | |
| 19619 Info individually. (Each, therefore, required its own | |
| 19620 @code{@@setfilename} line.)@refill | |
| 19621 | |
| 19622 However, because large Info files are now split automatically, it is | |
| 19623 no longer necessary to keep them small.@refill | |
| 19624 | |
| 19625 Nowadays, multiple Texinfo files are used mostly for large documents, | |
| 19626 such as @cite{The XEmacs Lisp Reference Manual}, and for projects | |
| 19627 in which several different people write different sections of a | |
| 19628 document simultaneously.@refill | |
| 19629 | |
| 19630 In addition, the Info formatting commands have been extended to work | |
| 19631 with the @code{@@include} command so as to create a single large Info | |
| 19632 file that is split into smaller files if necessary. This means that | |
| 19633 you can write menus and cross references without naming the different | |
| 19634 Texinfo files.@refill | |
| 19635 | 22534 |
| 19636 | 22535 |
| 19637 @node Headings | 22536 @node Headings |
| 19638 @appendix Page Headings | 22537 @appendix Page Headings |
| 19639 @cindex Headings | 22538 @cindex Headings |
| 19642 @cindex Page headings | 22541 @cindex Page headings |
| 19643 @cindex Formatting headings and footings | 22542 @cindex Formatting headings and footings |
| 19644 | 22543 |
| 19645 Most printed manuals contain headings along the top of every page | 22544 Most printed manuals contain headings along the top of every page |
| 19646 except the title and copyright pages. Some manuals also contain | 22545 except the title and copyright pages. Some manuals also contain |
| 19647 footings. (Headings and footings have no meaning to Info, which is | 22546 footings. @c HTML output also supports something like these, but in a |
| 19648 not paginated.)@refill | 22547 @c completely different way: @pxref{Customizing HTML Page Layout}. |
| 22548 Headings and footings have no meaning in Info or the other output | |
| 22549 formats. | |
| 19649 | 22550 |
| 19650 @menu | 22551 @menu |
| 19651 * Headings Introduced:: Conventions for using page headings. | 22552 * Headings Introduced:: Conventions for using page headings. |
| 19652 * Heading Format:: Standard page heading formats. | 22553 * Heading Format:: Standard page heading formats. |
| 19653 * Heading Choice:: How to specify the type of page heading. | 22554 * Heading Choice:: How to specify the type of page heading. |
| 19658 @section Headings Introduced | 22559 @section Headings Introduced |
| 19659 | 22560 |
| 19660 Texinfo provides standard page heading formats for manuals that are | 22561 Texinfo provides standard page heading formats for manuals that are |
| 19661 printed on one side of each sheet of paper and for manuals that are | 22562 printed on one side of each sheet of paper and for manuals that are |
| 19662 printed on both sides of the paper. Typically, you will use these | 22563 printed on both sides of the paper. Typically, you will use these |
| 19663 formats, but you can specify your own format if you wish.@refill | 22564 formats, but you can specify your own format if you wish. |
| 19664 | 22565 |
| 19665 In addition, you can specify whether chapters should begin on a new | 22566 In addition, you can specify whether chapters should begin on a new |
| 19666 page, or merely continue the same page as the previous chapter; and if | 22567 page, or merely continue the same page as the previous chapter; and if |
| 19667 chapters begin on new pages, you can specify whether they must be | 22568 chapters begin on new pages, you can specify whether they must be |
| 19668 odd-numbered pages.@refill | 22569 odd-numbered pages. |
| 19669 | 22570 |
| 19670 By convention, a book is printed on both sides of each sheet of paper. | 22571 By convention, a book is printed on both sides of each sheet of paper. |
| 19671 When you open a book, the right-hand page is odd-numbered, and | 22572 When you open a book, the right-hand page is odd-numbered, and |
| 19672 chapters begin on right-hand pages---a preceding left-hand page is | 22573 chapters begin on right-hand pages---a preceding left-hand page is |
| 19673 left blank if necessary. Reports, however, are often printed on just | 22574 left blank if necessary. Reports, however, are often printed on just |
| 19674 one side of paper, and chapters begin on a fresh page immediately | 22575 one side of paper, and chapters begin on a fresh page immediately |
| 19675 following the end of the preceding chapter. In short or informal | 22576 following the end of the preceding chapter. In short or informal |
| 19676 reports, chapters often do not begin on a new page at all, but are | 22577 reports, chapters often do not begin on a new page at all, but are |
| 19677 separated from the preceding text by a small amount of whitespace.@refill | 22578 separated from the preceding text by a small amount of whitespace. |
| 19678 | 22579 |
| 19679 The @code{@@setchapternewpage} command controls whether chapters begin | 22580 The @code{@@setchapternewpage} command controls whether chapters begin |
| 19680 on new pages, and whether one of the standard heading formats is used. | 22581 on new pages, and whether one of the standard heading formats is used. |
| 19681 In addition, Texinfo has several heading and footing commands that you | 22582 In addition, Texinfo has several heading and footing commands that you |
| 19682 can use to generate your own heading and footing formats.@refill | 22583 can use to generate your own heading and footing formats. |
| 19683 | 22584 |
| 19684 In Texinfo, headings and footings are single lines at the tops and | 22585 In Texinfo, headings and footings are single lines at the tops and |
| 19685 bottoms of pages; you cannot create multiline headings or footings. | 22586 bottoms of pages; you cannot create multiline headings or footings. |
| 19686 Each header or footer line is divided into three parts: a left part, a | 22587 Each header or footer line is divided into three parts: a left part, a |
| 19687 middle part, and a right part. Any part, or a whole line, may be left | 22588 middle part, and a right part. Any part, or a whole line, may be left |
| 19688 blank. Text for the left part of a header or footer line is set | 22589 blank. Text for the left part of a header or footer line is set |
| 19689 flushleft; text for the middle part is centered; and, text for the | 22590 flushleft; text for the middle part is centered; and, text for the |
| 19690 right part is set flushright.@refill | 22591 right part is set flushright. |
| 22592 | |
| 19691 | 22593 |
| 19692 @node Heading Format | 22594 @node Heading Format |
| 19693 @comment node-name, next, previous, up | |
| 19694 @section Standard Heading Formats | 22595 @section Standard Heading Formats |
| 19695 | 22596 |
| 19696 Texinfo provides two standard heading formats, one for manuals printed | 22597 Texinfo provides two standard heading formats, one for manuals printed |
| 19697 on one side of each sheet of paper, and the other for manuals printed | 22598 on one side of each sheet of paper, and the other for manuals printed |
| 19698 on both sides of the paper. | 22599 on both sides of the paper. |
| 19699 | 22600 |
| 19700 By default, nothing is specified for the footing of a Texinfo file, | 22601 By default, nothing is specified for the footing of a Texinfo file, |
| 19701 so the footing remains blank.@refill | 22602 so the footing remains blank. |
| 19702 | 22603 |
| 19703 The standard format for single-sided printing consists of a header | 22604 The standard format for single-sided printing consists of a header |
| 19704 line in which the left-hand part contains the name of the chapter, the | 22605 line in which the left-hand part contains the name of the chapter, the |
| 19705 central part is blank, and the right-hand part contains the page | 22606 central part is blank, and the right-hand part contains the page |
| 19706 number.@refill | 22607 number. |
| 19707 | 22608 |
| 19708 @need 950 | 22609 @need 950 |
| 19709 A single-sided page looks like this: | 22610 A single-sided page looks like this: |
| 19710 | 22611 |
| 19711 @example | 22612 @example |
| 19725 left- and odd-numbered pages are on the right. (@TeX{} will adjust the | 22626 left- and odd-numbered pages are on the right. (@TeX{} will adjust the |
| 19726 widths of the left- and right-hand margins. Usually, widths are | 22627 widths of the left- and right-hand margins. Usually, widths are |
| 19727 correct, but during double-sided printing, it is wise to check that | 22628 correct, but during double-sided printing, it is wise to check that |
| 19728 pages will bind properly---sometimes a printer will produce output in | 22629 pages will bind properly---sometimes a printer will produce output in |
| 19729 which the even-numbered pages have a larger right-hand margin than the | 22630 which the even-numbered pages have a larger right-hand margin than the |
| 19730 odd-numbered pages.)@refill | 22631 odd-numbered pages.) |
| 19731 | 22632 |
| 19732 In the standard double-sided format, the left part of the left-hand | 22633 In the standard double-sided format, the left part of the left-hand |
| 19733 (even-numbered) page contains the page number, the central part is | 22634 (even-numbered) page contains the page number, the central part is |
| 19734 blank, and the right part contains the title (specified by the | 22635 blank, and the right part contains the title (specified by the |
| 19735 @code{@@settitle} command). The left part of the right-hand | 22636 @code{@@settitle} command). The left part of the right-hand |
| 19736 (odd-numbered) page contains the name of the chapter, the central part | 22637 (odd-numbered) page contains the name of the chapter, the central part |
| 19737 is blank, and the right part contains the page number.@refill | 22638 is blank, and the right part contains the page number. |
| 19738 | 22639 |
| 19739 @need 750 | 22640 @need 750 |
| 19740 Two pages, side by side as in an open book, look like this:@refill | 22641 Two pages, side by side as in an open book, look like this: |
| 19741 | 22642 |
| 19742 @example | 22643 @example |
| 19743 @group | 22644 @group |
| 19744 _______________________ _______________________ | 22645 _______________________ _______________________ |
| 19745 | | | | | 22646 | | | | |
| 19752 @end example | 22653 @end example |
| 19753 | 22654 |
| 19754 @noindent | 22655 @noindent |
| 19755 The chapter name is preceded by the word ``Chapter'', the chapter number | 22656 The chapter name is preceded by the word ``Chapter'', the chapter number |
| 19756 and a colon. This makes it easier to keep track of where you are in the | 22657 and a colon. This makes it easier to keep track of where you are in the |
| 19757 manual.@refill | 22658 manual. |
| 19758 | 22659 |
| 19759 @node Heading Choice | 22660 @node Heading Choice |
| 19760 @comment node-name, next, previous, up | |
| 19761 @section Specifying the Type of Heading | 22661 @section Specifying the Type of Heading |
| 19762 | 22662 |
| 19763 @TeX{} does not begin to generate page headings for a standard Texinfo | 22663 @TeX{} does not begin to generate page headings for a standard Texinfo |
| 19764 file until it reaches the @code{@@end titlepage} command. Thus, the | 22664 file until it reaches the @code{@@end titlepage} command. Thus, the |
| 19765 title and copyright pages are not numbered. The @code{@@end | 22665 title and copyright pages are not numbered. The @code{@@end |
| 19766 titlepage} command causes @TeX{} to begin to generate page headings | 22666 titlepage} command causes @TeX{} to begin to generate page headings |
| 19767 according to a standard format specified by the | 22667 according to a standard format specified by the |
| 19768 @code{@@setchapternewpage} command that precedes the | 22668 @code{@@setchapternewpage} command that precedes the |
| 19769 @code{@@titlepage} section.@refill | 22669 @code{@@titlepage} section. |
| 19770 | 22670 |
| 19771 @need 1000 | 22671 @need 1000 |
| 19772 There are four possibilities:@refill | 22672 There are four possibilities: |
| 19773 | 22673 |
| 19774 @table @asis | 22674 @table @asis |
| 19775 @item No @code{@@setchapternewpage} command | 22675 @item No @code{@@setchapternewpage} command |
| 19776 Cause @TeX{} to specify the single-sided heading format, with chapters | 22676 Cause @TeX{} to specify the single-sided heading format, with chapters |
| 19777 on new pages. This is the same as @code{@@setchapternewpage on}.@refill | 22677 on new pages. This is the same as @code{@@setchapternewpage on}. |
| 19778 | 22678 |
| 19779 @item @code{@@setchapternewpage on} | 22679 @item @code{@@setchapternewpage on} |
| 19780 Specify the single-sided heading format, with chapters on new pages.@refill | 22680 Specify the single-sided heading format, with chapters on new pages. |
| 19781 | 22681 |
| 19782 @item @code{@@setchapternewpage off} | 22682 @item @code{@@setchapternewpage off} |
| 19783 Cause @TeX{} to start a new chapter on the same page as the last page of | 22683 Cause @TeX{} to start a new chapter on the same page as the last page |
| 19784 the preceding chapter, after skipping some vertical whitespace. Also | 22684 of the preceding chapter, after skipping some vertical whitespace. |
| 19785 cause @TeX{} to typeset for single-sided printing. (You can override | 22685 Also cause @TeX{} to typeset for single-sided printing. (You can |
| 19786 the headers format with the @code{@@headings double} command; see | 22686 override the headers format with the @code{@@headings double} command; |
| 19787 @ref{headings on off, , The @code{@@headings} Command}.)@refill | 22687 @pxref{@t{@@headings}}.) |
| 19788 | 22688 |
| 19789 @item @code{@@setchapternewpage odd} | 22689 @item @code{@@setchapternewpage odd} |
| 19790 Specify the double-sided heading format, with chapters on new pages.@refill | 22690 Specify the double-sided heading format, with chapters on new pages. |
| 19791 @end table | 22691 @end table |
| 19792 | 22692 |
| 19793 @noindent | 22693 @noindent |
| 19794 Texinfo lacks an @code{@@setchapternewpage even} command.@refill | 22694 Texinfo lacks an @code{@@setchapternewpage even} command. |
| 22695 | |
| 19795 | 22696 |
| 19796 @node Custom Headings | 22697 @node Custom Headings |
| 19797 @comment node-name, next, previous, up | |
| 19798 @section How to Make Your Own Headings | 22698 @section How to Make Your Own Headings |
| 19799 | 22699 |
| 19800 You can use the standard headings provided with Texinfo or specify | 22700 You can use the standard headings provided with Texinfo or specify |
| 19801 your own. By default, Texinfo has no footers, so if you specify them, | 22701 your own. By default, Texinfo has no footers, so if you specify them, |
| 19802 the available page size for the main text will be slightly reduced. | 22702 the available page size for the main text will be slightly reduced. |
| 19803 | 22703 |
| 19804 Texinfo provides six commands for specifying headings and | 22704 Texinfo provides six commands for specifying headings and |
| 19805 footings: | 22705 footings: |
| 19806 @itemize @bullet | 22706 @itemize @bullet |
| 19807 @item | 22707 @item |
| 19808 @code{@@everyheading} @code{@@everyfooting} generate page headers and | 22708 @code{@@everyheading} and @code{@@everyfooting} generate page headers and |
| 19809 footers that are the same for both even- and odd-numbered pages. | 22709 footers that are the same for both even- and odd-numbered pages. |
| 19810 @item | 22710 @item |
| 19811 @code{@@evenheading} and @code{@@evenfooting} command generate headers | 22711 @code{@@evenheading} and @code{@@evenfooting} command generate headers |
| 19812 and footers for even-numbered (left-hand) pages. | 22712 and footers for even-numbered (left-hand) pages. |
| 19813 @item | 22713 @item |
| 19814 @code{@@oddheading} and @code{@@oddfooting} generate headers and footers | 22714 @code{@@oddheading} and @code{@@oddfooting} generate headers and footers |
| 19815 for odd-numbered (right-hand) pages. | 22715 for odd-numbered (right-hand) pages. |
| 19816 @end itemize | 22716 @end itemize |
| 19817 | 22717 |
| 19818 Write custom heading specifications in the Texinfo file immediately | 22718 Write custom heading specifications in the Texinfo file immediately |
| 19819 after the @code{@@end titlepage} command. | 22719 after the @code{@@end titlepage} command. You must cancel the |
| 19820 You must cancel the predefined heading commands with the | 22720 predefined heading commands with the @code{@@headings off} command |
| 19821 @code{@@headings off} command before defining your own | 22721 before defining your own specifications. |
| 19822 specifications. | |
| 19823 | 22722 |
| 19824 @need 1000 | 22723 @need 1000 |
| 19825 Here is how to tell @TeX{} to place the chapter name at the left, the | 22724 Here is how to tell @TeX{} to place the chapter name at the left, the |
| 19826 page number in the center, and the date at the right of every header | 22725 page number in the center, and the date at the right of every header |
| 19827 for both even- and odd-numbered pages: | 22726 for both even- and odd-numbered pages: |
| 19837 You need to divide the left part from the central part and the central | 22736 You need to divide the left part from the central part and the central |
| 19838 part from the right part by inserting @samp{@@|} between parts. | 22737 part from the right part by inserting @samp{@@|} between parts. |
| 19839 Otherwise, the specification command will not be able to tell where | 22738 Otherwise, the specification command will not be able to tell where |
| 19840 the text for one part ends and the next part begins. | 22739 the text for one part ends and the next part begins. |
| 19841 | 22740 |
| 19842 Each part can contain text or @@-commands. The text | 22741 Each part can contain text or @@-commands. The text is printed as if |
| 19843 is printed as if the part were within an ordinary paragraph in the | 22742 the part were within an ordinary paragraph in the body of the page. |
| 19844 body of the page. The @@-commands replace | 22743 The @@-commands replace themselves with the page number, date, chapter |
| 19845 themselves with the page number, date, chapter name, or | 22744 name, or whatever. |
| 19846 whatever. | |
| 19847 | 22745 |
| 19848 @need 950 | 22746 @need 950 |
| 19849 Here are the six heading and footing commands: | 22747 Here are the six heading and footing commands: |
| 19850 | 22748 |
| 19851 @table @code | 22749 @table @code |
| 19985 By default the @code{@@this...} commands reflect the situation at the | 22883 By default the @code{@@this...} commands reflect the situation at the |
| 19986 bottom of a page both in headings and in footings. | 22884 bottom of a page both in headings and in footings. |
| 19987 | 22885 |
| 19988 | 22886 |
| 19989 @node Catching Mistakes | 22887 @node Catching Mistakes |
| 19990 @appendix Formatting Mistakes | 22888 @appendix Catching Mistakes |
| 19991 @cindex Structure, catching mistakes in | 22889 @cindex Structure, catching mistakes in |
| 19992 @cindex Nodes, catching mistakes | 22890 @cindex Nodes, catching mistakes |
| 19993 @cindex Catching mistakes | 22891 @cindex Catching mistakes |
| 19994 @cindex Correcting mistakes | 22892 @cindex Correcting mistakes |
| 19995 @cindex Mistakes, catching | 22893 @cindex Mistakes, catching |
| 20000 kinds of mistake you can make with Texinfo: you can make mistakes with | 22898 kinds of mistake you can make with Texinfo: you can make mistakes with |
| 20001 @@-commands, and you can make mistakes with the structure of the nodes | 22899 @@-commands, and you can make mistakes with the structure of the nodes |
| 20002 and chapters. | 22900 and chapters. |
| 20003 | 22901 |
| 20004 XEmacs has two tools for catching the @@-command mistakes and two for | 22902 XEmacs has two tools for catching the @@-command mistakes and two for |
| 20005 catching structuring mistakes.@refill | 22903 catching structuring mistakes. |
| 20006 | 22904 |
| 20007 For finding problems with @@-commands, you can run @TeX{} or a region | 22905 For finding problems with @@-commands, you can run @TeX{} or a region |
| 20008 formatting command on the region that has a problem; indeed, you can | 22906 formatting command on the region that has a problem; indeed, you can |
| 20009 run these commands on each region as you write it.@refill | 22907 run these commands on each region as you write it. |
| 20010 | 22908 |
| 20011 For finding problems with the structure of nodes and chapters, you can use | 22909 For finding problems with the structure of nodes and chapters, you can use |
| 20012 @kbd{C-c C-s} (@code{texinfo-show-structure}) and the related @code{occur} | 22910 @kbd{C-c C-s} (@code{texinfo-show-structure}) and the related @code{occur} |
| 20013 command and you can use the @kbd{M-x Info-validate} command.@refill | 22911 command and you can use the @kbd{M-x Info-validate} command. |
| 20014 | 22912 |
| 20015 @menu | 22913 @menu |
| 20016 * makeinfo Preferred:: @code{makeinfo} finds errors. | 22914 * @t{makeinfo} Preferred:: @code{makeinfo} finds errors. |
| 20017 * Debugging with Info:: How to catch errors with Info formatting. | 22915 * Debugging with Info:: How to catch errors with Info formatting. |
| 20018 * Debugging with TeX:: How to catch errors with @TeX{} formatting. | 22916 * Debugging with @TeX{}:: How to catch errors with @TeX{} formatting. |
| 20019 * Using texinfo-show-structure:: How to use @code{texinfo-show-structure}. | 22917 * Using @t{texinfo-show-structure}:: How to use @code{texinfo-show-structure}. |
| 20020 * Using occur:: How to list all lines containing a pattern. | 22918 * Using @t{occur}:: How to list all lines containing a pattern. |
| 20021 * Running Info-Validate:: How to find badly referenced nodes. | 22919 * Running @t{Info-validate}:: How to find badly referenced nodes. |
| 20022 @end menu | 22920 @end menu |
| 20023 | 22921 |
| 20024 | 22922 |
| 20025 @node makeinfo Preferred | 22923 @node @t{makeinfo} Preferred |
| 20026 @section @code{makeinfo} Find Errors | 22924 @section @code{makeinfo} Preferred |
| 22925 | |
| 22926 @c anchor{makeinfo Preferred}@c prev name | |
| 20027 | 22927 |
| 20028 The @code{makeinfo} program does an excellent job of catching errors | 22928 The @code{makeinfo} program does an excellent job of catching errors |
| 20029 and reporting them---far better than @code{texinfo-format-region} or | 22929 and reporting them---far better than @code{texinfo-format-region} or |
| 20030 @code{texinfo-format-buffer}. In addition, the various functions for | 22930 @code{texinfo-format-buffer}. In addition, the various functions for |
| 20031 automatically creating and updating node pointers and menus remove | 22931 automatically creating and updating node pointers and menus remove |
| 20032 many opportunities for human error.@refill | 22932 many opportunities for human error. |
| 20033 | 22933 |
| 20034 If you can, use the updating commands to create and insert pointers | 22934 If you can, use the updating commands to create and insert pointers |
| 20035 and menus. These prevent many errors. Then use @code{makeinfo} (or | 22935 and menus. These prevent many errors. Then use @code{makeinfo} (or |
| 20036 its Texinfo mode manifestations, @code{makeinfo-region} and | 22936 its Texinfo mode manifestations, @code{makeinfo-region} and |
| 20037 @code{makeinfo-buffer}) to format your file and check for other | 22937 @code{makeinfo-buffer}) to format your file and check for other |
| 20038 errors. This is the best way to work with Texinfo. But if you | 22938 errors. This is the best way to work with Texinfo. But if you |
| 20039 cannot use @code{makeinfo}, or your problem is very puzzling, then you | 22939 cannot use @code{makeinfo}, or your problem is very puzzling, then you |
| 20040 may want to use the tools described in this appendix.@refill | 22940 may want to use the tools described in this appendix. |
| 22941 | |
| 20041 | 22942 |
| 20042 @node Debugging with Info | 22943 @node Debugging with Info |
| 20043 @comment node-name, next, previous, up | |
| 20044 @section Catching Errors with Info Formatting | 22944 @section Catching Errors with Info Formatting |
| 20045 @cindex Catching errors with Info formatting | 22945 @cindex Catching errors with Info formatting |
| 20046 @cindex Debugging with Info formatting | 22946 @cindex Debugging with Info formatting |
| 20047 | 22947 |
| 20048 After you have written part of a Texinfo file, you can use the | 22948 After you have written part of a Texinfo file, you can use the |
| 20049 @code{texinfo-format-region} or the @code{makeinfo-region} command to | 22949 @code{texinfo-format-region} or the @code{makeinfo-region} command to |
| 20050 see whether the region formats properly.@refill | 22950 see whether the region formats properly. |
| 20051 | 22951 |
| 20052 Most likely, however, you are reading this section because for some | 22952 Most likely, however, you are reading this section because for some |
| 20053 reason you cannot use the @code{makeinfo-region} command; therefore, the | 22953 reason you cannot use the @code{makeinfo-region} command; therefore, the |
| 20054 rest of this section presumes that you are using | 22954 rest of this section presumes that you are using |
| 20055 @code{texinfo-format-region}.@refill | 22955 @code{texinfo-format-region}. |
| 20056 | 22956 |
| 20057 If you have made a mistake with an @@-command, | 22957 If you have made a mistake with an @@-command, |
| 20058 @code{texinfo-format-region} will stop processing at or after the | 22958 @code{texinfo-format-region} will stop processing at or after the |
| 20059 error and display an error message. To see where in the buffer the | 22959 error and display an error message. To see where in the buffer the |
| 20060 error occurred, switch to the @samp{*Info Region*} buffer; the cursor | 22960 error occurred, switch to the @samp{*Info Region*} buffer; the cursor |
| 20061 will be in a position that is after the location of the error. Also, | 22961 will be in a position that is after the location of the error. Also, |
| 20062 the text will not be formatted after the place where the error | 22962 the text will not be formatted after the place where the error |
| 20063 occurred (or more precisely, where it was detected).@refill | 22963 occurred (or more precisely, where it was detected). |
| 20064 | 22964 |
| 20065 For example, if you accidentally end a menu with the command @code{@@end | 22965 For example, if you accidentally end a menu with the command @code{@@end |
| 20066 menus} with an `s' on the end, instead of with @code{@@end menu}, you | 22966 menus} with an `s' on the end, instead of with @code{@@end menu}, you |
| 20067 will see an error message that says:@refill | 22967 will see an error message that says: |
| 20068 | 22968 |
| 20069 @example | 22969 @example |
| 20070 @@end menus is not handled by texinfo | 22970 @@end menus is not handled by texinfo |
| 20071 @end example | 22971 @end example |
| 20072 | 22972 |
| 20073 @noindent | 22973 @noindent |
| 20074 The cursor will stop at the point in the buffer where the error | 22974 The cursor will stop at the point in the buffer where the error |
| 20075 occurs, or not long after it. The buffer will look like this:@refill | 22975 occurs, or not long after it. The buffer will look like this: |
| 20076 | 22976 |
| 20077 @example | 22977 @example |
| 20078 @group | 22978 @group |
| 20079 ---------- Buffer: *Info Region* ---------- | 22979 ---------- Buffer: *Info Region* ---------- |
| 20080 * Menu: | 22980 * Menu: |
| 20081 | 22981 |
| 20082 * Using texinfo-show-structure:: How to use | 22982 * Using texinfo-show-structure:: How to use |
| 20083 `texinfo-show-structure' | 22983 `texinfo-show-structure' |
| 20084 to catch mistakes. | 22984 to catch mistakes. |
| 20085 * Running Info-Validate:: How to check for | 22985 * Running Info-validate:: How to check for |
| 20086 unreferenced nodes. | 22986 unreferenced nodes. |
| 20087 @@end menus | 22987 @@end menus |
| 20088 @point{} | 22988 @point{} |
| 20089 ---------- Buffer: *Info Region* ---------- | 22989 ---------- Buffer: *Info Region* ---------- |
| 20090 @end group | 22990 @end group |
| 20091 @end example | 22991 @end example |
| 20092 | 22992 |
| 20093 The @code{texinfo-format-region} command sometimes provides slightly | 22993 The @code{texinfo-format-region} command sometimes provides slightly |
| 20094 odd error messages. For example, the following cross reference fails to format:@refill | 22994 odd error messages. For example, the following cross reference fails to format: |
| 20095 | 22995 |
| 20096 @example | 22996 @example |
| 20097 (@@xref@{Catching Mistakes, for more info.) | 22997 (@@xref@{Catching Mistakes, for more info.) |
| 20098 @end example | 22998 @end example |
| 20099 | 22999 |
| 20100 @noindent | 23000 @noindent |
| 20101 In this case, @code{texinfo-format-region} detects the missing closing | 23001 In this case, @code{texinfo-format-region} detects the missing closing |
| 20102 brace but displays a message that says @samp{Unbalanced parentheses} | 23002 brace but displays a message that says @samp{Unbalanced parentheses} |
| 20103 rather than @samp{Unbalanced braces}. This is because the formatting | 23003 rather than @samp{Unbalanced braces}. This is because the formatting |
| 20104 command looks for mismatches between braces as if they were | 23004 command looks for mismatches between braces as if they were |
| 20105 parentheses.@refill | 23005 parentheses. |
| 20106 | 23006 |
| 20107 Sometimes @code{texinfo-format-region} fails to detect mistakes. For | 23007 Sometimes @code{texinfo-format-region} fails to detect mistakes. For |
| 20108 example, in the following, the closing brace is swapped with the | 23008 example, in the following, the closing brace is swapped with the |
| 20109 closing parenthesis:@refill | 23009 closing parenthesis: |
| 20110 | 23010 |
| 20111 @example | 23011 @example |
| 20112 (@@xref@{Catching Mistakes), for more info.@} | 23012 (@@xref@{Catching Mistakes), for more info.@} |
| 20113 @end example | 23013 @end example |
| 20114 | 23014 |
| 20117 @example | 23017 @example |
| 20118 (*Note for more info.: Catching Mistakes) | 23018 (*Note for more info.: Catching Mistakes) |
| 20119 @end example | 23019 @end example |
| 20120 | 23020 |
| 20121 The only way for you to detect this error is to realize that the | 23021 The only way for you to detect this error is to realize that the |
| 20122 reference should have looked like this:@refill | 23022 reference should have looked like this: |
| 20123 | 23023 |
| 20124 @example | 23024 @example |
| 20125 (*Note Catching Mistakes::, for more info.) | 23025 (*Note Catching Mistakes::, for more info.) |
| 20126 @end example | 23026 @end example |
| 20127 | 23027 |
| 20141 will complete the node name of the correctly written example and take | 23041 will complete the node name of the correctly written example and take |
| 20142 you to the `Catching Mistakes' node. (If you try this, you can return | 23042 you to the `Catching Mistakes' node. (If you try this, you can return |
| 20143 from the `Catching Mistakes' node by typing @kbd{l} | 23043 from the `Catching Mistakes' node by typing @kbd{l} |
| 20144 (@code{Info-last}).) | 23044 (@code{Info-last}).) |
| 20145 | 23045 |
| 20146 @c !!! section on using Elisp debugger ignored. | 23046 |
| 20147 @ignore | 23047 @node Debugging with @TeX{} |
| 20148 Sometimes @code{texinfo-format-region} will stop long after the | 23048 @section Debugging with @TeX{} |
| 20149 original error; this is because it does not discover the problem until | |
| 20150 then. In this case, you will need to backtrack.@refill | |
| 20151 | |
| 20152 @c menu | |
| 20153 @c * Using the XEmacs Lisp Debugger:: How to use the XEmacs Lisp debugger. | |
| 20154 @c end menu | |
| 20155 | |
| 20156 @c node Using the XEmacs Lisp Debugger | |
| 20157 @c appendixsubsec Using the XEmacs Lisp Debugger | |
| 20158 @c index Using the XEmacs Lisp debugger | |
| 20159 @c index XEmacs Lisp debugger | |
| 20160 @c index Debugger, using the XEmacs Lisp | |
| 20161 | |
| 20162 If an error is especially elusive, you can turn on the XEmacs Lisp | |
| 20163 debugger and look at the backtrace; this tells you where in the | |
| 20164 @code{texinfo-format-region} function the problem occurred. You can | |
| 20165 turn on the debugger with the command:@refill | |
| 20166 | |
| 20167 @example | |
| 20168 M-x set-variable @key{RET} debug-on-error @key{RET} t @key{RET} | |
| 20169 @end example | |
| 20170 | |
| 20171 @noindent | |
| 20172 and turn it off with | |
| 20173 | |
| 20174 @example | |
| 20175 M-x set-variable @key{RET} debug-on-error @key{RET} nil @key{RET} | |
| 20176 @end example | |
| 20177 | |
| 20178 Often, when you are using the debugger, it is easier to follow what is | |
| 20179 going on if you use the XEmacs Lisp files that are not byte-compiled. | |
| 20180 The byte-compiled sources send octal numbers to the debugger that may | |
| 20181 look mysterious. To use the uncompiled source files, load | |
| 20182 @file{texinfmt.el} and @file{texinfo.el} with the @kbd{M-x load-file} | |
| 20183 command.@refill | |
| 20184 | |
| 20185 The debugger will not catch an error if @code{texinfo-format-region} | |
| 20186 does not detect one. In the example shown above, | |
| 20187 @code{texinfo-format-region} did not find the error when the whole | |
| 20188 list was formatted, but only when part of the list was formatted. | |
| 20189 When @code{texinfo-format-region} did not find an error, the debugger | |
| 20190 did not find one either. @refill | |
| 20191 | |
| 20192 However, when @code{texinfo-format-region} did report an error, it | |
| 20193 invoked the debugger. This is the backtrace it produced:@refill | |
| 20194 | |
| 20195 @example | |
| 20196 ---------- Buffer: *Backtrace* ---------- | |
| 20197 Signalling: (search-failed "[@},]") | |
| 20198 re-search-forward("[@},]") | |
| 20199 (while ...) | |
| 20200 (let ...) | |
| 20201 texinfo-format-parse-args() | |
| 20202 (let ...) | |
| 20203 texinfo-format-xref() | |
| 20204 funcall(texinfo-format-xref) | |
| 20205 (if ...) | |
| 20206 (let ...) | |
| 20207 (if ...) | |
| 20208 (while ...) | |
| 20209 texinfo-format-scan() | |
| 20210 (save-excursion ...) | |
| 20211 (let ...) | |
| 20212 texinfo-format-region(103370 103631) | |
| 20213 * call-interactively(texinfo-format-region) | |
| 20214 ---------- Buffer: *Backtrace* ---------- | |
| 20215 @end example | |
| 20216 | |
| 20217 The backtrace is read from the bottom up. | |
| 20218 @code{texinfo-format-region} was called interactively; and it, in | |
| 20219 turn, called various functions, including @code{texinfo-format-scan}, | |
| 20220 @code{texinfo-format-xref} and @code{texinfo-format-parse-args}. | |
| 20221 Inside the function @code{texinfo-format-parse-args}, the function | |
| 20222 @code{re-search-forward} was called; it was this function that could | |
| 20223 not find the missing right-hand brace.@refill | |
| 20224 | |
| 20225 @xref{Lisp Debug, , Debugging XEmacs Lisp, xemacs, XEmacs User's Manual}, | |
| 20226 for more information.@refill | |
| 20227 @end ignore | |
| 20228 | |
| 20229 @node Debugging with TeX | |
| 20230 @comment node-name, next, previous, up | |
| 20231 @section Catching Errors with @TeX{} Formatting | |
| 20232 @cindex Catching errors with @TeX{} formatting | 23049 @cindex Catching errors with @TeX{} formatting |
| 20233 @cindex Debugging with @TeX{} formatting | 23050 @cindex Debugging with @TeX{} formatting |
| 20234 | 23051 |
| 20235 You can also catch mistakes when you format a file with @TeX{}.@refill | 23052 You can also catch mistakes when you format a file with @TeX{}. |
| 20236 | 23053 |
| 20237 Usually, you will want to do this after you have run | 23054 Usually, you will want to do this after you have run |
| 20238 @code{texinfo-format-buffer} (or, better, @code{makeinfo-buffer}) on | 23055 @code{texinfo-format-buffer} (or, better, @code{makeinfo-buffer}) on |
| 20239 the same file, because @code{texinfo-format-buffer} sometimes displays | 23056 the same file, because @code{texinfo-format-buffer} sometimes displays |
| 20240 error messages that make more sense than @TeX{}. (@xref{Debugging | 23057 error messages that make more sense than @TeX{}. (@xref{Debugging |
| 20241 with Info}, for more information.)@refill | 23058 with Info}, for more information.) |
| 20242 | 23059 |
| 20243 For example, @TeX{} was run on a Texinfo file, part of which is shown | 23060 For example, @TeX{} was run on a Texinfo file, part of which is shown |
| 20244 here:@refill | 23061 here: |
| 20245 | 23062 |
| 20246 @example | 23063 @example |
| 20247 ---------- Buffer: texinfo.texi ---------- | 23064 ---------- Buffer: texinfo.texi ---------- |
| 20248 name of the Texinfo file as an extension. The | 23065 name of the Texinfo file as an extension. The |
| 20249 @@samp@{??@} are `wildcards' that cause the shell to | 23066 @@samp@{??@} are `wildcards' that cause the shell to |
| 20253 ---------- Buffer: texinfo.texi ---------- | 23070 ---------- Buffer: texinfo.texi ---------- |
| 20254 @end example | 23071 @end example |
| 20255 | 23072 |
| 20256 @noindent | 23073 @noindent |
| 20257 (The cross reference lacks a closing brace.) | 23074 (The cross reference lacks a closing brace.) |
| 20258 @TeX{} produced the following output, after which it stopped:@refill | 23075 @TeX{} produced the following output, after which it stopped: |
| 20259 | 23076 |
| 20260 @example | 23077 @example |
| 20261 ---------- Buffer: *tex-shell* ---------- | 23078 ---------- Buffer: *tex-shell* ---------- |
| 20262 Runaway argument? | 23079 Runaway argument? |
| 20263 @{sorting indices, for more information about sorting | 23080 @{sorting indices, for more information about sorting |
| 20280 | 23097 |
| 20281 @noindent | 23098 @noindent |
| 20282 @samp{@@par} is an internal @TeX{} command of no relevance to Texinfo. | 23099 @samp{@@par} is an internal @TeX{} command of no relevance to Texinfo. |
| 20283 @samp{l.27} means that @TeX{} detected the problem on line 27 of the | 23100 @samp{l.27} means that @TeX{} detected the problem on line 27 of the |
| 20284 Texinfo file. The @samp{?} is the prompt @TeX{} uses in this | 23101 Texinfo file. The @samp{?} is the prompt @TeX{} uses in this |
| 20285 circumstance.@refill | 23102 circumstance. |
| 20286 | 23103 |
| 20287 Unfortunately, @TeX{} is not always so helpful, and sometimes you must | 23104 Unfortunately, @TeX{} is not always so helpful, and sometimes you must |
| 20288 truly be a Sherlock Holmes to discover what went wrong.@refill | 23105 truly be a Sherlock Holmes to discover what went wrong. |
| 20289 | 23106 |
| 20290 In any case, if you run into a problem like this, you can do one of three | 23107 In any case, if you run into a problem like this, you can do one of three |
| 20291 things.@refill | 23108 things. |
| 20292 | 23109 |
| 20293 @enumerate | 23110 @enumerate |
| 20294 @item | 23111 @item |
| 20295 You can tell @TeX{} to continue running and ignore just this error by | 23112 You can tell @TeX{} to continue running and ignore just this error by |
| 20296 typing @key{RET} at the @samp{?} prompt.@refill | 23113 typing @key{RET} at the @samp{?} prompt. |
| 20297 | 23114 |
| 20298 @item | 23115 @item |
| 20299 You can tell @TeX{} to continue running and to ignore all errors as best | 23116 You can tell @TeX{} to continue running and to ignore all errors as best |
| 20300 it can by typing @kbd{r @key{RET}} at the @samp{?} prompt.@refill | 23117 it can by typing @kbd{r @key{RET}} at the @samp{?} prompt. |
| 20301 | 23118 |
| 20302 This is often the best thing to do. However, beware: the one error | 23119 This is often the best thing to do. However, beware: the one error |
| 20303 may produce a cascade of additional error messages as its consequences | 23120 may produce a cascade of additional error messages as its consequences |
| 20304 are felt through the rest of the file. To stop @TeX{} when it is | 23121 are felt through the rest of the file. To stop @TeX{} when it is |
| 20305 producing such an avalanche of error messages, type @kbd{C-c} (or | 23122 producing such an avalanche of error messages, type @kbd{C-c} (or |
| 20306 @kbd{C-c C-c}, if you are running a shell inside XEmacs). | 23123 @kbd{C-c C-c}, if you are running a shell inside XEmacs). |
| 20307 | 23124 |
| 20308 @item | 23125 @item |
| 20309 You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}} | 23126 You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}} |
| 20310 at the @samp{?} prompt.@refill | 23127 at the @samp{?} prompt. |
| 20311 @end enumerate | 23128 @end enumerate |
| 20312 | 23129 |
| 20313 If you are running @TeX{} inside XEmacs, you need to switch to the shell | 23130 If you are running @TeX{} inside XEmacs, you need to switch to the shell |
| 20314 buffer and line at which @TeX{} offers the @samp{?} prompt. | 23131 buffer and line at which @TeX{} offers the @samp{?} prompt. |
| 20315 | 23132 |
| 20316 Sometimes @TeX{} will format a file without producing error messages even | 23133 Sometimes @TeX{} will format a file without producing error messages even |
| 20317 though there is a problem. This usually occurs if a command is not ended | 23134 though there is a problem. This usually occurs if a command is not ended |
| 20318 but @TeX{} is able to continue processing anyhow. For example, if you fail | 23135 but @TeX{} is able to continue processing anyhow. For example, if you fail |
| 20319 to end an itemized list with the @code{@@end itemize} command, @TeX{} will | 23136 to end an itemized list with the @code{@@end itemize} command, @TeX{} will |
| 20320 write a DVI file that you can print out. The only error message that | 23137 write a DVI file that you can print out. The only error message that |
| 20321 @TeX{} will give you is the somewhat mysterious comment that@refill | 23138 @TeX{} will give you is the somewhat mysterious comment: |
| 20322 | 23139 |
| 20323 @example | 23140 @example |
| 20324 (@@end occurred inside a group at level 1) | 23141 (@@end occurred inside a group at level 1) |
| 20325 @end example | 23142 @end example |
| 20326 | 23143 |
| 20328 However, if you print the DVI file, you will find that the text | 23145 However, if you print the DVI file, you will find that the text |
| 20329 of the file that follows the itemized list is entirely indented as if | 23146 of the file that follows the itemized list is entirely indented as if |
| 20330 it were part of the last item in the itemized list. The error message | 23147 it were part of the last item in the itemized list. The error message |
| 20331 is the way @TeX{} says that it expected to find an @code{@@end} | 23148 is the way @TeX{} says that it expected to find an @code{@@end} |
| 20332 command somewhere in the file; but that it could not determine where | 23149 command somewhere in the file; but that it could not determine where |
| 20333 it was needed.@refill | 23150 it was needed. |
| 20334 | 23151 |
| 20335 Another source of notoriously hard-to-find errors is a missing | 23152 Another source of notoriously hard-to-find errors is a missing |
| 20336 @code{@@end group} command. If you ever are stumped by | 23153 @code{@@end group} command. If you ever are stumped by |
| 20337 incomprehensible errors, look for a missing @code{@@end group} command | 23154 incomprehensible errors, look for a missing @code{@@end group} command |
| 20338 first.@refill | 23155 first. |
| 20339 | 23156 |
| 20340 If the Texinfo file lacks header lines, | 23157 If the Texinfo file lacks header lines, |
| 20341 @TeX{} may stop in the | 23158 @TeX{} may stop in the |
| 20342 beginning of its run and display output that looks like the following. | 23159 beginning of its run and display output that looks like the following. |
| 20343 The @samp{*} indicates that @TeX{} is waiting for input.@refill | 23160 The @samp{*} indicates that @TeX{} is waiting for input. |
| 20344 | 23161 |
| 20345 @example | 23162 @example |
| 20346 This is TeX, Version 3.14159 (Web2c 7.0) | 23163 This is TeX, Version 3.14159 (Web2c 7.0) |
| 20347 (test.texinfo [1]) | 23164 (test.texinfo [1]) |
| 20348 * | 23165 * |
| 20351 @noindent | 23168 @noindent |
| 20352 In this case, simply type @kbd{\end @key{RET}} after the asterisk. Then | 23169 In this case, simply type @kbd{\end @key{RET}} after the asterisk. Then |
| 20353 write the header lines in the Texinfo file and run the @TeX{} command | 23170 write the header lines in the Texinfo file and run the @TeX{} command |
| 20354 again. (Note the use of the backslash, @samp{\}. @TeX{} uses @samp{\} | 23171 again. (Note the use of the backslash, @samp{\}. @TeX{} uses @samp{\} |
| 20355 instead of @samp{@@}; and in this circumstance, you are working | 23172 instead of @samp{@@}; and in this circumstance, you are working |
| 20356 directly with @TeX{}, not with Texinfo.)@refill | 23173 directly with @TeX{}, not with Texinfo.) |
| 20357 | 23174 |
| 20358 @node Using texinfo-show-structure | 23175 @node Using @t{texinfo-show-structure} |
| 20359 @comment node-name, next, previous, up | |
| 20360 @section Using @code{texinfo-show-structure} | 23176 @section Using @code{texinfo-show-structure} |
| 23177 | |
| 20361 @cindex Showing the structure of a file | 23178 @cindex Showing the structure of a file |
| 20362 @findex texinfo-show-structure | 23179 @findex texinfo-show-structure |
| 20363 | 23180 |
| 20364 It is not always easy to keep track of the nodes, chapters, sections, and | 23181 It is not always easy to keep track of the nodes, chapters, sections, and |
| 20365 subsections of a Texinfo file. This is especially true if you are revising | 23182 subsections of a Texinfo file. This is especially true if you are revising |
| 20366 or adding to a Texinfo file that someone else has written.@refill | 23183 or adding to a Texinfo file that someone else has written. |
| 20367 | 23184 |
| 20368 In XEmacs, in Texinfo mode, the @code{texinfo-show-structure} | 23185 In XEmacs, in Texinfo mode, the @code{texinfo-show-structure} |
| 20369 command lists all the lines that begin with the @@-commands that | 23186 command lists all the lines that begin with the @@-commands that |
| 20370 specify the structure: @code{@@chapter}, @code{@@section}, | 23187 specify the structure: @code{@@chapter}, @code{@@section}, |
| 20371 @code{@@appendix}, and so on. With an argument (@w{@kbd{C-u}} | 23188 @code{@@appendix}, and so on. With an argument (@w{@kbd{C-u}} |
| 20372 as prefix argument, if interactive), | 23189 as prefix argument, if interactive), |
| 20373 the command also shows the @code{@@node} lines. The | 23190 the command also shows the @code{@@node} lines. The |
| 20374 @code{texinfo-show-structure} command is bound to @kbd{C-c C-s} in | 23191 @code{texinfo-show-structure} command is bound to @kbd{C-c C-s} in |
| 20375 Texinfo mode, by default.@refill | 23192 Texinfo mode, by default. |
| 20376 | 23193 |
| 20377 The lines are displayed in a buffer called the @samp{*Occur*} buffer, | 23194 The lines are displayed in a buffer called the @samp{*Occur*} buffer, |
| 20378 indented by hierarchical level. For example, here is a part of what was | 23195 indented by hierarchical level. For example, here is a part of what was |
| 20379 produced by running @code{texinfo-show-structure} on this manual:@refill | 23196 produced by running @code{texinfo-show-structure} on this manual: |
| 20380 | 23197 |
| 20381 @example | 23198 @example |
| 20382 @group | 23199 @group |
| 20383 Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\| | 23200 Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\| |
| 20384 unnum\\|major\\|chapheading \\|heading \\|appendix\\)" | 23201 unnum\\|major\\|chapheading \\|heading \\|appendix\\)" |
| 20400 commands respectively. If you move your cursor into the @samp{*Occur*} | 23217 commands respectively. If you move your cursor into the @samp{*Occur*} |
| 20401 window, you can position the cursor over one of the lines and use the | 23218 window, you can position the cursor over one of the lines and use the |
| 20402 @kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to | 23219 @kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to |
| 20403 the corresponding spot in the Texinfo file. @xref{Other Repeating | 23220 the corresponding spot in the Texinfo file. @xref{Other Repeating |
| 20404 Search, , Using Occur, xemacs, XEmacs User's Manual}, for more | 23221 Search, , Using Occur, xemacs, XEmacs User's Manual}, for more |
| 20405 information about @code{occur-mode-goto-occurrence}.@refill | 23222 information about @code{occur-mode-goto-occurrence}. |
| 20406 | 23223 |
| 20407 The first line in the @samp{*Occur*} window describes the @dfn{regular | 23224 The first line in the @samp{*Occur*} window describes the @dfn{regular |
| 20408 expression} specified by @var{texinfo-heading-pattern}. This regular | 23225 expression} specified by @var{texinfo-heading-pattern}. This regular |
| 20409 expression is the pattern that @code{texinfo-show-structure} looks for. | 23226 expression is the pattern that @code{texinfo-show-structure} looks for. |
| 20410 @xref{Regexps, , Using Regular Expressions, xemacs, XEmacs User's Manual}, | 23227 @xref{Regexps, , Using Regular Expressions, xemacs, XEmacs User's Manual}, |
| 20411 for more information.@refill | 23228 for more information. |
| 20412 | 23229 |
| 20413 When you invoke the @code{texinfo-show-structure} command, XEmacs will | 23230 When you invoke the @code{texinfo-show-structure} command, XEmacs will |
| 20414 display the structure of the whole buffer. If you want to see the | 23231 display the structure of the whole buffer. If you want to see the |
| 20415 structure of just a part of the buffer, of one chapter, for example, | 23232 structure of just a part of the buffer, of one chapter, for example, |
| 20416 use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the | 23233 use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the |
| 20417 region. (@xref{Narrowing, , , xemacs, XEmacs User's Manual}.) This is | 23234 region. (@xref{Narrowing, , , xemacs, XEmacs User's Manual}.) This is |
| 20418 how the example used above was generated. (To see the whole buffer | 23235 how the example used above was generated. (To see the whole buffer |
| 20419 again, use @kbd{C-x n w} (@code{widen}).)@refill | 23236 again, use @kbd{C-x n w} (@code{widen}).) |
| 20420 | 23237 |
| 20421 If you call @code{texinfo-show-structure} with a prefix argument by | 23238 If you call @code{texinfo-show-structure} with a prefix argument by |
| 20422 typing @w{@kbd{C-u C-c C-s}}, it will list lines beginning with | 23239 typing @w{@kbd{C-u C-c C-s}}, it will list lines beginning with |
| 20423 @code{@@node} as well as the lines beginning with the @@-sign commands | 23240 @code{@@node} as well as the lines beginning with the @@-sign commands |
| 20424 for @code{@@chapter}, @code{@@section}, and the like.@refill | 23241 for @code{@@chapter}, @code{@@section}, and the like. |
| 20425 | 23242 |
| 20426 You can remind yourself of the structure of a Texinfo file by looking at | 23243 You can remind yourself of the structure of a Texinfo file by looking at |
| 20427 the list in the @samp{*Occur*} window; and if you have mis-named a node | 23244 the list in the @samp{*Occur*} window; and if you have mis-named a node |
| 20428 or left out a section, you can correct the mistake.@refill | 23245 or left out a section, you can correct the mistake. |
| 20429 | 23246 |
| 20430 @node Using occur | 23247 @node Using @t{occur} |
| 20431 @comment node-name, next, previous, up | |
| 20432 @section Using @code{occur} | 23248 @section Using @code{occur} |
| 23249 | |
| 20433 @cindex Occurrences, listing with @code{@@occur} | 23250 @cindex Occurrences, listing with @code{@@occur} |
| 20434 @findex occur | 23251 @findex occur |
| 20435 | 23252 |
| 20436 Sometimes the @code{texinfo-show-structure} command produces too much | 23253 Sometimes the @code{texinfo-show-structure} command produces too much |
| 20437 information. Perhaps you want to remind yourself of the overall structure | 23254 information. Perhaps you want to remind yourself of the overall structure |
| 20438 of a Texinfo file, and are overwhelmed by the detailed list produced by | 23255 of a Texinfo file, and are overwhelmed by the detailed list produced by |
| 20439 @code{texinfo-show-structure}. In this case, you can use the @code{occur} | 23256 @code{texinfo-show-structure}. In this case, you can use the @code{occur} |
| 20440 command directly. To do this, type@refill | 23257 command directly. To do this, type: |
| 20441 | 23258 |
| 20442 @example | 23259 @example |
| 20443 @kbd{M-x occur} | 23260 @kbd{M-x occur} |
| 20444 @end example | 23261 @end example |
| 20445 | 23262 |
| 20446 @noindent | 23263 @noindent |
| 20447 and then, when prompted, type a @dfn{regexp}, a regular expression for | 23264 and then, when prompted, type a @dfn{regexp}, a regular expression for |
| 20448 the pattern you want to match. (@xref{Regexps, , Regular Expressions, | 23265 the pattern you want to match. (@xref{Regexps, , Regular Expressions, |
| 20449 xemacs, XEmacs User's Manual}.) The @code{occur} command works from the | 23266 xemacs, XEmacs User's Manual}.) The @code{occur} command works from |
| 20450 current location of the cursor in the buffer to the end of the buffer. | 23267 the current location of the cursor in the buffer to the end of the |
| 20451 If you want to run @code{occur} on the whole buffer, place the cursor at | 23268 buffer. If you want to run @code{occur} on the whole buffer, place |
| 20452 the beginning of the buffer.@refill | 23269 the cursor at the beginning of the buffer. |
| 20453 | 23270 |
| 20454 For example, to see all the lines that contain the word | 23271 For example, to see all the lines that contain the word |
| 20455 @samp{@@chapter} in them, just type @samp{@@chapter}. This will | 23272 @samp{@@chapter} in them, just type @samp{@@chapter}. This will |
| 20456 produce a list of the chapters. It will also list all the sentences | 23273 produce a list of the chapters. It will also list all the sentences |
| 20457 with @samp{@@chapter} in the middle of the line.@refill | 23274 with @samp{@@chapter} in the middle of the line. |
| 20458 | 23275 |
| 20459 If you want to see only those lines that start with the word | 23276 If you want to see only those lines that start with the word |
| 20460 @samp{@@chapter}, type @samp{^@@chapter} when prompted by | 23277 @samp{@@chapter}, type @samp{^@@chapter} when prompted by |
| 20461 @code{occur}. If you want to see all the lines that end with a word | 23278 @code{occur}. If you want to see all the lines that end with a word |
| 20462 or phrase, end the last word with a @samp{$}; for example, | 23279 or phrase, end the last word with a @samp{$}; for example, |
| 20463 @samp{catching mistakes$}. This can be helpful when you want to see | 23280 @samp{catching mistakes$}. This can be helpful when you want to see |
| 20464 all the nodes that are part of the same chapter or section and | 23281 all the nodes that are part of the same chapter or section and |
| 20465 therefore have the same `Up' pointer.@refill | 23282 therefore have the same `Up' pointer. |
| 20466 | 23283 |
| 20467 @xref{Other Repeating Search, , Using Occur, xemacs, XEmacs User's Manual}, | 23284 @xref{Other Repeating Search, , Using Occur, xemacs, XEmacs User's Manual}, |
| 20468 for more information.@refill | 23285 for more information. |
| 20469 | 23286 |
| 20470 @node Running Info-Validate | 23287 |
| 20471 @comment node-name, next, previous, up | 23288 @node Running @t{Info-validate} |
| 20472 @section Finding Badly Referenced Nodes | 23289 @section Finding Badly Referenced Nodes |
| 23290 | |
| 23291 @anchor{Running Info-Validate}@c old name | |
| 20473 @findex Info-validate | 23292 @findex Info-validate |
| 20474 @cindex Nodes, checking for badly referenced | 23293 @cindex Nodes, checking for badly referenced |
| 20475 @cindex Checking for badly referenced nodes | 23294 @cindex Checking for badly referenced nodes |
| 20476 @cindex Looking for badly referenced nodes | 23295 @cindex Looking for badly referenced nodes |
| 20477 @cindex Finding badly referenced nodes | 23296 @cindex Finding badly referenced nodes |
| 20479 | 23298 |
| 20480 You can use the @code{Info-validate} command to check whether any of | 23299 You can use the @code{Info-validate} command to check whether any of |
| 20481 the `Next', `Previous', `Up' or other node pointers fail to point to a | 23300 the `Next', `Previous', `Up' or other node pointers fail to point to a |
| 20482 node. This command checks that every node pointer points to an | 23301 node. This command checks that every node pointer points to an |
| 20483 existing node. The @code{Info-validate} command works only on Info | 23302 existing node. The @code{Info-validate} command works only on Info |
| 20484 files, not on Texinfo files.@refill | 23303 files, not on Texinfo files. |
| 20485 | 23304 |
| 20486 The @code{makeinfo} program validates pointers automatically, so you | 23305 The @code{makeinfo} program validates pointers automatically, so you |
| 20487 do not need to use the @code{Info-validate} command if you are using | 23306 do not need to use the @code{Info-validate} command if you are using |
| 20488 @code{makeinfo}. You only may need to use @code{Info-validate} if you | 23307 @code{makeinfo}. You only may need to use @code{Info-validate} if you |
| 20489 are unable to run @code{makeinfo} and instead must create an Info file | 23308 are unable to run @code{makeinfo} and instead must create an Info file |
| 20490 using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or | 23309 using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or |
| 20491 if you write an Info file from scratch.@refill | 23310 if you write an Info file from scratch. |
| 20492 | 23311 |
| 20493 @menu | 23312 @menu |
| 20494 * Using Info-validate:: How to run @code{Info-validate}. | 23313 * Using @t{Info-validate}:: How to run @code{Info-validate}. |
| 20495 * Unsplit:: How to create an unsplit file. | 23314 * Unsplit:: How to create an unsplit file. |
| 20496 * Tagifying:: How to tagify a file. | 23315 * Tagifying:: How to tagify a file. |
| 20497 * Splitting:: How to split a file manually. | 23316 * Splitting:: How to split a file manually. |
| 20498 @end menu | 23317 @end menu |
| 20499 | 23318 |
| 20500 @node Using Info-validate | 23319 |
| 20501 @subsection Running @code{Info-validate} | 23320 @node Using @t{Info-validate} |
| 20502 @cindex Running @code{Info-validate} | 23321 @subsection Using @code{Info-validate} |
| 23322 | |
| 23323 @cindex Using @code{Info-validate} | |
| 20503 @cindex Info validating a large file | 23324 @cindex Info validating a large file |
| 20504 @cindex Validating a large file | 23325 @cindex Validating a large file |
| 20505 | 23326 |
| 20506 To use @code{Info-validate}, visit the Info file you wish to check and | 23327 To use @code{Info-validate}, visit the Info file you wish to check and |
| 20507 type:@refill | 23328 type: |
| 20508 | 23329 |
| 20509 @example | 23330 @example |
| 20510 M-x Info-validate | 23331 M-x Info-validate |
| 20511 @end example | 23332 @end example |
| 20512 | 23333 |
| 20513 @noindent | 23334 @noindent |
| 20514 Note that the @code{Info-validate} command requires an upper case | 23335 Note that the @code{Info-validate} command requires an uppercase |
| 20515 `I'. You may also need to create a tag table before running | 23336 `I'@. You may also need to create a tag table before running |
| 20516 @code{Info-validate}. @xref{Tagifying}. | 23337 @code{Info-validate}. @xref{Tagifying}. |
| 20517 | 23338 |
| 20518 If your file is valid, you will receive a message that says ``File appears | 23339 If your file is valid, you will receive a message that says ``File appears |
| 20519 valid''. However, if you have a pointer that does not point to a node, | 23340 valid''. However, if you have a pointer that does not point to a node, |
| 20520 error messages will be displayed in a buffer called @samp{*problems in | 23341 error messages will be displayed in a buffer called @samp{*problems in |
| 20521 info file*}.@refill | 23342 info file*}. |
| 20522 | 23343 |
| 20523 For example, @code{Info-validate} was run on a test file that contained | 23344 For example, @code{Info-validate} was run on a test file that contained |
| 20524 only the first node of this manual. One of the messages said:@refill | 23345 only the first node of this manual. One of the messages said: |
| 20525 | 23346 |
| 20526 @example | 23347 @example |
| 20527 In node "Overview", invalid Next: Texinfo Mode | 23348 In node "Overview", invalid Next: Texinfo Mode |
| 20528 @end example | 23349 @end example |
| 20529 | 23350 |
| 20530 @noindent | 23351 @noindent |
| 20531 This meant that the node called @samp{Overview} had a `Next' pointer that | 23352 This meant that the node called @samp{Overview} had a `Next' pointer that |
| 20532 did not point to anything (which was true in this case, since the test file | 23353 did not point to anything (which was true in this case, since the test file |
| 20533 had only one node in it).@refill | 23354 had only one node in it). |
| 20534 | 23355 |
| 20535 Now suppose we add a node named @samp{Texinfo Mode} to our test case | 23356 Now suppose we add a node named @samp{Texinfo Mode} to our test case |
| 20536 but we do not specify a `Previous' for this node. Then we will get | 23357 but we do not specify a `Previous' for this node. Then we will get |
| 20537 the following error message:@refill | 23358 the following error message: |
| 20538 | 23359 |
| 20539 @example | 23360 @example |
| 20540 In node "Texinfo Mode", should have Previous: Overview | 23361 In node "Texinfo Mode", should have Previous: Overview |
| 20541 @end example | 23362 @end example |
| 20542 | 23363 |
| 20543 @noindent | 23364 @noindent |
| 20544 This is because every `Next' pointer should be matched by a | 23365 This is because every `Next' pointer should be matched by a |
| 20545 `Previous' (in the node where the `Next' points) which points back.@refill | 23366 `Previous' (in the node where the `Next' points) which points back. |
| 20546 | 23367 |
| 20547 @code{Info-validate} also checks that all menu entries and cross references | 23368 @code{Info-validate} also checks that all menu entries and cross references |
| 20548 point to actual nodes.@refill | 23369 point to actual nodes. |
| 20549 | 23370 |
| 20550 @code{Info-validate} requires a tag table and does not work with files | 23371 @code{Info-validate} requires a tag table and does not work with files |
| 20551 that have been split. (The @code{texinfo-format-buffer} command | 23372 that have been split. (The @code{texinfo-format-buffer} command |
| 20552 automatically splits large files.) In order to use @code{Info-validate} | 23373 automatically splits large files.) In order to use @code{Info-validate} |
| 20553 on a large file, you must run @code{texinfo-format-buffer} with an | 23374 on a large file, you must run @code{texinfo-format-buffer} with an |
| 20554 argument so that it does not split the Info file; and you must create a | 23375 argument so that it does not split the Info file; and you must create a |
| 20555 tag table for the unsplit file. | 23376 tag table for the unsplit file. |
| 20556 | 23377 |
| 20557 @node Unsplit | 23378 @node Unsplit |
| 20558 @comment node-name, next, previous, up | |
| 20559 @subsection Creating an Unsplit File | 23379 @subsection Creating an Unsplit File |
| 20560 @cindex Creating an unsplit file | 23380 @cindex Creating an unsplit file |
| 20561 @cindex Unsplit file creation | 23381 @cindex Unsplit file creation |
| 20562 | 23382 |
| 20563 You can run @code{Info-validate} only on a single Info file that has a | 23383 You can run @code{Info-validate} only on a single Info file that has a |
| 20566 (longer than 300,000 bytes or so), you need to run the | 23386 (longer than 300,000 bytes or so), you need to run the |
| 20567 @code{texinfo-format-buffer} or @code{makeinfo-buffer} command in such | 23387 @code{texinfo-format-buffer} or @code{makeinfo-buffer} command in such |
| 20568 a way that it does not create indirect subfiles. You will also need | 23388 a way that it does not create indirect subfiles. You will also need |
| 20569 to create a tag table for the Info file. After you have done this, | 23389 to create a tag table for the Info file. After you have done this, |
| 20570 you can run @code{Info-validate} and look for badly referenced | 23390 you can run @code{Info-validate} and look for badly referenced |
| 20571 nodes.@refill | 23391 nodes. |
| 20572 | 23392 |
| 20573 The first step is to create an unsplit Info file. To prevent | 23393 The first step is to create an unsplit Info file. To prevent |
| 20574 @code{texinfo-format-buffer} from splitting a Texinfo file into | 23394 @code{texinfo-format-buffer} from splitting a Texinfo file into |
| 20575 smaller Info files, give a prefix to the @kbd{M-x | 23395 smaller Info files, give a prefix to the @kbd{M-x |
| 20576 texinfo-format-buffer} command:@refill | 23396 texinfo-format-buffer} command: |
| 20577 | 23397 |
| 20578 @example | 23398 @example |
| 20579 C-u M-x texinfo-format-buffer | 23399 C-u M-x texinfo-format-buffer |
| 20580 @end example | 23400 @end example |
| 20581 | 23401 |
| 20586 C-u C-c C-e C-b | 23406 C-u C-c C-e C-b |
| 20587 @end example | 23407 @end example |
| 20588 | 23408 |
| 20589 @noindent | 23409 @noindent |
| 20590 When you do this, Texinfo will not split the file and will not create | 23410 When you do this, Texinfo will not split the file and will not create |
| 20591 a tag table for it. @refill | 23411 a tag table for it. |
| 20592 @cindex Making a tag table manually | 23412 @cindex Making a tag table manually |
| 20593 @cindex Tag table, making manually | 23413 @cindex Tag table, making manually |
| 20594 | 23414 |
| 20595 @node Tagifying | 23415 @node Tagifying |
| 20596 @subsection Tagifying a File | 23416 @subsection Tagifying a File |
| 20597 | 23417 |
| 20598 After creating an unsplit Info file, you must create a tag table for | 23418 After creating an unsplit Info file, you must create a tag table for |
| 20599 it. Visit the Info file you wish to tagify and type:@refill | 23419 it. Visit the Info file you wish to tagify and type: |
| 20600 | 23420 |
| 20601 @example | 23421 @example |
| 20602 M-x Info-tagify | 23422 M-x Info-tagify |
| 20603 @end example | 23423 @end example |
| 20604 | 23424 |
| 20605 @noindent | 23425 @noindent |
| 20606 (Note the upper case @samp{I} in @code{Info-tagify}.) This creates an | 23426 (Note the uppercase @samp{I} in @code{Info-tagify}.) This creates an |
| 20607 Info file with a tag table that you can validate.@refill | 23427 Info file with a tag table that you can validate. |
| 20608 | 23428 |
| 20609 The third step is to validate the Info file:@refill | 23429 The third step is to validate the Info file: |
| 20610 | 23430 |
| 20611 @example | 23431 @example |
| 20612 M-x Info-validate | 23432 M-x Info-validate |
| 20613 @end example | 23433 @end example |
| 20614 | 23434 |
| 20615 @noindent | 23435 @noindent |
| 20616 (Note the upper case @samp{I} in @code{Info-validate}.) | 23436 (Note the uppercase @samp{I} in @code{Info-validate}.) |
| 20617 In brief, the steps are:@refill | 23437 In brief, the steps are: |
| 20618 | 23438 |
| 20619 @example | 23439 @example |
| 20620 @group | 23440 @group |
| 20621 C-u M-x texinfo-format-buffer | 23441 C-u M-x texinfo-format-buffer |
| 20622 M-x Info-tagify | 23442 M-x Info-tagify |
| 20625 @end example | 23445 @end example |
| 20626 | 23446 |
| 20627 After you have validated the node structure, you can rerun | 23447 After you have validated the node structure, you can rerun |
| 20628 @code{texinfo-format-buffer} in the normal way so it will construct a | 23448 @code{texinfo-format-buffer} in the normal way so it will construct a |
| 20629 tag table and split the file automatically, or you can make the tag | 23449 tag table and split the file automatically, or you can make the tag |
| 20630 table and split the file manually.@refill | 23450 table and split the file manually. |
| 20631 | 23451 |
| 20632 @node Splitting | 23452 @node Splitting |
| 20633 @comment node-name, next, previous, up | |
| 20634 @subsection Splitting a File Manually | 23453 @subsection Splitting a File Manually |
| 20635 @cindex Splitting an Info file manually | 23454 @cindex Splitting an Info file manually |
| 20636 @cindex Info file, splitting manually | 23455 @cindex Info file, splitting manually |
| 20637 | 23456 |
| 20638 You should split a large file or else let the | 23457 You should split a large file or else let the |
| 20639 @code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it | 23458 @code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it |
| 20640 for you automatically. (Generally you will let one of the formatting | 23459 for you automatically. (Generally you will let one of the formatting |
| 20641 commands do this job for you. @xref{Creating an Info File}.)@refill | 23460 commands do this job for you. @xref{Creating an Info File}.) |
| 20642 | 23461 |
| 20643 The split-off files are called the indirect subfiles.@refill | 23462 The split-off files are called the indirect subfiles. |
| 20644 | 23463 |
| 20645 Info files are split to save memory. With smaller files, XEmacs does not | 23464 Info files are split to save memory. With smaller files, XEmacs does not |
| 20646 have make such a large buffer to hold the information.@refill | 23465 have to make such a large buffer to hold the information. |
| 20647 | 23466 |
| 20648 If an Info file has more than 30 nodes, you should also make a tag | 23467 If an Info file has more than 30 nodes, you should also make a tag |
| 20649 table for it. @xref{Using Info-validate}, for information | 23468 table for it. @xref{Using @t{Info-validate}}, for information |
| 20650 about creating a tag table. (Again, tag tables are usually created | 23469 about creating a tag table. (Again, tag tables are usually created |
| 20651 automatically by the formatting command; you only need to create a tag | 23470 automatically by the formatting command; you only need to create a tag |
| 20652 table yourself if you are doing the job manually. Most likely, you | 23471 table yourself if you are doing the job manually. Most likely, you |
| 20653 will do this for a large, unsplit file on which you have run | 23472 will do this for a large, unsplit file on which you have run |
| 20654 @code{Info-validate}.)@refill | 23473 @code{Info-validate}.) |
| 20655 | |
| 20656 @c Info-split is autoloaded in `loaddefs.el' in Emacs 18.51 | |
| 20657 @ignore | |
| 20658 Before running @code{Info-split}, you need to load the @code{info} library | |
| 20659 into XEmacs by giving the command @kbd{M-x load-library @key{RET} info | |
| 20660 @key{RET}}. | |
| 20661 @end ignore | |
| 20662 | 23474 |
| 20663 Visit the Info file you wish to tagify and split and type the two | 23475 Visit the Info file you wish to tagify and split and type the two |
| 20664 commands:@refill | 23476 commands: |
| 20665 | 23477 |
| 20666 @example | 23478 @example |
| 20667 M-x Info-tagify | 23479 M-x Info-tagify |
| 20668 M-x Info-split | 23480 M-x Info-split |
| 20669 @end example | 23481 @end example |
| 20670 | 23482 |
| 20671 @noindent | 23483 @noindent |
| 20672 (Note that the @samp{I} in @samp{Info} is upper case.)@refill | 23484 (Note that the @samp{I} in @samp{Info} is uppercase.) |
| 20673 | 23485 |
| 20674 When you use the @code{Info-split} command, the buffer is modified into a | 23486 When you use the @code{Info-split} command, the buffer is modified into a |
| 20675 (small) Info file which lists the indirect subfiles. This file should be | 23487 (small) Info file which lists the indirect subfiles. This file should be |
| 20676 saved in place of the original visited file. The indirect subfiles are | 23488 saved in place of the original visited file. The indirect subfiles are |
| 20677 written in the same directory the original file is in, with names generated | 23489 written in the same directory the original file is in, with names generated |
| 20678 by appending @samp{-} and a number to the original file name.@refill | 23490 by appending @samp{-} and a number to the original file name. |
| 20679 | 23491 |
| 20680 The primary file still functions as an Info file, but it contains just | 23492 The primary file still functions as an Info file, but it contains just |
| 20681 the tag table and a directory of subfiles.@refill | 23493 the tag table and a directory of subfiles. |
| 20682 | 23494 |
| 20683 | 23495 |
| 20684 @ignore | 23496 @node Info Format Specification |
| 20685 The simple description in the command summary seems sufficient to me | 23497 @appendix Info Format Specification |
| 20686 these days, so ignore this appendix. --karl, 13mar04. | 23498 |
| 20687 | 23499 @cindex Info format specification |
| 20688 @node Refilling Paragraphs | 23500 @cindex Specification of Info format |
| 20689 @appendix Refilling Paragraphs | 23501 @cindex Definition of Info format |
| 20690 @cindex Refilling paragraphs | 23502 |
| 20691 @cindex Filling paragraphs | 23503 Here we describe the technical details of the Info format. |
| 20692 @cindex Paragraphs, filling | 23504 |
| 20693 @findex refill | 23505 This format definition was written some 25 years after the Info format |
| 20694 | 23506 was first devised. So in the event of conflicts between this |
| 20695 The @code{@@refill} command refills and, optionally, indents the first | 23507 definition and actual practice, practice wins. It also assumes some |
| 20696 line of a paragraph.@footnote{Perhaps the command should have been | 23508 general knowledge of Texinfo; it is meant to be a guide for |
| 20697 called the @code{@@refillandindent} command, but @code{@@refill} is | 23509 implementors rather than a rigid technical standard. We often refer |
| 20698 shorter and the name was chosen before indenting was possible.} The | 23510 back to other parts of this manual for examples and definitions, |
| 20699 @code{@@refill} command is no longer important, but we describe it here | 23511 rather than redundantly spelling out every detail. |
| 20700 because you once needed it. You will see it in many old Texinfo | 23512 |
| 20701 files.@refill | 23513 In this formal description, the characters @code{<>*()|=#} are used |
| 20702 | 23514 for the language of the description itself. Other characters are |
| 20703 Without refilling, paragraphs containing long @@-constructs may look | 23515 literal. The formal constructs used are typical: @code{<...>} |
| 20704 bad after formatting because the formatter removes @@-commands and | 23516 indicates a metavariable name, @samp{=} means definition, @samp{*} |
| 20705 shortens some lines more than others. In the past, neither the | 23517 repetition, @samp{?} optional, @samp{()} grouping, @samp{|} |
| 20706 @code{texinfo-format-region} command nor the | 23518 alternation, @samp{#} comment. Exception: @samp{*} at the beginning |
| 20707 @code{texinfo-format-buffer} command refilled paragraphs | 23519 of a line is literal. |
| 20708 automatically. The @code{@@refill} command had to be written at the | 23520 |
| 20709 end of every paragraph to cause these formatters to fill them. (Both | 23521 We specify literal parentheses (those that are part of the Info |
| 20710 @TeX{} and @code{makeinfo} have always refilled paragraphs | 23522 format) with @t{<lparen>} and @t{<rparen>}, meaning the single |
| 20711 automatically.) Now, all the Info formatters automatically fill and | 23523 characters @samp{(} and @samp{)} respectively. |
| 20712 indent those paragraphs that need to be filled and indented.@refill | 23524 |
| 20713 | 23525 Finally, the two-character sequence @samp{^@var{x}} means the single |
| 20714 The @code{@@refill} command causes @code{texinfo-format-region} and | 23526 character @samp{CTRL-@var{x}}, for any @var{x}. |
| 20715 @code{texinfo-format-buffer} to refill a paragraph in the Info file | 23527 |
| 20716 @emph{after} all the other processing has been done. For this reason, | 23528 @menu |
| 20717 you can not use @code{@@refill} with a paragraph containing either | 23529 * General: Info Format General Layout. |
| 20718 @code{@@*} or @code{@@w@{ @dots{} @}} since the refilling action will | 23530 * Text: Info Format Text Constructs. |
| 20719 override those two commands.@refill | 23531 @end menu |
| 20720 | 23532 |
| 20721 The @code{texinfo-format-region} and @code{texinfo-format-buffer} | 23533 |
| 20722 commands now automatically append @code{@@refill} to the end of each | 23534 @node Info Format General Layout |
| 20723 paragraph that should be filled. They do not append @code{@@refill} to | 23535 @section Info Format General Layout |
| 20724 the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}} | 23536 |
| 20725 and therefore do not refill or indent them.@refill | 23537 This section describes the overall layout of Info manuals. |
| 20726 | 23538 |
| 20727 @end ignore | 23539 @menu |
| 23540 * Whole: Info Format Whole Manual. Split vs.@: nonsplit manuals. | |
| 23541 * Preamble: Info Format Preamble. | |
| 23542 * Indirect: Info Format Indirect Tag Table. | |
| 23543 * Tag table: Info Format Tag Table. | |
| 23544 * Local variables: Info Format Local Variables. | |
| 23545 * Regular nodes: Info Format Regular Nodes. | |
| 23546 @end menu | |
| 23547 | |
| 23548 | |
| 23549 @node Info Format Whole Manual | |
| 23550 @subheading Info Format: A Whole Manual | |
| 23551 | |
| 23552 @cindex Nonsplit manuals, Info format of | |
| 23553 @cindex Split manuals, Info format of | |
| 23554 @cindex Whole manual, in Info format | |
| 23555 | |
| 23556 To begin, an Info manual is either @dfn{nonsplit} (contained wholly | |
| 23557 within a single file) or @dfn{split} (across several files). | |
| 23558 | |
| 23559 The syntax for a nonsplit manual is: | |
| 23560 | |
| 23561 @example | |
| 23562 <nonsplit info file> = | |
| 23563 <preamble> | |
| 23564 <node>* | |
| 23565 <tag table> | |
| 23566 (<local variables>)? | |
| 23567 @end example | |
| 23568 | |
| 23569 When split, there is a @dfn{main file}, which contains only pointers | |
| 23570 to the nodes given in other @dfn{subfiles}. The main file looks | |
| 23571 like this: | |
| 23572 | |
| 23573 @example | |
| 23574 <split info main file> = | |
| 23575 <preamble> | |
| 23576 <indirect table> | |
| 23577 <tag table> | |
| 23578 (<local variables>)? | |
| 23579 @end example | |
| 23580 | |
| 23581 The subfiles in a split manual have the following syntax: | |
| 23582 | |
| 23583 @example | |
| 23584 <split info subfile> = | |
| 23585 <preamble> | |
| 23586 <node>* | |
| 23587 @end example | |
| 23588 | |
| 23589 | |
| 23590 @node Info Format Preamble | |
| 23591 @subheading Info Format: Preamble | |
| 23592 | |
| 23593 @cindex Preamble, in Info format | |
| 23594 | |
| 23595 The @t{<preamble>} is text at the beginning of all output files. | |
| 23596 It is not intended to be visible by default in an Info viewer, but | |
| 23597 may be displayed upon user request. | |
| 23598 | |
| 23599 @example | |
| 23600 <preamble> = | |
| 23601 <identification> # "This is FILENAME, produced by ..." | |
| 23602 <copying text> # Expansion of @@copying text. | |
| 23603 <dir entries> # Derived from @@dircategory and @@direntry. | |
| 23604 @end example | |
| 23605 | |
| 23606 These pieces are: | |
| 23607 | |
| 23608 @table @t | |
| 23609 @item <identification line> | |
| 23610 An arbitrary string beginning the output file, followed by a blank | |
| 23611 line. | |
| 23612 | |
| 23613 @item <copying text> | |
| 23614 The expansion of an @code{@@copying} environment, if the manual has | |
| 23615 one (@pxref{@t{@@copying}}). | |
| 23616 | |
| 23617 @item <dir entries> | |
| 23618 The result of any @code{@@dircategory} and @code{@@direntry} | |
| 23619 commands present in the manual (@pxref{Installing Dir Entries}). | |
| 23620 | |
| 23621 @end table | |
| 23622 | |
| 23623 | |
| 23624 @node Info Format Indirect Tag Table | |
| 23625 @subheading Info Format: Indirect Tag Table | |
| 23626 | |
| 23627 @cindex Indirect tag table, in Info format | |
| 23628 | |
| 23629 The indirect table is written to the main file in the case of split | |
| 23630 output only. It specifies the starting byte position of each split | |
| 23631 output file (as a decimal integer): | |
| 23632 | |
| 23633 @example | |
| 23634 <indirect table> = | |
| 23635 ^_ | |
| 23636 Indirect: | |
| 23637 (<filename>: <bytepos>)* | |
| 23638 @end example | |
| 23639 | |
| 23640 The number of preamble bytes written to each output file is included | |
| 23641 in the positions. Neither the preamble nor the size of the top-level | |
| 23642 output file is included. | |
| 23643 | |
| 23644 The first actual node of content will be pointed to by the first | |
| 23645 entry. | |
| 23646 | |
| 23647 Unfortunately, Info-creating programs such as @code{makeinfo} have not | |
| 23648 always implemented these rules perfectly, due to various bugs and | |
| 23649 oversights. Therefore, robust Info viewers should fall back to | |
| 23650 searching ``nearby'' the given position for a node, instead of just | |
| 23651 giving up if the position is not perfectly at a node beginning. | |
| 23652 | |
| 23653 As an example, suppose split output is generated for the GDB manual. | |
| 23654 The top-level file @file{gdb.info} will contain something like this: | |
| 23655 | |
| 23656 @example | |
| 23657 ^_ | |
| 23658 Indirect: | |
| 23659 gdb.info-1: 1878 | |
| 23660 gdb.info-2: 295733 | |
| 23661 ... | |
| 23662 @end example | |
| 23663 | |
| 23664 This tells Info viewers that the first node of the manual occurs at | |
| 23665 byte 1878 (i.e., after the preamble) of the file @file{gdb.info-1}. | |
| 23666 The first node written to @file{gdb.info-2} would start at byte 295733 | |
| 23667 if the subsequent @file{gdb.info-*} files (not including | |
| 23668 @file{gdb.info} files were appended to @file{gdb.info-1}, including | |
| 23669 their preambles. | |
| 23670 | |
| 23671 | |
| 23672 @node Info Format Tag Table | |
| 23673 @subheading Info Format: Tag Table | |
| 23674 | |
| 23675 @cindex Tag table, in Info format | |
| 23676 | |
| 23677 The tag table specifies the starting byte position of each node and anchor | |
| 23678 in the file. It is written in the main output file only, not (in the | |
| 23679 case of split output) any subfiles. | |
| 23680 | |
| 23681 @example | |
| 23682 <tag table> = | |
| 23683 ^_ | |
| 23684 Tag Table: | |
| 23685 <lparen>Indirect<rparen> # this line appears in split output only | |
| 23686 (Node|Ref): <nodeid>^?<bytepos> | |
| 23687 ^_ | |
| 23688 End Tag Table | |
| 23689 @end example | |
| 23690 | |
| 23691 The @samp{(Indirect)} line is the next line after @samp{Tag Table:} | |
| 23692 in the case of split output only. | |
| 23693 | |
| 23694 Each following line defines an identifier as either an anchor or a | |
| 23695 node, as specific. It is an error to define the same identifier both | |
| 23696 ways. For example, @samp{Node: Top^?1647} says that the node named | |
| 23697 @samp{Top} starts at byte 1647 while @samp{Ref: | |
| 23698 Overview-Footnote-1^?30045} says that the anchor named | |
| 23699 @samp{Overview-Footnote-1} starts at byte 30045. | |
| 23700 | |
| 23701 In the case of nonsplit output, the byte positions simply refer to the | |
| 23702 location in the output file. In the case of split output, the byte | |
| 23703 positions refer to an imaginary file created by concatenating all the | |
| 23704 split files (but not the top-level file). See the previous section. | |
| 23705 | |
| 23706 Here is an example: | |
| 23707 | |
| 23708 @example | |
| 23709 ^_ | |
| 23710 Tag Table: | |
| 23711 Node: Top^_89 | |
| 23712 Node: Ch1^_292 | |
| 23713 ^_ | |
| 23714 End Tag Table | |
| 23715 @end example | |
| 23716 | |
| 23717 This specifies a manual with two nodes, `Top' and `Ch1', at byte | |
| 23718 positions 89 and 292 respectively. Because the @samp{(Indirect)} line | |
| 23719 is not present, the manual is not split. | |
| 23720 | |
| 23721 | |
| 23722 @node Info Format Local Variables | |
| 23723 @subheading Info Format: Local Variables | |
| 23724 | |
| 23725 @cindex Local variable section, in Info format | |
| 23726 | |
| 23727 The local variables section is optional and is currently used to give the | |
| 23728 encoding information. It may be augmented in the future. | |
| 23729 | |
| 23730 @example | |
| 23731 <local variables> = | |
| 23732 ^_ | |
| 23733 Local Variables: | |
| 23734 coding: <encoding> | |
| 23735 End: | |
| 23736 @end example | |
| 23737 | |
| 23738 @xref{@t{@@documentencoding}}. | |
| 23739 | |
| 23740 | |
| 23741 @node Info Format Regular Nodes | |
| 23742 @subheading Info Format: Regular Nodes | |
| 23743 | |
| 23744 @cindex Info nodes, in Info format | |
| 23745 | |
| 23746 Regular nodes look like this: | |
| 23747 | |
| 23748 @example | |
| 23749 <node> = | |
| 23750 ^_ | |
| 23751 File: <fn>, Node: <id1>, (Next: <id2>, )? (Prev: <id3>, )? Up: <id4> | |
| 23752 | |
| 23753 <general text, until the next ^_ or end-of-file> | |
| 23754 @end example | |
| 23755 | |
| 23756 The @code{Next} and @code{Prev} pointers are optional. The @code{Up} | |
| 23757 pointer may technically also be absent, although this is most likely the | |
| 23758 case of a wrongly-structured Info manual. At least one space must be | |
| 23759 present after each colon and comma, but any number of spaces are | |
| 23760 ignored. | |
| 23761 | |
| 23762 This @t{<node>} defines @t{<id1>} in file @t{<fn>}, which is typically | |
| 23763 just @samp{manualname} or perhaps @samp{manualname.info}. Each of the | |
| 23764 other references @t{<id2>}, @t{<id3>}, and @t{<id4>} must be defined | |
| 23765 with either @samp{Node} or @samp{Ref} in the @t{<tag table>}. | |
| 23766 | |
| 23767 Conventionally the nodes are arranged to form a tree, but this is not | |
| 23768 a requirement of the format. Each pointer can refer to any defined | |
| 23769 identifier. | |
| 23770 | |
| 23771 Identifiers cannot include periods, commas, colons or parentheses | |
| 23772 (including @@-commands which produce any of these); these can confuse | |
| 23773 Info readers. @xref{Node Line Requirements}. | |
| 23774 | |
| 23775 The @t{<general text>} of the node can include the special constructs | |
| 23776 described next. | |
| 23777 | |
| 23778 | |
| 23779 @node Info Format Text Constructs | |
| 23780 @section Info Format Text Constructs | |
| 23781 | |
| 23782 @cindex Info format text constructs | |
| 23783 @cindex text constructs, Info format | |
| 23784 | |
| 23785 These special Info constructs can appear within the text of a node. | |
| 23786 | |
| 23787 @menu | |
| 23788 * Menu: Info Format Menu. | |
| 23789 * Image: Info Format Image. | |
| 23790 * Printindex: Info Format Printindex. | |
| 23791 * Xref: Info Format Cross Reference. | |
| 23792 @end menu | |
| 23793 | |
| 23794 | |
| 23795 @node Info Format Menu | |
| 23796 @subsection Info Format: Menu | |
| 23797 | |
| 23798 @cindex Menus, in Info format | |
| 23799 | |
| 23800 Conventionally menus appear at the end of nodes, but the Info format | |
| 23801 places no restrictions on their location. | |
| 23802 | |
| 23803 @example | |
| 23804 <menu> = | |
| 23805 * Menu: | |
| 23806 (<menu entry> | <menu comment>)* | |
| 23807 @end example | |
| 23808 | |
| 23809 The parts of a @t{<menu entry>} are described in @ref{Menu Parts}. | |
| 23810 | |
| 23811 A @t{<menu comment>} is any line not beginning with @samp{*} that | |
| 23812 appears either at the beginning of the menu or is separated from a | |
| 23813 menu entry by one or more blank lines. These comments are intended to | |
| 23814 be displayed as part of the menu, as-is (@pxref{Writing a Menu}). | |
| 23815 | |
| 23816 | |
| 23817 @node Info Format Image | |
| 23818 @subsection Info Format: Image | |
| 23819 | |
| 23820 @cindex Images, in Info format | |
| 23821 | |
| 23822 The @code{@@image} command results in the following special directive | |
| 23823 within the Info file (@pxref{Images}): | |
| 23824 | |
| 23825 @example | |
| 23826 <image> = | |
| 23827 ^@@^H[image src="<image file>" | |
| 23828 (text="<txt file contents>")? | |
| 23829 (alt="<alt text>")? | |
| 23830 ^@@^H] | |
| 23831 @end example | |
| 23832 | |
| 23833 The line breaks and indentation in this description are editorial; the | |
| 23834 whitespace between the different parts of the directive in Info files | |
| 23835 is arbitrary. | |
| 23836 | |
| 23837 In the string @t{<image file>}, @t{<txt file contents>} and @t{<alt | |
| 23838 text>}, @samp{"} is quoted as @samp{\"} and @samp{\} is quoted as | |
| 23839 @samp{\\}. The text and alt specifications are optional. | |
| 23840 | |
| 23841 The @t{alt} value serves the same purpose as in HTML: A prose | |
| 23842 description of the image. In text-only displays or speech systems, | |
| 23843 for example, the @t{alt} value may be used instead of displaying the | |
| 23844 (typically graphical) @t{<image file>}. | |
| 23845 | |
| 23846 The @t{<txt file contents>}, if present, should be taken as an ASCII | |
| 23847 representation of the image, and also may be used on a text-only | |
| 23848 display. | |
| 23849 | |
| 23850 The format does not prescribe the choice between displaying the | |
| 23851 @t{<image file>}, the @t{<alt text>} or @t{<txt file contents>}. | |
| 23852 | |
| 23853 | |
| 23854 @node Info Format Printindex | |
| 23855 @subsection Info Format: Printindex | |
| 23856 | |
| 23857 @cindex Indices, in Info format | |
| 23858 | |
| 23859 Indices in Info format are generally written as a menu | |
| 23860 (@pxref{Indices}), but with an additional directive at the beginning | |
| 23861 marking this as an index node: | |
| 23862 | |
| 23863 @example | |
| 23864 <printindex> = | |
| 23865 ^@@^H[index^@@^H] | |
| 23866 * Menu: | |
| 23867 | |
| 23868 <index entry>* | |
| 23869 @end example | |
| 23870 | |
| 23871 The @t{<index entry>} items are similar to normal menu entries, but | |
| 23872 the free-format description is replaced by the line number of where | |
| 23873 the entries occurs in the text: | |
| 23874 | |
| 23875 @example | |
| 23876 <index entry> = | |
| 23877 * <entry text>: <entry node>. <lparen>line <lineno><rparen> | |
| 23878 @end example | |
| 23879 | |
| 23880 @noindent | |
| 23881 The @t{<entry text>} is the index term. The @t{<lineno>} is an | |
| 23882 unsigned integer, given relative to the start of the @t{<entry node>}. | |
| 23883 There may be arbitrary whitespace after the colon and period, as usual | |
| 23884 in menus. Here is an example: | |
| 23885 | |
| 23886 @example | |
| 23887 ^@@^H[index^@@^H] | |
| 23888 * Menu: | |
| 23889 | |
| 23890 * thunder: Weather Phenomena. (line 5) | |
| 23891 @end example | |
| 23892 | |
| 23893 This means that an index entry for `thunder' appears at line 5 of the | |
| 23894 node `Weather Phenomena'. | |
| 23895 | |
| 23896 | |
| 23897 @node Info Format Cross Reference | |
| 23898 @subsection Info Format: Cross Reference | |
| 23899 | |
| 23900 @cindex Cross references, in Info format | |
| 23901 | |
| 23902 A general cross reference in Info format is written as follows: | |
| 23903 | |
| 23904 @example | |
| 23905 <cross-reference> = | |
| 23906 * (N|n)ote (<id>:: | <label>:(<lparen><infofile><rparen>)?<id>(.|,)) | |
| 23907 @end example | |
| 23908 | |
| 23909 Whether @samp{note} or @samp{Note} is used is not significant. | |
| 23910 | |
| 23911 The @samp{<id>::} form indicates a node or anchor reference within the | |
| 23912 current manual. | |
| 23913 | |
| 23914 The longer form indicates a general reference, typically used to refer | |
| 23915 to a node or anchor in a different manual, but possibly to the current | |
| 23916 manual. The @t{<label>} is descriptive text; the optional | |
| 23917 @samp{(<infofile>)} is the filename of the manual being referenced, | |
| 23918 and the @t{<id>} is the node or anchor within that manual, terminated | |
| 23919 by a comma or period. That final punctuation is part of the | |
| 23920 surrounding sentence, and should be displayed. | |
| 23921 | |
| 23922 Here are some examples: | |
| 23923 | |
| 23924 @example | |
| 23925 *note GNU Free Documentation License:: | |
| 23926 *note Tag table: Info Format Tag Table, for details. | |
| 23927 *Note Overview: (make)Top. | |
| 23928 @end example | |
| 23929 | |
| 23930 The first shows the short form, a reference to a node in the current | |
| 23931 manual. | |
| 23932 | |
| 23933 The second also refers to a node in the current manual, namely `Info | |
| 23934 Format Tag Table'; the `Tag table' before the @samp{:} is only a label | |
| 23935 on this particular reference. | |
| 23936 | |
| 23937 The third example refers to the node `Top' in another manual, namely | |
| 23938 @samp{make}, with `Overview' being the label for this cross reference. | |
| 23939 | |
| 23940 @xref{Cross References}. | |
| 23941 | |
| 23942 | |
| 23943 @c The simple description in the command summary seems sufficient to me | |
| 23944 @c these days, so ignore this appendix. --karl, 13mar04. | |
| 23945 @c | |
| 23946 @c @node Refilling Paragraphs | |
| 23947 @c @appendix Refilling Paragraphs | |
| 23948 @c @cindex Refilling paragraphs | |
| 23949 @c @cindex Filling paragraphs | |
| 23950 @c @cindex Paragraphs, filling | |
| 23951 @c @findex refill | |
| 23952 @c | |
| 23953 @c The @code{@@refill} command refills and, optionally, indents the first | |
| 23954 @c line of a paragraph.@footnote{Perhaps the command should have been | |
| 23955 @c called the @code{@@refillandindent} command, but @code{@@refill} is | |
| 23956 @c shorter and the name was chosen before indenting was possible.} The | |
| 23957 @c @code{@@refill} command is no longer important, but we describe it here | |
| 23958 @c because you once needed it. You will see it in many old Texinfo | |
| 23959 @c files. | |
| 23960 @c | |
| 23961 @c Without refilling, paragraphs containing long @@-constructs may look | |
| 23962 @c bad after formatting because the formatter removes @@-commands and | |
| 23963 @c shortens some lines more than others. In the past, neither the | |
| 23964 @c @code{texinfo-format-region} command nor the | |
| 23965 @c @code{texinfo-format-buffer} command refilled paragraphs | |
| 23966 @c automatically. The @code{@@refill} command had to be written at the | |
| 23967 @c end of every paragraph to cause these formatters to fill them. (Both | |
| 23968 @c @TeX{} and @code{makeinfo} have always refilled paragraphs | |
| 23969 @c automatically.) Now, all the Info formatters automatically fill and | |
| 23970 @c indent those paragraphs that need to be filled and indented. | |
| 23971 @c | |
| 23972 @c The @code{@@refill} command causes @code{texinfo-format-region} and | |
| 23973 @c @code{texinfo-format-buffer} to refill a paragraph in the Info file | |
| 23974 @c @emph{after} all the other processing has been done. For this reason, | |
| 23975 @c you can not use @code{@@refill} with a paragraph containing either | |
| 23976 @c @code{@@*} or @code{@@w@{ @dots{} @}} since the refilling action will | |
| 23977 @c override those two commands. | |
| 23978 @c | |
| 23979 @c The @code{texinfo-format-region} and @code{texinfo-format-buffer} | |
| 23980 @c commands now automatically append @code{@@refill} to the end of each | |
| 23981 @c paragraph that should be filled. They do not append @code{@@refill} to | |
| 23982 @c the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}} | |
| 23983 @c and therefore do not refill or indent them. | |
| 20728 | 23984 |
| 20729 | 23985 |
| 20730 @c These are no longer ``new'', and the explanations | 23986 @c These are no longer ``new'', and the explanations |
| 20731 @c are all given elsewhere anyway, I think. --karl, 25apr97. | 23987 @c are all given elsewhere anyway. So ignore the entire appendix. |
| 20732 @c So ignore the entire appendix. | 23988 @c --karl, 25apr97. |
| 20733 @ignore | |
| 20734 @c node New Features, Command and Variable Index, Obtaining TeX, Top | 23989 @c node New Features, Command and Variable Index, Obtaining TeX, Top |
| 20735 @c appendix Second Edition Features | 23990 @c appendix Second Edition Features |
| 20736 | 23991 |
| 20737 @tex | 23992 @c @tex |
| 20738 % Widen the space for the first column so three control-character | 23993 @c % Widen the space for the first column so three control-character % |
| 20739 % strings fit in the first column. Switched back to default .8in | 23994 @c strings fit in the first column. Switched back to default .8in % |
| 20740 % value at end of chapter. | 23995 @c value at end of chapter. \global\tableindent=1.0in |
| 20741 \global\tableindent=1.0in | 23996 @c @end tex |
| 20742 @end tex | 23997 @c |
| 20743 | 23998 @c The second edition of the Texinfo manual describes more than 20 new |
| 20744 The second edition of the Texinfo manual describes more than 20 new | 23999 @c Texinfo mode commands and more than 50 previously undocumented Texinfo |
| 20745 Texinfo mode commands and more than 50 previously undocumented Texinfo | 24000 @c @@-commands. This edition is more than twice the length of the first |
| 20746 @@-commands. This edition is more than twice the length of the first | 24001 @c edition. |
| 20747 edition.@refill | 24002 @c |
| 20748 | 24003 @c Here is a brief description of the new commands. |
| 20749 Here is a brief description of the new commands.@refill | 24004 @c |
| 20750 | 24005 @c @c menu |
| 20751 @c menu | 24006 @c * New Texinfo Mode Commands:: The updating commands are especially useful. |
| 20752 * New Texinfo Mode Commands:: The updating commands are especially useful. | 24007 @c * New Commands:: Many newly described @@-commands. |
| 20753 * New Commands:: Many newly described @@-commands. | 24008 @c @c end menu |
| 20754 @c end menu | 24009 @c |
| 20755 | 24010 @c @c node New Texinfo Mode Commands, New Commands, Obtaining TeX, Obtaining TeX |
| 20756 @c node New Texinfo Mode Commands, New Commands, Obtaining TeX, Obtaining TeX | 24011 @c @c appendixsec New Texinfo Mode Commands |
| 20757 @c appendixsec New Texinfo Mode Commands | 24012 @c |
| 20758 | 24013 @c Texinfo mode provides commands and features especially designed for |
| 20759 Texinfo mode provides commands and features especially designed for | 24014 @c working with Texinfo files. More than 20 new commands have been |
| 20760 working with Texinfo files. More than 20 new commands have been | 24015 @c added, including commands for automatically creating and updating |
| 20761 added, including commands for automatically creating and updating | 24016 @c both nodes and menus. This is a tedious task when done by hand. |
| 20762 both nodes and menus. This is a tedious task when done by hand.@refill | 24017 @c |
| 20763 | 24018 @c The keybindings are intended to be somewhat mnemonic. |
| 20764 The keybindings are intended to be somewhat mnemonic.@refill | 24019 @c |
| 20765 | 24020 @c @c subheading Update all nodes and menus |
| 20766 @c subheading Update all nodes and menus | 24021 @c |
| 20767 | 24022 @c The @code{texinfo-master-menu} command is the primary command: |
| 20768 The @code{texinfo-master-menu} command is the primary command: | 24023 @c |
| 20769 | 24024 @c @table @kbd |
| 20770 @table @kbd | 24025 @c @item C-c C-u m |
| 20771 @item C-c C-u m | 24026 @c @itemx M-x texinfo-master-menu |
| 20772 @itemx M-x texinfo-master-menu | 24027 @c Create or update a master menu. |
| 20773 Create or update a master menu. | 24028 @c With @kbd{C-u} as a prefix argument, |
| 20774 With @kbd{C-u} as a prefix argument, | 24029 @c first create or update all nodes |
| 20775 first create or update all nodes | 24030 @c and regular menus. |
| 20776 and regular menus. | 24031 @c @end table |
| 20777 @end table | 24032 @c |
| 20778 | 24033 @c @c subheading Update Pointers |
| 20779 @c subheading Update Pointers | 24034 @c |
| 20780 | 24035 @c @noindent |
| 20781 @noindent | 24036 @c Create or update `Next', `Previous', and `Up' node pointers. |
| 20782 Create or update `Next', `Previous', and `Up' node pointers.@refill | 24037 @c |
| 20783 | 24038 @c @noindent |
| 20784 @noindent | 24039 @c @xref{Updating Nodes and Menus}. |
| 20785 @xref{Updating Nodes and Menus}. | 24040 @c |
| 20786 | 24041 @c @table @kbd |
| 20787 @table @kbd | 24042 @c @item C-c C-u C-n |
| 20788 @item C-c C-u C-n | 24043 @c @itemx M-x texinfo-update-node |
| 20789 @itemx M-x texinfo-update-node | 24044 @c Update a node. |
| 20790 Update a node. | 24045 @c |
| 20791 | 24046 @c @item C-c C-u C-e |
| 20792 @item C-c C-u C-e | 24047 @c @itemx M-x texinfo-every-node-update |
| 20793 @itemx M-x texinfo-every-node-update | 24048 @c Update every node in the buffer. |
| 20794 Update every node in the buffer. | 24049 @c @end table |
| 20795 @end table | 24050 @c |
| 20796 | 24051 @c @c subheading Update Menus |
| 20797 @c subheading Update Menus | 24052 @c |
| 20798 | 24053 @c @noindent |
| 20799 @noindent | 24054 @c Create or update menus. |
| 20800 Create or update menus.@refill | 24055 @c |
| 20801 | 24056 @c @noindent |
| 20802 @noindent | 24057 @c @xref{Updating Nodes and Menus}. |
| 20803 @xref{Updating Nodes and Menus}. | 24058 @c |
| 20804 | 24059 @c @table @kbd |
| 20805 @table @kbd | 24060 @c @item C-c C-u C-m |
| 20806 @item C-c C-u C-m | 24061 @c @itemx M-x texinfo-make-menu |
| 20807 @itemx M-x texinfo-make-menu | 24062 @c Make or update a menu. |
| 20808 Make or update a menu. | 24063 @c |
| 20809 | 24064 @c @item C-c C-u C-a |
| 20810 @item C-c C-u C-a | 24065 @c @itemx M-x texinfo-all-menus-update |
| 20811 @itemx M-x texinfo-all-menus-update | 24066 @c Make or update all the menus in a buffer. |
| 20812 Make or update all the menus in a buffer. | 24067 @c With @kbd{C-u} as a prefix argument, |
| 20813 With @kbd{C-u} as a prefix argument, | 24068 @c first update all the nodes. |
| 20814 first update all the nodes. | 24069 @c @end table |
| 20815 @end table | 24070 @c |
| 20816 | 24071 @c @c subheading Insert Title as Description |
| 20817 @c subheading Insert Title as Description | 24072 @c |
| 20818 | 24073 @c @noindent |
| 20819 @noindent | 24074 @c Insert a node's chapter or section title in the space for the |
| 20820 Insert a node's chapter or section title in the space for the | 24075 @c description in a menu entry line; position point so you can edit the |
| 20821 description in a menu entry line; position point so you can edit the | 24076 @c insert. (This command works somewhat differently than the other |
| 20822 insert. (This command works somewhat differently than the other | 24077 @c insertion commands, which insert only a predefined string.) |
| 20823 insertion commands, which insert only a predefined string.)@refill | 24078 @c |
| 20824 | 24079 @c @noindent |
| 20825 @noindent | 24080 @c @xref{Inserting, Inserting Frequently Used Commands}. |
| 20826 @xref{Inserting, Inserting Frequently Used Commands}. | 24081 @c |
| 20827 | 24082 @c @table @kbd |
| 20828 @table @kbd | 24083 @c @item C-c C-c C-d |
| 20829 @item C-c C-c C-d | 24084 @c Insert title. |
| 20830 Insert title. | 24085 @c @end table |
| 20831 @end table | 24086 @c |
| 20832 | 24087 @c @c subheading Format for Info |
| 20833 @c subheading Format for Info | 24088 @c |
| 20834 | 24089 @c @noindent |
| 20835 @noindent | 24090 @c Provide keybindings both for the Info formatting commands that are |
| 20836 Provide keybindings both for the Info formatting commands that are | 24091 @c written in Emacs Lisp and for @code{makeinfo} that is written in |
| 20837 written in XEmacs Lisp and for @code{makeinfo} that is written in | 24092 @c C. |
| 20838 C.@refill | 24093 @c |
| 20839 | 24094 @c @noindent |
| 20840 @noindent | 24095 @c @xref{Info Formatting}. |
| 20841 @xref{Info Formatting}. | 24096 @c |
| 20842 | 24097 @c @noindent |
| 20843 @noindent | 24098 @c Use the Emacs lisp @code{texinfo-format@dots{}} commands: |
| 20844 Use the XEmacs lisp @code{texinfo-format@dots{}} commands: | 24099 @c |
| 20845 | 24100 @c @table @kbd |
| 20846 @table @kbd | 24101 @c @item C-c C-e C-r |
| 20847 @item C-c C-e C-r | 24102 @c Format the region. |
| 20848 Format the region. | 24103 @c |
| 20849 | 24104 @c @item C-c C-e C-b |
| 20850 @item C-c C-e C-b | 24105 @c Format the buffer. |
| 20851 Format the buffer. | 24106 @c @end table |
| 20852 @end table | 24107 @c |
| 20853 | 24108 @c @noindent |
| 20854 @noindent | 24109 @c Use @code{makeinfo}: |
| 20855 Use @code{makeinfo}: | 24110 @c |
| 20856 | 24111 @c @table @kbd |
| 20857 @table @kbd | 24112 @c @item C-c C-m C-r |
| 20858 @item C-c C-m C-r | 24113 @c Format the region. |
| 20859 Format the region. | 24114 @c |
| 20860 | 24115 @c @item C-c C-m C-b |
| 20861 @item C-c C-m C-b | 24116 @c Format the buffer. |
| 20862 Format the buffer. | 24117 @c |
| 20863 | 24118 @c @item C-c C-m C-l |
| 20864 @item C-c C-m C-l | 24119 @c Recenter the @code{makeinfo} output buffer. |
| 20865 Recenter the @code{makeinfo} output buffer. | 24120 @c |
| 20866 | 24121 @c @item C-c C-m C-k |
| 20867 @item C-c C-m C-k | 24122 @c Kill the @code{makeinfo} formatting job. |
| 20868 Kill the @code{makeinfo} formatting job. | 24123 @c @end table |
| 20869 @end table | 24124 @c |
| 20870 | 24125 @c @c subheading Typeset and Print |
| 20871 @c subheading Typeset and Print | 24126 @c |
| 20872 | 24127 @c @noindent |
| 20873 @noindent | 24128 @c Typeset and print Texinfo documents from within XEmacs. |
| 20874 Typeset and print Texinfo documents from within XEmacs. | 24129 @c |
| 20875 | 24130 @c @noindent |
| 20876 @noindent | 24131 @c @xref{Printing}. |
| 20877 @xref{Printing}. | 24132 @c |
| 20878 | 24133 @c @table @kbd |
| 20879 @table @kbd | 24134 @c @item C-c C-t C-b |
| 20880 @item C-c C-t C-b | 24135 @c Run @code{texi2dvi} on the buffer. |
| 20881 Run @code{texi2dvi} on the buffer. | 24136 @c |
| 20882 | 24137 @c @item C-c C-t C-r |
| 20883 @item C-c C-t C-r | 24138 @c Run @TeX{} on the region. |
| 20884 Run @TeX{} on the region. | 24139 @c |
| 20885 | 24140 @c @item C-c C-t C-i |
| 20886 @item C-c C-t C-i | 24141 @c Run @code{texindex}. |
| 20887 Run @code{texindex}. | 24142 @c |
| 20888 | 24143 @c @item C-c C-t C-p |
| 20889 @item C-c C-t C-p | 24144 @c Print the DVI file. |
| 20890 Print the DVI file. | 24145 @c |
| 20891 | 24146 @c @item C-c C-t C-q |
| 20892 @item C-c C-t C-q | 24147 @c Show the print queue. |
| 20893 Show the print queue. | 24148 @c |
| 20894 | 24149 @c @item C-c C-t C-d |
| 20895 @item C-c C-t C-d | 24150 @c Delete a job from the print queue. |
| 20896 Delete a job from the print queue. | 24151 @c |
| 20897 | 24152 @c @item C-c C-t C-k |
| 20898 @item C-c C-t C-k | 24153 @c Kill the current @TeX{} formatting job. |
| 20899 Kill the current @TeX{} formatting job. | 24154 @c |
| 20900 | 24155 @c @item C-c C-t C-x |
| 20901 @item C-c C-t C-x | 24156 @c Quit a currently stopped @TeX{} formatting job. |
| 20902 Quit a currently stopped @TeX{} formatting job. | 24157 @c |
| 20903 | 24158 @c @item C-c C-t C-l |
| 20904 @item C-c C-t C-l | 24159 @c Recenter the output buffer. |
| 20905 Recenter the output buffer. | 24160 @c @end table |
| 20906 @end table | 24161 @c |
| 20907 | 24162 @c @c subheading Other Updating Commands |
| 20908 @c subheading Other Updating Commands | 24163 @c |
| 20909 | 24164 @c @noindent |
| 20910 @noindent | 24165 @c The ``other updating commands'' do not have standard keybindings because |
| 20911 The ``other updating commands'' do not have standard keybindings because | 24166 @c they are used less frequently. |
| 20912 they are used less frequently.@refill | 24167 @c |
| 20913 | 24168 @c @noindent |
| 20914 @noindent | 24169 @c @xref{Other Updating Commands}. |
| 20915 @xref{Other Updating Commands}. | 24170 @c |
| 20916 | 24171 @c @table @kbd |
| 20917 @table @kbd | 24172 @c @item M-x texinfo-insert-node-lines |
| 20918 @item M-x texinfo-insert-node-lines | 24173 @c Insert missing @code{@@node} lines using |
| 20919 Insert missing @code{@@node} lines using | 24174 @c section titles as node names. |
| 20920 section titles as node names. | 24175 @c |
| 20921 | 24176 @c @item M-x texinfo-multiple-files-update |
| 20922 @item M-x texinfo-multiple-files-update | 24177 @c Update a multi-file document. |
| 20923 Update a multi-file document. | 24178 @c With a numeric prefix, such as @kbd{C-u 8}, |
| 20924 With a numeric prefix, such as @kbd{C-u 8}, | 24179 @c update @strong{every} pointer and |
| 20925 update @strong{every} pointer and | 24180 @c menu in @strong{all} the files and |
| 20926 menu in @strong{all} the files and | 24181 @c then insert a master menu. |
| 20927 then insert a master menu. | 24182 @c |
| 20928 | 24183 @c @item M-x texinfo-indent-menu-description |
| 20929 @item M-x texinfo-indent-menu-description | 24184 @c Indent descriptions in menus. |
| 20930 Indent descriptions in menus. | 24185 @c |
| 20931 | 24186 @c @item M-x texinfo-sequential-node-update |
| 20932 @item M-x texinfo-sequential-node-update | 24187 @c Insert node pointers in strict sequence. |
| 20933 Insert node pointers in strict sequence. | 24188 @c @end table |
| 20934 @end table | 24189 @c |
| 20935 | 24190 @c @c no.de New Commands, , New Texinfo Mode Commands, Obtaining TeX |
| 20936 @c no.de New Commands, , New Texinfo Mode Commands, Obtaining TeX | 24191 @c @c appendix.sec New Texinfo @@-Commands |
| 20937 @c appendix.sec New Texinfo @@-Commands | 24192 @c |
| 20938 | 24193 @c The second edition of the Texinfo manual describes more than 50 |
| 20939 The second edition of the Texinfo manual describes more than 50 | 24194 @c commands that were not described in the first edition. A third or so |
| 20940 commands that were not described in the first edition. A third or so | 24195 @c of these commands existed in Texinfo but were not documented in the |
| 20941 of these commands existed in Texinfo but were not documented in the | 24196 @c manual; the others are new. Here is a listing, with brief |
| 20942 manual; the others are new. Here is a listing, with brief | 24197 @c descriptions of them: |
| 20943 descriptions of them:@refill | 24198 @c |
| 20944 | 24199 @c @c subheading Indexing |
| 20945 @c subheading Indexing | 24200 @c |
| 20946 | 24201 @c @noindent |
| 20947 @noindent | 24202 @c Create your own index, and merge indices. |
| 20948 Create your own index, and merge indices.@refill | 24203 @c |
| 20949 | 24204 @c @noindent |
| 20950 @noindent | 24205 @c @xref{Indices}. |
| 20951 @xref{Indices}. | 24206 @c |
| 20952 | 24207 @c @table @kbd |
| 20953 @table @kbd | 24208 @c @item @@defindex @var{index-name} |
| 20954 @item @@defindex @var{index-name} | 24209 @c Define a new index and its indexing command. |
| 20955 Define a new index and its indexing command. | 24210 @c See also the @code{@@defcodeindex} command. |
| 20956 See also the @code{@@defcodeindex} command. | 24211 @c |
| 20957 | 24212 @c @c written verbosely to avoid overfull hbox |
| 20958 @c written verbosely to avoid overfull hbox | 24213 @c @item @@synindex @var{from-index} @var{into-index} |
| 20959 @item @@synindex @var{from-index} @var{into-index} | 24214 @c Merge the @var{from-index} index into the @var{into-index} index. |
| 20960 Merge the @var{from-index} index into the @var{into-index} index. | 24215 @c See also the @code{@@syncodeindex} command. |
| 20961 See also the @code{@@syncodeindex} command. | 24216 @c @end table |
| 20962 @end table | 24217 @c |
| 20963 | 24218 @c @c subheading Definitions |
| 20964 @c subheading Definitions | 24219 @c |
| 20965 | 24220 @c @noindent |
| 20966 @noindent | 24221 @c Describe functions, variables, macros, |
| 20967 Describe functions, variables, macros, | 24222 @c commands, user options, special forms, and other such artifacts in a |
| 20968 commands, user options, special forms, and other such artifacts in a | 24223 @c uniform format. |
| 20969 uniform format.@refill | 24224 @c |
| 20970 | 24225 @c @noindent |
| 20971 @noindent | 24226 @c @xref{Definition Commands}. |
| 20972 @xref{Definition Commands}. | 24227 @c |
| 20973 | 24228 @c @table @kbd |
| 20974 @table @kbd | 24229 @c @item @@deffn @var{category} @var{name} @var{arguments}@dots{} |
| 20975 @item @@deffn @var{category} @var{name} @var{arguments}@dots{} | 24230 @c Format a description for functions, interactive |
| 20976 Format a description for functions, interactive | 24231 @c commands, and similar entities. |
| 20977 commands, and similar entities. | 24232 @c |
| 20978 | 24233 @c @item @@defvr, @@defop, @dots{} |
| 20979 @item @@defvr, @@defop, @dots{} | 24234 @c 15 other related commands. |
| 20980 15 other related commands. | 24235 @c @end table |
| 20981 @end table | 24236 @c |
| 20982 | 24237 @c @c subheading Glyphs |
| 20983 @c subheading Glyphs | 24238 @c |
| 20984 | 24239 @c @noindent |
| 20985 @noindent | 24240 @c Indicate the results of evaluation, expansion, |
| 20986 Indicate the results of evaluation, expansion, | 24241 @c printed output, an error message, equivalence of expressions, and the |
| 20987 printed output, an error message, equivalence of expressions, and the | 24242 @c location of point. |
| 20988 location of point.@refill | 24243 @c |
| 20989 | 24244 @c @noindent |
| 20990 @noindent | 24245 @c @xref{Glyphs}. |
| 20991 @xref{Glyphs}. | 24246 @c |
| 20992 | 24247 @c @table @kbd |
| 20993 @table @kbd | 24248 @c @item @@equiv@{@} |
| 20994 @item @@equiv@{@} | 24249 @c @itemx @equiv{} |
| 20995 @itemx @equiv{} | 24250 @c Equivalence: |
| 20996 Equivalence: | 24251 @c |
| 20997 | 24252 @c @item @@error@{@} |
| 20998 @item @@error@{@} | 24253 @c @itemx @error{} |
| 20999 @itemx @error{} | 24254 @c Error message |
| 21000 Error message | 24255 @c |
| 21001 | 24256 @c @item @@expansion@{@} |
| 21002 @item @@expansion@{@} | 24257 @c @itemx @expansion{} |
| 21003 @itemx @expansion{} | 24258 @c Macro expansion |
| 21004 Macro expansion | 24259 @c |
| 21005 | 24260 @c @item @@point@{@} |
| 21006 @item @@point@{@} | 24261 @c @itemx @point{} |
| 21007 @itemx @point{} | 24262 @c Position of point |
| 21008 Position of point | 24263 @c |
| 21009 | 24264 @c @item @@print@{@} |
| 21010 @item @@print@{@} | 24265 @c @itemx @print{} |
| 21011 @itemx @print{} | 24266 @c Printed output |
| 21012 Printed output | 24267 @c |
| 21013 | 24268 @c @item @@result@{@} |
| 21014 @item @@result@{@} | 24269 @c @itemx @result{} |
| 21015 @itemx @result{} | 24270 @c Result of an expression |
| 21016 Result of an expression | 24271 @c @end table |
| 21017 @end table | 24272 @c |
| 21018 | 24273 @c @c subheading Page Headings |
| 21019 @c subheading Page Headings | 24274 @c |
| 21020 | 24275 @c @noindent |
| 21021 @noindent | 24276 @c Customize page headings. |
| 21022 Customize page headings. | 24277 @c |
| 21023 | 24278 @c @noindent |
| 21024 @noindent | 24279 @c @xref{Headings}. |
| 21025 @xref{Headings}. | 24280 @c |
| 21026 | 24281 @c @table @kbd |
| 21027 @table @kbd | 24282 @c @item @@headings @var{on-off-single-double} |
| 21028 @item @@headings @var{on-off-single-double} | 24283 @c Headings on or off, single, or double-sided. |
| 21029 Headings on or off, single, or double-sided. | 24284 @c |
| 21030 | 24285 @c @item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] |
| 21031 @item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] | 24286 @c Footings for even-numbered (left-hand) pages. |
| 21032 Footings for even-numbered (left-hand) pages. | 24287 @c |
| 21033 | 24288 @c @item @@evenheading, @@everyheading, @@oddheading, @dots{} |
| 21034 @item @@evenheading, @@everyheading, @@oddheading, @dots{} | 24289 @c Five other related commands. |
| 21035 Five other related commands. | 24290 @c |
| 21036 | 24291 @c @item @@thischapter |
| 21037 @item @@thischapter | 24292 @c Insert name of chapter and chapter number. |
| 21038 Insert name of chapter and chapter number. | 24293 @c |
| 21039 | 24294 @c @item @@thischaptername, @@thisfile, @@thistitle, @@thispage |
| 21040 @item @@thischaptername, @@thisfile, @@thistitle, @@thispage | 24295 @c Related commands. |
| 21041 Related commands. | 24296 @c @end table |
| 21042 @end table | 24297 @c |
| 21043 | 24298 @c @c subheading Formatting |
| 21044 @c subheading Formatting | 24299 @c |
| 21045 | 24300 @c @noindent |
| 21046 @noindent | 24301 @c Format blocks of text. |
| 21047 Format blocks of text. | 24302 @c |
| 21048 | 24303 @c @noindent |
| 21049 @noindent | 24304 @c @xref{Quotations and Examples}, and@* |
| 21050 @xref{Quotations and Examples}, and@* | 24305 @c @ref{Lists and Tables, , Making Lists and Tables}. |
| 21051 @ref{Lists and Tables, , Making Lists and Tables}. | 24306 @c |
| 21052 | 24307 @c @table @kbd |
| 21053 @table @kbd | 24308 @c @item @@cartouche |
| 21054 @item @@cartouche | 24309 @c Draw rounded box surrounding text (no effect in Info). |
| 21055 Draw rounded box surrounding text (no effect in Info). | 24310 @c |
| 21056 | 24311 @c @item @@enumerate @var{optional-arg} |
| 21057 @item @@enumerate @var{optional-arg} | 24312 @c Enumerate a list with letters or numbers. |
| 21058 Enumerate a list with letters or numbers. | 24313 @c |
| 21059 | 24314 @c @item @@exdent @var{line-of-text} |
| 21060 @item @@exdent @var{line-of-text} | 24315 @c Remove indentation. |
| 21061 Remove indentation. | 24316 @c |
| 21062 | 24317 @c @item @@flushleft |
| 21063 @item @@flushleft | 24318 @c Left justify. |
| 21064 Left justify. | 24319 @c |
| 21065 | 24320 @c @item @@flushright |
| 21066 @item @@flushright | 24321 @c Right justify. |
| 21067 Right justify. | 24322 @c |
| 21068 | 24323 @c @item @@format |
| 21069 @item @@format | 24324 @c Do not narrow nor change font. |
| 21070 Do not narrow nor change font. | 24325 @c |
| 21071 | 24326 @c @item @@ftable @var{formatting-command} |
| 21072 @item @@ftable @var{formatting-command} | 24327 @c @itemx @@vtable @var{formatting-command} |
| 21073 @itemx @@vtable @var{formatting-command} | 24328 @c Two-column table with indexing. |
| 21074 Two-column table with indexing. | 24329 @c |
| 21075 | 24330 @c @item @@lisp |
| 21076 @item @@lisp | 24331 @c For an example of Lisp code. |
| 21077 For an example of Lisp code. | 24332 @c |
| 21078 | 24333 @c @item @@smallexample |
| 21079 @item @@smallexample | 24334 @c @itemx @@smalllisp |
| 21080 @itemx @@smalllisp | 24335 @c Like @@table and @@lisp, but for (originally) @@smallbook. |
| 21081 Like @@table and @@lisp, but for (originally) @@smallbook. | 24336 @c @end table |
| 21082 @end table | 24337 @c |
| 21083 | 24338 @c @c subheading Conditionals |
| 21084 @c subheading Conditionals | 24339 @c |
| 21085 | 24340 @c @noindent |
| 21086 @noindent | 24341 @c Conditionally format text. |
| 21087 Conditionally format text. | 24342 @c |
| 21088 | 24343 @c @noindent |
| 21089 @noindent | 24344 @c @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}. |
| 21090 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill | 24345 @c |
| 21091 | 24346 @c @table @kbd |
| 21092 @table @kbd | 24347 @c @item @@set @var{flag} [@var{string}] |
| 21093 @item @@set @var{flag} [@var{string}] | 24348 @c Set a flag. Optionally, set value |
| 21094 Set a flag. Optionally, set value | 24349 @c of @var{flag} to @var{string}. |
| 21095 of @var{flag} to @var{string}. | 24350 @c |
| 21096 | 24351 @c @item @@clear @var{flag} |
| 21097 @item @@clear @var{flag} | 24352 @c Clear a flag. |
| 21098 Clear a flag. | 24353 @c |
| 21099 | 24354 @c @item @@value@{@var{flag}@} |
| 21100 @item @@value@{@var{flag}@} | 24355 @c Replace with value to which @var{flag} is set. |
| 21101 Replace with value to which @var{flag} is set. | 24356 @c |
| 21102 | 24357 @c @item @@ifset @var{flag} |
| 21103 @item @@ifset @var{flag} | 24358 @c Format, if @var{flag} is set. |
| 21104 Format, if @var{flag} is set. | 24359 @c |
| 21105 | 24360 @c @item @@ifclear @var{flag} |
| 21106 @item @@ifclear @var{flag} | 24361 @c Ignore, if @var{flag} is set. |
| 21107 Ignore, if @var{flag} is set. | 24362 @c @end table |
| 21108 @end table | 24363 @c |
| 21109 | 24364 @c @c subheading @@heading series for Titles |
| 21110 @c subheading @@heading series for Titles | 24365 @c |
| 21111 | 24366 @c @noindent |
| 21112 @noindent | 24367 @c Produce unnumbered headings that do not appear in a table of contents. |
| 21113 Produce unnumbered headings that do not appear in a table of contents. | 24368 @c |
| 21114 | 24369 @c @noindent |
| 21115 @noindent | 24370 @c @xref{Structuring}. |
| 21116 @xref{Structuring}. | 24371 @c |
| 21117 | 24372 @c @table @kbd |
| 21118 @table @kbd | 24373 @c @item @@heading @var{title} |
| 21119 @item @@heading @var{title} | 24374 @c Unnumbered section-like heading not listed |
| 21120 Unnumbered section-like heading not listed | 24375 @c in the table of contents of a printed manual. |
| 21121 in the table of contents of a printed manual. | 24376 @c |
| 21122 | 24377 @c @item @@chapheading, @@majorheading, @@c subheading, @@subsubheading |
| 21123 @item @@chapheading, @@majorheading, @@c subheading, @@subsubheading | 24378 @c Related commands. |
| 21124 Related commands. | 24379 @c @end table |
| 21125 @end table | 24380 @c |
| 21126 | 24381 @c @need 1000 |
| 21127 @need 1000 | 24382 @c @c subheading Font commands |
| 21128 @c subheading Font commands | 24383 @c |
| 21129 | 24384 @c @need 1000 |
| 21130 @need 1000 | 24385 @c @noindent |
| 21131 @noindent | 24386 @c @xref{Smallcaps}, and @* |
| 21132 @xref{Smallcaps}, and @* | 24387 @c @ref{Fonts}. |
| 21133 @ref{Fonts}. | 24388 @c |
| 21134 | 24389 @c @table @kbd |
| 21135 @table @kbd | 24390 @c @item @@r@{@var{text}@} |
| 21136 @item @@r@{@var{text}@} | 24391 @c Print in roman font. |
| 21137 Print in roman font. | 24392 @c |
| 21138 | 24393 @c @item @@sc@{@var{text}@} |
| 21139 @item @@sc@{@var{text}@} | 24394 @c Print in @sc{small caps} font. |
| 21140 Print in @sc{small caps} font. | 24395 @c @end table |
| 21141 @end table | 24396 @c |
| 21142 | 24397 @c @c subheading Miscellaneous |
| 21143 @c subheading Miscellaneous | 24398 @c |
| 21144 | 24399 @c @noindent |
| 21145 @noindent | 24400 @c See @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author} Commands},@* |
| 21146 See @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author} Commands},@* | 24401 @c see @ref{Customized Highlighting},@* |
| 21147 see @ref{Customized Highlighting},@* | 24402 @c see @ref{Overfull hboxes},@* |
| 21148 see @ref{Overfull hboxes},@* | 24403 @c see @ref{Footnotes},@* |
| 21149 see @ref{Footnotes},@* | 24404 @c see @ref{dmn, , Format a Dimension},@* |
| 21150 see @ref{dmn, , Format a Dimension},@* | 24405 @c see @ref{Raise/lower sections, , @code{@@raisesections} and @code{@@lowersections}},@* |
| 21151 see @ref{Raise/lower sections, , @code{@@raisesections} and @code{@@lowersections}},@* | 24406 @c see @ref{math, , @code{@@math}: Inserting Mathematical Expressions}.@* |
| 21152 see @ref{math, , @code{@@math} - Inserting Mathematical Expressions}.@* | 24407 @c see @ref{minus, , Inserting a Minus Sign},@* |
| 21153 see @ref{minus, , Inserting a Minus Sign},@* | 24408 @c see @ref{paragraphindent, , Paragraph Indenting},@* |
| 21154 see @ref{paragraphindent, , Paragraph Indenting},@* | 24409 @c see @ref{Cross Reference Commands},@* |
| 21155 see @ref{Cross Reference Commands},@* | 24410 @c see @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author}}, and@* |
| 21156 see @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author}}, and@* | 24411 @c see @ref{Custom Headings, , How to Make Your Own Headings}. |
| 21157 see @ref{Custom Headings, , How to Make Your Own Headings}. | 24412 @c |
| 21158 | 24413 @c @table @kbd |
| 21159 @table @kbd | 24414 @c @item @@author @var{author} |
| 21160 @item @@author @var{author} | 24415 @c Typeset author's name. |
| 21161 Typeset author's name. | 24416 @c |
| 21162 | 24417 @c @c @item @@definfoenclose @var{new-command}, @var{before}, @var{after}, |
| 21163 @c @item @@definfoenclose @var{new-command}, @var{before}, @var{after}, | 24418 @c @c Define a highlighting command for Info. (Info only.) |
| 21164 @c Define a highlighting command for Info. (Info only.) | 24419 @c |
| 21165 | 24420 @c @item @@finalout |
| 21166 @item @@finalout | 24421 @c Produce cleaner printed output. |
| 21167 Produce cleaner printed output. | 24422 @c |
| 21168 | 24423 @c @item @@footnotestyle @var{end-or-separate} |
| 21169 @item @@footnotestyle @var{end-or-separate} | 24424 @c Specify footnote style, either @samp{end} or @samp{separate}. |
| 21170 Specify footnote style, either @samp{end} or @samp{separate}. | 24425 @c @xref{Footnote Styles}. |
| 21171 @xref{Footnote Styles}. | 24426 @c |
| 21172 | 24427 @c @item @@dmn@{@var{dimension}@} |
| 21173 @item @@dmn@{@var{dimension}@} | 24428 @c Format a dimension. |
| 21174 Format a dimension. | 24429 @c |
| 21175 | 24430 @c @item @@global@@let@var{new-cmd}=@var{existing-cmd} |
| 21176 @item @@global@@let@var{new-cmd}=@var{existing-cmd} | 24431 @c Define a highlighting command for @TeX{}. (@TeX{} only.) |
| 21177 Define a highlighting command for @TeX{}. (@TeX{} only.) | 24432 @c |
| 21178 | 24433 @c @item @@lowersections |
| 21179 @item @@lowersections | 24434 @c Reduce hierarchical level of sectioning commands. |
| 21180 Reduce hierarchical level of sectioning commands. | 24435 @c |
| 21181 | 24436 @c @item @@math@{@var{mathematical-expression}@} |
| 21182 @item @@math@{@var{mathematical-expression}@} | 24437 @c Format a mathematical expression. |
| 21183 Format a mathematical expression. | 24438 @c |
| 21184 | 24439 @c @item @@minus@{@} |
| 21185 @item @@minus@{@} | 24440 @c Generate a minus sign. |
| 21186 Generate a minus sign. | 24441 @c |
| 21187 | 24442 @c @item @@paragraphindent @var{asis-or-number} |
| 21188 @item @@paragraphindent @var{asis-or-number} | 24443 @c Specify amount of paragraph indentation. |
| 21189 Specify paragraph indentation. | 24444 @c |
| 21190 | 24445 @c @item @@raisesections |
| 21191 @item @@raisesections | 24446 @c Raise hierarchical level of sectioning commands. |
| 21192 Raise hierarchical level of sectioning commands. | 24447 @c |
| 21193 | 24448 @c @item @@ref@{@var{node-name}, @r{[}@var{entry}@r{]}, @r{[}@var{topic-or-title}@r{]}, @r{[}@var{info-file}@r{]}, @r{[}@var{manual}@r{]}@} |
| 21194 @item @@ref@{@var{node-name}, @r{[}@var{entry}@r{]}, @r{[}@var{topic-or-title}@r{]}, @r{[}@var{info-file}@r{]}, @r{[}@var{manual}@r{]}@} | 24449 @c Make a reference. In the printed manual, the |
| 21195 Make a reference. In the printed manual, the | 24450 @c reference does not start with the word `see'. |
| 21196 reference does not start with the word `see'. | 24451 @c |
| 21197 | 24452 @c @item @@title @var{title} |
| 21198 @item @@title @var{title} | 24453 @c Typeset @var{title} in the alternative |
| 21199 Typeset @var{title} in the alternative | 24454 @c title page format. |
| 21200 title page format. | 24455 @c |
| 21201 | 24456 @c @item @@subtitle @var{subtitle} |
| 21202 @item @@subtitle @var{subtitle} | 24457 @c Typeset @var{subtitle} in the alternative |
| 21203 Typeset @var{subtitle} in the alternative | 24458 @c title page format. |
| 21204 title page format. | 24459 @c |
| 21205 | 24460 @c @item @@today@{@} |
| 21206 @item @@today@{@} | 24461 @c Insert the current date. |
| 21207 Insert the current date. | 24462 @c @end table |
| 21208 @end table | 24463 @c @tex |
| 21209 @tex | 24464 @c % Switch width of first column of tables back to default value |
| 21210 % Switch width of first column of tables back to default value | 24465 @c \global\tableindent=.8in |
| 21211 \global\tableindent=.8in | 24466 @c @end tex |
| 21212 @end tex | |
| 21213 @end ignore | |
| 21214 | 24467 |
| 21215 | 24468 |
| 21216 @node GNU Free Documentation License | 24469 @node GNU Free Documentation License |
| 21217 @appendix GNU Free Documentation License | 24470 @appendix GNU Free Documentation License |
| 21218 | 24471 |
| 21222 @node Command and Variable Index | 24475 @node Command and Variable Index |
| 21223 @unnumbered Command and Variable Index | 24476 @unnumbered Command and Variable Index |
| 21224 | 24477 |
| 21225 This is an alphabetical list of all the @@-commands, assorted XEmacs Lisp | 24478 This is an alphabetical list of all the @@-commands, assorted XEmacs Lisp |
| 21226 functions, and several variables. To make the list easier to use, the | 24479 functions, and several variables. To make the list easier to use, the |
| 21227 commands are listed without their preceding @samp{@@}.@refill | 24480 commands are listed without their preceding @samp{@@}. |
| 21228 | 24481 |
| 21229 @printindex fn | 24482 @printindex fn |
| 21230 | 24483 |
| 21231 | 24484 |
| 21232 @node General Index | 24485 @node General Index |