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
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