| texinfo.txi (93139) | texinfo.txi (100513) |
|---|---|
| 1\input texinfo.tex @c -*-texinfo-*- | 1\input texinfo.tex @c -*-texinfo-*- |
| 2@c $Id: texinfo.txi,v 1.192 2002/03/04 14:52:52 karl Exp $ | 2@c $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $ 3@c Ordinarily Texinfo files have the extension .texi. But texinfo.texi 4@c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi. 5 6@c Everything between the start/end of header lines will be passed by 7@c Emacs's {texinfo,makeinfo}-format region commands. See the `start of 8@c header' node for more info. |
| 3@c %**start of header 4 | 9@c %**start of header 10 |
| 5@c All text is ignored before the setfilename. | 11@c makeinfo and texinfo.tex ignore all text before @setfilename. 12@c 13@c Ordinarily the setfilename argument ends with .info. But 14@c texinfo.info-13 is too long for 14-character filesystems. |
| 6@setfilename texinfo 7 | 15@setfilename texinfo 16 |
| 17@c Automake automatically updates version.texi to @set VERSION and 18@c @set UPDATED to appropriate values. |
|
| 8@include version.texi | 19@include version.texi |
| 9@settitle Texinfo @value{VERSION} | 20@settitle GNU Texinfo @value{VERSION} |
| 10 11@c Define a new index for options. 12@defcodeindex op 13@c Put everything except function (command, in this case) names in one 14@c index (arbitrarily chosen to be the concept index). 15@syncodeindex op cp 16@syncodeindex vr cp 17@syncodeindex pg cp 18 19@footnotestyle separate 20@paragraphindent 2 21@c finalout 22 23@comment %**end of header 24 | 21 22@c Define a new index for options. 23@defcodeindex op 24@c Put everything except function (command, in this case) names in one 25@c index (arbitrarily chosen to be the concept index). 26@syncodeindex op cp 27@syncodeindex vr cp 28@syncodeindex pg cp 29 30@footnotestyle separate 31@paragraphindent 2 32@c finalout 33 34@comment %**end of header 35 |
| 36@copying 37This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}), 38a documentation system that can produce both online information and a 39printed manual from a single source. 40 41Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99, 2000, 01, 02 42Free Software Foundation, Inc. 43 44@quotation 45Permission is granted to copy, distribute and/or modify this document 46under the terms of the GNU Free Documentation License, Version 1.1 or 47any later version published by the Free Software Foundation; with no 48Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' 49and with the Back-Cover Texts as in (a) below. A copy of the license is 50included in the section entitled ``GNU Free Documentation License.'' 51 52(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify 53this GNU Manual, like GNU software. Copies published by the Free 54Software Foundation raise funds for GNU development.'' 55@end quotation 56@end copying 57 |
|
| 25@dircategory Texinfo documentation system 26@direntry 27* Texinfo: (texinfo). The GNU documentation format. 28* install-info: (texinfo)Invoking install-info. Update info/dir entries. 29* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents. 30* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files. 31* makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source. 32@end direntry --- 4 unchanged lines hidden (view full) --- 37@c Set smallbook if printing in smallbook format so the example of the 38@c smallbook font is actually written using smallbook; in bigbook, a kludge 39@c is used for TeX output. Do this through the -t option to texi2dvi, 40@c so this same source can be used for other paper sizes as well. 41@c smallbook 42@c set smallbook 43@c @@clear smallbook 44 | 58@dircategory Texinfo documentation system 59@direntry 60* Texinfo: (texinfo). The GNU documentation format. 61* install-info: (texinfo)Invoking install-info. Update info/dir entries. 62* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents. 63* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files. 64* makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source. 65@end direntry --- 4 unchanged lines hidden (view full) --- 70@c Set smallbook if printing in smallbook format so the example of the 71@c smallbook font is actually written using smallbook; in bigbook, a kludge 72@c is used for TeX output. Do this through the -t option to texi2dvi, 73@c so this same source can be used for other paper sizes as well. 74@c smallbook 75@c set smallbook 76@c @@clear smallbook 77 |
| 45@c If you like blank pages. Can add through texi2dvi -t. | 78@c If you like blank pages, add through texi2dvi -t. |
| 46@c setchapternewpage odd 47 48@c Currently undocumented command, 5 December 1993: 49@c nwnode (Same as node, but no warnings; for `makeinfo'.) 50 | 79@c setchapternewpage odd 80 81@c Currently undocumented command, 5 December 1993: 82@c nwnode (Same as node, but no warnings; for `makeinfo'.) 83 |
| 51@ifinfo 52This file documents Texinfo, a documentation system that can produce 53both online information and a printed manual from a single source. This 54edition is for Texinfo version @value{VERSION}, @value{UPDATED}. | |
| 55 | 84 |
| 56Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99, 2000, 01, 02 57Free Software Foundation, Inc. 58 59Permission is granted to copy, distribute and/or modify this document 60under the terms of the GNU Free Documentation License, Version 1.1 or 61any later version published by the Free Software Foundation; with the 62Invariant Section being ``History'', with no Front-Cover Texts, and with 63no Back-Cover Texts. A copy of the license is included in the section 64entitled ``GNU Free Documentation License''. 65@end ifinfo 66 67 | |
| 68@shorttitlepage Texinfo 69 70@titlepage 71@title Texinfo 72@subtitle The GNU Documentation Format 73@subtitle for Texinfo version @value{VERSION}, @value{UPDATED} 74 75@author Robert J. Chassell 76@author Richard M. Stallman 77 78@c Include the Distribution inside the titlepage so 79@c that headings are turned off. 80 81@page 82@vskip 0pt plus 1filll | 85@shorttitlepage Texinfo 86 87@titlepage 88@title Texinfo 89@subtitle The GNU Documentation Format 90@subtitle for Texinfo version @value{VERSION}, @value{UPDATED} 91 92@author Robert J. Chassell 93@author Richard M. Stallman 94 95@c Include the Distribution inside the titlepage so 96@c that headings are turned off. 97 98@page 99@vskip 0pt plus 1filll |
| 83Copyright @copyright{} 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99, 2000, 01, 02 84Free Software Foundation, Inc. | 100@insertcopying |
| 85 | 101 |
| 86This manual is for Texinfo version @value{VERSION}, @value{UPDATED}. 87 | |
| 88Published by the Free Software Foundation @* 8959 Temple Place Suite 330 @* 90Boston, MA 02111-1307 @* 91USA @* 92ISBN 1-882114-67-1 @c for version 4.0, September 1999. | 102Published by the Free Software Foundation @* 10359 Temple Place Suite 330 @* 104Boston, MA 02111-1307 @* 105USA @* 106ISBN 1-882114-67-1 @c for version 4.0, September 1999. |
| 93@c ISBN 1-882114-65-5 @c for version 3.12, March 1998. 94@c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995 | 107@c ISBN 1-882114-65-5 is for version 3.12, March 1998. |
| 95@c ISBN 1-882114-64-7 is for edition 2.24 of November 1996. | 108@c ISBN 1-882114-64-7 is for edition 2.24 of November 1996. |
| 109@c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995 |
|
| 96 97Cover art by Etienne Suvasa. | 110 111Cover art by Etienne Suvasa. |
| 98 99Permission is granted to copy, distribute and/or modify this document 100under the terms of the GNU Free Documentation License, Version 1.1 or 101any later version published by the Free Software Foundation; with the 102Invariant Section being ``History'', with no Front-Cover Texts, and with 103no Back-Cover Texts. A copy of the license is included in the section 104entitled ``GNU Free Documentation License''. 105 | |
| 106@end titlepage 107 | 112@end titlepage 113 |
| 114 |
|
| 108@summarycontents 109@contents 110 | 115@summarycontents 116@contents 117 |
| 118 |
|
| 111@ifnottex 112@node Top 113@top Texinfo 114 | 119@ifnottex 120@node Top 121@top Texinfo 122 |
| 115Texinfo is a documentation system that uses a single source to produce 116both online information and printed output. | 123@insertcopying |
| 117 118The first part of this master menu lists the major nodes in this Info 119document, including the @@-command and concept indices. The rest of 120the menu lists all the lower level nodes in the document. 121 | 124 125The first part of this master menu lists the major nodes in this Info 126document, including the @@-command and concept indices. The rest of 127the menu lists all the lower level nodes in the document. 128 |
| 122This is Edition @value{VERSION} of the Texinfo manual, updated @value{UPDATED}. | |
| 123@end ifnottex 124 125@menu | 129@end ifnottex 130 131@menu |
| 126* Copying:: Your rights. | 132* Copying Conditions:: Your rights. |
| 127* Overview:: Texinfo in brief. 128* Texinfo Mode:: How to use Texinfo mode. 129* Beginning a File:: What is at the beginning of a Texinfo file? 130* Ending a File:: What is at the end of a Texinfo file? 131* Structuring:: How to create chapters, sections, subsections, 132 appendices, and other parts. 133* Nodes:: How to write nodes. 134* Menus:: How to write menus. --- 11 unchanged lines hidden (view full) --- 146* Conditionals:: How to specify text for either @TeX{} or Info. 147* Internationalization:: 148* Defining New Texinfo Commands:: 149* Hardcopy:: How to convert a Texinfo file to a file 150 for printing and how to print that file. 151* Creating and Installing Info Files:: 152* Command List:: All the Texinfo @@-commands. 153* Tips:: Hints on how to write a Texinfo document. | 133* Overview:: Texinfo in brief. 134* Texinfo Mode:: How to use Texinfo mode. 135* Beginning a File:: What is at the beginning of a Texinfo file? 136* Ending a File:: What is at the end of a Texinfo file? 137* Structuring:: How to create chapters, sections, subsections, 138 appendices, and other parts. 139* Nodes:: How to write nodes. 140* Menus:: How to write menus. --- 11 unchanged lines hidden (view full) --- 152* Conditionals:: How to specify text for either @TeX{} or Info. 153* Internationalization:: 154* Defining New Texinfo Commands:: 155* Hardcopy:: How to convert a Texinfo file to a file 156 for printing and how to print that file. 157* Creating and Installing Info Files:: 158* Command List:: All the Texinfo @@-commands. 159* Tips:: Hints on how to write a Texinfo document. |
| 154* Sample Texinfo File:: A sample Texinfo file to look at. | 160* Sample Texinfo Files:: Complete examples, including full texts. |
| 155* Include Files:: How to incorporate other Texinfo files. 156* Headings:: How to write page headings and footings. 157* Catching Mistakes:: How to find formatting mistakes. 158* Refilling Paragraphs:: All about paragraph refilling. 159* Command Syntax:: A description of @@-Command syntax. 160* Obtaining TeX:: How to Obtain @TeX{}. | 161* Include Files:: How to incorporate other Texinfo files. 162* Headings:: How to write page headings and footings. 163* Catching Mistakes:: How to find formatting mistakes. 164* Refilling Paragraphs:: All about paragraph refilling. 165* Command Syntax:: A description of @@-Command syntax. 166* Obtaining TeX:: How to Obtain @TeX{}. |
| 161* Documentation Copying:: The GNU Free Documentation License. | 167* Copying This Manual:: The GNU Free Documentation License. |
| 162* Command and Variable Index:: A menu containing commands and variables. 163* Concept Index:: A menu covering many topics. 164 165@detailmenu 166 --- The Detailed Node Listing --- 167 168Overview of Texinfo 169 --- 27 unchanged lines hidden (view full) --- 197* Updating Requirements:: How to structure a Texinfo file for 198 using the updating command. 199* Other Updating Commands:: How to indent descriptions, insert 200 missing nodes lines, and update 201 nodes in sequence. 202 203Beginning a Texinfo File 204 | 168* Command and Variable Index:: A menu containing commands and variables. 169* Concept Index:: A menu covering many topics. 170 171@detailmenu 172 --- The Detailed Node Listing --- 173 174Overview of Texinfo 175 --- 27 unchanged lines hidden (view full) --- 203* Updating Requirements:: How to structure a Texinfo file for 204 using the updating command. 205* Other Updating Commands:: How to indent descriptions, insert 206 missing nodes lines, and update 207 nodes in sequence. 208 209Beginning a Texinfo File 210 |
| 205* Four Parts:: Four parts begin a Texinfo file. 206* Sample Beginning:: Here is a sample beginning for a Texinfo file. 207* Header:: The very beginning of a Texinfo file. 208* Info Summary and Permissions:: Summary and copying permissions for Info. | 211* Sample Beginning:: A sample beginning for a Texinfo file. 212* Texinfo File Header:: 213* Document Permissions:: |
| 209* Titlepage & Copyright Page:: Creating the title and copyright pages. 210* The Top Node:: Creating the `Top' node and master menu. | 214* Titlepage & Copyright Page:: Creating the title and copyright pages. 215* The Top Node:: Creating the `Top' node and master menu. |
| 216* Global Document Commands:: |
|
| 211* Software Copying Permissions:: Ensure that you and others continue to | 217* Software Copying Permissions:: Ensure that you and others continue to |
| 212 have the right to use and share software. | 218 have the right to use and share software. |
| 213 | 219 |
| 214The Texinfo File Header | 220Texinfo File Header |
| 215 216* First Line:: The first line of a Texinfo file. 217* Start of Header:: Formatting a region requires this. 218* setfilename:: Tell Info the name of the Info file. 219* settitle:: Create a title for the printed work. | 221 222* First Line:: The first line of a Texinfo file. 223* Start of Header:: Formatting a region requires this. 224* setfilename:: Tell Info the name of the Info file. 225* settitle:: Create a title for the printed work. |
| 220* documentdescription:: Document summary for the HTML output. 221* setchapternewpage:: Start chapters on right-hand pages. 222* paragraphindent:: Specify paragraph indentation. 223* exampleindent:: Specify environment indentation. | |
| 224* End of Header:: Formatting a region requires this. 225 | 226* End of Header:: Formatting a region requires this. 227 |
| 226The Title and Copyright Pages | 228Document Permissions |
| 227 | 229 |
| 230* copying:: Declare the document's copying permissions. 231* insertcopying:: Where to insert the permissions. 232 233Title and Copyright Pages 234 |
|
| 228* titlepage:: Create a title for the printed document. 229* titlefont center sp:: The @code{@@titlefont}, @code{@@center}, 230 and @code{@@sp} commands. 231* title subtitle author:: The @code{@@title}, @code{@@subtitle}, 232 and @code{@@author} commands. | 235* titlepage:: Create a title for the printed document. 236* titlefont center sp:: The @code{@@titlefont}, @code{@@center}, 237 and @code{@@sp} commands. 238* title subtitle author:: The @code{@@title}, @code{@@subtitle}, 239 and @code{@@author} commands. |
| 233* Copyright & Permissions:: How to write the copyright notice and | 240* Copyright:: How to write the copyright notice and |
| 234 include copying permissions. 235* end titlepage:: Turn on page headings after the title and 236 copyright pages. 237* headings on off:: An option for turning headings on and off 238 and double or single sided printing. 239 240The `Top' Node and Master Menu 241 | 241 include copying permissions. 242* end titlepage:: Turn on page headings after the title and 243 copyright pages. 244* headings on off:: An option for turning headings on and off 245 and double or single sided printing. 246 247The `Top' Node and Master Menu 248 |
| 242* Title of Top Node:: Sketch what the file is about. 243* Master Menu Parts:: A master menu has three or more parts. | 249* Top Node Example:: 250* Master Menu Parts:: |
| 244 | 251 |
| 252Global Document Commands 253 254* documentdescription:: Document summary for the HTML output. 255* setchapternewpage:: Start chapters on right-hand pages. 256* paragraphindent:: Specify paragraph indentation. 257* exampleindent:: Specify environment indentation. 258 |
|
| 245Ending a Texinfo File 246 247* Printing Indices & Menus:: How to print an index in hardcopy and 248 generate index menus in Info. 249* Contents:: How to create a table of contents. 250* File End:: How to mark the end of a file. 251 252Chapter Structuring --- 23 unchanged lines hidden (view full) --- 276The @code{@@node} Command 277 278* Node Names:: How to choose node and pointer names. 279* Writing a Node:: How to write an @code{@@node} line. 280* Node Line Tips:: Keep names short. 281* Node Line Requirements:: Keep names unique, without @@-commands. 282* First Node:: How to write a `Top' node. 283* makeinfo top command:: How to use the @code{@@top} command. | 259Ending a Texinfo File 260 261* Printing Indices & Menus:: How to print an index in hardcopy and 262 generate index menus in Info. 263* Contents:: How to create a table of contents. 264* File End:: How to mark the end of a file. 265 266Chapter Structuring --- 23 unchanged lines hidden (view full) --- 290The @code{@@node} Command 291 292* Node Names:: How to choose node and pointer names. 293* Writing a Node:: How to write an @code{@@node} line. 294* Node Line Tips:: Keep names short. 295* Node Line Requirements:: Keep names unique, without @@-commands. 296* First Node:: How to write a `Top' node. 297* makeinfo top command:: How to use the @code{@@top} command. |
| 284* Top Node Summary:: Write a brief description for readers. | |
| 285 286Menus 287 288* Menu Location:: Put a menu in a short node. 289* Writing a Menu:: What is a menu? 290* Menu Parts:: A menu entry has three parts. 291* Less Cluttered Menu Entry:: Two part menu entry. 292* Menu Example:: Two and three part menu entries. --- 26 unchanged lines hidden (view full) --- 319 320Indicating Definitions, Commands, etc. 321 322* Useful Highlighting:: Highlighting provides useful information. 323* code:: Indicating program code. 324* kbd:: Showing keyboard input. 325* key:: Specifying keys. 326* samp:: A literal sequence of characters. | 298 299Menus 300 301* Menu Location:: Put a menu in a short node. 302* Writing a Menu:: What is a menu? 303* Menu Parts:: A menu entry has three parts. 304* Less Cluttered Menu Entry:: Two part menu entry. 305* Menu Example:: Two and three part menu entries. --- 26 unchanged lines hidden (view full) --- 332 333Indicating Definitions, Commands, etc. 334 335* Useful Highlighting:: Highlighting provides useful information. 336* code:: Indicating program code. 337* kbd:: Showing keyboard input. 338* key:: Specifying keys. 339* samp:: A literal sequence of characters. |
| 327* verb:: A verbatim sequence of characters. | 340* verb:: A verbatim sequence of characters. |
| 328* var:: Indicating metasyntactic variables. 329* env:: Indicating environment variables. 330* file:: Indicating file names. 331* command:: Indicating command names. 332* option:: Indicating option names. 333* dfn:: Specifying definitions. 334* cite:: Referring to books not in the Info system. 335* acronym:: Indicating acronyms. --- 7 unchanged lines hidden (view full) --- 343* Fonts:: Various font commands for printed output. 344 345Quotations and Examples 346 347* Block Enclosing Commands:: Different constructs for different purposes. 348* quotation:: Writing a quotation. 349* example:: Writing an example in a fixed-width font. 350* verbatim:: Writing a verbatim example. | 341* var:: Indicating metasyntactic variables. 342* env:: Indicating environment variables. 343* file:: Indicating file names. 344* command:: Indicating command names. 345* option:: Indicating option names. 346* dfn:: Specifying definitions. 347* cite:: Referring to books not in the Info system. 348* acronym:: Indicating acronyms. --- 7 unchanged lines hidden (view full) --- 356* Fonts:: Various font commands for printed output. 357 358Quotations and Examples 359 360* Block Enclosing Commands:: Different constructs for different purposes. 361* quotation:: Writing a quotation. 362* example:: Writing an example in a fixed-width font. 363* verbatim:: Writing a verbatim example. |
| 351* verbatiminclude:: Including a file verbatim. | 364* verbatiminclude:: Including a file verbatim. |
| 352* lisp:: Illustrating Lisp code. 353* small:: Forms for @code{@@smallbook}. 354* display:: Writing an example in the current font. 355* format:: Writing an example without narrowed margins. 356* exdent:: Undo indentation on a line. 357* flushleft & flushright:: Pushing text flush left or flush right. 358* noindent:: Preventing paragraph indentation. 359* cartouche:: Drawing rounded rectangles around examples. --- 171 unchanged lines hidden (view full) --- 531* pagesizes:: How to print with customized page sizes. 532* Cropmarks and Magnification:: How to print marks to indicate the size 533 of pages and how to print scaled up output. 534* PDF Output:: Portable Document Format output. 535 536Creating and Installing Info Files 537 538* Creating an Info File:: | 365* lisp:: Illustrating Lisp code. 366* small:: Forms for @code{@@smallbook}. 367* display:: Writing an example in the current font. 368* format:: Writing an example without narrowed margins. 369* exdent:: Undo indentation on a line. 370* flushleft & flushright:: Pushing text flush left or flush right. 371* noindent:: Preventing paragraph indentation. 372* cartouche:: Drawing rounded rectangles around examples. --- 171 unchanged lines hidden (view full) --- 544* pagesizes:: How to print with customized page sizes. 545* Cropmarks and Magnification:: How to print marks to indicate the size 546 of pages and how to print scaled up output. 547* PDF Output:: Portable Document Format output. 548 549Creating and Installing Info Files 550 551* Creating an Info File:: |
| 539* Installing an Info File:: | 552* Installing an Info File:: |
| 540 541Creating an Info File 542 543* makeinfo advantages:: @code{makeinfo} provides better error checking. 544* Invoking makeinfo:: How to run @code{makeinfo} from a shell. 545* makeinfo options:: Specify fill-column and other options. 546* Pointer Validation:: How to check that pointers point somewhere. 547* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs. --- 10 unchanged lines hidden (view full) --- 558* Directory File:: The top level menu for all Info files. 559* New Info File:: Listing a new Info file. 560* Other Info Directories:: How to specify Info files that are 561 located in other directories. 562* Installing Dir Entries:: How to specify what menu entry to add 563 to the Info directory. 564* Invoking install-info:: @code{install-info} options. 565 | 553 554Creating an Info File 555 556* makeinfo advantages:: @code{makeinfo} provides better error checking. 557* Invoking makeinfo:: How to run @code{makeinfo} from a shell. 558* makeinfo options:: Specify fill-column and other options. 559* Pointer Validation:: How to check that pointers point somewhere. 560* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs. --- 10 unchanged lines hidden (view full) --- 571* Directory File:: The top level menu for all Info files. 572* New Info File:: Listing a new Info file. 573* Other Info Directories:: How to specify Info files that are 574 located in other directories. 575* Installing Dir Entries:: How to specify what menu entry to add 576 to the Info directory. 577* Invoking install-info:: @code{install-info} options. 578 |
| 579Sample Texinfo Files 580 581* Short Sample Texinfo File:: 582* GNU Sample Texts:: 583 |
|
| 566Include Files 567 568* Using Include Files:: How to use the @code{@@include} command. 569* texinfo-multiple-files-update:: How to create and update nodes and 570 menus when using included files. 571* Include File Requirements:: What @code{texinfo-multiple-files-update} expects. 572* Sample Include File:: A sample outer file with included files 573 within it; and a sample included file. --- 18 unchanged lines hidden (view full) --- 592 593Finding Badly Referenced Nodes 594 595* Using Info-validate:: How to run @code{Info-validate}. 596* Unsplit:: How to create an unsplit file. 597* Tagifying:: How to tagify a file. 598* Splitting:: How to split a file manually. 599 | 584Include Files 585 586* Using Include Files:: How to use the @code{@@include} command. 587* texinfo-multiple-files-update:: How to create and update nodes and 588 menus when using included files. 589* Include File Requirements:: What @code{texinfo-multiple-files-update} expects. 590* Sample Include File:: A sample outer file with included files 591 within it; and a sample included file. --- 18 unchanged lines hidden (view full) --- 610 611Finding Badly Referenced Nodes 612 613* Using Info-validate:: How to run @code{Info-validate}. 614* Unsplit:: How to create an unsplit file. 615* Tagifying:: How to tagify a file. 616* Splitting:: How to split a file manually. 617 |
| 618Copying This Manual 619 620* GNU Free Documentation License:: License for copying this manual. 621 |
|
| 600@end detailmenu 601@end menu 602 603@c Reward readers for getting to the end of the menu :). 604@c Contributed by Arnold Robbins. 605@quotation 606Documentation is like sex: when it is good, it is very, very good; and 607when it is bad, it is better than nothing. 608---Dick Brandon 609@end quotation 610 611 | 622@end detailmenu 623@end menu 624 625@c Reward readers for getting to the end of the menu :). 626@c Contributed by Arnold Robbins. 627@quotation 628Documentation is like sex: when it is good, it is very, very good; and 629when it is bad, it is better than nothing. 630---Dick Brandon 631@end quotation 632 633 |
| 612@node Copying | 634@node Copying Conditions |
| 613@unnumbered Texinfo Copying Conditions 614@cindex Copying conditions 615@cindex Conditions for copying Texinfo 616 617The programs currently being distributed that relate to Texinfo include 618@code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}. 619These programs are @dfn{free}; this means that everyone is free to use 620them and free to redistribute them on a free basis. The Texinfo-related --- 19 unchanged lines hidden (view full) --- 640out that there is no warranty for the programs that relate to Texinfo. 641If these programs are modified by someone else and passed on, we want 642their recipients to know that what they have is not what we distributed, 643so that any problems introduced by others will not reflect on our 644reputation. 645 646The precise conditions of the licenses for the programs currently being 647distributed that relate to Texinfo are found in the General Public | 635@unnumbered Texinfo Copying Conditions 636@cindex Copying conditions 637@cindex Conditions for copying Texinfo 638 639The programs currently being distributed that relate to Texinfo include 640@code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}. 641These programs are @dfn{free}; this means that everyone is free to use 642them and free to redistribute them on a free basis. The Texinfo-related --- 19 unchanged lines hidden (view full) --- 662out that there is no warranty for the programs that relate to Texinfo. 663If these programs are modified by someone else and passed on, we want 664their recipients to know that what they have is not what we distributed, 665so that any problems introduced by others will not reflect on our 666reputation. 667 668The precise conditions of the licenses for the programs currently being 669distributed that relate to Texinfo are found in the General Public |
| 648Licenses that accompany them. | 670Licenses that accompany them. This manual specifically is covered by 671the GNU Free Documentation License (@pxref{GNU Free Documentation 672License}). |
| 649 650 651@node Overview 652@chapter Overview of Texinfo 653@cindex Overview of Texinfo 654@cindex Texinfo overview 655 656@dfn{Texinfo}@footnote{The first syllable of ``Texinfo'' is pronounced --- 37 unchanged lines hidden (view full) --- 694from @uref{ftp://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide. 695 696@cindex Checklist for bug reports 697For bug reports, please include enough information for the maintainers 698to reproduce the problem. Generally speaking, that means: 699 700@itemize @bullet 701@item the version number of Texinfo and the program(s) or manual(s) involved. | 673 674 675@node Overview 676@chapter Overview of Texinfo 677@cindex Overview of Texinfo 678@cindex Texinfo overview 679 680@dfn{Texinfo}@footnote{The first syllable of ``Texinfo'' is pronounced --- 37 unchanged lines hidden (view full) --- 718from @uref{ftp://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide. 719 720@cindex Checklist for bug reports 721For bug reports, please include enough information for the maintainers 722to reproduce the problem. Generally speaking, that means: 723 724@itemize @bullet 725@item the version number of Texinfo and the program(s) or manual(s) involved. |
| 702@item hardware, operating system, and compiler versions. 703@item any unusual options you gave to @command{configure}. | 726@item hardware and operating system names and versions. |
| 704@item the contents of any input files necessary to reproduce the bug. 705@item a description of the problem and samples of any erroneous output. | 727@item the contents of any input files necessary to reproduce the bug. 728@item a description of the problem and samples of any erroneous output. |
| 729@item any unusual options you gave to @command{configure}. |
|
| 706@item anything else that you think would be helpful. 707@end itemize 708 709When in doubt whether something is needed or not, include it. It's 710better to include too much than to leave out something important. 711 | 730@item anything else that you think would be helpful. 731@end itemize 732 733When in doubt whether something is needed or not, include it. It's 734better to include too much than to leave out something important. 735 |
| 736@cindex Patches, contributing |
|
| 712Patches are most welcome; if possible, please make them with 713@samp{@w{diff -c}} (@pxref{Top,, Overview, diffutils, Comparing and 714Merging Files}) and include @file{ChangeLog} entries (@pxref{Change 715Log,,, emacs, The GNU Emacs Manual}). 716 717When sending patches, if possible please do not encode or split them in 718any way; it's much easier to deal with one plain text message, however 719large, than many small ones. @uref{ftp://ftp.gnu.org/gnu/sharutils/, --- 13 unchanged lines hidden (view full) --- 733indices. From the same Texinfo source file, you can create a 734menu-driven, online Info file with nodes, menus, cross references, and 735indices. You can also create from that same source file an HTML output 736file suitable for use with a web browser, or an XML file. @cite{The GNU 737Emacs Manual} is a good example of a Texinfo file, as is this manual. 738 739To make a printed document, you process a Texinfo source file with the 740@TeX{} typesetting program (but the Texinfo language is very different | 737Patches are most welcome; if possible, please make them with 738@samp{@w{diff -c}} (@pxref{Top,, Overview, diffutils, Comparing and 739Merging Files}) and include @file{ChangeLog} entries (@pxref{Change 740Log,,, emacs, The GNU Emacs Manual}). 741 742When sending patches, if possible please do not encode or split them in 743any way; it's much easier to deal with one plain text message, however 744large, than many small ones. @uref{ftp://ftp.gnu.org/gnu/sharutils/, --- 13 unchanged lines hidden (view full) --- 758indices. From the same Texinfo source file, you can create a 759menu-driven, online Info file with nodes, menus, cross references, and 760indices. You can also create from that same source file an HTML output 761file suitable for use with a web browser, or an XML file. @cite{The GNU 762Emacs Manual} is a good example of a Texinfo file, as is this manual. 763 764To make a printed document, you process a Texinfo source file with the 765@TeX{} typesetting program (but the Texinfo language is very different |
| 741from @TeX{}'s usual language, plain @TeX{}). This creates a DVI file 742that you can typeset and print as a book or report (@pxref{Hardcopy}). | 766and much stricter than @TeX{}'s usual language, plain @TeX{}). This 767creates a DVI file that you can typeset and print as a book or report 768(@pxref{Hardcopy}). |
| 743 744@pindex makeinfo 745To output an Info file, process your Texinfo source with the 746@code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command. 747You can install the result in your Info tree (@pxref{Installing an Info 748File}). 749 750To output an HTML file, run @code{makeinfo --html} on your Texinfo 751source. You can (for example) install the result on your web site. 752 753@cindex Docbook, converting to Texinfo 754@cindex Conversion, from Docbook to Texinfo 755To output an XML file, run @code{makeinfo --xml} on your Texinfo source. | 769 770@pindex makeinfo 771To output an Info file, process your Texinfo source with the 772@code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command. 773You can install the result in your Info tree (@pxref{Installing an Info 774File}). 775 776To output an HTML file, run @code{makeinfo --html} on your Texinfo 777source. You can (for example) install the result on your web site. 778 779@cindex Docbook, converting to Texinfo 780@cindex Conversion, from Docbook to Texinfo 781To output an XML file, run @code{makeinfo --xml} on your Texinfo source. |
| 756To output DocBook, run @code{makeinfo --docbook}. If you want to 757convert from Docbook @emph{to} Texinfo, please see 758@uref{http://docbook2X.sourceforge.net/}. | 782To output DocBook (a particular form of XML), run @code{makeinfo 783--docbook}. If you want to convert from Docbook @emph{to} Texinfo, 784please see @uref{http://docbook2X.sourceforge.net/}. |
| 759 760@cindex Output formats, supporting more 761@cindex SGML-tools output format 762If you are a programmer and would like to contribute to the GNU project 763by implementing additional output formats for Texinfo, that would be 764excellent. But please do not write a separate translator texi2foo for 765your favorite format foo! That is the hard way to do the job, and makes 766extra work in subsequent maintenance, since the Texinfo language is 767continually being enhanced and updated. Instead, the best approach is 768modify @code{makeinfo} to generate the new format, as it does now for | 785 786@cindex Output formats, supporting more 787@cindex SGML-tools output format 788If you are a programmer and would like to contribute to the GNU project 789by implementing additional output formats for Texinfo, that would be 790excellent. But please do not write a separate translator texi2foo for 791your favorite format foo! That is the hard way to do the job, and makes 792extra work in subsequent maintenance, since the Texinfo language is 793continually being enhanced and updated. Instead, the best approach is 794modify @code{makeinfo} to generate the new format, as it does now for |
| 769Info and HTML. | 795Info, plain text, HTML, XML, and DocBook. |
| 770 771@TeX{} works with virtually all printers; Info works with virtually all 772computer terminals; the HTML output works with virtually all web 773browsers. Thus Texinfo can be used by almost any computer user. 774 775@cindex Source file 776A Texinfo source file is a plain @sc{ascii} file containing text and 777@dfn{@@-commands} (words preceded by an @samp{@@}) that tell the --- 14 unchanged lines hidden (view full) --- 792 793@cindex Man page output, not supported 794From time to time, proposals are made to generate traditional Unix man 795pages from Texinfo source. This is not likely to ever be supported, 796because man pages have a very strict conventional format. Merely 797enhancing @command{makeinfo} to output troff format would be 798insufficient. Generating a good man page therefore requires a 799completely different source than the typical Texinfo applications of | 796 797@TeX{} works with virtually all printers; Info works with virtually all 798computer terminals; the HTML output works with virtually all web 799browsers. Thus Texinfo can be used by almost any computer user. 800 801@cindex Source file 802A Texinfo source file is a plain @sc{ascii} file containing text and 803@dfn{@@-commands} (words preceded by an @samp{@@}) that tell the --- 14 unchanged lines hidden (view full) --- 818 819@cindex Man page output, not supported 820From time to time, proposals are made to generate traditional Unix man 821pages from Texinfo source. This is not likely to ever be supported, 822because man pages have a very strict conventional format. Merely 823enhancing @command{makeinfo} to output troff format would be 824insufficient. Generating a good man page therefore requires a 825completely different source than the typical Texinfo applications of |
| 800generating a good user manual or a good reference manual. This makes | 826writing a good user tutorial or a good reference manual. This makes |
| 801generating man pages incompatible with the Texinfo design goal of not 802having to document the same information in different ways for different 803output formats. You might as well just write the man page directly. 804 805@pindex help2man 806@cindex O'Dea, Brendan | 827generating man pages incompatible with the Texinfo design goal of not 828having to document the same information in different ways for different 829output formats. You might as well just write the man page directly. 830 831@pindex help2man 832@cindex O'Dea, Brendan |
| 807If you wish to support man pages, the program @command{help2man} may be 808useful; it generates a traditional man page from the @samp{--help} 809output of a program. In fact, this is currently used to generate man 810pages for the Texinfo programs themselves. It is GNU software written 811by Brendan O'Dea, available from 812@uref{http://www.ozemail.com.au/~bod/help2man.tar.gz}. | 833Man pages still have their place, and if you wish to support them, the 834program @command{help2man} may be useful; it generates a traditional man 835page from the @samp{--help} output of a program. In fact, this is 836currently used to generate man pages for the Texinfo programs 837themselves. It is GNU software written by Brendan O'Dea, available from 838@uref{ftp://ftp.gnu.org/gnu/help2man/}. |
| 813 814 815@node Info Files 816@section Info files 817@cindex Info files 818 819An Info file is a Texinfo file formatted so that the Info documentation 820reading program can operate on it. (@code{makeinfo} 821and @code{texinfo-format-buffer} are two commands that convert a Texinfo file | 839 840 841@node Info Files 842@section Info files 843@cindex Info files 844 845An Info file is a Texinfo file formatted so that the Info documentation 846reading program can operate on it. (@code{makeinfo} 847and @code{texinfo-format-buffer} are two commands that convert a Texinfo file |
| 822into an Info file.)@refill | 848into an Info file.) |
| 823 824Info files are divided into pieces called @dfn{nodes}, each of which 825contains the discussion of one topic. Each node has a name, and 826contains both text for the user to read and pointers to other nodes, 827which are identified by their names. The Info program displays one node 828at a time, and provides commands with which the user can move to other | 849 850Info files are divided into pieces called @dfn{nodes}, each of which 851contains the discussion of one topic. Each node has a name, and 852contains both text for the user to read and pointers to other nodes, 853which are identified by their names. The Info program displays one node 854at a time, and provides commands with which the user can move to other |
| 829related nodes.@refill | 855related nodes. |
| 830 831@ifinfo | 856 857@ifinfo |
| 832@inforef{Top, info, info}, for more information about using Info.@refill | 858@inforef{Top, info, info}, for more information about using Info. |
| 833@end ifinfo 834 835Each node of an Info file may have any number of child nodes that 836describe subtopics of the node's topic. The names of child 837nodes are listed in a @dfn{menu} within the parent node; this 838allows you to use certain Info commands to move to one of the child 839nodes. Generally, an Info file is organized like a book. If a node 840is at the logical level of a chapter, its child nodes are at the level 841of sections; likewise, the child nodes of sections are at the level | 859@end ifinfo 860 861Each node of an Info file may have any number of child nodes that 862describe subtopics of the node's topic. The names of child 863nodes are listed in a @dfn{menu} within the parent node; this 864allows you to use certain Info commands to move to one of the child 865nodes. Generally, an Info file is organized like a book. If a node 866is at the logical level of a chapter, its child nodes are at the level 867of sections; likewise, the child nodes of sections are at the level |
| 842of subsections.@refill | 868of subsections. |
| 843 844All the children of any one parent are linked together in a 845bidirectional chain of `Next' and `Previous' pointers. The `Next' 846pointer provides a link to the next section, and the `Previous' pointer 847provides a link to the previous section. This means that all the nodes 848that are at the level of sections within a chapter are linked together. 849Normally the order in this chain is the same as the order of the 850children in the parent's menu. Each child node records the parent node 851name as its `Up' pointer. The last child has no `Next' pointer, and the 852first child has the parent both as its `Previous' and as its `Up' 853pointer.@footnote{In some documents, the first child has no `Previous' 854pointer. Occasionally, the last child has the node name of the next | 869 870All the children of any one parent are linked together in a 871bidirectional chain of `Next' and `Previous' pointers. The `Next' 872pointer provides a link to the next section, and the `Previous' pointer 873provides a link to the previous section. This means that all the nodes 874that are at the level of sections within a chapter are linked together. 875Normally the order in this chain is the same as the order of the 876children in the parent's menu. Each child node records the parent node 877name as its `Up' pointer. The last child has no `Next' pointer, and the 878first child has the parent both as its `Previous' and as its `Up' 879pointer.@footnote{In some documents, the first child has no `Previous' 880pointer. Occasionally, the last child has the node name of the next |
| 855following higher level node as its `Next' pointer.}@refill | 881following higher level node as its `Next' pointer.} |
| 856 857The book-like structuring of an Info file into nodes that correspond 858to chapters, sections, and the like is a matter of convention, not a 859requirement. The `Up', `Previous', and `Next' pointers of a node can 860point to any other nodes, and a menu can contain any other nodes. 861Thus, the node structure can be any directed graph. But it is usually 862more comprehensible to follow a structure that corresponds to the 863structure of chapters and sections in a printed book or report.@refill --- 82 unchanged lines hidden (view full) --- 946file @file{texinfo.tex} that contains information (definitions or 947@dfn{macros}) that @TeX{} uses when it typesets a Texinfo file. 948(@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands 949to @TeX{} commands, which @TeX{} can then process to create the typeset 950document.) @file{texinfo.tex} contains the specifications for printing 951a document. You can get the latest version of @file{texinfo.tex} from 952@uref{ftp://ftp.gnu.org/gnu/texinfo.tex}. 953 | 882 883The book-like structuring of an Info file into nodes that correspond 884to chapters, sections, and the like is a matter of convention, not a 885requirement. The `Up', `Previous', and `Next' pointers of a node can 886point to any other nodes, and a menu can contain any other nodes. 887Thus, the node structure can be any directed graph. But it is usually 888more comprehensible to follow a structure that corresponds to the 889structure of chapters and sections in a printed book or report.@refill --- 82 unchanged lines hidden (view full) --- 972file @file{texinfo.tex} that contains information (definitions or 973@dfn{macros}) that @TeX{} uses when it typesets a Texinfo file. 974(@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands 975to @TeX{} commands, which @TeX{} can then process to create the typeset 976document.) @file{texinfo.tex} contains the specifications for printing 977a document. You can get the latest version of @file{texinfo.tex} from 978@uref{ftp://ftp.gnu.org/gnu/texinfo.tex}. 979 |
| 954Most often, documents are printed on 8.5 inch by 11 inch pages 955(216@dmn{mm} by 280@dmn{mm}; this is the default size), but you can also 956print for 7 inch by 9.25 inch pages (178@dmn{mm} by 235@dmn{mm}; the 957@code{@@smallbook} size) or on A4 or A5 size paper (@code{@@afourpaper}, 958@code{@@afivepaper}). (@xref{smallbook, , Printing ``Small'' Books}. 959Also, see @ref{A4 Paper, ,Printing on A4 Paper}.) | 980In the United States, documents are most often printed on 8.5 inch by 11 981inch pages (216@dmn{mm} by 280@dmn{mm}); this is the default size. But 982you can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by 983235@dmn{mm}, the @code{@@smallbook} size; or on A4 or A5 size paper 984(@code{@@afourpaper}, @code{@@afivepaper}). (@xref{smallbook, , 985Printing ``Small'' Books}. Also, see @ref{A4 Paper, ,Printing on A4 986Paper}.) |
| 960 961By changing the parameters in @file{texinfo.tex}, you can change the 962size of the printed document. In addition, you can change the style in 963which the printed document is formatted; for example, you can change the 964sizes and fonts used, the amount of indentation for each paragraph, the 965degree to which words are hyphenated, and the like. By changing the 966specifications, you can make a book look dignified, old and serious, or | 987 988By changing the parameters in @file{texinfo.tex}, you can change the 989size of the printed document. In addition, you can change the style in 990which the printed document is formatted; for example, you can change the 991sizes and fonts used, the amount of indentation for each paragraph, the 992degree to which words are hyphenated, and the like. By changing the 993specifications, you can make a book look dignified, old and serious, or |
| 967light-hearted, young and cheery.@refill | 994light-hearted, young and cheery. |
| 968 969@TeX{} is freely distributable. It is written in a superset of Pascal 970called WEB and can be compiled either in Pascal or (by using a 971conversion program that comes with the @TeX{} distribution) in C. 972(@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information 973about @TeX{}.)@refill 974 975@TeX{} is very powerful and has a great many features. Because a 976Texinfo file must be able to present information both on a 977character-only terminal in Info form and in a typeset book, the | 995 996@TeX{} is freely distributable. It is written in a superset of Pascal 997called WEB and can be compiled either in Pascal or (by using a 998conversion program that comes with the @TeX{} distribution) in C. 999(@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information 1000about @TeX{}.)@refill 1001 1002@TeX{} is very powerful and has a great many features. Because a 1003Texinfo file must be able to present information both on a 1004character-only terminal in Info form and in a typeset book, the |
| 978formatting commands that Texinfo supports are necessarily 979limited.@refill | 1005formatting commands that Texinfo supports are necessarily limited. |
| 980 981To get a copy of @TeX{}, see 982@ref{Obtaining TeX, , How to Obtain @TeX{}}. 983 984 | 1006 1007To get a copy of @TeX{}, see 1008@ref{Obtaining TeX, , How to Obtain @TeX{}}. 1009 1010 |
| 985@node Formatting Commands, Conventions, Printed Books, Overview | 1011@node Formatting Commands |
| 986@section @@-commands 987@cindex @@-commands 988@cindex Formatting commands 989 990In a Texinfo file, the commands that tell @TeX{} how to typeset the 991printed manual and tell @code{makeinfo} and 992@code{texinfo-format-buffer} how to create an Info file are preceded 993by @samp{@@}; they are called @dfn{@@-commands}. For example, 994@code{@@node} is the command to indicate a node and @code{@@chapter} 995is the command to indicate the start of a chapter.@refill 996 997@quotation 998@strong{Please note:} All the @@-commands, with the exception of the | 1012@section @@-commands 1013@cindex @@-commands 1014@cindex Formatting commands 1015 1016In a Texinfo file, the commands that tell @TeX{} how to typeset the 1017printed manual and tell @code{makeinfo} and 1018@code{texinfo-format-buffer} how to create an Info file are preceded 1019by @samp{@@}; they are called @dfn{@@-commands}. For example, 1020@code{@@node} is the command to indicate a node and @code{@@chapter} 1021is the command to indicate the start of a chapter.@refill 1022 1023@quotation 1024@strong{Please note:} All the @@-commands, with the exception of the |
| 999@code{@@TeX@{@}} command, must be written entirely in lower 1000case.@refill | 1025@code{@@TeX@{@}} command, must be written entirely in lower case. |
| 1001@end quotation 1002 1003The Texinfo @@-commands are a strictly limited set of constructs. The 1004strict limits make it possible for Texinfo files to be understood both 1005by @TeX{} and by the code that converts them into Info files. You can 1006display Info files on any terminal that displays alphabetic and 1007numeric characters. Similarly, you can print the output generated by 1008@TeX{} on a wide variety of printers.@refill --- 53 unchanged lines hidden (view full) --- 1062 1063As you gain experience with Texinfo, you will rapidly learn how to 1064write the different commands: the different ways to write commands 1065make it easier to write and read Texinfo files than if all commands 1066followed exactly the same syntax. (For details about @@-command 1067syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill 1068 1069 | 1026@end quotation 1027 1028The Texinfo @@-commands are a strictly limited set of constructs. The 1029strict limits make it possible for Texinfo files to be understood both 1030by @TeX{} and by the code that converts them into Info files. You can 1031display Info files on any terminal that displays alphabetic and 1032numeric characters. Similarly, you can print the output generated by 1033@TeX{} on a wide variety of printers.@refill --- 53 unchanged lines hidden (view full) --- 1087 1088As you gain experience with Texinfo, you will rapidly learn how to 1089write the different commands: the different ways to write commands 1090make it easier to write and read Texinfo files than if all commands 1091followed exactly the same syntax. (For details about @@-command 1092syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill 1093 1094 |
| 1070@node Conventions, Comments, Formatting Commands, Overview | 1095@node Conventions |
| 1071@section General Syntactic Conventions 1072@cindex General syntactic conventions 1073@cindex Syntactic conventions 1074@cindex Conventions, syntactic 1075 1076This section describes the general conventions used in all Texinfo documents. 1077 1078@itemize @bullet 1079@item 1080All printable @sc{ascii} characters except @samp{@@}, @samp{@{} and 1081@samp{@}} can appear in a Texinfo file and stand for themselves. | 1096@section General Syntactic Conventions 1097@cindex General syntactic conventions 1098@cindex Syntactic conventions 1099@cindex Conventions, syntactic 1100 1101This section describes the general conventions used in all Texinfo documents. 1102 1103@itemize @bullet 1104@item 1105All printable @sc{ascii} characters except @samp{@@}, @samp{@{} and 1106@samp{@}} can appear in a Texinfo file and stand for themselves. |
| 1082@samp{@@} is the escape character which introduces commands. 1083@samp{@{} and @samp{@}} should be used only to surround arguments to 1084certain commands. To put one of these special characters into the 1085document, put an @samp{@@} character in front of it, like this: 1086@samp{@@@@}, @samp{@@@{}, and @samp{@@@}}.@refill | 1107@samp{@@} is the escape character which introduces commands, while 1108@samp{@{} and @samp{@}} are used to surround arguments to certain 1109commands. To put one of these special characters into the document, put 1110an @samp{@@} character in front of it, like this: @samp{@@@@}, 1111@samp{@@@{}, and @samp{@@@}}. |
| 1087 1088@item | 1112 1113@item |
| 1089@ifinfo | |
| 1090It is customary in @TeX{} to use doubled single-quote characters to | 1114It is customary in @TeX{} to use doubled single-quote characters to |
| 1091begin and end quotations: ` ` and ' ' (but without a space between the 1092two single-quote characters). This convention should be followed in 1093Texinfo files. @TeX{} converts doubled single-quote characters to 1094left- and right-hand doubled quotation marks and Info converts doubled 1095single-quote characters to @sc{ascii} double-quotes: ` ` and ' ' to " .@refill 1096@end ifinfo 1097@iftex 1098It is customary in @TeX{} to use doubled single-quote characters to 1099begin and end quotations: @w{@t{ `` }} and @w{@t{ '' }}. This | 1115begin and end quotations: @w{@t{`@w{}`@dots{}'@w{}'}}. This |
| 1100convention should be followed in Texinfo files. @TeX{} converts | 1116convention should be followed in Texinfo files. @TeX{} converts |
| 1101doubled single-quote characters to left- and right-hand doubled 1102quotation marks, ``like this'', and Info converts doubled single-quote 1103characters to @sc{ascii} double-quotes: @w{@t{ `` }} and 1104@w{@t{ '' }} to @w{@t{ " }}.@refill | 1117two single quotes to left- and right-hand doubled 1118quotation marks, 1119@c this comes out as "like this" in Info, of course, which is just confusing. 1120@iftex 1121``like this'', |
| 1105@end iftex | 1122@end iftex |
| 1123and Info converts doubled single-quote characters to @sc{ascii} 1124double-quotes: @w{@t{`@w{}`@dots{}'@w{}'}} becomes @w{@t{"@dots{}"}}. |
|
| 1106 1107@item 1108Use three hyphens in a row, @samp{---}, for a dash---like this. In 1109@TeX{}, a single or double hyphen produces a printed dash that is 1110shorter than the usual typeset dash. Info reduces three hyphens to two 1111for display on the screen. 1112 1113@item 1114To prevent a paragraph from being indented in the printed manual, put 1115the command @code{@@noindent} on a line by itself before the | 1125 1126@item 1127Use three hyphens in a row, @samp{---}, for a dash---like this. In 1128@TeX{}, a single or double hyphen produces a printed dash that is 1129shorter than the usual typeset dash. Info reduces three hyphens to two 1130for display on the screen. 1131 1132@item 1133To prevent a paragraph from being indented in the printed manual, put 1134the command @code{@@noindent} on a line by itself before the |
| 1116paragraph.@refill | 1135paragraph. |
| 1117 1118@item 1119If you mark off a region of the Texinfo file with the @code{@@iftex} 1120and @w{@code{@@end iftex}} commands, that region will appear only in 1121the printed copy; in that region, you can use certain commands | 1136 1137@item 1138If you mark off a region of the Texinfo file with the @code{@@iftex} 1139and @w{@code{@@end iftex}} commands, that region will appear only in 1140the printed copy; in that region, you can use certain commands |
| 1122borrowed from plain @TeX{} that you cannot use in Info. Likewise, if 1123you mark off a region with the @code{@@ifinfo} and @code{@@end ifinfo} 1124commands, that region will appear only in the Info file; in that 1125region, you can use Info commands that you cannot use in @TeX{}. 1126Similarly for @code{@@ifhtml @dots{} @@end ifhtml}, 1127@code{@@ifnothtml @dots{} @@end ifnothtml}, 1128@code{@@ifnotinfo @dots{} @@end ifnotinfo}, 1129@code{@@ifnottex @dots{} @@end ifnottex}. 1130@xref{Conditionals}. | 1141borrowed from plain @TeX{} that you cannot use in Info. Conversely, 1142text surrounded by @code{@@ifnottex} and @code{@@end ifnottex} will 1143appear in all output formats @emph{except} @TeX{}. 1144 1145Each of the other output formats (@code{html}, @code{info}, 1146@code{plaintext}) have an analogous pair of commands. @xref{Conditionals}. |
| 1131@end itemize 1132 1133@cindex Tabs; don't use! 1134@quotation | 1147@end itemize 1148 1149@cindex Tabs; don't use! 1150@quotation |
| 1135@strong{Caution:} Do not use tabs in a Texinfo file (except in verbatim 1136modes) ! @TeX{} uses variable-width fonts, which means that it is 1137impractical at best to define a tab to work in all circumstances. | 1151@strong{Caution:} Do not use tab characters in a Texinfo file (except in 1152verbatim modes)! @TeX{} uses variable-width fonts, which means that it 1153is impractical at best to define a tab to work in all circumstances. |
| 1138Consequently, @TeX{} treats tabs like single spaces, and that is not 1139what they look like. Furthermore, @code{makeinfo} does nothing special 1140with tabs, and thus a tab character in your input file may appear | 1154Consequently, @TeX{} treats tabs like single spaces, and that is not 1155what they look like. Furthermore, @code{makeinfo} does nothing special 1156with tabs, and thus a tab character in your input file may appear |
| 1141differently in the output, for example, in an indented example. | 1157differently in the output, for example, in indented text. |
| 1142 1143@noindent 1144To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple 1145spaces when you press the @key{TAB} key. 1146 1147@noindent 1148Also, you can run @code{untabify} in Emacs to convert tabs in a region 1149to multiple spaces. 1150@end quotation 1151 1152 | 1158 1159@noindent 1160To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple 1161spaces when you press the @key{TAB} key. 1162 1163@noindent 1164Also, you can run @code{untabify} in Emacs to convert tabs in a region 1165to multiple spaces. 1166@end quotation 1167 1168 |
| 1153@node Comments, Minimum, Conventions, Overview | 1169@node Comments |
| 1154@section Comments 1155 | 1170@section Comments 1171 |
| 1172@cindex Comments 1173@findex comment 1174@findex c @r{(comment)} 1175 |
|
| 1156You can write comments in a Texinfo file that will not appear in 1157either the Info file or the printed manual by using the 1158@code{@@comment} command (which may be abbreviated to @code{@@c}). 1159Such comments are for the person who revises the Texinfo file. All the 1160text on a line that follows either @code{@@comment} or @code{@@c} is a 1161comment; the rest of the line does not appear in either the Info file | 1176You can write comments in a Texinfo file that will not appear in 1177either the Info file or the printed manual by using the 1178@code{@@comment} command (which may be abbreviated to @code{@@c}). 1179Such comments are for the person who revises the Texinfo file. All the 1180text on a line that follows either @code{@@comment} or @code{@@c} is a 1181comment; the rest of the line does not appear in either the Info file |
| 1162or the printed manual. (Often, you can write the @code{@@comment} or 1163@code{@@c} in the middle of a line, and only the text that follows after 1164the @code{@@comment} or @code{@@c} command does not appear; but some 1165commands, such as @code{@@settitle} and @code{@@setfilename}, work on a 1166whole line. You cannot use @code{@@comment} or @code{@@c} in a line 1167beginning with such a command.)@refill 1168@cindex Comments 1169@findex comment 1170@findex c @r{(comment)} | 1182or the printed manual. |
| 1171 | 1183 |
| 1184Often, you can write the @code{@@comment} or @code{@@c} in the middle of 1185a line, and only the text that follows after the @code{@@comment} or 1186@code{@@c} command does not appear; but some commands, such as 1187@code{@@settitle} and @code{@@setfilename}, work on a whole line. You 1188cannot use @code{@@comment} or @code{@@c} in a line beginning with such 1189a command. 1190 1191@cindex Ignored text 1192@cindex Unprocessed text 1193@findex ignore |
|
| 1172You can write long stretches of text that will not appear in either 1173the Info file or the printed manual by using the @code{@@ignore} and 1174@code{@@end ignore} commands. Write each of these commands on a line 1175of its own, starting each command at the beginning of the line. Text 1176between these two commands does not appear in the processed output. 1177You can use @code{@@ignore} and @code{@@end ignore} for writing 1178comments. 1179 | 1194You can write long stretches of text that will not appear in either 1195the Info file or the printed manual by using the @code{@@ignore} and 1196@code{@@end ignore} commands. Write each of these commands on a line 1197of its own, starting each command at the beginning of the line. Text 1198between these two commands does not appear in the processed output. 1199You can use @code{@@ignore} and @code{@@end ignore} for writing 1200comments. 1201 |
| 1180@cindex Ignored text 1181@cindex Unprocessed text 1182@findex ignore 1183@c !!! Perhaps include this comment about ignore and ifset: 1184@ignore | |
| 1185Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or 1186@code{@@ifclear} conditions is ignored in the sense that it will not 1187contribute to the formatted output. However, @TeX{} and makeinfo must | 1202Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or 1203@code{@@ifclear} conditions is ignored in the sense that it will not 1204contribute to the formatted output. However, @TeX{} and makeinfo must |
| 1188still parse the ignored text, in order to understand when to 1189@emph{stop} ignoring text from the source file; that means that you 1190will still get error messages if you have invalid Texinfo markup 1191within ignored text. 1192@end ignore | 1205still parse the ignored text, in order to understand when to @emph{stop} 1206ignoring text from the source file; that means that you may still get 1207error messages if you have invalid Texinfo commands within ignored text. |
| 1193 1194 | 1208 1209 |
| 1195@node Minimum, Six Parts, Comments, Overview | 1210@node Minimum |
| 1196@section What a Texinfo File Must Have 1197@cindex Minimal Texinfo file (requirements) 1198@cindex Must have in Texinfo file 1199@cindex Required in Texinfo file 1200@cindex Texinfo file minimum 1201 | 1211@section What a Texinfo File Must Have 1212@cindex Minimal Texinfo file (requirements) 1213@cindex Must have in Texinfo file 1214@cindex Required in Texinfo file 1215@cindex Texinfo file minimum 1216 |
| 1202By convention, the names of Texinfo files end with one of the 1203extensions @file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}. 1204The longer extension is preferred since it describes more clearly to a 1205human reader the nature of the file. The shorter extensions are for 1206operating systems that cannot handle long file names.@refill | 1217By convention, the namea of a Texinfo file ends with (in order of 1218preference) one of the extensions @file{.texinfo}, @file{.texi}, 1219@file{.txi}, or @file{.tex}. The longer extensions are preferred since 1220they describe more clearly to a human reader the nature of the file. 1221The shorter extensions are for operating systems that cannot handle long 1222file names. |
| 1207 1208In order to be made into a printed manual and an Info file, a Texinfo | 1223 1224In order to be made into a printed manual and an Info file, a Texinfo |
| 1209file @strong{must} begin with lines like this:@refill | 1225file @strong{must} begin with lines like this: |
| 1210 1211@example 1212@group 1213\input texinfo 1214@@setfilename @var{info-file-name} 1215@@settitle @var{name-of-manual} 1216@end group 1217@end example 1218 1219@noindent | 1226 1227@example 1228@group 1229\input texinfo 1230@@setfilename @var{info-file-name} 1231@@settitle @var{name-of-manual} 1232@end group 1233@end example 1234 1235@noindent |
| 1220The contents of the file follow this beginning, and then you @strong{must} end 1221a Texinfo file with a line like this:@refill | 1236The contents of the file follow this beginning, and then you 1237@strong{must} end a Texinfo file with a line like this: |
| 1222 1223@example 1224@@bye 1225@end example 1226 | 1238 1239@example 1240@@bye 1241@end example 1242 |
| 1227@findex input @r{(@TeX{} command)} | 1243@findex \input @r{(raw @TeX{} startup)} |
| 1228@noindent | 1244@noindent |
| 1245Here's an explanation: 1246 1247@itemize @bullet 1248@item |
|
| 1229The @samp{\input texinfo} line tells @TeX{} to use the 1230@file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo 1231@@-commands into @TeX{} typesetting commands. (Note the use of the | 1249The @samp{\input texinfo} line tells @TeX{} to use the 1250@file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo 1251@@-commands into @TeX{} typesetting commands. (Note the use of the |
| 1232backslash, @samp{\}; this is correct for @TeX{}.) The 1233@samp{@@setfilename} line provides a name for the Info file and tells 1234@TeX{} to open auxiliary files. The @samp{@@settitle} line specifies a 1235title for the page headers (or footers) of the printed manual, and the 1236default document description title for the @samp{<head>} in HTML format. | 1252backslash, @samp{\}; this is correct for @TeX{}.) |
| 1237 | 1253 |
| 1254@item 1255The @code{@@setfilename} line provides a name for the Info file and 1256tells @TeX{} to open auxiliary files. @strong{All text before 1257@code{@@setfilename} is ignored!} 1258 1259@item 1260The @code{@@settitle} line specifies a title for the page headers (or 1261footers) of the printed manual, and the default document description for 1262the @samp{<head>} in HTML format. Strictly speaking, @code{@@settitle} 1263is optional---if you don't mind your document being titled `Untitled'. 1264 1265@item |
|
| 1238The @code{@@bye} line at the end of the file on a line of its own tells | 1266The @code{@@bye} line at the end of the file on a line of its own tells |
| 1239the formatters that the file is ended and to stop formatting.@refill | 1267the formatters that the file is ended and to stop formatting. |
| 1240 | 1268 |
| 1241Usually, you will not use quite such a spare format, but will include | 1269@end itemize 1270 1271Typically, you will not use quite such a spare format, but will include |
| 1242mode setting and start-of-header and end-of-header lines at the | 1272mode setting and start-of-header and end-of-header lines at the |
| 1243beginning of a Texinfo file, like this:@refill | 1273beginning of a Texinfo file, like this: |
| 1244 1245@example 1246@group 1247\input texinfo @@c -*-texinfo-*- 1248@@c %**start of header 1249@@setfilename @var{info-file-name} 1250@@settitle @var{name-of-manual} 1251@@c %**end of header 1252@end group 1253@end example 1254 1255@noindent 1256In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into 1257Texinfo mode when you edit the file. 1258 | 1274 1275@example 1276@group 1277\input texinfo @@c -*-texinfo-*- 1278@@c %**start of header 1279@@setfilename @var{info-file-name} 1280@@settitle @var{name-of-manual} 1281@@c %**end of header 1282@end group 1283@end example 1284 1285@noindent 1286In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into 1287Texinfo mode when you edit the file. 1288 |
| 1259The @code{@@c} lines which surround the @samp{@@setfilename} and 1260@samp{@@settitle} lines are optional, but you need them in order to 1261run @TeX{} or Info on just part of the file. (@xref{Start of Header}, 1262for more information.)@refill | 1289The @code{@@c} lines which surround the @code{@@setfilename} and 1290@code{@@settitle} lines are optional, but you need them in order to 1291run @TeX{} or Info on just part of the file. (@xref{Start of Header}.) |
| 1263 | 1292 |
| 1264Furthermore, you will usually provide a Texinfo file with a title 1265page, indices, and the like. But the minimum, which can be useful 1266for short documents, is just the three lines at the beginning and the 1267one line at the end.@refill | 1293Furthermore, you will usually provide a Texinfo file with a title page, 1294indices, and the like, all of which are explained in this manual. But 1295the minimum, which can be useful for short documents, is just the three 1296lines at the beginning and the one line at the end. |
| 1268 | 1297 |
| 1269@node Six Parts, Short Sample, Minimum, Overview 1270@comment node-name, next, previous, up | 1298 1299@node Six Parts |
| 1271@section Six Parts of a Texinfo File 1272 | 1300@section Six Parts of a Texinfo File 1301 |
| 1273Generally, a Texinfo file contains more than the minimal 1274beginning and end---it usually contains six parts:@refill | 1302Generally, a Texinfo file contains more than the minimal beginning and 1303end described in the previous section---it usually contains the six 1304parts listed below. These are described fully in the following sections. |
| 1275 1276@table @r 1277@item 1. Header | 1305 1306@table @r 1307@item 1. Header |
| 1278The @dfn{Header} names the file, tells @TeX{} which definitions' file to 1279use, and performs other ``housekeeping'' tasks.@refill | 1308The @dfn{Header} names the file, tells @TeX{} which definitions file to 1309use, and other such housekeeping tasks. |
| 1280 | 1310 |
| 1281@item 2. Summary Description and Copyright 1282The @dfn{Summary Description and Copyright} segment describes the document 1283and contains the copyright notice and copying permissions for the Info 1284file. The segment must be enclosed between @code{@@ifinfo} and 1285@code{@@end ifinfo} commands so that the formatters place it only in the Info 1286file.@refill | 1311@item 2. Summary and Copyright 1312The @dfn{Summary and Copyright} segment describes the document and 1313contains the copyright notice and copying permissions. This is done 1314with the @code{@@copying} command. |
| 1287 1288@item 3. Title and Copyright | 1315 1316@item 3. Title and Copyright |
| 1289The @dfn{Title and Copyright} segment contains the title and copyright pages 1290and copying permissions for the printed manual. The segment must be 1291enclosed between @code{@@titlepage} and @code{@@end titlepage} commands. 1292The title and copyright page appear only in the printed @w{manual}.@refill | 1317The @dfn{Title and Copyright} segment contains the title and copyright 1318pages for the printed manual. The segment must be enclosed between 1319@code{@@titlepage} and @code{@@end titlepage} commands. The title and 1320copyright page appear only in the printed manual. |
| 1293 1294@item 4. `Top' Node and Master Menu | 1321 1322@item 4. `Top' Node and Master Menu |
| 1295The @dfn{Master Menu} contains a complete menu of all the nodes in the whole 1296Info file. It appears only in the Info file, in the `Top' node.@refill | 1323The `Top' node starts off the online output; it does not appear in the 1324printed manual. We recommend including the copying permissions here as 1325well as the segments above. And it contains at least a top-level menu 1326listing the chapters, and possibly a @dfn{Master Menu} listing all the 1327nodes in the entire document. |
| 1297 1298@item 5. Body | 1328 1329@item 5. Body |
| 1299The @dfn{Body} of the document may be structured like a traditional book or 1300encyclopedia or it may be free form.@refill | 1330The @dfn{Body} of the document is typically structured like a 1331traditional book or encyclopedia, but it may be free form. |
| 1301 1302@item 6. End | 1332 1333@item 6. End |
| 1303The @dfn{End} contains commands for printing indices and generating 1304the table of contents, and the @code{@@bye} command on a line of its 1305own.@refill | 1334The @dfn{End} segment contains commands for printing indices and 1335generating the table of contents, and the @code{@@bye} command on a line 1336of its own. |
| 1306@end table 1307 | 1337@end table 1338 |
| 1339 |
|
| 1308@node Short Sample 1309@section A Short Sample Texinfo File | 1340@node Short Sample 1341@section A Short Sample Texinfo File |
| 1310@cindex Sample Texinfo file | 1342@cindex Sample Texinfo file, with comments |
| 1311 | 1343 |
| 1312Here is a complete but very short Texinfo file, in six parts. The first 1313three parts of the file, from @samp{\input texinfo} through to 1314@samp{@@end titlepage}, look more intimidating than they are. Most of 1315the material is standard boilerplate; when you write a manual, simply 1316insert the names for your own manual in this segment. (@xref{Beginning a 1317File}.)@refill | 1344Here is a very short but complete Texinfo file, in the six conventional 1345parts enumerated in the previous section, so you can see how Texinfo 1346source appears in practice. The first three parts of the file, from 1347@samp{\input texinfo} through to @samp{@@end titlepage}, look more 1348intimidating than they are: most of the material is standard 1349boilerplate; when writing a manual, you simply change the names as 1350appropriate. |
| 1318 | 1351 |
| 1352@xref{Beginning a File}, for full documentation on the commands listed 1353here. @xref{GNU Sample Texts}, for the full texts to be used in GNU manuals. 1354 |
|
| 1319In the following, the sample text is @emph{indented}; comments on it are | 1355In the following, the sample text is @emph{indented}; comments on it are |
| 1320not. The complete file, without any comments, is shown in 1321@ref{Sample Texinfo File}. | 1356not. The complete file, without interspersed comments, is shown in 1357@ref{Short Sample Texinfo File}. |
| 1322 1323@subheading Part 1: Header 1324 1325@noindent 1326The header does not appear in either the Info file or the 1327printed output. It sets various parameters, including the 1328name of the Info file and the title used in the header. 1329 1330@example 1331@group 1332\input texinfo @@c -*-texinfo-*- 1333@@c %**start of header 1334@@setfilename sample.info | 1358 1359@subheading Part 1: Header 1360 1361@noindent 1362The header does not appear in either the Info file or the 1363printed output. It sets various parameters, including the 1364name of the Info file and the title used in the header. 1365 1366@example 1367@group 1368\input texinfo @@c -*-texinfo-*- 1369@@c %**start of header 1370@@setfilename sample.info |
| 1335@@settitle Sample Document 1336@@setchapternewpage odd | 1371@@settitle Sample Manual 1.0 |
| 1337@@c %**end of header 1338@end group 1339@end example 1340 1341@subheading Part 2: Summary Description and Copyright 1342 1343@noindent | 1372@@c %**end of header 1373@end group 1374@end example 1375 1376@subheading Part 2: Summary Description and Copyright 1377 1378@noindent |
| 1344The summary description and copyright segment does not 1345appear in the printed document. | 1379A real manual includes more text here, according to the license under 1380which it is distributed. @xref{GNU Sample Texts}. |
| 1346 1347@example 1348@group | 1381 1382@example 1383@group |
| 1349@@ifinfo 1350This is a short example of a complete Texinfo file. | 1384@@copying 1385This is a short example of a complete Texinfo file, version 1.0. |
| 1351 1352Copyright @@copyright@{@} 2002 Free Software Foundation, Inc. | 1386 1387Copyright @@copyright@{@} 2002 Free Software Foundation, Inc. |
| 1353@@end ifinfo | 1388@@end copying |
| 1354@end group 1355@end example 1356 | 1389@end group 1390@end example 1391 |
| 1357@subheading Part 3: Titlepage and Copyright | 1392@subheading Part 3: Titlepage, Contents, Copyright |
| 1358 1359@noindent | 1393 1394@noindent |
| 1360The titlepage segment does not appear in the Info file. | 1395The titlepage segment does not appear in the online output, only in the 1396printed manual. We use the @code{@@insertcopying} command to 1397include the permission text from the previous section, instead of 1398writing it out again; it is output on the back of the title page. The 1399@code{@@contents} command generates a table of contents. |
| 1361 1362@example 1363@group | 1400 1401@example 1402@group |
| 1364@@contents | |
| 1365@@titlepage | 1403@@titlepage |
| 1366@@sp 10 | |
| 1367@@title Sample Title 1368@end group 1369 1370@group 1371@@c The following two commands start the copyright page. 1372@@page 1373@@vskip 0pt plus 1filll | 1404@@title Sample Title 1405@end group 1406 1407@group 1408@@c The following two commands start the copyright page. 1409@@page 1410@@vskip 0pt plus 1filll |
| 1374Copyright @@copyright@{@} 2002 Free Software Foundation, Inc. | 1411@@insertcopying |
| 1375@@end titlepage 1376@end group | 1412@@end titlepage 1413@end group |
| 1414 1415@@c Output the table of contents at the beginning. 1416@@contents |
|
| 1377@end example 1378 1379@subheading Part 4: `Top' Node and Master Menu 1380 1381@noindent | 1417@end example 1418 1419@subheading Part 4: `Top' Node and Master Menu 1420 1421@noindent |
| 1382The `Top' node contains the master menu for the Info file. 1383Since a printed manual uses a table of contents rather than 1384a menu, the master menu appears only in online output. | 1422The `Top' node contains the master menu for the Info file. Since a 1423printed manual uses a table of contents rather than a menu, the master 1424menu appears only in online output. We also include the copying text 1425again for the benefit of online readers. And since the copying text 1426begins with a brief description of the manual, no other text is needed. |
| 1385 1386@example 1387@group 1388@@ifnottex 1389@@node Top 1390@@end ifnottex 1391@end group 1392@end example 1393 1394@example 1395@group | 1427 1428@example 1429@group 1430@@ifnottex 1431@@node Top 1432@@end ifnottex 1433@end group 1434@end example 1435 1436@example 1437@group |
| 1438@@insertcopying 1439 |
|
| 1396@@menu 1397* First Chapter:: The first chapter is the | 1440@@menu 1441* First Chapter:: The first chapter is the |
| 1398 only chapter in this sample. 1399* Concept Index:: This index has two entries. | 1442 only chapter in this sample. 1443* Index:: Complete index. |
| 1400@@end menu 1401@end group 1402@end example 1403 | 1444@@end menu 1445@end group 1446@end example 1447 |
| 1404@subheading Part 5: The Body of the Document | |
| 1405 | 1448 |
| 1449@subheading Part 5: The Body of the Document 1450 |
|
| 1406@noindent 1407The body segment contains all the text of the document, but not the 1408indices or table of contents. This example illustrates a node and a | 1451@noindent 1452The body segment contains all the text of the document, but not the 1453indices or table of contents. This example illustrates a node and a |
| 1409chapter containing an enumerated list.@refill | 1454chapter containing an enumerated list. |
| 1410 1411@example 1412@group 1413@@node First Chapter 1414@@chapter First Chapter | 1455 1456@example 1457@group 1458@@node First Chapter 1459@@chapter First Chapter |
| 1415@@cindex Chapter, first | 1460 1461@@cindex chapter, first |
| 1416@end group 1417 1418@group | 1462@end group 1463 1464@group |
| 1419This is the contents of the first chapter. 1420@@cindex Another sample index entry | 1465This is the first chapter. 1466@@cindex index entry, another |
| 1421@end group 1422 1423@group 1424Here is a numbered list. 1425 1426@@enumerate 1427@@item 1428This is the first item. 1429 1430@@item 1431This is the second item. 1432@@end enumerate 1433@end group | 1467@end group 1468 1469@group 1470Here is a numbered list. 1471 1472@@enumerate 1473@@item 1474This is the first item. 1475 1476@@item 1477This is the second item. 1478@@end enumerate 1479@end group |
| 1434 1435@group 1436The @@code@{makeinfo@} command transforms a Texinfo file 1437such as this into an Info file or other output; 1438@@TeX@ typesets it for a printed manual. 1439@end group | |
| 1440@end example 1441 | 1480@end example 1481 |
| 1482 |
|
| 1442@subheading Part 6: The End of the Document 1443 1444@noindent 1445The end segment contains commands for generating an index in a node and | 1483@subheading Part 6: The End of the Document 1484 1485@noindent 1486The end segment contains commands for generating an index in a node and |
| 1446unnumbered chapter of its own, (usually) for generating the table of 1447contents, and the @code{@@bye} command that marks the end of the 1448document.@refill | 1487unnumbered chapter of its own, and the @code{@@bye} command that marks 1488the end of the document. |
| 1449 1450@example 1451@group | 1489 1490@example 1491@group |
| 1452@@node Concept Index 1453@@unnumbered Concept Index | 1492@@node Index 1493@@unnumbered Index |
| 1454@end group 1455 1456@group 1457@@printindex cp 1458 1459@@bye 1460@end group 1461@end example 1462 | 1494@end group 1495 1496@group 1497@@printindex cp 1498 1499@@bye 1500@end group 1501@end example 1502 |
| 1463@subheading The Results | |
| 1464 | 1503 |
| 1504@subheading Some Results 1505 |
|
| 1465Here is what the contents of the first chapter of the sample look like: 1466 1467@sp 1 1468@need 700 1469@quotation | 1506Here is what the contents of the first chapter of the sample look like: 1507 1508@sp 1 1509@need 700 1510@quotation |
| 1470This is the contents of the first chapter. | 1511This is the first chapter. |
| 1471 1472Here is a numbered list. 1473 1474@enumerate 1475@item 1476This is the first item. 1477 1478@item 1479This is the second item. 1480@end enumerate | 1512 1513Here is a numbered list. 1514 1515@enumerate 1516@item 1517This is the first item. 1518 1519@item 1520This is the second item. 1521@end enumerate |
| 1481 1482The @code{makeinfo} and @code{texinfo-format-buffer} 1483commands transform a Texinfo file such as this into 1484an Info file; and @TeX{} typesets it for a printed 1485manual. | |
| 1486@end quotation 1487 1488 1489@node History 1490@section History 1491 1492@cindex Stallman, Richard M. 1493@cindex Chassell, Robert J. | 1522@end quotation 1523 1524 1525@node History 1526@section History 1527 1528@cindex Stallman, Richard M. 1529@cindex Chassell, Robert J. |
| 1530@cindex Fox, Brian |
|
| 1494@cindex Berry, Karl 1495Richard M.@: Stallman invented the Texinfo format, wrote the initial | 1531@cindex Berry, Karl 1532Richard M.@: Stallman invented the Texinfo format, wrote the initial |
| 1496processors, and created Edition 1.0 of this manual. @w{Robert J.@: 1497Chassell} greatly revised and extended the manual, starting with Edition | 1533processors, and created Edition 1.0 of this manual. @w{Robert J.@:} 1534Chassell greatly revised and extended the manual, starting with Edition |
| 14981.1. Brian Fox was responsible for the standalone Texinfo distribution 1499until version 3.8, and wrote the standalone @command{makeinfo} and | 15351.1. Brian Fox was responsible for the standalone Texinfo distribution 1536until version 3.8, and wrote the standalone @command{makeinfo} and |
| 1500@command{info}. Karl Berry has made the updates since Texinfo 3.8 and 1501subsequent releases, starting with Edition 2.22 of the manual. | 1537@command{info} programs. Karl Berry has continued maintenance since 1538Texinfo 3.8 (manual edition 2.22). |
| 1502 1503@cindex Pinard, Fran@,{c}ois 1504@cindex Zuhn, David D. 1505@cindex Weisshaus, Melissa 1506@cindex Zaretskii, Eli 1507@cindex Schwab, Andreas 1508@cindex Weinberg, Zack | 1539 1540@cindex Pinard, Fran@,{c}ois 1541@cindex Zuhn, David D. 1542@cindex Weisshaus, Melissa 1543@cindex Zaretskii, Eli 1544@cindex Schwab, Andreas 1545@cindex Weinberg, Zack |
| 1509Our thanks go out to all who helped improve this work, particularly to 1510Fran@,{c}ois Pinard and @w{David D.@: Zuhn}, who tirelessly recorded and 1511reported mistakes and obscurities; our special thanks go to Melissa 1512Weisshaus for her frequent and often tedious reviews of nearly similar 1513editions. The indefatigable Eli Zaretskii and Andreas Schwab have 1514provided patches beyond counting. Zack Weinberg did the impossible by 1515implementing the macro syntax in @file{texinfo.tex}. Dozens of others 1516have contributed patches and suggestions, they are gratefully 1517acknowledged in the @file{ChangeLog} file. Our mistakes are our own. | 1546Our thanks go out to all who helped improve this work, particularly the 1547indefatigable Eli Zaretskii and Andreas Schwab, who have provided 1548patches beyond counting. Fran@,{c}ois Pinard and @w{David D.@: Zuhn}, 1549tirelessly recorded and reported mistakes and obscurities. Zack 1550Weinberg did the impossible by implementing the macro syntax in 1551@file{texinfo.tex}. Special thanks go to Melissa Weisshaus for her 1552frequent reviews of nearly similar editions. Dozens of others have 1553contributed patches and suggestions, they are gratefully acknowledged in 1554the @file{ChangeLog} file. Our mistakes are our own. |
| 1518 1519@cindex Scribe 1520@cindex Reid, Brian 1521@cindex History of Texinfo | 1555 1556@cindex Scribe 1557@cindex Reid, Brian 1558@cindex History of Texinfo |
| 1559@cindex Texinfo history |
|
| 1522A bit of history: in the 1970's at CMU, Brian Reid developed a program 1523and format named Scribe to mark up documents for printing. It used the | 1560A bit of history: in the 1970's at CMU, Brian Reid developed a program 1561and format named Scribe to mark up documents for printing. It used the |
| 1524@code{@@} character to introduce commands as Texinfo does and strived to 1525describe document contents rather than formatting. | 1562@code{@@} character to introduce commands, as Texinfo does. Much more 1563consequentially, it strived to describe document contents rather than 1564formatting, an idea wholeheartedly adopted by Texinfo. |
| 1526 1527@cindex Bolio 1528@cindex Bo@TeX{} 1529Meanwhile, people at MIT developed another, not too dissimilar format 1530called Bolio. This then was converted to using @TeX{} as its typesetting | 1565 1566@cindex Bolio 1567@cindex Bo@TeX{} 1568Meanwhile, people at MIT developed another, not too dissimilar format 1569called Bolio. This then was converted to using @TeX{} as its typesetting |
| 1531language: Bo@TeX{}. | 1570language: Bo@TeX{}. The earliest Bo@TeX{} version seems to have been 15710.02 on October 31, 1984. |
| 1532 1533Bo@TeX{} could only be used as a markup language for documents to be 1534printed, not for online documents. Richard Stallman (RMS) worked on 1535both Bolio and Bo@TeX{}. He also developed a nifty on-line help format 1536called Info, and then combined Bo@TeX{} and Info to create Texinfo, a | 1572 1573Bo@TeX{} could only be used as a markup language for documents to be 1574printed, not for online documents. Richard Stallman (RMS) worked on 1575both Bolio and Bo@TeX{}. He also developed a nifty on-line help format 1576called Info, and then combined Bo@TeX{} and Info to create Texinfo, a |
| 1537mark up language for text that is intended to be read both on line and | 1577mark up language for text that is intended to be read both online and |
| 1538as printed hard copy. 1539 1540 | 1578as printed hard copy. 1579 1580 |
| 1541 | |
| 1542@node Texinfo Mode 1543@chapter Using Texinfo Mode 1544@cindex Texinfo mode 1545@cindex Mode, using Texinfo 1546@cindex GNU Emacs 1547@cindex Emacs 1548 1549You may edit a Texinfo file with any text editor you choose. A Texinfo 1550file is no different from any other @sc{ascii} file. However, GNU Emacs | 1581@node Texinfo Mode 1582@chapter Using Texinfo Mode 1583@cindex Texinfo mode 1584@cindex Mode, using Texinfo 1585@cindex GNU Emacs 1586@cindex Emacs 1587 1588You may edit a Texinfo file with any text editor you choose. A Texinfo 1589file is no different from any other @sc{ascii} file. However, GNU Emacs |
| 1551comes with a special mode, called Texinfo 1552mode, that provides Emacs commands and tools to help ease your work.@refill | 1590comes with a special mode, called Texinfo mode, that provides Emacs 1591commands and tools to help ease your work. |
| 1553 1554This chapter describes features of GNU Emacs' Texinfo mode but not any | 1592 1593This chapter describes features of GNU Emacs' Texinfo mode but not any |
| 1555features of the Texinfo formatting language. If you are reading this | 1594features of the Texinfo formatting language. So if you are reading this |
| 1556manual straight through from the beginning, you may want to skim through 1557this chapter briefly and come back to it after reading succeeding | 1595manual straight through from the beginning, you may want to skim through 1596this chapter briefly and come back to it after reading succeeding |
| 1558chapters which describe the Texinfo formatting language in 1559detail.@refill | 1597chapters which describe the Texinfo formatting language in detail. |
| 1560 1561@menu 1562* Texinfo Mode Overview:: How Texinfo mode can help you. 1563* Emacs Editing:: Texinfo mode adds to GNU Emacs' general 1564 purpose editing features. 1565* Inserting:: How to insert frequently used @@-commands. 1566* Showing the Structure:: How to show the structure of a file. 1567* Updating Nodes and Menus:: How to update or create new nodes and menus. --- 477 unchanged lines hidden (view full) --- 2045Manual}).@refill 2046 2047Also, the @code{texinfo-indent-menu-description} command may be used to 2048indent existing menu descriptions to a specified column. Finally, if 2049you wish, you can use the @code{texinfo-insert-node-lines} command to 2050insert missing @code{@@node} lines into a file. (@xref{Other Updating 2051Commands}, for more information.)@refill 2052 | 1598 1599@menu 1600* Texinfo Mode Overview:: How Texinfo mode can help you. 1601* Emacs Editing:: Texinfo mode adds to GNU Emacs' general 1602 purpose editing features. 1603* Inserting:: How to insert frequently used @@-commands. 1604* Showing the Structure:: How to show the structure of a file. 1605* Updating Nodes and Menus:: How to update or create new nodes and menus. --- 477 unchanged lines hidden (view full) --- 2083Manual}).@refill 2084 2085Also, the @code{texinfo-indent-menu-description} command may be used to 2086indent existing menu descriptions to a specified column. Finally, if 2087you wish, you can use the @code{texinfo-insert-node-lines} command to 2088insert missing @code{@@node} lines into a file. (@xref{Other Updating 2089Commands}, for more information.)@refill 2090 |
| 2053@node Updating Requirements, Other Updating Commands, Updating Commands, Updating Nodes and Menus 2054@comment node-name, next, previous, up | 2091@node Updating Requirements |
| 2055@subsection Updating Requirements 2056@cindex Updating requirements 2057@cindex Requirements for updating commands 2058 2059To use the updating commands, you must organize the Texinfo file 2060hierarchically with chapters, sections, subsections, and the like. 2061When you construct the hierarchy of the manual, do not `jump down' 2062more than one level at a time: you can follow the `Top' node with a 2063chapter, but not with a section; you can follow a chapter with a 2064section, but not with a subsection. However, you may `jump up' any 2065number of levels at one time---for example, from a subsection to a 2066chapter.@refill 2067 2068Each @code{@@node} line, with the exception of the line for the `Top' 2069node, must be followed by a line with a structuring command such as 2070@code{@@chapter}, @code{@@section}, or 2071@code{@@unnumberedsubsec}.@refill 2072 2073Each @code{@@node} line/structuring-command line combination | 2092@subsection Updating Requirements 2093@cindex Updating requirements 2094@cindex Requirements for updating commands 2095 2096To use the updating commands, you must organize the Texinfo file 2097hierarchically with chapters, sections, subsections, and the like. 2098When you construct the hierarchy of the manual, do not `jump down' 2099more than one level at a time: you can follow the `Top' node with a 2100chapter, but not with a section; you can follow a chapter with a 2101section, but not with a subsection. However, you may `jump up' any 2102number of levels at one time---for example, from a subsection to a 2103chapter.@refill 2104 2105Each @code{@@node} line, with the exception of the line for the `Top' 2106node, must be followed by a line with a structuring command such as 2107@code{@@chapter}, @code{@@section}, or 2108@code{@@unnumberedsubsec}.@refill 2109 2110Each @code{@@node} line/structuring-command line combination |
| 2074must look either like this:@refill | 2111must look either like this: |
| 2075 2076@example 2077@group 2078@@node Comments, Minimum, Conventions, Overview 2079@@comment node-name, next, previous, up 2080@@section Comments 2081@end group 2082@end example 2083 2084or like this (without the @code{@@comment} line): 2085 2086@example 2087@group 2088@@node Comments, Minimum, Conventions, Overview 2089@@section Comments 2090@end group 2091@end example 2092 | 2112 2113@example 2114@group 2115@@node Comments, Minimum, Conventions, Overview 2116@@comment node-name, next, previous, up 2117@@section Comments 2118@end group 2119@end example 2120 2121or like this (without the @code{@@comment} line): 2122 2123@example 2124@group 2125@@node Comments, Minimum, Conventions, Overview 2126@@section Comments 2127@end group 2128@end example 2129 |
| 2130or like this (without the explicit node pointers): 2131 2132@example 2133@group 2134@@node Comments 2135@@section Comments 2136@end group 2137@end example 2138 |
|
| 2093@noindent 2094In this example, `Comments' is the name of both the node and the 2095section. The next node is called `Minimum' and the previous node is 2096called `Conventions'. The `Comments' section is within the `Overview' 2097node, which is specified by the `Up' pointer. (Instead of an | 2139@noindent 2140In this example, `Comments' is the name of both the node and the 2141section. The next node is called `Minimum' and the previous node is 2142called `Conventions'. The `Comments' section is within the `Overview' 2143node, which is specified by the `Up' pointer. (Instead of an |
| 2098@code{@@comment} line, you may also write an @code{@@ifinfo} line.)@refill | 2144@code{@@comment} line, you may also write an @code{@@ifinfo} line.) |
| 2099 2100If a file has a `Top' node, it must be called @samp{top} or @samp{Top} | 2145 2146If a file has a `Top' node, it must be called @samp{top} or @samp{Top} |
| 2101and be the first node in the file.@refill | 2147and be the first node in the file. |
| 2102 2103The menu updating commands create a menu of sections within a chapter, 2104a menu of subsections within a section, and so on. This means that 2105you must have a `Top' node if you want a menu of chapters.@refill 2106 2107Incidentally, the @code{makeinfo} command will create an Info file for a 2108hierarchically organized Texinfo file that lacks `Next', `Previous' and 2109`Up' pointers. Thus, if you can be sure that your Texinfo file will be 2110formatted with @code{makeinfo}, you have no need for the update node 2111commands. (@xref{Creating an Info File}, for more information about 2112@code{makeinfo}.) However, both @code{makeinfo} and the 2113@code{texinfo-format-@dots{}} commands require that you insert menus in 2114the file. 2115 | 2148 2149The menu updating commands create a menu of sections within a chapter, 2150a menu of subsections within a section, and so on. This means that 2151you must have a `Top' node if you want a menu of chapters.@refill 2152 2153Incidentally, the @code{makeinfo} command will create an Info file for a 2154hierarchically organized Texinfo file that lacks `Next', `Previous' and 2155`Up' pointers. Thus, if you can be sure that your Texinfo file will be 2156formatted with @code{makeinfo}, you have no need for the update node 2157commands. (@xref{Creating an Info File}, for more information about 2158@code{makeinfo}.) However, both @code{makeinfo} and the 2159@code{texinfo-format-@dots{}} commands require that you insert menus in 2160the file. 2161 |
| 2116@node Other Updating Commands, , Updating Requirements, Updating Nodes and Menus 2117@comment node-name, next, previous, up | 2162 2163@node Other Updating Commands |
| 2118@subsection Other Updating Commands 2119 2120In addition to the five major updating commands, Texinfo mode 2121possesses several less frequently used updating commands:@refill 2122 2123@table @kbd 2124@item M-x texinfo-insert-node-lines 2125@findex texinfo-insert-node-lines --- 113 unchanged lines hidden (view full) --- 2239 2240@example 2241C-c C-m C-b 2242@exdent or 2243M-x makeinfo-buffer 2244@end example 2245 2246For @TeX{} or the Info formatting commands to work, the file @emph{must} | 2164@subsection Other Updating Commands 2165 2166In addition to the five major updating commands, Texinfo mode 2167possesses several less frequently used updating commands:@refill 2168 2169@table @kbd 2170@item M-x texinfo-insert-node-lines 2171@findex texinfo-insert-node-lines --- 113 unchanged lines hidden (view full) --- 2285 2286@example 2287C-c C-m C-b 2288@exdent or 2289M-x makeinfo-buffer 2290@end example 2291 2292For @TeX{} or the Info formatting commands to work, the file @emph{must} |
| 2247include a line that has @code{@@setfilename} in its header.@refill | 2293include a line that has @code{@@setfilename} in its header. |
| 2248 2249@xref{Creating an Info File}, for details about Info formatting.@refill 2250 2251@node Printing, Texinfo Mode Summary, Info Formatting, Texinfo Mode 2252@comment node-name, next, previous, up 2253@section Formatting and Printing 2254@cindex Formatting for printing 2255@cindex Printing a region or buffer --- 232 unchanged lines hidden (view full) --- 2488@end group 2489 2490@group 2491M-x texinfo-sequential-node-update 2492 @r{Insert node pointers in strict sequence.} 2493@end group 2494@end example 2495 | 2294 2295@xref{Creating an Info File}, for details about Info formatting.@refill 2296 2297@node Printing, Texinfo Mode Summary, Info Formatting, Texinfo Mode 2298@comment node-name, next, previous, up 2299@section Formatting and Printing 2300@cindex Formatting for printing 2301@cindex Printing a region or buffer --- 232 unchanged lines hidden (view full) --- 2534@end group 2535 2536@group 2537M-x texinfo-sequential-node-update 2538 @r{Insert node pointers in strict sequence.} 2539@end group 2540@end example 2541 |
| 2542 |
|
| 2496@node Beginning a File 2497@chapter Beginning a Texinfo File 2498@cindex Beginning a Texinfo file 2499@cindex Texinfo file beginning 2500@cindex File beginning 2501 2502Certain pieces of information must be provided at the beginning of a | 2543@node Beginning a File 2544@chapter Beginning a Texinfo File 2545@cindex Beginning a Texinfo file 2546@cindex Texinfo file beginning 2547@cindex File beginning 2548 2549Certain pieces of information must be provided at the beginning of a |
| 2503Texinfo file, such as the name of the file and the title of the 2504document.@refill | 2550Texinfo file, such as the name for the output file(s), the title of the 2551document, and the Top node. |
| 2505 | 2552 |
| 2553This chapter expands on the minimal complete Texinfo source file 2554previously given (@pxref{Six Parts}). 2555 |
|
| 2506@menu | 2556@menu |
| 2507* Four Parts:: Four parts begin a Texinfo file. 2508* Sample Beginning:: Here is a sample beginning for a Texinfo file. 2509* Header:: The very beginning of a Texinfo file. 2510* Info Summary and Permissions:: Summary and copying permissions for Info. | 2557* Sample Beginning:: A sample beginning for a Texinfo file. 2558* Texinfo File Header:: The first lines. 2559* Document Permissions:: Ensuring your manual is free. |
| 2511* Titlepage & Copyright Page:: Creating the title and copyright pages. 2512* The Top Node:: Creating the `Top' node and master menu. | 2560* Titlepage & Copyright Page:: Creating the title and copyright pages. 2561* The Top Node:: Creating the `Top' node and master menu. |
| 2562* Global Document Commands:: Affecting formatting throughout. |
|
| 2513* Software Copying Permissions:: Ensure that you and others continue to | 2563* Software Copying Permissions:: Ensure that you and others continue to |
| 2514 have the right to use and share software. | 2564 have the right to use and share software. |
| 2515@end menu 2516 | 2565@end menu 2566 |
| 2517@node Four Parts, Sample Beginning, Beginning a File, Beginning a File 2518@ifinfo 2519@heading Four Parts Begin a File 2520@end ifinfo | |
| 2521 | 2567 |
| 2522Generally, the beginning of a Texinfo file has four parts:@refill 2523 2524@enumerate 2525@item 2526The header, delimited by special comment lines, that includes the 2527commands for naming the Texinfo file and telling @TeX{} what 2528definitions file to use when processing the Texinfo file.@refill 2529 2530@item 2531A short statement of what the file is about, with a copyright notice 2532and copying permissions. This is enclosed in @code{@@ifinfo} and 2533@code{@@end ifinfo} commands so that the formatters place it only 2534in the Info file.@refill 2535 2536@item 2537A title page and copyright page, with a copyright notice and copying 2538permissions. This is enclosed between @code{@@titlepage} and 2539@code{@@end titlepage} commands. The title and copyright page appear 2540only in the printed @w{manual}.@refill 2541 2542@item 2543The `Top' node that contains a menu for the whole Info file. The 2544contents of this node appear only in the Info file.@refill 2545@end enumerate 2546 2547Also, optionally, you may include the copying conditions for a program 2548and a warranty disclaimer. The copying section will be followed by an 2549introduction or else by the first chapter of the manual.@refill 2550 2551Since the copyright notice and copying permissions for the Texinfo 2552document (in contrast to the copying permissions for a program) are in 2553parts that appear only in the Info file or only in the printed manual, 2554this information must be given twice.@refill 2555 2556 | |
| 2557@node Sample Beginning 2558@section Sample Texinfo File Beginning 2559 | 2568@node Sample Beginning 2569@section Sample Texinfo File Beginning 2570 |
| 2560The following sample shows what is needed.@refill | 2571@cindex Example beginning of Texinfo file |
| 2561 | 2572 |
| 2573The following sample shows what is needed. The elements given here are 2574explained in more detail in the following sections. Other commands are 2575often included at the beginning of Texinfo files, but the ones here are 2576the most critical. 2577 2578@xref{GNU Sample Texts}, for the full texts to be used in GNU manuals. 2579 |
|
| 2562@example 2563\input texinfo @@c -*-texinfo-*- 2564@@c %**start of header | 2580@example 2581\input texinfo @@c -*-texinfo-*- 2582@@c %**start of header |
| 2565@@setfilename @var{name-of-info-file} 2566@@settitle @var{name-of-manual} 2567@@setchapternewpage odd | 2583@@setfilename @var{infoname}.info 2584@@settitle @var{name-of-manual} @var{version} |
| 2568@@c %**end of header 2569 | 2585@@c %**end of header 2586 |
| 2570@@ifinfo 2571This file documents @dots{} | 2587@@copying 2588This manual is for @var{program}, version @var{version}. |
| 2572 | 2589 |
| 2573Copyright @var{year} @var{copyright-owner} | 2590Copyright @@copyright@{@} @var{years} @var{copyright-owner}. |
| 2574 2575@group | 2591 2592@group |
| 2593@@quotation |
|
| 2576Permission is granted to @dots{} | 2594Permission is granted to @dots{} |
| 2577@@end ifinfo | 2595@@end quotation 2596@@end copying |
| 2578@end group 2579 2580@group | 2597@end group 2598 2599@group |
| 2581@@c This title page illustrates only one of the 2582@@c two methods of forming a title page. 2583@end group 2584 2585@group | |
| 2586@@titlepage 2587@@title @var{name-of-manual-when-printed} 2588@@subtitle @var{subtitle-if-any} 2589@@subtitle @var{second-subtitle} 2590@@author @var{author} 2591@end group 2592 2593@group 2594@@c The following two commands 2595@@c start the copyright page. 2596@@page 2597@@vskip 0pt plus 1filll | 2600@@titlepage 2601@@title @var{name-of-manual-when-printed} 2602@@subtitle @var{subtitle-if-any} 2603@@subtitle @var{second-subtitle} 2604@@author @var{author} 2605@end group 2606 2607@group 2608@@c The following two commands 2609@@c start the copyright page. 2610@@page 2611@@vskip 0pt plus 1filll |
| 2598Copyright @@copyright@{@} @var{year} @var{copyright-owner} | 2612@@insertcopying |
| 2599@end group 2600 2601Published by @dots{} | 2613@end group 2614 2615Published by @dots{} |
| 2602 2603Permission is granted to @dots{} | |
| 2604@@end titlepage 2605 | 2616@@end titlepage 2617 |
| 2618@@c So the toc is printed in the right place. 2619@@contents 2620 |
|
| 2606@@ifnottex 2607@@node Top 2608@@top @var{title} 2609 | 2621@@ifnottex 2622@@node Top 2623@@top @var{title} 2624 |
| 2610This document describes @dots{} 2611 2612This document applies to version @dots{} 2613of the program named @dots{} | 2625@@insertcopying |
| 2614@@end ifnottex 2615 2616@group 2617@@menu | 2626@@end ifnottex 2627 2628@group 2629@@menu |
| 2618* Copying:: Your rights and freedoms. | |
| 2619* First Chapter:: Getting started @dots{} | 2630* First Chapter:: Getting started @dots{} |
| 2620* Second Chapter:: @dots{} | 2631* Second Chapter:: @dots{} |
| 2621 @dots{} | 2632 @dots{} |
| 2622 @dots{} | 2633* Copying:: Your rights and freedoms. |
| 2623@@end menu 2624@end group 2625 2626@group | 2634@@end menu 2635@end group 2636 2637@group |
| 2627@@node First Chapter | 2638@@node First Chapter |
| 2628@@chapter First Chapter | 2639@@chapter First Chapter |
| 2629@@cindex Index entry for First Chapter | 2640 2641@@cindex first chapter 2642@@cindex chapter, first 2643@dots{} |
| 2630@end group 2631@end example 2632 2633 | 2644@end group 2645@end example 2646 2647 |
| 2634@node Header 2635@section The Texinfo File Header | 2648@node Texinfo File Header 2649@section Texinfo File Header |
| 2636@cindex Header for Texinfo files 2637@cindex Texinfo file header 2638 2639Texinfo files start with at least three lines that provide Info and 2640@TeX{} with necessary information. These are the @code{\input texinfo} | 2650@cindex Header for Texinfo files 2651@cindex Texinfo file header 2652 2653Texinfo files start with at least three lines that provide Info and 2654@TeX{} with necessary information. These are the @code{\input texinfo} |
| 2641line, the @code{@@settitle} line, and the @code{@@setfilename} line. If 2642you want to run @TeX{} on just a part of the Texinfo file, you must | 2655line, the @code{@@settitle} line, and the @code{@@setfilename} line. 2656 2657Also, if you want to format just part of the Texinfo file, you must |
| 2643write the @code{@@settitle} and @code{@@setfilename} lines between | 2658write the @code{@@settitle} and @code{@@setfilename} lines between |
| 2644start-of-header and end-of-header lines. | 2659start-of-header and end-of-header lines. The start- and end-of-header 2660lines are optional, but they do no harm, so you might as well always 2661include them. |
| 2645 | 2662 |
| 2646Thus, the beginning of a Texinfo file looks like this: | 2663Any command that affects document formatting as a whole makes sense to 2664include in the header. @code{@@synindex} (@pxref{synindex}), for 2665instance, is another command often included in the header. @xref{GNU 2666Sample Texts}, for complete sample texts. |
| 2647 | 2667 |
| 2648@example 2649@group 2650\input texinfo @@c -*-texinfo-*- 2651@@setfilename sample.info 2652@@settitle Sample Document 2653@end group 2654@end example | 2668Thus, the beginning of a Texinfo file generally looks like this: |
| 2655 | 2669 |
| 2656@noindent 2657or else like this: 2658 | |
| 2659@example 2660@group 2661\input texinfo @@c -*-texinfo-*- 2662@@c %**start of header 2663@@setfilename sample.info | 2670@example 2671@group 2672\input texinfo @@c -*-texinfo-*- 2673@@c %**start of header 2674@@setfilename sample.info |
| 2664@@settitle Sample Document | 2675@@settitle Sample Manual 1.0 |
| 2665@@c %**end of header 2666@end group 2667@end example 2668 2669@menu 2670* First Line:: The first line of a Texinfo file. 2671* Start of Header:: Formatting a region requires this. 2672* setfilename:: Tell Info the name of the Info file. 2673* settitle:: Create a title for the printed work. | 2676@@c %**end of header 2677@end group 2678@end example 2679 2680@menu 2681* First Line:: The first line of a Texinfo file. 2682* Start of Header:: Formatting a region requires this. 2683* setfilename:: Tell Info the name of the Info file. 2684* settitle:: Create a title for the printed work. |
| 2674* documentdescription:: Document summary for the HTML output. 2675* setchapternewpage:: Start chapters on right-hand pages. 2676* paragraphindent:: Specify paragraph indentation. 2677* exampleindent:: Specify environment indentation. | |
| 2678* End of Header:: Formatting a region requires this. 2679@end menu 2680 2681 2682@node First Line 2683@subsection The First Line of a Texinfo File 2684@cindex First line of a Texinfo file 2685@cindex Beginning line of a Texinfo file 2686@cindex Header of a Texinfo file 2687 2688Every Texinfo file that is to be the top-level input to @TeX{} must begin | 2685* End of Header:: Formatting a region requires this. 2686@end menu 2687 2688 2689@node First Line 2690@subsection The First Line of a Texinfo File 2691@cindex First line of a Texinfo file 2692@cindex Beginning line of a Texinfo file 2693@cindex Header of a Texinfo file 2694 2695Every Texinfo file that is to be the top-level input to @TeX{} must begin |
| 2689with a line that looks like this:@refill | 2696with a line that looks like this: |
| 2690 2691@example 2692\input texinfo @@c -*-texinfo-*- 2693@end example 2694 2695@noindent 2696This line serves two functions: 2697 2698@enumerate 2699@item 2700When the file is processed by @TeX{}, the @samp{\input texinfo} command 2701tells @TeX{} to load the macros needed for processing a Texinfo file. | 2697 2698@example 2699\input texinfo @@c -*-texinfo-*- 2700@end example 2701 2702@noindent 2703This line serves two functions: 2704 2705@enumerate 2706@item 2707When the file is processed by @TeX{}, the @samp{\input texinfo} command 2708tells @TeX{} to load the macros needed for processing a Texinfo file. |
| 2702These are in a file called @file{texinfo.tex}, which is usually located 2703in the @file{/usr/lib/tex/macros} directory. @TeX{} uses the backslash, 2704@samp{\}, to mark the beginning of a command, just as Texinfo uses 2705@samp{@@}. The @file{texinfo.tex} file causes the switch from @samp{\} 2706to @samp{@@}; before the switch occurs, @TeX{} requires @samp{\}, which 2707is why it appears at the beginning of the file.@refill | 2709These are in a file called @file{texinfo.tex}, which should have been 2710installed on your system along with either the @TeX{} or Texinfo 2711software. @TeX{} uses the backslash, @samp{\}, to mark the beginning of 2712a command, exactly as Texinfo uses @samp{@@}. The @file{texinfo.tex} 2713file causes the switch from @samp{\} to @samp{@@}; before the switch 2714occurs, @TeX{} requires @samp{\}, which is why it appears at the 2715beginning of the file. |
| 2708 2709@item 2710When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode | 2716 2717@item 2718When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode |
| 2711specification tells Emacs to use Texinfo mode.@refill | 2719specification tells Emacs to use Texinfo mode. |
| 2712@end enumerate 2713 2714 2715@node Start of Header 2716@subsection Start of Header 2717@cindex Start of header line 2718 | 2720@end enumerate 2721 2722 2723@node Start of Header 2724@subsection Start of Header 2725@cindex Start of header line 2726 |
| 2719Write a start-of-header line on the second line of a Texinfo file. 2720Follow the start-of-header line with @code{@@setfilename} and 2721@code{@@settitle} lines and, optionally, with other command lines, such 2722as @code{@@smallbook} or @code{@@footnotestyle}; and then by an 2723end-of-header line (@pxref{End of Header}).@refill | 2727A start-of-header line is a Texinfo comment that looks like this: |
| 2724 | 2728 |
| 2725With these lines, you can format part of a Texinfo file for Info or 2726typeset part for printing.@refill 2727 2728A start-of-header line looks like this:@refill 2729 | |
| 2730@example 2731@@c %**start of header 2732@end example 2733 | 2729@example 2730@@c %**start of header 2731@end example 2732 |
| 2733Write the start-of-header line on the second line of a Texinfo file. 2734Follow the start-of-header line with @code{@@setfilename} and 2735@code{@@settitle} lines and, optionally, with other commands that 2736globally affect the document formatting, such as @code{@@synindex} or 2737@code{@@footnotestyle}; and then by an end-of-header line (@pxref{End of 2738Header}). 2739 2740The start- and end-of-header lines allow you to format only part of a 2741Texinfo file for Info or printing. @xref{texinfo-format commands}. 2742 |
|
| 2734The odd string of characters, @samp{%**}, is to ensure that no other | 2743The odd string of characters, @samp{%**}, is to ensure that no other |
| 2735comment is accidentally taken for a start-of-header line.@refill | 2744comment is accidentally taken for a start-of-header line. You can 2745change it if you wish by setting the @code{tex-start-of-header} and/or 2746@code{tex-end-of-header} Emacs variables. @xref{Texinfo Mode Printing}. |
| 2736 | 2747 |
| 2748 |
|
| 2737@node setfilename | 2749@node setfilename |
| 2738@subsection @code{@@setfilename} 2739@cindex Info file requires @code{@@setfilename} | 2750@subsection @code{@@setfilename}: Set the output file name |
| 2740@findex setfilename | 2751@findex setfilename |
| 2752@cindex Texinfo requires @code{@@setfilename} |
|
| 2741 2742In order to serve as the primary input file for either @code{makeinfo} 2743or @TeX{}, a Texinfo file must contain a line that looks like this: 2744 2745@example 2746@@setfilename @var{info-file-name} 2747@end example 2748 2749Write the @code{@@setfilename} command at the beginning of a line and 2750follow it on the same line by the Info file name. Do not write anything 2751else on the line; anything on the line after the command is considered 2752part of the file name, including what would otherwise be a 2753comment. 2754 | 2753 2754In order to serve as the primary input file for either @code{makeinfo} 2755or @TeX{}, a Texinfo file must contain a line that looks like this: 2756 2757@example 2758@@setfilename @var{info-file-name} 2759@end example 2760 2761Write the @code{@@setfilename} command at the beginning of a line and 2762follow it on the same line by the Info file name. Do not write anything 2763else on the line; anything on the line after the command is considered 2764part of the file name, including what would otherwise be a 2765comment. 2766 |
| 2767@cindex Ignored before @code{@@setfilename} 2768@cindex @samp{\input} source line ignored 2769The Info formatting commands ignore everything written before the 2770@code{@@setfilename} line, which is why the very first line of 2771the file (the @code{\input} line) does not show up in the output. 2772 |
|
| 2755The @code{@@setfilename} line specifies the name of the output file to | 2773The @code{@@setfilename} line specifies the name of the output file to |
| 2756be generated. This name should be different from the name of the 2757Texinfo file. There are two conventions for choosing the name: you can 2758either remove the extension (such as @samp{.texi}) from the input file 2759name, or replace it with the @samp{.info} extension. When producing 2760HTML output, @code{makeinfo} will replace any extension with 2761@samp{html}, or add @samp{.html} if the given name has no extension. | 2774be generated. This name must be different from the name of the Texinfo 2775file. There are two conventions for choosing the name: you can either 2776remove the extension (such as @samp{.texi}) entirely from the input file 2777name, or, preferably, replace it with the @samp{.info} extension. |
| 2762 | 2778 |
| 2763Some operating systems cannot handle long file names. You can run into 2764a problem even when the file name you specify is itself short enough. | 2779@cindex Length of file names 2780@cindex File name collision 2781@cindex Info file name, choosing 2782Although an explicit @samp{.info} extension is preferable, some 2783operating systems cannot handle long file names. You can run into a 2784problem even when the file name you specify is itself short enough. |
| 2765This occurs because the Info formatters split a long Info file into 2766short indirect subfiles, and name them by appending @samp{-1}, 2767@samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original | 2785This occurs because the Info formatters split a long Info file into 2786short indirect subfiles, and name them by appending @samp{-1}, 2787@samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original |
| 2768file name. (@xref{Tag and Split Files, , Tag Files and Split Files}.) 2769The subfile name @file{texinfo.info-10}, for example, is too long for 2770some systems; so the Info file name for this document is @file{texinfo} 2771rather than @file{texinfo.info}. When @code{makeinfo} is running on 2772operating systems such as MS-DOS which impose grave limits on file 2773names, it will sometimes remove some characters from the original file 2774name to leave enough space for the subfile suffix, thus producing files 2775named @file{texin-10}, @file{gcc.i12}, etc. | 2788file name. (@xref{Tag and Split Files}.) The subfile name 2789@file{texinfo.info-10}, for example, is too long for old systems with a 279014-character limit on filenames; so the Info file name for this document 2791is @file{texinfo} rather than @file{texinfo.info}. When @code{makeinfo} 2792is running on operating systems such as MS-DOS which impose severe 2793limits on file names, it may remove some characters from the original 2794file name to leave enough space for the subfile suffix, thus producing 2795files named @file{texin-10}, @file{gcc.i12}, etc. |
| 2776 | 2796 |
| 2777@cindex Ignored before @code{@@setfilename} 2778@cindex @samp{\input} source line ignored 2779The Info formatting commands ignore everything written before the 2780@code{@@setfilename} line, which is why the very first line of 2781the file (the @code{\input} line) does not show up in the output. | 2797When producing HTML output, @code{makeinfo} will replace any extension 2798with @samp{html}, or add @samp{.html} if the given name has no 2799extension. |
| 2782 2783@pindex texinfo.cnf 2784The @code{@@setfilename} line produces no output when you typeset a 2785manual with @TeX{}, but it is nevertheless essential: it opens the 2786index, cross-reference, and other auxiliary files used by Texinfo, and 2787also reads @file{texinfo.cnf} if that file is present on your system 2788(@pxref{Preparing for TeX,, Preparing for @TeX{}}). 2789 --- 4 unchanged lines hidden (view full) --- 2794 2795In order to be made into a printed manual, a Texinfo file must contain 2796a line that looks like this: 2797 2798@example 2799@@settitle @var{title} 2800@end example 2801 | 2800 2801@pindex texinfo.cnf 2802The @code{@@setfilename} line produces no output when you typeset a 2803manual with @TeX{}, but it is nevertheless essential: it opens the 2804index, cross-reference, and other auxiliary files used by Texinfo, and 2805also reads @file{texinfo.cnf} if that file is present on your system 2806(@pxref{Preparing for TeX,, Preparing for @TeX{}}). 2807 --- 4 unchanged lines hidden (view full) --- 2812 2813In order to be made into a printed manual, a Texinfo file must contain 2814a line that looks like this: 2815 2816@example 2817@@settitle @var{title} 2818@end example 2819 |
| 2802In the HTML file produced by @command{makeinfo}, @var{title} serves as 2803the default document description in the @samp{<head>} part; see 2804@ref{documentdescription}, for how to change that. 2805 | |
| 2806Write the @code{@@settitle} command at the beginning of a line and | 2820Write the @code{@@settitle} command at the beginning of a line and |
| 2807follow it on the same line by the title. This tells @TeX{} the title 2808to use in a header or footer. Do not write anything else on the line; 2809anything on the line after the command is considered part of the 2810title, including a comment.@refill | 2821follow it on the same line by the title. This tells @TeX{} the title to 2822use in a header or footer. Do not write anything else on the line; 2823anything on the line after the command is considered part of the title, 2824including what would otherwise be a comment. |
| 2811 | 2825 |
| 2826The @code{@@settitle} command should precede everything that generates 2827actual output in @TeX{}. 2828 2829@cindex <title> HTML tag 2830In the HTML file produced by @command{makeinfo}, @var{title} also serves 2831as the document @samp{<title>} and the default document description in 2832the @samp{<head>} part; see @ref{documentdescription}, for how to change 2833that. 2834 2835The title in the @code{@@settitle} command does not affect the title as 2836it appears on the title page. Thus, the two do not need not match 2837exactly. A practice we recommend is to include the version or edition 2838number of the manual in the @code{@@settitle} title; on the title page, 2839the version number generally appears as a @code{@@subtitle} so it would 2840be omitted from the @code{@@title}. (@xref{titlepage}.) 2841 |
|
| 2812Conventionally, when @TeX{} formats a Texinfo file for double-sided 2813output, the title is printed in the left-hand (even-numbered) page 2814headings and the current chapter title is printed in the right-hand 2815(odd-numbered) page headings. (@TeX{} learns the title of each chapter | 2842Conventionally, when @TeX{} formats a Texinfo file for double-sided 2843output, the title is printed in the left-hand (even-numbered) page 2844headings and the current chapter title is printed in the right-hand 2845(odd-numbered) page headings. (@TeX{} learns the title of each chapter |
| 2816from each @code{@@chapter} command.) Page footers are not 2817printed.@refill | 2846from each @code{@@chapter} command.) By default, no page footer is 2847printed. |
| 2818 2819Even if you are printing in a single-sided style, @TeX{} looks for an 2820@code{@@settitle} command line, in case you include the manual title | 2848 2849Even if you are printing in a single-sided style, @TeX{} looks for an 2850@code{@@settitle} command line, in case you include the manual title |
| 2821in the heading. @refill | 2851in the heading. |
| 2822 | 2852 |
| 2823The @code{@@settitle} command should precede everything that generates 2824actual output in @TeX{}.@refill 2825 2826Although the title in the @code{@@settitle} command is usually the 2827same as the title on the title page, it does not affect the title as 2828it appears on the title page. Thus, the two do not need not match 2829exactly; and the title in the @code{@@settitle} command can be a 2830shortened or expanded version of the title as it appears on the title 2831page. (@xref{titlepage, , @code{@@titlepage}}.)@refill 2832 | |
| 2833@TeX{} prints page headings only for that text that comes after the 2834@code{@@end titlepage} command in the Texinfo file, or that comes 2835after an @code{@@headings} command that turns on headings. 2836(@xref{headings on off, , The @code{@@headings} Command}, for more | 2853@TeX{} prints page headings only for that text that comes after the 2854@code{@@end titlepage} command in the Texinfo file, or that comes 2855after an @code{@@headings} command that turns on headings. 2856(@xref{headings on off, , The @code{@@headings} Command}, for more |
| 2837information.)@refill | 2857information.) |
| 2838 | 2858 |
| 2839You may, if you wish, create your own, customized headings and 2840footings. @xref{Headings, , Page Headings}, for a detailed discussion 2841of this process.@refill | 2859You may, if you wish, create your own, customized headings and footings. 2860@xref{Headings}, for a detailed discussion of this. |
| 2842 2843 | 2861 2862 |
| 2844@node documentdescription 2845@subsection @code{@@documentdescription}: Summary text 2846@cindex Document description 2847@cindex Description of document 2848@cindex Summary of document 2849@cindex <meta> HTML tag, and document description | 2863@node End of Header 2864@subsection End of Header 2865@cindex End of header line |
| 2850 | 2866 |
| 2851When producing HTML output for a document, @command{makeinfo} writes a 2852@samp{<meta>} element in the @samp{<head>} to give some idea of the 2853content of the document. By default, this @dfn{description} is the title 2854of the document, taken from the @code{@@settitle} command 2855(@pxref{settitle}). To change this, use the @code{@@documentdescription} 2856environment, as in: | 2867Follow the header lines with an @w{end-of-header} line, which is a 2868Texinfo comment that looks like this: |
| 2857 2858@example | 2869 2870@example |
| 2859@@documentdescription 2860descriptive text 2861@@end documendescription | 2871@@c %**end of header |
| 2862@end example 2863 | 2872@end example 2873 |
| 2864@noindent 2865This will produce the following output in the @samp{<head>} of the HTML: | 2874@xref{Start of Header}. |
| 2866 | 2875 |
| 2867@example 2868<meta name=description content="descriptive text"> 2869@end example | |
| 2870 | 2876 |
| 2871@code{@@documentdescription} must be specified before the first node of 2872the document. | 2877@node Document Permissions 2878@section Document Permissions 2879@cindex Document Permissions 2880@cindex Copying Permissions |
| 2873 | 2881 |
| 2882The copyright notice and copying permissions for a document need to 2883appear in several places in the various Texinfo output formats. 2884Therefore, Texinfo provides a command (@code{@@copying}) to declare 2885this text once, and another command (@code{@@insertcopying}) to 2886insert the text at appropriate points. |
|
| 2874 | 2887 |
| 2875@findex documentdescription 2876@node setchapternewpage 2877@subsection @code{@@setchapternewpage}: 2878@cindex Starting chapters 2879@cindex Pages, starting odd 2880@findex setchapternewpage | 2888@menu 2889* copying:: Declare the document's copying permissions. 2890* insertcopying:: Where to insert the permissions. 2891@end menu |
| 2881 | 2892 |
| 2882In an officially bound book, text is usually printed on both sides of 2883the paper, chapters start on right-hand pages, and right-hand pages have 2884odd numbers. But in short reports, text often is printed only on one 2885side of the paper. Also in short reports, chapters sometimes do not 2886start on new pages, but are printed on the same page as the end of the 2887preceding chapter, after a small amount of vertical whitespace. | |
| 2888 | 2893 |
| 2889You can use the @code{@@setchapternewpage} command with various 2890arguments to specify how @TeX{} should start chapters and whether it 2891should format headers for printing on one or both sides of the paper 2892(single-sided or double-sided printing). | 2894@node copying 2895@subsection @code{@@copying}: Declare copying permissions 2896@findex copying |
| 2893 | 2897 |
| 2894Write the @code{@@setchapternewpage} command at the beginning of a 2895line followed by its argument. | 2898The @code{@@copying} command should be given very early in the document; 2899right after the header material (@pxref{Texinfo File Header}) is the 2900recommended location. It conventionally consists of a sentence or two 2901about what the program is, the legal copyright line, and the copying 2902permissions. Here is a skeletal example: |
| 2896 | 2903 |
| 2897For example, you would write the following to cause each chapter to 2898start on a fresh odd-numbered page: 2899 | |
| 2900@example | 2904@example |
| 2901@@setchapternewpage odd 2902@end example | 2905@@copying 2906This manual is for @var{program} (version @var{version}), 2907which @dots{} |
| 2903 | 2908 |
| 2904You can specify one of three alternatives with the 2905@code{@@setchapternewpage} command: | 2909Copyright @@copyright@{@} @var{years} @var{copyright-owner}. |
| 2906 | 2910 |
| 2907@table @asis 2908 2909@item @code{@@setchapternewpage off} 2910Cause @TeX{} to typeset a new chapter on the same page as the last 2911chapter, after skipping some vertical whitespace. Also, cause @TeX{} to 2912format page headers for single-sided printing. 2913 2914@item @code{@@setchapternewpage on} 2915Cause @TeX{} to start new chapters on new pages and to format page 2916headers for single-sided printing. This is the form most often used for 2917short reports or personal printing. This is the default. 2918 2919@item @code{@@setchapternewpage odd} 2920Cause @TeX{} to start new chapters on new, odd-numbered pages 2921(right-handed pages) and to typeset for double-sided printing. This is 2922the form most often used for books and manuals. 2923@end table 2924 2925Texinfo does not have an @code{@@setchapternewpage even} command, 2926because there is no printing tradition of starting chapters or books on 2927an even-numbered page. 2928 2929If you don't like the default headers that @code{@@setchapternewpage} 2930sets, you can explicit control them with the @code{@@headings} command. 2931@xref{headings on off, , The @code{@@headings} Command}. 2932 2933At the beginning of a manual or book, pages are not numbered---for 2934example, the title and copyright pages of a book are not numbered. By 2935convention, table of contents and frontmatter pages are numbered with 2936roman numerals and not in sequence with the rest of the document. 2937 2938Since an Info file does not have pages, the @code{@@setchapternewpage} 2939command has no effect on it. 2940 2941We recommend not including any @code{@@setchapternewpage} command in 2942your manual sources at all, since the desired output is not intrinsic to 2943the document. Instead, if you don't want the default option (no blank 2944pages, same headers on all pages) use the @option{--texinfo} option to 2945@command{texi2dvi} to specify the output you want. 2946 2947 2948 2949@node paragraphindent 2950@subsection Paragraph Indenting 2951@cindex Indenting paragraphs 2952@cindex Paragraph indentation 2953@findex paragraphindent 2954 2955The Texinfo processors may insert whitespace at the beginning of the 2956first line of each paragraph, thereby indenting that paragraph. You can 2957use the @code{@@paragraphindent} command to specify this indentation. 2958Write an @code{@@paragraphindent} command at the beginning of a line 2959followed by either @samp{asis} or a number: 2960 2961@example 2962@@paragraphindent @var{indent} | 2911@@quotation 2912Permission is granted to @dots{} 2913@@end quotation 2914@@end copying |
| 2963@end example 2964 | 2915@end example 2916 |
| 2965The indentation is according to the value of @var{indent}: | 2917The @code{@@quotation} has no legal significance; it's there to improve 2918readability in some contexts. |
| 2966 | 2919 |
| 2967@table @asis 2968@item @code{asis} 2969Do not change the existing indentation (not implemented in @TeX{}). | 2920@xref{GNU Sample Texts}, for the full text to be used in GNU manuals. 2921@xref{GNU Free Documentation License}, for the license itself under 2922which GNU and other free manuals are distributed. |
| 2970 | 2923 |
| 2971@item 0 2972Omit all indentation. | 2924The text of @code{@@copying} is output as a comment at the beginning of 2925Info, HTML, and XML output files. It is @emph{not} output implicitly in 2926plain text or @TeX{}; it's up to you to use @code{@@insertcopying} to 2927emit the copying information. See the next section for details. |
| 2973 | 2928 |
| 2974@item @var{n} 2975Indent by @var{n} space characters in Info output, by @var{n} ems in 2976@TeX{}. | 2929@findex copyright 2930In output formats that support it (print and HTML), the 2931@code{@@copyright@{@}} command generates a @samp{c} inside a circle. In 2932Info and plain text, it generates @samp{(C)}. The copyright notice 2933itself has the following legally defined sequence: |
| 2977 | 2934 |
| 2978@end table 2979 2980The default value of @var{indent} is @samp{asis}. 2981@code{@@paragraphindent} is ignored for HTML output. 2982 2983Write the @code{@@paragraphindent} command before or shortly after the 2984end-of-header line at the beginning of a Texinfo file. (If you write 2985the command between the start-of-header and end-of-header lines, the 2986region formatting commands indent paragraphs as specified.) 2987 2988A peculiarity of the @code{texinfo-format-buffer} and 2989@code{texinfo-format-region} commands is that they do not indent (nor 2990fill) paragraphs that contain @code{@@w} or @code{@@*} commands. 2991@xref{Refilling Paragraphs}, for further information. 2992 2993 2994@node exampleindent 2995@subsection @code{@@exampleindent}: Environment Indenting 2996@cindex Indenting environments 2997@cindex Environment indentation 2998@cindex Example indentation 2999@findex exampleindent 3000 3001The Texinfo processors indent each line of @code{@@example} and similar 3002environments. You can use the @code{@@exampleindent} command to specify 3003this indentation. Write an @code{@@exampleindent} command at the 3004beginning of a line followed by either @samp{asis} or a number: 3005 | |
| 3006@example | 2935@example |
| 3007@@exampleindent @var{indent} | 2936Copyright @copyright{} @var{years} @var{copyright-owner}. |
| 3008@end example 3009 | 2937@end example 2938 |
| 3010The indentation is according to the value of @var{indent}: | 2939@cindex Copyright word, always in English 2940The word `Copyright' must always be written in English, even if the 2941manual is otherwise in another language. This is due to international 2942law. |
| 3011 | 2943 |
| 3012@table @asis 3013@item @code{asis} 3014Do not change the existing indentation (not implemented in @TeX{}). | 2944@cindex Years, in copyright line 2945The list of years should include all years in which a version was 2946completed (even if it was released in a subsequent year). Ranges are 2947not allowed, each year must be written out individually, separated by 2948commas. |
| 3015 | 2949 |
| 3016@item 0 3017Omit all indentation. | 2950@cindex Copyright owner for FSF works 2951The copyright owner (or owners) is whoever holds legal copyright on the 2952work. In the case of works assigned to the FSF, the owner is `Free 2953Software Foundation, Inc.'. |
| 3018 | 2954 |
| 3019@item @var{n} 3020Indent environments by @var{n} space characters in Info output, by 3021@var{n} ems in @TeX{}. | 2955@xref{Copyright Notices,,,maintain,GNU Maintenance Instructions}, for 2956additional information. |
| 3022 | 2957 |
| 3023@end table | |
| 3024 | 2958 |
| 3025The default value of @var{indent} is 5. @code{@@exampleindent} is 3026ignored for HTML output. | 2959@node insertcopying 2960@subsection @code{@@insertcopying}: Include permissions text 2961@findex insertcopying 2962@cindex Copying text, including 2963@cindex Permissions text, including 2964@cindex Including permissions text |
| 3027 | 2965 |
| 3028Write the @code{@@exampleindent} command before or shortly after the 3029end-of-header line at the beginning of a Texinfo file. (If you write 3030the command between the start-of-header and end-of-header lines, the 3031region formatting commands indent examples as specified.) | 2966The @code{@@insertcopying} command is simply written on a line by 2967itself, like this: |
| 3032 | 2968 |
| 3033 3034@node End of Header 3035@subsection End of Header 3036@cindex End of header line 3037 3038Follow the header lines with an @w{end-of-header} line. 3039An end-of-header line looks like this:@refill 3040 | |
| 3041@example | 2969@example |
| 3042@@c %**end of header | 2970@@insertcopying |
| 3043@end example 3044 | 2971@end example 2972 |
| 3045If you include the @code{@@setchapternewpage} command between the 3046start-of-header and end-of-header lines, @TeX{} will typeset a region as 3047that command specifies. Similarly, if you include an @code{@@smallbook} 3048command between the start-of-header and end-of-header lines, @TeX{} will 3049typeset a region in the ``small'' book format.@refill | 2973It inserts the text previously defined by @code{@@copying}. Legally, it 2974must be used on the copyright page in the printed manual 2975(@pxref{Copyright}). |
| 3050 | 2976 |
| 3051@ifinfo 3052The reason for the odd string of characters (@samp{%**}) is so that the 3053@code{texinfo-tex-region} command does not accidentally find 3054something that it should not when it is looking for the header.@refill | 2977Although it's not a legal requirement, we also strongly recommend using 2978@code{@@insertcopying} in the Top node of your manual (@pxref{The Top 2979Node}). Here's why: |
| 3055 | 2980 |
| 3056The start-of-header line and the end-of-header line are Texinfo mode 3057variables that you can change.@refill 3058@end ifinfo | 2981The @code{@@copying} command itself causes the permissions text to 2982appear in an Info file @emph{before} the first node. The text is also 2983copied into the beginning of each split Info output file, as is legally 2984necessary. This location implies a human reading the manual using Info 2985does @emph{not} see this text (except when using the advanced Info 2986command @kbd{g *}). Therefore, an explicit @code{@@insertcopying} 2987in the Top node makes it apparent to readers that the manual is free. |
| 3059 | 2988 |
| 3060@iftex 3061@xref{Start of Header}. 3062@end iftex | 2989Similarly, the @code{@@copying} text is automatically included at the 2990beginning of each HTML output file, as an HTML comment. Again, this 2991text is not visible (unless the reader views the HTML source). And 2992therefore again, the @code{@@insertcopying} in the Top node is valuable 2993because it makes the copying permissions visible and thus promotes 2994freedom. |
| 3063 | 2995 |
| 2996The permissions text defined by @code{@@copying} also appears 2997automatically at the beginning of the XML output file. |
|
| 3064 | 2998 |
| 3065@node Info Summary and Permissions 3066@section Summary and Copying Permissions for Info | |
| 3067 | 2999 |
| 3068The title page and the copyright page appear only in the printed copy of 3069the manual; therefore, the same information must be inserted in a 3070section that appears only in the Info file. This section usually 3071contains a brief description of the contents of the Info file, a 3072copyright notice, and copying permissions.@refill 3073 3074The copyright notice should read: 3075 3076@example 3077Copyright @var{year} @var{copyright-owner} 3078@end example 3079 3080@noindent 3081and be put on a line by itself. 3082 3083Standard text for the copyright permissions of free manuals is contained 3084in an appendix to this manual (@pxref{Documentation Copying, , GNU Free 3085Documentation License}). 3086 3087The permissions text appears in an Info file @emph{before} the first 3088node. This mean that a reader does @emph{not} see this text when 3089reading the file using Info (except when using the advanced Info command 3090@kbd{g *}). 3091 3092 | |
| 3093@node Titlepage & Copyright Page | 3000@node Titlepage & Copyright Page |
| 3094@section The Title and Copyright Pages | 3001@section Title and Copyright Pages |
| 3095 | 3002 |
| 3096A manual's name and author are usually printed on a title page. 3097Sometimes copyright information is printed on the title page as well; 3098more often, copyright information is printed on the back of the title 3099page. | 3003In hard copy output, the manual's name and author are usually printed on 3004a title page. Copyright information is usually printed on the back of 3005the title page. |
| 3100 | 3006 |
| 3101The title and copyright pages appear in the printed manual, but not in the 3102Info file. Because of this, it is possible to use several slightly | 3007The title and copyright pages appear in the printed manual, but not in 3008the Info file. Because of this, it is possible to use several slightly |
| 3103obscure @TeX{} typesetting commands that cannot be used in an Info file. | 3009obscure @TeX{} typesetting commands that cannot be used in an Info file. |
| 3104In addition, this part of the beginning of a Texinfo file contains the text 3105of the copying permissions that will appear in the printed manual.@refill | 3010In addition, this part of the beginning of a Texinfo file contains the 3011text of the copying permissions that appears in the printed manual. |
| 3106 | 3012 |
| 3107@cindex Titlepage, for plain text | 3013@cindex Title page, for plain text 3014@cindex Copyright page, for plain text |
| 3108You may wish to include titlepage-like information for plain text | 3015You may wish to include titlepage-like information for plain text |
| 3109output. Simply place any such leading material between @code{@@ifinfo} 3110and @code{@@end ifinfo}; @command{makeinfo} includes this in its plain 3111text output. It will not show up in the Info readers. | 3016output. Simply place any such leading material between 3017@code{@@ifplaintext} and @code{@@end ifplaintext}; @command{makeinfo} 3018includes this when writing plain text (@samp{--no-headers}), along with 3019an @code{@@insertcopying}. |
| 3112 | 3020 |
| 3113@xref{Documentation Copying, , GNU Free Documentation License}, for the 3114standard text for the copyright permissions. 3115 | |
| 3116@menu 3117* titlepage:: Create a title for the printed document. 3118* titlefont center sp:: The @code{@@titlefont}, @code{@@center}, 3119 and @code{@@sp} commands. 3120* title subtitle author:: The @code{@@title}, @code{@@subtitle}, 3121 and @code{@@author} commands. | 3021@menu 3022* titlepage:: Create a title for the printed document. 3023* titlefont center sp:: The @code{@@titlefont}, @code{@@center}, 3024 and @code{@@sp} commands. 3025* title subtitle author:: The @code{@@title}, @code{@@subtitle}, 3026 and @code{@@author} commands. |
| 3122* Copyright & Permissions:: How to write the copyright notice and | 3027* Copyright:: How to write the copyright notice and |
| 3123 include copying permissions. 3124* end titlepage:: Turn on page headings after the title and 3125 copyright pages. 3126* headings on off:: An option for turning headings on and off 3127 and double or single sided printing. 3128@end menu 3129 3130 | 3028 include copying permissions. 3029* end titlepage:: Turn on page headings after the title and 3030 copyright pages. 3031* headings on off:: An option for turning headings on and off 3032 and double or single sided printing. 3033@end menu 3034 3035 |
| 3131@node titlepage, titlefont center sp, Titlepage & Copyright Page, Titlepage & Copyright Page 3132@comment node-name, next, previous, up | 3036@node titlepage |
| 3133@subsection @code{@@titlepage} 3134@cindex Title page 3135@findex titlepage 3136 3137Start the material for the title page and following copyright page 3138with @code{@@titlepage} on a line by itself and end it with | 3037@subsection @code{@@titlepage} 3038@cindex Title page 3039@findex titlepage 3040 3041Start the material for the title page and following copyright page 3042with @code{@@titlepage} on a line by itself and end it with |
| 3139@code{@@end titlepage} on a line by itself.@refill | 3043@code{@@end titlepage} on a line by itself. |
| 3140 3141The @code{@@end titlepage} command starts a new page and turns on page 3142numbering. (@xref{Headings, , Page Headings}, for details about how to 3143generate page headings.) All the material that you want to appear on 3144unnumbered pages should be put between the @code{@@titlepage} and 3145@code{@@end titlepage} commands. You can force the table of contents to 3146appear there with the @code{@@setcontentsaftertitlepage} command 3147(@pxref{Contents}). --- 5 unchanged lines hidden (view full) --- 3153the copyright page is produced. (The @code{@@titlepage} command might 3154perhaps have been better named the @code{@@titleandadditionalpages} 3155command, but that would have been rather long!) 3156 3157When you write a manual about a computer program, you should write the 3158version of the program to which the manual applies on the title page. 3159If the manual changes more frequently than the program or is independent 3160of it, you should also include an edition number@footnote{We have found | 3044 3045The @code{@@end titlepage} command starts a new page and turns on page 3046numbering. (@xref{Headings, , Page Headings}, for details about how to 3047generate page headings.) All the material that you want to appear on 3048unnumbered pages should be put between the @code{@@titlepage} and 3049@code{@@end titlepage} commands. You can force the table of contents to 3050appear there with the @code{@@setcontentsaftertitlepage} command 3051(@pxref{Contents}). --- 5 unchanged lines hidden (view full) --- 3057the copyright page is produced. (The @code{@@titlepage} command might 3058perhaps have been better named the @code{@@titleandadditionalpages} 3059command, but that would have been rather long!) 3060 3061When you write a manual about a computer program, you should write the 3062version of the program to which the manual applies on the title page. 3063If the manual changes more frequently than the program or is independent 3064of it, you should also include an edition number@footnote{We have found |
| 3161that it is helpful to refer to versions of manuals as `editions' and 3162versions of programs as `versions'; otherwise, we find we are liable to 3163confuse each other in conversation by referring to both the 3164documentation and the software with the same words.} for the manual. | 3065that it is helpful to refer to versions of independent manuals as 3066`editions' and versions of programs as `versions'; otherwise, we find we 3067are liable to confuse each other in conversation by referring to both 3068the documentation and the software with the same words.} for the manual. |
| 3165This helps readers keep track of which manual is for which version of 3166the program. (The `Top' node should also contain this information; see | 3069This helps readers keep track of which manual is for which version of 3070the program. (The `Top' node should also contain this information; see |
| 3167@ref{makeinfo top, , @code{@@top}}.) | 3071@ref{The Top Node}.) |
| 3168 3169Texinfo provides two main methods for creating a title page. One method 3170uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands 3171to generate a title page in which the words on the page are 3172centered. 3173 3174The second method uses the @code{@@title}, @code{@@subtitle}, and 3175@code{@@author} commands to create a title page with black rules under --- 5 unchanged lines hidden (view full) --- 3181You may use either method, or you may combine them; see the examples in 3182the sections below. 3183 3184@findex shorttitlepage 3185@cindex Bastard title page 3186@cindex Title page, bastard 3187For extremely simple applications, and for the bastard title page in 3188traditional book front matter, Texinfo also provides a command | 3072 3073Texinfo provides two main methods for creating a title page. One method 3074uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands 3075to generate a title page in which the words on the page are 3076centered. 3077 3078The second method uses the @code{@@title}, @code{@@subtitle}, and 3079@code{@@author} commands to create a title page with black rules under --- 5 unchanged lines hidden (view full) --- 3085You may use either method, or you may combine them; see the examples in 3086the sections below. 3087 3088@findex shorttitlepage 3089@cindex Bastard title page 3090@cindex Title page, bastard 3091For extremely simple applications, and for the bastard title page in 3092traditional book front matter, Texinfo also provides a command |
| 3189@code{@@shorttitlepage} which takes a single argument as the title. The 3190argument is typeset on a page by itself and followed by a blank page. | 3093@code{@@shorttitlepage} which takes the rest of the line as the title. 3094The argument is typeset on a page by itself and followed by a blank 3095page. |
| 3191 3192 3193@node titlefont center sp 3194@subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp} 3195@findex titlefont 3196@findex center 3197@findex sp @r{(titlepage line spacing)} 3198 3199You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center} 3200commands to create a title page for a printed document. (This is the | 3096 3097 3098@node titlefont center sp 3099@subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp} 3100@findex titlefont 3101@findex center 3102@findex sp @r{(titlepage line spacing)} 3103 3104You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center} 3105commands to create a title page for a printed document. (This is the |
| 3201first of the two methods for creating a title page in Texinfo.)@refill | 3106first of the two methods for creating a title page in Texinfo.) |
| 3202 3203Use the @code{@@titlefont} command to select a large font suitable for 3204the title itself. You can use @code{@@titlefont} more than once if you 3205have an especially long title. 3206 3207@need 700 3208For example: 3209 3210@example 3211@@titlefont@{Texinfo@} 3212@end example 3213 3214Use the @code{@@center} command at the beginning of a line to center | 3107 3108Use the @code{@@titlefont} command to select a large font suitable for 3109the title itself. You can use @code{@@titlefont} more than once if you 3110have an especially long title. 3111 3112@need 700 3113For example: 3114 3115@example 3116@@titlefont@{Texinfo@} 3117@end example 3118 3119Use the @code{@@center} command at the beginning of a line to center |
| 3215the remaining text on that line. Thus,@refill | 3120the remaining text on that line. Thus, |
| 3216 3217@example 3218@@center @@titlefont@{Texinfo@} 3219@end example 3220 3221@noindent 3222centers the title, which in this example is ``Texinfo'' printed | 3121 3122@example 3123@@center @@titlefont@{Texinfo@} 3124@end example 3125 3126@noindent 3127centers the title, which in this example is ``Texinfo'' printed |
| 3223in the title font.@refill | 3128in the title font. |
| 3224 | 3129 |
| 3225Use the @code{@@sp} command to insert vertical space. For example:@refill | 3130Use the @code{@@sp} command to insert vertical space. For example: |
| 3226 3227@example 3228@@sp 2 3229@end example 3230 3231@noindent 3232This inserts two blank lines on the printed page. (@xref{sp, , 3233@code{@@sp}}, for more information about the @code{@@sp} | 3131 3132@example 3133@@sp 2 3134@end example 3135 3136@noindent 3137This inserts two blank lines on the printed page. (@xref{sp, , 3138@code{@@sp}}, for more information about the @code{@@sp} |
| 3234command.)@refill | 3139command.) |
| 3235 | 3140 |
| 3236A template for this method looks like this:@refill | 3141A template for this method looks like this: |
| 3237 3238@example 3239@group 3240@@titlepage 3241@@sp 10 3242@@center @@titlefont@{@var{name-of-manual-when-printed}@} 3243@@sp 2 3244@@center @var{subtitle-if-any} 3245@@sp 2 3246@@center @var{author} 3247@dots{} 3248@@end titlepage 3249@end group 3250@end example 3251 | 3142 3143@example 3144@group 3145@@titlepage 3146@@sp 10 3147@@center @@titlefont@{@var{name-of-manual-when-printed}@} 3148@@sp 2 3149@@center @var{subtitle-if-any} 3150@@sp 2 3151@@center @var{author} 3152@dots{} 3153@@end titlepage 3154@end group 3155@end example 3156 |
| 3252The spacing of the example fits an 8.5 by 11 inch manual.@refill | 3157The spacing of the example fits an 8.5 by 11 inch manual. |
| 3253 3254 3255@node title subtitle author 3256@subsection @code{@@title}, @code{@@subtitle}, and @code{@@author} 3257@findex title 3258@findex subtitle 3259@findex author 3260 3261You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author} 3262commands to create a title page in which the vertical and horizontal 3263spacing is done for you automatically. This contrasts with the method 3264described in the previous section, in which the @code{@@sp} command is 3265needed to adjust vertical spacing. 3266 3267Write the @code{@@title}, @code{@@subtitle}, or @code{@@author} 3268commands at the beginning of a line followed by the title, subtitle, | 3158 3159 3160@node title subtitle author 3161@subsection @code{@@title}, @code{@@subtitle}, and @code{@@author} 3162@findex title 3163@findex subtitle 3164@findex author 3165 3166You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author} 3167commands to create a title page in which the vertical and horizontal 3168spacing is done for you automatically. This contrasts with the method 3169described in the previous section, in which the @code{@@sp} command is 3170needed to adjust vertical spacing. 3171 3172Write the @code{@@title}, @code{@@subtitle}, or @code{@@author} 3173commands at the beginning of a line followed by the title, subtitle, |
| 3269or author.@refill | 3174or author. |
| 3270 3271The @code{@@title} command produces a line in which the title is set 3272flush to the left-hand side of the page in a larger than normal font. 3273The title is underlined with a black rule. Only a single line is 3274allowed; the @code{@@*} command may not be used to break the title into 3275two lines. To handle very long titles, you may find it profitable to 3276use both @code{@@title} and @code{@@titlefont}; see the final example in 3277this section. 3278 3279The @code{@@subtitle} command sets subtitles in a normal-sized font | 3175 3176The @code{@@title} command produces a line in which the title is set 3177flush to the left-hand side of the page in a larger than normal font. 3178The title is underlined with a black rule. Only a single line is 3179allowed; the @code{@@*} command may not be used to break the title into 3180two lines. To handle very long titles, you may find it profitable to 3181use both @code{@@title} and @code{@@titlefont}; see the final example in 3182this section. 3183 3184The @code{@@subtitle} command sets subtitles in a normal-sized font |
| 3280flush to the right-hand side of the page.@refill | 3185flush to the right-hand side of the page. |
| 3281 3282The @code{@@author} command sets the names of the author or authors in 3283a middle-sized font flush to the left-hand side of the page on a line 3284near the bottom of the title page. The names are underlined with a 3285black rule that is thinner than the rule that underlines the title. 3286(The black rule only occurs if the @code{@@author} command line is | 3186 3187The @code{@@author} command sets the names of the author or authors in 3188a middle-sized font flush to the left-hand side of the page on a line 3189near the bottom of the title page. The names are underlined with a 3190black rule that is thinner than the rule that underlines the title. 3191(The black rule only occurs if the @code{@@author} command line is |
| 3287followed by an @code{@@page} command line.)@refill | 3192followed by an @code{@@page} command line.) |
| 3288 3289There are two ways to use the @code{@@author} command: you can write 3290the name or names on the remaining part of the line that starts with | 3193 3194There are two ways to use the @code{@@author} command: you can write 3195the name or names on the remaining part of the line that starts with |
| 3291an @code{@@author} command:@refill | 3196an @code{@@author} command: |
| 3292 3293@example 3294@@author by Jane Smith and John Doe 3295@end example 3296 3297@noindent 3298or you can write the names one above each other by using two (or more) | 3197 3198@example 3199@@author by Jane Smith and John Doe 3200@end example 3201 3202@noindent 3203or you can write the names one above each other by using two (or more) |
| 3299@code{@@author} commands:@refill | 3204@code{@@author} commands: |
| 3300 3301@example 3302@group 3303@@author Jane Smith 3304@@author John Doe 3305@end group 3306@end example 3307 3308@noindent | 3205 3206@example 3207@group 3208@@author Jane Smith 3209@@author John Doe 3210@end group 3211@end example 3212 3213@noindent |
| 3309(Only the bottom name is underlined with a black rule.)@refill | 3214(Only the bottom name is underlined with a black rule.) |
| 3310 3311@need 950 | 3215 3216@need 950 |
| 3312A template for this method looks like this:@refill | 3217A template for this method looks like this: |
| 3313 3314@example 3315@group 3316@@titlepage 3317@@title @var{name-of-manual-when-printed} 3318@@subtitle @var{subtitle-if-any} 3319@@subtitle @var{second-subtitle} 3320@@author @var{author} --- 15 unchanged lines hidden (view full) --- 3336@@title for MS-Windows and MS-DOS 3337@@subtitle Edition @@value@{e@} for Release @@value@{cde@} 3338@@author by Daniel Hagerty, Melissa Weisshaus 3339@@author and Eli Zaretskii 3340@end group 3341@end example 3342 3343@noindent | 3218 3219@example 3220@group 3221@@titlepage 3222@@title @var{name-of-manual-when-printed} 3223@@subtitle @var{subtitle-if-any} 3224@@subtitle @var{second-subtitle} 3225@@author @var{author} --- 15 unchanged lines hidden (view full) --- 3241@@title for MS-Windows and MS-DOS 3242@@subtitle Edition @@value@{e@} for Release @@value@{cde@} 3243@@author by Daniel Hagerty, Melissa Weisshaus 3244@@author and Eli Zaretskii 3245@end group 3246@end example 3247 3248@noindent |
| 3344(The use of @code{@@value} here is explained in @ref{value 3345Example,,@code{@@value} Example}.) | 3249(The use of @code{@@value} here is explained in @ref{value Example}. |
| 3346 3347 | 3250 3251 |
| 3348@node Copyright & Permissions 3349@subsection Copyright Page and Permissions | 3252@node Copyright 3253@subsection Copyright Page |
| 3350@cindex Copyright page 3351@cindex Printed permissions 3352@cindex Permissions, printed 3353 | 3254@cindex Copyright page 3255@cindex Printed permissions 3256@cindex Permissions, printed 3257 |
| 3354By international treaty, the copyright notice for a book should be 3355either on the title page or on the back of the title page. The 3356copyright notice should include the year followed by the name of the 3357organization or person who owns the copyright.@refill | 3258By international treaty, the copyright notice for a book must be either 3259on the title page or on the back of the title page. When the copyright 3260notice is on the back of the title page, that page is customarily not 3261numbered. Therefore, in Texinfo, the information on the copyright page 3262should be within @code{@@titlepage} and @code{@@end titlepage} 3263commands. |
| 3358 | 3264 |
| 3359When the copyright notice is on the back of the title page, that page 3360is customarily not numbered. Therefore, in Texinfo, the information 3361on the copyright page should be within @code{@@titlepage} and 3362@code{@@end titlepage} commands.@refill 3363 3364@findex vskip 3365@findex filll 3366@cindex Vertical whitespace (@samp{vskip}) | 3265@findex vskip @r{@TeX{} vertical skip} 3266@findex filll @r{@TeX{} dimension} |
| 3367Use the @code{@@page} command to cause a page break. To push the 3368copyright notice and the other text on the copyright page towards the | 3267Use the @code{@@page} command to cause a page break. To push the 3268copyright notice and the other text on the copyright page towards the |
| 3369bottom of the page, you can write a somewhat mysterious line after the 3370@code{@@page} command that reads like this:@refill | 3269bottom of the page, use the following incantantion after @code{@@page}: |
| 3371 3372@example 3373@@vskip 0pt plus 1filll 3374@end example 3375 3376@noindent 3377This is a @TeX{} command that is not supported by the Info formatting | 3270 3271@example 3272@@vskip 0pt plus 1filll 3273@end example 3274 3275@noindent 3276This is a @TeX{} command that is not supported by the Info formatting |
| 3378commands. The @code{@@vskip} command inserts whitespace. The 3379@samp{0pt plus 1filll} means to put in zero points of mandatory whitespace, 3380and as much optional whitespace as needed to push the 3381following text to the bottom of the page. Note the use of three 3382@samp{l}s in the word @samp{filll}; this is the correct usage in 3383@TeX{}.@refill | 3277commands. The @code{@@vskip} command inserts whitespace. The @samp{0pt 3278plus 1filll} means to put in zero points of mandatory whitespace, and as 3279much optional whitespace as needed to push the following text to the 3280bottom of the page. Note the use of three @samp{l}s in the word 3281@samp{filll}; this is correct. |
| 3384 | 3282 |
| 3385@findex copyright 3386In a printed manual, the @code{@@copyright@{@}} command generates a 3387@samp{c} inside a circle. (In Info, it generates @samp{(C)}.) The 3388copyright notice itself has the following legally defined sequence:@refill | 3283To insert the copyright text itself, write @code{@@insertcopying} 3284next (@pxref{Document Permissions}): |
| 3389 3390@example | 3285 3286@example |
| 3391Copyright @copyright{} @var{year} @var{copyright-owner} | 3287@@insertcopying |
| 3392@end example 3393 | 3288@end example 3289 |
| 3394It is customary to put information on how to get a manual after the 3395copyright notice, followed by the copying permissions for the manual. | 3290Follow the copying text by the publisher, ISBN numbers, cover art 3291credits, and other such information. |
| 3396 | 3292 |
| 3397Permissions must be given here as well as in the summary segment within 3398@code{@@ifinfo} and @code{@@end ifinfo} that immediately follows the 3399header since this text appears only in the printed manual and the 3400@samp{ifinfo} text appears only in the Info file. | 3293Here is an example putting all this together: |
| 3401 | 3294 |
| 3402@xref{Documentation Copying,,GNU Free Documentation License}, for the 3403standard text. | 3295@example 3296@@titlepage 3297@dots{} 3298@@page 3299@@vskip 0pt plus 1filll 3300@@insertcopying |
| 3404 | 3301 |
| 3302Published by @dots{} |
|
| 3405 | 3303 |
| 3304Cover art by @dots{} 3305@@end titlepage 3306@end example 3307 3308 |
|
| 3406@node end titlepage 3407@subsection Heading Generation 3408@findex end titlepage 3409@cindex Headings, page, begin to appear 3410@cindex Titlepage end starts headings 3411@cindex End titlepage starts headings 3412 | 3309@node end titlepage 3310@subsection Heading Generation 3311@findex end titlepage 3312@cindex Headings, page, begin to appear 3313@cindex Titlepage end starts headings 3314@cindex End titlepage starts headings 3315 |
| 3413An @code{@@end titlepage} command on a line by itself not only marks 3414the end of the title and copyright pages, but also causes @TeX{} to start 3415generating page headings and page numbers. | 3316The @code{@@end titlepage} command must be written on a line by itself. 3317It not only marks the end of the title and copyright pages, but also 3318causes @TeX{} to start generating page headings and page numbers. |
| 3416 3417To repeat what is said elsewhere, Texinfo has two standard page heading 3418formats, one for documents which are printed on one side of each sheet of paper 3419(single-sided printing), and the other for documents which are printed on both 3420sides of each sheet (double-sided printing). | 3319 3320To repeat what is said elsewhere, Texinfo has two standard page heading 3321formats, one for documents which are printed on one side of each sheet of paper 3322(single-sided printing), and the other for documents which are printed on both 3323sides of each sheet (double-sided printing). |
| 3421(@xref{setchapternewpage, ,@code{@@setchapternewpage}}.) 3422You can specify these formats in different ways:@refill | 3324You can specify these formats in different ways: |
| 3423 3424@itemize @bullet 3425@item 3426The conventional way is to write an @code{@@setchapternewpage} command 3427before the title page commands, and then have the @code{@@end 3428titlepage} command start generating page headings in the manner desired. | 3325 3326@itemize @bullet 3327@item 3328The conventional way is to write an @code{@@setchapternewpage} command 3329before the title page commands, and then have the @code{@@end 3330titlepage} command start generating page headings in the manner desired. |
| 3429(@xref{setchapternewpage, , @code{@@setchapternewpage}}.)@refill | 3331(@xref{setchapternewpage}.) |
| 3430 3431@item 3432Alternatively, you can use the @code{@@headings} command to prevent page 3433headings from being generated or to start them for either single or 3434double-sided printing. (Write an @code{@@headings} command immediately 3435after the @code{@@end titlepage} command. @xref{headings on off, , The 3436@code{@@headings} Command}, for more information.)@refill 3437 3438@item 3439Or, you may specify your own page heading and footing format. 3440@xref{Headings, , Page Headings}, for detailed | 3332 3333@item 3334Alternatively, you can use the @code{@@headings} command to prevent page 3335headings from being generated or to start them for either single or 3336double-sided printing. (Write an @code{@@headings} command immediately 3337after the @code{@@end titlepage} command. @xref{headings on off, , The 3338@code{@@headings} Command}, for more information.)@refill 3339 3340@item 3341Or, you may specify your own page heading and footing format. 3342@xref{Headings, , Page Headings}, for detailed |
| 3441information about page headings and footings.@refill | 3343information about page headings and footings. |
| 3442@end itemize 3443 3444Most documents are formatted with the standard single-sided or 3445double-sided format, using @code{@@setchapternewpage odd} for 3446double-sided printing and no @code{@@setchapternewpage} command for | 3344@end itemize 3345 3346Most documents are formatted with the standard single-sided or 3347double-sided format, using @code{@@setchapternewpage odd} for 3348double-sided printing and no @code{@@setchapternewpage} command for |
| 3447single-sided printing.@refill | 3349single-sided printing. |
| 3448 | 3350 |
| 3449@node headings on off, , end titlepage, Titlepage & Copyright Page 3450@comment node-name, next, previous, up | 3351 3352@node headings on off |
| 3451@subsection The @code{@@headings} Command 3452@findex headings 3453 3454The @code{@@headings} command is rarely used. It specifies what kind of 3455page headings and footings to print on each page. Usually, this is 3456controlled by the @code{@@setchapternewpage} command. You need the 3457@code{@@headings} command only if the @code{@@setchapternewpage} command 3458does not do what you want, or if you want to turn off pre-defined page --- 48 unchanged lines hidden (view full) --- 3507headings.@refill 3508 3509You can also specify your own style of page heading and footing. 3510@xref{Headings, , Page Headings}, for more information.@refill 3511 3512 3513@node The Top Node 3514@section The `Top' Node and Master Menu | 3353@subsection The @code{@@headings} Command 3354@findex headings 3355 3356The @code{@@headings} command is rarely used. It specifies what kind of 3357page headings and footings to print on each page. Usually, this is 3358controlled by the @code{@@setchapternewpage} command. You need the 3359@code{@@headings} command only if the @code{@@setchapternewpage} command 3360does not do what you want, or if you want to turn off pre-defined page --- 48 unchanged lines hidden (view full) --- 3409headings.@refill 3410 3411You can also specify your own style of page heading and footing. 3412@xref{Headings, , Page Headings}, for more information.@refill 3413 3414 3415@node The Top Node 3416@section The `Top' Node and Master Menu |
| 3515@cindex @samp{@r{Top}} node 3516@cindex Master menu | 3417@cindex Top node |
| 3517@cindex Node, `Top' 3518 | 3418@cindex Node, `Top' 3419 |
| 3519The `Top' node is the node from which you enter an Info file.@refill | 3420The `Top' node is the node in which a reader enters an Info manual. As 3421such, it should begin with the @code{@@insertcopying} command 3422(@pxref{Document Permissions}) to provide a brief description of the 3423manual (including the version number) and copying permissions, and end 3424with a master menu for the whole manual. Of course you should include 3425any other general information you feel a reader would find helpful. |
| 3520 | 3426 |
| 3521A `Top' node should contain a brief description of the Info file and an 3522extensive, master menu for the whole Info file. 3523This helps the reader understand what the Info file is 3524about. Also, you should write the version number of the program to 3525which the Info file applies; or, at least, the edition number.@refill | 3427@findex top 3428It is also conventional to write an @code{@@top} sectioning command line 3429containing the title of the document immediately after the @code{@@node 3430Top} line (@pxref{makeinfo top command, , The @code{@@top} Sectioning 3431Command}). |
| 3526 | 3432 |
| 3527The contents of the `Top' node should appear only in the Info file; none 3528of it should appear in printed output, so enclose it between 3529@code{@@ifinfo} and @code{@@end ifinfo} commands. (@TeX{} does not | 3433The contents of the `Top' node should appear only in the online output; 3434none of it should appear in printed output, so enclose it between 3435@code{@@ifnottex} and @code{@@end ifnottex} commands. (@TeX{} does not |
| 3530print either an @code{@@node} line or a menu; they appear only in Info; 3531strictly speaking, you are not required to enclose these parts between | 3436print either an @code{@@node} line or a menu; they appear only in Info; 3437strictly speaking, you are not required to enclose these parts between |
| 3532@code{@@ifinfo} and @code{@@end ifinfo}, but it is simplest to do so. 3533@xref{Conditionals, , Conditionally Visible Text}.)@refill | 3438@code{@@ifnottex} and @code{@@end ifnottext}, but it is simplest to do 3439so. @xref{Conditionals, , Conditionally Visible Text}.) |
| 3534 3535@menu | 3440 3441@menu |
| 3536* Title of Top Node:: Sketch what the file is about. 3537* Master Menu Parts:: A master menu has three or more parts. | 3442* Top Node Example:: 3443* Master Menu Parts:: |
| 3538@end menu 3539 3540 | 3444@end menu 3445 3446 |
| 3541@node Title of Top Node 3542@subsection `Top' Node Title | 3447@node Top Node Example 3448@subsection Top Node Example |
| 3543 | 3449 |
| 3544Sometimes, you will want to place an @code{@@top} sectioning command 3545line containing the title of the document immediately after the 3546@code{@@node Top} line (@pxref{makeinfo top command, , The @code{@@top} 3547Sectioning Command}, for more information).@refill | 3450@cindex Top node example |
| 3548 | 3451 |
| 3549For example, the beginning of the Top node of this manual contains an 3550@code{@@top} sectioning command, a short description, and edition and 3551version information. It looks like this:@refill | 3452Here is an example of a Top node. |
| 3552 3553@example 3554@group | 3453 3454@example 3455@group |
| 3555@dots{} 3556@@end titlepage 3557 | |
| 3558@@ifnottex | 3456@@ifnottex |
| 3559@@node Top, Copying, , (dir) 3560@@top Texinfo | 3457@@node Top 3458@@top Sample Title |
| 3561 | 3459 |
| 3562Texinfo is a documentation system@dots{} | 3460@@insertcopying |
| 3563@end group 3564 | 3461@end group 3462 |
| 3565@group 3566This is edition@dots{} 3567@dots{} 3568@@end ifnottex 3569@end group | 3463Additional general information. |
| 3570 3571@group 3572@@menu | 3464 3465@group 3466@@menu |
| 3573* Copying:: Texinfo is freely 3574 redistributable. 3575* Overview:: What is Texinfo? | 3467* First Chapter:: 3468* Second Chapter:: |
| 3576@dots{} | 3469@dots{} |
| 3470* Index:: |
|
| 3577@end group 3578@@end menu 3579@end example 3580 | 3471@end group 3472@@end menu 3473@end example 3474 |
| 3581In a `Top' node, the `Previous', and `Up' nodes usually refer to the top 3582level directory of the whole Info system, which is called @samp{(dir)}. 3583The `Next' node refers to the first node that follows the main or master 3584menu, which is usually the copying permissions, introduction, or first 3585chapter.@refill | |
| 3586 | 3475 |
| 3587@node Master Menu Parts, , Title of Top Node, The Top Node | 3476@node Master Menu Parts |
| 3588@subsection Parts of a Master Menu | 3477@subsection Parts of a Master Menu |
| 3589@cindex Master menu parts | 3478@cindex Master menu 3479@cindex Menu, master |
| 3590@cindex Parts of a master menu 3591 3592A @dfn{master menu} is a detailed main menu listing all the nodes in a 3593file. 3594 3595A master menu is enclosed in @code{@@menu} and @code{@@end menu} | 3480@cindex Parts of a master menu 3481 3482A @dfn{master menu} is a detailed main menu listing all the nodes in a 3483file. 3484 3485A master menu is enclosed in @code{@@menu} and @code{@@end menu} |
| 3596commands and does not appear in the printed document.@refill | 3486commands and does not appear in the printed document. |
| 3597 | 3487 |
| 3598Generally, a master menu is divided into parts.@refill | 3488Generally, a master menu is divided into parts. |
| 3599 3600@itemize @bullet 3601@item 3602The first part contains the major nodes in the Texinfo file: the nodes | 3489 3490@itemize @bullet 3491@item 3492The first part contains the major nodes in the Texinfo file: the nodes |
| 3603for the chapters, chapter-like sections, and the appendices.@refill | 3493for the chapters, chapter-like sections, and the appendices. |
| 3604 3605@item | 3494 3495@item |
| 3606The second part contains nodes for the indices.@refill | 3496The second part contains nodes for the indices. |
| 3607 3608@item 3609The third and subsequent parts contain a listing of the other, lower 3610level nodes, often ordered by chapter. This way, rather than go 3611through an intermediary menu, an inquirer can go directly to a 3612particular node when searching for specific information. These menu 3613items are not required; add them if you think they are a 3614convenience. If you do use them, put @code{@@detailmenu} before the 3615first one, and @code{@@end detailmenu} after the last; otherwise, 3616@code{makeinfo} will get confused. 3617@end itemize 3618 3619Each section in the menu can be introduced by a descriptive line. So 3620long as the line does not begin with an asterisk, it will not be 3621treated as a menu entry. (@xref{Writing a Menu}, for more | 3497 3498@item 3499The third and subsequent parts contain a listing of the other, lower 3500level nodes, often ordered by chapter. This way, rather than go 3501through an intermediary menu, an inquirer can go directly to a 3502particular node when searching for specific information. These menu 3503items are not required; add them if you think they are a 3504convenience. If you do use them, put @code{@@detailmenu} before the 3505first one, and @code{@@end detailmenu} after the last; otherwise, 3506@code{makeinfo} will get confused. 3507@end itemize 3508 3509Each section in the menu can be introduced by a descriptive line. So 3510long as the line does not begin with an asterisk, it will not be 3511treated as a menu entry. (@xref{Writing a Menu}, for more |
| 3622information.)@refill | 3512information.) |
| 3623 3624For example, the master menu for this manual looks like the following | 3513 3514For example, the master menu for this manual looks like the following |
| 3625(but has many more entries):@refill | 3515(but has many more entries): |
| 3626 3627@example 3628@group 3629@@menu | 3516 3517@example 3518@group 3519@@menu |
| 3630* Copying:: Texinfo is freely 3631 redistributable. 3632* Overview:: What is Texinfo? 3633* Texinfo Mode:: Special features in GNU Emacs. | 3520* Copying Conditions:: Your rights. 3521* Overview:: Texinfo in brief. |
| 3634@dots{} | 3522@dots{} |
| 3635@dots{} | |
| 3636@end group 3637@group 3638* Command and Variable Index:: | 3523@end group 3524@group 3525* Command and Variable Index:: |
| 3639 An entry for each @@-command. 3640* Concept Index:: An entry for each concept. | 3526* Concept Index:: |
| 3641@end group 3642 3643@group 3644@@detailmenu 3645 --- The Detailed Node Listing --- 3646 3647Overview of Texinfo 3648 | 3527@end group 3528 3529@group 3530@@detailmenu 3531 --- The Detailed Node Listing --- 3532 3533Overview of Texinfo 3534 |
| 3649* Info Files:: What is an Info file? 3650* Printed Manuals:: Characteristics of 3651 a printed manual. | 3535* Reporting Bugs:: @dots{} |
| 3652@dots{} | 3536@dots{} |
| 3653@dots{} | |
| 3654@end group 3655 3656@group | 3537@end group 3538 3539@group |
| 3657Using Texinfo Mode | 3540Beginning a Texinfo File |
| 3658 | 3541 |
| 3659* Info on a Region:: Formatting part of a file 3660 for Info. | 3542* Sample Beginning:: @dots{} |
| 3661@dots{} | 3543@dots{} |
| 3662@dots{} | |
| 3663@@end detailmenu 3664@@end menu 3665@end group 3666@end example 3667 | 3544@@end detailmenu 3545@@end menu 3546@end group 3547@end example 3548 |
| 3549 3550@node Global Document Commands 3551@section Global Document Commands 3552@cindex Global Document Commands 3553 3554Besides the basic commands mentioned in the previous sections, here are 3555additional commands which affect the document as a whole. They are 3556generally all given before the Top node, if they are given at all. 3557 3558@menu 3559* documentdescription:: Document summary for the HTML output. 3560* setchapternewpage:: Start chapters on right-hand pages. 3561* paragraphindent:: Specify paragraph indentation. 3562* exampleindent:: Specify environment indentation. 3563@end menu 3564 3565 3566@node documentdescription 3567@subsection @code{@@documentdescription}: Summary text 3568@cindex Document description 3569@cindex Description of document 3570@cindex Summary of document 3571@cindex Abstract of document 3572@cindex <meta> HTML tag, and document description 3573@findex documentdescription 3574 3575When producing HTML output for a document, @command{makeinfo} writes a 3576@samp{<meta>} element in the @samp{<head>} to give some idea of the 3577content of the document. By default, this @dfn{description} is the title 3578of the document, taken from the @code{@@settitle} command 3579(@pxref{settitle}). To change this, use the @code{@@documentdescription} 3580environment, as in: 3581 3582@example 3583@@documentdescription 3584descriptive text. 3585@@end documentdescription 3586@end example 3587 3588@noindent 3589This will produce the following output in the @samp{<head>} of the HTML: 3590 3591@example 3592<meta name=description content="descriptive text."> 3593@end example 3594 3595@code{@@documentdescription} must be specified before the first node of 3596the document. 3597 3598 3599@node setchapternewpage 3600@subsection @code{@@setchapternewpage}: 3601@cindex Starting chapters 3602@cindex Pages, starting odd 3603@findex setchapternewpage 3604 3605In an officially bound book, text is usually printed on both sides of 3606the paper, chapters start on right-hand pages, and right-hand pages have 3607odd numbers. But in short reports, text often is printed only on one 3608side of the paper. Also in short reports, chapters sometimes do not 3609start on new pages, but are printed on the same page as the end of the 3610preceding chapter, after a small amount of vertical whitespace. 3611 3612You can use the @code{@@setchapternewpage} command with various 3613arguments to specify how @TeX{} should start chapters and whether it 3614should format headers for printing on one or both sides of the paper 3615(single-sided or double-sided printing). 3616 3617Write the @code{@@setchapternewpage} command at the beginning of a 3618line followed by its argument. 3619 3620For example, you would write the following to cause each chapter to 3621start on a fresh odd-numbered page: 3622 3623@example 3624@@setchapternewpage odd 3625@end example 3626 3627You can specify one of three alternatives with the 3628@code{@@setchapternewpage} command: 3629 3630@table @asis 3631 3632@item @code{@@setchapternewpage off} 3633Cause @TeX{} to typeset a new chapter on the same page as the last 3634chapter, after skipping some vertical whitespace. Also, cause @TeX{} to 3635format page headers for single-sided printing. 3636 3637@item @code{@@setchapternewpage on} 3638Cause @TeX{} to start new chapters on new pages and to format page 3639headers for single-sided printing. This is the form most often used for 3640short reports or personal printing. This is the default. 3641 3642@item @code{@@setchapternewpage odd} 3643Cause @TeX{} to start new chapters on new, odd-numbered pages 3644(right-handed pages) and to typeset for double-sided printing. This is 3645the form most often used for books and manuals. 3646@end table 3647 3648Texinfo does not have an @code{@@setchapternewpage even} command, 3649because there is no printing tradition of starting chapters or books on 3650an even-numbered page. 3651 3652If you don't like the default headers that @code{@@setchapternewpage} 3653sets, you can explicit control them with the @code{@@headings} command. 3654@xref{headings on off, , The @code{@@headings} Command}. 3655 3656At the beginning of a manual or book, pages are not numbered---for 3657example, the title and copyright pages of a book are not numbered. By 3658convention, table of contents and frontmatter pages are numbered with 3659roman numerals and not in sequence with the rest of the document. 3660 3661Since an Info file does not have pages, the @code{@@setchapternewpage} 3662command has no effect on it. 3663 3664We recommend not including any @code{@@setchapternewpage} command in 3665your manual sources at all, since the desired output is not intrinsic to 3666the document. For a particular hard copy run, if you don't want the 3667default option (no blank pages, same headers on all pages) use the 3668@option{--texinfo} option to @command{texi2dvi} to specify the output 3669you want. 3670 3671 3672@node paragraphindent 3673@subsection Paragraph Indenting 3674@cindex Indenting paragraphs, control of 3675@cindex Paragraph indentation control 3676@findex paragraphindent 3677 3678The Texinfo processors may insert whitespace at the beginning of the 3679first line of each paragraph, thereby indenting that paragraph. You can 3680use the @code{@@paragraphindent} command to specify this indentation. 3681Write an @code{@@paragraphindent} command at the beginning of a line 3682followed by either @samp{asis} or a number: 3683 3684@example 3685@@paragraphindent @var{indent} 3686@end example 3687 3688The indentation is according to the value of @var{indent}: 3689 3690@table @asis 3691@item @code{asis} 3692Do not change the existing indentation (not implemented in @TeX{}). 3693 3694@item @code{none} 3695@itemx 0 3696Omit all indentation. 3697 3698@item @var{n} 3699Indent by @var{n} space characters in Info output, by @var{n} ems in 3700@TeX{}. 3701 3702@end table 3703 3704The default value of @var{indent} is 3. @code{@@paragraphindent} is 3705ignored for HTML output. 3706 3707It is best to write the @code{@@paragraphindent} command before the 3708end-of-header line at the beginning of a Texinfo file, so the region 3709formatting commands indent paragraphs as specified. @xref{Start of 3710Header}. 3711 3712A peculiarity of the @code{texinfo-format-buffer} and 3713@code{texinfo-format-region} commands is that they do not indent (nor 3714fill) paragraphs that contain @code{@@w} or @code{@@*} commands. 3715@xref{Refilling Paragraphs}, for further information. 3716 3717 3718@node exampleindent 3719@subsection @code{@@exampleindent}: Environment Indenting 3720@cindex Indenting environments 3721@cindex Environment indentation 3722@cindex Example indentation 3723@findex exampleindent 3724 3725The Texinfo processors indent each line of @code{@@example} and similar 3726environments. You can use the @code{@@exampleindent} command to specify 3727this indentation. Write an @code{@@exampleindent} command at the 3728beginning of a line followed by either @samp{asis} or a number: 3729 3730@example 3731@@exampleindent @var{indent} 3732@end example 3733 3734The indentation is according to the value of @var{indent}: 3735 3736@table @asis 3737@item @code{asis} 3738Do not change the existing indentation (not implemented in @TeX{}). 3739 3740@item 0 3741Omit all indentation. 3742 3743@item @var{n} 3744Indent environments by @var{n} space characters in Info output, by 3745@var{n} ems in @TeX{}. 3746 3747@end table 3748 3749The default value of @var{indent} is 5. @code{@@exampleindent} is 3750ignored for HTML output. 3751 3752It is best to write the @code{@@exampleindent} command before the 3753end-of-header line at the beginning of a Texinfo file, so the region 3754formatting commands indent paragraphs as specified. @xref{Start of 3755Header}. 3756 3757 |
|
| 3668@node Software Copying Permissions | 3758@node Software Copying Permissions |
| 3669@comment node-name, next, previous, up | |
| 3670@section Software Copying Permissions 3671@cindex Software copying permissions 3672@cindex Copying software 3673@cindex Distribution 3674@cindex License agreement 3675 3676If the Texinfo file has a section containing the ``General Public | 3759@section Software Copying Permissions 3760@cindex Software copying permissions 3761@cindex Copying software 3762@cindex Distribution 3763@cindex License agreement 3764 3765If the Texinfo file has a section containing the ``General Public |
| 3677License'' and the distribution information and a warranty disclaimer 3678for the software that is documented, this section usually follows the 3679`Top' node. The General Public License is very important to Project | 3766License'' and the distribution information and a warranty disclaimer for 3767the software that is documented, we recommend placing this right after 3768the `Top' node. The General Public License is very important to Project |
| 3680GNU software. It ensures that you and others will continue to have a | 3769GNU software. It ensures that you and others will continue to have a |
| 3681right to use and share the software.@refill | 3770right to use and share the software. |
| 3682 3683The copying and distribution information and the disclaimer are followed | 3771 3772The copying and distribution information and the disclaimer are followed |
| 3684by an introduction or else by the first chapter of the manual.@refill | 3773by an introduction or else by the first chapter of the manual. |
| 3685 3686@cindex Introduction, as part of file 3687Although an introduction is not a required part of a Texinfo file, it 3688is very helpful. Ideally, it should state clearly and concisely what 3689the file is about and who would be interested in reading it. In 3690general, an introduction would follow the licensing and distribution 3691information, although sometimes people put it earlier in the document. | 3774 3775@cindex Introduction, as part of file 3776Although an introduction is not a required part of a Texinfo file, it 3777is very helpful. Ideally, it should state clearly and concisely what 3778the file is about and who would be interested in reading it. In 3779general, an introduction would follow the licensing and distribution 3780information, although sometimes people put it earlier in the document. |
| 3692Usually, an introduction is put in an @code{@@unnumbered} section. 3693(@xref{unnumbered & appendix, , The @code{@@unnumbered} and 3694@code{@@appendix} Commands}.)@refill | |
| 3695 | 3781 |
| 3696@node Ending a File, Structuring, Beginning a File, Top 3697@comment node-name, next, previous, up | 3782 3783@node Ending a File |
| 3698@chapter Ending a Texinfo File 3699@cindex Ending a Texinfo file 3700@cindex Texinfo file ending 3701@cindex File ending 3702@findex bye 3703 3704The end of a Texinfo file should include commands to create indices and | 3784@chapter Ending a Texinfo File 3785@cindex Ending a Texinfo file 3786@cindex Texinfo file ending 3787@cindex File ending 3788@findex bye 3789 3790The end of a Texinfo file should include commands to create indices and |
| 3705(usually) to generate detailed and summary tables of contents. And it 3706must include the @code{@@bye} command that marks the last line processed 3707by @TeX{}.@refill | 3791(perhaps) to generate both the full and summary tables of contents. 3792Finally, it must include the @code{@@bye} command that marks the last 3793line to be processed. |
| 3708 3709@need 700 3710For example: 3711 3712@example | 3794 3795@need 700 3796For example: 3797 3798@example |
| 3713@@node Concept Index, , Variables Index, Top 3714@@c node-name, next, previous, up 3715@@unnumbered Concept Index | 3799@@node Index 3800@@unnumbered Index |
| 3716 3717@@printindex cp 3718 | 3801 3802@@printindex cp 3803 |
| 3804@@shortcontents |
|
| 3719@@contents | 3805@@contents |
| 3806 |
|
| 3720@@bye 3721@end example 3722 3723@menu 3724* Printing Indices & Menus:: How to print an index in hardcopy and 3725 generate index menus in Info. 3726* Contents:: How to create a table of contents. 3727* File End:: How to mark the end of a file. 3728@end menu 3729 | 3807@@bye 3808@end example 3809 3810@menu 3811* Printing Indices & Menus:: How to print an index in hardcopy and 3812 generate index menus in Info. 3813* Contents:: How to create a table of contents. 3814* File End:: How to mark the end of a file. 3815@end menu 3816 |
| 3730@node Printing Indices & Menus, Contents, Ending a File, Ending a File 3731@comment node-name, next, previous, up 3732@section Index Menus and Printing an Index | 3817 3818@node Printing Indices & Menus 3819@section Printing Indices and Menus |
| 3733@findex printindex 3734@cindex Printing an index 3735@cindex Indices, printing and menus 3736@cindex Generating menus with indices 3737@cindex Menus generated with indices 3738 | 3820@findex printindex 3821@cindex Printing an index 3822@cindex Indices, printing and menus 3823@cindex Generating menus with indices 3824@cindex Menus generated with indices 3825 |
| 3739To print an index means to include it as part of a manual or Info 3740file. This does not happen automatically just because you use 3741@code{@@cindex} or other index-entry generating commands in the 3742Texinfo file; those just cause the raw data for the index to be 3743accumulated. To generate an index, you must include the 3744@code{@@printindex} command at the place in the document where you 3745want the index to appear. Also, as part of the process of creating a 3746printed manual, you must run a program called @code{texindex} 3747(@pxref{Hardcopy}) to sort the raw data to produce a sorted 3748index file. The sorted index file is what is actually used to 3749print the index.@refill | 3826To print an index means to include it as part of a manual or Info file. 3827This does not happen automatically just because you use @code{@@cindex} 3828or other index-entry generating commands in the Texinfo file; those just 3829cause the raw data for the index to be accumulated. To generate an 3830index, you must include the @code{@@printindex} command at the place in 3831the document where you want the index to appear. Also, as part of the 3832process of creating a printed manual, you must run a program called 3833@code{texindex} (@pxref{Hardcopy}) to sort the raw data to produce a 3834sorted index file. The sorted index file is what is actually used to 3835print the index. |
| 3750 | 3836 |
| 3751Texinfo offers six different types of predefined index: the concept 3752index, the function index, the variables index, the keystroke index, the 3753program index, and the data type index (@pxref{Predefined Indices}). Each 3754index type has a two-letter name: @samp{cp}, @samp{fn}, @samp{vr}, 3755@samp{ky}, @samp{pg}, and @samp{tp}. You may merge indices, or put them 3756into separate sections (@pxref{Combining Indices}); or you may define 3757your own indices (@pxref{New Indices, , Defining New Indices}).@refill | 3837Texinfo offers six separate types of predefined index, each with a 3838two-letter abbreviation, as illustrated in the following table. 3839However, you may merge indices (@pxref{Combining Indices}) or define 3840your own indices (@pxref{New Indices}). |
| 3758 | 3841 |
| 3759The @code{@@printindex} command takes a two-letter index name, reads 3760the corresponding sorted index file and formats it appropriately into 3761an index.@refill | 3842Here are the predefined indices, their abbreviations, and the 3843corresponding index entry commands: |
| 3762 | 3844 |
| 3763@ignore 3764The two-letter index names are: 3765 | |
| 3766@table @samp 3767@item cp | 3845@table @samp 3846@item cp |
| 3768concept index | 3847concept index (@code{@@cindex}) |
| 3769@item fn | 3848@item fn |
| 3770function index | 3849function index (@code{@@findex}) |
| 3771@item vr | 3850@item vr |
| 3772variable index | 3851variable index (@code{@@index}) |
| 3773@item ky | 3852@item ky |
| 3774key index | 3853key index (@code{@@kindex}) |
| 3775@item pg | 3854@item pg |
| 3776program index | 3855program index (@code{@@pindex}) |
| 3777@item tp | 3856@item tp |
| 3778data type index | 3857data type index (@code{@@tindex}) |
| 3779@end table | 3858@end table |
| 3780@end ignore 3781The @code{@@printindex} command does not generate a chapter heading 3782for the index. Consequently, you should precede the 3783@code{@@printindex} command with a suitable section or chapter command 3784(usually @code{@@unnumbered}) to supply the chapter heading and put 3785the index into the table of contents. Precede the @code{@@unnumbered} 3786command with an @code{@@node} line.@refill | |
| 3787 | 3859 |
| 3788@need 1200 | 3860The @code{@@printindex} command takes a two-letter index abbreviation, 3861reads the corresponding sorted index file and formats it appropriately 3862into an index. 3863 3864The @code{@@printindex} command does not generate a chapter heading for 3865the index. Consequently, you should precede the @code{@@printindex} 3866command with a suitable section or chapter command (usually 3867@code{@@appendix} or @code{@@unnumbered}) to supply the chapter heading 3868and put the index into the table of contents. Precede the 3869@code{@@unnumbered} command with an @code{@@node} line. 3870 |
| 3789For example: 3790 3791@smallexample 3792@group | 3871For example: 3872 3873@smallexample 3874@group |
| 3793@@node Variable Index, Concept Index, Function Index, Top 3794@@comment node-name, next, previous, up | 3875@@node Variable Index |
| 3795@@unnumbered Variable Index 3796 3797@@printindex vr 3798@end group 3799 3800@group | 3876@@unnumbered Variable Index 3877 3878@@printindex vr 3879@end group 3880 3881@group |
| 3801@@node Concept Index, , Variable Index, Top 3802@@comment node-name, next, previous, up | 3882@@node Concept Index |
| 3803@@unnumbered Concept Index 3804 3805@@printindex cp 3806@end group 3807@end smallexample 3808 3809@noindent | 3883@@unnumbered Concept Index 3884 3885@@printindex cp 3886@end group 3887@end smallexample 3888 3889@noindent |
| 3810Readers often prefer that the concept index come last in a book, 3811since that makes it easiest to find. Having just one index helps 3812readers also, since then they have only one place to look 3813(@pxref{synindex}). | |
| 3814 | 3890 |
| 3891We recommend placing the concept index last, since that makes it easiest 3892to find. We also recommend having a single index whenever possible, 3893since then readers have only one place to look (@pxref{Combining Indices}). |
|
| 3815 | 3894 |
| 3895 |
|
| 3816@node Contents 3817@section Generating a Table of Contents 3818@cindex Table of contents 3819@cindex Contents, Table of 3820@cindex Short table of contents 3821@findex contents 3822@findex summarycontents 3823@findex shortcontents 3824 3825The @code{@@chapter}, @code{@@section}, and other structuring commands 3826supply the information to make up a table of contents, but they do not 3827cause an actual table to appear in the manual. To do this, you must use 3828the @code{@@contents} and/or @code{@@summarycontents} command(s). 3829 3830@table @code 3831@item @@contents 3832Generate a table of contents in a printed manual, including all 3833chapters, sections, subsections, etc., as well as appendices and | 3896@node Contents 3897@section Generating a Table of Contents 3898@cindex Table of contents 3899@cindex Contents, Table of 3900@cindex Short table of contents 3901@findex contents 3902@findex summarycontents 3903@findex shortcontents 3904 3905The @code{@@chapter}, @code{@@section}, and other structuring commands 3906supply the information to make up a table of contents, but they do not 3907cause an actual table to appear in the manual. To do this, you must use 3908the @code{@@contents} and/or @code{@@summarycontents} command(s). 3909 3910@table @code 3911@item @@contents 3912Generate a table of contents in a printed manual, including all 3913chapters, sections, subsections, etc., as well as appendices and |
| 3834unnumbered chapters. (Headings generated by the @code{@@heading} 3835series of commands do not appear in the table of contents.) | 3914unnumbered chapters. Headings generated by the @code{@@heading} 3915series of commands do not appear in the table of contents. |
| 3836 3837@item @@shortcontents 3838@itemx @@summarycontents | 3916 3917@item @@shortcontents 3918@itemx @@summarycontents |
| 3839(@code{@@summarycontents} is a synonym for @code{@@shortcontents}; the 3840two commands are exactly the same.)@refill | 3919(@code{@@summarycontents} is a synonym for @code{@@shortcontents}.) |
| 3841 3842Generate a short or summary table of contents that lists only the | 3920 3921Generate a short or summary table of contents that lists only the |
| 3843chapters (and appendices and unnumbered chapters). Omit sections, subsections 3844and subsubsections. Only a long manual needs a short table 3845of contents in addition to the full table of contents.@refill | 3922chapters, appendices, and unnumbered chapters. Sections, subsections 3923and subsubsections are omitted. Only a long manual needs a short table 3924of contents in addition to the full table of contents. |
| 3846 3847@end table 3848 3849Both contents commands should be written on a line by themselves. 3850The contents commands automatically generate a chapter-like heading at 3851the top of the first table of contents page, so don't include any 3852sectioning command such as @code{@@unnumbered} before them. 3853 --- 22 unchanged lines hidden (view full) --- 3876@findex setcontentsaftertitlepage 3877@findex setshortcontentsaftertitlepage 3878@cindex Contents, after title page 3879@cindex Table of contents, after title page 3880As an author, you can put the contents commands wherever you prefer. 3881But if you are a user simply printing a manual, you may wish to print 3882the contents after the title page even if the author put the contents 3883commands at the end of the document (as is the case in most existing | 3925 3926@end table 3927 3928Both contents commands should be written on a line by themselves. 3929The contents commands automatically generate a chapter-like heading at 3930the top of the first table of contents page, so don't include any 3931sectioning command such as @code{@@unnumbered} before them. 3932 --- 22 unchanged lines hidden (view full) --- 3955@findex setcontentsaftertitlepage 3956@findex setshortcontentsaftertitlepage 3957@cindex Contents, after title page 3958@cindex Table of contents, after title page 3959As an author, you can put the contents commands wherever you prefer. 3960But if you are a user simply printing a manual, you may wish to print 3961the contents after the title page even if the author put the contents 3962commands at the end of the document (as is the case in most existing |
| 3884Texinfo documents). You can do this by specifying | 3963Texinfo documents, at this writing). You can do this by specifying |
| 3885@code{@@setcontentsaftertitlepage} and/or 3886@code{@@setshortcontentsaftertitlepage}. The first prints only the main 3887contents after the @code{@@end titlepage}; the second prints both the 3888short contents and the main contents. In either case, any subsequent 3889@code{@@contents} or @code{@@shortcontents} is ignored (unless no 3890@code{@@end titlepage} is ever encountered). 3891 3892You need to include the @code{@@set@dots{}contentsaftertitlepage} 3893commands early in the document (just after @code{@@setfilename}, for | 3964@code{@@setcontentsaftertitlepage} and/or 3965@code{@@setshortcontentsaftertitlepage}. The first prints only the main 3966contents after the @code{@@end titlepage}; the second prints both the 3967short contents and the main contents. In either case, any subsequent 3968@code{@@contents} or @code{@@shortcontents} is ignored (unless no 3969@code{@@end titlepage} is ever encountered). 3970 3971You need to include the @code{@@set@dots{}contentsaftertitlepage} 3972commands early in the document (just after @code{@@setfilename}, for |
| 3894example). Or, if you're using @command{texi2dvi} (@pxref{Format with 3895texi2dvi}), you can use its @option{--texinfo} option to specify this 3896without altering the source file at all. For example: | 3973example). We recommend using @command{texi2dvi} (@pxref{Format with 3974texi2dvi}) to specify this without altering the source file at all. For 3975example: |
| 3897@example | 3976@example |
| 3898texi2dvi --texinfo=@@setshortcontentsaftertitlepage foo.texi | 3977texi2dvi --texinfo=@@setcontentsaftertitlepage foo.texi |
| 3899@end example 3900 3901 3902@node File End 3903@section @code{@@bye} File Ending 3904@findex bye 3905 3906An @code{@@bye} command terminates @TeX{} or Info formatting. None of | 3978@end example 3979 3980 3981@node File End 3982@section @code{@@bye} File Ending 3983@findex bye 3984 3985An @code{@@bye} command terminates @TeX{} or Info formatting. None of |
| 3907the formatting commands see any of the file following @code{@@bye}. 3908The @code{@@bye} command should be on a line by itself.@refill | 3986the formatting commands reading anything following @code{@@bye}. The 3987@code{@@bye} command should be on a line by itself. |
| 3909 | 3988 |
| 3910If you wish, you may follow the @code{@@bye} line with notes. These notes 3911will not be formatted and will not appear in either Info or a printed 3912manual; it is as if text after @code{@@bye} were within @code{@@ignore} 3913@dots{} @code{@@end ignore}. Also, you may follow the @code{@@bye} line 3914with a local variables list. @xref{Compile-Command, , Using Local 3915Variables and the Compile Command}, for more information.@refill | 3989If you wish, you may follow the @code{@@bye} line with notes. These 3990notes will not be formatted and will not appear in either Info or a 3991printed manual; it is as if text after @code{@@bye} were within 3992@code{@@ignore} @dots{} @code{@@end ignore}. Also, you may follow the 3993@code{@@bye} line with a local variables list for Emacs. 3994@xref{Compile-Command, , Using Local Variables and the Compile Command}, 3995for more information. |
| 3916 3917 3918@node Structuring 3919@chapter Chapter Structuring 3920@cindex Chapter structuring 3921@cindex Structuring of chapters 3922 3923The @dfn{chapter structuring} commands divide a document into a hierarchy of --- 705 unchanged lines hidden (view full) --- 4629 4630@menu 4631* Node Names:: How to choose node and pointer names. 4632* Writing a Node:: How to write an @code{@@node} line. 4633* Node Line Tips:: Keep names short. 4634* Node Line Requirements:: Keep names unique, without @@-commands. 4635* First Node:: How to write a `Top' node. 4636* makeinfo top command:: How to use the @code{@@top} command. | 3996 3997 3998@node Structuring 3999@chapter Chapter Structuring 4000@cindex Chapter structuring 4001@cindex Structuring of chapters 4002 4003The @dfn{chapter structuring} commands divide a document into a hierarchy of --- 705 unchanged lines hidden (view full) --- 4709 4710@menu 4711* Node Names:: How to choose node and pointer names. 4712* Writing a Node:: How to write an @code{@@node} line. 4713* Node Line Tips:: Keep names short. 4714* Node Line Requirements:: Keep names unique, without @@-commands. 4715* First Node:: How to write a `Top' node. 4716* makeinfo top command:: How to use the @code{@@top} command. |
| 4637* Top Node Summary:: Write a brief description for readers. | |
| 4638@end menu 4639 4640 4641@node Node Names 4642@subsection Choosing Node and Pointer Names 4643 4644@cindex Node names, choosing 4645The name of a node identifies the node. The pointers enable --- 172 unchanged lines hidden (view full) --- 4818 4819@noindent 4820The corresponding node name is: 4821 4822@smallexample 4823unnumberedsec appendixsec heading 4824@end smallexample 4825 | 4717@end menu 4718 4719 4720@node Node Names 4721@subsection Choosing Node and Pointer Names 4722 4723@cindex Node names, choosing 4724The name of a node identifies the node. The pointers enable --- 172 unchanged lines hidden (view full) --- 4897 4898@noindent 4899The corresponding node name is: 4900 4901@smallexample 4902unnumberedsec appendixsec heading 4903@end smallexample 4904 |
| 4826@cindex Case in nodename | 4905@cindex Case in node name |
| 4827@item 4828Case is significant. 4829@end itemize 4830 4831 | 4906@item 4907Case is significant. 4908@end itemize 4909 4910 |
| 4832@node First Node, makeinfo top command, Node Line Requirements, node 4833@comment node-name, next, previous, up | 4911@node First Node |
| 4834@subsection The First Node 4835@cindex Top node is first 4836@cindex First node 4837 4838The first node of a Texinfo file is the @dfn{Top} node, except in an | 4912@subsection The First Node 4913@cindex Top node is first 4914@cindex First node 4915 4916The first node of a Texinfo file is the @dfn{Top} node, except in an |
| 4839included file (@pxref{Include Files}). The Top node contains the main 4840or master menu for the document, and a short summary of the document 4841(@pxref{Top Node Summary}). | 4917included file (@pxref{Include Files}). The Top node should contain a 4918short summary, copying permissions, and a master menu. @xref{The Top 4919Node}, for more information on the Top node contents and examples. |
| 4842 | 4920 |
| 4921Here is a description of the node pointers to be used in the Top node: 4922 4923@itemize @bullet 4924 4925@item |
|
| 4843@cindex Up node of Top node 4844@cindex (dir) as Up node of Top node 4845The Top node (which must be named @samp{top} or @samp{Top}) should have 4846as its `Up' node the name of a node in another file, where there is a | 4926@cindex Up node of Top node 4927@cindex (dir) as Up node of Top node 4928The Top node (which must be named @samp{top} or @samp{Top}) should have 4929as its `Up' node the name of a node in another file, where there is a |
| 4847menu that leads to this file. Specify the file name in parentheses. If 4848the file is to be installed directly in the Info directory file, use 4849@samp{(dir)} as the parent of the Top node; this is short for 4850@samp{(dir)top}, and specifies the Top node in the @file{dir} file, 4851which contains the main menu for the Info system as a whole. For 4852example, the @code{@@node Top} line of this manual looks like this: | 4930menu that leads to this file. Specify the file name in parentheses. |
| 4853 | 4931 |
| 4854@example 4855@@node Top, Copying, , (dir) 4856@end example | 4932Usually, all Info files are installed in the same Info directory tree; 4933in this case, use @samp{(dir)} as the parent of the Top node; this is 4934short for @samp{(dir)top}, and specifies the Top node in the @file{dir} 4935file, which contains the main menu for the Info system as a whole. |
| 4857 | 4936 |
| 4858@noindent 4859(You can use the Texinfo updating commands or the @code{makeinfo} 4860utility to insert these pointers automatically.) 4861 | 4937@item |
| 4862@cindex Previous node of Top node | 4938@cindex Previous node of Top node |
| 4863Do not define the `Previous' node of the Top node to be @samp{(dir)}, as 4864it causes confusing behavior for users: if you are in the Top node and 4865hits @key{DEL} to go backwards, you wind up in the middle of the 4866some other entry in the @file{dir} file, which has nothing to do with 4867what you were reading. | 4939On the other hand, do not define the `Previous' node of the Top node to 4940be @samp{(dir)}, as it causes confusing behavior for users: if you are 4941in the Top node and hits @key{DEL} to go backwards, you wind up in the 4942middle of the some other entry in the @file{dir} file, which has nothing 4943to do with what you were reading. |
| 4868 | 4944 |
| 4945@item 4946@cindex Next node of Top node 4947The `Next' node of the Top node should be the first chapter in your 4948document. 4949 4950@end itemize 4951 |
|
| 4869@xref{Installing an Info File}, for more information about installing 4870an Info file in the @file{info} directory. 4871 | 4952@xref{Installing an Info File}, for more information about installing 4953an Info file in the @file{info} directory. 4954 |
| 4955For concreteness, here is an example with explicit pointers (which you 4956can maintain automatically with the texinfo mode commands): |
|
| 4872 | 4957 |
| 4873@node makeinfo top command, Top Node Summary, First Node, node 4874@comment node-name, next, previous, up | 4958Or you can leave the pointers off entirely and let the tools implicitly 4959define them. This is recommended. Thus: 4960 4961@example 4962@@node Top 4963@end example 4964 4965 4966@node makeinfo top command |
| 4875@subsection The @code{@@top} Sectioning Command 4876@findex top @r{(@@-command)} 4877 | 4967@subsection The @code{@@top} Sectioning Command 4968@findex top @r{(@@-command)} 4969 |
| 4878A special sectioning command, @code{@@top}, has been created for use 4879with the @code{@@node Top} line. The @code{@@top} sectioning command tells | 4970A special sectioning command, @code{@@top} should be used with the 4971@code{@@node Top} line. The @code{@@top} sectioning command tells |
| 4880@code{makeinfo} that it marks the `Top' node in the file. It provides | 4972@code{makeinfo} that it marks the `Top' node in the file. It provides |
| 4881the information that @code{makeinfo} needs to insert node 4882pointers automatically. Write the @code{@@top} command at the 4883beginning of the line immediately following the @code{@@node Top} 4884line. Write the title on the remaining part of the same line as the 4885@code{@@top} command.@refill | 4973the information that @code{makeinfo} needs to insert node pointers 4974automatically. Write the @code{@@top} command at the beginning of the 4975line immediately following the @code{@@node Top} line. Write the title 4976on the remaining part of the same line as the @code{@@top} command. |
| 4886 | 4977 |
| 4887In Info, the @code{@@top} sectioning command causes the title to appear on a 4888line by itself, with a line of asterisks inserted underneath.@refill | 4978In Info, the @code{@@top} sectioning command causes the title to appear 4979on a line by itself, with a line of asterisks inserted underneath, as 4980other sectioning commands do. |
| 4889 4890In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top} 4891sectioning command is merely a synonym for @code{@@unnumbered}. 4892Neither of these formatters require an @code{@@top} command, and do 4893nothing special with it. You can use @code{@@chapter} or 4894@code{@@unnumbered} after the @code{@@node Top} line when you use 4895these formatters. Also, you can use @code{@@chapter} or 4896@code{@@unnumbered} when you use the Texinfo updating commands to | 4981 4982In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top} 4983sectioning command is merely a synonym for @code{@@unnumbered}. 4984Neither of these formatters require an @code{@@top} command, and do 4985nothing special with it. You can use @code{@@chapter} or 4986@code{@@unnumbered} after the @code{@@node Top} line when you use 4987these formatters. Also, you can use @code{@@chapter} or 4988@code{@@unnumbered} when you use the Texinfo updating commands to |
| 4897create or update pointers and menus.@refill | 4989create or update pointers and menus. |
| 4898 | 4990 |
| 4991Thus, in practice, a Top node starts like this: |
|
| 4899 | 4992 |
| 4900@node Top Node Summary, , makeinfo top command, node 4901@subsection The `Top' Node Summary 4902@cindex @samp{@r{Top}} node summary | 4993@example 4994@@node Top 4995@@top Your Manual Title 4996@end example |
| 4903 | 4997 |
| 4904You can help readers by writing a summary in the `Top' node, after the 4905@code{@@top} line, before the main or master menu. The summary should 4906briefly describe the document. In Info, this summary will appear just 4907before the master menu. In a printed manual, this summary will appear 4908on a page of its own.@refill | |
| 4909 | 4998 |
| 4910If you do not want the summary to appear on a page of its own in a 4911printed manual, you can enclose the whole of the `Top' node, including 4912the @code{@@node Top} line and the @code{@@top} sectioning command line 4913or other sectioning command line between @code{@@ifinfo} and @code{@@end 4914ifinfo}. This prevents any of the text from appearing in the printed 4915output. (@pxref{Conditionals, , Conditionally Visible Text}). You can 4916repeat the brief description from the `Top' node within @code{@@iftex} 4917@dots{} @code{@@end iftex} at the beginning of the first chapter, for 4918those who read the printed manual. This saves paper and may look 4919neater.@refill 4920 4921You should write the version number of the program to which the manual 4922applies in the summary. This helps the reader keep track of which 4923manual is for which version of the program. If the manual changes more 4924frequently than the program or is independent of it, you should also 4925include an edition number for the manual. (The title page should also 4926contain this information: see @ref{titlepage, , 4927@code{@@titlepage}}.)@refill 4928 4929 | |
| 4930@node makeinfo Pointer Creation 4931@section Creating Pointers with @code{makeinfo} 4932@cindex Creating pointers with @code{makeinfo} 4933@cindex Pointer creation with @code{makeinfo} 4934@cindex Automatic pointer creation with @code{makeinfo} 4935 4936The @code{makeinfo} program has a feature for automatically defining 4937node pointers for a hierarchically organized file. --- 109 unchanged lines hidden (view full) --- 5047@cindex Nodes for menus are short 5048@cindex Short nodes for menus 5049 5050The short text before a menu may look awkward in a printed manual. To 5051avoid this, you can write a menu near the beginning of its node and 5052follow the menu by an @code{@@node} line, and then an @code{@@heading} 5053line located within @code{@@ifinfo} and @code{@@end ifinfo}. This way, 5054the menu, @code{@@node} line, and title appear only in the Info file, | 4999@node makeinfo Pointer Creation 5000@section Creating Pointers with @code{makeinfo} 5001@cindex Creating pointers with @code{makeinfo} 5002@cindex Pointer creation with @code{makeinfo} 5003@cindex Automatic pointer creation with @code{makeinfo} 5004 5005The @code{makeinfo} program has a feature for automatically defining 5006node pointers for a hierarchically organized file. --- 109 unchanged lines hidden (view full) --- 5116@cindex Nodes for menus are short 5117@cindex Short nodes for menus 5118 5119The short text before a menu may look awkward in a printed manual. To 5120avoid this, you can write a menu near the beginning of its node and 5121follow the menu by an @code{@@node} line, and then an @code{@@heading} 5122line located within @code{@@ifinfo} and @code{@@end ifinfo}. This way, 5123the menu, @code{@@node} line, and title appear only in the Info file, |
| 5055not the printed document.@refill | 5124not the printed document. |
| 5056 5057For example, the preceding two paragraphs follow an Info-only menu, | 5125 5126For example, the preceding two paragraphs follow an Info-only menu, |
| 5058@code{@@node} line, and heading, and look like this:@refill | 5127@code{@@node} line, and heading, and look like this: |
| 5059 5060@example 5061@group 5062@@menu 5063* Menu Location:: Put a menu in a short node. 5064* Writing a Menu:: What is a menu? 5065* Menu Parts:: A menu entry has three parts. 5066* Less Cluttered Menu Entry:: Two part menu entry. --- 4 unchanged lines hidden (view full) --- 5071 5072@@node Menu Location, Writing a Menu, , Menus 5073@@ifinfo 5074@@heading Menus Need Short Nodes 5075@@end ifinfo 5076@end group 5077@end example 5078 | 5128 5129@example 5130@group 5131@@menu 5132* Menu Location:: Put a menu in a short node. 5133* Writing a Menu:: What is a menu? 5134* Menu Parts:: A menu entry has three parts. 5135* Less Cluttered Menu Entry:: Two part menu entry. --- 4 unchanged lines hidden (view full) --- 5140 5141@@node Menu Location, Writing a Menu, , Menus 5142@@ifinfo 5143@@heading Menus Need Short Nodes 5144@@end ifinfo 5145@end group 5146@end example 5147 |
| 5079The Texinfo file for this document contains more than a dozen 5080examples of this procedure. One is at the beginning of this chapter; 5081another is at the beginning of @ref{Cross References}. @refill | 5148The Texinfo file for this document contains a number of 5149examples of this procedure; one is at the beginning of this chapter. |
| 5082 5083 5084@node Writing a Menu, Menu Parts, Menu Location, Menus 5085@section Writing a Menu 5086@cindex Writing a menu 5087@cindex Menu writing 5088 5089A menu consists of an @code{@@menu} command on a line by --- 1312 unchanged lines hidden (view full) --- 6402not something else that should not be changed.@refill 6403 6404@menu 6405* Useful Highlighting:: Highlighting provides useful information. 6406* code:: Indicating program code. 6407* kbd:: Showing keyboard input. 6408* key:: Specifying keys. 6409* samp:: A literal sequence of characters. | 5150 5151 5152@node Writing a Menu, Menu Parts, Menu Location, Menus 5153@section Writing a Menu 5154@cindex Writing a menu 5155@cindex Menu writing 5156 5157A menu consists of an @code{@@menu} command on a line by --- 1312 unchanged lines hidden (view full) --- 6470not something else that should not be changed.@refill 6471 6472@menu 6473* Useful Highlighting:: Highlighting provides useful information. 6474* code:: Indicating program code. 6475* kbd:: Showing keyboard input. 6476* key:: Specifying keys. 6477* samp:: A literal sequence of characters. |
| 6410* verb:: A verbatim sequence of characters. | 6478* verb:: A verbatim sequence of characters. |
| 6411* var:: Indicating metasyntactic variables. 6412* env:: Indicating environment variables. 6413* file:: Indicating file names. 6414* command:: Indicating command names. 6415* option:: Indicating option names. 6416* dfn:: Specifying definitions. 6417* cite:: Referring to books not in the Info system. 6418* acronym:: Indicating acronyms. --- 925 unchanged lines hidden (view full) --- 7344line. 7345@findex end 7346 7347@menu 7348* Block Enclosing Commands:: Different constructs for different purposes. 7349* quotation:: Writing a quotation. 7350* example:: Writing an example in a fixed-width font. 7351* verbatim:: Writing a verbatim example. | 6479* var:: Indicating metasyntactic variables. 6480* env:: Indicating environment variables. 6481* file:: Indicating file names. 6482* command:: Indicating command names. 6483* option:: Indicating option names. 6484* dfn:: Specifying definitions. 6485* cite:: Referring to books not in the Info system. 6486* acronym:: Indicating acronyms. --- 925 unchanged lines hidden (view full) --- 7412line. 7413@findex end 7414 7415@menu 7416* Block Enclosing Commands:: Different constructs for different purposes. 7417* quotation:: Writing a quotation. 7418* example:: Writing an example in a fixed-width font. 7419* verbatim:: Writing a verbatim example. |
| 7352* verbatiminclude:: Including a file verbatim. | 7420* verbatiminclude:: Including a file verbatim. |
| 7353* lisp:: Illustrating Lisp code. 7354* small:: Forms for @code{@@smallbook}. 7355* display:: Writing an example in the current font. 7356* format:: Writing an example without narrowed margins. 7357* exdent:: Undo indentation on a line. 7358* flushleft & flushright:: Pushing text flush left or flush right. 7359* noindent:: Preventing paragraph indentation. 7360* cartouche:: Drawing rounded rectangles around examples. --- 198 unchanged lines hidden (view full) --- 7559such as computer input or output (@code{@@example} interprets its text 7560as regular Texinfo commands). This is especially useful for including 7561automatically generated output in a Texinfo manual. Here is an example; 7562the output you see is just the same as the input, with a line 7563@code{@@verbatim} before and a line @code{@@end verbatim} after. 7564 7565@verbatim 7566This is an example of text written in a @verbatim | 7421* lisp:: Illustrating Lisp code. 7422* small:: Forms for @code{@@smallbook}. 7423* display:: Writing an example in the current font. 7424* format:: Writing an example without narrowed margins. 7425* exdent:: Undo indentation on a line. 7426* flushleft & flushright:: Pushing text flush left or flush right. 7427* noindent:: Preventing paragraph indentation. 7428* cartouche:: Drawing rounded rectangles around examples. --- 198 unchanged lines hidden (view full) --- 7627such as computer input or output (@code{@@example} interprets its text 7628as regular Texinfo commands). This is especially useful for including 7629automatically generated output in a Texinfo manual. Here is an example; 7630the output you see is just the same as the input, with a line 7631@code{@@verbatim} before and a line @code{@@end verbatim} after. 7632 7633@verbatim 7634This is an example of text written in a @verbatim |
| 7567block. No character substitutions are made all commands 7568are ignored, until the next 'end verbatim' command. | 7635block. No character substitutions are made. All commands 7636are ignored, until `<at>end verbatim'. |
| 7569 7570In the printed manual, the text is typeset in a 7571fixed-width font, and not indented or filled. All 7572spaces and blank lines are significant, including tabs. 7573@end verbatim 7574 7575Write a @code{@@verbatim} command at the beginning of a line by itself. 7576This line will disappear from the output. Mark the end of the verbatim 7577block with a @code{@@end verbatim} command, also written at the 7578beginning of a line by itself. The @code{@@end verbatim} will also 7579disappear from the output. 7580 7581For example: | 7637 7638In the printed manual, the text is typeset in a 7639fixed-width font, and not indented or filled. All 7640spaces and blank lines are significant, including tabs. 7641@end verbatim 7642 7643Write a @code{@@verbatim} command at the beginning of a line by itself. 7644This line will disappear from the output. Mark the end of the verbatim 7645block with a @code{@@end verbatim} command, also written at the 7646beginning of a line by itself. The @code{@@end verbatim} will also 7647disappear from the output. 7648 7649For example: |
| 7582@c urg: got to trick this a bit: can't use @end verbatim inside @verbatim | 7650@c oops, got to trick this a bit: can't use @end verbatim inside @verbatim |
| 7583 7584@example 7585@exdent @@verbatim 7586@exdent @{ 7587@exdent <tab>@@command with strange characters: @@'e 7588@exdent expand<tab>me 7589@exdent @} 7590@exdent @@end verbatim --- 5 unchanged lines hidden (view full) --- 7596@verbatim 7597{ 7598 @command with strange characters: @'e 7599expand me 7600} 7601@end verbatim 7602 7603Since the lines containing @code{@@verbatim} and @code{@@end verbatim} | 7651 7652@example 7653@exdent @@verbatim 7654@exdent @{ 7655@exdent <tab>@@command with strange characters: @@'e 7656@exdent expand<tab>me 7657@exdent @} 7658@exdent @@end verbatim --- 5 unchanged lines hidden (view full) --- 7664@verbatim 7665{ 7666 @command with strange characters: @'e 7667expand me 7668} 7669@end verbatim 7670 7671Since the lines containing @code{@@verbatim} and @code{@@end verbatim} |
| 7604will disappear, tyically you should put a blank line before the | 7672produce no output, tyically you should put a blank line before the |
| 7605@code{@@verbatim} and another blank line after the @code{@@end 7606verbatim}. Blank lines between the beginning @code{@@verbatim} and the | 7673@code{@@verbatim} and another blank line after the @code{@@end 7674verbatim}. Blank lines between the beginning @code{@@verbatim} and the |
| 7607ending @code{@@end verbatim} will appear in the output.) | 7675ending @code{@@end verbatim} will appear in the output. |
| 7608 7609 7610@node verbatiminclude 7611@section @code{@@verbatiminclude} @var{file}: Include a File Verbatim 7612@cindex Verbatim, include file 7613@cindex Including a file verbatim 7614@findex verbatiminclude 7615 --- 1190 unchanged lines hidden (view full) --- 8806 8807@menu 8808* syncodeindex:: How to merge two indices, using @code{@@code} 8809 font for the merged-from index. 8810* synindex:: How to merge two indices, using the 8811 default font of the merged-to index. 8812@end menu 8813 | 7676 7677 7678@node verbatiminclude 7679@section @code{@@verbatiminclude} @var{file}: Include a File Verbatim 7680@cindex Verbatim, include file 7681@cindex Including a file verbatim 7682@findex verbatiminclude 7683 --- 1190 unchanged lines hidden (view full) --- 8874 8875@menu 8876* syncodeindex:: How to merge two indices, using @code{@@code} 8877 font for the merged-from index. 8878* synindex:: How to merge two indices, using the 8879 default font of the merged-to index. 8880@end menu 8881 |
| 8814@node syncodeindex, synindex, Combining Indices, Combining Indices | 8882@node syncodeindex |
| 8815@subsection @code{@@syncodeindex} 8816@findex syncodeindex 8817 8818When you want to combine functions and concepts into one index, you 8819should index the functions with @code{@@findex} and index the concepts 8820with @code{@@cindex}, and use the @code{@@syncodeindex} command to 8821redirect the function index entries into the concept index.@refill 8822@findex syncodeindex --- 131 unchanged lines hidden (view full) --- 8954 8955The @code{@@defcodeindex} is like the @code{@@defindex} command, except 8956that, in the printed output, it prints entries in an @code{@@code} font 8957instead of a roman font. Thus, it parallels the @code{@@findex} command 8958rather than the @code{@@cindex} command.@refill 8959 8960You should define new indices within or right after the end-of-header 8961line of a Texinfo file, before any @code{@@synindex} or | 8883@subsection @code{@@syncodeindex} 8884@findex syncodeindex 8885 8886When you want to combine functions and concepts into one index, you 8887should index the functions with @code{@@findex} and index the concepts 8888with @code{@@cindex}, and use the @code{@@syncodeindex} command to 8889redirect the function index entries into the concept index.@refill 8890@findex syncodeindex --- 131 unchanged lines hidden (view full) --- 9022 9023The @code{@@defcodeindex} is like the @code{@@defindex} command, except 9024that, in the printed output, it prints entries in an @code{@@code} font 9025instead of a roman font. Thus, it parallels the @code{@@findex} command 9026rather than the @code{@@cindex} command.@refill 9027 9028You should define new indices within or right after the end-of-header 9029line of a Texinfo file, before any @code{@@synindex} or |
| 8962@code{@@syncodeindex} commands (@pxref{Header}).@refill | 9030@code{@@syncodeindex} commands (@pxref{Texinfo File Header}). |
| 8963 | 9031 |
| 9032 |
|
| 8964@node Insertions 8965@chapter Special Insertions 8966@cindex Inserting special characters and symbols 8967@cindex Special insertions 8968 8969Texinfo provides several commands for inserting characters that have 8970special meaning in Texinfo, such as braces, and for other graphic 8971elements that do not correspond to simple characters you can type. --- 51 unchanged lines hidden (view full) --- 9023 9024@menu 9025* Inserting An Atsign:: How to insert @samp{@@}. 9026* Inserting Braces:: How to insert @samp{@{} and @samp{@}}. 9027@end menu 9028 9029@node Inserting An Atsign, Inserting Braces, Braces Atsigns, Braces Atsigns 9030@subsection Inserting @samp{@@} with @@@@ | 9033@node Insertions 9034@chapter Special Insertions 9035@cindex Inserting special characters and symbols 9036@cindex Special insertions 9037 9038Texinfo provides several commands for inserting characters that have 9039special meaning in Texinfo, such as braces, and for other graphic 9040elements that do not correspond to simple characters you can type. --- 51 unchanged lines hidden (view full) --- 9092 9093@menu 9094* Inserting An Atsign:: How to insert @samp{@@}. 9095* Inserting Braces:: How to insert @samp{@{} and @samp{@}}. 9096@end menu 9097 9098@node Inserting An Atsign, Inserting Braces, Braces Atsigns, Braces Atsigns 9099@subsection Inserting @samp{@@} with @@@@ |
| 9031@findex @@ @r{(single @samp{@@})} | 9100@findex @@ @r{(literal @samp{@@})} |
| 9032 9033@code{@@@@} stands for a single @samp{@@} in either printed or Info 9034output. 9035 9036Do not put braces after an @code{@@@@} command. 9037 9038 9039@node Inserting Braces 9040@subsection Inserting @samp{@{} and @samp{@}}with @@@{ and @@@} | 9101 9102@code{@@@@} stands for a single @samp{@@} in either printed or Info 9103output. 9104 9105Do not put braces after an @code{@@@@} command. 9106 9107 9108@node Inserting Braces 9109@subsection Inserting @samp{@{} and @samp{@}}with @@@{ and @@@} |
| 9041@findex @{ @r{(single @samp{@{})} 9042@findex @} @r{(single @samp{@}})} | 9110@findex @{ @r{(literal @samp{@{})} 9111@findex @} @r{(literal @samp{@}})} |
| 9043 9044@code{@@@{} stands for a single @samp{@{} in either printed or Info 9045output. 9046 9047@code{@@@}} stands for a single @samp{@}} in either printed or Info 9048output. 9049 9050Do not put braces after either an @code{@@@{} or an @code{@@@}} --- 208 unchanged lines hidden (view full) --- 9259 9260Here is a table with the commands Texinfo provides for inserting 9261floating accents. The commands with non-alphabetic names do not take 9262braces around their argument (which is taken to be the next character). 9263(Exception: @code{@@,} @emph{does} take braces around its argument.) 9264This is so as to make the source as convenient to type and read as 9265possible, since accented characters are very common in some languages. 9266 | 9112 9113@code{@@@{} stands for a single @samp{@{} in either printed or Info 9114output. 9115 9116@code{@@@}} stands for a single @samp{@}} in either printed or Info 9117output. 9118 9119Do not put braces after either an @code{@@@{} or an @code{@@@}} --- 208 unchanged lines hidden (view full) --- 9328 9329Here is a table with the commands Texinfo provides for inserting 9330floating accents. The commands with non-alphabetic names do not take 9331braces around their argument (which is taken to be the next character). 9332(Exception: @code{@@,} @emph{does} take braces around its argument.) 9333This is so as to make the source as convenient to type and read as 9334possible, since accented characters are very common in some languages. 9335 |
| 9267@findex " | 9336@findex " @r{(umlaut accent)} |
| 9268@cindex Umlaut accent | 9337@cindex Umlaut accent |
| 9269@findex ' | 9338@findex ' @r{(umlaut accent)} |
| 9270@cindex Acute accent | 9339@cindex Acute accent |
| 9271@findex = | 9340@findex = @r{(macron accent)} |
| 9272@cindex Macron accent | 9341@cindex Macron accent |
| 9273@findex ^ | 9342@findex ^ @r{(circumflex accent)} |
| 9274@cindex Circumflex accent | 9343@cindex Circumflex accent |
| 9275@findex ` | 9344@findex ` @r{(grave accent)} |
| 9276@cindex Grave accent | 9345@cindex Grave accent |
| 9277@findex ~ | 9346@findex ~ @r{(tilde accent)} |
| 9278@cindex Tilde accent | 9347@cindex Tilde accent |
| 9279@findex , | 9348@findex , @r{(cedilla accent)} |
| 9280@cindex Cedilla accent 9281@findex dotaccent 9282@cindex Dot accent | 9349@cindex Cedilla accent 9350@findex dotaccent 9351@cindex Dot accent |
| 9283@findex H | 9352@findex H @r{(Hungarian umlaut accent)} |
| 9284@cindex Hungarian umlaut accent 9285@findex ringaccent 9286@cindex Ring accent 9287@findex tieaccent 9288@cindex Tie-after accent | 9353@cindex Hungarian umlaut accent 9354@findex ringaccent 9355@cindex Ring accent 9356@findex tieaccent 9357@cindex Tie-after accent |
| 9289@findex u | 9358@findex u @r{(breve accent)} |
| 9290@cindex Breve accent 9291@findex ubaraccent 9292@cindex Underbar accent 9293@findex udotaccent 9294@cindex Underdot accent | 9359@cindex Breve accent 9360@findex ubaraccent 9361@cindex Underbar accent 9362@findex udotaccent 9363@cindex Underdot accent |
| 9295@findex v | 9364@findex v @r{(check accent)} |
| 9296@cindex Check accent 9297@multitable {@@questiondown@{@}} {Output} {macron/overbar accent} 9298@item Command @tab Output @tab What 9299@item @t{@@"o} @tab @"o @tab umlaut accent 9300@item @t{@@'o} @tab @'o @tab acute accent 9301@item @t{@@,@{c@}} @tab @,{c} @tab cedilla accent 9302@item @t{@@=o} @tab @=o @tab macron/overbar accent 9303@item @t{@@^o} @tab @^o @tab circumflex accent --- 230 unchanged lines hidden (view full) --- 9534(a + b)(a + b) = a^2 + 2ab + b^2 9535@end example 9536 9537Thus, the @code{@@math} command has no effect on the Info output. 9538 9539@code{@@math} implies @code{@@tex}. This not only makes it possible to 9540write superscripts and subscripts (as in the above example), but also 9541allows you to use any of the plain @TeX{} math control sequences. It's | 9365@cindex Check accent 9366@multitable {@@questiondown@{@}} {Output} {macron/overbar accent} 9367@item Command @tab Output @tab What 9368@item @t{@@"o} @tab @"o @tab umlaut accent 9369@item @t{@@'o} @tab @'o @tab acute accent 9370@item @t{@@,@{c@}} @tab @,{c} @tab cedilla accent 9371@item @t{@@=o} @tab @=o @tab macron/overbar accent 9372@item @t{@@^o} @tab @^o @tab circumflex accent --- 230 unchanged lines hidden (view full) --- 9603(a + b)(a + b) = a^2 + 2ab + b^2 9604@end example 9605 9606Thus, the @code{@@math} command has no effect on the Info output. 9607 9608@code{@@math} implies @code{@@tex}. This not only makes it possible to 9609write superscripts and subscripts (as in the above example), but also 9610allows you to use any of the plain @TeX{} math control sequences. It's |
| 9542simplest to use @samp{\} instead of @samp{@@} for these commands. As 9543in: | 9611conventional to use @samp{\} instead of @samp{@@} for these commands. 9612As in: |
| 9544@example 9545@@math@{\sin 2\pi \equiv \cos 3\pi@} 9546@end example 9547 9548@iftex 9549@noindent which looks like this in @TeX{}: 9550@display 9551@math{\sin 2\pi \equiv \cos 3\pi} 9552@end display 9553 9554@noindent and 9555@end iftex 9556@noindent which looks like the input in Info and HTML: 9557@example 9558\sin 2\pi \equiv \cos 3\pi 9559@end example 9560 | 9613@example 9614@@math@{\sin 2\pi \equiv \cos 3\pi@} 9615@end example 9616 9617@iftex 9618@noindent which looks like this in @TeX{}: 9619@display 9620@math{\sin 2\pi \equiv \cos 3\pi} 9621@end display 9622 9623@noindent and 9624@end iftex 9625@noindent which looks like the input in Info and HTML: 9626@example 9627\sin 2\pi \equiv \cos 3\pi 9628@end example 9629 |
| 9630@findex \ @r{(literal \ in @code{@@math})} 9631Since @samp{\} is an escape character inside @code{@@math}, you can use 9632@code{@@\} to get a literal backslash (@code{\\} will work in @TeX{}, 9633but you'll get the literal @samp{\\} in Info). @code{@@\} is not 9634defined outside of @code{@@math}, since a @samp{\} ordinarily produces a 9635literal @samp{\}. 9636 9637 |
|
| 9561@cindex Displayed equations 9562@cindex Equations, displayed 9563For displayed equations, you must at present use @TeX{} directly 9564(@pxref{Raw Formatter Commands}). 9565 9566 9567@node Glyphs 9568@section Glyphs for Examples --- 797 unchanged lines hidden (view full) --- 10366refilled after the line break occurs, negating the effect of the line 10367break.@refill 10368@end quotation 10369 10370 10371@node - and hyphenation 10372@section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} hyphenate 10373 | 9638@cindex Displayed equations 9639@cindex Equations, displayed 9640For displayed equations, you must at present use @TeX{} directly 9641(@pxref{Raw Formatter Commands}). 9642 9643 9644@node Glyphs 9645@section Glyphs for Examples --- 797 unchanged lines hidden (view full) --- 10443refilled after the line break occurs, negating the effect of the line 10444break.@refill 10445@end quotation 10446 10447 10448@node - and hyphenation 10449@section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} hyphenate 10450 |
| 10374@findex - | 10451@findex - @r{(discretionary hyphen)} |
| 10375@findex hyphenation 10376@cindex Hyphenation, helping @TeX{} do 10377@cindex Fine-tuning, and hyphenation 10378 10379Although @TeX{}'s hyphenation algorithm is generally pretty good, it 10380does miss useful hyphenation points from time to time. (Or, far more 10381rarely, insert an incorrect hyphenation.) So, for documents with an 10382unusual vocabulary or when fine-tuning for a printed edition, you may 10383wish to help @TeX{} out. Texinfo supports two commands for this: 10384 10385@table @code 10386@item @@- 10387Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does | 10452@findex hyphenation 10453@cindex Hyphenation, helping @TeX{} do 10454@cindex Fine-tuning, and hyphenation 10455 10456Although @TeX{}'s hyphenation algorithm is generally pretty good, it 10457does miss useful hyphenation points from time to time. (Or, far more 10458rarely, insert an incorrect hyphenation.) So, for documents with an 10459unusual vocabulary or when fine-tuning for a printed edition, you may 10460wish to help @TeX{} out. Texinfo supports two commands for this: 10461 10462@table @code 10463@item @@- 10464Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does |
| 10388not have to) hyphenate. This is especially useful when you notice 10389an overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull 10390hboxes}). @TeX{} will not insert any hyphenation points in a word 10391containing @code{@@-}. | 10465not have to) hyphenate. This is especially useful when you notice an 10466overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull 10467hboxes}). @TeX{} will not insert any hyphenation points itself into a 10468word containing @code{@@-}. |
| 10392 10393@item @@hyphenation@{@var{hy-phen-a-ted words}@} 10394Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you 10395put a @samp{-} at each hyphenation point. For example: 10396@example 10397@@hyphenation@{man-u-script man-u-scripts@} 10398@end example 10399@noindent @TeX{} only uses the specified hyphenation points when the --- 1340 unchanged lines hidden (view full) --- 11740 all output formats); and how to set a 11741 flag to a string that you can insert. 11742@end menu 11743 11744 11745@node Conditional Commands 11746@section Conditional Commands 11747 | 10469 10470@item @@hyphenation@{@var{hy-phen-a-ted words}@} 10471Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you 10472put a @samp{-} at each hyphenation point. For example: 10473@example 10474@@hyphenation@{man-u-script man-u-scripts@} 10475@end example 10476@noindent @TeX{} only uses the specified hyphenation points when the --- 1340 unchanged lines hidden (view full) --- 11817 all output formats); and how to set a 11818 flag to a string that you can insert. 11819@end menu 11820 11821 11822@node Conditional Commands 11823@section Conditional Commands 11824 |
| 11825Texinfo has a pair of commands for each output format, to allow 11826conditional inclusion of text for a particular output format. 11827 |
|
| 11748@findex ifinfo 11749@code{@@ifinfo} begins segments of text that should be ignored by @TeX{} 11750when it typesets the printed manual. The segment of text appears only | 11828@findex ifinfo 11829@code{@@ifinfo} begins segments of text that should be ignored by @TeX{} 11830when it typesets the printed manual. The segment of text appears only |
| 11751in the Info file. The @code{@@ifinfo} command should appear on a line 11752by itself; end the Info-only text with a line containing @code{@@end 11753ifinfo} by itself. At the beginning of a Texinfo file, the Info 11754permissions are contained within a region marked by @code{@@ifinfo} and 11755@code{@@end ifinfo}. (@xref{Info Summary and Permissions}.) | 11831in the Info file and (for historical compatibility) the plain text 11832output. The @code{@@ifinfo} command should appear on a line by itself; 11833end the Info-only text with a line containing @code{@@end ifinfo} by 11834itself. |
| 11756 11757@findex iftex 11758@findex ifhtml | 11835 11836@findex iftex 11837@findex ifhtml |
| 11759The @code{@@iftex} and @code{@@end iftex} commands are similar to the 11760@code{@@ifinfo} and @code{@@end ifinfo} commands, except that they 11761specify text that will appear in the printed manual but not in the Info 11762file. Likewise for @code{@@ifhtml} and @code{@@end ifhtml}, which 11763specify text to appear only in HTML output.@refill | 11838@findex ifplaintext 11839The @code{@@iftex} and @code{@@end iftex} commands are analogous to the 11840@code{@@ifinfo} and @code{@@end ifinfo} commands; they specify text that 11841will appear in the printed manual but not in the Info file. Likewise 11842for @code{@@ifhtml} and @code{@@end ifhtml}, which specify text to 11843appear only in HTML output. And for @code{@@ifplaintext} and 11844@code{@@end ifplaintext}, which specify text to appear only in plain 11845text output. |
| 11764 11765For example, 11766 11767@example 11768@@iftex 11769This text will appear only in the printed manual. 11770@@end iftex 11771@@ifinfo | 11846 11847For example, 11848 11849@example 11850@@iftex 11851This text will appear only in the printed manual. 11852@@end iftex 11853@@ifinfo |
| 11772However, this text will appear only in Info. | 11854However, this text will appear only in Info (or plain text). |
| 11773@@end ifinfo 11774@@ifhtml 11775And this text will only appear in HTML. 11776@@end ifhtml | 11855@@end ifinfo 11856@@ifhtml 11857And this text will only appear in HTML. 11858@@end ifhtml |
| 11859@@ifplaintext 11860Whereas this text will only appear in plain text. 11861@@end ifplaintext |
|
| 11777@end example 11778 11779@noindent 11780The preceding example produces the following line: 11781@iftex 11782This text will appear only in the printed manual. 11783@end iftex 11784@ifinfo | 11862@end example 11863 11864@noindent 11865The preceding example produces the following line: 11866@iftex 11867This text will appear only in the printed manual. 11868@end iftex 11869@ifinfo |
| 11785However, this text will appear only in Info. | 11870However, this text will appear only in Info (or plain text). |
| 11786@end ifinfo 11787@ifhtml 11788And this text will only appear in HTML. 11789@end ifhtml | 11871@end ifinfo 11872@ifhtml 11873And this text will only appear in HTML. 11874@end ifhtml |
| 11875@ifplaintext 11876Whereas this text will only appear in plain text. 11877@end ifplaintext |
|
| 11790 11791@noindent 11792Notice that you only see one of the input lines, depending on which 11793version of the manual you are reading. 11794 11795 11796@node Conditional Not Commands 11797@section Conditional Not Commands 11798@findex ifnothtml 11799@findex ifnotinfo | 11878 11879@noindent 11880Notice that you only see one of the input lines, depending on which 11881version of the manual you are reading. 11882 11883 11884@node Conditional Not Commands 11885@section Conditional Not Commands 11886@findex ifnothtml 11887@findex ifnotinfo |
| 11888@findex ifnotplaintext |
|
| 11800@findex ifnottex 11801 11802You can specify text to be included in any output format @emph{other} 11803than some given one with the @code{@@ifnot@dots{}} commands: 11804@example 11805@@ifnothtml @dots{} @@end ifnothtml 11806@@ifnotinfo @dots{} @@end ifnotinfo | 11889@findex ifnottex 11890 11891You can specify text to be included in any output format @emph{other} 11892than some given one with the @code{@@ifnot@dots{}} commands: 11893@example 11894@@ifnothtml @dots{} @@end ifnothtml 11895@@ifnotinfo @dots{} @@end ifnotinfo |
| 11896@@ifnotplaintext @dots{} @@end ifnotplaintext |
|
| 11807@@ifnottex @dots{} @@end ifnottex 11808@end example 11809@noindent 11810(The @code{@@ifnot@dots{}} command and the @code{@@end} command must | 11897@@ifnottex @dots{} @@end ifnottex 11898@end example 11899@noindent 11900(The @code{@@ifnot@dots{}} command and the @code{@@end} command must |
| 11811actually appear on lines by themselves.) | 11901appear on lines by themselves in your actual source file.) |
| 11812 | 11902 |
| 11813If the output file is not being made for the given format, the region is 11814included. Otherwise, it is ignored. | 11903If the output file is @emph{not} being made for the given format, the 11904region is included. Otherwise, it is ignored. |
| 11815 | 11905 |
| 11906With one exception (for historical compatibility): @code{@@ifnotinfo} 11907text is omitted for both Info and plain text output, not just Info. To 11908specify text which appears only in Info and not in plain text, use 11909@code{@@ifnotplaintext}, like this: 11910@example 11911@ifinfo 11912@ifnotplaintext 11913This will be in Info, but not plain text. 11914@end ifnotplaintext 11915@end ifinfo 11916@end example 11917 |
|
| 11816The regions delimited by these commands are ordinary Texinfo source as 11817with @code{@@iftex}, not raw formatter source as with @code{@@tex} 11818(@pxref{Raw Formatter Commands}). 11819 11820 11821@node Raw Formatter Commands 11822@section Raw Formatter Commands 11823@cindex @TeX{} commands, using ordinary --- 251 unchanged lines hidden (view full) --- 12075@@ifclear @var{flag} 12076@end example 12077 12078 12079@node value Example 12080@subsection @code{@@value} Example 12081 12082You can use the @code{@@value} command to minimize the number of places | 11918The regions delimited by these commands are ordinary Texinfo source as 11919with @code{@@iftex}, not raw formatter source as with @code{@@tex} 11920(@pxref{Raw Formatter Commands}). 11921 11922 11923@node Raw Formatter Commands 11924@section Raw Formatter Commands 11925@cindex @TeX{} commands, using ordinary --- 251 unchanged lines hidden (view full) --- 12177@@ifclear @var{flag} 12178@end example 12179 12180 12181@node value Example 12182@subsection @code{@@value} Example 12183 12184You can use the @code{@@value} command to minimize the number of places |
| 12083you need to change when you record an update to a manual. Here is how 12084it is done in @cite{The GNU Make Manual}: | 12185you need to change when you record an update to a manual. @xref{GNU 12186Sample Texts}, for an example of this same principle can work with 12187Automake distributions, and full texts. |
| 12085 | 12188 |
| 12189Here is an example adapted from @ref{Top,, Overview, make, The GNU Make 12190Manual}): 12191 |
|
| 12086@enumerate 12087@item 12088Set the flags: 12089 12090@example 12091@group 12092@@set EDITION 0.35 Beta 12093@@set VERSION 3.63 Beta 12094@@set UPDATED 14 August 1992 12095@@set UPDATE-MONTH August 1992 12096@end group 12097@end example 12098 12099@item | 12192@enumerate 12193@item 12194Set the flags: 12195 12196@example 12197@group 12198@@set EDITION 0.35 Beta 12199@@set VERSION 3.63 Beta 12200@@set UPDATED 14 August 1992 12201@@set UPDATE-MONTH August 1992 12202@end group 12203@end example 12204 12205@item |
| 12100Write text for the first @code{@@ifinfo} section, for people reading the 12101Texinfo file: | 12206Write text for the @code{@@copying} section (@pxref{copying}): |
| 12102 12103@example 12104@group | 12207 12208@example 12209@group |
| 12210@@copying |
|
| 12105This is Edition @@value@{EDITION@}, 12106last updated @@value@{UPDATED@}, 12107of @@cite@{The GNU Make Manual@}, 12108for @@code@{make@}, version @@value@{VERSION@}. | 12211This is Edition @@value@{EDITION@}, 12212last updated @@value@{UPDATED@}, 12213of @@cite@{The GNU Make Manual@}, 12214for @@code@{make@}, version @@value@{VERSION@}. |
| 12215 12216Copyright @dots{} 12217 12218Permission is granted @dots{} 12219@@end copying |
|
| 12109@end group 12110@end example 12111 12112@item 12113Write text for the title page, for people reading the printed manual: | 12220@end group 12221@end example 12222 12223@item 12224Write text for the title page, for people reading the printed manual: |
| 12114@c List only the month and the year since that looks less fussy on a 12115@c printed cover than a date that lists the day as well. | |
| 12116 12117@example 12118@group | 12225 12226@example 12227@group |
| 12228@@titlepage |
|
| 12119@@title GNU Make 12120@@subtitle A Program for Directing Recompilation 12121@@subtitle Edition @@value@{EDITION@}, @dots{} 12122@@subtitle @@value@{UPDATE-MONTH@} | 12229@@title GNU Make 12230@@subtitle A Program for Directing Recompilation 12231@@subtitle Edition @@value@{EDITION@}, @dots{} 12232@@subtitle @@value@{UPDATE-MONTH@} |
| 12233@@page 12234@@insertcopying 12235@dots{} 12236@@end titlepage |
|
| 12123@end group 12124@end example 12125 12126@noindent 12127(On a printed cover, a date listing the month and the year looks less 12128fussy than a date listing the day as well as the month and year.) 12129 12130@item 12131Write text for the Top node, for people reading the Info file: 12132 12133@example 12134@group | 12237@end group 12238@end example 12239 12240@noindent 12241(On a printed cover, a date listing the month and the year looks less 12242fussy than a date listing the day as well as the month and year.) 12243 12244@item 12245Write text for the Top node, for people reading the Info file: 12246 12247@example 12248@group |
| 12135This is Edition @@value@{EDITION@} 12136of the @@cite@{GNU Make Manual@}, 12137last updated @@value@{UPDATED@} 12138for @@code@{make@} Version @@value@{VERSION@}. | 12249@@ifnottex 12250@@node Top 12251@@top Make 12252 12253@@insertcopying 12254@dots{} 12255@@end ifnottex |
| 12139@end group 12140@end example 12141 | 12256@end group 12257@end example 12258 |
| 12142After you format the manual, the text in the first @code{@@ifinfo} 12143section looks like this: | 12259After you format the manual, the @code{@@value} constructs have been 12260expanded, so the output contains text like this: |
| 12144 12145@example 12146@group 12147This is Edition 0.35 Beta, last updated 14 August 1992, 12148of `The GNU Make Manual', for `make', Version 3.63 Beta. 12149@end group 12150@end example 12151@end enumerate 12152 | 12261 12262@example 12263@group 12264This is Edition 0.35 Beta, last updated 14 August 1992, 12265of `The GNU Make Manual', for `make', Version 3.63 Beta. 12266@end group 12267@end example 12268@end enumerate 12269 |
| 12153When you update the manual, change only the values of the flags; you do 12154not need to edit the three sections. | 12270When you update the manual, you change only the values of the flags; you 12271do not need to edit the three sections. |
| 12155 12156 12157@node Internationalization 12158@chapter Internationalization 12159 12160@cindex Internationalization 12161Texinfo has some support for writing in languages other than English, 12162although this area still needs considerable work. --- 492 unchanged lines hidden (view full) --- 12655always work. 12656 12657@item 12658The @TeX{} implementation cannot construct macros that define macros in 12659the natural way. To do this, you must use conditionals and raw @TeX{}. 12660For example: 12661 12662@example | 12272 12273 12274@node Internationalization 12275@chapter Internationalization 12276 12277@cindex Internationalization 12278Texinfo has some support for writing in languages other than English, 12279although this area still needs considerable work. --- 492 unchanged lines hidden (view full) --- 12772always work. 12773 12774@item 12775The @TeX{} implementation cannot construct macros that define macros in 12776the natural way. To do this, you must use conditionals and raw @TeX{}. 12777For example: 12778 12779@example |
| 12663@@ifinfo | 12780@@ifnottex |
| 12664@@macro ctor @{name, arg@} 12665@@macro \name\ 12666something involving \arg\ somehow 12667@@end macro 12668@@end macro | 12781@@macro ctor @{name, arg@} 12782@@macro \name\ 12783something involving \arg\ somehow 12784@@end macro 12785@@end macro |
| 12669@@end ifinfo | 12786@@end ifnottex |
| 12670@@tex 12671\gdef\ctor#1@{\ctorx#1,@} 12672\gdef\ctorx#1,#2,@{\def#1@{something involving #2 somehow@}@} 12673@@end tex 12674@end example 12675 12676@item 12677It is best to avoid comments inside macro definitions. --- 549 unchanged lines hidden (view full) --- 13227 13228You can change the values of these variables with the @kbd{M-x 13229edit-options} command (@pxref{Edit Options, , Editing Variable Values, 13230emacs, The GNU Emacs Manual}), with the @kbd{M-x set-variable} command 13231(@pxref{Examining, , Examining and Setting Variables, emacs, The GNU 13232Emacs Manual}), or with your @file{.emacs} initialization file 13233(@pxref{Init File, , , emacs, The GNU Emacs Manual}).@refill 13234 | 12787@@tex 12788\gdef\ctor#1@{\ctorx#1,@} 12789\gdef\ctorx#1,#2,@{\def#1@{something involving #2 somehow@}@} 12790@@end tex 12791@end example 12792 12793@item 12794It is best to avoid comments inside macro definitions. --- 549 unchanged lines hidden (view full) --- 13344 13345You can change the values of these variables with the @kbd{M-x 13346edit-options} command (@pxref{Edit Options, , Editing Variable Values, 13347emacs, The GNU Emacs Manual}), with the @kbd{M-x set-variable} command 13348(@pxref{Examining, , Examining and Setting Variables, emacs, The GNU 13349Emacs Manual}), or with your @file{.emacs} initialization file 13350(@pxref{Init File, , , emacs, The GNU Emacs Manual}).@refill 13351 |
| 13235@cindex Customize Emacs package 13236@findex Development/Docs/Texinfo Customize group | 13352@cindex Customize Emacs package (@t{Development/Docs/Texinfo}) |
| 13237Beginning with version 20, GNU Emacs offers a user-friendly interface, 13238called @dfn{Customize}, for changing values of user-definable variables. 13239@xref{Easy Customization, , Easy Customization Interface, emacs, The GNU 13240Emacs Manual}, for more details about this. The Texinfo variables can 13241be found in the @samp{Development/Docs/Texinfo} group, once you invoke 13242the @kbd{M-x customize} command. 13243 13244 | 13353Beginning with version 20, GNU Emacs offers a user-friendly interface, 13354called @dfn{Customize}, for changing values of user-definable variables. 13355@xref{Easy Customization, , Easy Customization Interface, emacs, The GNU 13356Emacs Manual}, for more details about this. The Texinfo variables can 13357be found in the @samp{Development/Docs/Texinfo} group, once you invoke 13358the @kbd{M-x customize} command. 13359 13360 |
| 13245@node Compile-Command, Requirements Summary, Texinfo Mode Printing, Hardcopy | 13361@node Compile-Command |
| 13246@section Using the Local Variables List 13247@cindex Local variables 13248@cindex Compile command for formatting 13249@cindex Format with the compile command 13250 13251Yet another way to apply the @TeX{} formatting command to a Texinfo file 13252is to put that command in a @dfn{local variables list} at the end of the 13253Texinfo file. You can then specify the @code{tex} or @code{texi2dvi} --- 384 unchanged lines hidden (view full) --- 13638sheet of film; but you can attempt to use it to mark the corners of a 13639book set to 7 by 9.25 inches with the @code{@@smallbook} command. 13640(Printers will not produce cropmarks for regular sized output that is 13641printed on regular sized paper.) Since different printing machines work 13642in different ways, you should explore the use of this command with a 13643spirit of adventure. You may have to redefine the command in 13644@file{texinfo.tex}. 13645 | 13362@section Using the Local Variables List 13363@cindex Local variables 13364@cindex Compile command for formatting 13365@cindex Format with the compile command 13366 13367Yet another way to apply the @TeX{} formatting command to a Texinfo file 13368is to put that command in a @dfn{local variables list} at the end of the 13369Texinfo file. You can then specify the @code{tex} or @code{texi2dvi} --- 384 unchanged lines hidden (view full) --- 13754sheet of film; but you can attempt to use it to mark the corners of a 13755book set to 7 by 9.25 inches with the @code{@@smallbook} command. 13756(Printers will not produce cropmarks for regular sized output that is 13757printed on regular sized paper.) Since different printing machines work 13758in different ways, you should explore the use of this command with a 13759spirit of adventure. You may have to redefine the command in 13760@file{texinfo.tex}. 13761 |
| 13646@findex mag @r{(@TeX{} command)} | 13762@findex \mag @r{(raw @TeX{} magnification)} |
| 13647@cindex Magnified printing 13648@cindex Larger or smaller pages 13649You can attempt to direct @TeX{} to typeset pages larger or smaller than 13650usual with the @code{\mag} @TeX{} command. Everything that is typeset 13651is scaled proportionally larger or smaller. (@code{\mag} stands for 13652``magnification''.) This is @emph{not} a Texinfo @@-command, but is a 13653plain @TeX{} command that is prefixed with a backslash. You have to 13654write this command between @code{@@tex} and @code{@@end tex} --- 54 unchanged lines hidden (view full) --- 13709@node Creating and Installing Info Files 13710@chapter Creating and Installing Info Files 13711 13712This chapter describes how to create and install Info files. @xref{Info 13713Files}, for general information about the file format itself. 13714 13715@menu 13716* Creating an Info File:: | 13763@cindex Magnified printing 13764@cindex Larger or smaller pages 13765You can attempt to direct @TeX{} to typeset pages larger or smaller than 13766usual with the @code{\mag} @TeX{} command. Everything that is typeset 13767is scaled proportionally larger or smaller. (@code{\mag} stands for 13768``magnification''.) This is @emph{not} a Texinfo @@-command, but is a 13769plain @TeX{} command that is prefixed with a backslash. You have to 13770write this command between @code{@@tex} and @code{@@end tex} --- 54 unchanged lines hidden (view full) --- 13825@node Creating and Installing Info Files 13826@chapter Creating and Installing Info Files 13827 13828This chapter describes how to create and install Info files. @xref{Info 13829Files}, for general information about the file format itself. 13830 13831@menu 13832* Creating an Info File:: |
| 13717* Installing an Info File:: | 13833* Installing an Info File:: |
| 13718@end menu 13719 13720 13721@node Creating an Info File 13722@section Creating an Info File 13723@cindex Creating an Info file 13724@cindex Info, creating an online file 13725@cindex Formatting a file for Info --- 63 unchanged lines hidden (view full) --- 13789makeinfo --version 13790@end example 13791 13792@xref{makeinfo options}, for more information. 13793@end ifinfo 13794 13795 13796@node makeinfo options | 13834@end menu 13835 13836 13837@node Creating an Info File 13838@section Creating an Info File 13839@cindex Creating an Info file 13840@cindex Info, creating an online file 13841@cindex Formatting a file for Info --- 63 unchanged lines hidden (view full) --- 13905makeinfo --version 13906@end example 13907 13908@xref{makeinfo options}, for more information. 13909@end ifinfo 13910 13911 13912@node makeinfo options |
| 13797@comment node-name, next, previous, up | |
| 13798@subsection Options for @code{makeinfo} 13799@cindex @code{makeinfo} options 13800@cindex Options for @code{makeinfo} 13801 13802The @code{makeinfo} command takes a number of options. Most often, 13803options are used to set the value of the fill column and specify the 13804footnote style. Each command line option is a word preceded by 13805@samp{--} or a letter preceded by @samp{-}. You can use abbreviations --- 109 unchanged lines hidden (view full) --- 13915that does not support @code{@@macro}. 13916 13917@item --no-headers 13918@opindex --no-headers 13919@cindex Plain text output 13920@cindex ASCII text output 13921@cindex Generating plain text files 13922@cindex @file{INSTALL} file, generating | 13913@subsection Options for @code{makeinfo} 13914@cindex @code{makeinfo} options 13915@cindex Options for @code{makeinfo} 13916 13917The @code{makeinfo} command takes a number of options. Most often, 13918options are used to set the value of the fill column and specify the 13919footnote style. Each command line option is a word preceded by 13920@samp{--} or a letter preceded by @samp{-}. You can use abbreviations --- 109 unchanged lines hidden (view full) --- 14030that does not support @code{@@macro}. 14031 14032@item --no-headers 14033@opindex --no-headers 14034@cindex Plain text output 14035@cindex ASCII text output 14036@cindex Generating plain text files 14037@cindex @file{INSTALL} file, generating |
| 13923For Info output, do not include menus or node lines in the output and 13924write to standard output (unless @option{--output} is specified). This 13925results in an @sc{ascii} file that you cannot read in Info since it does 13926not contain the requisite nodes or menus. It is primarily useful to 13927extract certain pieces of a manual into separate files to be included in 13928a distribution, such as @file{INSTALL} files. | 14038@cindex Node separators, omitting 14039@cindex Menus, omitting 14040For Info output, do not include menus or node separator lines in the 14041output. This results in a simple plain text file that you can (for 14042example) send in email without complications, or include in a 14043distribution (as in an @file{INSTALL} file). |
| 13929 13930@cindex Navigation links, omitting | 14044 14045@cindex Navigation links, omitting |
| 13931For HTML output, if @samp{--no-split} is also specified, do not include a 13932navigation links at the top of each node. @xref{makeinfo html}. | 14046For HTML output, likewise omit menus. And if @samp{--no-split} is also 14047specified, do not include a navigation links at the top of each node 14048(these are never included in the default case of split output). 14049@xref{makeinfo html}. |
| 13933 | 14050 |
| 14051In both cases, write to standard output by default (can still be 14052overridden by @option{-o}). 14053 |
|
| 13934@item --no-split 13935@opindex --no-split 13936@cindex Splitting of output files 13937@cindex Output file splitting 13938Suppress the splitting stage of @code{makeinfo}. By default, large 13939output files (where the size is greater than 70k bytes) are split into 13940smaller subfiles. For Info output, each one is approximately 50k bytes. 13941For HTML output, each file contains one node (@pxref{makeinfo html}). --- 475 unchanged lines hidden (view full) --- 14417which have special significance in HTML). 14418 14419The @samp{--footnote-style} option is currently ignored for HTML output; 14420footnotes are linked to the end of the output file. 14421 14422The HTML generated is mostly standard (i.e., HTML 2.0, RFC-1866). The 14423exception is that HTML 3.2 tables are generated from the 14424@code{@@multitable} command, but tagged to degrade as well as possible | 14054@item --no-split 14055@opindex --no-split 14056@cindex Splitting of output files 14057@cindex Output file splitting 14058Suppress the splitting stage of @code{makeinfo}. By default, large 14059output files (where the size is greater than 70k bytes) are split into 14060smaller subfiles. For Info output, each one is approximately 50k bytes. 14061For HTML output, each file contains one node (@pxref{makeinfo html}). --- 475 unchanged lines hidden (view full) --- 14537which have special significance in HTML). 14538 14539The @samp{--footnote-style} option is currently ignored for HTML output; 14540footnotes are linked to the end of the output file. 14541 14542The HTML generated is mostly standard (i.e., HTML 2.0, RFC-1866). The 14543exception is that HTML 3.2 tables are generated from the 14544@code{@@multitable} command, but tagged to degrade as well as possible |
| 14425in browsers without table support. Please report output from an 14426error-free run of @code{makeinfo} which violates the @w{HTML 3.2} DTD as 14427a bug. | 14545in browsers without table support. The HTML 4 @samp{lang} attribute on 14546the @samp{<html>} attribute is also used. Please report output from an 14547error-free run of @code{makeinfo} which has browser portability problems 14548as a bug. |
| 14428 14429Navigation bars are inserted at the start of nodes, similarly to Info 14430output. The @samp{--no-headers} option will suppress this if used with 14431@samp{--no-split}. Header @code{<link>} elements in split output can 14432support info-like navigation with browsers like Lynx and @w{Emacs W3} 14433which implement this @w{HTML 1.0} feature. @samp{@@xref} commands to 14434other documents are generated assuming the other document is available 14435in split HTML form, and installed in the same HTML documentation tree, --- 7 unchanged lines hidden (view full) --- 14443@cindex @file{dir} directory for Info installation 14444 14445Info files are usually kept in the @file{info} directory. You can read 14446Info files using the standalone Info program or the Info reader built 14447into Emacs. (@inforef{Top, info, info}, for an introduction to Info.) 14448 14449@menu 14450* Directory File:: The top level menu for all Info files. | 14549 14550Navigation bars are inserted at the start of nodes, similarly to Info 14551output. The @samp{--no-headers} option will suppress this if used with 14552@samp{--no-split}. Header @code{<link>} elements in split output can 14553support info-like navigation with browsers like Lynx and @w{Emacs W3} 14554which implement this @w{HTML 1.0} feature. @samp{@@xref} commands to 14555other documents are generated assuming the other document is available 14556in split HTML form, and installed in the same HTML documentation tree, --- 7 unchanged lines hidden (view full) --- 14564@cindex @file{dir} directory for Info installation 14565 14566Info files are usually kept in the @file{info} directory. You can read 14567Info files using the standalone Info program or the Info reader built 14568into Emacs. (@inforef{Top, info, info}, for an introduction to Info.) 14569 14570@menu 14571* Directory File:: The top level menu for all Info files. |
| 14451* New Info File:: Listing a new info file. | 14572* New Info File:: Listing a new Info file. |
| 14452* Other Info Directories:: How to specify Info files that are 14453 located in other directories. 14454* Installing Dir Entries:: How to specify what menu entry to add 14455 to the Info directory. 14456* Invoking install-info:: @code{install-info} options. 14457@end menu 14458 14459 --- 223 unchanged lines hidden (view full) --- 14683 14684When you install an Info file onto your system, you can use the program 14685@code{install-info} to update the Info directory file @file{dir}. 14686Normally the makefile for the package runs @code{install-info}, just 14687after copying the Info file into its proper installed location. 14688 14689@findex dircategory 14690@findex direntry | 14573* Other Info Directories:: How to specify Info files that are 14574 located in other directories. 14575* Installing Dir Entries:: How to specify what menu entry to add 14576 to the Info directory. 14577* Invoking install-info:: @code{install-info} options. 14578@end menu 14579 14580 --- 223 unchanged lines hidden (view full) --- 14804 14805When you install an Info file onto your system, you can use the program 14806@code{install-info} to update the Info directory file @file{dir}. 14807Normally the makefile for the package runs @code{install-info}, just 14808after copying the Info file into its proper installed location. 14809 14810@findex dircategory 14811@findex direntry |
| 14691In order for the Info file to work with @code{install-info}, you should 14692use the commands @code{@@dircategory} and | 14812In order for the Info file to work with @code{install-info}, you include 14813the commands @code{@@dircategory} and |
| 14693@code{@@direntry}@dots{}@code{@@end direntry} in the Texinfo source 14694file. Use @code{@@direntry} to specify the menu entries to add to the 14695Info directory file, and use @code{@@dircategory} to specify which part 14696of the Info directory to put it in. Here is how these commands are used 14697in this manual: 14698 14699@smallexample 14700@@dircategory Texinfo documentation system --- 31 unchanged lines hidden (view full) --- 14732Here are some recommended @code{@@dircategory} categories: 14733 14734@display 14735GNU packages 14736GNU programming tools 14737GNU programming documentation 14738GNU Emacs Lisp 14739GNU libraries | 14814@code{@@direntry}@dots{}@code{@@end direntry} in the Texinfo source 14815file. Use @code{@@direntry} to specify the menu entries to add to the 14816Info directory file, and use @code{@@dircategory} to specify which part 14817of the Info directory to put it in. Here is how these commands are used 14818in this manual: 14819 14820@smallexample 14821@@dircategory Texinfo documentation system --- 31 unchanged lines hidden (view full) --- 14853Here are some recommended @code{@@dircategory} categories: 14854 14855@display 14856GNU packages 14857GNU programming tools 14858GNU programming documentation 14859GNU Emacs Lisp 14860GNU libraries |
| 14740Linux | |
| 14741TeX 14742Individual utilities 14743@end display 14744 14745The idea is to include the `Invoking' node for every program installed 14746by a package under `Individual utilities', and an entry for the manual 14747as a whole in the appropriate other category. 14748 --- 135 unchanged lines hidden (view full) --- 14884 14885@item @@" 14886@itemx @@' 14887Generate an umlaut or acute accent, respectively, over the next 14888character, as in @"o and @'o. @xref{Inserting Accents}. 14889 14890@item @@* 14891Force a line break. Do not end a paragraph that uses @code{@@*} with | 14861TeX 14862Individual utilities 14863@end display 14864 14865The idea is to include the `Invoking' node for every program installed 14866by a package under `Individual utilities', and an entry for the manual 14867as a whole in the appropriate other category. 14868 --- 135 unchanged lines hidden (view full) --- 15004 15005@item @@" 15006@itemx @@' 15007Generate an umlaut or acute accent, respectively, over the next 15008character, as in @"o and @'o. @xref{Inserting Accents}. 15009 15010@item @@* 15011Force a line break. Do not end a paragraph that uses @code{@@*} with |
| 14892an @code{@@refill} command. @xref{Line Breaks}.@refill | 15012an @code{@@refill} command. @xref{Line Breaks}. |
| 14893 14894@item @@,@{@var{c}@} 14895Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting 14896Accents}. 14897 14898@item @@- 14899Insert a discretionary hyphenation point. @xref{- and hyphenation}. 14900 --- 15 unchanged lines hidden (view full) --- 14916@item @@? 14917Generate a question mark that really does end a sentence (usually after 14918an end-of-sentence capital letter). @xref{Ending a Sentence}. 14919 14920@item @@@@ 14921Stands for an at sign, @samp{@@}. 14922@xref{Braces Atsigns, , Inserting @@ and braces}. 14923 | 15013 15014@item @@,@{@var{c}@} 15015Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting 15016Accents}. 15017 15018@item @@- 15019Insert a discretionary hyphenation point. @xref{- and hyphenation}. 15020 --- 15 unchanged lines hidden (view full) --- 15036@item @@? 15037Generate a question mark that really does end a sentence (usually after 15038an end-of-sentence capital letter). @xref{Ending a Sentence}. 15039 15040@item @@@@ 15041Stands for an at sign, @samp{@@}. 15042@xref{Braces Atsigns, , Inserting @@ and braces}. 15043 |
| 15044@item @@\ 15045Stands for a backslash (@samp{\}) inside @code{@@math}. 15046@xref{math,,@code{math}}. 15047 |
|
| 14924@item @@^ 14925@itemx @@` 14926Generate a circumflex (hat) or grave accent, respectively, over the next | 15048@item @@^ 15049@itemx @@` 15050Generate a circumflex (hat) or grave accent, respectively, over the next |
| 14927character, as in @^o. | 15051character, as in @^o and @`e. |
| 14928@xref{Inserting Accents}. 14929 14930@item @@@{ 14931Stands for a left brace, @samp{@{}. 14932@xref{Braces Atsigns, , Inserting @@ and braces}. 14933 14934@item @@@} 14935Stands for a right-hand brace, @samp{@}}.@* --- 376 unchanged lines hidden (view full) --- 15312 15313@item @@error@{@} 15314Indicate to the reader with a glyph that the following text is 15315an error message: @samp{@error{}}. @xref{Error Glyph}.@refill 15316 15317@item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] 15318@itemx @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}] 15319Specify page footings resp.@: headings for even-numbered (left-hand) | 15052@xref{Inserting Accents}. 15053 15054@item @@@{ 15055Stands for a left brace, @samp{@{}. 15056@xref{Braces Atsigns, , Inserting @@ and braces}. 15057 15058@item @@@} 15059Stands for a right-hand brace, @samp{@}}.@* --- 376 unchanged lines hidden (view full) --- 15436 15437@item @@error@{@} 15438Indicate to the reader with a glyph that the following text is 15439an error message: @samp{@error{}}. @xref{Error Glyph}.@refill 15440 15441@item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] 15442@itemx @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}] 15443Specify page footings resp.@: headings for even-numbered (left-hand) |
| 15320pages. Only allowed inside @code{@@iftex}. @xref{Custom Headings, , | 15444pages. @xref{Custom Headings, , |
| 15321How to Make Your Own Headings}.@refill 15322 15323@item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] 15324@itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}] 15325Specify page footings resp.@: headings for every page. Not relevant to 15326Info. @xref{Custom Headings, , How to Make Your Own Headings}.@refill 15327 15328@item @@example --- 82 unchanged lines hidden (view full) --- 15411Enter HTML completely. Pair with @code{@@end html}. @xref{Raw 15412Formatter Commands}. 15413 15414@item @@hyphenation@{@var{hy-phen-a-ted words}@} 15415Explicitly define hyphenation points. @xref{- and hyphenation,, 15416@code{@@-} and @code{@@hyphenation}}. 15417 15418@item @@i@{@var{text}@} | 15445How to Make Your Own Headings}.@refill 15446 15447@item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] 15448@itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}] 15449Specify page footings resp.@: headings for every page. Not relevant to 15450Info. @xref{Custom Headings, , How to Make Your Own Headings}.@refill 15451 15452@item @@example --- 82 unchanged lines hidden (view full) --- 15535Enter HTML completely. Pair with @code{@@end html}. @xref{Raw 15536Formatter Commands}. 15537 15538@item @@hyphenation@{@var{hy-phen-a-ted words}@} 15539Explicitly define hyphenation points. @xref{- and hyphenation,, 15540@code{@@-} and @code{@@hyphenation}}. 15541 15542@item @@i@{@var{text}@} |
| 15419Print @var{text} in @i{italic} font. No effect in Info. 15420@xref{Fonts}.@refill | 15543Print @var{text} in @i{italic} font. No effect in Info. @xref{Fonts}. |
| 15421 15422@item @@ifclear @var{flag} 15423If @var{flag} is cleared, the Texinfo formatting commands format text 15424between @code{@@ifclear @var{flag}} and the following @code{@@end 15425ifclear} command. 15426@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill 15427 15428@item @@ifhtml 15429@itemx @@ifinfo 15430Begin a stretch of text that will be ignored by @TeX{} when it typesets | 15544 15545@item @@ifclear @var{flag} 15546If @var{flag} is cleared, the Texinfo formatting commands format text 15547between @code{@@ifclear @var{flag}} and the following @code{@@end 15548ifclear} command. 15549@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill 15550 15551@item @@ifhtml 15552@itemx @@ifinfo 15553Begin a stretch of text that will be ignored by @TeX{} when it typesets |
| 15431the printed manual. The text appears only in the HTML resp.@: Info 15432file. Pair with @code{@@end ifhtml} resp.@: @code{@@end ifinfo}. 15433@xref{Conditionals}. | 15554the printed manual. @code{@@ifhtml} text appears only in the HTML 15555output. @code{@@ifinfo} output appears in both Info and (for historical 15556compatibility) plain text output . Pair with @code{@@end ifhtml} 15557resp.@: @code{@@end ifinfo}. @xref{Conditionals}. |
| 15434 15435@item @@ifnothtml 15436@itemx @@ifnotinfo | 15558 15559@item @@ifnothtml 15560@itemx @@ifnotinfo |
| 15561@itemx @@ifnotplaintext |
|
| 15437@itemx @@ifnottex 15438Begin a stretch of text that will be ignored in one output format but | 15562@itemx @@ifnottex 15563Begin a stretch of text that will be ignored in one output format but |
| 15439not the others. The text appears only in the format not specified. 15440Pair with @code{@@end ifnothtml} resp.@: @code{@@end ifnotinfo} resp.@: 15441@code{@@end ifnotinfo}. @xref{Conditionals}. | 15564not the others. The text appears in the formats not specified: 15565@code{@@ifnothtml} text is omitted from html output, etc. The exception 15566is @code{@@ifnotinfo} text, which is omitted from plain text output as 15567well as Info output. Pair with @code{@@end ifnothtml} resp.@: 15568@code{@@end ifnotinfo} resp.@: @code{@@end ifnotplaintext} resp.@: 15569@code{@@end ifnottex}. @xref{Conditionals}. |
| 15442 | 15570 |
| 15571@item @@ifplaintext 15572Begin a stretch of text that appears only in the plain text output. 15573Pair with @code{@@end ifplaintext}. @xref{Conditionals}. 15574 |
|
| 15443@item @@ifset @var{flag} 15444If @var{flag} is set, the Texinfo formatting commands format text 15445between @code{@@ifset @var{flag}} and the following @code{@@end ifset} 15446command. 15447@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill 15448 15449@item @@iftex 15450Begin a stretch of text that will not appear in the Info file, but --- 20 unchanged lines hidden (view full) --- 15471@code{@@inforef}}.@refill 15472 15473@item \input @var{macro-definitions-file} 15474Use the specified macro definitions file. This command is used only 15475in the first line of a Texinfo file to cause @TeX{} to make use of the 15476@file{texinfo} macro definitions file. The backslash in @code{\input} 15477is used instead of an @code{@@} because @TeX{} does not 15478recognize @code{@@} until after it has read the definitions file. | 15575@item @@ifset @var{flag} 15576If @var{flag} is set, the Texinfo formatting commands format text 15577between @code{@@ifset @var{flag}} and the following @code{@@end ifset} 15578command. 15579@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill 15580 15581@item @@iftex 15582Begin a stretch of text that will not appear in the Info file, but --- 20 unchanged lines hidden (view full) --- 15603@code{@@inforef}}.@refill 15604 15605@item \input @var{macro-definitions-file} 15606Use the specified macro definitions file. This command is used only 15607in the first line of a Texinfo file to cause @TeX{} to make use of the 15608@file{texinfo} macro definitions file. The backslash in @code{\input} 15609is used instead of an @code{@@} because @TeX{} does not 15610recognize @code{@@} until after it has read the definitions file. |
| 15479@xref{Header, , The Texinfo File Header}.@refill | 15611@xref{Texinfo File Header}. |
| 15480 15481@item @@item 15482Indicate the beginning of a marked paragraph for @code{@@itemize} and 15483@code{@@enumerate}; indicate the beginning of the text of a first column 15484entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}. 15485@xref{Lists and Tables}.@refill 15486 15487@item @@itemize @var{mark-generating-character-or-command} --- 89 unchanged lines hidden (view full) --- 15577@item @@O@{@} 15578@itemx @@o@{@} 15579Generate the uppercase and lowercase O-with-slash letters, respectively: 15580@O{}, @o{}. 15581 15582@item @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] 15583@itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}] 15584Specify page footings resp.@: headings for odd-numbered (right-hand) | 15612 15613@item @@item 15614Indicate the beginning of a marked paragraph for @code{@@itemize} and 15615@code{@@enumerate}; indicate the beginning of the text of a first column 15616entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}. 15617@xref{Lists and Tables}.@refill 15618 15619@item @@itemize @var{mark-generating-character-or-command} --- 89 unchanged lines hidden (view full) --- 15709@item @@O@{@} 15710@itemx @@o@{@} 15711Generate the uppercase and lowercase O-with-slash letters, respectively: 15712@O{}, @o{}. 15713 15714@item @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] 15715@itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}] 15716Specify page footings resp.@: headings for odd-numbered (right-hand) |
| 15585pages. Only allowed inside @code{@@iftex}. @xref{Custom Headings, , | 15717pages. @xref{Custom Headings, , |
| 15586How to Make Your Own Headings}.@refill 15587 15588@item @@OE@{@} 15589@itemx @@oe@{@} 15590Generate the uppercase and lowercase OE ligatures, respectively: 15591@OE{}, @oe{}. @xref{Inserting Accents}. 15592 15593@item @@option@{@var{option-name}@} --- 279 unchanged lines hidden (view full) --- 15873@xref{titlepage, , @code{@@titlepage}}.@refill 15874 15875@item @@today@{@} 15876Insert the current date, in `1 Jan 1900' style. @xref{Custom 15877Headings, , How to Make Your Own Headings}.@refill 15878 15879@item @@top @var{title} 15880In a Texinfo file to be formatted with @code{makeinfo}, identify the | 15718How to Make Your Own Headings}.@refill 15719 15720@item @@OE@{@} 15721@itemx @@oe@{@} 15722Generate the uppercase and lowercase OE ligatures, respectively: 15723@OE{}, @oe{}. @xref{Inserting Accents}. 15724 15725@item @@option@{@var{option-name}@} --- 279 unchanged lines hidden (view full) --- 16005@xref{titlepage, , @code{@@titlepage}}.@refill 16006 16007@item @@today@{@} 16008Insert the current date, in `1 Jan 1900' style. @xref{Custom 16009Headings, , How to Make Your Own Headings}.@refill 16010 16011@item @@top @var{title} 16012In a Texinfo file to be formatted with @code{makeinfo}, identify the |
| 15881topmost @code{@@node} line in the file, which must be written on the line | 16013topmost @code{@@node} in the file, which must be written on the line |
| 15882immediately preceding the @code{@@top} command. Used for 15883@code{makeinfo}'s node pointer insertion feature. The title is 15884underlined with asterisks. Both the @code{@@node} line and the @code{@@top} | 16014immediately preceding the @code{@@top} command. Used for 16015@code{makeinfo}'s node pointer insertion feature. The title is 16016underlined with asterisks. Both the @code{@@node} line and the @code{@@top} |
| 15885line normally should be enclosed by @code{@@ifinfo} and @code{@@end 15886ifinfo}. In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top} | 16017line normally should be enclosed by @code{@@ifnottex} and @code{@@end 16018ifnottex}. In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top} |
| 15887command is merely a synonym for @code{@@unnumbered}. @xref{makeinfo 15888Pointer Creation, , Creating Pointers with @code{makeinfo}}. 15889 15890@item @@u@{@var{c}@} 15891@itemx @@ubaraccent@{@var{c}@} 15892@itemx @@udotaccent@{@var{c}@} 15893Generate a breve, underbar, or underdot accent, respectively, over or 15894under the character @var{c}, as in @u{o}, @ubaraccent{o}, --- 65 unchanged lines hidden (view full) --- 15960Add @var{entry} to the index of variables. @xref{Index Entries, , 15961Defining the Entries of an Index}.@refill 15962 15963@item @@vskip @var{amount} 15964In a printed manual, insert whitespace so as to push text on the 15965remainder of the page towards the bottom of the page. Used in 15966formatting the copyright page with the argument @samp{0pt plus 159671filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used | 16019command is merely a synonym for @code{@@unnumbered}. @xref{makeinfo 16020Pointer Creation, , Creating Pointers with @code{makeinfo}}. 16021 16022@item @@u@{@var{c}@} 16023@itemx @@ubaraccent@{@var{c}@} 16024@itemx @@udotaccent@{@var{c}@} 16025Generate a breve, underbar, or underdot accent, respectively, over or 16026under the character @var{c}, as in @u{o}, @ubaraccent{o}, --- 65 unchanged lines hidden (view full) --- 16092Add @var{entry} to the index of variables. @xref{Index Entries, , 16093Defining the Entries of an Index}.@refill 16094 16095@item @@vskip @var{amount} 16096In a printed manual, insert whitespace so as to push text on the 16097remainder of the page towards the bottom of the page. Used in 16098formatting the copyright page with the argument @samp{0pt plus 160991filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used |
| 15968only in contexts ignored for Info. @xref{Copyright & Permissions, , 15969The Copyright Page and Printed Permissions}.@refill | 16100only in contexts ignored for Info. @xref{Copyright}. |
| 15970 15971@item @@vtable @var{formatting-command} 15972Begin a two-column table, using @code{@@item} for each entry. 15973Automatically enter each of the items in the first column into the 15974index of variables. Pair with @code{@@end vtable}. The same as 15975@code{@@table}, except for indexing. @xref{ftable vtable, , 15976@code{@@ftable} and @code{@@vtable}}.@refill 15977 --- 154 unchanged lines hidden (view full) --- 16132@item 16133Write the prefatory sentence or phrase for a multi-item list or table as 16134a complete expression. Do not write ``You can set:''; instead, write 16135``You can set these variables:''. The former expression sounds cut off. 16136@end itemize 16137 16138@subsubheading Editions, Dates and Versions 16139 | 16101 16102@item @@vtable @var{formatting-command} 16103Begin a two-column table, using @code{@@item} for each entry. 16104Automatically enter each of the items in the first column into the 16105index of variables. Pair with @code{@@end vtable}. The same as 16106@code{@@table}, except for indexing. @xref{ftable vtable, , 16107@code{@@ftable} and @code{@@vtable}}.@refill 16108 --- 154 unchanged lines hidden (view full) --- 16263@item 16264Write the prefatory sentence or phrase for a multi-item list or table as 16265a complete expression. Do not write ``You can set:''; instead, write 16266``You can set these variables:''. The former expression sounds cut off. 16267@end itemize 16268 16269@subsubheading Editions, Dates and Versions 16270 |
| 16140Write the edition and version numbers and date in three places in every 16141manual: | 16271Include edition numbers, version numbers, and dates in the 16272@code{@@copying} text (for people reading the Texinfo file, and for the 16273legal copyright in the output files). Then use @code{@@insertcopying} 16274in the @code{@@titlepage} section (for people reading the printed 16275output) and the Top node (for people reading the online output). |
| 16142 | 16276 |
| 16143@enumerate 16144@item 16145In the first @code{@@ifinfo} section, for people reading the Texinfo file. | 16277It is easiest to do this using @code{@@set} and @code{@@value}. 16278@xref{value Example, , @code{@@value} Example}, and @ref{GNU Sample Texts}. |
| 16146 | 16279 |
| 16147@item 16148In the @code{@@titlepage} section, for people reading the printed manual. | |
| 16149 | 16280 |
| 16150@item 16151In the `Top' node, for people reading the Info file. 16152@end enumerate 16153 16154@noindent 16155Also, it helps to write a note before the first @code{@@ifinfo} 16156section to explain what you are doing. 16157 16158@need 800 16159@noindent 16160For example: 16161 16162@example 16163@group 16164@@c ===> NOTE! <== 16165@@c Specify the edition and version numbers and date 16166@@c in *three* places: 16167@@c 1. First ifinfo section 2. title page 3. top node 16168@@c To find the locations, search for !!set 16169@end group 16170 16171@group 16172@@ifinfo 16173@@c !!set edition, date, version 16174This is Edition 4.03, January 1992, 16175of the @@cite@{GDB Manual@} for GDB Version 4.3. 16176@dots{} 16177@end group 16178@end example 16179 16180@noindent 16181---or use @code{@@set} and @code{@@value} 16182(@pxref{value Example, , @code{@@value} Example}). 16183 | |
| 16184@subsubheading Definition Commands 16185 16186Definition commands are @code{@@deffn}, @code{@@defun}, 16187@code{@@defmac}, and the like, and enable you to write descriptions in 16188a uniform format.@refill 16189 16190@itemize @bullet 16191@item --- 232 unchanged lines hidden (view full) --- 16424@item 16425Write notes for yourself at the very end of a Texinfo file after the 16426@code{@@bye}. None of the formatters process text after the 16427@code{@@bye}; it is as if the text were within @code{@@ignore} @dots{} 16428@code{@@end ignore}. 16429@end itemize 16430 16431 | 16281@subsubheading Definition Commands 16282 16283Definition commands are @code{@@deffn}, @code{@@defun}, 16284@code{@@defmac}, and the like, and enable you to write descriptions in 16285a uniform format.@refill 16286 16287@itemize @bullet 16288@item --- 232 unchanged lines hidden (view full) --- 16521@item 16522Write notes for yourself at the very end of a Texinfo file after the 16523@code{@@bye}. None of the formatters process text after the 16524@code{@@bye}; it is as if the text were within @code{@@ignore} @dots{} 16525@code{@@end ignore}. 16526@end itemize 16527 16528 |
| 16432@node Sample Texinfo File 16433@appendix A Sample Texinfo File | 16529@node Sample Texinfo Files 16530@appendix Sample Texinfo Files 16531@cindex Sample Texinfo files 16532 16533The first example is from the first chapter (@pxref{Short Sample}), 16534given here in its entirety, without commentary. The second sample 16535includes the full texts to be used in GNU manuals. 16536 16537@menu 16538* Short Sample Texinfo File:: 16539* GNU Sample Texts:: 16540@end menu 16541 16542 16543@node Short Sample Texinfo File 16544@section Short Sample |
| 16434@cindex Sample Texinfo file, no comments 16435 16436Here is a complete, short sample Texinfo file, without any commentary. | 16545@cindex Sample Texinfo file, no comments 16546 16547Here is a complete, short sample Texinfo file, without any commentary. |
| 16437You can see this file, with comments, in the first chapter. 16438@xref{Short Sample, , A Short Sample Texinfo File}. | 16548You can see this file, with comments, in the first chapter. @xref{Short 16549Sample}. |
| 16439 | 16550 |
| 16551In a nutshell: The @command{makeinfo} program transforms a Texinfo 16552source file such as this into an Info file or HTML; and @TeX{} typesets 16553it for a printed manual. 16554 16555 |
|
| 16440@sp 1 16441@example 16442\input texinfo @@c -*-texinfo-*- 16443@@c %**start of header 16444@@setfilename sample.info | 16556@sp 1 16557@example 16558\input texinfo @@c -*-texinfo-*- 16559@@c %**start of header 16560@@setfilename sample.info |
| 16445@@settitle Sample Document | 16561@@settitle Sample Manual 1.0 |
| 16446@@c %**end of header 16447 | 16562@@c %**end of header 16563 |
| 16448@@ifinfo | 16564@@copying |
| 16449This is a short example of a complete Texinfo file. 16450 16451Copyright (C) 2002 Free Software Foundation, Inc. | 16565This is a short example of a complete Texinfo file. 16566 16567Copyright (C) 2002 Free Software Foundation, Inc. |
| 16452@@end ifinfo | 16568@@end copying |
| 16453 16454@@titlepage | 16569 16570@@titlepage |
| 16455@@comment The title is printed in a large font. | |
| 16456@@title Sample Title | 16571@@title Sample Title |
| 16457 16458@@c The following two commands start the copyright page. | |
| 16459@@page 16460@@vskip 0pt plus 1filll | 16572@@page 16573@@vskip 0pt plus 1filll |
| 16461Copyright @@copyright@{@} 2002 Free Software Foundation, Inc. | 16574@@insertcopying |
| 16462@@end titlepage 16463 16464@@c Output the table of the contents at the beginning. 16465@@contents 16466 16467@@ifnottex 16468@@node Top 16469 | 16575@@end titlepage 16576 16577@@c Output the table of the contents at the beginning. 16578@@contents 16579 16580@@ifnottex 16581@@node Top 16582 |
| 16470This is the top node of a sample document. | 16583@@insertcopying |
| 16471@@end ifnottex 16472 16473@@menu 16474* First Chapter:: The first chapter is the | 16584@@end ifnottex 16585 16586@@menu 16587* First Chapter:: The first chapter is the |
| 16475 only chapter in this sample. 16476* Concept Index:: This index has two entries. | 16588 only chapter in this sample. 16589* Index:: Complete index. |
| 16477@@end menu 16478 16479 | 16590@@end menu 16591 16592 |
| 16480@@node First Chapter | 16593@@node First Chapter |
| 16481@@chapter First Chapter | 16594@@chapter First Chapter |
| 16482@@cindex Chapter, first | |
| 16483 | 16595 |
| 16484This is the contents of the first chapter. 16485@@cindex Another sample index entry | 16596@@cindex chapter, first |
| 16486 | 16597 |
| 16598This is the first chapter. 16599@@cindex index entry, another 16600 |
|
| 16487Here is a numbered list. 16488 16489@@enumerate 16490@@item 16491This is the first item. 16492 16493@@item 16494This is the second item. 16495@@end enumerate 16496 | 16601Here is a numbered list. 16602 16603@@enumerate 16604@@item 16605This is the first item. 16606 16607@@item 16608This is the second item. 16609@@end enumerate 16610 |
| 16497The @@code@{makeinfo@} command transforms a Texinfo source file 16498such as this into an Info file or HTML; and @@TeX typesets it 16499for a printed manual. | |
| 16500 | 16611 |
| 16612@@node Index 16613@@unnumbered Index |
|
| 16501 | 16614 |
| 16502@@node Concept Index 16503@@unnumbered Concept Index | 16615@@printindex cp |
| 16504 | 16616 |
| 16617@@bye 16618@end example 16619 16620 16621@node GNU Sample Texts 16622@section GNU Sample Texts 16623 16624@cindex GNU sample texts 16625@cindex Sample texts, GNU 16626@cindex Full texts, GNU 16627 16628Here is a sample Texinfo document with the full texts that should be 16629used in GNU manuals. 16630 16631As well as the legal texts, it also serves as a practical example of how 16632many elements in a GNU system can affect the manual. If you're not 16633familiar with all these different elements, don't worry. They're not 16634required and a perfectly good manual can be written without them. 16635They're included here nonetheless because many manuals do (or could) 16636benefit from them. 16637 16638@xref{Short Sample}, for a minimal example of a Texinfo file. 16639@xref{Beginning a File}, for a full explanation of that minimal 16640example. 16641 16642Here are some notes on the example: 16643 16644@itemize @bullet 16645@item 16646@cindex $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $ comment 16647@cindex CVS $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $, in Texinfo 16648@cindex RCS $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $, in Texinfo 16649The @samp{$Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $} comment is for CVS (@pxref{Top,, Overview, cvs, 16650Concurrent Versions System}) or RCS (see rcsintro(1)) version control 16651systems, which expand it into a string such as: 16652@example 16653$Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $ 16654@end example 16655(This is useful in all sources that use version control, not just manuals.) 16656 16657@item 16658@pindex automake@r{, and version info} 16659The @file{version.texi} in the @code{@@include} command is maintained 16660automatically by Automake (@pxref{Top,, Introduction, automake, GNU 16661Automake}). It sets the @samp{VERSION} and @samp{UPDATED} values used 16662elsewhere. If your distribution doesn't use Automake, you can mimic 16663these or equivalent settings. 16664 16665@item 16666The @code{@@syncodeindex} command reflects the recommendation to use only 16667one index if at all possible, to make it easier for readers. 16668 16669@item 16670The @code{@@dircategory} is for constructing the Info directory. 16671@xref{Installing Dir Entries}, which includes a variety of recommended 16672category names. 16673 16674@item 16675The `Invoking' node is a GNU standard to help users find the basic 16676information about command-line usage of a given program. @xref{Manual 16677Structure Details,,,standards, GNU Coding Standards}. 16678 16679@item 16680It is best to include the entire GNU Free Documentation License in a GNU 16681manual, unless the manual is only a few pages long. Of course this 16682sample is even shorter than that, but it includes the FDL anyway in 16683order to show one conventional way of doing so. The @file{fdl.texi} 16684file is available on the GNU machines (and in the Texinfo and other GNU 16685distributions). 16686 16687The FDL provides for omitting itself under certain conditions, but in 16688that case the sample texts given here have to be modified. @xref{GNU 16689Free Documentation License}. 16690 16691@item 16692If your manual has invariant sections (again, see the license itself for 16693details), then don't forget to include them. 16694@end itemize 16695 16696Here is the sample document: 16697 16698@c We do the first part of this with @example instead of @verbatim 16699@c because the literal @setfilename and @include confuse Automake. Argh. 16700@example 16701\input texinfo @@c -*-texinfo-*- 16702@@comment $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $ 16703@@comment %**start of header 16704@@setfilename sample.info 16705@@include version.texi 16706@@settitle GNU Sample @@value@{VERSION@} 16707@@syncodeindex pg cp 16708@@comment %**end of header 16709@@copying 16710This manual is for GNU Sample 16711(version @@value@{VERSION@}, @@value@{UPDATED@}), 16712which is an example in the Texinfo documentation. 16713 16714Copyright @@copyright@{@} 2002 Free Software Foundation, Inc. 16715 16716@@quotation 16717Permission is granted to copy, distribute and/or modify this document 16718under the terms of the GNU Free Documentation License, Version 1.1 or 16719any later version published by the Free Software Foundation; with no 16720Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' 16721and with the Back-Cover Texts as in (a) below. A copy of the 16722license is included in the section entitled ``GNU Free Documentation 16723License.'' 16724 16725(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify 16726this GNU Manual, like GNU software. Copies published by the Free 16727Software Foundation raise funds for GNU development.'' 16728@@end quotation 16729@@end copying 16730 16731@@dircategory Texinfo documentation system 16732@@direntry 16733* sample: (sample)Invoking sample. 16734@@end direntry 16735 16736@@titlepage 16737@@title GNU Sample 16738@@subtitle for version @@value@{VERSION@}, @@value@{UPDATED@} 16739@@author A.U. Thor (@@email@{bug-texinfo@@@@gnu.org@}) 16740@@page 16741@@vskip 0pt plus 1filll 16742@@insertcopying 16743@@end titlepage 16744 16745@@contents 16746 16747@@ifnottex 16748@@node Top 16749@@top GNU Sample 16750 16751@@insertcopying 16752@@end ifnottex 16753 16754@@menu 16755* Invoking sample:: 16756* Copying This Manual:: 16757* Index:: 16758@@end menu 16759 16760 16761@@node Invoking sample 16762@@chapter Invoking sample 16763 16764@@pindex sample 16765@@cindex invoking @@command@{sample@} 16766 16767This is a sample manual. There is no sample program to 16768invoke, but if there was, you could see its basic usage 16769and command line options here. 16770 16771 16772@@node Copying This Manual 16773@@appendix Copying This Manual 16774 16775@@menu 16776* GNU Free Documentation License:: License for copying this manual. 16777@@end menu 16778 16779@@include fdl.texi 16780 16781 16782@@node Index 16783@@unnumbered Index 16784 |
|
| 16505@@printindex cp 16506 16507@@bye 16508@end example 16509 16510 16511@node Include Files 16512@appendix Include Files 16513@cindex Include files 16514 16515When @TeX{} or an Info formatting command sees an @code{@@include} 16516command in a Texinfo file, it processes the contents of the file named 16517by the command and incorporates them into the DVI or Info file being 16518created. Index entries from the included file are incorporated into | 16785@@printindex cp 16786 16787@@bye 16788@end example 16789 16790 16791@node Include Files 16792@appendix Include Files 16793@cindex Include files 16794 16795When @TeX{} or an Info formatting command sees an @code{@@include} 16796command in a Texinfo file, it processes the contents of the file named 16797by the command and incorporates them into the DVI or Info file being 16798created. Index entries from the included file are incorporated into |
| 16519the indices of the output file.@refill | 16799the indices of the output file. |
| 16520 16521Include files let you keep a single large document as a collection of 16522conveniently small parts. 16523 16524@menu 16525* Using Include Files:: How to use the @code{@@include} command. 16526* texinfo-multiple-files-update:: How to create and update nodes and 16527 menus when using included files. --- 199 unchanged lines hidden (view full) --- 16727@group 16728@@summarycontents 16729@@contents 16730 16731@@bye 16732@end group 16733@end example 16734 | 16800 16801Include files let you keep a single large document as a collection of 16802conveniently small parts. 16803 16804@menu 16805* Using Include Files:: How to use the @code{@@include} command. 16806* texinfo-multiple-files-update:: How to create and update nodes and 16807 menus when using included files. --- 199 unchanged lines hidden (view full) --- 17007@group 17008@@summarycontents 17009@@contents 17010 17011@@bye 17012@end group 17013@end example 17014 |
| 16735An included file, such as @file{foo.texinfo}, might look like 16736this:@refill | 17015An included file, such as @file{foo.texinfo}, might look like this: |
| 16737 16738@example 16739@group 16740@@node First, Second, , Top 16741@@chapter First Chapter 16742 16743Contents of first chapter @dots{} 16744@end group --- 237 unchanged lines hidden (view full) --- 16982@code{@@evenheading} and @code{@@evenfooting} command generate headers 16983and footers for even-numbered (left-hand) pages. 16984@item 16985@code{@@oddheading} and @code{@@oddfooting} generate headers and footers 16986for odd-numbered (right-hand) pages. 16987@end itemize 16988 16989Write custom heading specifications in the Texinfo file immediately | 17016 17017@example 17018@group 17019@@node First, Second, , Top 17020@@chapter First Chapter 17021 17022Contents of first chapter @dots{} 17023@end group --- 237 unchanged lines hidden (view full) --- 17261@code{@@evenheading} and @code{@@evenfooting} command generate headers 17262and footers for even-numbered (left-hand) pages. 17263@item 17264@code{@@oddheading} and @code{@@oddfooting} generate headers and footers 17265for odd-numbered (right-hand) pages. 17266@end itemize 17267 17268Write custom heading specifications in the Texinfo file immediately |
| 16990after the @code{@@end titlepage} command. Enclose your specifications 16991between @code{@@iftex} and @code{@@end iftex} commands since the 16992@code{texinfo-format-buffer} command may not recognize them. Also, 16993you must cancel the predefined heading commands with the | 17269after the @code{@@end titlepage} command. 17270You must cancel the predefined heading commands with the |
| 16994@code{@@headings off} command before defining your own 16995specifications.@refill 16996 16997@need 1000 16998Here is how to tell @TeX{} to place the chapter name at the left, the 16999page number in the center, and the date at the right of every header 17000for both even- and odd-numbered pages:@refill 17001 17002@example 17003@group | 17271@code{@@headings off} command before defining your own 17272specifications.@refill 17273 17274@need 1000 17275Here is how to tell @TeX{} to place the chapter name at the left, the 17276page number in the center, and the date at the right of every header 17277for both even- and odd-numbered pages:@refill 17278 17279@example 17280@group |
| 17004@@iftex | |
| 17005@@headings off 17006@@everyheading @@thischapter @@| @@thispage @@| @@today@{@} | 17281@@headings off 17282@@everyheading @@thischapter @@| @@thispage @@| @@today@{@} |
| 17007@@end iftex | |
| 17008@end group 17009@end example 17010 17011@noindent 17012You need to divide the left part from the central part and the central 17013part from the right part by inserting @samp{@@|} between parts. 17014Otherwise, the specification command will not be able to tell where 17015the text for one part ends and the next part begins.@refill --- 83 unchanged lines hidden (view full) --- 17099@findex today 17100 17101Other @@-commands and text are printed in a header or footer just as 17102if they were in the body of a page. It is useful to incorporate text, 17103particularly when you are writing drafts:@refill 17104 17105@example 17106@group | 17283@end group 17284@end example 17285 17286@noindent 17287You need to divide the left part from the central part and the central 17288part from the right part by inserting @samp{@@|} between parts. 17289Otherwise, the specification command will not be able to tell where 17290the text for one part ends and the next part begins.@refill --- 83 unchanged lines hidden (view full) --- 17374@findex today 17375 17376Other @@-commands and text are printed in a header or footer just as 17377if they were in the body of a page. It is useful to incorporate text, 17378particularly when you are writing drafts:@refill 17379 17380@example 17381@group |
| 17107@@iftex | |
| 17108@@headings off 17109@@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter 17110@@everyfooting @@| @@| Version: 0.27: @@today@{@} | 17382@@headings off 17383@@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter 17384@@everyfooting @@| @@| Version: 0.27: @@today@{@} |
| 17111@@end iftex | |
| 17112@end group 17113@end example 17114 17115Beware of overlong titles: they may overlap another part of the 17116header or footer and blot it out.@refill 17117 17118 17119@node Catching Mistakes 17120@appendix Formatting Mistakes 17121@cindex Structure, catching mistakes in 17122@cindex Nodes, catching mistakes 17123@cindex Catching mistakes 17124@cindex Correcting mistakes 17125@cindex Mistakes, catching 17126@cindex Problems, catching 17127@cindex Debugging the Texinfo structure 17128 | 17385@end group 17386@end example 17387 17388Beware of overlong titles: they may overlap another part of the 17389header or footer and blot it out.@refill 17390 17391 17392@node Catching Mistakes 17393@appendix Formatting Mistakes 17394@cindex Structure, catching mistakes in 17395@cindex Nodes, catching mistakes 17396@cindex Catching mistakes 17397@cindex Correcting mistakes 17398@cindex Mistakes, catching 17399@cindex Problems, catching 17400@cindex Debugging the Texinfo structure 17401 |
| 17129Besides mistakes in the content of your documentation, there 17130are two kinds of mistake you can make with Texinfo: you can make mistakes 17131with @@-commands, and you can make mistakes with the structure of the 17132nodes and chapters.@refill | 17402Besides mistakes in the content of your documentation, there are two 17403kinds of mistake you can make with Texinfo: you can make mistakes with 17404@@-commands, and you can make mistakes with the structure of the nodes 17405and chapters. |
| 17133 17134Emacs has two tools for catching the @@-command mistakes and two for 17135catching structuring mistakes.@refill 17136 17137For finding problems with @@-commands, you can run @TeX{} or a region 17138formatting command on the region that has a problem; indeed, you can 17139run these commands on each region as you write it.@refill 17140 --- 1306 unchanged lines hidden (view full) --- 18447@end table 18448@tex 18449% Switch width of first column of tables back to default value 18450\global\tableindent=.8in 18451@end tex 18452@end ignore 18453 18454 | 17406 17407Emacs has two tools for catching the @@-command mistakes and two for 17408catching structuring mistakes.@refill 17409 17410For finding problems with @@-commands, you can run @TeX{} or a region 17411formatting command on the region that has a problem; indeed, you can 17412run these commands on each region as you write it.@refill 17413 --- 1306 unchanged lines hidden (view full) --- 18720@end table 18721@tex 18722% Switch width of first column of tables back to default value 18723\global\tableindent=.8in 18724@end tex 18725@end ignore 18726 18727 |
| 18455@node Documentation Copying 18456@appendix GNU Free Documentation License | 18728@node Copying This Manual 18729@appendix Copying This Manual |
| 18457 | 18730 |
| 18458@cindex FDL, GNU Free Documentation License 18459@center Version 1.1, March 2000 | 18731@menu 18732* GNU Free Documentation License:: License for copying this manual. 18733@end menu |
| 18460 | 18734 |
| 18461@display 18462Copyright @copyright{} 2000 Free Software Foundation, Inc. 1846359 Temple Place, Suite 330, Boston, MA 02111-1307, USA | 18735@include fdl.texi |
| 18464 | 18736 |
| 18465Everyone is permitted to copy and distribute verbatim copies 18466of this license document, but changing it is not allowed. 18467@end display | |
| 18468 | 18737 |
| 18469@enumerate 0 18470@item 18471PREAMBLE 18472 18473The purpose of this License is to make a manual, textbook, or other 18474written document @dfn{free} in the sense of freedom: to assure everyone 18475the effective freedom to copy and redistribute it, with or without 18476modifying it, either commercially or noncommercially. Secondarily, 18477this License preserves for the author and publisher a way to get 18478credit for their work, while not being considered responsible for 18479modifications made by others. 18480 18481This License is a kind of ``copyleft'', which means that derivative 18482works of the document must themselves be free in the same sense. It 18483complements the GNU General Public License, which is a copyleft 18484license designed for free software. 18485 18486We have designed this License in order to use it for manuals for free 18487software, because free software needs free documentation: a free 18488program should come with manuals providing the same freedoms that the 18489software does. But this License is not limited to software manuals; 18490it can be used for any textual work, regardless of subject matter or 18491whether it is published as a printed book. We recommend this License 18492principally for works whose purpose is instruction or reference. 18493 18494@item 18495APPLICABILITY AND DEFINITIONS 18496 18497This License applies to any manual or other work that contains a 18498notice placed by the copyright holder saying it can be distributed 18499under the terms of this License. The ``Document'', below, refers to any 18500such manual or work. Any member of the public is a licensee, and is 18501addressed as ``you''. 18502 18503A ``Modified Version'' of the Document means any work containing the 18504Document or a portion of it, either copied verbatim, or with 18505modifications and/or translated into another language. 18506 18507A ``Secondary Section'' is a named appendix or a front-matter section of 18508the Document that deals exclusively with the relationship of the 18509publishers or authors of the Document to the Document's overall subject 18510(or to related matters) and contains nothing that could fall directly 18511within that overall subject. (For example, if the Document is in part a 18512textbook of mathematics, a Secondary Section may not explain any 18513mathematics.) The relationship could be a matter of historical 18514connection with the subject or with related matters, or of legal, 18515commercial, philosophical, ethical or political position regarding 18516them. 18517 18518The ``Invariant Sections'' are certain Secondary Sections whose titles 18519are designated, as being those of Invariant Sections, in the notice 18520that says that the Document is released under this License. 18521 18522The ``Cover Texts'' are certain short passages of text that are listed, 18523as Front-Cover Texts or Back-Cover Texts, in the notice that says that 18524the Document is released under this License. 18525 18526A ``Transparent'' copy of the Document means a machine-readable copy, 18527represented in a format whose specification is available to the 18528general public, whose contents can be viewed and edited directly and 18529straightforwardly with generic text editors or (for images composed of 18530pixels) generic paint programs or (for drawings) some widely available 18531drawing editor, and that is suitable for input to text formatters or 18532for automatic translation to a variety of formats suitable for input 18533to text formatters. A copy made in an otherwise Transparent file 18534format whose markup has been designed to thwart or discourage 18535subsequent modification by readers is not Transparent. A copy that is 18536not ``Transparent'' is called ``Opaque''. 18537 18538Examples of suitable formats for Transparent copies include plain 18539@sc{ascii} without markup, Texinfo input format, La@TeX{} input format, 18540@acronym{SGML} or @acronym{XML} using a publicly available 18541@acronym{DTD}, and standard-conforming simple @acronym{HTML} designed 18542for human modification. Opaque formats include PostScript, 18543@acronym{PDF}, proprietary formats that can be read and edited only by 18544proprietary word processors, @acronym{SGML} or @acronym{XML} for which 18545the @acronym{DTD} and/or processing tools are not generally available, 18546and the machine-generated @acronym{HTML} produced by some word 18547processors for output purposes only. 18548 18549The ``Title Page'' means, for a printed book, the title page itself, 18550plus such following pages as are needed to hold, legibly, the material 18551this License requires to appear in the title page. For works in 18552formats which do not have any title page as such, ``Title Page'' means 18553the text near the most prominent appearance of the work's title, 18554preceding the beginning of the body of the text. 18555 18556@item 18557VERBATIM COPYING 18558 18559You may copy and distribute the Document in any medium, either 18560commercially or noncommercially, provided that this License, the 18561copyright notices, and the license notice saying this License applies 18562to the Document are reproduced in all copies, and that you add no other 18563conditions whatsoever to those of this License. You may not use 18564technical measures to obstruct or control the reading or further 18565copying of the copies you make or distribute. However, you may accept 18566compensation in exchange for copies. If you distribute a large enough 18567number of copies you must also follow the conditions in section 3. 18568 18569You may also lend copies, under the same conditions stated above, and 18570you may publicly display copies. 18571 18572@item 18573COPYING IN QUANTITY 18574 18575If you publish printed copies of the Document numbering more than 100, 18576and the Document's license notice requires Cover Texts, you must enclose 18577the copies in covers that carry, clearly and legibly, all these Cover 18578Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on 18579the back cover. Both covers must also clearly and legibly identify 18580you as the publisher of these copies. The front cover must present 18581the full title with all words of the title equally prominent and 18582visible. You may add other material on the covers in addition. 18583Copying with changes limited to the covers, as long as they preserve 18584the title of the Document and satisfy these conditions, can be treated 18585as verbatim copying in other respects. 18586 18587If the required texts for either cover are too voluminous to fit 18588legibly, you should put the first ones listed (as many as fit 18589reasonably) on the actual cover, and continue the rest onto adjacent 18590pages. 18591 18592If you publish or distribute Opaque copies of the Document numbering 18593more than 100, you must either include a machine-readable Transparent 18594copy along with each Opaque copy, or state in or with each Opaque copy 18595a publicly-accessible computer-network location containing a complete 18596Transparent copy of the Document, free of added material, which the 18597general network-using public has access to download anonymously at no 18598charge using public-standard network protocols. If you use the latter 18599option, you must take reasonably prudent steps, when you begin 18600distribution of Opaque copies in quantity, to ensure that this 18601Transparent copy will remain thus accessible at the stated location 18602until at least one year after the last time you distribute an Opaque 18603copy (directly or through your agents or retailers) of that edition to 18604the public. 18605 18606It is requested, but not required, that you contact the authors of the 18607Document well before redistributing any large number of copies, to give 18608them a chance to provide you with an updated version of the Document. 18609 18610@item 18611MODIFICATIONS 18612 18613You may copy and distribute a Modified Version of the Document under 18614the conditions of sections 2 and 3 above, provided that you release 18615the Modified Version under precisely this License, with the Modified 18616Version filling the role of the Document, thus licensing distribution 18617and modification of the Modified Version to whoever possesses a copy 18618of it. In addition, you must do these things in the Modified Version: 18619 18620@enumerate A 18621@item 18622Use in the Title Page (and on the covers, if any) a title distinct 18623from that of the Document, and from those of previous versions 18624(which should, if there were any, be listed in the History section 18625of the Document). You may use the same title as a previous version 18626if the original publisher of that version gives permission. 18627 18628@item 18629List on the Title Page, as authors, one or more persons or entities 18630responsible for authorship of the modifications in the Modified 18631Version, together with at least five of the principal authors of the 18632Document (all of its principal authors, if it has less than five). 18633 18634@item 18635State on the Title page the name of the publisher of the 18636Modified Version, as the publisher. 18637 18638@item 18639Preserve all the copyright notices of the Document. 18640 18641@item 18642Add an appropriate copyright notice for your modifications 18643adjacent to the other copyright notices. 18644 18645@item 18646Include, immediately after the copyright notices, a license notice 18647giving the public permission to use the Modified Version under the 18648terms of this License, in the form shown in the Addendum below. 18649 18650@item 18651Preserve in that license notice the full lists of Invariant Sections 18652and required Cover Texts given in the Document's license notice. 18653 18654@item 18655Include an unaltered copy of this License. 18656 18657@item 18658Preserve the section entitled ``History'', and its title, and add to 18659it an item stating at least the title, year, new authors, and 18660publisher of the Modified Version as given on the Title Page. If 18661there is no section entitled ``History'' in the Document, create one 18662stating the title, year, authors, and publisher of the Document as 18663given on its Title Page, then add an item describing the Modified 18664Version as stated in the previous sentence. 18665 18666@item 18667Preserve the network location, if any, given in the Document for 18668public access to a Transparent copy of the Document, and likewise 18669the network locations given in the Document for previous versions 18670it was based on. These may be placed in the ``History'' section. 18671You may omit a network location for a work that was published at 18672least four years before the Document itself, or if the original 18673publisher of the version it refers to gives permission. 18674 18675@item 18676In any section entitled ``Acknowledgments'' or ``Dedications'', 18677preserve the section's title, and preserve in the section all the 18678substance and tone of each of the contributor acknowledgments 18679and/or dedications given therein. 18680 18681@item 18682Preserve all the Invariant Sections of the Document, 18683unaltered in their text and in their titles. Section numbers 18684or the equivalent are not considered part of the section titles. 18685 18686@item 18687Delete any section entitled ``Endorsements''. Such a section 18688may not be included in the Modified Version. 18689 18690@item 18691Do not retitle any existing section as ``Endorsements'' 18692or to conflict in title with any Invariant Section. 18693@end enumerate 18694 18695If the Modified Version includes new front-matter sections or 18696appendices that qualify as Secondary Sections and contain no material 18697copied from the Document, you may at your option designate some or all 18698of these sections as invariant. To do this, add their titles to the 18699list of Invariant Sections in the Modified Version's license notice. 18700These titles must be distinct from any other section titles. 18701 18702You may add a section entitled ``Endorsements'', provided it contains 18703nothing but endorsements of your Modified Version by various 18704parties---for example, statements of peer review or that the text has 18705been approved by an organization as the authoritative definition of a 18706standard. 18707 18708You may add a passage of up to five words as a Front-Cover Text, and a 18709passage of up to 25 words as a Back-Cover Text, to the end of the list 18710of Cover Texts in the Modified Version. Only one passage of 18711Front-Cover Text and one of Back-Cover Text may be added by (or 18712through arrangements made by) any one entity. If the Document already 18713includes a cover text for the same cover, previously added by you or 18714by arrangement made by the same entity you are acting on behalf of, 18715you may not add another; but you may replace the old one, on explicit 18716permission from the previous publisher that added the old one. 18717 18718The author(s) and publisher(s) of the Document do not by this License 18719give permission to use their names for publicity for or to assert or 18720imply endorsement of any Modified Version. 18721 18722@item 18723COMBINING DOCUMENTS 18724 18725You may combine the Document with other documents released under this 18726License, under the terms defined in section 4 above for modified 18727versions, provided that you include in the combination all of the 18728Invariant Sections of all of the original documents, unmodified, and 18729list them all as Invariant Sections of your combined work in its 18730license notice. 18731 18732The combined work need only contain one copy of this License, and 18733multiple identical Invariant Sections may be replaced with a single 18734copy. If there are multiple Invariant Sections with the same name but 18735different contents, make the title of each such section unique by 18736adding at the end of it, in parentheses, the name of the original 18737author or publisher of that section if known, or else a unique number. 18738Make the same adjustment to the section titles in the list of 18739Invariant Sections in the license notice of the combined work. 18740 18741In the combination, you must combine any sections entitled ``History'' 18742in the various original documents, forming one section entitled 18743``History''; likewise combine any sections entitled ``Acknowledgments'', 18744and any sections entitled ``Dedications''. You must delete all sections 18745entitled ``Endorsements.'' 18746 18747@item 18748COLLECTIONS OF DOCUMENTS 18749 18750You may make a collection consisting of the Document and other documents 18751released under this License, and replace the individual copies of this 18752License in the various documents with a single copy that is included in 18753the collection, provided that you follow the rules of this License for 18754verbatim copying of each of the documents in all other respects. 18755 18756You may extract a single document from such a collection, and distribute 18757it individually under this License, provided you insert a copy of this 18758License into the extracted document, and follow this License in all 18759other respects regarding verbatim copying of that document. 18760 18761@item 18762AGGREGATION WITH INDEPENDENT WORKS 18763 18764A compilation of the Document or its derivatives with other separate 18765and independent documents or works, in or on a volume of a storage or 18766distribution medium, does not as a whole count as a Modified Version 18767of the Document, provided no compilation copyright is claimed for the 18768compilation. Such a compilation is called an ``aggregate'', and this 18769License does not apply to the other self-contained works thus compiled 18770with the Document, on account of their being thus compiled, if they 18771are not themselves derivative works of the Document. 18772 18773If the Cover Text requirement of section 3 is applicable to these 18774copies of the Document, then if the Document is less than one quarter 18775of the entire aggregate, the Document's Cover Texts may be placed on 18776covers that surround only the Document within the aggregate. 18777Otherwise they must appear on covers around the whole aggregate. 18778 18779@item 18780TRANSLATION 18781 18782Translation is considered a kind of modification, so you may 18783distribute translations of the Document under the terms of section 4. 18784Replacing Invariant Sections with translations requires special 18785permission from their copyright holders, but you may include 18786translations of some or all Invariant Sections in addition to the 18787original versions of these Invariant Sections. You may include a 18788translation of this License provided that you also include the 18789original English version of this License. In case of a disagreement 18790between the translation and the original English version of this 18791License, the original English version will prevail. 18792 18793@item 18794TERMINATION 18795 18796You may not copy, modify, sublicense, or distribute the Document except 18797as expressly provided for under this License. Any other attempt to 18798copy, modify, sublicense or distribute the Document is void, and will 18799automatically terminate your rights under this License. However, 18800parties who have received copies, or rights, from you under this 18801License will not have their licenses terminated so long as such 18802parties remain in full compliance. 18803 18804@item 18805FUTURE REVISIONS OF THIS LICENSE 18806 18807The Free Software Foundation may publish new, revised versions 18808of the GNU Free Documentation License from time to time. Such new 18809versions will be similar in spirit to the present version, but may 18810differ in detail to address new problems or concerns. See 18811@uref{http://www.gnu.org/copyleft/}. 18812 18813Each version of the License is given a distinguishing version number. 18814If the Document specifies that a particular numbered version of this 18815License ``or any later version'' applies to it, you have the option of 18816following the terms and conditions either of that specified version or 18817of any later version that has been published (not as a draft) by the 18818Free Software Foundation. If the Document does not specify a version 18819number of this License, you may choose any version ever published (not 18820as a draft) by the Free Software Foundation. 18821@end enumerate 18822 18823@page 18824@appendixsubsec ADDENDUM: How to use this License for your documents 18825 18826To use this License in a document you have written, include a copy of 18827the License in the document and put the following copyright and 18828license notices just after the title page: 18829 18830@smallexample 18831@group 18832 Copyright (C) @var{year} @var{your name}. 18833 Permission is granted to copy, distribute and/or modify this document 18834 under the terms of the GNU Free Documentation License, Version 1.1 18835 or any later version published by the Free Software Foundation; 18836 with the Invariant Sections being @var{list their titles}, with the 18837 Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}. 18838 A copy of the license is included in the section entitled ``GNU 18839 Free Documentation License''. 18840@end group 18841@end smallexample 18842 18843If you have no Invariant Sections, write ``with no Invariant Sections'' 18844instead of saying which ones are invariant. If you have no 18845Front-Cover Texts, write ``no Front-Cover Texts'' instead of 18846``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts. 18847 18848If your document contains nontrivial examples of program code, we 18849recommend releasing these examples in parallel under your choice of 18850free software license, such as the GNU General Public License, 18851to permit their use in free software. 18852 18853 | |
| 18854@node Command and Variable Index 18855@unnumbered Command and Variable Index 18856 18857This is an alphabetical list of all the @@-commands, assorted Emacs Lisp 18858functions, and several variables. To make the list easier to use, the 18859commands are listed without their preceding @samp{@@}.@refill 18860 18861@printindex fn 18862 18863 18864@node Concept Index 18865@unnumbered Concept Index 18866 18867@printindex cp 18868 18869 18870@bye | 18738@node Command and Variable Index 18739@unnumbered Command and Variable Index 18740 18741This is an alphabetical list of all the @@-commands, assorted Emacs Lisp 18742functions, and several variables. To make the list easier to use, the 18743commands are listed without their preceding @samp{@@}.@refill 18744 18745@printindex fn 18746 18747 18748@node Concept Index 18749@unnumbered Concept Index 18750 18751@printindex cp 18752 18753 18754@bye |