1\input texinfo.tex @c -*-texinfo-*- |
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. |
9@c %**start of header 10 |
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. |
15@setfilename texinfo 16 |
17@c Automake automatically updates version.texi to @set VERSION and 18@c @set UPDATED to appropriate values. |
19@include version.texi |
20@settitle GNU Texinfo @value{VERSION} |
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 |
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 |
78@c If you like blank pages, add through texi2dvi -t. |
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 |
84 |
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 |
100@insertcopying |
101 |
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. |
107@c ISBN 1-882114-65-5 is for version 3.12, March 1998. |
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 |
110 111Cover art by Etienne Suvasa. |
112@end titlepage 113 |
114 |
115@summarycontents 116@contents 117 |
118 |
119@ifnottex 120@node Top 121@top Texinfo 122 |
123@insertcopying |
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 |
129@end ifnottex 130 131@menu |
132* Copying Conditions:: Your rights. |
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. |
160* Sample Texinfo Files:: Complete examples, including full texts. |
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{}. |
167* Copying This Manual:: The GNU Free Documentation License. |
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 |
211* Sample Beginning:: A sample beginning for a Texinfo file. 212* Texinfo File Header:: 213* Document Permissions:: |
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:: |
217* Software Copying Permissions:: Ensure that you and others continue to |
218 have the right to use and share software. |
219 |
220Texinfo File Header |
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. |
226* End of Header:: Formatting a region requires this. 227 |
228Document Permissions |
229 |
230* copying:: Declare the document's copying permissions. 231* insertcopying:: Where to insert the permissions. 232 233Title and Copyright Pages 234 |
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. |
240* Copyright:: How to write the copyright notice and |
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 |
249* Top Node Example:: 250* Master Menu Parts:: |
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 |
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. |
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. |
340* verb:: A verbatim sequence of characters. |
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. |
364* verbatiminclude:: Including a file verbatim. |
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:: |
552* Installing an Info File:: |
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 |
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 |
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 |
634@node Copying Conditions |
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 |
670Licenses that accompany them. This manual specifically is covered by 671the GNU Free Documentation License (@pxref{GNU Free Documentation 672License}). |
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. |
726@item hardware and operating system names and versions. |
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}. |
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 |
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 |
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}). |
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. |
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/}. |
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 |
795Info, plain text, HTML, XML, and DocBook. |
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 |
826writing a good user tutorial or a good reference manual. This makes |
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 |
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/}. |
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 |
848into an Info file.) |
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 |
855related nodes. |
856 857@ifinfo |
858@inforef{Top, info, info}, for more information about using Info. |
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 |
868of subsections. |
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 |
881following higher level node as its `Next' pointer.} |
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 |
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}.) |
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 |
994light-hearted, young and cheery. |
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 |
1005formatting commands that Texinfo supports are necessarily limited. |
1006 1007To get a copy of @TeX{}, see 1008@ref{Obtaining TeX, , How to Obtain @TeX{}}. 1009 1010 |
1011@node Formatting Commands |
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 |
1025@code{@@TeX@{@}} command, must be written entirely in lower case. |
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 |
1095@node Conventions |
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. |
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{@@@}}. |
1112 1113@item |
1114It is customary in @TeX{} to use doubled single-quote characters to |
1115begin and end quotations: @w{@t{`@w{}`@dots{}'@w{}'}}. This |
1116convention should be followed in Texinfo files. @TeX{} converts |
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'', |
1122@end iftex |
1123and Info converts doubled single-quote characters to @sc{ascii} 1124double-quotes: @w{@t{`@w{}`@dots{}'@w{}'}} becomes @w{@t{"@dots{}"}}. |
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 |
1135paragraph. |
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 |
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}. |
1147@end itemize 1148 1149@cindex Tabs; don't use! 1150@quotation |
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. |
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 |
1157differently in the output, for example, in indented text. |
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 |
1169@node Comments |
1170@section Comments 1171 |
1172@cindex Comments 1173@findex comment 1174@findex c @r{(comment)} 1175 |
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 |
1182or the printed manual. |
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 |
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 |
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 |
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. |
1208 1209 |
1210@node Minimum |
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 |
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. |
1223 1224In order to be made into a printed manual and an Info file, a Texinfo |
1225file @strong{must} begin with lines like this: |
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 |
1236The contents of the file follow this beginning, and then you 1237@strong{must} end a Texinfo file with a line like this: |
1238 1239@example 1240@@bye 1241@end example 1242 |
1243@findex \input @r{(raw @TeX{} startup)} |
1244@noindent |
1245Here's an explanation: 1246 1247@itemize @bullet 1248@item |
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 |
1252backslash, @samp{\}; this is correct for @TeX{}.) |
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 |
1266The @code{@@bye} line at the end of the file on a line of its own tells |
1267the formatters that the file is ended and to stop formatting. |
1268 |
1269@end itemize 1270 1271Typically, you will not use quite such a spare format, but will include |
1272mode setting and start-of-header and end-of-header lines at the |
1273beginning of a Texinfo file, like this: |
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 |
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}.) |
1292 |
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. |
1297 |
1298 1299@node Six Parts |
1300@section Six Parts of a Texinfo File 1301 |
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. |
1305 1306@table @r 1307@item 1. Header |
1308The @dfn{Header} names the file, tells @TeX{} which definitions file to 1309use, and other such housekeeping tasks. |
1310 |
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. |
1315 1316@item 3. Title and Copyright |
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. |
1321 1322@item 4. `Top' Node and Master Menu |
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. |
1328 1329@item 5. Body |
1330The @dfn{Body} of the document is typically structured like a 1331traditional book or encyclopedia, but it may be free form. |
1332 1333@item 6. End |
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. |
1337@end table 1338 |
1339 |
1340@node Short Sample 1341@section A Short Sample Texinfo File |
1342@cindex Sample Texinfo file, with comments |
1343 |
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. |
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 |
1355In the following, the sample text is @emph{indented}; comments on it are |
1356not. The complete file, without interspersed comments, is shown in 1357@ref{Short Sample Texinfo File}. |
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 |
1371@@settitle Sample Manual 1.0 |
1372@@c %**end of header 1373@end group 1374@end example 1375 1376@subheading Part 2: Summary Description and Copyright 1377 1378@noindent |
1379A real manual includes more text here, according to the license under 1380which it is distributed. @xref{GNU Sample Texts}. |
1381 1382@example 1383@group |
1384@@copying 1385This is a short example of a complete Texinfo file, version 1.0. |
1386 1387Copyright @@copyright@{@} 2002 Free Software Foundation, Inc. |
1388@@end copying |
1389@end group 1390@end example 1391 |
1392@subheading Part 3: Titlepage, Contents, Copyright |
1393 1394@noindent |
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. |
1400 1401@example 1402@group |
1403@@titlepage |
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 |
1411@@insertcopying |
1412@@end titlepage 1413@end group |
1414 1415@@c Output the table of contents at the beginning. 1416@@contents |
1417@end example 1418 1419@subheading Part 4: `Top' Node and Master Menu 1420 1421@noindent |
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. |
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 |
1440@@menu 1441* First Chapter:: The first chapter is the |
1442 only chapter in this sample. 1443* Index:: Complete index. |
1444@@end menu 1445@end group 1446@end example 1447 |
1448 |
1449@subheading Part 5: The Body of the Document 1450 |
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 |
1454chapter containing an enumerated list. |
1455 1456@example 1457@group 1458@@node First Chapter 1459@@chapter First Chapter |
1460 1461@@cindex chapter, first |
1462@end group 1463 1464@group |
1465This is the first chapter. 1466@@cindex index entry, another |
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 |
1480@end example 1481 |
1482 |
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 |
1487unnumbered chapter of its own, and the @code{@@bye} command that marks 1488the end of the document. |
1489 1490@example 1491@group |
1492@@node Index 1493@@unnumbered Index |
1494@end group 1495 1496@group 1497@@printindex cp 1498 1499@@bye 1500@end group 1501@end example 1502 |
1503 |
1504@subheading Some Results 1505 |
1506Here is what the contents of the first chapter of the sample look like: 1507 1508@sp 1 1509@need 700 1510@quotation |
1511This is the first chapter. |
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 |
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 |
1531@cindex Berry, Karl 1532Richard M.@: Stallman invented the Texinfo format, wrote the initial |
1533processors, and created Edition 1.0 of this manual. @w{Robert J.@:} 1534Chassell greatly revised and extended the manual, starting with Edition |
15351.1. Brian Fox was responsible for the standalone Texinfo distribution 1536until version 3.8, and wrote the standalone @command{makeinfo} and |
1537@command{info} programs. Karl Berry has continued maintenance since 1538Texinfo 3.8 (manual edition 2.22). |
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 |
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. |
1555 1556@cindex Scribe 1557@cindex Reid, Brian 1558@cindex History of Texinfo |
1559@cindex Texinfo history |
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 |
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. |
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 |
1570language: Bo@TeX{}. The earliest Bo@TeX{} version seems to have been 15710.02 on October 31, 1984. |
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 |
1577mark up language for text that is intended to be read both online and |
1578as printed hard copy. 1579 1580 |
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 |
1590comes with a special mode, called Texinfo mode, that provides Emacs 1591commands and tools to help ease your work. |
1592 1593This chapter describes features of GNU Emacs' Texinfo mode but not any |
1594features of the Texinfo formatting language. So if you are reading this |
1595manual straight through from the beginning, you may want to skim through 1596this chapter briefly and come back to it after reading succeeding |
1597chapters which describe the Texinfo formatting language in detail. |
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 |
2091@node Updating Requirements |
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 |
2111must look either like this: |
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 |
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 |
2144@code{@@comment} line, you may also write an @code{@@ifinfo} line.) |
2145 2146If a file has a `Top' node, it must be called @samp{top} or @samp{Top} |
2147and be the first node in the file. |
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 |
2162 2163@node Other Updating Commands |
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} |
2293include a line that has @code{@@setfilename} in its header. |
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 |
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 |
2550Texinfo file, such as the name for the output file(s), the title of the 2551document, and the Top node. |
2552 |
2553This chapter expands on the minimal complete Texinfo source file 2554previously given (@pxref{Six Parts}). 2555 |
2556@menu |
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. |
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. |
2563* Software Copying Permissions:: Ensure that you and others continue to |
2564 have the right to use and share software. |
2565@end menu 2566 |
2567 |
2568@node Sample Beginning 2569@section Sample Texinfo File Beginning 2570 |
2571@cindex Example beginning of Texinfo file |
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 |
2580@example 2581\input texinfo @@c -*-texinfo-*- 2582@@c %**start of header |
2583@@setfilename @var{infoname}.info 2584@@settitle @var{name-of-manual} @var{version} |
2585@@c %**end of header 2586 |
2587@@copying 2588This manual is for @var{program}, version @var{version}. |
2589 |
2590Copyright @@copyright@{@} @var{years} @var{copyright-owner}. |
2591 2592@group |
2593@@quotation |
2594Permission is granted to @dots{} |
2595@@end quotation 2596@@end copying |
2597@end group 2598 2599@group |
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 |
2612@@insertcopying |
2613@end group 2614 2615Published by @dots{} |
2616@@end titlepage 2617 |
2618@@c So the toc is printed in the right place. 2619@@contents 2620 |
2621@@ifnottex 2622@@node Top 2623@@top @var{title} 2624 |
2625@@insertcopying |
2626@@end ifnottex 2627 2628@group 2629@@menu |
2630* First Chapter:: Getting started @dots{} |
2631* Second Chapter:: @dots{} |
2632 @dots{} |
2633* Copying:: Your rights and freedoms. |
2634@@end menu 2635@end group 2636 2637@group |
2638@@node First Chapter |
2639@@chapter First Chapter |
2640 2641@@cindex first chapter 2642@@cindex chapter, first 2643@dots{} |
2644@end group 2645@end example 2646 2647 |
2648@node Texinfo File Header 2649@section Texinfo File Header |
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} |
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 |
2658write the @code{@@settitle} and @code{@@setfilename} lines between |
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. |
2662 |
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. |
2667 |
2668Thus, the beginning of a Texinfo file generally looks like this: |
2669 |
2670@example 2671@group 2672\input texinfo @@c -*-texinfo-*- 2673@@c %**start of header 2674@@setfilename sample.info |
2675@@settitle Sample Manual 1.0 |
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. |
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 |
2696with a line that looks like this: |
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. |
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. |
2716 2717@item 2718When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode |
2719specification tells Emacs to use Texinfo mode. |
2720@end enumerate 2721 2722 2723@node Start of Header 2724@subsection Start of Header 2725@cindex Start of header line 2726 |
2727A start-of-header line is a Texinfo comment that looks like this: |
2728 |
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 |
2743The odd string of characters, @samp{%**}, is to ensure that no other |
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}. |
2747 |
2748 |
2749@node setfilename |
2750@subsection @code{@@setfilename}: Set the output file name |
2751@findex setfilename |
2752@cindex Texinfo requires @code{@@setfilename} |
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 |
2773The @code{@@setfilename} line specifies the name of the output file to |
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. |
2778 |
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. |
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 |
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. |
2796 |
2797When producing HTML output, @code{makeinfo} will replace any extension 2798with @samp{html}, or add @samp{.html} if the given name has no 2799extension. |
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 |
2820Write the @code{@@settitle} command at the beginning of a line and |
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. |
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 |
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 |
2846from each @code{@@chapter} command.) By default, no page footer is 2847printed. |
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 |
2851in the heading. |
2852 |
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 |
2857information.) |
2858 |
2859You may, if you wish, create your own, customized headings and footings. 2860@xref{Headings}, for a detailed discussion of this. |
2861 2862 |
2863@node End of Header 2864@subsection End of Header 2865@cindex End of header line |
2866 |
2867Follow the header lines with an @w{end-of-header} line, which is a 2868Texinfo comment that looks like this: |
2869 2870@example |
2871@@c %**end of header |
2872@end example 2873 |
2874@xref{Start of Header}. |
2875 |
2876 |
2877@node Document Permissions 2878@section Document Permissions 2879@cindex Document Permissions 2880@cindex Copying Permissions |
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. |
2887 |
2888@menu 2889* copying:: Declare the document's copying permissions. 2890* insertcopying:: Where to insert the permissions. 2891@end menu |
2892 |
2893 |
2894@node copying 2895@subsection @code{@@copying}: Declare copying permissions 2896@findex copying |
2897 |
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: |
2903 |
2904@example |
2905@@copying 2906This manual is for @var{program} (version @var{version}), 2907which @dots{} |
2908 |
2909Copyright @@copyright@{@} @var{years} @var{copyright-owner}. |
2910 |
2911@@quotation 2912Permission is granted to @dots{} 2913@@end quotation 2914@@end copying |
2915@end example 2916 |
2917The @code{@@quotation} has no legal significance; it's there to improve 2918readability in some contexts. |
2919 |
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. |
2923 |
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. |
2928 |
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: |
2934 |
2935@example |
2936Copyright @copyright{} @var{years} @var{copyright-owner}. |
2937@end example 2938 |
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. |
2943 |
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. |
2949 |
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.'. |
2954 |
2955@xref{Copyright Notices,,,maintain,GNU Maintenance Instructions}, for 2956additional information. |
2957 |
2958 |
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 |
2965 |
2966The @code{@@insertcopying} command is simply written on a line by 2967itself, like this: |
2968 |
2969@example |
2970@@insertcopying |
2971@end example 2972 |
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}). |
2976 |
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: |
2980 |
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. |
2988 |
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. |
2995 |
2996The permissions text defined by @code{@@copying} also appears 2997automatically at the beginning of the XML output file. |
2998 |
2999 |
3000@node Titlepage & Copyright Page |
3001@section Title and Copyright Pages |
3002 |
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. |
3006 |
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 |
3009obscure @TeX{} typesetting commands that cannot be used in an Info file. |
3010In addition, this part of the beginning of a Texinfo file contains the 3011text of the copying permissions that appears in the printed manual. |
3012 |
3013@cindex Title page, for plain text 3014@cindex Copyright page, for plain text |
3015You may wish to include titlepage-like information for plain text |
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}. |
3020 |
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. |
3027* Copyright:: How to write the copyright notice and |
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 |
3036@node titlepage |
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 |
3043@code{@@end titlepage} on a line by itself. |
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 |
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. |
3069This helps readers keep track of which manual is for which version of 3070the program. (The `Top' node should also contain this information; see |
3071@ref{The Top Node}.) |
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 |
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. |
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 |
3106first of the two methods for creating a title page in Texinfo.) |
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 |
3120the remaining text on that line. Thus, |
3121 3122@example 3123@@center @@titlefont@{Texinfo@} 3124@end example 3125 3126@noindent 3127centers the title, which in this example is ``Texinfo'' printed |
3128in the title font. |
3129 |
3130Use the @code{@@sp} command to insert vertical space. For example: |
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} |
3139command.) |
3140 |
3141A template for this method looks like this: |
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 |
3157The spacing of the example fits an 8.5 by 11 inch manual. |
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, |
3174or author. |
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 |
3185flush to the right-hand side of the page. |
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 |
3192followed by an @code{@@page} command line.) |
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 |
3196an @code{@@author} command: |
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) |
3204@code{@@author} commands: |
3205 3206@example 3207@group 3208@@author Jane Smith 3209@@author John Doe 3210@end group 3211@end example 3212 3213@noindent |
3214(Only the bottom name is underlined with a black rule.) |
3215 3216@need 950 |
3217A template for this method looks like this: |
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 |
3249(The use of @code{@@value} here is explained in @ref{value Example}. |
3250 3251 |
3252@node Copyright 3253@subsection Copyright Page |
3254@cindex Copyright page 3255@cindex Printed permissions 3256@cindex Permissions, printed 3257 |
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. |
3264 |
3265@findex vskip @r{@TeX{} vertical skip} 3266@findex filll @r{@TeX{} dimension} |
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 |
3269bottom of the page, use the following incantantion after @code{@@page}: |
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 |
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. |
3282 |
3283To insert the copyright text itself, write @code{@@insertcopying} 3284next (@pxref{Document Permissions}): |
3285 3286@example |
3287@@insertcopying |
3288@end example 3289 |
3290Follow the copying text by the publisher, ISBN numbers, cover art 3291credits, and other such information. |
3292 |
3293Here is an example putting all this together: |
3294 |
3295@example 3296@@titlepage 3297@dots{} 3298@@page 3299@@vskip 0pt plus 1filll 3300@@insertcopying |
3301 |
3302Published by @dots{} |
3303 |
3304Cover art by @dots{} 3305@@end titlepage 3306@end example 3307 3308 |
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 |
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. |
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). |
3324You can specify these formats in different ways: |
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. |
3331(@xref{setchapternewpage}.) |
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 |
3343information about page headings and footings. |
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 |
3349single-sided printing. |
3350 |
3351 3352@node headings on off |
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 |
3417@cindex Top node |
3418@cindex Node, `Top' 3419 |
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. |
3426 |
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}). |
3432 |
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 |
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 |
3438@code{@@ifnottex} and @code{@@end ifnottext}, but it is simplest to do 3439so. @xref{Conditionals, , Conditionally Visible Text}.) |
3440 3441@menu |
3442* Top Node Example:: 3443* Master Menu Parts:: |
3444@end menu 3445 3446 |
3447@node Top Node Example 3448@subsection Top Node Example |
3449 |
3450@cindex Top node example |
3451 |
3452Here is an example of a Top node. |
3453 3454@example 3455@group |
3456@@ifnottex |
3457@@node Top 3458@@top Sample Title |
3459 |
3460@@insertcopying |
3461@end group 3462 |
3463Additional general information. |
3464 3465@group 3466@@menu |
3467* First Chapter:: 3468* Second Chapter:: |
3469@dots{} |
3470* Index:: |
3471@end group 3472@@end menu 3473@end example 3474 |
3475 |
3476@node Master Menu Parts |
3477@subsection Parts of a Master Menu |
3478@cindex Master menu 3479@cindex Menu, master |
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} |
3486commands and does not appear in the printed document. |
3487 |
3488Generally, a master menu is divided into parts. |
3489 3490@itemize @bullet 3491@item 3492The first part contains the major nodes in the Texinfo file: the nodes |
3493for the chapters, chapter-like sections, and the appendices. |
3494 3495@item |
3496The second part contains nodes for the indices. |
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 |
3512information.) |
3513 3514For example, the master menu for this manual looks like the following |
3515(but has many more entries): |
3516 3517@example 3518@group 3519@@menu |
3520* Copying Conditions:: Your rights. 3521* Overview:: Texinfo in brief. |
3522@dots{} |
3523@end group 3524@group 3525* Command and Variable Index:: |
3526* Concept Index:: |
3527@end group 3528 3529@group 3530@@detailmenu 3531 --- The Detailed Node Listing --- 3532 3533Overview of Texinfo 3534 |
3535* Reporting Bugs:: @dots{} |
3536@dots{} |
3537@end group 3538 3539@group |
3540Beginning a Texinfo File |
3541 |
3542* Sample Beginning:: @dots{} |
3543@dots{} |
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 |
3758@node Software Copying Permissions |
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 |
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 |
3769GNU software. It ensures that you and others will continue to have a |
3770right to use and share the software. |
3771 3772The copying and distribution information and the disclaimer are followed |
3773by an introduction or else by the first chapter of the manual. |
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. |
3781 |
3782 3783@node Ending a File |
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 |
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. |
3794 3795@need 700 3796For example: 3797 3798@example |
3799@@node Index 3800@@unnumbered Index |
3801 3802@@printindex cp 3803 |
3804@@shortcontents |
3805@@contents |
3806 |
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 |
3817 3818@node Printing Indices & Menus 3819@section Printing Indices and Menus |
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 |
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. |
3836 |
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}). |
3841 |
3842Here are the predefined indices, their abbreviations, and the 3843corresponding index entry commands: |
3844 |
3845@table @samp 3846@item cp |
3847concept index (@code{@@cindex}) |
3848@item fn |
3849function index (@code{@@findex}) |
3850@item vr |
3851variable index (@code{@@index}) |
3852@item ky |
3853key index (@code{@@kindex}) |
3854@item pg |
3855program index (@code{@@pindex}) |
3856@item tp |
3857data type index (@code{@@tindex}) |
3858@end table |
3859 |
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 |
3871For example: 3872 3873@smallexample 3874@group |
3875@@node Variable Index |
3876@@unnumbered Variable Index 3877 3878@@printindex vr 3879@end group 3880 3881@group |
3882@@node Concept Index |
3883@@unnumbered Concept Index 3884 3885@@printindex cp 3886@end group 3887@end smallexample 3888 3889@noindent |
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}). |
3894 |
3895 |
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 |
3914unnumbered chapters. Headings generated by the @code{@@heading} 3915series of commands do not appear in the table of contents. |
3916 3917@item @@shortcontents 3918@itemx @@summarycontents |
3919(@code{@@summarycontents} is a synonym for @code{@@shortcontents}.) |
3920 3921Generate a short or summary table of contents that lists only the |
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. |
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 |
3963Texinfo documents, at this writing). You can do this by specifying |
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 |
3973example). We recommend using @command{texi2dvi} (@pxref{Format with 3974texi2dvi}) to specify this without altering the source file at all. For 3975example: |
3976@example |
3977texi2dvi --texinfo=@@setcontentsaftertitlepage foo.texi |
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 |
3986the formatting commands reading anything following @code{@@bye}. The 3987@code{@@bye} command should be on a line by itself. |
3988 |
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. |
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. |
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 |
4905@cindex Case in node name |
4906@item 4907Case is significant. 4908@end itemize 4909 4910 |
4911@node First Node |
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 |
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. |
4920 |
4921Here is a description of the node pointers to be used in the Top node: 4922 4923@itemize @bullet 4924 4925@item |
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 |
4930menu that leads to this file. Specify the file name in parentheses. |
4931 |
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. |
4936 |
4937@item |
4938@cindex Previous node of Top node |
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. |
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 |
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): |
4957 |
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 |
4967@subsection The @code{@@top} Sectioning Command 4968@findex top @r{(@@-command)} 4969 |
4970A special sectioning command, @code{@@top} should be used with the 4971@code{@@node Top} line. The @code{@@top} sectioning command tells |
4972@code{makeinfo} that it marks the `Top' node in the file. It provides |
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. |
4977 |
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. |
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 |
4989create or update pointers and menus. |
4990 |
4991Thus, in practice, a Top node starts like this: |
4992 |
4993@example 4994@@node Top 4995@@top Your Manual Title 4996@end example |
4997 |
4998 |
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, |
5124not the printed document. |
5125 5126For example, the preceding two paragraphs follow an Info-only menu, |
5127@code{@@node} line, and heading, and look like this: |
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 |
5148The Texinfo file for this document contains a number of 5149examples of this procedure; one is at the beginning of this chapter. |
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. |
6478* verb:: A verbatim sequence of characters. |
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. |
7420* verbatiminclude:: Including a file 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 |
7635block. No character substitutions are made. All commands 7636are ignored, until `<at>end verbatim'. |
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: |
7650@c oops, got to trick this a bit: can't use @end verbatim inside @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} |
7672produce no output, tyically you should put a blank line before the |
7673@code{@@verbatim} and another blank line after the @code{@@end 7674verbatim}. Blank lines between the beginning @code{@@verbatim} and the |
7675ending @code{@@end verbatim} will appear in the output. |
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 |
8882@node syncodeindex |
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 |
9030@code{@@syncodeindex} commands (@pxref{Texinfo File Header}). |
9031 |
9032 |
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 @@@@ |
9100@findex @@ @r{(literal @samp{@@})} |
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 @@@} |
9110@findex @{ @r{(literal @samp{@{})} 9111@findex @} @r{(literal @samp{@}})} |
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 |
9336@findex " @r{(umlaut accent)} |
9337@cindex Umlaut accent |
9338@findex ' @r{(umlaut accent)} |
9339@cindex Acute accent |
9340@findex = @r{(macron accent)} |
9341@cindex Macron accent |
9342@findex ^ @r{(circumflex accent)} |
9343@cindex Circumflex accent |
9344@findex ` @r{(grave accent)} |
9345@cindex Grave accent |
9346@findex ~ @r{(tilde accent)} |
9347@cindex Tilde accent |
9348@findex , @r{(cedilla accent)} |
9349@cindex Cedilla accent 9350@findex dotaccent 9351@cindex Dot accent |
9352@findex H @r{(Hungarian umlaut accent)} |
9353@cindex Hungarian umlaut accent 9354@findex ringaccent 9355@cindex Ring accent 9356@findex tieaccent 9357@cindex Tie-after accent |
9358@findex u @r{(breve accent)} |
9359@cindex Breve accent 9360@findex ubaraccent 9361@cindex Underbar accent 9362@findex udotaccent 9363@cindex Underdot accent |
9364@findex v @r{(check accent)} |
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 |
9611conventional to use @samp{\} instead of @samp{@@} for these commands. 9612As in: |
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 |
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 |
10451@findex - @r{(discretionary hyphen)} |
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 |
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{@@-}. |
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 |
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 |
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. |
11835 11836@findex iftex 11837@findex ifhtml |
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. |
11846 11847For example, 11848 11849@example 11850@@iftex 11851This text will appear only in the printed manual. 11852@@end iftex 11853@@ifinfo |
11854However, this text will appear only in Info (or plain text). |
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 |
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 |
11870However, this text will appear only in Info (or plain text). |
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 |
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 |
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 |
11897@@ifnottex @dots{} @@end ifnottex 11898@end example 11899@noindent 11900(The @code{@@ifnot@dots{}} command and the @code{@@end} command must |
11901appear on lines by themselves in your actual source file.) |
11902 |
11903If the output file is @emph{not} being made for the given format, the 11904region is included. Otherwise, it is ignored. |
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 |
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 |
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. |
12188 |
12189Here is an example adapted from @ref{Top,, Overview, make, The GNU Make 12190Manual}): 12191 |
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 |
12206Write text for the @code{@@copying} section (@pxref{copying}): |
12207 12208@example 12209@group |
12210@@copying |
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 |
12220@end group 12221@end example 12222 12223@item 12224Write text for the title page, for people reading the printed manual: |
12225 12226@example 12227@group |
12228@@titlepage |
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 |
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 |
12249@@ifnottex 12250@@node Top 12251@@top Make 12252 12253@@insertcopying 12254@dots{} 12255@@end ifnottex |
12256@end group 12257@end example 12258 |
12259After you format the manual, the @code{@@value} constructs have been 12260expanded, so the output contains text like this: |
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 |
12270When you update the manual, you change only the values of the flags; you 12271do not need to edit the three sections. |
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 |
12780@@ifnottex |
12781@@macro ctor @{name, arg@} 12782@@macro \name\ 12783something involving \arg\ somehow 12784@@end macro 12785@@end macro |
12786@@end ifnottex |
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 |
13352@cindex Customize Emacs package (@t{Development/Docs/Texinfo}) |
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 |
13361@node Compile-Command |
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 |
13762@findex \mag @r{(raw @TeX{} magnification)} |
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:: |
13833* Installing an Info File:: |
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 |
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 |
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). |
14044 14045@cindex Navigation links, omitting |
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}. |
14050 |
14051In both cases, write to standard output by default (can still be 14052overridden by @option{-o}). 14053 |
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 |
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. |
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. |
14572* New Info File:: Listing a new Info file. |
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 |
14812In order for the Info file to work with @code{install-info}, you include 14813the commands @code{@@dircategory} and |
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 |
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 |
15012an @code{@@refill} command. @xref{Line Breaks}. |
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 |
15048@item @@^ 15049@itemx @@` 15050Generate a circumflex (hat) or grave accent, respectively, over the next |
15051character, as in @^o and @`e. |
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) |
15444pages. @xref{Custom Headings, , |
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}@} |
15543Print @var{text} in @i{italic} font. No effect in Info. @xref{Fonts}. |
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 |
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}. |
15558 15559@item @@ifnothtml 15560@itemx @@ifnotinfo |
15561@itemx @@ifnotplaintext |
15562@itemx @@ifnottex 15563Begin a stretch of text that will be ignored in one output format but |
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}. |
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 |
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. |
15611@xref{Texinfo File Header}. |
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) |
15717pages. @xref{Custom Headings, , |
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 |
16013topmost @code{@@node} in the file, which must be written on the line |
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} |
16017line normally should be enclosed by @code{@@ifnottex} and @code{@@end 16018ifnottex}. In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top} |
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 |
16100only in contexts ignored for Info. @xref{Copyright}. |
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 |
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). |
16276 |
16277It is easiest to do this using @code{@@set} and @code{@@value}. 16278@xref{value Example, , @code{@@value} Example}, and @ref{GNU Sample Texts}. |
16279 |
16280 |
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 |
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 |
16545@cindex Sample Texinfo file, no comments 16546 16547Here is a complete, short sample Texinfo file, without any commentary. |
16548You can see this file, with comments, in the first chapter. @xref{Short 16549Sample}. |
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 |
16556@sp 1 16557@example 16558\input texinfo @@c -*-texinfo-*- 16559@@c %**start of header 16560@@setfilename sample.info |
16561@@settitle Sample Manual 1.0 |
16562@@c %**end of header 16563 |
16564@@copying |
16565This is a short example of a complete Texinfo file. 16566 16567Copyright (C) 2002 Free Software Foundation, Inc. |
16568@@end copying |
16569 16570@@titlepage |
16571@@title Sample Title |
16572@@page 16573@@vskip 0pt plus 1filll |
16574@@insertcopying |
16575@@end titlepage 16576 16577@@c Output the table of the contents at the beginning. 16578@@contents 16579 16580@@ifnottex 16581@@node Top 16582 |
16583@@insertcopying |
16584@@end ifnottex 16585 16586@@menu 16587* First Chapter:: The first chapter is the |
16588 only chapter in this sample. 16589* Index:: Complete index. |
16590@@end menu 16591 16592 |
16593@@node First Chapter |
16594@@chapter First Chapter |
16595 |
16596@@cindex chapter, first |
16597 |
16598This is the first chapter. 16599@@cindex index entry, another 16600 |
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 |
16611 |
16612@@node Index 16613@@unnumbered Index |
16614 |
16615@@printindex cp |
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 |
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 |
16799the indices of the output file. |
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 |
17015An included file, such as @file{foo.texinfo}, might look like this: |
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 |
17269after the @code{@@end titlepage} command. 17270You must cancel the predefined heading commands with the |
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 |
17281@@headings off 17282@@everyheading @@thischapter @@| @@thispage @@| @@today@{@} |
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 |
17382@@headings off 17383@@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter 17384@@everyfooting @@| @@| Version: 0.27: @@today@{@} |
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 |
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. |
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 |
18728@node Copying This Manual 18729@appendix Copying This Manual |
18730 |
18731@menu 18732* GNU Free Documentation License:: License for copying this manual. 18733@end menu |
18734 |
18735@include fdl.texi |
18736 |
18737 |
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 |