1\input texinfo.tex @c -*-texinfo-*-
2@c $Id: texinfo.txi,v 1.192 2002/03/04 14:52:52 karl Exp $
3@c %**start of header
4
5@c All text is ignored before the setfilename.
6@setfilename texinfo
7
8@include version.texi
9@settitle Texinfo @value{VERSION}
10
11@c Define a new index for options.
12@defcodeindex op
13@c Put everything except function (command, in this case) names in one
14@c index (arbitrarily chosen to be the concept index).
15@syncodeindex op cp
16@syncodeindex vr cp
17@syncodeindex pg cp
18
19@footnotestyle separate
20@paragraphindent 2
21@c finalout
22
23@comment %**end of header
24
25@dircategory Texinfo documentation system
26@direntry
27* Texinfo: (texinfo). The GNU documentation format.
28* install-info: (texinfo)Invoking install-info. Update info/dir entries.
29* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
30* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
31* makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source.
32@end direntry
--- 4 unchanged lines hidden (view full) ---
37@c Set smallbook if printing in smallbook format so the example of the
38@c smallbook font is actually written using smallbook; in bigbook, a kludge
39@c is used for TeX output. Do this through the -t option to texi2dvi,
40@c so this same source can be used for other paper sizes as well.
41@c smallbook
42@c set smallbook
43@c @@clear smallbook
44
45@c If you like blank pages. Can add through texi2dvi -t.
46@c setchapternewpage odd
47
48@c Currently undocumented command, 5 December 1993:
49@c nwnode (Same as node, but no warnings; for `makeinfo'.)
50
51@ifinfo
52This file documents Texinfo, a documentation system that can produce
53both online information and a printed manual from a single source. This
54edition is for Texinfo version @value{VERSION}, @value{UPDATED}.
55
56Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99, 2000, 01, 02
57Free Software Foundation, Inc.
58
59Permission is granted to copy, distribute and/or modify this document
60under the terms of the GNU Free Documentation License, Version 1.1 or
61any later version published by the Free Software Foundation; with the
62Invariant Section being ``History'', with no Front-Cover Texts, and with
63no Back-Cover Texts. A copy of the license is included in the section
64entitled ``GNU Free Documentation License''.
65@end ifinfo
66
67
68@shorttitlepage Texinfo
69
70@titlepage
71@title Texinfo
72@subtitle The GNU Documentation Format
73@subtitle for Texinfo version @value{VERSION}, @value{UPDATED}
74
75@author Robert J. Chassell
76@author Richard M. Stallman
77
78@c Include the Distribution inside the titlepage so
79@c that headings are turned off.
80
81@page
82@vskip 0pt plus 1filll
83Copyright @copyright{} 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99, 2000, 01, 02
84Free Software Foundation, Inc.
85
86This manual is for Texinfo version @value{VERSION}, @value{UPDATED}.
87
88Published by the Free Software Foundation @*
8959 Temple Place Suite 330 @*
90Boston, MA 02111-1307 @*
91USA @*
92ISBN 1-882114-67-1 @c for version 4.0, September 1999.
93@c ISBN 1-882114-65-5 @c for version 3.12, March 1998.
94@c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995
95@c ISBN 1-882114-64-7 is for edition 2.24 of November 1996.
96
97Cover art by Etienne Suvasa.
98
99Permission is granted to copy, distribute and/or modify this document
100under the terms of the GNU Free Documentation License, Version 1.1 or
101any later version published by the Free Software Foundation; with the
102Invariant Section being ``History'', with no Front-Cover Texts, and with
103no Back-Cover Texts. A copy of the license is included in the section
104entitled ``GNU Free Documentation License''.
105
106@end titlepage
107
108@summarycontents
109@contents
110
111@ifnottex
112@node Top
113@top Texinfo
114
115Texinfo is a documentation system that uses a single source to produce
116both online information and printed output.
117
118The first part of this master menu lists the major nodes in this Info
119document, including the @@-command and concept indices. The rest of
120the menu lists all the lower level nodes in the document.
121
122This is Edition @value{VERSION} of the Texinfo manual, updated @value{UPDATED}.
123@end ifnottex
124
125@menu
126* Copying:: Your rights.
127* Overview:: Texinfo in brief.
128* Texinfo Mode:: How to use Texinfo mode.
129* Beginning a File:: What is at the beginning of a Texinfo file?
130* Ending a File:: What is at the end of a Texinfo file?
131* Structuring:: How to create chapters, sections, subsections,
132 appendices, and other parts.
133* Nodes:: How to write nodes.
134* Menus:: How to write menus.
--- 11 unchanged lines hidden (view full) ---
146* Conditionals:: How to specify text for either @TeX{} or Info.
147* Internationalization::
148* Defining New Texinfo Commands::
149* Hardcopy:: How to convert a Texinfo file to a file
150 for printing and how to print that file.
151* Creating and Installing Info Files::
152* Command List:: All the Texinfo @@-commands.
153* Tips:: Hints on how to write a Texinfo document.
154* Sample Texinfo File:: A sample Texinfo file to look at.
155* Include Files:: How to incorporate other Texinfo files.
156* Headings:: How to write page headings and footings.
157* Catching Mistakes:: How to find formatting mistakes.
158* Refilling Paragraphs:: All about paragraph refilling.
159* Command Syntax:: A description of @@-Command syntax.
160* Obtaining TeX:: How to Obtain @TeX{}.
161* Documentation Copying:: The GNU Free Documentation License.
162* Command and Variable Index:: A menu containing commands and variables.
163* Concept Index:: A menu covering many topics.
164
165@detailmenu
166 --- The Detailed Node Listing ---
167
168Overview of Texinfo
169
--- 27 unchanged lines hidden (view full) ---
197* Updating Requirements:: How to structure a Texinfo file for
198 using the updating command.
199* Other Updating Commands:: How to indent descriptions, insert
200 missing nodes lines, and update
201 nodes in sequence.
202
203Beginning a Texinfo File
204
205* Four Parts:: Four parts begin a Texinfo file.
206* Sample Beginning:: Here is a sample beginning for a Texinfo file.
207* Header:: The very beginning of a Texinfo file.
208* Info Summary and Permissions:: Summary and copying permissions for Info.
209* Titlepage & Copyright Page:: Creating the title and copyright pages.
210* The Top Node:: Creating the `Top' node and master menu.
211* Software Copying Permissions:: Ensure that you and others continue to
212 have the right to use and share software.
213
214The Texinfo File Header
215
216* First Line:: The first line of a Texinfo file.
217* Start of Header:: Formatting a region requires this.
218* setfilename:: Tell Info the name of the Info file.
219* settitle:: Create a title for the printed work.
220* documentdescription:: Document summary for the HTML output.
221* setchapternewpage:: Start chapters on right-hand pages.
222* paragraphindent:: Specify paragraph indentation.
223* exampleindent:: Specify environment indentation.
224* End of Header:: Formatting a region requires this.
225
226The Title and Copyright Pages
227
228* titlepage:: Create a title for the printed document.
229* titlefont center sp:: The @code{@@titlefont}, @code{@@center},
230 and @code{@@sp} commands.
231* title subtitle author:: The @code{@@title}, @code{@@subtitle},
232 and @code{@@author} commands.
233* Copyright & Permissions:: How to write the copyright notice and
234 include copying permissions.
235* end titlepage:: Turn on page headings after the title and
236 copyright pages.
237* headings on off:: An option for turning headings on and off
238 and double or single sided printing.
239
240The `Top' Node and Master Menu
241
242* Title of Top Node:: Sketch what the file is about.
243* Master Menu Parts:: A master menu has three or more parts.
244
245Ending a Texinfo File
246
247* Printing Indices & Menus:: How to print an index in hardcopy and
248 generate index menus in Info.
249* Contents:: How to create a table of contents.
250* File End:: How to mark the end of a file.
251
252Chapter Structuring
--- 23 unchanged lines hidden (view full) ---
276The @code{@@node} Command
277
278* Node Names:: How to choose node and pointer names.
279* Writing a Node:: How to write an @code{@@node} line.
280* Node Line Tips:: Keep names short.
281* Node Line Requirements:: Keep names unique, without @@-commands.
282* First Node:: How to write a `Top' node.
283* makeinfo top command:: How to use the @code{@@top} command.
284* Top Node Summary:: Write a brief description for readers.
285
286Menus
287
288* Menu Location:: Put a menu in a short node.
289* Writing a Menu:: What is a menu?
290* Menu Parts:: A menu entry has three parts.
291* Less Cluttered Menu Entry:: Two part menu entry.
292* Menu Example:: Two and three part menu entries.
--- 26 unchanged lines hidden (view full) ---
319
320Indicating Definitions, Commands, etc.
321
322* Useful Highlighting:: Highlighting provides useful information.
323* code:: Indicating program code.
324* kbd:: Showing keyboard input.
325* key:: Specifying keys.
326* samp:: A literal sequence of characters.
327* verb:: A verbatim sequence of characters.
328* var:: Indicating metasyntactic variables.
329* env:: Indicating environment variables.
330* file:: Indicating file names.
331* command:: Indicating command names.
332* option:: Indicating option names.
333* dfn:: Specifying definitions.
334* cite:: Referring to books not in the Info system.
335* acronym:: Indicating acronyms.
--- 7 unchanged lines hidden (view full) ---
343* Fonts:: Various font commands for printed output.
344
345Quotations and Examples
346
347* Block Enclosing Commands:: Different constructs for different purposes.
348* quotation:: Writing a quotation.
349* example:: Writing an example in a fixed-width font.
350* verbatim:: Writing a verbatim example.
351* verbatiminclude:: Including a file verbatim.
352* lisp:: Illustrating Lisp code.
353* small:: Forms for @code{@@smallbook}.
354* display:: Writing an example in the current font.
355* format:: Writing an example without narrowed margins.
356* exdent:: Undo indentation on a line.
357* flushleft & flushright:: Pushing text flush left or flush right.
358* noindent:: Preventing paragraph indentation.
359* cartouche:: Drawing rounded rectangles around examples.
--- 171 unchanged lines hidden (view full) ---
531* pagesizes:: How to print with customized page sizes.
532* Cropmarks and Magnification:: How to print marks to indicate the size
533 of pages and how to print scaled up output.
534* PDF Output:: Portable Document Format output.
535
536Creating and Installing Info Files
537
538* Creating an Info File::
539* Installing an Info File::
540
541Creating an Info File
542
543* makeinfo advantages:: @code{makeinfo} provides better error checking.
544* Invoking makeinfo:: How to run @code{makeinfo} from a shell.
545* makeinfo options:: Specify fill-column and other options.
546* Pointer Validation:: How to check that pointers point somewhere.
547* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs.
--- 10 unchanged lines hidden (view full) ---
558* Directory File:: The top level menu for all Info files.
559* New Info File:: Listing a new Info file.
560* Other Info Directories:: How to specify Info files that are
561 located in other directories.
562* Installing Dir Entries:: How to specify what menu entry to add
563 to the Info directory.
564* Invoking install-info:: @code{install-info} options.
565
566Include Files
567
568* Using Include Files:: How to use the @code{@@include} command.
569* texinfo-multiple-files-update:: How to create and update nodes and
570 menus when using included files.
571* Include File Requirements:: What @code{texinfo-multiple-files-update} expects.
572* Sample Include File:: A sample outer file with included files
573 within it; and a sample included file.
--- 18 unchanged lines hidden (view full) ---
592
593Finding Badly Referenced Nodes
594
595* Using Info-validate:: How to run @code{Info-validate}.
596* Unsplit:: How to create an unsplit file.
597* Tagifying:: How to tagify a file.
598* Splitting:: How to split a file manually.
599
600@end detailmenu
601@end menu
602
603@c Reward readers for getting to the end of the menu :).
604@c Contributed by Arnold Robbins.
605@quotation
606Documentation is like sex: when it is good, it is very, very good; and
607when it is bad, it is better than nothing.
608---Dick Brandon
609@end quotation
610
611
612@node Copying
613@unnumbered Texinfo Copying Conditions
614@cindex Copying conditions
615@cindex Conditions for copying Texinfo
616
617The programs currently being distributed that relate to Texinfo include
618@code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}.
619These programs are @dfn{free}; this means that everyone is free to use
620them and free to redistribute them on a free basis. The Texinfo-related
--- 19 unchanged lines hidden (view full) ---
640out that there is no warranty for the programs that relate to Texinfo.
641If these programs are modified by someone else and passed on, we want
642their recipients to know that what they have is not what we distributed,
643so that any problems introduced by others will not reflect on our
644reputation.
645
646The precise conditions of the licenses for the programs currently being
647distributed that relate to Texinfo are found in the General Public
648Licenses that accompany them.
649
650
651@node Overview
652@chapter Overview of Texinfo
653@cindex Overview of Texinfo
654@cindex Texinfo overview
655
656@dfn{Texinfo}@footnote{The first syllable of ``Texinfo'' is pronounced
--- 37 unchanged lines hidden (view full) ---
694from @uref{ftp://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide.
695
696@cindex Checklist for bug reports
697For bug reports, please include enough information for the maintainers
698to reproduce the problem. Generally speaking, that means:
699
700@itemize @bullet
701@item the version number of Texinfo and the program(s) or manual(s) involved.
702@item hardware, operating system, and compiler versions.
703@item any unusual options you gave to @command{configure}.
704@item the contents of any input files necessary to reproduce the bug.
705@item a description of the problem and samples of any erroneous output.
706@item anything else that you think would be helpful.
707@end itemize
708
709When in doubt whether something is needed or not, include it. It's
710better to include too much than to leave out something important.
711
712Patches are most welcome; if possible, please make them with
713@samp{@w{diff -c}} (@pxref{Top,, Overview, diffutils, Comparing and
714Merging Files}) and include @file{ChangeLog} entries (@pxref{Change
715Log,,, emacs, The GNU Emacs Manual}).
716
717When sending patches, if possible please do not encode or split them in
718any way; it's much easier to deal with one plain text message, however
719large, than many small ones. @uref{ftp://ftp.gnu.org/gnu/sharutils/,
--- 13 unchanged lines hidden (view full) ---
733indices. From the same Texinfo source file, you can create a
734menu-driven, online Info file with nodes, menus, cross references, and
735indices. You can also create from that same source file an HTML output
736file suitable for use with a web browser, or an XML file. @cite{The GNU
737Emacs Manual} is a good example of a Texinfo file, as is this manual.
738
739To make a printed document, you process a Texinfo source file with the
740@TeX{} typesetting program (but the Texinfo language is very different
741from @TeX{}'s usual language, plain @TeX{}). This creates a DVI file
742that you can typeset and print as a book or report (@pxref{Hardcopy}).
743
744@pindex makeinfo
745To output an Info file, process your Texinfo source with the
746@code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command.
747You can install the result in your Info tree (@pxref{Installing an Info
748File}).
749
750To output an HTML file, run @code{makeinfo --html} on your Texinfo
751source. You can (for example) install the result on your web site.
752
753@cindex Docbook, converting to Texinfo
754@cindex Conversion, from Docbook to Texinfo
755To output an XML file, run @code{makeinfo --xml} on your Texinfo source.
756To output DocBook, run @code{makeinfo --docbook}. If you want to
757convert from Docbook @emph{to} Texinfo, please see
758@uref{http://docbook2X.sourceforge.net/}.
759
760@cindex Output formats, supporting more
761@cindex SGML-tools output format
762If you are a programmer and would like to contribute to the GNU project
763by implementing additional output formats for Texinfo, that would be
764excellent. But please do not write a separate translator texi2foo for
765your favorite format foo! That is the hard way to do the job, and makes
766extra work in subsequent maintenance, since the Texinfo language is
767continually being enhanced and updated. Instead, the best approach is
768modify @code{makeinfo} to generate the new format, as it does now for
769Info and HTML.
770
771@TeX{} works with virtually all printers; Info works with virtually all
772computer terminals; the HTML output works with virtually all web
773browsers. Thus Texinfo can be used by almost any computer user.
774
775@cindex Source file
776A Texinfo source file is a plain @sc{ascii} file containing text and
777@dfn{@@-commands} (words preceded by an @samp{@@}) that tell the
--- 14 unchanged lines hidden (view full) ---
792
793@cindex Man page output, not supported
794From time to time, proposals are made to generate traditional Unix man
795pages from Texinfo source. This is not likely to ever be supported,
796because man pages have a very strict conventional format. Merely
797enhancing @command{makeinfo} to output troff format would be
798insufficient. Generating a good man page therefore requires a
799completely different source than the typical Texinfo applications of
800generating a good user manual or a good reference manual. This makes
801generating man pages incompatible with the Texinfo design goal of not
802having to document the same information in different ways for different
803output formats. You might as well just write the man page directly.
804
805@pindex help2man
806@cindex O'Dea, Brendan
807If you wish to support man pages, the program @command{help2man} may be
808useful; it generates a traditional man page from the @samp{--help}
809output of a program. In fact, this is currently used to generate man
810pages for the Texinfo programs themselves. It is GNU software written
811by Brendan O'Dea, available from
812@uref{http://www.ozemail.com.au/~bod/help2man.tar.gz}.
813
814
815@node Info Files
816@section Info files
817@cindex Info files
818
819An Info file is a Texinfo file formatted so that the Info documentation
820reading program can operate on it. (@code{makeinfo}
821and @code{texinfo-format-buffer} are two commands that convert a Texinfo file
822into an Info file.)@refill
823
824Info files are divided into pieces called @dfn{nodes}, each of which
825contains the discussion of one topic. Each node has a name, and
826contains both text for the user to read and pointers to other nodes,
827which are identified by their names. The Info program displays one node
828at a time, and provides commands with which the user can move to other
829related nodes.@refill
830
831@ifinfo
832@inforef{Top, info, info}, for more information about using Info.@refill
833@end ifinfo
834
835Each node of an Info file may have any number of child nodes that
836describe subtopics of the node's topic. The names of child
837nodes are listed in a @dfn{menu} within the parent node; this
838allows you to use certain Info commands to move to one of the child
839nodes. Generally, an Info file is organized like a book. If a node
840is at the logical level of a chapter, its child nodes are at the level
841of sections; likewise, the child nodes of sections are at the level
842of subsections.@refill
843
844All the children of any one parent are linked together in a
845bidirectional chain of `Next' and `Previous' pointers. The `Next'
846pointer provides a link to the next section, and the `Previous' pointer
847provides a link to the previous section. This means that all the nodes
848that are at the level of sections within a chapter are linked together.
849Normally the order in this chain is the same as the order of the
850children in the parent's menu. Each child node records the parent node
851name as its `Up' pointer. The last child has no `Next' pointer, and the
852first child has the parent both as its `Previous' and as its `Up'
853pointer.@footnote{In some documents, the first child has no `Previous'
854pointer. Occasionally, the last child has the node name of the next
855following higher level node as its `Next' pointer.}@refill
856
857The book-like structuring of an Info file into nodes that correspond
858to chapters, sections, and the like is a matter of convention, not a
859requirement. The `Up', `Previous', and `Next' pointers of a node can
860point to any other nodes, and a menu can contain any other nodes.
861Thus, the node structure can be any directed graph. But it is usually
862more comprehensible to follow a structure that corresponds to the
863structure of chapters and sections in a printed book or report.@refill
--- 82 unchanged lines hidden (view full) ---
946file @file{texinfo.tex} that contains information (definitions or
947@dfn{macros}) that @TeX{} uses when it typesets a Texinfo file.
948(@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands
949to @TeX{} commands, which @TeX{} can then process to create the typeset
950document.) @file{texinfo.tex} contains the specifications for printing
951a document. You can get the latest version of @file{texinfo.tex} from
952@uref{ftp://ftp.gnu.org/gnu/texinfo.tex}.
953
954Most often, documents are printed on 8.5 inch by 11 inch pages
955(216@dmn{mm} by 280@dmn{mm}; this is the default size), but you can also
956print for 7 inch by 9.25 inch pages (178@dmn{mm} by 235@dmn{mm}; the
957@code{@@smallbook} size) or on A4 or A5 size paper (@code{@@afourpaper},
958@code{@@afivepaper}). (@xref{smallbook, , Printing ``Small'' Books}.
959Also, see @ref{A4 Paper, ,Printing on A4 Paper}.)
960
961By changing the parameters in @file{texinfo.tex}, you can change the
962size of the printed document. In addition, you can change the style in
963which the printed document is formatted; for example, you can change the
964sizes and fonts used, the amount of indentation for each paragraph, the
965degree to which words are hyphenated, and the like. By changing the
966specifications, you can make a book look dignified, old and serious, or
967light-hearted, young and cheery.@refill
968
969@TeX{} is freely distributable. It is written in a superset of Pascal
970called WEB and can be compiled either in Pascal or (by using a
971conversion program that comes with the @TeX{} distribution) in C.
972(@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information
973about @TeX{}.)@refill
974
975@TeX{} is very powerful and has a great many features. Because a
976Texinfo file must be able to present information both on a
977character-only terminal in Info form and in a typeset book, the
978formatting commands that Texinfo supports are necessarily
979limited.@refill
980
981To get a copy of @TeX{}, see
982@ref{Obtaining TeX, , How to Obtain @TeX{}}.
983
984
985@node Formatting Commands, Conventions, Printed Books, Overview
986@section @@-commands
987@cindex @@-commands
988@cindex Formatting commands
989
990In a Texinfo file, the commands that tell @TeX{} how to typeset the
991printed manual and tell @code{makeinfo} and
992@code{texinfo-format-buffer} how to create an Info file are preceded
993by @samp{@@}; they are called @dfn{@@-commands}. For example,
994@code{@@node} is the command to indicate a node and @code{@@chapter}
995is the command to indicate the start of a chapter.@refill
996
997@quotation
998@strong{Please note:} All the @@-commands, with the exception of the
999@code{@@TeX@{@}} command, must be written entirely in lower
1000case.@refill
1001@end quotation
1002
1003The Texinfo @@-commands are a strictly limited set of constructs. The
1004strict limits make it possible for Texinfo files to be understood both
1005by @TeX{} and by the code that converts them into Info files. You can
1006display Info files on any terminal that displays alphabetic and
1007numeric characters. Similarly, you can print the output generated by
1008@TeX{} on a wide variety of printers.@refill
--- 53 unchanged lines hidden (view full) ---
1062
1063As you gain experience with Texinfo, you will rapidly learn how to
1064write the different commands: the different ways to write commands
1065make it easier to write and read Texinfo files than if all commands
1066followed exactly the same syntax. (For details about @@-command
1067syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill
1068
1069
1070@node Conventions, Comments, Formatting Commands, Overview
1071@section General Syntactic Conventions
1072@cindex General syntactic conventions
1073@cindex Syntactic conventions
1074@cindex Conventions, syntactic
1075
1076This section describes the general conventions used in all Texinfo documents.
1077
1078@itemize @bullet
1079@item
1080All printable @sc{ascii} characters except @samp{@@}, @samp{@{} and
1081@samp{@}} can appear in a Texinfo file and stand for themselves.
1082@samp{@@} is the escape character which introduces commands.
1083@samp{@{} and @samp{@}} should be used only to surround arguments to
1084certain commands. To put one of these special characters into the
1085document, put an @samp{@@} character in front of it, like this:
1086@samp{@@@@}, @samp{@@@{}, and @samp{@@@}}.@refill
1087
1088@item
1089@ifinfo
1090It is customary in @TeX{} to use doubled single-quote characters to
1091begin and end quotations: ` ` and ' ' (but without a space between the
1092two single-quote characters). This convention should be followed in
1093Texinfo files. @TeX{} converts doubled single-quote characters to
1094left- and right-hand doubled quotation marks and Info converts doubled
1095single-quote characters to @sc{ascii} double-quotes: ` ` and ' ' to " .@refill
1096@end ifinfo
1097@iftex
1098It is customary in @TeX{} to use doubled single-quote characters to
1099begin and end quotations: @w{@t{ `` }} and @w{@t{ '' }}. This
1100convention should be followed in Texinfo files. @TeX{} converts
1101doubled single-quote characters to left- and right-hand doubled
1102quotation marks, ``like this'', and Info converts doubled single-quote
1103characters to @sc{ascii} double-quotes: @w{@t{ `` }} and
1104@w{@t{ '' }} to @w{@t{ " }}.@refill
1105@end iftex
1106
1107@item
1108Use three hyphens in a row, @samp{---}, for a dash---like this. In
1109@TeX{}, a single or double hyphen produces a printed dash that is
1110shorter than the usual typeset dash. Info reduces three hyphens to two
1111for display on the screen.
1112
1113@item
1114To prevent a paragraph from being indented in the printed manual, put
1115the command @code{@@noindent} on a line by itself before the
1116paragraph.@refill
1117
1118@item
1119If you mark off a region of the Texinfo file with the @code{@@iftex}
1120and @w{@code{@@end iftex}} commands, that region will appear only in
1121the printed copy; in that region, you can use certain commands
1122borrowed from plain @TeX{} that you cannot use in Info. Likewise, if
1123you mark off a region with the @code{@@ifinfo} and @code{@@end ifinfo}
1124commands, that region will appear only in the Info file; in that
1125region, you can use Info commands that you cannot use in @TeX{}.
1126Similarly for @code{@@ifhtml @dots{} @@end ifhtml},
1127@code{@@ifnothtml @dots{} @@end ifnothtml},
1128@code{@@ifnotinfo @dots{} @@end ifnotinfo},
1129@code{@@ifnottex @dots{} @@end ifnottex}.
1130@xref{Conditionals}.
1131@end itemize
1132
1133@cindex Tabs; don't use!
1134@quotation
1135@strong{Caution:} Do not use tabs in a Texinfo file (except in verbatim
1136modes) ! @TeX{} uses variable-width fonts, which means that it is
1137impractical at best to define a tab to work in all circumstances.
1138Consequently, @TeX{} treats tabs like single spaces, and that is not
1139what they look like. Furthermore, @code{makeinfo} does nothing special
1140with tabs, and thus a tab character in your input file may appear
1141differently in the output, for example, in an indented example.
1142
1143@noindent
1144To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple
1145spaces when you press the @key{TAB} key.
1146
1147@noindent
1148Also, you can run @code{untabify} in Emacs to convert tabs in a region
1149to multiple spaces.
1150@end quotation
1151
1152
1153@node Comments, Minimum, Conventions, Overview
1154@section Comments
1155
1156You can write comments in a Texinfo file that will not appear in
1157either the Info file or the printed manual by using the
1158@code{@@comment} command (which may be abbreviated to @code{@@c}).
1159Such comments are for the person who revises the Texinfo file. All the
1160text on a line that follows either @code{@@comment} or @code{@@c} is a
1161comment; the rest of the line does not appear in either the Info file
1162or the printed manual. (Often, you can write the @code{@@comment} or
1163@code{@@c} in the middle of a line, and only the text that follows after
1164the @code{@@comment} or @code{@@c} command does not appear; but some
1165commands, such as @code{@@settitle} and @code{@@setfilename}, work on a
1166whole line. You cannot use @code{@@comment} or @code{@@c} in a line
1167beginning with such a command.)@refill
1168@cindex Comments
1169@findex comment
1170@findex c @r{(comment)}
1171
1172You can write long stretches of text that will not appear in either
1173the Info file or the printed manual by using the @code{@@ignore} and
1174@code{@@end ignore} commands. Write each of these commands on a line
1175of its own, starting each command at the beginning of the line. Text
1176between these two commands does not appear in the processed output.
1177You can use @code{@@ignore} and @code{@@end ignore} for writing
1178comments.
1179
1180@cindex Ignored text
1181@cindex Unprocessed text
1182@findex ignore
1183@c !!! Perhaps include this comment about ignore and ifset:
1184@ignore
1185Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or
1186@code{@@ifclear} conditions is ignored in the sense that it will not
1187contribute to the formatted output. However, @TeX{} and makeinfo must
1188still parse the ignored text, in order to understand when to
1189@emph{stop} ignoring text from the source file; that means that you
1190will still get error messages if you have invalid Texinfo markup
1191within ignored text.
1192@end ignore
1193
1194
1195@node Minimum, Six Parts, Comments, Overview
1196@section What a Texinfo File Must Have
1197@cindex Minimal Texinfo file (requirements)
1198@cindex Must have in Texinfo file
1199@cindex Required in Texinfo file
1200@cindex Texinfo file minimum
1201
1202By convention, the names of Texinfo files end with one of the
1203extensions @file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}.
1204The longer extension is preferred since it describes more clearly to a
1205human reader the nature of the file. The shorter extensions are for
1206operating systems that cannot handle long file names.@refill
1207
1208In order to be made into a printed manual and an Info file, a Texinfo
1209file @strong{must} begin with lines like this:@refill
1210
1211@example
1212@group
1213\input texinfo
1214@@setfilename @var{info-file-name}
1215@@settitle @var{name-of-manual}
1216@end group
1217@end example
1218
1219@noindent
1220The contents of the file follow this beginning, and then you @strong{must} end
1221a Texinfo file with a line like this:@refill
1222
1223@example
1224@@bye
1225@end example
1226
1227@findex input @r{(@TeX{} command)}
1228@noindent
1229The @samp{\input texinfo} line tells @TeX{} to use the
1230@file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo
1231@@-commands into @TeX{} typesetting commands. (Note the use of the
1232backslash, @samp{\}; this is correct for @TeX{}.) The
1233@samp{@@setfilename} line provides a name for the Info file and tells
1234@TeX{} to open auxiliary files. The @samp{@@settitle} line specifies a
1235title for the page headers (or footers) of the printed manual, and the
1236default document description title for the @samp{<head>} in HTML format.
1237
1238The @code{@@bye} line at the end of the file on a line of its own tells
1239the formatters that the file is ended and to stop formatting.@refill
1240
1241Usually, you will not use quite such a spare format, but will include
1242mode setting and start-of-header and end-of-header lines at the
1243beginning of a Texinfo file, like this:@refill
1244
1245@example
1246@group
1247\input texinfo @@c -*-texinfo-*-
1248@@c %**start of header
1249@@setfilename @var{info-file-name}
1250@@settitle @var{name-of-manual}
1251@@c %**end of header
1252@end group
1253@end example
1254
1255@noindent
1256In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into
1257Texinfo mode when you edit the file.
1258
1259The @code{@@c} lines which surround the @samp{@@setfilename} and
1260@samp{@@settitle} lines are optional, but you need them in order to
1261run @TeX{} or Info on just part of the file. (@xref{Start of Header},
1262for more information.)@refill
1263
1264Furthermore, you will usually provide a Texinfo file with a title
1265page, indices, and the like. But the minimum, which can be useful
1266for short documents, is just the three lines at the beginning and the
1267one line at the end.@refill
1268
1269@node Six Parts, Short Sample, Minimum, Overview
1270@comment node-name, next, previous, up
1271@section Six Parts of a Texinfo File
1272
1273Generally, a Texinfo file contains more than the minimal
1274beginning and end---it usually contains six parts:@refill
1275
1276@table @r
1277@item 1. Header
1278The @dfn{Header} names the file, tells @TeX{} which definitions' file to
1279use, and performs other ``housekeeping'' tasks.@refill
1280
1281@item 2. Summary Description and Copyright
1282The @dfn{Summary Description and Copyright} segment describes the document
1283and contains the copyright notice and copying permissions for the Info
1284file. The segment must be enclosed between @code{@@ifinfo} and
1285@code{@@end ifinfo} commands so that the formatters place it only in the Info
1286file.@refill
1287
1288@item 3. Title and Copyright
1289The @dfn{Title and Copyright} segment contains the title and copyright pages
1290and copying permissions for the printed manual. The segment must be
1291enclosed between @code{@@titlepage} and @code{@@end titlepage} commands.
1292The title and copyright page appear only in the printed @w{manual}.@refill
1293
1294@item 4. `Top' Node and Master Menu
1295The @dfn{Master Menu} contains a complete menu of all the nodes in the whole
1296Info file. It appears only in the Info file, in the `Top' node.@refill
1297
1298@item 5. Body
1299The @dfn{Body} of the document may be structured like a traditional book or
1300encyclopedia or it may be free form.@refill
1301
1302@item 6. End
1303The @dfn{End} contains commands for printing indices and generating
1304the table of contents, and the @code{@@bye} command on a line of its
1305own.@refill
1306@end table
1307
1308@node Short Sample
1309@section A Short Sample Texinfo File
1310@cindex Sample Texinfo file
1311
1312Here is a complete but very short Texinfo file, in six parts. The first
1313three parts of the file, from @samp{\input texinfo} through to
1314@samp{@@end titlepage}, look more intimidating than they are. Most of
1315the material is standard boilerplate; when you write a manual, simply
1316insert the names for your own manual in this segment. (@xref{Beginning a
1317File}.)@refill
1318
1319In the following, the sample text is @emph{indented}; comments on it are
1320not. The complete file, without any comments, is shown in
1321@ref{Sample Texinfo File}.
1322
1323@subheading Part 1: Header
1324
1325@noindent
1326The header does not appear in either the Info file or the
1327printed output. It sets various parameters, including the
1328name of the Info file and the title used in the header.
1329
1330@example
1331@group
1332\input texinfo @@c -*-texinfo-*-
1333@@c %**start of header
1334@@setfilename sample.info
1335@@settitle Sample Document
1336@@setchapternewpage odd
1337@@c %**end of header
1338@end group
1339@end example
1340
1341@subheading Part 2: Summary Description and Copyright
1342
1343@noindent
1344The summary description and copyright segment does not
1345appear in the printed document.
1346
1347@example
1348@group
1349@@ifinfo
1350This is a short example of a complete Texinfo file.
1351
1352Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
1353@@end ifinfo
1354@end group
1355@end example
1356
1357@subheading Part 3: Titlepage and Copyright
1358
1359@noindent
1360The titlepage segment does not appear in the Info file.
1361
1362@example
1363@group
1364@@contents
1365@@titlepage
1366@@sp 10
1367@@title Sample Title
1368@end group
1369
1370@group
1371@@c The following two commands start the copyright page.
1372@@page
1373@@vskip 0pt plus 1filll
1374Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
1375@@end titlepage
1376@end group
1377@end example
1378
1379@subheading Part 4: `Top' Node and Master Menu
1380
1381@noindent
1382The `Top' node contains the master menu for the Info file.
1383Since a printed manual uses a table of contents rather than
1384a menu, the master menu appears only in online output.
1385
1386@example
1387@group
1388@@ifnottex
1389@@node Top
1390@@end ifnottex
1391@end group
1392@end example
1393
1394@example
1395@group
1396@@menu
1397* First Chapter:: The first chapter is the
1398 only chapter in this sample.
1399* Concept Index:: This index has two entries.
1400@@end menu
1401@end group
1402@end example
1403
1404@subheading Part 5: The Body of the Document
1405
1406@noindent
1407The body segment contains all the text of the document, but not the
1408indices or table of contents. This example illustrates a node and a
1409chapter containing an enumerated list.@refill
1410
1411@example
1412@group
1413@@node First Chapter
1414@@chapter First Chapter
1415@@cindex Chapter, first
1416@end group
1417
1418@group
1419This is the contents of the first chapter.
1420@@cindex Another sample index entry
1421@end group
1422
1423@group
1424Here is a numbered list.
1425
1426@@enumerate
1427@@item
1428This is the first item.
1429
1430@@item
1431This is the second item.
1432@@end enumerate
1433@end group
1434
1435@group
1436The @@code@{makeinfo@} command transforms a Texinfo file
1437such as this into an Info file or other output;
1438@@TeX@ typesets it for a printed manual.
1439@end group
1440@end example
1441
1442@subheading Part 6: The End of the Document
1443
1444@noindent
1445The end segment contains commands for generating an index in a node and
1446unnumbered chapter of its own, (usually) for generating the table of
1447contents, and the @code{@@bye} command that marks the end of the
1448document.@refill
1449
1450@example
1451@group
1452@@node Concept Index
1453@@unnumbered Concept Index
1454@end group
1455
1456@group
1457@@printindex cp
1458
1459@@bye
1460@end group
1461@end example
1462
1463@subheading The Results
1464
1465Here is what the contents of the first chapter of the sample look like:
1466
1467@sp 1
1468@need 700
1469@quotation
1470This is the contents of the first chapter.
1471
1472Here is a numbered list.
1473
1474@enumerate
1475@item
1476This is the first item.
1477
1478@item
1479This is the second item.
1480@end enumerate
1481
1482The @code{makeinfo} and @code{texinfo-format-buffer}
1483commands transform a Texinfo file such as this into
1484an Info file; and @TeX{} typesets it for a printed
1485manual.
1486@end quotation
1487
1488
1489@node History
1490@section History
1491
1492@cindex Stallman, Richard M.
1493@cindex Chassell, Robert J.
1494@cindex Berry, Karl
1495Richard M.@: Stallman invented the Texinfo format, wrote the initial
1496processors, and created Edition 1.0 of this manual. @w{Robert J.@:
1497Chassell} greatly revised and extended the manual, starting with Edition
14981.1. Brian Fox was responsible for the standalone Texinfo distribution
1499until version 3.8, and wrote the standalone @command{makeinfo} and
1500@command{info}. Karl Berry has made the updates since Texinfo 3.8 and
1501subsequent releases, starting with Edition 2.22 of the manual.
1502
1503@cindex Pinard, Fran@,{c}ois
1504@cindex Zuhn, David D.
1505@cindex Weisshaus, Melissa
1506@cindex Zaretskii, Eli
1507@cindex Schwab, Andreas
1508@cindex Weinberg, Zack
1509Our thanks go out to all who helped improve this work, particularly to
1510Fran@,{c}ois Pinard and @w{David D.@: Zuhn}, who tirelessly recorded and
1511reported mistakes and obscurities; our special thanks go to Melissa
1512Weisshaus for her frequent and often tedious reviews of nearly similar
1513editions. The indefatigable Eli Zaretskii and Andreas Schwab have
1514provided patches beyond counting. Zack Weinberg did the impossible by
1515implementing the macro syntax in @file{texinfo.tex}. Dozens of others
1516have contributed patches and suggestions, they are gratefully
1517acknowledged in the @file{ChangeLog} file. Our mistakes are our own.
1518
1519@cindex Scribe
1520@cindex Reid, Brian
1521@cindex History of Texinfo
1522A bit of history: in the 1970's at CMU, Brian Reid developed a program
1523and format named Scribe to mark up documents for printing. It used the
1524@code{@@} character to introduce commands as Texinfo does and strived to
1525describe document contents rather than formatting.
1526
1527@cindex Bolio
1528@cindex Bo@TeX{}
1529Meanwhile, people at MIT developed another, not too dissimilar format
1530called Bolio. This then was converted to using @TeX{} as its typesetting
1531language: Bo@TeX{}.
1532
1533Bo@TeX{} could only be used as a markup language for documents to be
1534printed, not for online documents. Richard Stallman (RMS) worked on
1535both Bolio and Bo@TeX{}. He also developed a nifty on-line help format
1536called Info, and then combined Bo@TeX{} and Info to create Texinfo, a
1537mark up language for text that is intended to be read both on line and
1538as printed hard copy.
1539
1540
1541
1542@node Texinfo Mode
1543@chapter Using Texinfo Mode
1544@cindex Texinfo mode
1545@cindex Mode, using Texinfo
1546@cindex GNU Emacs
1547@cindex Emacs
1548
1549You may edit a Texinfo file with any text editor you choose. A Texinfo
1550file is no different from any other @sc{ascii} file. However, GNU Emacs
1551comes with a special mode, called Texinfo
1552mode, that provides Emacs commands and tools to help ease your work.@refill
1553
1554This chapter describes features of GNU Emacs' Texinfo mode but not any
1555features of the Texinfo formatting language. If you are reading this
1556manual straight through from the beginning, you may want to skim through
1557this chapter briefly and come back to it after reading succeeding
1558chapters which describe the Texinfo formatting language in
1559detail.@refill
1560
1561@menu
1562* Texinfo Mode Overview:: How Texinfo mode can help you.
1563* Emacs Editing:: Texinfo mode adds to GNU Emacs' general
1564 purpose editing features.
1565* Inserting:: How to insert frequently used @@-commands.
1566* Showing the Structure:: How to show the structure of a file.
1567* Updating Nodes and Menus:: How to update or create new nodes and menus.
--- 477 unchanged lines hidden (view full) ---
2045Manual}).@refill
2046
2047Also, the @code{texinfo-indent-menu-description} command may be used to
2048indent existing menu descriptions to a specified column. Finally, if
2049you wish, you can use the @code{texinfo-insert-node-lines} command to
2050insert missing @code{@@node} lines into a file. (@xref{Other Updating
2051Commands}, for more information.)@refill
2052
2053@node Updating Requirements, Other Updating Commands, Updating Commands, Updating Nodes and Menus
2054@comment node-name, next, previous, up
2055@subsection Updating Requirements
2056@cindex Updating requirements
2057@cindex Requirements for updating commands
2058
2059To use the updating commands, you must organize the Texinfo file
2060hierarchically with chapters, sections, subsections, and the like.
2061When you construct the hierarchy of the manual, do not `jump down'
2062more than one level at a time: you can follow the `Top' node with a
2063chapter, but not with a section; you can follow a chapter with a
2064section, but not with a subsection. However, you may `jump up' any
2065number of levels at one time---for example, from a subsection to a
2066chapter.@refill
2067
2068Each @code{@@node} line, with the exception of the line for the `Top'
2069node, must be followed by a line with a structuring command such as
2070@code{@@chapter}, @code{@@section}, or
2071@code{@@unnumberedsubsec}.@refill
2072
2073Each @code{@@node} line/structuring-command line combination
2074must look either like this:@refill
2075
2076@example
2077@group
2078@@node Comments, Minimum, Conventions, Overview
2079@@comment node-name, next, previous, up
2080@@section Comments
2081@end group
2082@end example
2083
2084or like this (without the @code{@@comment} line):
2085
2086@example
2087@group
2088@@node Comments, Minimum, Conventions, Overview
2089@@section Comments
2090@end group
2091@end example
2092
2093@noindent
2094In this example, `Comments' is the name of both the node and the
2095section. The next node is called `Minimum' and the previous node is
2096called `Conventions'. The `Comments' section is within the `Overview'
2097node, which is specified by the `Up' pointer. (Instead of an
2098@code{@@comment} line, you may also write an @code{@@ifinfo} line.)@refill
2099
2100If a file has a `Top' node, it must be called @samp{top} or @samp{Top}
2101and be the first node in the file.@refill
2102
2103The menu updating commands create a menu of sections within a chapter,
2104a menu of subsections within a section, and so on. This means that
2105you must have a `Top' node if you want a menu of chapters.@refill
2106
2107Incidentally, the @code{makeinfo} command will create an Info file for a
2108hierarchically organized Texinfo file that lacks `Next', `Previous' and
2109`Up' pointers. Thus, if you can be sure that your Texinfo file will be
2110formatted with @code{makeinfo}, you have no need for the update node
2111commands. (@xref{Creating an Info File}, for more information about
2112@code{makeinfo}.) However, both @code{makeinfo} and the
2113@code{texinfo-format-@dots{}} commands require that you insert menus in
2114the file.
2115
2116@node Other Updating Commands, , Updating Requirements, Updating Nodes and Menus
2117@comment node-name, next, previous, up
2118@subsection Other Updating Commands
2119
2120In addition to the five major updating commands, Texinfo mode
2121possesses several less frequently used updating commands:@refill
2122
2123@table @kbd
2124@item M-x texinfo-insert-node-lines
2125@findex texinfo-insert-node-lines
--- 113 unchanged lines hidden (view full) ---
2239
2240@example
2241C-c C-m C-b
2242@exdent or
2243M-x makeinfo-buffer
2244@end example
2245
2246For @TeX{} or the Info formatting commands to work, the file @emph{must}
2247include a line that has @code{@@setfilename} in its header.@refill
2248
2249@xref{Creating an Info File}, for details about Info formatting.@refill
2250
2251@node Printing, Texinfo Mode Summary, Info Formatting, Texinfo Mode
2252@comment node-name, next, previous, up
2253@section Formatting and Printing
2254@cindex Formatting for printing
2255@cindex Printing a region or buffer
--- 232 unchanged lines hidden (view full) ---
2488@end group
2489
2490@group
2491M-x texinfo-sequential-node-update
2492 @r{Insert node pointers in strict sequence.}
2493@end group
2494@end example
2495
2496@node Beginning a File
2497@chapter Beginning a Texinfo File
2498@cindex Beginning a Texinfo file
2499@cindex Texinfo file beginning
2500@cindex File beginning
2501
2502Certain pieces of information must be provided at the beginning of a
2503Texinfo file, such as the name of the file and the title of the
2504document.@refill
2505
2506@menu
2507* Four Parts:: Four parts begin a Texinfo file.
2508* Sample Beginning:: Here is a sample beginning for a Texinfo file.
2509* Header:: The very beginning of a Texinfo file.
2510* Info Summary and Permissions:: Summary and copying permissions for Info.
2511* Titlepage & Copyright Page:: Creating the title and copyright pages.
2512* The Top Node:: Creating the `Top' node and master menu.
2513* Software Copying Permissions:: Ensure that you and others continue to
2514 have the right to use and share software.
2515@end menu
2516
2517@node Four Parts, Sample Beginning, Beginning a File, Beginning a File
2518@ifinfo
2519@heading Four Parts Begin a File
2520@end ifinfo
2521
2522Generally, the beginning of a Texinfo file has four parts:@refill
2523
2524@enumerate
2525@item
2526The header, delimited by special comment lines, that includes the
2527commands for naming the Texinfo file and telling @TeX{} what
2528definitions file to use when processing the Texinfo file.@refill
2529
2530@item
2531A short statement of what the file is about, with a copyright notice
2532and copying permissions. This is enclosed in @code{@@ifinfo} and
2533@code{@@end ifinfo} commands so that the formatters place it only
2534in the Info file.@refill
2535
2536@item
2537A title page and copyright page, with a copyright notice and copying
2538permissions. This is enclosed between @code{@@titlepage} and
2539@code{@@end titlepage} commands. The title and copyright page appear
2540only in the printed @w{manual}.@refill
2541
2542@item
2543The `Top' node that contains a menu for the whole Info file. The
2544contents of this node appear only in the Info file.@refill
2545@end enumerate
2546
2547Also, optionally, you may include the copying conditions for a program
2548and a warranty disclaimer. The copying section will be followed by an
2549introduction or else by the first chapter of the manual.@refill
2550
2551Since the copyright notice and copying permissions for the Texinfo
2552document (in contrast to the copying permissions for a program) are in
2553parts that appear only in the Info file or only in the printed manual,
2554this information must be given twice.@refill
2555
2556
2557@node Sample Beginning
2558@section Sample Texinfo File Beginning
2559
2560The following sample shows what is needed.@refill
2561
2562@example
2563\input texinfo @@c -*-texinfo-*-
2564@@c %**start of header
2565@@setfilename @var{name-of-info-file}
2566@@settitle @var{name-of-manual}
2567@@setchapternewpage odd
2568@@c %**end of header
2569
2570@@ifinfo
2571This file documents @dots{}
2572
2573Copyright @var{year} @var{copyright-owner}
2574
2575@group
2576Permission is granted to @dots{}
2577@@end ifinfo
2578@end group
2579
2580@group
2581@@c This title page illustrates only one of the
2582@@c two methods of forming a title page.
2583@end group
2584
2585@group
2586@@titlepage
2587@@title @var{name-of-manual-when-printed}
2588@@subtitle @var{subtitle-if-any}
2589@@subtitle @var{second-subtitle}
2590@@author @var{author}
2591@end group
2592
2593@group
2594@@c The following two commands
2595@@c start the copyright page.
2596@@page
2597@@vskip 0pt plus 1filll
2598Copyright @@copyright@{@} @var{year} @var{copyright-owner}
2599@end group
2600
2601Published by @dots{}
2602
2603Permission is granted to @dots{}
2604@@end titlepage
2605
2606@@ifnottex
2607@@node Top
2608@@top @var{title}
2609
2610This document describes @dots{}
2611
2612This document applies to version @dots{}
2613of the program named @dots{}
2614@@end ifnottex
2615
2616@group
2617@@menu
2618* Copying:: Your rights and freedoms.
2619* First Chapter:: Getting started @dots{}
2620* Second Chapter:: @dots{}
2621 @dots{}
2622 @dots{}
2623@@end menu
2624@end group
2625
2626@group
2627@@node First Chapter
2628@@chapter First Chapter
2629@@cindex Index entry for First Chapter
2630@end group
2631@end example
2632
2633
2634@node Header
2635@section The Texinfo File Header
2636@cindex Header for Texinfo files
2637@cindex Texinfo file header
2638
2639Texinfo files start with at least three lines that provide Info and
2640@TeX{} with necessary information. These are the @code{\input texinfo}
2641line, the @code{@@settitle} line, and the @code{@@setfilename} line. If
2642you want to run @TeX{} on just a part of the Texinfo file, you must
2643write the @code{@@settitle} and @code{@@setfilename} lines between
2644start-of-header and end-of-header lines.
2645
2646Thus, the beginning of a Texinfo file looks like this:
2647
2648@example
2649@group
2650\input texinfo @@c -*-texinfo-*-
2651@@setfilename sample.info
2652@@settitle Sample Document
2653@end group
2654@end example
2655
2656@noindent
2657or else like this:
2658
2659@example
2660@group
2661\input texinfo @@c -*-texinfo-*-
2662@@c %**start of header
2663@@setfilename sample.info
2664@@settitle Sample Document
2665@@c %**end of header
2666@end group
2667@end example
2668
2669@menu
2670* First Line:: The first line of a Texinfo file.
2671* Start of Header:: Formatting a region requires this.
2672* setfilename:: Tell Info the name of the Info file.
2673* settitle:: Create a title for the printed work.
2674* documentdescription:: Document summary for the HTML output.
2675* setchapternewpage:: Start chapters on right-hand pages.
2676* paragraphindent:: Specify paragraph indentation.
2677* exampleindent:: Specify environment indentation.
2678* End of Header:: Formatting a region requires this.
2679@end menu
2680
2681
2682@node First Line
2683@subsection The First Line of a Texinfo File
2684@cindex First line of a Texinfo file
2685@cindex Beginning line of a Texinfo file
2686@cindex Header of a Texinfo file
2687
2688Every Texinfo file that is to be the top-level input to @TeX{} must begin
2689with a line that looks like this:@refill
2690
2691@example
2692\input texinfo @@c -*-texinfo-*-
2693@end example
2694
2695@noindent
2696This line serves two functions:
2697
2698@enumerate
2699@item
2700When the file is processed by @TeX{}, the @samp{\input texinfo} command
2701tells @TeX{} to load the macros needed for processing a Texinfo file.
2702These are in a file called @file{texinfo.tex}, which is usually located
2703in the @file{/usr/lib/tex/macros} directory. @TeX{} uses the backslash,
2704@samp{\}, to mark the beginning of a command, just as Texinfo uses
2705@samp{@@}. The @file{texinfo.tex} file causes the switch from @samp{\}
2706to @samp{@@}; before the switch occurs, @TeX{} requires @samp{\}, which
2707is why it appears at the beginning of the file.@refill
2708
2709@item
2710When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode
2711specification tells Emacs to use Texinfo mode.@refill
2712@end enumerate
2713
2714
2715@node Start of Header
2716@subsection Start of Header
2717@cindex Start of header line
2718
2719Write a start-of-header line on the second line of a Texinfo file.
2720Follow the start-of-header line with @code{@@setfilename} and
2721@code{@@settitle} lines and, optionally, with other command lines, such
2722as @code{@@smallbook} or @code{@@footnotestyle}; and then by an
2723end-of-header line (@pxref{End of Header}).@refill
2724
2725With these lines, you can format part of a Texinfo file for Info or
2726typeset part for printing.@refill
2727
2728A start-of-header line looks like this:@refill
2729
2730@example
2731@@c %**start of header
2732@end example
2733
2734The odd string of characters, @samp{%**}, is to ensure that no other
2735comment is accidentally taken for a start-of-header line.@refill
2736
2737@node setfilename
2738@subsection @code{@@setfilename}
2739@cindex Info file requires @code{@@setfilename}
2740@findex setfilename
2741
2742In order to serve as the primary input file for either @code{makeinfo}
2743or @TeX{}, a Texinfo file must contain a line that looks like this:
2744
2745@example
2746@@setfilename @var{info-file-name}
2747@end example
2748
2749Write the @code{@@setfilename} command at the beginning of a line and
2750follow it on the same line by the Info file name. Do not write anything
2751else on the line; anything on the line after the command is considered
2752part of the file name, including what would otherwise be a
2753comment.
2754
2755The @code{@@setfilename} line specifies the name of the output file to
2756be generated. This name should be different from the name of the
2757Texinfo file. There are two conventions for choosing the name: you can
2758either remove the extension (such as @samp{.texi}) from the input file
2759name, or replace it with the @samp{.info} extension. When producing
2760HTML output, @code{makeinfo} will replace any extension with
2761@samp{html}, or add @samp{.html} if the given name has no extension.
2762
2763Some operating systems cannot handle long file names. You can run into
2764a problem even when the file name you specify is itself short enough.
2765This occurs because the Info formatters split a long Info file into
2766short indirect subfiles, and name them by appending @samp{-1},
2767@samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original
2768file name. (@xref{Tag and Split Files, , Tag Files and Split Files}.)
2769The subfile name @file{texinfo.info-10}, for example, is too long for
2770some systems; so the Info file name for this document is @file{texinfo}
2771rather than @file{texinfo.info}. When @code{makeinfo} is running on
2772operating systems such as MS-DOS which impose grave limits on file
2773names, it will sometimes remove some characters from the original file
2774name to leave enough space for the subfile suffix, thus producing files
2775named @file{texin-10}, @file{gcc.i12}, etc.
2776
2777@cindex Ignored before @code{@@setfilename}
2778@cindex @samp{\input} source line ignored
2779The Info formatting commands ignore everything written before the
2780@code{@@setfilename} line, which is why the very first line of
2781the file (the @code{\input} line) does not show up in the output.
2782
2783@pindex texinfo.cnf
2784The @code{@@setfilename} line produces no output when you typeset a
2785manual with @TeX{}, but it is nevertheless essential: it opens the
2786index, cross-reference, and other auxiliary files used by Texinfo, and
2787also reads @file{texinfo.cnf} if that file is present on your system
2788(@pxref{Preparing for TeX,, Preparing for @TeX{}}).
2789
--- 4 unchanged lines hidden (view full) ---
2794
2795In order to be made into a printed manual, a Texinfo file must contain
2796a line that looks like this:
2797
2798@example
2799@@settitle @var{title}
2800@end example
2801
2802In the HTML file produced by @command{makeinfo}, @var{title} serves as
2803the default document description in the @samp{<head>} part; see
2804@ref{documentdescription}, for how to change that.
2805
2806Write the @code{@@settitle} command at the beginning of a line and
2807follow it on the same line by the title. This tells @TeX{} the title
2808to use in a header or footer. Do not write anything else on the line;
2809anything on the line after the command is considered part of the
2810title, including a comment.@refill
2811
2812Conventionally, when @TeX{} formats a Texinfo file for double-sided
2813output, the title is printed in the left-hand (even-numbered) page
2814headings and the current chapter title is printed in the right-hand
2815(odd-numbered) page headings. (@TeX{} learns the title of each chapter
2816from each @code{@@chapter} command.) Page footers are not
2817printed.@refill
2818
2819Even if you are printing in a single-sided style, @TeX{} looks for an
2820@code{@@settitle} command line, in case you include the manual title
2821in the heading. @refill
2822
2823The @code{@@settitle} command should precede everything that generates
2824actual output in @TeX{}.@refill
2825
2826Although the title in the @code{@@settitle} command is usually the
2827same as the title on the title page, it does not affect the title as
2828it appears on the title page. Thus, the two do not need not match
2829exactly; and the title in the @code{@@settitle} command can be a
2830shortened or expanded version of the title as it appears on the title
2831page. (@xref{titlepage, , @code{@@titlepage}}.)@refill
2832
2833@TeX{} prints page headings only for that text that comes after the
2834@code{@@end titlepage} command in the Texinfo file, or that comes
2835after an @code{@@headings} command that turns on headings.
2836(@xref{headings on off, , The @code{@@headings} Command}, for more
2837information.)@refill
2838
2839You may, if you wish, create your own, customized headings and
2840footings. @xref{Headings, , Page Headings}, for a detailed discussion
2841of this process.@refill
2842
2843
2844@node documentdescription
2845@subsection @code{@@documentdescription}: Summary text
2846@cindex Document description
2847@cindex Description of document
2848@cindex Summary of document
2849@cindex <meta> HTML tag, and document description
2850
2851When producing HTML output for a document, @command{makeinfo} writes a
2852@samp{<meta>} element in the @samp{<head>} to give some idea of the
2853content of the document. By default, this @dfn{description} is the title
2854of the document, taken from the @code{@@settitle} command
2855(@pxref{settitle}). To change this, use the @code{@@documentdescription}
2856environment, as in:
2857
2858@example
2859@@documentdescription
2860descriptive text
2861@@end documendescription
2862@end example
2863
2864@noindent
2865This will produce the following output in the @samp{<head>} of the HTML:
2866
2867@example
2868<meta name=description content="descriptive text">
2869@end example
2870
2871@code{@@documentdescription} must be specified before the first node of
2872the document.
2873
2874
2875@findex documentdescription
2876@node setchapternewpage
2877@subsection @code{@@setchapternewpage}:
2878@cindex Starting chapters
2879@cindex Pages, starting odd
2880@findex setchapternewpage
2881
2882In an officially bound book, text is usually printed on both sides of
2883the paper, chapters start on right-hand pages, and right-hand pages have
2884odd numbers. But in short reports, text often is printed only on one
2885side of the paper. Also in short reports, chapters sometimes do not
2886start on new pages, but are printed on the same page as the end of the
2887preceding chapter, after a small amount of vertical whitespace.
2888
2889You can use the @code{@@setchapternewpage} command with various
2890arguments to specify how @TeX{} should start chapters and whether it
2891should format headers for printing on one or both sides of the paper
2892(single-sided or double-sided printing).
2893
2894Write the @code{@@setchapternewpage} command at the beginning of a
2895line followed by its argument.
2896
2897For example, you would write the following to cause each chapter to
2898start on a fresh odd-numbered page:
2899
2900@example
2901@@setchapternewpage odd
2902@end example
2903
2904You can specify one of three alternatives with the
2905@code{@@setchapternewpage} command:
2906
2907@table @asis
2908
2909@item @code{@@setchapternewpage off}
2910Cause @TeX{} to typeset a new chapter on the same page as the last
2911chapter, after skipping some vertical whitespace. Also, cause @TeX{} to
2912format page headers for single-sided printing.
2913
2914@item @code{@@setchapternewpage on}
2915Cause @TeX{} to start new chapters on new pages and to format page
2916headers for single-sided printing. This is the form most often used for
2917short reports or personal printing. This is the default.
2918
2919@item @code{@@setchapternewpage odd}
2920Cause @TeX{} to start new chapters on new, odd-numbered pages
2921(right-handed pages) and to typeset for double-sided printing. This is
2922the form most often used for books and manuals.
2923@end table
2924
2925Texinfo does not have an @code{@@setchapternewpage even} command,
2926because there is no printing tradition of starting chapters or books on
2927an even-numbered page.
2928
2929If you don't like the default headers that @code{@@setchapternewpage}
2930sets, you can explicit control them with the @code{@@headings} command.
2931@xref{headings on off, , The @code{@@headings} Command}.
2932
2933At the beginning of a manual or book, pages are not numbered---for
2934example, the title and copyright pages of a book are not numbered. By
2935convention, table of contents and frontmatter pages are numbered with
2936roman numerals and not in sequence with the rest of the document.
2937
2938Since an Info file does not have pages, the @code{@@setchapternewpage}
2939command has no effect on it.
2940
2941We recommend not including any @code{@@setchapternewpage} command in
2942your manual sources at all, since the desired output is not intrinsic to
2943the document. Instead, if you don't want the default option (no blank
2944pages, same headers on all pages) use the @option{--texinfo} option to
2945@command{texi2dvi} to specify the output you want.
2946
2947
2948
2949@node paragraphindent
2950@subsection Paragraph Indenting
2951@cindex Indenting paragraphs
2952@cindex Paragraph indentation
2953@findex paragraphindent
2954
2955The Texinfo processors may insert whitespace at the beginning of the
2956first line of each paragraph, thereby indenting that paragraph. You can
2957use the @code{@@paragraphindent} command to specify this indentation.
2958Write an @code{@@paragraphindent} command at the beginning of a line
2959followed by either @samp{asis} or a number:
2960
2961@example
2962@@paragraphindent @var{indent}
2963@end example
2964
2965The indentation is according to the value of @var{indent}:
2966
2967@table @asis
2968@item @code{asis}
2969Do not change the existing indentation (not implemented in @TeX{}).
2970
2971@item 0
2972Omit all indentation.
2973
2974@item @var{n}
2975Indent by @var{n} space characters in Info output, by @var{n} ems in
2976@TeX{}.
2977
2978@end table
2979
2980The default value of @var{indent} is @samp{asis}.
2981@code{@@paragraphindent} is ignored for HTML output.
2982
2983Write the @code{@@paragraphindent} command before or shortly after the
2984end-of-header line at the beginning of a Texinfo file. (If you write
2985the command between the start-of-header and end-of-header lines, the
2986region formatting commands indent paragraphs as specified.)
2987
2988A peculiarity of the @code{texinfo-format-buffer} and
2989@code{texinfo-format-region} commands is that they do not indent (nor
2990fill) paragraphs that contain @code{@@w} or @code{@@*} commands.
2991@xref{Refilling Paragraphs}, for further information.
2992
2993
2994@node exampleindent
2995@subsection @code{@@exampleindent}: Environment Indenting
2996@cindex Indenting environments
2997@cindex Environment indentation
2998@cindex Example indentation
2999@findex exampleindent
3000
3001The Texinfo processors indent each line of @code{@@example} and similar
3002environments. You can use the @code{@@exampleindent} command to specify
3003this indentation. Write an @code{@@exampleindent} command at the
3004beginning of a line followed by either @samp{asis} or a number:
3005
3006@example
3007@@exampleindent @var{indent}
3008@end example
3009
3010The indentation is according to the value of @var{indent}:
3011
3012@table @asis
3013@item @code{asis}
3014Do not change the existing indentation (not implemented in @TeX{}).
3015
3016@item 0
3017Omit all indentation.
3018
3019@item @var{n}
3020Indent environments by @var{n} space characters in Info output, by
3021@var{n} ems in @TeX{}.
3022
3023@end table
3024
3025The default value of @var{indent} is 5. @code{@@exampleindent} is
3026ignored for HTML output.
3027
3028Write the @code{@@exampleindent} command before or shortly after the
3029end-of-header line at the beginning of a Texinfo file. (If you write
3030the command between the start-of-header and end-of-header lines, the
3031region formatting commands indent examples as specified.)
3032
3033
3034@node End of Header
3035@subsection End of Header
3036@cindex End of header line
3037
3038Follow the header lines with an @w{end-of-header} line.
3039An end-of-header line looks like this:@refill
3040
3041@example
3042@@c %**end of header
3043@end example
3044
3045If you include the @code{@@setchapternewpage} command between the
3046start-of-header and end-of-header lines, @TeX{} will typeset a region as
3047that command specifies. Similarly, if you include an @code{@@smallbook}
3048command between the start-of-header and end-of-header lines, @TeX{} will
3049typeset a region in the ``small'' book format.@refill
3050
3051@ifinfo
3052The reason for the odd string of characters (@samp{%**}) is so that the
3053@code{texinfo-tex-region} command does not accidentally find
3054something that it should not when it is looking for the header.@refill
3055
3056The start-of-header line and the end-of-header line are Texinfo mode
3057variables that you can change.@refill
3058@end ifinfo
3059
3060@iftex
3061@xref{Start of Header}.
3062@end iftex
3063
3064
3065@node Info Summary and Permissions
3066@section Summary and Copying Permissions for Info
3067
3068The title page and the copyright page appear only in the printed copy of
3069the manual; therefore, the same information must be inserted in a
3070section that appears only in the Info file. This section usually
3071contains a brief description of the contents of the Info file, a
3072copyright notice, and copying permissions.@refill
3073
3074The copyright notice should read:
3075
3076@example
3077Copyright @var{year} @var{copyright-owner}
3078@end example
3079
3080@noindent
3081and be put on a line by itself.
3082
3083Standard text for the copyright permissions of free manuals is contained
3084in an appendix to this manual (@pxref{Documentation Copying, , GNU Free
3085Documentation License}).
3086
3087The permissions text appears in an Info file @emph{before} the first
3088node. This mean that a reader does @emph{not} see this text when
3089reading the file using Info (except when using the advanced Info command
3090@kbd{g *}).
3091
3092
3093@node Titlepage & Copyright Page
3094@section The Title and Copyright Pages
3095
3096A manual's name and author are usually printed on a title page.
3097Sometimes copyright information is printed on the title page as well;
3098more often, copyright information is printed on the back of the title
3099page.
3100
3101The title and copyright pages appear in the printed manual, but not in the
3102Info file. Because of this, it is possible to use several slightly
3103obscure @TeX{} typesetting commands that cannot be used in an Info file.
3104In addition, this part of the beginning of a Texinfo file contains the text
3105of the copying permissions that will appear in the printed manual.@refill
3106
3107@cindex Titlepage, for plain text
3108You may wish to include titlepage-like information for plain text
3109output. Simply place any such leading material between @code{@@ifinfo}
3110and @code{@@end ifinfo}; @command{makeinfo} includes this in its plain
3111text output. It will not show up in the Info readers.
3112
3113@xref{Documentation Copying, , GNU Free Documentation License}, for the
3114standard text for the copyright permissions.
3115
3116@menu
3117* titlepage:: Create a title for the printed document.
3118* titlefont center sp:: The @code{@@titlefont}, @code{@@center},
3119 and @code{@@sp} commands.
3120* title subtitle author:: The @code{@@title}, @code{@@subtitle},
3121 and @code{@@author} commands.
3122* Copyright & Permissions:: How to write the copyright notice and
3123 include copying permissions.
3124* end titlepage:: Turn on page headings after the title and
3125 copyright pages.
3126* headings on off:: An option for turning headings on and off
3127 and double or single sided printing.
3128@end menu
3129
3130
3131@node titlepage, titlefont center sp, Titlepage & Copyright Page, Titlepage & Copyright Page
3132@comment node-name, next, previous, up
3133@subsection @code{@@titlepage}
3134@cindex Title page
3135@findex titlepage
3136
3137Start the material for the title page and following copyright page
3138with @code{@@titlepage} on a line by itself and end it with
3139@code{@@end titlepage} on a line by itself.@refill
3140
3141The @code{@@end titlepage} command starts a new page and turns on page
3142numbering. (@xref{Headings, , Page Headings}, for details about how to
3143generate page headings.) All the material that you want to appear on
3144unnumbered pages should be put between the @code{@@titlepage} and
3145@code{@@end titlepage} commands. You can force the table of contents to
3146appear there with the @code{@@setcontentsaftertitlepage} command
3147(@pxref{Contents}).
--- 5 unchanged lines hidden (view full) ---
3153the copyright page is produced. (The @code{@@titlepage} command might
3154perhaps have been better named the @code{@@titleandadditionalpages}
3155command, but that would have been rather long!)
3156
3157When you write a manual about a computer program, you should write the
3158version of the program to which the manual applies on the title page.
3159If the manual changes more frequently than the program or is independent
3160of it, you should also include an edition number@footnote{We have found
3161that it is helpful to refer to versions of manuals as `editions' and
3162versions of programs as `versions'; otherwise, we find we are liable to
3163confuse each other in conversation by referring to both the
3164documentation and the software with the same words.} for the manual.
3165This helps readers keep track of which manual is for which version of
3166the program. (The `Top' node should also contain this information; see
3167@ref{makeinfo top, , @code{@@top}}.)
3168
3169Texinfo provides two main methods for creating a title page. One method
3170uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands
3171to generate a title page in which the words on the page are
3172centered.
3173
3174The second method uses the @code{@@title}, @code{@@subtitle}, and
3175@code{@@author} commands to create a title page with black rules under
--- 5 unchanged lines hidden (view full) ---
3181You may use either method, or you may combine them; see the examples in
3182the sections below.
3183
3184@findex shorttitlepage
3185@cindex Bastard title page
3186@cindex Title page, bastard
3187For extremely simple applications, and for the bastard title page in
3188traditional book front matter, Texinfo also provides a command
3189@code{@@shorttitlepage} which takes a single argument as the title. The
3190argument is typeset on a page by itself and followed by a blank page.
3191
3192
3193@node titlefont center sp
3194@subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp}
3195@findex titlefont
3196@findex center
3197@findex sp @r{(titlepage line spacing)}
3198
3199You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center}
3200commands to create a title page for a printed document. (This is the
3201first of the two methods for creating a title page in Texinfo.)@refill
3202
3203Use the @code{@@titlefont} command to select a large font suitable for
3204the title itself. You can use @code{@@titlefont} more than once if you
3205have an especially long title.
3206
3207@need 700
3208For example:
3209
3210@example
3211@@titlefont@{Texinfo@}
3212@end example
3213
3214Use the @code{@@center} command at the beginning of a line to center
3215the remaining text on that line. Thus,@refill
3216
3217@example
3218@@center @@titlefont@{Texinfo@}
3219@end example
3220
3221@noindent
3222centers the title, which in this example is ``Texinfo'' printed
3223in the title font.@refill
3224
3225Use the @code{@@sp} command to insert vertical space. For example:@refill
3226
3227@example
3228@@sp 2
3229@end example
3230
3231@noindent
3232This inserts two blank lines on the printed page. (@xref{sp, ,
3233@code{@@sp}}, for more information about the @code{@@sp}
3234command.)@refill
3235
3236A template for this method looks like this:@refill
3237
3238@example
3239@group
3240@@titlepage
3241@@sp 10
3242@@center @@titlefont@{@var{name-of-manual-when-printed}@}
3243@@sp 2
3244@@center @var{subtitle-if-any}
3245@@sp 2
3246@@center @var{author}
3247@dots{}
3248@@end titlepage
3249@end group
3250@end example
3251
3252The spacing of the example fits an 8.5 by 11 inch manual.@refill
3253
3254
3255@node title subtitle author
3256@subsection @code{@@title}, @code{@@subtitle}, and @code{@@author}
3257@findex title
3258@findex subtitle
3259@findex author
3260
3261You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author}
3262commands to create a title page in which the vertical and horizontal
3263spacing is done for you automatically. This contrasts with the method
3264described in the previous section, in which the @code{@@sp} command is
3265needed to adjust vertical spacing.
3266
3267Write the @code{@@title}, @code{@@subtitle}, or @code{@@author}
3268commands at the beginning of a line followed by the title, subtitle,
3269or author.@refill
3270
3271The @code{@@title} command produces a line in which the title is set
3272flush to the left-hand side of the page in a larger than normal font.
3273The title is underlined with a black rule. Only a single line is
3274allowed; the @code{@@*} command may not be used to break the title into
3275two lines. To handle very long titles, you may find it profitable to
3276use both @code{@@title} and @code{@@titlefont}; see the final example in
3277this section.
3278
3279The @code{@@subtitle} command sets subtitles in a normal-sized font
3280flush to the right-hand side of the page.@refill
3281
3282The @code{@@author} command sets the names of the author or authors in
3283a middle-sized font flush to the left-hand side of the page on a line
3284near the bottom of the title page. The names are underlined with a
3285black rule that is thinner than the rule that underlines the title.
3286(The black rule only occurs if the @code{@@author} command line is
3287followed by an @code{@@page} command line.)@refill
3288
3289There are two ways to use the @code{@@author} command: you can write
3290the name or names on the remaining part of the line that starts with
3291an @code{@@author} command:@refill
3292
3293@example
3294@@author by Jane Smith and John Doe
3295@end example
3296
3297@noindent
3298or you can write the names one above each other by using two (or more)
3299@code{@@author} commands:@refill
3300
3301@example
3302@group
3303@@author Jane Smith
3304@@author John Doe
3305@end group
3306@end example
3307
3308@noindent
3309(Only the bottom name is underlined with a black rule.)@refill
3310
3311@need 950
3312A template for this method looks like this:@refill
3313
3314@example
3315@group
3316@@titlepage
3317@@title @var{name-of-manual-when-printed}
3318@@subtitle @var{subtitle-if-any}
3319@@subtitle @var{second-subtitle}
3320@@author @var{author}
--- 15 unchanged lines hidden (view full) ---
3336@@title for MS-Windows and MS-DOS
3337@@subtitle Edition @@value@{e@} for Release @@value@{cde@}
3338@@author by Daniel Hagerty, Melissa Weisshaus
3339@@author and Eli Zaretskii
3340@end group
3341@end example
3342
3343@noindent
3344(The use of @code{@@value} here is explained in @ref{value
3345Example,,@code{@@value} Example}.)
3346
3347
3348@node Copyright & Permissions
3349@subsection Copyright Page and Permissions
3350@cindex Copyright page
3351@cindex Printed permissions
3352@cindex Permissions, printed
3353
3354By international treaty, the copyright notice for a book should be
3355either on the title page or on the back of the title page. The
3356copyright notice should include the year followed by the name of the
3357organization or person who owns the copyright.@refill
3358
3359When the copyright notice is on the back of the title page, that page
3360is customarily not numbered. Therefore, in Texinfo, the information
3361on the copyright page should be within @code{@@titlepage} and
3362@code{@@end titlepage} commands.@refill
3363
3364@findex vskip
3365@findex filll
3366@cindex Vertical whitespace (@samp{vskip})
3367Use the @code{@@page} command to cause a page break. To push the
3368copyright notice and the other text on the copyright page towards the
3369bottom of the page, you can write a somewhat mysterious line after the
3370@code{@@page} command that reads like this:@refill
3371
3372@example
3373@@vskip 0pt plus 1filll
3374@end example
3375
3376@noindent
3377This is a @TeX{} command that is not supported by the Info formatting
3378commands. The @code{@@vskip} command inserts whitespace. The
3379@samp{0pt plus 1filll} means to put in zero points of mandatory whitespace,
3380and as much optional whitespace as needed to push the
3381following text to the bottom of the page. Note the use of three
3382@samp{l}s in the word @samp{filll}; this is the correct usage in
3383@TeX{}.@refill
3384
3385@findex copyright
3386In a printed manual, the @code{@@copyright@{@}} command generates a
3387@samp{c} inside a circle. (In Info, it generates @samp{(C)}.) The
3388copyright notice itself has the following legally defined sequence:@refill
3389
3390@example
3391Copyright @copyright{} @var{year} @var{copyright-owner}
3392@end example
3393
3394It is customary to put information on how to get a manual after the
3395copyright notice, followed by the copying permissions for the manual.
3396
3397Permissions must be given here as well as in the summary segment within
3398@code{@@ifinfo} and @code{@@end ifinfo} that immediately follows the
3399header since this text appears only in the printed manual and the
3400@samp{ifinfo} text appears only in the Info file.
3401
3402@xref{Documentation Copying,,GNU Free Documentation License}, for the
3403standard text.
3404
3405
3406@node end titlepage
3407@subsection Heading Generation
3408@findex end titlepage
3409@cindex Headings, page, begin to appear
3410@cindex Titlepage end starts headings
3411@cindex End titlepage starts headings
3412
3413An @code{@@end titlepage} command on a line by itself not only marks
3414the end of the title and copyright pages, but also causes @TeX{} to start
3415generating page headings and page numbers.
3416
3417To repeat what is said elsewhere, Texinfo has two standard page heading
3418formats, one for documents which are printed on one side of each sheet of paper
3419(single-sided printing), and the other for documents which are printed on both
3420sides of each sheet (double-sided printing).
3421(@xref{setchapternewpage, ,@code{@@setchapternewpage}}.)
3422You can specify these formats in different ways:@refill
3423
3424@itemize @bullet
3425@item
3426The conventional way is to write an @code{@@setchapternewpage} command
3427before the title page commands, and then have the @code{@@end
3428titlepage} command start generating page headings in the manner desired.
3429(@xref{setchapternewpage, , @code{@@setchapternewpage}}.)@refill
3430
3431@item
3432Alternatively, you can use the @code{@@headings} command to prevent page
3433headings from being generated or to start them for either single or
3434double-sided printing. (Write an @code{@@headings} command immediately
3435after the @code{@@end titlepage} command. @xref{headings on off, , The
3436@code{@@headings} Command}, for more information.)@refill
3437
3438@item
3439Or, you may specify your own page heading and footing format.
3440@xref{Headings, , Page Headings}, for detailed
3441information about page headings and footings.@refill
3442@end itemize
3443
3444Most documents are formatted with the standard single-sided or
3445double-sided format, using @code{@@setchapternewpage odd} for
3446double-sided printing and no @code{@@setchapternewpage} command for
3447single-sided printing.@refill
3448
3449@node headings on off, , end titlepage, Titlepage & Copyright Page
3450@comment node-name, next, previous, up
3451@subsection The @code{@@headings} Command
3452@findex headings
3453
3454The @code{@@headings} command is rarely used. It specifies what kind of
3455page headings and footings to print on each page. Usually, this is
3456controlled by the @code{@@setchapternewpage} command. You need the
3457@code{@@headings} command only if the @code{@@setchapternewpage} command
3458does not do what you want, or if you want to turn off pre-defined page
--- 48 unchanged lines hidden (view full) ---
3507headings.@refill
3508
3509You can also specify your own style of page heading and footing.
3510@xref{Headings, , Page Headings}, for more information.@refill
3511
3512
3513@node The Top Node
3514@section The `Top' Node and Master Menu
3515@cindex @samp{@r{Top}} node
3516@cindex Master menu
3517@cindex Node, `Top'
3518
3519The `Top' node is the node from which you enter an Info file.@refill
3520
3521A `Top' node should contain a brief description of the Info file and an
3522extensive, master menu for the whole Info file.
3523This helps the reader understand what the Info file is
3524about. Also, you should write the version number of the program to
3525which the Info file applies; or, at least, the edition number.@refill
3526
3527The contents of the `Top' node should appear only in the Info file; none
3528of it should appear in printed output, so enclose it between
3529@code{@@ifinfo} and @code{@@end ifinfo} commands. (@TeX{} does not
3530print either an @code{@@node} line or a menu; they appear only in Info;
3531strictly speaking, you are not required to enclose these parts between
3532@code{@@ifinfo} and @code{@@end ifinfo}, but it is simplest to do so.
3533@xref{Conditionals, , Conditionally Visible Text}.)@refill
3534
3535@menu
3536* Title of Top Node:: Sketch what the file is about.
3537* Master Menu Parts:: A master menu has three or more parts.
3538@end menu
3539
3540
3541@node Title of Top Node
3542@subsection `Top' Node Title
3543
3544Sometimes, you will want to place an @code{@@top} sectioning command
3545line containing the title of the document immediately after the
3546@code{@@node Top} line (@pxref{makeinfo top command, , The @code{@@top}
3547Sectioning Command}, for more information).@refill
3548
3549For example, the beginning of the Top node of this manual contains an
3550@code{@@top} sectioning command, a short description, and edition and
3551version information. It looks like this:@refill
3552
3553@example
3554@group
3555@dots{}
3556@@end titlepage
3557
3558@@ifnottex
3559@@node Top, Copying, , (dir)
3560@@top Texinfo
3561
3562Texinfo is a documentation system@dots{}
3563@end group
3564
3565@group
3566This is edition@dots{}
3567@dots{}
3568@@end ifnottex
3569@end group
3570
3571@group
3572@@menu
3573* Copying:: Texinfo is freely
3574 redistributable.
3575* Overview:: What is Texinfo?
3576@dots{}
3577@end group
3578@@end menu
3579@end example
3580
3581In a `Top' node, the `Previous', and `Up' nodes usually refer to the top
3582level directory of the whole Info system, which is called @samp{(dir)}.
3583The `Next' node refers to the first node that follows the main or master
3584menu, which is usually the copying permissions, introduction, or first
3585chapter.@refill
3586
3587@node Master Menu Parts, , Title of Top Node, The Top Node
3588@subsection Parts of a Master Menu
3589@cindex Master menu parts
3590@cindex Parts of a master menu
3591
3592A @dfn{master menu} is a detailed main menu listing all the nodes in a
3593file.
3594
3595A master menu is enclosed in @code{@@menu} and @code{@@end menu}
3596commands and does not appear in the printed document.@refill
3597
3598Generally, a master menu is divided into parts.@refill
3599
3600@itemize @bullet
3601@item
3602The first part contains the major nodes in the Texinfo file: the nodes
3603for the chapters, chapter-like sections, and the appendices.@refill
3604
3605@item
3606The second part contains nodes for the indices.@refill
3607
3608@item
3609The third and subsequent parts contain a listing of the other, lower
3610level nodes, often ordered by chapter. This way, rather than go
3611through an intermediary menu, an inquirer can go directly to a
3612particular node when searching for specific information. These menu
3613items are not required; add them if you think they are a
3614convenience. If you do use them, put @code{@@detailmenu} before the
3615first one, and @code{@@end detailmenu} after the last; otherwise,
3616@code{makeinfo} will get confused.
3617@end itemize
3618
3619Each section in the menu can be introduced by a descriptive line. So
3620long as the line does not begin with an asterisk, it will not be
3621treated as a menu entry. (@xref{Writing a Menu}, for more
3622information.)@refill
3623
3624For example, the master menu for this manual looks like the following
3625(but has many more entries):@refill
3626
3627@example
3628@group
3629@@menu
3630* Copying:: Texinfo is freely
3631 redistributable.
3632* Overview:: What is Texinfo?
3633* Texinfo Mode:: Special features in GNU Emacs.
3634@dots{}
3635@dots{}
3636@end group
3637@group
3638* Command and Variable Index::
3639 An entry for each @@-command.
3640* Concept Index:: An entry for each concept.
3641@end group
3642
3643@group
3644@@detailmenu
3645 --- The Detailed Node Listing ---
3646
3647Overview of Texinfo
3648
3649* Info Files:: What is an Info file?
3650* Printed Manuals:: Characteristics of
3651 a printed manual.
3652@dots{}
3653@dots{}
3654@end group
3655
3656@group
3657Using Texinfo Mode
3658
3659* Info on a Region:: Formatting part of a file
3660 for Info.
3661@dots{}
3662@dots{}
3663@@end detailmenu
3664@@end menu
3665@end group
3666@end example
3667
3668@node Software Copying Permissions
3669@comment node-name, next, previous, up
3670@section Software Copying Permissions
3671@cindex Software copying permissions
3672@cindex Copying software
3673@cindex Distribution
3674@cindex License agreement
3675
3676If the Texinfo file has a section containing the ``General Public
3677License'' and the distribution information and a warranty disclaimer
3678for the software that is documented, this section usually follows the
3679`Top' node. The General Public License is very important to Project
3680GNU software. It ensures that you and others will continue to have a
3681right to use and share the software.@refill
3682
3683The copying and distribution information and the disclaimer are followed
3684by an introduction or else by the first chapter of the manual.@refill
3685
3686@cindex Introduction, as part of file
3687Although an introduction is not a required part of a Texinfo file, it
3688is very helpful. Ideally, it should state clearly and concisely what
3689the file is about and who would be interested in reading it. In
3690general, an introduction would follow the licensing and distribution
3691information, although sometimes people put it earlier in the document.
3692Usually, an introduction is put in an @code{@@unnumbered} section.
3693(@xref{unnumbered & appendix, , The @code{@@unnumbered} and
3694@code{@@appendix} Commands}.)@refill
3695
3696@node Ending a File, Structuring, Beginning a File, Top
3697@comment node-name, next, previous, up
3698@chapter Ending a Texinfo File
3699@cindex Ending a Texinfo file
3700@cindex Texinfo file ending
3701@cindex File ending
3702@findex bye
3703
3704The end of a Texinfo file should include commands to create indices and
3705(usually) to generate detailed and summary tables of contents. And it
3706must include the @code{@@bye} command that marks the last line processed
3707by @TeX{}.@refill
3708
3709@need 700
3710For example:
3711
3712@example
3713@@node Concept Index, , Variables Index, Top
3714@@c node-name, next, previous, up
3715@@unnumbered Concept Index
3716
3717@@printindex cp
3718
3719@@contents
3720@@bye
3721@end example
3722
3723@menu
3724* Printing Indices & Menus:: How to print an index in hardcopy and
3725 generate index menus in Info.
3726* Contents:: How to create a table of contents.
3727* File End:: How to mark the end of a file.
3728@end menu
3729
3730@node Printing Indices & Menus, Contents, Ending a File, Ending a File
3731@comment node-name, next, previous, up
3732@section Index Menus and Printing an Index
3733@findex printindex
3734@cindex Printing an index
3735@cindex Indices, printing and menus
3736@cindex Generating menus with indices
3737@cindex Menus generated with indices
3738
3739To print an index means to include it as part of a manual or Info
3740file. This does not happen automatically just because you use
3741@code{@@cindex} or other index-entry generating commands in the
3742Texinfo file; those just cause the raw data for the index to be
3743accumulated. To generate an index, you must include the
3744@code{@@printindex} command at the place in the document where you
3745want the index to appear. Also, as part of the process of creating a
3746printed manual, you must run a program called @code{texindex}
3747(@pxref{Hardcopy}) to sort the raw data to produce a sorted
3748index file. The sorted index file is what is actually used to
3749print the index.@refill
3750
3751Texinfo offers six different types of predefined index: the concept
3752index, the function index, the variables index, the keystroke index, the
3753program index, and the data type index (@pxref{Predefined Indices}). Each
3754index type has a two-letter name: @samp{cp}, @samp{fn}, @samp{vr},
3755@samp{ky}, @samp{pg}, and @samp{tp}. You may merge indices, or put them
3756into separate sections (@pxref{Combining Indices}); or you may define
3757your own indices (@pxref{New Indices, , Defining New Indices}).@refill
3758
3759The @code{@@printindex} command takes a two-letter index name, reads
3760the corresponding sorted index file and formats it appropriately into
3761an index.@refill
3762
3763@ignore
3764The two-letter index names are:
3765
3766@table @samp
3767@item cp
3768concept index
3769@item fn
3770function index
3771@item vr
3772variable index
3773@item ky
3774key index
3775@item pg
3776program index
3777@item tp
3778data type index
3779@end table
3780@end ignore
3781The @code{@@printindex} command does not generate a chapter heading
3782for the index. Consequently, you should precede the
3783@code{@@printindex} command with a suitable section or chapter command
3784(usually @code{@@unnumbered}) to supply the chapter heading and put
3785the index into the table of contents. Precede the @code{@@unnumbered}
3786command with an @code{@@node} line.@refill
3787
3788@need 1200
3789For example:
3790
3791@smallexample
3792@group
3793@@node Variable Index, Concept Index, Function Index, Top
3794@@comment node-name, next, previous, up
3795@@unnumbered Variable Index
3796
3797@@printindex vr
3798@end group
3799
3800@group
3801@@node Concept Index, , Variable Index, Top
3802@@comment node-name, next, previous, up
3803@@unnumbered Concept Index
3804
3805@@printindex cp
3806@end group
3807@end smallexample
3808
3809@noindent
3810Readers often prefer that the concept index come last in a book,
3811since that makes it easiest to find. Having just one index helps
3812readers also, since then they have only one place to look
3813(@pxref{synindex}).
3814
3815
3816@node Contents
3817@section Generating a Table of Contents
3818@cindex Table of contents
3819@cindex Contents, Table of
3820@cindex Short table of contents
3821@findex contents
3822@findex summarycontents
3823@findex shortcontents
3824
3825The @code{@@chapter}, @code{@@section}, and other structuring commands
3826supply the information to make up a table of contents, but they do not
3827cause an actual table to appear in the manual. To do this, you must use
3828the @code{@@contents} and/or @code{@@summarycontents} command(s).
3829
3830@table @code
3831@item @@contents
3832Generate a table of contents in a printed manual, including all
3833chapters, sections, subsections, etc., as well as appendices and
3834unnumbered chapters. (Headings generated by the @code{@@heading}
3835series of commands do not appear in the table of contents.)
3836
3837@item @@shortcontents
3838@itemx @@summarycontents
3839(@code{@@summarycontents} is a synonym for @code{@@shortcontents}; the
3840two commands are exactly the same.)@refill
3841
3842Generate a short or summary table of contents that lists only the
3843chapters (and appendices and unnumbered chapters). Omit sections, subsections
3844and subsubsections. Only a long manual needs a short table
3845of contents in addition to the full table of contents.@refill
3846
3847@end table
3848
3849Both contents commands should be written on a line by themselves.
3850The contents commands automatically generate a chapter-like heading at
3851the top of the first table of contents page, so don't include any
3852sectioning command such as @code{@@unnumbered} before them.
3853
--- 22 unchanged lines hidden (view full) ---
3876@findex setcontentsaftertitlepage
3877@findex setshortcontentsaftertitlepage
3878@cindex Contents, after title page
3879@cindex Table of contents, after title page
3880As an author, you can put the contents commands wherever you prefer.
3881But if you are a user simply printing a manual, you may wish to print
3882the contents after the title page even if the author put the contents
3883commands at the end of the document (as is the case in most existing
3884Texinfo documents). You can do this by specifying
3885@code{@@setcontentsaftertitlepage} and/or
3886@code{@@setshortcontentsaftertitlepage}. The first prints only the main
3887contents after the @code{@@end titlepage}; the second prints both the
3888short contents and the main contents. In either case, any subsequent
3889@code{@@contents} or @code{@@shortcontents} is ignored (unless no
3890@code{@@end titlepage} is ever encountered).
3891
3892You need to include the @code{@@set@dots{}contentsaftertitlepage}
3893commands early in the document (just after @code{@@setfilename}, for
3894example). Or, if you're using @command{texi2dvi} (@pxref{Format with
3895texi2dvi}), you can use its @option{--texinfo} option to specify this
3896without altering the source file at all. For example:
3897@example
3898texi2dvi --texinfo=@@setshortcontentsaftertitlepage foo.texi
3899@end example
3900
3901
3902@node File End
3903@section @code{@@bye} File Ending
3904@findex bye
3905
3906An @code{@@bye} command terminates @TeX{} or Info formatting. None of
3907the formatting commands see any of the file following @code{@@bye}.
3908The @code{@@bye} command should be on a line by itself.@refill
3909
3910If you wish, you may follow the @code{@@bye} line with notes. These notes
3911will not be formatted and will not appear in either Info or a printed
3912manual; it is as if text after @code{@@bye} were within @code{@@ignore}
3913@dots{} @code{@@end ignore}. Also, you may follow the @code{@@bye} line
3914with a local variables list. @xref{Compile-Command, , Using Local
3915Variables and the Compile Command}, for more information.@refill
3916
3917
3918@node Structuring
3919@chapter Chapter Structuring
3920@cindex Chapter structuring
3921@cindex Structuring of chapters
3922
3923The @dfn{chapter structuring} commands divide a document into a hierarchy of
--- 705 unchanged lines hidden (view full) ---
4629
4630@menu
4631* Node Names:: How to choose node and pointer names.
4632* Writing a Node:: How to write an @code{@@node} line.
4633* Node Line Tips:: Keep names short.
4634* Node Line Requirements:: Keep names unique, without @@-commands.
4635* First Node:: How to write a `Top' node.
4636* makeinfo top command:: How to use the @code{@@top} command.
4637* Top Node Summary:: Write a brief description for readers.
4638@end menu
4639
4640
4641@node Node Names
4642@subsection Choosing Node and Pointer Names
4643
4644@cindex Node names, choosing
4645The name of a node identifies the node. The pointers enable
--- 172 unchanged lines hidden (view full) ---
4818
4819@noindent
4820The corresponding node name is:
4821
4822@smallexample
4823unnumberedsec appendixsec heading
4824@end smallexample
4825
4826@cindex Case in nodename
4827@item
4828Case is significant.
4829@end itemize
4830
4831
4832@node First Node, makeinfo top command, Node Line Requirements, node
4833@comment node-name, next, previous, up
4834@subsection The First Node
4835@cindex Top node is first
4836@cindex First node
4837
4838The first node of a Texinfo file is the @dfn{Top} node, except in an
4839included file (@pxref{Include Files}). The Top node contains the main
4840or master menu for the document, and a short summary of the document
4841(@pxref{Top Node Summary}).
4842
4843@cindex Up node of Top node
4844@cindex (dir) as Up node of Top node
4845The Top node (which must be named @samp{top} or @samp{Top}) should have
4846as its `Up' node the name of a node in another file, where there is a
4847menu that leads to this file. Specify the file name in parentheses. If
4848the file is to be installed directly in the Info directory file, use
4849@samp{(dir)} as the parent of the Top node; this is short for
4850@samp{(dir)top}, and specifies the Top node in the @file{dir} file,
4851which contains the main menu for the Info system as a whole. For
4852example, the @code{@@node Top} line of this manual looks like this:
4853
4854@example
4855@@node Top, Copying, , (dir)
4856@end example
4857
4858@noindent
4859(You can use the Texinfo updating commands or the @code{makeinfo}
4860utility to insert these pointers automatically.)
4861
4862@cindex Previous node of Top node
4863Do not define the `Previous' node of the Top node to be @samp{(dir)}, as
4864it causes confusing behavior for users: if you are in the Top node and
4865hits @key{DEL} to go backwards, you wind up in the middle of the
4866some other entry in the @file{dir} file, which has nothing to do with
4867what you were reading.
4868
4869@xref{Installing an Info File}, for more information about installing
4870an Info file in the @file{info} directory.
4871
4872
4873@node makeinfo top command, Top Node Summary, First Node, node
4874@comment node-name, next, previous, up
4875@subsection The @code{@@top} Sectioning Command
4876@findex top @r{(@@-command)}
4877
4878A special sectioning command, @code{@@top}, has been created for use
4879with the @code{@@node Top} line. The @code{@@top} sectioning command tells
4880@code{makeinfo} that it marks the `Top' node in the file. It provides
4881the information that @code{makeinfo} needs to insert node
4882pointers automatically. Write the @code{@@top} command at the
4883beginning of the line immediately following the @code{@@node Top}
4884line. Write the title on the remaining part of the same line as the
4885@code{@@top} command.@refill
4886
4887In Info, the @code{@@top} sectioning command causes the title to appear on a
4888line by itself, with a line of asterisks inserted underneath.@refill
4889
4890In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
4891sectioning command is merely a synonym for @code{@@unnumbered}.
4892Neither of these formatters require an @code{@@top} command, and do
4893nothing special with it. You can use @code{@@chapter} or
4894@code{@@unnumbered} after the @code{@@node Top} line when you use
4895these formatters. Also, you can use @code{@@chapter} or
4896@code{@@unnumbered} when you use the Texinfo updating commands to
4897create or update pointers and menus.@refill
4898
4899
4900@node Top Node Summary, , makeinfo top command, node
4901@subsection The `Top' Node Summary
4902@cindex @samp{@r{Top}} node summary
4903
4904You can help readers by writing a summary in the `Top' node, after the
4905@code{@@top} line, before the main or master menu. The summary should
4906briefly describe the document. In Info, this summary will appear just
4907before the master menu. In a printed manual, this summary will appear
4908on a page of its own.@refill
4909
4910If you do not want the summary to appear on a page of its own in a
4911printed manual, you can enclose the whole of the `Top' node, including
4912the @code{@@node Top} line and the @code{@@top} sectioning command line
4913or other sectioning command line between @code{@@ifinfo} and @code{@@end
4914ifinfo}. This prevents any of the text from appearing in the printed
4915output. (@pxref{Conditionals, , Conditionally Visible Text}). You can
4916repeat the brief description from the `Top' node within @code{@@iftex}
4917@dots{} @code{@@end iftex} at the beginning of the first chapter, for
4918those who read the printed manual. This saves paper and may look
4919neater.@refill
4920
4921You should write the version number of the program to which the manual
4922applies in the summary. This helps the reader keep track of which
4923manual is for which version of the program. If the manual changes more
4924frequently than the program or is independent of it, you should also
4925include an edition number for the manual. (The title page should also
4926contain this information: see @ref{titlepage, ,
4927@code{@@titlepage}}.)@refill
4928
4929
4930@node makeinfo Pointer Creation
4931@section Creating Pointers with @code{makeinfo}
4932@cindex Creating pointers with @code{makeinfo}
4933@cindex Pointer creation with @code{makeinfo}
4934@cindex Automatic pointer creation with @code{makeinfo}
4935
4936The @code{makeinfo} program has a feature for automatically defining
4937node pointers for a hierarchically organized file.
--- 109 unchanged lines hidden (view full) ---
5047@cindex Nodes for menus are short
5048@cindex Short nodes for menus
5049
5050The short text before a menu may look awkward in a printed manual. To
5051avoid this, you can write a menu near the beginning of its node and
5052follow the menu by an @code{@@node} line, and then an @code{@@heading}
5053line located within @code{@@ifinfo} and @code{@@end ifinfo}. This way,
5054the menu, @code{@@node} line, and title appear only in the Info file,
5055not the printed document.@refill
5056
5057For example, the preceding two paragraphs follow an Info-only menu,
5058@code{@@node} line, and heading, and look like this:@refill
5059
5060@example
5061@group
5062@@menu
5063* Menu Location:: Put a menu in a short node.
5064* Writing a Menu:: What is a menu?
5065* Menu Parts:: A menu entry has three parts.
5066* Less Cluttered Menu Entry:: Two part menu entry.
--- 4 unchanged lines hidden (view full) ---
5071
5072@@node Menu Location, Writing a Menu, , Menus
5073@@ifinfo
5074@@heading Menus Need Short Nodes
5075@@end ifinfo
5076@end group
5077@end example
5078
5079The Texinfo file for this document contains more than a dozen
5080examples of this procedure. One is at the beginning of this chapter;
5081another is at the beginning of @ref{Cross References}. @refill
5082
5083
5084@node Writing a Menu, Menu Parts, Menu Location, Menus
5085@section Writing a Menu
5086@cindex Writing a menu
5087@cindex Menu writing
5088
5089A menu consists of an @code{@@menu} command on a line by
--- 1312 unchanged lines hidden (view full) ---
6402not something else that should not be changed.@refill
6403
6404@menu
6405* Useful Highlighting:: Highlighting provides useful information.
6406* code:: Indicating program code.
6407* kbd:: Showing keyboard input.
6408* key:: Specifying keys.
6409* samp:: A literal sequence of characters.
6410* verb:: A verbatim sequence of characters.
6411* var:: Indicating metasyntactic variables.
6412* env:: Indicating environment variables.
6413* file:: Indicating file names.
6414* command:: Indicating command names.
6415* option:: Indicating option names.
6416* dfn:: Specifying definitions.
6417* cite:: Referring to books not in the Info system.
6418* acronym:: Indicating acronyms.
--- 925 unchanged lines hidden (view full) ---
7344line.
7345@findex end
7346
7347@menu
7348* Block Enclosing Commands:: Different constructs for different purposes.
7349* quotation:: Writing a quotation.
7350* example:: Writing an example in a fixed-width font.
7351* verbatim:: Writing a verbatim example.
7352* verbatiminclude:: Including a file verbatim.
7353* lisp:: Illustrating Lisp code.
7354* small:: Forms for @code{@@smallbook}.
7355* display:: Writing an example in the current font.
7356* format:: Writing an example without narrowed margins.
7357* exdent:: Undo indentation on a line.
7358* flushleft & flushright:: Pushing text flush left or flush right.
7359* noindent:: Preventing paragraph indentation.
7360* cartouche:: Drawing rounded rectangles around examples.
--- 198 unchanged lines hidden (view full) ---
7559such as computer input or output (@code{@@example} interprets its text
7560as regular Texinfo commands). This is especially useful for including
7561automatically generated output in a Texinfo manual. Here is an example;
7562the output you see is just the same as the input, with a line
7563@code{@@verbatim} before and a line @code{@@end verbatim} after.
7564
7565@verbatim
7566This is an example of text written in a @verbatim
7567block. No character substitutions are made all commands
7568are ignored, until the next 'end verbatim' command.
7569
7570In the printed manual, the text is typeset in a
7571fixed-width font, and not indented or filled. All
7572spaces and blank lines are significant, including tabs.
7573@end verbatim
7574
7575Write a @code{@@verbatim} command at the beginning of a line by itself.
7576This line will disappear from the output. Mark the end of the verbatim
7577block with a @code{@@end verbatim} command, also written at the
7578beginning of a line by itself. The @code{@@end verbatim} will also
7579disappear from the output.
7580
7581For example:
7582@c urg: got to trick this a bit: can't use @end verbatim inside @verbatim
7583
7584@example
7585@exdent @@verbatim
7586@exdent @{
7587@exdent <tab>@@command with strange characters: @@'e
7588@exdent expand<tab>me
7589@exdent @}
7590@exdent @@end verbatim
--- 5 unchanged lines hidden (view full) ---
7596@verbatim
7597{
7598 @command with strange characters: @'e
7599expand me
7600}
7601@end verbatim
7602
7603Since the lines containing @code{@@verbatim} and @code{@@end verbatim}
7604will disappear, tyically you should put a blank line before the
7605@code{@@verbatim} and another blank line after the @code{@@end
7606verbatim}. Blank lines between the beginning @code{@@verbatim} and the
7607ending @code{@@end verbatim} will appear in the output.)
7608
7609
7610@node verbatiminclude
7611@section @code{@@verbatiminclude} @var{file}: Include a File Verbatim
7612@cindex Verbatim, include file
7613@cindex Including a file verbatim
7614@findex verbatiminclude
7615
--- 1190 unchanged lines hidden (view full) ---
8806
8807@menu
8808* syncodeindex:: How to merge two indices, using @code{@@code}
8809 font for the merged-from index.
8810* synindex:: How to merge two indices, using the
8811 default font of the merged-to index.
8812@end menu
8813
8814@node syncodeindex, synindex, Combining Indices, Combining Indices
8815@subsection @code{@@syncodeindex}
8816@findex syncodeindex
8817
8818When you want to combine functions and concepts into one index, you
8819should index the functions with @code{@@findex} and index the concepts
8820with @code{@@cindex}, and use the @code{@@syncodeindex} command to
8821redirect the function index entries into the concept index.@refill
8822@findex syncodeindex
--- 131 unchanged lines hidden (view full) ---
8954
8955The @code{@@defcodeindex} is like the @code{@@defindex} command, except
8956that, in the printed output, it prints entries in an @code{@@code} font
8957instead of a roman font. Thus, it parallels the @code{@@findex} command
8958rather than the @code{@@cindex} command.@refill
8959
8960You should define new indices within or right after the end-of-header
8961line of a Texinfo file, before any @code{@@synindex} or
8962@code{@@syncodeindex} commands (@pxref{Header}).@refill
8963
8964@node Insertions
8965@chapter Special Insertions
8966@cindex Inserting special characters and symbols
8967@cindex Special insertions
8968
8969Texinfo provides several commands for inserting characters that have
8970special meaning in Texinfo, such as braces, and for other graphic
8971elements that do not correspond to simple characters you can type.
--- 51 unchanged lines hidden (view full) ---
9023
9024@menu
9025* Inserting An Atsign:: How to insert @samp{@@}.
9026* Inserting Braces:: How to insert @samp{@{} and @samp{@}}.
9027@end menu
9028
9029@node Inserting An Atsign, Inserting Braces, Braces Atsigns, Braces Atsigns
9030@subsection Inserting @samp{@@} with @@@@
9031@findex @@ @r{(single @samp{@@})}
9032
9033@code{@@@@} stands for a single @samp{@@} in either printed or Info
9034output.
9035
9036Do not put braces after an @code{@@@@} command.
9037
9038
9039@node Inserting Braces
9040@subsection Inserting @samp{@{} and @samp{@}}with @@@{ and @@@}
9041@findex @{ @r{(single @samp{@{})}
9042@findex @} @r{(single @samp{@}})}
9043
9044@code{@@@{} stands for a single @samp{@{} in either printed or Info
9045output.
9046
9047@code{@@@}} stands for a single @samp{@}} in either printed or Info
9048output.
9049
9050Do not put braces after either an @code{@@@{} or an @code{@@@}}
--- 208 unchanged lines hidden (view full) ---
9259
9260Here is a table with the commands Texinfo provides for inserting
9261floating accents. The commands with non-alphabetic names do not take
9262braces around their argument (which is taken to be the next character).
9263(Exception: @code{@@,} @emph{does} take braces around its argument.)
9264This is so as to make the source as convenient to type and read as
9265possible, since accented characters are very common in some languages.
9266
9267@findex "
9268@cindex Umlaut accent
9269@findex '
9270@cindex Acute accent
9271@findex =
9272@cindex Macron accent
9273@findex ^
9274@cindex Circumflex accent
9275@findex `
9276@cindex Grave accent
9277@findex ~
9278@cindex Tilde accent
9279@findex ,
9280@cindex Cedilla accent
9281@findex dotaccent
9282@cindex Dot accent
9283@findex H
9284@cindex Hungarian umlaut accent
9285@findex ringaccent
9286@cindex Ring accent
9287@findex tieaccent
9288@cindex Tie-after accent
9289@findex u
9290@cindex Breve accent
9291@findex ubaraccent
9292@cindex Underbar accent
9293@findex udotaccent
9294@cindex Underdot accent
9295@findex v
9296@cindex Check accent
9297@multitable {@@questiondown@{@}} {Output} {macron/overbar accent}
9298@item Command @tab Output @tab What
9299@item @t{@@"o} @tab @"o @tab umlaut accent
9300@item @t{@@'o} @tab @'o @tab acute accent
9301@item @t{@@,@{c@}} @tab @,{c} @tab cedilla accent
9302@item @t{@@=o} @tab @=o @tab macron/overbar accent
9303@item @t{@@^o} @tab @^o @tab circumflex accent
--- 230 unchanged lines hidden (view full) ---
9534(a + b)(a + b) = a^2 + 2ab + b^2
9535@end example
9536
9537Thus, the @code{@@math} command has no effect on the Info output.
9538
9539@code{@@math} implies @code{@@tex}. This not only makes it possible to
9540write superscripts and subscripts (as in the above example), but also
9541allows you to use any of the plain @TeX{} math control sequences. It's
9542simplest to use @samp{\} instead of @samp{@@} for these commands. As
9543in:
9544@example
9545@@math@{\sin 2\pi \equiv \cos 3\pi@}
9546@end example
9547
9548@iftex
9549@noindent which looks like this in @TeX{}:
9550@display
9551@math{\sin 2\pi \equiv \cos 3\pi}
9552@end display
9553
9554@noindent and
9555@end iftex
9556@noindent which looks like the input in Info and HTML:
9557@example
9558\sin 2\pi \equiv \cos 3\pi
9559@end example
9560
9561@cindex Displayed equations
9562@cindex Equations, displayed
9563For displayed equations, you must at present use @TeX{} directly
9564(@pxref{Raw Formatter Commands}).
9565
9566
9567@node Glyphs
9568@section Glyphs for Examples
--- 797 unchanged lines hidden (view full) ---
10366refilled after the line break occurs, negating the effect of the line
10367break.@refill
10368@end quotation
10369
10370
10371@node - and hyphenation
10372@section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} hyphenate
10373
10374@findex -
10375@findex hyphenation
10376@cindex Hyphenation, helping @TeX{} do
10377@cindex Fine-tuning, and hyphenation
10378
10379Although @TeX{}'s hyphenation algorithm is generally pretty good, it
10380does miss useful hyphenation points from time to time. (Or, far more
10381rarely, insert an incorrect hyphenation.) So, for documents with an
10382unusual vocabulary or when fine-tuning for a printed edition, you may
10383wish to help @TeX{} out. Texinfo supports two commands for this:
10384
10385@table @code
10386@item @@-
10387Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does
10388not have to) hyphenate. This is especially useful when you notice
10389an overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull
10390hboxes}). @TeX{} will not insert any hyphenation points in a word
10391containing @code{@@-}.
10392
10393@item @@hyphenation@{@var{hy-phen-a-ted words}@}
10394Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you
10395put a @samp{-} at each hyphenation point. For example:
10396@example
10397@@hyphenation@{man-u-script man-u-scripts@}
10398@end example
10399@noindent @TeX{} only uses the specified hyphenation points when the
--- 1340 unchanged lines hidden (view full) ---
11740 all output formats); and how to set a
11741 flag to a string that you can insert.
11742@end menu
11743
11744
11745@node Conditional Commands
11746@section Conditional Commands
11747
11748@findex ifinfo
11749@code{@@ifinfo} begins segments of text that should be ignored by @TeX{}
11750when it typesets the printed manual. The segment of text appears only
11751in the Info file. The @code{@@ifinfo} command should appear on a line
11752by itself; end the Info-only text with a line containing @code{@@end
11753ifinfo} by itself. At the beginning of a Texinfo file, the Info
11754permissions are contained within a region marked by @code{@@ifinfo} and
11755@code{@@end ifinfo}. (@xref{Info Summary and Permissions}.)
11756
11757@findex iftex
11758@findex ifhtml
11759The @code{@@iftex} and @code{@@end iftex} commands are similar to the
11760@code{@@ifinfo} and @code{@@end ifinfo} commands, except that they
11761specify text that will appear in the printed manual but not in the Info
11762file. Likewise for @code{@@ifhtml} and @code{@@end ifhtml}, which
11763specify text to appear only in HTML output.@refill
11764
11765For example,
11766
11767@example
11768@@iftex
11769This text will appear only in the printed manual.
11770@@end iftex
11771@@ifinfo
11772However, this text will appear only in Info.
11773@@end ifinfo
11774@@ifhtml
11775And this text will only appear in HTML.
11776@@end ifhtml
11777@end example
11778
11779@noindent
11780The preceding example produces the following line:
11781@iftex
11782This text will appear only in the printed manual.
11783@end iftex
11784@ifinfo
11785However, this text will appear only in Info.
11786@end ifinfo
11787@ifhtml
11788And this text will only appear in HTML.
11789@end ifhtml
11790
11791@noindent
11792Notice that you only see one of the input lines, depending on which
11793version of the manual you are reading.
11794
11795
11796@node Conditional Not Commands
11797@section Conditional Not Commands
11798@findex ifnothtml
11799@findex ifnotinfo
11800@findex ifnottex
11801
11802You can specify text to be included in any output format @emph{other}
11803than some given one with the @code{@@ifnot@dots{}} commands:
11804@example
11805@@ifnothtml @dots{} @@end ifnothtml
11806@@ifnotinfo @dots{} @@end ifnotinfo
11807@@ifnottex @dots{} @@end ifnottex
11808@end example
11809@noindent
11810(The @code{@@ifnot@dots{}} command and the @code{@@end} command must
11811actually appear on lines by themselves.)
11812
11813If the output file is not being made for the given format, the region is
11814included. Otherwise, it is ignored.
11815
11816The regions delimited by these commands are ordinary Texinfo source as
11817with @code{@@iftex}, not raw formatter source as with @code{@@tex}
11818(@pxref{Raw Formatter Commands}).
11819
11820
11821@node Raw Formatter Commands
11822@section Raw Formatter Commands
11823@cindex @TeX{} commands, using ordinary
--- 251 unchanged lines hidden (view full) ---
12075@@ifclear @var{flag}
12076@end example
12077
12078
12079@node value Example
12080@subsection @code{@@value} Example
12081
12082You can use the @code{@@value} command to minimize the number of places
12083you need to change when you record an update to a manual. Here is how
12084it is done in @cite{The GNU Make Manual}:
12085
12086@enumerate
12087@item
12088Set the flags:
12089
12090@example
12091@group
12092@@set EDITION 0.35 Beta
12093@@set VERSION 3.63 Beta
12094@@set UPDATED 14 August 1992
12095@@set UPDATE-MONTH August 1992
12096@end group
12097@end example
12098
12099@item
12100Write text for the first @code{@@ifinfo} section, for people reading the
12101Texinfo file:
12102
12103@example
12104@group
12105This is Edition @@value@{EDITION@},
12106last updated @@value@{UPDATED@},
12107of @@cite@{The GNU Make Manual@},
12108for @@code@{make@}, version @@value@{VERSION@}.
12109@end group
12110@end example
12111
12112@item
12113Write text for the title page, for people reading the printed manual:
12114@c List only the month and the year since that looks less fussy on a
12115@c printed cover than a date that lists the day as well.
12116
12117@example
12118@group
12119@@title GNU Make
12120@@subtitle A Program for Directing Recompilation
12121@@subtitle Edition @@value@{EDITION@}, @dots{}
12122@@subtitle @@value@{UPDATE-MONTH@}
12123@end group
12124@end example
12125
12126@noindent
12127(On a printed cover, a date listing the month and the year looks less
12128fussy than a date listing the day as well as the month and year.)
12129
12130@item
12131Write text for the Top node, for people reading the Info file:
12132
12133@example
12134@group
12135This is Edition @@value@{EDITION@}
12136of the @@cite@{GNU Make Manual@},
12137last updated @@value@{UPDATED@}
12138for @@code@{make@} Version @@value@{VERSION@}.
12139@end group
12140@end example
12141
12142After you format the manual, the text in the first @code{@@ifinfo}
12143section looks like this:
12144
12145@example
12146@group
12147This is Edition 0.35 Beta, last updated 14 August 1992,
12148of `The GNU Make Manual', for `make', Version 3.63 Beta.
12149@end group
12150@end example
12151@end enumerate
12152
12153When you update the manual, change only the values of the flags; you do
12154not need to edit the three sections.
12155
12156
12157@node Internationalization
12158@chapter Internationalization
12159
12160@cindex Internationalization
12161Texinfo has some support for writing in languages other than English,
12162although this area still needs considerable work.
--- 492 unchanged lines hidden (view full) ---
12655always work.
12656
12657@item
12658The @TeX{} implementation cannot construct macros that define macros in
12659the natural way. To do this, you must use conditionals and raw @TeX{}.
12660For example:
12661
12662@example
12663@@ifinfo
12664@@macro ctor @{name, arg@}
12665@@macro \name\
12666something involving \arg\ somehow
12667@@end macro
12668@@end macro
12669@@end ifinfo
12670@@tex
12671\gdef\ctor#1@{\ctorx#1,@}
12672\gdef\ctorx#1,#2,@{\def#1@{something involving #2 somehow@}@}
12673@@end tex
12674@end example
12675
12676@item
12677It is best to avoid comments inside macro definitions.
--- 549 unchanged lines hidden (view full) ---
13227
13228You can change the values of these variables with the @kbd{M-x
13229edit-options} command (@pxref{Edit Options, , Editing Variable Values,
13230emacs, The GNU Emacs Manual}), with the @kbd{M-x set-variable} command
13231(@pxref{Examining, , Examining and Setting Variables, emacs, The GNU
13232Emacs Manual}), or with your @file{.emacs} initialization file
13233(@pxref{Init File, , , emacs, The GNU Emacs Manual}).@refill
13234
13235@cindex Customize Emacs package
13236@findex Development/Docs/Texinfo Customize group
13237Beginning with version 20, GNU Emacs offers a user-friendly interface,
13238called @dfn{Customize}, for changing values of user-definable variables.
13239@xref{Easy Customization, , Easy Customization Interface, emacs, The GNU
13240Emacs Manual}, for more details about this. The Texinfo variables can
13241be found in the @samp{Development/Docs/Texinfo} group, once you invoke
13242the @kbd{M-x customize} command.
13243
13244
13245@node Compile-Command, Requirements Summary, Texinfo Mode Printing, Hardcopy
13246@section Using the Local Variables List
13247@cindex Local variables
13248@cindex Compile command for formatting
13249@cindex Format with the compile command
13250
13251Yet another way to apply the @TeX{} formatting command to a Texinfo file
13252is to put that command in a @dfn{local variables list} at the end of the
13253Texinfo file. You can then specify the @code{tex} or @code{texi2dvi}
--- 384 unchanged lines hidden (view full) ---
13638sheet of film; but you can attempt to use it to mark the corners of a
13639book set to 7 by 9.25 inches with the @code{@@smallbook} command.
13640(Printers will not produce cropmarks for regular sized output that is
13641printed on regular sized paper.) Since different printing machines work
13642in different ways, you should explore the use of this command with a
13643spirit of adventure. You may have to redefine the command in
13644@file{texinfo.tex}.
13645
13646@findex mag @r{(@TeX{} command)}
13647@cindex Magnified printing
13648@cindex Larger or smaller pages
13649You can attempt to direct @TeX{} to typeset pages larger or smaller than
13650usual with the @code{\mag} @TeX{} command. Everything that is typeset
13651is scaled proportionally larger or smaller. (@code{\mag} stands for
13652``magnification''.) This is @emph{not} a Texinfo @@-command, but is a
13653plain @TeX{} command that is prefixed with a backslash. You have to
13654write this command between @code{@@tex} and @code{@@end tex}
--- 54 unchanged lines hidden (view full) ---
13709@node Creating and Installing Info Files
13710@chapter Creating and Installing Info Files
13711
13712This chapter describes how to create and install Info files. @xref{Info
13713Files}, for general information about the file format itself.
13714
13715@menu
13716* Creating an Info File::
13717* Installing an Info File::
13718@end menu
13719
13720
13721@node Creating an Info File
13722@section Creating an Info File
13723@cindex Creating an Info file
13724@cindex Info, creating an online file
13725@cindex Formatting a file for Info
--- 63 unchanged lines hidden (view full) ---
13789makeinfo --version
13790@end example
13791
13792@xref{makeinfo options}, for more information.
13793@end ifinfo
13794
13795
13796@node makeinfo options
13797@comment node-name, next, previous, up
13798@subsection Options for @code{makeinfo}
13799@cindex @code{makeinfo} options
13800@cindex Options for @code{makeinfo}
13801
13802The @code{makeinfo} command takes a number of options. Most often,
13803options are used to set the value of the fill column and specify the
13804footnote style. Each command line option is a word preceded by
13805@samp{--} or a letter preceded by @samp{-}. You can use abbreviations
--- 109 unchanged lines hidden (view full) ---
13915that does not support @code{@@macro}.
13916
13917@item --no-headers
13918@opindex --no-headers
13919@cindex Plain text output
13920@cindex ASCII text output
13921@cindex Generating plain text files
13922@cindex @file{INSTALL} file, generating
13923For Info output, do not include menus or node lines in the output and
13924write to standard output (unless @option{--output} is specified). This
13925results in an @sc{ascii} file that you cannot read in Info since it does
13926not contain the requisite nodes or menus. It is primarily useful to
13927extract certain pieces of a manual into separate files to be included in
13928a distribution, such as @file{INSTALL} files.
13929
13930@cindex Navigation links, omitting
13931For HTML output, if @samp{--no-split} is also specified, do not include a
13932navigation links at the top of each node. @xref{makeinfo html}.
13933
13934@item --no-split
13935@opindex --no-split
13936@cindex Splitting of output files
13937@cindex Output file splitting
13938Suppress the splitting stage of @code{makeinfo}. By default, large
13939output files (where the size is greater than 70k bytes) are split into
13940smaller subfiles. For Info output, each one is approximately 50k bytes.
13941For HTML output, each file contains one node (@pxref{makeinfo html}).
--- 475 unchanged lines hidden (view full) ---
14417which have special significance in HTML).
14418
14419The @samp{--footnote-style} option is currently ignored for HTML output;
14420footnotes are linked to the end of the output file.
14421
14422The HTML generated is mostly standard (i.e., HTML 2.0, RFC-1866). The
14423exception is that HTML 3.2 tables are generated from the
14424@code{@@multitable} command, but tagged to degrade as well as possible
14425in browsers without table support. Please report output from an
14426error-free run of @code{makeinfo} which violates the @w{HTML 3.2} DTD as
14427a bug.
14428
14429Navigation bars are inserted at the start of nodes, similarly to Info
14430output. The @samp{--no-headers} option will suppress this if used with
14431@samp{--no-split}. Header @code{<link>} elements in split output can
14432support info-like navigation with browsers like Lynx and @w{Emacs W3}
14433which implement this @w{HTML 1.0} feature. @samp{@@xref} commands to
14434other documents are generated assuming the other document is available
14435in split HTML form, and installed in the same HTML documentation tree,
--- 7 unchanged lines hidden (view full) ---
14443@cindex @file{dir} directory for Info installation
14444
14445Info files are usually kept in the @file{info} directory. You can read
14446Info files using the standalone Info program or the Info reader built
14447into Emacs. (@inforef{Top, info, info}, for an introduction to Info.)
14448
14449@menu
14450* Directory File:: The top level menu for all Info files.
14451* New Info File:: Listing a new info file.
14452* Other Info Directories:: How to specify Info files that are
14453 located in other directories.
14454* Installing Dir Entries:: How to specify what menu entry to add
14455 to the Info directory.
14456* Invoking install-info:: @code{install-info} options.
14457@end menu
14458
14459
--- 223 unchanged lines hidden (view full) ---
14683
14684When you install an Info file onto your system, you can use the program
14685@code{install-info} to update the Info directory file @file{dir}.
14686Normally the makefile for the package runs @code{install-info}, just
14687after copying the Info file into its proper installed location.
14688
14689@findex dircategory
14690@findex direntry
14691In order for the Info file to work with @code{install-info}, you should
14692use the commands @code{@@dircategory} and
14693@code{@@direntry}@dots{}@code{@@end direntry} in the Texinfo source
14694file. Use @code{@@direntry} to specify the menu entries to add to the
14695Info directory file, and use @code{@@dircategory} to specify which part
14696of the Info directory to put it in. Here is how these commands are used
14697in this manual:
14698
14699@smallexample
14700@@dircategory Texinfo documentation system
--- 31 unchanged lines hidden (view full) ---
14732Here are some recommended @code{@@dircategory} categories:
14733
14734@display
14735GNU packages
14736GNU programming tools
14737GNU programming documentation
14738GNU Emacs Lisp
14739GNU libraries
14740Linux
14741TeX
14742Individual utilities
14743@end display
14744
14745The idea is to include the `Invoking' node for every program installed
14746by a package under `Individual utilities', and an entry for the manual
14747as a whole in the appropriate other category.
14748
--- 135 unchanged lines hidden (view full) ---
14884
14885@item @@"
14886@itemx @@'
14887Generate an umlaut or acute accent, respectively, over the next
14888character, as in @"o and @'o. @xref{Inserting Accents}.
14889
14890@item @@*
14891Force a line break. Do not end a paragraph that uses @code{@@*} with
14892an @code{@@refill} command. @xref{Line Breaks}.@refill
14893
14894@item @@,@{@var{c}@}
14895Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting
14896Accents}.
14897
14898@item @@-
14899Insert a discretionary hyphenation point. @xref{- and hyphenation}.
14900
--- 15 unchanged lines hidden (view full) ---
14916@item @@?
14917Generate a question mark that really does end a sentence (usually after
14918an end-of-sentence capital letter). @xref{Ending a Sentence}.
14919
14920@item @@@@
14921Stands for an at sign, @samp{@@}.
14922@xref{Braces Atsigns, , Inserting @@ and braces}.
14923
14924@item @@^
14925@itemx @@`
14926Generate a circumflex (hat) or grave accent, respectively, over the next
14927character, as in @^o.
14928@xref{Inserting Accents}.
14929
14930@item @@@{
14931Stands for a left brace, @samp{@{}.
14932@xref{Braces Atsigns, , Inserting @@ and braces}.
14933
14934@item @@@}
14935Stands for a right-hand brace, @samp{@}}.@*
--- 376 unchanged lines hidden (view full) ---
15312
15313@item @@error@{@}
15314Indicate to the reader with a glyph that the following text is
15315an error message: @samp{@error{}}. @xref{Error Glyph}.@refill
15316
15317@item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
15318@itemx @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
15319Specify page footings resp.@: headings for even-numbered (left-hand)
15320pages. Only allowed inside @code{@@iftex}. @xref{Custom Headings, ,
15321How to Make Your Own Headings}.@refill
15322
15323@item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
15324@itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
15325Specify page footings resp.@: headings for every page. Not relevant to
15326Info. @xref{Custom Headings, , How to Make Your Own Headings}.@refill
15327
15328@item @@example
--- 82 unchanged lines hidden (view full) ---
15411Enter HTML completely. Pair with @code{@@end html}. @xref{Raw
15412Formatter Commands}.
15413
15414@item @@hyphenation@{@var{hy-phen-a-ted words}@}
15415Explicitly define hyphenation points. @xref{- and hyphenation,,
15416@code{@@-} and @code{@@hyphenation}}.
15417
15418@item @@i@{@var{text}@}
15419Print @var{text} in @i{italic} font. No effect in Info.
15420@xref{Fonts}.@refill
15421
15422@item @@ifclear @var{flag}
15423If @var{flag} is cleared, the Texinfo formatting commands format text
15424between @code{@@ifclear @var{flag}} and the following @code{@@end
15425ifclear} command.
15426@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
15427
15428@item @@ifhtml
15429@itemx @@ifinfo
15430Begin a stretch of text that will be ignored by @TeX{} when it typesets
15431the printed manual. The text appears only in the HTML resp.@: Info
15432file. Pair with @code{@@end ifhtml} resp.@: @code{@@end ifinfo}.
15433@xref{Conditionals}.
15434
15435@item @@ifnothtml
15436@itemx @@ifnotinfo
15437@itemx @@ifnottex
15438Begin a stretch of text that will be ignored in one output format but
15439not the others. The text appears only in the format not specified.
15440Pair with @code{@@end ifnothtml} resp.@: @code{@@end ifnotinfo} resp.@:
15441@code{@@end ifnotinfo}. @xref{Conditionals}.
15442
15443@item @@ifset @var{flag}
15444If @var{flag} is set, the Texinfo formatting commands format text
15445between @code{@@ifset @var{flag}} and the following @code{@@end ifset}
15446command.
15447@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
15448
15449@item @@iftex
15450Begin a stretch of text that will not appear in the Info file, but
--- 20 unchanged lines hidden (view full) ---
15471@code{@@inforef}}.@refill
15472
15473@item \input @var{macro-definitions-file}
15474Use the specified macro definitions file. This command is used only
15475in the first line of a Texinfo file to cause @TeX{} to make use of the
15476@file{texinfo} macro definitions file. The backslash in @code{\input}
15477is used instead of an @code{@@} because @TeX{} does not
15478recognize @code{@@} until after it has read the definitions file.
15479@xref{Header, , The Texinfo File Header}.@refill
15480
15481@item @@item
15482Indicate the beginning of a marked paragraph for @code{@@itemize} and
15483@code{@@enumerate}; indicate the beginning of the text of a first column
15484entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}.
15485@xref{Lists and Tables}.@refill
15486
15487@item @@itemize @var{mark-generating-character-or-command}
--- 89 unchanged lines hidden (view full) ---
15577@item @@O@{@}
15578@itemx @@o@{@}
15579Generate the uppercase and lowercase O-with-slash letters, respectively:
15580@O{}, @o{}.
15581
15582@item @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
15583@itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
15584Specify page footings resp.@: headings for odd-numbered (right-hand)
15585pages. Only allowed inside @code{@@iftex}. @xref{Custom Headings, ,
15586How to Make Your Own Headings}.@refill
15587
15588@item @@OE@{@}
15589@itemx @@oe@{@}
15590Generate the uppercase and lowercase OE ligatures, respectively:
15591@OE{}, @oe{}. @xref{Inserting Accents}.
15592
15593@item @@option@{@var{option-name}@}
--- 279 unchanged lines hidden (view full) ---
15873@xref{titlepage, , @code{@@titlepage}}.@refill
15874
15875@item @@today@{@}
15876Insert the current date, in `1 Jan 1900' style. @xref{Custom
15877Headings, , How to Make Your Own Headings}.@refill
15878
15879@item @@top @var{title}
15880In a Texinfo file to be formatted with @code{makeinfo}, identify the
15881topmost @code{@@node} line in the file, which must be written on the line
15882immediately preceding the @code{@@top} command. Used for
15883@code{makeinfo}'s node pointer insertion feature. The title is
15884underlined with asterisks. Both the @code{@@node} line and the @code{@@top}
15885line normally should be enclosed by @code{@@ifinfo} and @code{@@end
15886ifinfo}. In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
15887command is merely a synonym for @code{@@unnumbered}. @xref{makeinfo
15888Pointer Creation, , Creating Pointers with @code{makeinfo}}.
15889
15890@item @@u@{@var{c}@}
15891@itemx @@ubaraccent@{@var{c}@}
15892@itemx @@udotaccent@{@var{c}@}
15893Generate a breve, underbar, or underdot accent, respectively, over or
15894under the character @var{c}, as in @u{o}, @ubaraccent{o},
--- 65 unchanged lines hidden (view full) ---
15960Add @var{entry} to the index of variables. @xref{Index Entries, ,
15961Defining the Entries of an Index}.@refill
15962
15963@item @@vskip @var{amount}
15964In a printed manual, insert whitespace so as to push text on the
15965remainder of the page towards the bottom of the page. Used in
15966formatting the copyright page with the argument @samp{0pt plus
159671filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used
15968only in contexts ignored for Info. @xref{Copyright & Permissions, ,
15969The Copyright Page and Printed Permissions}.@refill
15970
15971@item @@vtable @var{formatting-command}
15972Begin a two-column table, using @code{@@item} for each entry.
15973Automatically enter each of the items in the first column into the
15974index of variables. Pair with @code{@@end vtable}. The same as
15975@code{@@table}, except for indexing. @xref{ftable vtable, ,
15976@code{@@ftable} and @code{@@vtable}}.@refill
15977
--- 154 unchanged lines hidden (view full) ---
16132@item
16133Write the prefatory sentence or phrase for a multi-item list or table as
16134a complete expression. Do not write ``You can set:''; instead, write
16135``You can set these variables:''. The former expression sounds cut off.
16136@end itemize
16137
16138@subsubheading Editions, Dates and Versions
16139
16140Write the edition and version numbers and date in three places in every
16141manual:
16142
16143@enumerate
16144@item
16145In the first @code{@@ifinfo} section, for people reading the Texinfo file.
16146
16147@item
16148In the @code{@@titlepage} section, for people reading the printed manual.
16149
16150@item
16151In the `Top' node, for people reading the Info file.
16152@end enumerate
16153
16154@noindent
16155Also, it helps to write a note before the first @code{@@ifinfo}
16156section to explain what you are doing.
16157
16158@need 800
16159@noindent
16160For example:
16161
16162@example
16163@group
16164@@c ===> NOTE! <==
16165@@c Specify the edition and version numbers and date
16166@@c in *three* places:
16167@@c 1. First ifinfo section 2. title page 3. top node
16168@@c To find the locations, search for !!set
16169@end group
16170
16171@group
16172@@ifinfo
16173@@c !!set edition, date, version
16174This is Edition 4.03, January 1992,
16175of the @@cite@{GDB Manual@} for GDB Version 4.3.
16176@dots{}
16177@end group
16178@end example
16179
16180@noindent
16181---or use @code{@@set} and @code{@@value}
16182(@pxref{value Example, , @code{@@value} Example}).
16183
16184@subsubheading Definition Commands
16185
16186Definition commands are @code{@@deffn}, @code{@@defun},
16187@code{@@defmac}, and the like, and enable you to write descriptions in
16188a uniform format.@refill
16189
16190@itemize @bullet
16191@item
--- 232 unchanged lines hidden (view full) ---
16424@item
16425Write notes for yourself at the very end of a Texinfo file after the
16426@code{@@bye}. None of the formatters process text after the
16427@code{@@bye}; it is as if the text were within @code{@@ignore} @dots{}
16428@code{@@end ignore}.
16429@end itemize
16430
16431
16432@node Sample Texinfo File
16433@appendix A Sample Texinfo File
16434@cindex Sample Texinfo file, no comments
16435
16436Here is a complete, short sample Texinfo file, without any commentary.
16437You can see this file, with comments, in the first chapter.
16438@xref{Short Sample, , A Short Sample Texinfo File}.
16439
16440@sp 1
16441@example
16442\input texinfo @@c -*-texinfo-*-
16443@@c %**start of header
16444@@setfilename sample.info
16445@@settitle Sample Document
16446@@c %**end of header
16447
16448@@ifinfo
16449This is a short example of a complete Texinfo file.
16450
16451Copyright (C) 2002 Free Software Foundation, Inc.
16452@@end ifinfo
16453
16454@@titlepage
16455@@comment The title is printed in a large font.
16456@@title Sample Title
16457
16458@@c The following two commands start the copyright page.
16459@@page
16460@@vskip 0pt plus 1filll
16461Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
16462@@end titlepage
16463
16464@@c Output the table of the contents at the beginning.
16465@@contents
16466
16467@@ifnottex
16468@@node Top
16469
16470This is the top node of a sample document.
16471@@end ifnottex
16472
16473@@menu
16474* First Chapter:: The first chapter is the
16475 only chapter in this sample.
16476* Concept Index:: This index has two entries.
16477@@end menu
16478
16479
16480@@node First Chapter
16481@@chapter First Chapter
16482@@cindex Chapter, first
16483
16484This is the contents of the first chapter.
16485@@cindex Another sample index entry
16486
16487Here is a numbered list.
16488
16489@@enumerate
16490@@item
16491This is the first item.
16492
16493@@item
16494This is the second item.
16495@@end enumerate
16496
16497The @@code@{makeinfo@} command transforms a Texinfo source file
16498such as this into an Info file or HTML; and @@TeX typesets it
16499for a printed manual.
16500
16501
16502@@node Concept Index
16503@@unnumbered Concept Index
16504
16505@@printindex cp
16506
16507@@bye
16508@end example
16509
16510
16511@node Include Files
16512@appendix Include Files
16513@cindex Include files
16514
16515When @TeX{} or an Info formatting command sees an @code{@@include}
16516command in a Texinfo file, it processes the contents of the file named
16517by the command and incorporates them into the DVI or Info file being
16518created. Index entries from the included file are incorporated into
16519the indices of the output file.@refill
16520
16521Include files let you keep a single large document as a collection of
16522conveniently small parts.
16523
16524@menu
16525* Using Include Files:: How to use the @code{@@include} command.
16526* texinfo-multiple-files-update:: How to create and update nodes and
16527 menus when using included files.
--- 199 unchanged lines hidden (view full) ---
16727@group
16728@@summarycontents
16729@@contents
16730
16731@@bye
16732@end group
16733@end example
16734
16735An included file, such as @file{foo.texinfo}, might look like
16736this:@refill
16737
16738@example
16739@group
16740@@node First, Second, , Top
16741@@chapter First Chapter
16742
16743Contents of first chapter @dots{}
16744@end group
--- 237 unchanged lines hidden (view full) ---
16982@code{@@evenheading} and @code{@@evenfooting} command generate headers
16983and footers for even-numbered (left-hand) pages.
16984@item
16985@code{@@oddheading} and @code{@@oddfooting} generate headers and footers
16986for odd-numbered (right-hand) pages.
16987@end itemize
16988
16989Write custom heading specifications in the Texinfo file immediately
16990after the @code{@@end titlepage} command. Enclose your specifications
16991between @code{@@iftex} and @code{@@end iftex} commands since the
16992@code{texinfo-format-buffer} command may not recognize them. Also,
16993you must cancel the predefined heading commands with the
16994@code{@@headings off} command before defining your own
16995specifications.@refill
16996
16997@need 1000
16998Here is how to tell @TeX{} to place the chapter name at the left, the
16999page number in the center, and the date at the right of every header
17000for both even- and odd-numbered pages:@refill
17001
17002@example
17003@group
17004@@iftex
17005@@headings off
17006@@everyheading @@thischapter @@| @@thispage @@| @@today@{@}
17007@@end iftex
17008@end group
17009@end example
17010
17011@noindent
17012You need to divide the left part from the central part and the central
17013part from the right part by inserting @samp{@@|} between parts.
17014Otherwise, the specification command will not be able to tell where
17015the text for one part ends and the next part begins.@refill
--- 83 unchanged lines hidden (view full) ---
17099@findex today
17100
17101Other @@-commands and text are printed in a header or footer just as
17102if they were in the body of a page. It is useful to incorporate text,
17103particularly when you are writing drafts:@refill
17104
17105@example
17106@group
17107@@iftex
17108@@headings off
17109@@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter
17110@@everyfooting @@| @@| Version: 0.27: @@today@{@}
17111@@end iftex
17112@end group
17113@end example
17114
17115Beware of overlong titles: they may overlap another part of the
17116header or footer and blot it out.@refill
17117
17118
17119@node Catching Mistakes
17120@appendix Formatting Mistakes
17121@cindex Structure, catching mistakes in
17122@cindex Nodes, catching mistakes
17123@cindex Catching mistakes
17124@cindex Correcting mistakes
17125@cindex Mistakes, catching
17126@cindex Problems, catching
17127@cindex Debugging the Texinfo structure
17128
17129Besides mistakes in the content of your documentation, there
17130are two kinds of mistake you can make with Texinfo: you can make mistakes
17131with @@-commands, and you can make mistakes with the structure of the
17132nodes and chapters.@refill
17133
17134Emacs has two tools for catching the @@-command mistakes and two for
17135catching structuring mistakes.@refill
17136
17137For finding problems with @@-commands, you can run @TeX{} or a region
17138formatting command on the region that has a problem; indeed, you can
17139run these commands on each region as you write it.@refill
17140
--- 1306 unchanged lines hidden (view full) ---
18447@end table
18448@tex
18449% Switch width of first column of tables back to default value
18450\global\tableindent=.8in
18451@end tex
18452@end ignore
18453
18454
18455@node Documentation Copying
18456@appendix GNU Free Documentation License
18457
18458@cindex FDL, GNU Free Documentation License
18459@center Version 1.1, March 2000
18460
18461@display
18462Copyright @copyright{} 2000 Free Software Foundation, Inc.
1846359 Temple Place, Suite 330, Boston, MA 02111-1307, USA
18464
18465Everyone is permitted to copy and distribute verbatim copies
18466of this license document, but changing it is not allowed.
18467@end display
18468
18469@enumerate 0
18470@item
18471PREAMBLE
18472
18473The purpose of this License is to make a manual, textbook, or other
18474written document @dfn{free} in the sense of freedom: to assure everyone
18475the effective freedom to copy and redistribute it, with or without
18476modifying it, either commercially or noncommercially. Secondarily,
18477this License preserves for the author and publisher a way to get
18478credit for their work, while not being considered responsible for
18479modifications made by others.
18480
18481This License is a kind of ``copyleft'', which means that derivative
18482works of the document must themselves be free in the same sense. It
18483complements the GNU General Public License, which is a copyleft
18484license designed for free software.
18485
18486We have designed this License in order to use it for manuals for free
18487software, because free software needs free documentation: a free
18488program should come with manuals providing the same freedoms that the
18489software does. But this License is not limited to software manuals;
18490it can be used for any textual work, regardless of subject matter or
18491whether it is published as a printed book. We recommend this License
18492principally for works whose purpose is instruction or reference.
18493
18494@item
18495APPLICABILITY AND DEFINITIONS
18496
18497This License applies to any manual or other work that contains a
18498notice placed by the copyright holder saying it can be distributed
18499under the terms of this License. The ``Document'', below, refers to any
18500such manual or work. Any member of the public is a licensee, and is
18501addressed as ``you''.
18502
18503A ``Modified Version'' of the Document means any work containing the
18504Document or a portion of it, either copied verbatim, or with
18505modifications and/or translated into another language.
18506
18507A ``Secondary Section'' is a named appendix or a front-matter section of
18508the Document that deals exclusively with the relationship of the
18509publishers or authors of the Document to the Document's overall subject
18510(or to related matters) and contains nothing that could fall directly
18511within that overall subject. (For example, if the Document is in part a
18512textbook of mathematics, a Secondary Section may not explain any
18513mathematics.) The relationship could be a matter of historical
18514connection with the subject or with related matters, or of legal,
18515commercial, philosophical, ethical or political position regarding
18516them.
18517
18518The ``Invariant Sections'' are certain Secondary Sections whose titles
18519are designated, as being those of Invariant Sections, in the notice
18520that says that the Document is released under this License.
18521
18522The ``Cover Texts'' are certain short passages of text that are listed,
18523as Front-Cover Texts or Back-Cover Texts, in the notice that says that
18524the Document is released under this License.
18525
18526A ``Transparent'' copy of the Document means a machine-readable copy,
18527represented in a format whose specification is available to the
18528general public, whose contents can be viewed and edited directly and
18529straightforwardly with generic text editors or (for images composed of
18530pixels) generic paint programs or (for drawings) some widely available
18531drawing editor, and that is suitable for input to text formatters or
18532for automatic translation to a variety of formats suitable for input
18533to text formatters. A copy made in an otherwise Transparent file
18534format whose markup has been designed to thwart or discourage
18535subsequent modification by readers is not Transparent. A copy that is
18536not ``Transparent'' is called ``Opaque''.
18537
18538Examples of suitable formats for Transparent copies include plain
18539@sc{ascii} without markup, Texinfo input format, La@TeX{} input format,
18540@acronym{SGML} or @acronym{XML} using a publicly available
18541@acronym{DTD}, and standard-conforming simple @acronym{HTML} designed
18542for human modification. Opaque formats include PostScript,
18543@acronym{PDF}, proprietary formats that can be read and edited only by
18544proprietary word processors, @acronym{SGML} or @acronym{XML} for which
18545the @acronym{DTD} and/or processing tools are not generally available,
18546and the machine-generated @acronym{HTML} produced by some word
18547processors for output purposes only.
18548
18549The ``Title Page'' means, for a printed book, the title page itself,
18550plus such following pages as are needed to hold, legibly, the material
18551this License requires to appear in the title page. For works in
18552formats which do not have any title page as such, ``Title Page'' means
18553the text near the most prominent appearance of the work's title,
18554preceding the beginning of the body of the text.
18555
18556@item
18557VERBATIM COPYING
18558
18559You may copy and distribute the Document in any medium, either
18560commercially or noncommercially, provided that this License, the
18561copyright notices, and the license notice saying this License applies
18562to the Document are reproduced in all copies, and that you add no other
18563conditions whatsoever to those of this License. You may not use
18564technical measures to obstruct or control the reading or further
18565copying of the copies you make or distribute. However, you may accept
18566compensation in exchange for copies. If you distribute a large enough
18567number of copies you must also follow the conditions in section 3.
18568
18569You may also lend copies, under the same conditions stated above, and
18570you may publicly display copies.
18571
18572@item
18573COPYING IN QUANTITY
18574
18575If you publish printed copies of the Document numbering more than 100,
18576and the Document's license notice requires Cover Texts, you must enclose
18577the copies in covers that carry, clearly and legibly, all these Cover
18578Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
18579the back cover. Both covers must also clearly and legibly identify
18580you as the publisher of these copies. The front cover must present
18581the full title with all words of the title equally prominent and
18582visible. You may add other material on the covers in addition.
18583Copying with changes limited to the covers, as long as they preserve
18584the title of the Document and satisfy these conditions, can be treated
18585as verbatim copying in other respects.
18586
18587If the required texts for either cover are too voluminous to fit
18588legibly, you should put the first ones listed (as many as fit
18589reasonably) on the actual cover, and continue the rest onto adjacent
18590pages.
18591
18592If you publish or distribute Opaque copies of the Document numbering
18593more than 100, you must either include a machine-readable Transparent
18594copy along with each Opaque copy, or state in or with each Opaque copy
18595a publicly-accessible computer-network location containing a complete
18596Transparent copy of the Document, free of added material, which the
18597general network-using public has access to download anonymously at no
18598charge using public-standard network protocols. If you use the latter
18599option, you must take reasonably prudent steps, when you begin
18600distribution of Opaque copies in quantity, to ensure that this
18601Transparent copy will remain thus accessible at the stated location
18602until at least one year after the last time you distribute an Opaque
18603copy (directly or through your agents or retailers) of that edition to
18604the public.
18605
18606It is requested, but not required, that you contact the authors of the
18607Document well before redistributing any large number of copies, to give
18608them a chance to provide you with an updated version of the Document.
18609
18610@item
18611MODIFICATIONS
18612
18613You may copy and distribute a Modified Version of the Document under
18614the conditions of sections 2 and 3 above, provided that you release
18615the Modified Version under precisely this License, with the Modified
18616Version filling the role of the Document, thus licensing distribution
18617and modification of the Modified Version to whoever possesses a copy
18618of it. In addition, you must do these things in the Modified Version:
18619
18620@enumerate A
18621@item
18622Use in the Title Page (and on the covers, if any) a title distinct
18623from that of the Document, and from those of previous versions
18624(which should, if there were any, be listed in the History section
18625of the Document). You may use the same title as a previous version
18626if the original publisher of that version gives permission.
18627
18628@item
18629List on the Title Page, as authors, one or more persons or entities
18630responsible for authorship of the modifications in the Modified
18631Version, together with at least five of the principal authors of the
18632Document (all of its principal authors, if it has less than five).
18633
18634@item
18635State on the Title page the name of the publisher of the
18636Modified Version, as the publisher.
18637
18638@item
18639Preserve all the copyright notices of the Document.
18640
18641@item
18642Add an appropriate copyright notice for your modifications
18643adjacent to the other copyright notices.
18644
18645@item
18646Include, immediately after the copyright notices, a license notice
18647giving the public permission to use the Modified Version under the
18648terms of this License, in the form shown in the Addendum below.
18649
18650@item
18651Preserve in that license notice the full lists of Invariant Sections
18652and required Cover Texts given in the Document's license notice.
18653
18654@item
18655Include an unaltered copy of this License.
18656
18657@item
18658Preserve the section entitled ``History'', and its title, and add to
18659it an item stating at least the title, year, new authors, and
18660publisher of the Modified Version as given on the Title Page. If
18661there is no section entitled ``History'' in the Document, create one
18662stating the title, year, authors, and publisher of the Document as
18663given on its Title Page, then add an item describing the Modified
18664Version as stated in the previous sentence.
18665
18666@item
18667Preserve the network location, if any, given in the Document for
18668public access to a Transparent copy of the Document, and likewise
18669the network locations given in the Document for previous versions
18670it was based on. These may be placed in the ``History'' section.
18671You may omit a network location for a work that was published at
18672least four years before the Document itself, or if the original
18673publisher of the version it refers to gives permission.
18674
18675@item
18676In any section entitled ``Acknowledgments'' or ``Dedications'',
18677preserve the section's title, and preserve in the section all the
18678substance and tone of each of the contributor acknowledgments
18679and/or dedications given therein.
18680
18681@item
18682Preserve all the Invariant Sections of the Document,
18683unaltered in their text and in their titles. Section numbers
18684or the equivalent are not considered part of the section titles.
18685
18686@item
18687Delete any section entitled ``Endorsements''. Such a section
18688may not be included in the Modified Version.
18689
18690@item
18691Do not retitle any existing section as ``Endorsements''
18692or to conflict in title with any Invariant Section.
18693@end enumerate
18694
18695If the Modified Version includes new front-matter sections or
18696appendices that qualify as Secondary Sections and contain no material
18697copied from the Document, you may at your option designate some or all
18698of these sections as invariant. To do this, add their titles to the
18699list of Invariant Sections in the Modified Version's license notice.
18700These titles must be distinct from any other section titles.
18701
18702You may add a section entitled ``Endorsements'', provided it contains
18703nothing but endorsements of your Modified Version by various
18704parties---for example, statements of peer review or that the text has
18705been approved by an organization as the authoritative definition of a
18706standard.
18707
18708You may add a passage of up to five words as a Front-Cover Text, and a
18709passage of up to 25 words as a Back-Cover Text, to the end of the list
18710of Cover Texts in the Modified Version. Only one passage of
18711Front-Cover Text and one of Back-Cover Text may be added by (or
18712through arrangements made by) any one entity. If the Document already
18713includes a cover text for the same cover, previously added by you or
18714by arrangement made by the same entity you are acting on behalf of,
18715you may not add another; but you may replace the old one, on explicit
18716permission from the previous publisher that added the old one.
18717
18718The author(s) and publisher(s) of the Document do not by this License
18719give permission to use their names for publicity for or to assert or
18720imply endorsement of any Modified Version.
18721
18722@item
18723COMBINING DOCUMENTS
18724
18725You may combine the Document with other documents released under this
18726License, under the terms defined in section 4 above for modified
18727versions, provided that you include in the combination all of the
18728Invariant Sections of all of the original documents, unmodified, and
18729list them all as Invariant Sections of your combined work in its
18730license notice.
18731
18732The combined work need only contain one copy of this License, and
18733multiple identical Invariant Sections may be replaced with a single
18734copy. If there are multiple Invariant Sections with the same name but
18735different contents, make the title of each such section unique by
18736adding at the end of it, in parentheses, the name of the original
18737author or publisher of that section if known, or else a unique number.
18738Make the same adjustment to the section titles in the list of
18739Invariant Sections in the license notice of the combined work.
18740
18741In the combination, you must combine any sections entitled ``History''
18742in the various original documents, forming one section entitled
18743``History''; likewise combine any sections entitled ``Acknowledgments'',
18744and any sections entitled ``Dedications''. You must delete all sections
18745entitled ``Endorsements.''
18746
18747@item
18748COLLECTIONS OF DOCUMENTS
18749
18750You may make a collection consisting of the Document and other documents
18751released under this License, and replace the individual copies of this
18752License in the various documents with a single copy that is included in
18753the collection, provided that you follow the rules of this License for
18754verbatim copying of each of the documents in all other respects.
18755
18756You may extract a single document from such a collection, and distribute
18757it individually under this License, provided you insert a copy of this
18758License into the extracted document, and follow this License in all
18759other respects regarding verbatim copying of that document.
18760
18761@item
18762AGGREGATION WITH INDEPENDENT WORKS
18763
18764A compilation of the Document or its derivatives with other separate
18765and independent documents or works, in or on a volume of a storage or
18766distribution medium, does not as a whole count as a Modified Version
18767of the Document, provided no compilation copyright is claimed for the
18768compilation. Such a compilation is called an ``aggregate'', and this
18769License does not apply to the other self-contained works thus compiled
18770with the Document, on account of their being thus compiled, if they
18771are not themselves derivative works of the Document.
18772
18773If the Cover Text requirement of section 3 is applicable to these
18774copies of the Document, then if the Document is less than one quarter
18775of the entire aggregate, the Document's Cover Texts may be placed on
18776covers that surround only the Document within the aggregate.
18777Otherwise they must appear on covers around the whole aggregate.
18778
18779@item
18780TRANSLATION
18781
18782Translation is considered a kind of modification, so you may
18783distribute translations of the Document under the terms of section 4.
18784Replacing Invariant Sections with translations requires special
18785permission from their copyright holders, but you may include
18786translations of some or all Invariant Sections in addition to the
18787original versions of these Invariant Sections. You may include a
18788translation of this License provided that you also include the
18789original English version of this License. In case of a disagreement
18790between the translation and the original English version of this
18791License, the original English version will prevail.
18792
18793@item
18794TERMINATION
18795
18796You may not copy, modify, sublicense, or distribute the Document except
18797as expressly provided for under this License. Any other attempt to
18798copy, modify, sublicense or distribute the Document is void, and will
18799automatically terminate your rights under this License. However,
18800parties who have received copies, or rights, from you under this
18801License will not have their licenses terminated so long as such
18802parties remain in full compliance.
18803
18804@item
18805FUTURE REVISIONS OF THIS LICENSE
18806
18807The Free Software Foundation may publish new, revised versions
18808of the GNU Free Documentation License from time to time. Such new
18809versions will be similar in spirit to the present version, but may
18810differ in detail to address new problems or concerns. See
18811@uref{http://www.gnu.org/copyleft/}.
18812
18813Each version of the License is given a distinguishing version number.
18814If the Document specifies that a particular numbered version of this
18815License ``or any later version'' applies to it, you have the option of
18816following the terms and conditions either of that specified version or
18817of any later version that has been published (not as a draft) by the
18818Free Software Foundation. If the Document does not specify a version
18819number of this License, you may choose any version ever published (not
18820as a draft) by the Free Software Foundation.
18821@end enumerate
18822
18823@page
18824@appendixsubsec ADDENDUM: How to use this License for your documents
18825
18826To use this License in a document you have written, include a copy of
18827the License in the document and put the following copyright and
18828license notices just after the title page:
18829
18830@smallexample
18831@group
18832 Copyright (C) @var{year} @var{your name}.
18833 Permission is granted to copy, distribute and/or modify this document
18834 under the terms of the GNU Free Documentation License, Version 1.1
18835 or any later version published by the Free Software Foundation;
18836 with the Invariant Sections being @var{list their titles}, with the
18837 Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}.
18838 A copy of the license is included in the section entitled ``GNU
18839 Free Documentation License''.
18840@end group
18841@end smallexample
18842
18843If you have no Invariant Sections, write ``with no Invariant Sections''
18844instead of saying which ones are invariant. If you have no
18845Front-Cover Texts, write ``no Front-Cover Texts'' instead of
18846``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
18847
18848If your document contains nontrivial examples of program code, we
18849recommend releasing these examples in parallel under your choice of
18850free software license, such as the GNU General Public License,
18851to permit their use in free software.
18852
18853
18854@node Command and Variable Index
18855@unnumbered Command and Variable Index
18856
18857This is an alphabetical list of all the @@-commands, assorted Emacs Lisp
18858functions, and several variables. To make the list easier to use, the
18859commands are listed without their preceding @samp{@@}.@refill
18860
18861@printindex fn
18862
18863
18864@node Concept Index
18865@unnumbered Concept Index
18866
18867@printindex cp
18868
18869
18870@bye
2@c $Id: texinfo.txi,v 1.192 2002/03/04 14:52:52 karl Exp $
3@c %**start of header
4
5@c All text is ignored before the setfilename.
6@setfilename texinfo
7
8@include version.texi
9@settitle Texinfo @value{VERSION}
10
11@c Define a new index for options.
12@defcodeindex op
13@c Put everything except function (command, in this case) names in one
14@c index (arbitrarily chosen to be the concept index).
15@syncodeindex op cp
16@syncodeindex vr cp
17@syncodeindex pg cp
18
19@footnotestyle separate
20@paragraphindent 2
21@c finalout
22
23@comment %**end of header
24
25@dircategory Texinfo documentation system
26@direntry
27* Texinfo: (texinfo). The GNU documentation format.
28* install-info: (texinfo)Invoking install-info. Update info/dir entries.
29* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
30* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
31* makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source.
32@end direntry
--- 4 unchanged lines hidden (view full) ---
37@c Set smallbook if printing in smallbook format so the example of the
38@c smallbook font is actually written using smallbook; in bigbook, a kludge
39@c is used for TeX output. Do this through the -t option to texi2dvi,
40@c so this same source can be used for other paper sizes as well.
41@c smallbook
42@c set smallbook
43@c @@clear smallbook
44
45@c If you like blank pages. Can add through texi2dvi -t.
46@c setchapternewpage odd
47
48@c Currently undocumented command, 5 December 1993:
49@c nwnode (Same as node, but no warnings; for `makeinfo'.)
50
51@ifinfo
52This file documents Texinfo, a documentation system that can produce
53both online information and a printed manual from a single source. This
54edition is for Texinfo version @value{VERSION}, @value{UPDATED}.
55
56Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99, 2000, 01, 02
57Free Software Foundation, Inc.
58
59Permission is granted to copy, distribute and/or modify this document
60under the terms of the GNU Free Documentation License, Version 1.1 or
61any later version published by the Free Software Foundation; with the
62Invariant Section being ``History'', with no Front-Cover Texts, and with
63no Back-Cover Texts. A copy of the license is included in the section
64entitled ``GNU Free Documentation License''.
65@end ifinfo
66
67
68@shorttitlepage Texinfo
69
70@titlepage
71@title Texinfo
72@subtitle The GNU Documentation Format
73@subtitle for Texinfo version @value{VERSION}, @value{UPDATED}
74
75@author Robert J. Chassell
76@author Richard M. Stallman
77
78@c Include the Distribution inside the titlepage so
79@c that headings are turned off.
80
81@page
82@vskip 0pt plus 1filll
83Copyright @copyright{} 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99, 2000, 01, 02
84Free Software Foundation, Inc.
85
86This manual is for Texinfo version @value{VERSION}, @value{UPDATED}.
87
88Published by the Free Software Foundation @*
8959 Temple Place Suite 330 @*
90Boston, MA 02111-1307 @*
91USA @*
92ISBN 1-882114-67-1 @c for version 4.0, September 1999.
93@c ISBN 1-882114-65-5 @c for version 3.12, March 1998.
94@c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995
95@c ISBN 1-882114-64-7 is for edition 2.24 of November 1996.
96
97Cover art by Etienne Suvasa.
98
99Permission is granted to copy, distribute and/or modify this document
100under the terms of the GNU Free Documentation License, Version 1.1 or
101any later version published by the Free Software Foundation; with the
102Invariant Section being ``History'', with no Front-Cover Texts, and with
103no Back-Cover Texts. A copy of the license is included in the section
104entitled ``GNU Free Documentation License''.
105
106@end titlepage
107
108@summarycontents
109@contents
110
111@ifnottex
112@node Top
113@top Texinfo
114
115Texinfo is a documentation system that uses a single source to produce
116both online information and printed output.
117
118The first part of this master menu lists the major nodes in this Info
119document, including the @@-command and concept indices. The rest of
120the menu lists all the lower level nodes in the document.
121
122This is Edition @value{VERSION} of the Texinfo manual, updated @value{UPDATED}.
123@end ifnottex
124
125@menu
126* Copying:: Your rights.
127* Overview:: Texinfo in brief.
128* Texinfo Mode:: How to use Texinfo mode.
129* Beginning a File:: What is at the beginning of a Texinfo file?
130* Ending a File:: What is at the end of a Texinfo file?
131* Structuring:: How to create chapters, sections, subsections,
132 appendices, and other parts.
133* Nodes:: How to write nodes.
134* Menus:: How to write menus.
--- 11 unchanged lines hidden (view full) ---
146* Conditionals:: How to specify text for either @TeX{} or Info.
147* Internationalization::
148* Defining New Texinfo Commands::
149* Hardcopy:: How to convert a Texinfo file to a file
150 for printing and how to print that file.
151* Creating and Installing Info Files::
152* Command List:: All the Texinfo @@-commands.
153* Tips:: Hints on how to write a Texinfo document.
154* Sample Texinfo File:: A sample Texinfo file to look at.
155* Include Files:: How to incorporate other Texinfo files.
156* Headings:: How to write page headings and footings.
157* Catching Mistakes:: How to find formatting mistakes.
158* Refilling Paragraphs:: All about paragraph refilling.
159* Command Syntax:: A description of @@-Command syntax.
160* Obtaining TeX:: How to Obtain @TeX{}.
161* Documentation Copying:: The GNU Free Documentation License.
162* Command and Variable Index:: A menu containing commands and variables.
163* Concept Index:: A menu covering many topics.
164
165@detailmenu
166 --- The Detailed Node Listing ---
167
168Overview of Texinfo
169
--- 27 unchanged lines hidden (view full) ---
197* Updating Requirements:: How to structure a Texinfo file for
198 using the updating command.
199* Other Updating Commands:: How to indent descriptions, insert
200 missing nodes lines, and update
201 nodes in sequence.
202
203Beginning a Texinfo File
204
205* Four Parts:: Four parts begin a Texinfo file.
206* Sample Beginning:: Here is a sample beginning for a Texinfo file.
207* Header:: The very beginning of a Texinfo file.
208* Info Summary and Permissions:: Summary and copying permissions for Info.
209* Titlepage & Copyright Page:: Creating the title and copyright pages.
210* The Top Node:: Creating the `Top' node and master menu.
211* Software Copying Permissions:: Ensure that you and others continue to
212 have the right to use and share software.
213
214The Texinfo File Header
215
216* First Line:: The first line of a Texinfo file.
217* Start of Header:: Formatting a region requires this.
218* setfilename:: Tell Info the name of the Info file.
219* settitle:: Create a title for the printed work.
220* documentdescription:: Document summary for the HTML output.
221* setchapternewpage:: Start chapters on right-hand pages.
222* paragraphindent:: Specify paragraph indentation.
223* exampleindent:: Specify environment indentation.
224* End of Header:: Formatting a region requires this.
225
226The Title and Copyright Pages
227
228* titlepage:: Create a title for the printed document.
229* titlefont center sp:: The @code{@@titlefont}, @code{@@center},
230 and @code{@@sp} commands.
231* title subtitle author:: The @code{@@title}, @code{@@subtitle},
232 and @code{@@author} commands.
233* Copyright & Permissions:: How to write the copyright notice and
234 include copying permissions.
235* end titlepage:: Turn on page headings after the title and
236 copyright pages.
237* headings on off:: An option for turning headings on and off
238 and double or single sided printing.
239
240The `Top' Node and Master Menu
241
242* Title of Top Node:: Sketch what the file is about.
243* Master Menu Parts:: A master menu has three or more parts.
244
245Ending a Texinfo File
246
247* Printing Indices & Menus:: How to print an index in hardcopy and
248 generate index menus in Info.
249* Contents:: How to create a table of contents.
250* File End:: How to mark the end of a file.
251
252Chapter Structuring
--- 23 unchanged lines hidden (view full) ---
276The @code{@@node} Command
277
278* Node Names:: How to choose node and pointer names.
279* Writing a Node:: How to write an @code{@@node} line.
280* Node Line Tips:: Keep names short.
281* Node Line Requirements:: Keep names unique, without @@-commands.
282* First Node:: How to write a `Top' node.
283* makeinfo top command:: How to use the @code{@@top} command.
284* Top Node Summary:: Write a brief description for readers.
285
286Menus
287
288* Menu Location:: Put a menu in a short node.
289* Writing a Menu:: What is a menu?
290* Menu Parts:: A menu entry has three parts.
291* Less Cluttered Menu Entry:: Two part menu entry.
292* Menu Example:: Two and three part menu entries.
--- 26 unchanged lines hidden (view full) ---
319
320Indicating Definitions, Commands, etc.
321
322* Useful Highlighting:: Highlighting provides useful information.
323* code:: Indicating program code.
324* kbd:: Showing keyboard input.
325* key:: Specifying keys.
326* samp:: A literal sequence of characters.
327* verb:: A verbatim sequence of characters.
328* var:: Indicating metasyntactic variables.
329* env:: Indicating environment variables.
330* file:: Indicating file names.
331* command:: Indicating command names.
332* option:: Indicating option names.
333* dfn:: Specifying definitions.
334* cite:: Referring to books not in the Info system.
335* acronym:: Indicating acronyms.
--- 7 unchanged lines hidden (view full) ---
343* Fonts:: Various font commands for printed output.
344
345Quotations and Examples
346
347* Block Enclosing Commands:: Different constructs for different purposes.
348* quotation:: Writing a quotation.
349* example:: Writing an example in a fixed-width font.
350* verbatim:: Writing a verbatim example.
351* verbatiminclude:: Including a file verbatim.
352* lisp:: Illustrating Lisp code.
353* small:: Forms for @code{@@smallbook}.
354* display:: Writing an example in the current font.
355* format:: Writing an example without narrowed margins.
356* exdent:: Undo indentation on a line.
357* flushleft & flushright:: Pushing text flush left or flush right.
358* noindent:: Preventing paragraph indentation.
359* cartouche:: Drawing rounded rectangles around examples.
--- 171 unchanged lines hidden (view full) ---
531* pagesizes:: How to print with customized page sizes.
532* Cropmarks and Magnification:: How to print marks to indicate the size
533 of pages and how to print scaled up output.
534* PDF Output:: Portable Document Format output.
535
536Creating and Installing Info Files
537
538* Creating an Info File::
539* Installing an Info File::
540
541Creating an Info File
542
543* makeinfo advantages:: @code{makeinfo} provides better error checking.
544* Invoking makeinfo:: How to run @code{makeinfo} from a shell.
545* makeinfo options:: Specify fill-column and other options.
546* Pointer Validation:: How to check that pointers point somewhere.
547* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs.
--- 10 unchanged lines hidden (view full) ---
558* Directory File:: The top level menu for all Info files.
559* New Info File:: Listing a new Info file.
560* Other Info Directories:: How to specify Info files that are
561 located in other directories.
562* Installing Dir Entries:: How to specify what menu entry to add
563 to the Info directory.
564* Invoking install-info:: @code{install-info} options.
565
566Include Files
567
568* Using Include Files:: How to use the @code{@@include} command.
569* texinfo-multiple-files-update:: How to create and update nodes and
570 menus when using included files.
571* Include File Requirements:: What @code{texinfo-multiple-files-update} expects.
572* Sample Include File:: A sample outer file with included files
573 within it; and a sample included file.
--- 18 unchanged lines hidden (view full) ---
592
593Finding Badly Referenced Nodes
594
595* Using Info-validate:: How to run @code{Info-validate}.
596* Unsplit:: How to create an unsplit file.
597* Tagifying:: How to tagify a file.
598* Splitting:: How to split a file manually.
599
600@end detailmenu
601@end menu
602
603@c Reward readers for getting to the end of the menu :).
604@c Contributed by Arnold Robbins.
605@quotation
606Documentation is like sex: when it is good, it is very, very good; and
607when it is bad, it is better than nothing.
608---Dick Brandon
609@end quotation
610
611
612@node Copying
613@unnumbered Texinfo Copying Conditions
614@cindex Copying conditions
615@cindex Conditions for copying Texinfo
616
617The programs currently being distributed that relate to Texinfo include
618@code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}.
619These programs are @dfn{free}; this means that everyone is free to use
620them and free to redistribute them on a free basis. The Texinfo-related
--- 19 unchanged lines hidden (view full) ---
640out that there is no warranty for the programs that relate to Texinfo.
641If these programs are modified by someone else and passed on, we want
642their recipients to know that what they have is not what we distributed,
643so that any problems introduced by others will not reflect on our
644reputation.
645
646The precise conditions of the licenses for the programs currently being
647distributed that relate to Texinfo are found in the General Public
648Licenses that accompany them.
649
650
651@node Overview
652@chapter Overview of Texinfo
653@cindex Overview of Texinfo
654@cindex Texinfo overview
655
656@dfn{Texinfo}@footnote{The first syllable of ``Texinfo'' is pronounced
--- 37 unchanged lines hidden (view full) ---
694from @uref{ftp://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide.
695
696@cindex Checklist for bug reports
697For bug reports, please include enough information for the maintainers
698to reproduce the problem. Generally speaking, that means:
699
700@itemize @bullet
701@item the version number of Texinfo and the program(s) or manual(s) involved.
702@item hardware, operating system, and compiler versions.
703@item any unusual options you gave to @command{configure}.
704@item the contents of any input files necessary to reproduce the bug.
705@item a description of the problem and samples of any erroneous output.
706@item anything else that you think would be helpful.
707@end itemize
708
709When in doubt whether something is needed or not, include it. It's
710better to include too much than to leave out something important.
711
712Patches are most welcome; if possible, please make them with
713@samp{@w{diff -c}} (@pxref{Top,, Overview, diffutils, Comparing and
714Merging Files}) and include @file{ChangeLog} entries (@pxref{Change
715Log,,, emacs, The GNU Emacs Manual}).
716
717When sending patches, if possible please do not encode or split them in
718any way; it's much easier to deal with one plain text message, however
719large, than many small ones. @uref{ftp://ftp.gnu.org/gnu/sharutils/,
--- 13 unchanged lines hidden (view full) ---
733indices. From the same Texinfo source file, you can create a
734menu-driven, online Info file with nodes, menus, cross references, and
735indices. You can also create from that same source file an HTML output
736file suitable for use with a web browser, or an XML file. @cite{The GNU
737Emacs Manual} is a good example of a Texinfo file, as is this manual.
738
739To make a printed document, you process a Texinfo source file with the
740@TeX{} typesetting program (but the Texinfo language is very different
741from @TeX{}'s usual language, plain @TeX{}). This creates a DVI file
742that you can typeset and print as a book or report (@pxref{Hardcopy}).
743
744@pindex makeinfo
745To output an Info file, process your Texinfo source with the
746@code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command.
747You can install the result in your Info tree (@pxref{Installing an Info
748File}).
749
750To output an HTML file, run @code{makeinfo --html} on your Texinfo
751source. You can (for example) install the result on your web site.
752
753@cindex Docbook, converting to Texinfo
754@cindex Conversion, from Docbook to Texinfo
755To output an XML file, run @code{makeinfo --xml} on your Texinfo source.
756To output DocBook, run @code{makeinfo --docbook}. If you want to
757convert from Docbook @emph{to} Texinfo, please see
758@uref{http://docbook2X.sourceforge.net/}.
759
760@cindex Output formats, supporting more
761@cindex SGML-tools output format
762If you are a programmer and would like to contribute to the GNU project
763by implementing additional output formats for Texinfo, that would be
764excellent. But please do not write a separate translator texi2foo for
765your favorite format foo! That is the hard way to do the job, and makes
766extra work in subsequent maintenance, since the Texinfo language is
767continually being enhanced and updated. Instead, the best approach is
768modify @code{makeinfo} to generate the new format, as it does now for
769Info and HTML.
770
771@TeX{} works with virtually all printers; Info works with virtually all
772computer terminals; the HTML output works with virtually all web
773browsers. Thus Texinfo can be used by almost any computer user.
774
775@cindex Source file
776A Texinfo source file is a plain @sc{ascii} file containing text and
777@dfn{@@-commands} (words preceded by an @samp{@@}) that tell the
--- 14 unchanged lines hidden (view full) ---
792
793@cindex Man page output, not supported
794From time to time, proposals are made to generate traditional Unix man
795pages from Texinfo source. This is not likely to ever be supported,
796because man pages have a very strict conventional format. Merely
797enhancing @command{makeinfo} to output troff format would be
798insufficient. Generating a good man page therefore requires a
799completely different source than the typical Texinfo applications of
800generating a good user manual or a good reference manual. This makes
801generating man pages incompatible with the Texinfo design goal of not
802having to document the same information in different ways for different
803output formats. You might as well just write the man page directly.
804
805@pindex help2man
806@cindex O'Dea, Brendan
807If you wish to support man pages, the program @command{help2man} may be
808useful; it generates a traditional man page from the @samp{--help}
809output of a program. In fact, this is currently used to generate man
810pages for the Texinfo programs themselves. It is GNU software written
811by Brendan O'Dea, available from
812@uref{http://www.ozemail.com.au/~bod/help2man.tar.gz}.
813
814
815@node Info Files
816@section Info files
817@cindex Info files
818
819An Info file is a Texinfo file formatted so that the Info documentation
820reading program can operate on it. (@code{makeinfo}
821and @code{texinfo-format-buffer} are two commands that convert a Texinfo file
822into an Info file.)@refill
823
824Info files are divided into pieces called @dfn{nodes}, each of which
825contains the discussion of one topic. Each node has a name, and
826contains both text for the user to read and pointers to other nodes,
827which are identified by their names. The Info program displays one node
828at a time, and provides commands with which the user can move to other
829related nodes.@refill
830
831@ifinfo
832@inforef{Top, info, info}, for more information about using Info.@refill
833@end ifinfo
834
835Each node of an Info file may have any number of child nodes that
836describe subtopics of the node's topic. The names of child
837nodes are listed in a @dfn{menu} within the parent node; this
838allows you to use certain Info commands to move to one of the child
839nodes. Generally, an Info file is organized like a book. If a node
840is at the logical level of a chapter, its child nodes are at the level
841of sections; likewise, the child nodes of sections are at the level
842of subsections.@refill
843
844All the children of any one parent are linked together in a
845bidirectional chain of `Next' and `Previous' pointers. The `Next'
846pointer provides a link to the next section, and the `Previous' pointer
847provides a link to the previous section. This means that all the nodes
848that are at the level of sections within a chapter are linked together.
849Normally the order in this chain is the same as the order of the
850children in the parent's menu. Each child node records the parent node
851name as its `Up' pointer. The last child has no `Next' pointer, and the
852first child has the parent both as its `Previous' and as its `Up'
853pointer.@footnote{In some documents, the first child has no `Previous'
854pointer. Occasionally, the last child has the node name of the next
855following higher level node as its `Next' pointer.}@refill
856
857The book-like structuring of an Info file into nodes that correspond
858to chapters, sections, and the like is a matter of convention, not a
859requirement. The `Up', `Previous', and `Next' pointers of a node can
860point to any other nodes, and a menu can contain any other nodes.
861Thus, the node structure can be any directed graph. But it is usually
862more comprehensible to follow a structure that corresponds to the
863structure of chapters and sections in a printed book or report.@refill
--- 82 unchanged lines hidden (view full) ---
946file @file{texinfo.tex} that contains information (definitions or
947@dfn{macros}) that @TeX{} uses when it typesets a Texinfo file.
948(@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands
949to @TeX{} commands, which @TeX{} can then process to create the typeset
950document.) @file{texinfo.tex} contains the specifications for printing
951a document. You can get the latest version of @file{texinfo.tex} from
952@uref{ftp://ftp.gnu.org/gnu/texinfo.tex}.
953
954Most often, documents are printed on 8.5 inch by 11 inch pages
955(216@dmn{mm} by 280@dmn{mm}; this is the default size), but you can also
956print for 7 inch by 9.25 inch pages (178@dmn{mm} by 235@dmn{mm}; the
957@code{@@smallbook} size) or on A4 or A5 size paper (@code{@@afourpaper},
958@code{@@afivepaper}). (@xref{smallbook, , Printing ``Small'' Books}.
959Also, see @ref{A4 Paper, ,Printing on A4 Paper}.)
960
961By changing the parameters in @file{texinfo.tex}, you can change the
962size of the printed document. In addition, you can change the style in
963which the printed document is formatted; for example, you can change the
964sizes and fonts used, the amount of indentation for each paragraph, the
965degree to which words are hyphenated, and the like. By changing the
966specifications, you can make a book look dignified, old and serious, or
967light-hearted, young and cheery.@refill
968
969@TeX{} is freely distributable. It is written in a superset of Pascal
970called WEB and can be compiled either in Pascal or (by using a
971conversion program that comes with the @TeX{} distribution) in C.
972(@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information
973about @TeX{}.)@refill
974
975@TeX{} is very powerful and has a great many features. Because a
976Texinfo file must be able to present information both on a
977character-only terminal in Info form and in a typeset book, the
978formatting commands that Texinfo supports are necessarily
979limited.@refill
980
981To get a copy of @TeX{}, see
982@ref{Obtaining TeX, , How to Obtain @TeX{}}.
983
984
985@node Formatting Commands, Conventions, Printed Books, Overview
986@section @@-commands
987@cindex @@-commands
988@cindex Formatting commands
989
990In a Texinfo file, the commands that tell @TeX{} how to typeset the
991printed manual and tell @code{makeinfo} and
992@code{texinfo-format-buffer} how to create an Info file are preceded
993by @samp{@@}; they are called @dfn{@@-commands}. For example,
994@code{@@node} is the command to indicate a node and @code{@@chapter}
995is the command to indicate the start of a chapter.@refill
996
997@quotation
998@strong{Please note:} All the @@-commands, with the exception of the
999@code{@@TeX@{@}} command, must be written entirely in lower
1000case.@refill
1001@end quotation
1002
1003The Texinfo @@-commands are a strictly limited set of constructs. The
1004strict limits make it possible for Texinfo files to be understood both
1005by @TeX{} and by the code that converts them into Info files. You can
1006display Info files on any terminal that displays alphabetic and
1007numeric characters. Similarly, you can print the output generated by
1008@TeX{} on a wide variety of printers.@refill
--- 53 unchanged lines hidden (view full) ---
1062
1063As you gain experience with Texinfo, you will rapidly learn how to
1064write the different commands: the different ways to write commands
1065make it easier to write and read Texinfo files than if all commands
1066followed exactly the same syntax. (For details about @@-command
1067syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill
1068
1069
1070@node Conventions, Comments, Formatting Commands, Overview
1071@section General Syntactic Conventions
1072@cindex General syntactic conventions
1073@cindex Syntactic conventions
1074@cindex Conventions, syntactic
1075
1076This section describes the general conventions used in all Texinfo documents.
1077
1078@itemize @bullet
1079@item
1080All printable @sc{ascii} characters except @samp{@@}, @samp{@{} and
1081@samp{@}} can appear in a Texinfo file and stand for themselves.
1082@samp{@@} is the escape character which introduces commands.
1083@samp{@{} and @samp{@}} should be used only to surround arguments to
1084certain commands. To put one of these special characters into the
1085document, put an @samp{@@} character in front of it, like this:
1086@samp{@@@@}, @samp{@@@{}, and @samp{@@@}}.@refill
1087
1088@item
1089@ifinfo
1090It is customary in @TeX{} to use doubled single-quote characters to
1091begin and end quotations: ` ` and ' ' (but without a space between the
1092two single-quote characters). This convention should be followed in
1093Texinfo files. @TeX{} converts doubled single-quote characters to
1094left- and right-hand doubled quotation marks and Info converts doubled
1095single-quote characters to @sc{ascii} double-quotes: ` ` and ' ' to " .@refill
1096@end ifinfo
1097@iftex
1098It is customary in @TeX{} to use doubled single-quote characters to
1099begin and end quotations: @w{@t{ `` }} and @w{@t{ '' }}. This
1100convention should be followed in Texinfo files. @TeX{} converts
1101doubled single-quote characters to left- and right-hand doubled
1102quotation marks, ``like this'', and Info converts doubled single-quote
1103characters to @sc{ascii} double-quotes: @w{@t{ `` }} and
1104@w{@t{ '' }} to @w{@t{ " }}.@refill
1105@end iftex
1106
1107@item
1108Use three hyphens in a row, @samp{---}, for a dash---like this. In
1109@TeX{}, a single or double hyphen produces a printed dash that is
1110shorter than the usual typeset dash. Info reduces three hyphens to two
1111for display on the screen.
1112
1113@item
1114To prevent a paragraph from being indented in the printed manual, put
1115the command @code{@@noindent} on a line by itself before the
1116paragraph.@refill
1117
1118@item
1119If you mark off a region of the Texinfo file with the @code{@@iftex}
1120and @w{@code{@@end iftex}} commands, that region will appear only in
1121the printed copy; in that region, you can use certain commands
1122borrowed from plain @TeX{} that you cannot use in Info. Likewise, if
1123you mark off a region with the @code{@@ifinfo} and @code{@@end ifinfo}
1124commands, that region will appear only in the Info file; in that
1125region, you can use Info commands that you cannot use in @TeX{}.
1126Similarly for @code{@@ifhtml @dots{} @@end ifhtml},
1127@code{@@ifnothtml @dots{} @@end ifnothtml},
1128@code{@@ifnotinfo @dots{} @@end ifnotinfo},
1129@code{@@ifnottex @dots{} @@end ifnottex}.
1130@xref{Conditionals}.
1131@end itemize
1132
1133@cindex Tabs; don't use!
1134@quotation
1135@strong{Caution:} Do not use tabs in a Texinfo file (except in verbatim
1136modes) ! @TeX{} uses variable-width fonts, which means that it is
1137impractical at best to define a tab to work in all circumstances.
1138Consequently, @TeX{} treats tabs like single spaces, and that is not
1139what they look like. Furthermore, @code{makeinfo} does nothing special
1140with tabs, and thus a tab character in your input file may appear
1141differently in the output, for example, in an indented example.
1142
1143@noindent
1144To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple
1145spaces when you press the @key{TAB} key.
1146
1147@noindent
1148Also, you can run @code{untabify} in Emacs to convert tabs in a region
1149to multiple spaces.
1150@end quotation
1151
1152
1153@node Comments, Minimum, Conventions, Overview
1154@section Comments
1155
1156You can write comments in a Texinfo file that will not appear in
1157either the Info file or the printed manual by using the
1158@code{@@comment} command (which may be abbreviated to @code{@@c}).
1159Such comments are for the person who revises the Texinfo file. All the
1160text on a line that follows either @code{@@comment} or @code{@@c} is a
1161comment; the rest of the line does not appear in either the Info file
1162or the printed manual. (Often, you can write the @code{@@comment} or
1163@code{@@c} in the middle of a line, and only the text that follows after
1164the @code{@@comment} or @code{@@c} command does not appear; but some
1165commands, such as @code{@@settitle} and @code{@@setfilename}, work on a
1166whole line. You cannot use @code{@@comment} or @code{@@c} in a line
1167beginning with such a command.)@refill
1168@cindex Comments
1169@findex comment
1170@findex c @r{(comment)}
1171
1172You can write long stretches of text that will not appear in either
1173the Info file or the printed manual by using the @code{@@ignore} and
1174@code{@@end ignore} commands. Write each of these commands on a line
1175of its own, starting each command at the beginning of the line. Text
1176between these two commands does not appear in the processed output.
1177You can use @code{@@ignore} and @code{@@end ignore} for writing
1178comments.
1179
1180@cindex Ignored text
1181@cindex Unprocessed text
1182@findex ignore
1183@c !!! Perhaps include this comment about ignore and ifset:
1184@ignore
1185Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or
1186@code{@@ifclear} conditions is ignored in the sense that it will not
1187contribute to the formatted output. However, @TeX{} and makeinfo must
1188still parse the ignored text, in order to understand when to
1189@emph{stop} ignoring text from the source file; that means that you
1190will still get error messages if you have invalid Texinfo markup
1191within ignored text.
1192@end ignore
1193
1194
1195@node Minimum, Six Parts, Comments, Overview
1196@section What a Texinfo File Must Have
1197@cindex Minimal Texinfo file (requirements)
1198@cindex Must have in Texinfo file
1199@cindex Required in Texinfo file
1200@cindex Texinfo file minimum
1201
1202By convention, the names of Texinfo files end with one of the
1203extensions @file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}.
1204The longer extension is preferred since it describes more clearly to a
1205human reader the nature of the file. The shorter extensions are for
1206operating systems that cannot handle long file names.@refill
1207
1208In order to be made into a printed manual and an Info file, a Texinfo
1209file @strong{must} begin with lines like this:@refill
1210
1211@example
1212@group
1213\input texinfo
1214@@setfilename @var{info-file-name}
1215@@settitle @var{name-of-manual}
1216@end group
1217@end example
1218
1219@noindent
1220The contents of the file follow this beginning, and then you @strong{must} end
1221a Texinfo file with a line like this:@refill
1222
1223@example
1224@@bye
1225@end example
1226
1227@findex input @r{(@TeX{} command)}
1228@noindent
1229The @samp{\input texinfo} line tells @TeX{} to use the
1230@file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo
1231@@-commands into @TeX{} typesetting commands. (Note the use of the
1232backslash, @samp{\}; this is correct for @TeX{}.) The
1233@samp{@@setfilename} line provides a name for the Info file and tells
1234@TeX{} to open auxiliary files. The @samp{@@settitle} line specifies a
1235title for the page headers (or footers) of the printed manual, and the
1236default document description title for the @samp{<head>} in HTML format.
1237
1238The @code{@@bye} line at the end of the file on a line of its own tells
1239the formatters that the file is ended and to stop formatting.@refill
1240
1241Usually, you will not use quite such a spare format, but will include
1242mode setting and start-of-header and end-of-header lines at the
1243beginning of a Texinfo file, like this:@refill
1244
1245@example
1246@group
1247\input texinfo @@c -*-texinfo-*-
1248@@c %**start of header
1249@@setfilename @var{info-file-name}
1250@@settitle @var{name-of-manual}
1251@@c %**end of header
1252@end group
1253@end example
1254
1255@noindent
1256In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into
1257Texinfo mode when you edit the file.
1258
1259The @code{@@c} lines which surround the @samp{@@setfilename} and
1260@samp{@@settitle} lines are optional, but you need them in order to
1261run @TeX{} or Info on just part of the file. (@xref{Start of Header},
1262for more information.)@refill
1263
1264Furthermore, you will usually provide a Texinfo file with a title
1265page, indices, and the like. But the minimum, which can be useful
1266for short documents, is just the three lines at the beginning and the
1267one line at the end.@refill
1268
1269@node Six Parts, Short Sample, Minimum, Overview
1270@comment node-name, next, previous, up
1271@section Six Parts of a Texinfo File
1272
1273Generally, a Texinfo file contains more than the minimal
1274beginning and end---it usually contains six parts:@refill
1275
1276@table @r
1277@item 1. Header
1278The @dfn{Header} names the file, tells @TeX{} which definitions' file to
1279use, and performs other ``housekeeping'' tasks.@refill
1280
1281@item 2. Summary Description and Copyright
1282The @dfn{Summary Description and Copyright} segment describes the document
1283and contains the copyright notice and copying permissions for the Info
1284file. The segment must be enclosed between @code{@@ifinfo} and
1285@code{@@end ifinfo} commands so that the formatters place it only in the Info
1286file.@refill
1287
1288@item 3. Title and Copyright
1289The @dfn{Title and Copyright} segment contains the title and copyright pages
1290and copying permissions for the printed manual. The segment must be
1291enclosed between @code{@@titlepage} and @code{@@end titlepage} commands.
1292The title and copyright page appear only in the printed @w{manual}.@refill
1293
1294@item 4. `Top' Node and Master Menu
1295The @dfn{Master Menu} contains a complete menu of all the nodes in the whole
1296Info file. It appears only in the Info file, in the `Top' node.@refill
1297
1298@item 5. Body
1299The @dfn{Body} of the document may be structured like a traditional book or
1300encyclopedia or it may be free form.@refill
1301
1302@item 6. End
1303The @dfn{End} contains commands for printing indices and generating
1304the table of contents, and the @code{@@bye} command on a line of its
1305own.@refill
1306@end table
1307
1308@node Short Sample
1309@section A Short Sample Texinfo File
1310@cindex Sample Texinfo file
1311
1312Here is a complete but very short Texinfo file, in six parts. The first
1313three parts of the file, from @samp{\input texinfo} through to
1314@samp{@@end titlepage}, look more intimidating than they are. Most of
1315the material is standard boilerplate; when you write a manual, simply
1316insert the names for your own manual in this segment. (@xref{Beginning a
1317File}.)@refill
1318
1319In the following, the sample text is @emph{indented}; comments on it are
1320not. The complete file, without any comments, is shown in
1321@ref{Sample Texinfo File}.
1322
1323@subheading Part 1: Header
1324
1325@noindent
1326The header does not appear in either the Info file or the
1327printed output. It sets various parameters, including the
1328name of the Info file and the title used in the header.
1329
1330@example
1331@group
1332\input texinfo @@c -*-texinfo-*-
1333@@c %**start of header
1334@@setfilename sample.info
1335@@settitle Sample Document
1336@@setchapternewpage odd
1337@@c %**end of header
1338@end group
1339@end example
1340
1341@subheading Part 2: Summary Description and Copyright
1342
1343@noindent
1344The summary description and copyright segment does not
1345appear in the printed document.
1346
1347@example
1348@group
1349@@ifinfo
1350This is a short example of a complete Texinfo file.
1351
1352Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
1353@@end ifinfo
1354@end group
1355@end example
1356
1357@subheading Part 3: Titlepage and Copyright
1358
1359@noindent
1360The titlepage segment does not appear in the Info file.
1361
1362@example
1363@group
1364@@contents
1365@@titlepage
1366@@sp 10
1367@@title Sample Title
1368@end group
1369
1370@group
1371@@c The following two commands start the copyright page.
1372@@page
1373@@vskip 0pt plus 1filll
1374Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
1375@@end titlepage
1376@end group
1377@end example
1378
1379@subheading Part 4: `Top' Node and Master Menu
1380
1381@noindent
1382The `Top' node contains the master menu for the Info file.
1383Since a printed manual uses a table of contents rather than
1384a menu, the master menu appears only in online output.
1385
1386@example
1387@group
1388@@ifnottex
1389@@node Top
1390@@end ifnottex
1391@end group
1392@end example
1393
1394@example
1395@group
1396@@menu
1397* First Chapter:: The first chapter is the
1398 only chapter in this sample.
1399* Concept Index:: This index has two entries.
1400@@end menu
1401@end group
1402@end example
1403
1404@subheading Part 5: The Body of the Document
1405
1406@noindent
1407The body segment contains all the text of the document, but not the
1408indices or table of contents. This example illustrates a node and a
1409chapter containing an enumerated list.@refill
1410
1411@example
1412@group
1413@@node First Chapter
1414@@chapter First Chapter
1415@@cindex Chapter, first
1416@end group
1417
1418@group
1419This is the contents of the first chapter.
1420@@cindex Another sample index entry
1421@end group
1422
1423@group
1424Here is a numbered list.
1425
1426@@enumerate
1427@@item
1428This is the first item.
1429
1430@@item
1431This is the second item.
1432@@end enumerate
1433@end group
1434
1435@group
1436The @@code@{makeinfo@} command transforms a Texinfo file
1437such as this into an Info file or other output;
1438@@TeX@ typesets it for a printed manual.
1439@end group
1440@end example
1441
1442@subheading Part 6: The End of the Document
1443
1444@noindent
1445The end segment contains commands for generating an index in a node and
1446unnumbered chapter of its own, (usually) for generating the table of
1447contents, and the @code{@@bye} command that marks the end of the
1448document.@refill
1449
1450@example
1451@group
1452@@node Concept Index
1453@@unnumbered Concept Index
1454@end group
1455
1456@group
1457@@printindex cp
1458
1459@@bye
1460@end group
1461@end example
1462
1463@subheading The Results
1464
1465Here is what the contents of the first chapter of the sample look like:
1466
1467@sp 1
1468@need 700
1469@quotation
1470This is the contents of the first chapter.
1471
1472Here is a numbered list.
1473
1474@enumerate
1475@item
1476This is the first item.
1477
1478@item
1479This is the second item.
1480@end enumerate
1481
1482The @code{makeinfo} and @code{texinfo-format-buffer}
1483commands transform a Texinfo file such as this into
1484an Info file; and @TeX{} typesets it for a printed
1485manual.
1486@end quotation
1487
1488
1489@node History
1490@section History
1491
1492@cindex Stallman, Richard M.
1493@cindex Chassell, Robert J.
1494@cindex Berry, Karl
1495Richard M.@: Stallman invented the Texinfo format, wrote the initial
1496processors, and created Edition 1.0 of this manual. @w{Robert J.@:
1497Chassell} greatly revised and extended the manual, starting with Edition
14981.1. Brian Fox was responsible for the standalone Texinfo distribution
1499until version 3.8, and wrote the standalone @command{makeinfo} and
1500@command{info}. Karl Berry has made the updates since Texinfo 3.8 and
1501subsequent releases, starting with Edition 2.22 of the manual.
1502
1503@cindex Pinard, Fran@,{c}ois
1504@cindex Zuhn, David D.
1505@cindex Weisshaus, Melissa
1506@cindex Zaretskii, Eli
1507@cindex Schwab, Andreas
1508@cindex Weinberg, Zack
1509Our thanks go out to all who helped improve this work, particularly to
1510Fran@,{c}ois Pinard and @w{David D.@: Zuhn}, who tirelessly recorded and
1511reported mistakes and obscurities; our special thanks go to Melissa
1512Weisshaus for her frequent and often tedious reviews of nearly similar
1513editions. The indefatigable Eli Zaretskii and Andreas Schwab have
1514provided patches beyond counting. Zack Weinberg did the impossible by
1515implementing the macro syntax in @file{texinfo.tex}. Dozens of others
1516have contributed patches and suggestions, they are gratefully
1517acknowledged in the @file{ChangeLog} file. Our mistakes are our own.
1518
1519@cindex Scribe
1520@cindex Reid, Brian
1521@cindex History of Texinfo
1522A bit of history: in the 1970's at CMU, Brian Reid developed a program
1523and format named Scribe to mark up documents for printing. It used the
1524@code{@@} character to introduce commands as Texinfo does and strived to
1525describe document contents rather than formatting.
1526
1527@cindex Bolio
1528@cindex Bo@TeX{}
1529Meanwhile, people at MIT developed another, not too dissimilar format
1530called Bolio. This then was converted to using @TeX{} as its typesetting
1531language: Bo@TeX{}.
1532
1533Bo@TeX{} could only be used as a markup language for documents to be
1534printed, not for online documents. Richard Stallman (RMS) worked on
1535both Bolio and Bo@TeX{}. He also developed a nifty on-line help format
1536called Info, and then combined Bo@TeX{} and Info to create Texinfo, a
1537mark up language for text that is intended to be read both on line and
1538as printed hard copy.
1539
1540
1541
1542@node Texinfo Mode
1543@chapter Using Texinfo Mode
1544@cindex Texinfo mode
1545@cindex Mode, using Texinfo
1546@cindex GNU Emacs
1547@cindex Emacs
1548
1549You may edit a Texinfo file with any text editor you choose. A Texinfo
1550file is no different from any other @sc{ascii} file. However, GNU Emacs
1551comes with a special mode, called Texinfo
1552mode, that provides Emacs commands and tools to help ease your work.@refill
1553
1554This chapter describes features of GNU Emacs' Texinfo mode but not any
1555features of the Texinfo formatting language. If you are reading this
1556manual straight through from the beginning, you may want to skim through
1557this chapter briefly and come back to it after reading succeeding
1558chapters which describe the Texinfo formatting language in
1559detail.@refill
1560
1561@menu
1562* Texinfo Mode Overview:: How Texinfo mode can help you.
1563* Emacs Editing:: Texinfo mode adds to GNU Emacs' general
1564 purpose editing features.
1565* Inserting:: How to insert frequently used @@-commands.
1566* Showing the Structure:: How to show the structure of a file.
1567* Updating Nodes and Menus:: How to update or create new nodes and menus.
--- 477 unchanged lines hidden (view full) ---
2045Manual}).@refill
2046
2047Also, the @code{texinfo-indent-menu-description} command may be used to
2048indent existing menu descriptions to a specified column. Finally, if
2049you wish, you can use the @code{texinfo-insert-node-lines} command to
2050insert missing @code{@@node} lines into a file. (@xref{Other Updating
2051Commands}, for more information.)@refill
2052
2053@node Updating Requirements, Other Updating Commands, Updating Commands, Updating Nodes and Menus
2054@comment node-name, next, previous, up
2055@subsection Updating Requirements
2056@cindex Updating requirements
2057@cindex Requirements for updating commands
2058
2059To use the updating commands, you must organize the Texinfo file
2060hierarchically with chapters, sections, subsections, and the like.
2061When you construct the hierarchy of the manual, do not `jump down'
2062more than one level at a time: you can follow the `Top' node with a
2063chapter, but not with a section; you can follow a chapter with a
2064section, but not with a subsection. However, you may `jump up' any
2065number of levels at one time---for example, from a subsection to a
2066chapter.@refill
2067
2068Each @code{@@node} line, with the exception of the line for the `Top'
2069node, must be followed by a line with a structuring command such as
2070@code{@@chapter}, @code{@@section}, or
2071@code{@@unnumberedsubsec}.@refill
2072
2073Each @code{@@node} line/structuring-command line combination
2074must look either like this:@refill
2075
2076@example
2077@group
2078@@node Comments, Minimum, Conventions, Overview
2079@@comment node-name, next, previous, up
2080@@section Comments
2081@end group
2082@end example
2083
2084or like this (without the @code{@@comment} line):
2085
2086@example
2087@group
2088@@node Comments, Minimum, Conventions, Overview
2089@@section Comments
2090@end group
2091@end example
2092
2093@noindent
2094In this example, `Comments' is the name of both the node and the
2095section. The next node is called `Minimum' and the previous node is
2096called `Conventions'. The `Comments' section is within the `Overview'
2097node, which is specified by the `Up' pointer. (Instead of an
2098@code{@@comment} line, you may also write an @code{@@ifinfo} line.)@refill
2099
2100If a file has a `Top' node, it must be called @samp{top} or @samp{Top}
2101and be the first node in the file.@refill
2102
2103The menu updating commands create a menu of sections within a chapter,
2104a menu of subsections within a section, and so on. This means that
2105you must have a `Top' node if you want a menu of chapters.@refill
2106
2107Incidentally, the @code{makeinfo} command will create an Info file for a
2108hierarchically organized Texinfo file that lacks `Next', `Previous' and
2109`Up' pointers. Thus, if you can be sure that your Texinfo file will be
2110formatted with @code{makeinfo}, you have no need for the update node
2111commands. (@xref{Creating an Info File}, for more information about
2112@code{makeinfo}.) However, both @code{makeinfo} and the
2113@code{texinfo-format-@dots{}} commands require that you insert menus in
2114the file.
2115
2116@node Other Updating Commands, , Updating Requirements, Updating Nodes and Menus
2117@comment node-name, next, previous, up
2118@subsection Other Updating Commands
2119
2120In addition to the five major updating commands, Texinfo mode
2121possesses several less frequently used updating commands:@refill
2122
2123@table @kbd
2124@item M-x texinfo-insert-node-lines
2125@findex texinfo-insert-node-lines
--- 113 unchanged lines hidden (view full) ---
2239
2240@example
2241C-c C-m C-b
2242@exdent or
2243M-x makeinfo-buffer
2244@end example
2245
2246For @TeX{} or the Info formatting commands to work, the file @emph{must}
2247include a line that has @code{@@setfilename} in its header.@refill
2248
2249@xref{Creating an Info File}, for details about Info formatting.@refill
2250
2251@node Printing, Texinfo Mode Summary, Info Formatting, Texinfo Mode
2252@comment node-name, next, previous, up
2253@section Formatting and Printing
2254@cindex Formatting for printing
2255@cindex Printing a region or buffer
--- 232 unchanged lines hidden (view full) ---
2488@end group
2489
2490@group
2491M-x texinfo-sequential-node-update
2492 @r{Insert node pointers in strict sequence.}
2493@end group
2494@end example
2495
2496@node Beginning a File
2497@chapter Beginning a Texinfo File
2498@cindex Beginning a Texinfo file
2499@cindex Texinfo file beginning
2500@cindex File beginning
2501
2502Certain pieces of information must be provided at the beginning of a
2503Texinfo file, such as the name of the file and the title of the
2504document.@refill
2505
2506@menu
2507* Four Parts:: Four parts begin a Texinfo file.
2508* Sample Beginning:: Here is a sample beginning for a Texinfo file.
2509* Header:: The very beginning of a Texinfo file.
2510* Info Summary and Permissions:: Summary and copying permissions for Info.
2511* Titlepage & Copyright Page:: Creating the title and copyright pages.
2512* The Top Node:: Creating the `Top' node and master menu.
2513* Software Copying Permissions:: Ensure that you and others continue to
2514 have the right to use and share software.
2515@end menu
2516
2517@node Four Parts, Sample Beginning, Beginning a File, Beginning a File
2518@ifinfo
2519@heading Four Parts Begin a File
2520@end ifinfo
2521
2522Generally, the beginning of a Texinfo file has four parts:@refill
2523
2524@enumerate
2525@item
2526The header, delimited by special comment lines, that includes the
2527commands for naming the Texinfo file and telling @TeX{} what
2528definitions file to use when processing the Texinfo file.@refill
2529
2530@item
2531A short statement of what the file is about, with a copyright notice
2532and copying permissions. This is enclosed in @code{@@ifinfo} and
2533@code{@@end ifinfo} commands so that the formatters place it only
2534in the Info file.@refill
2535
2536@item
2537A title page and copyright page, with a copyright notice and copying
2538permissions. This is enclosed between @code{@@titlepage} and
2539@code{@@end titlepage} commands. The title and copyright page appear
2540only in the printed @w{manual}.@refill
2541
2542@item
2543The `Top' node that contains a menu for the whole Info file. The
2544contents of this node appear only in the Info file.@refill
2545@end enumerate
2546
2547Also, optionally, you may include the copying conditions for a program
2548and a warranty disclaimer. The copying section will be followed by an
2549introduction or else by the first chapter of the manual.@refill
2550
2551Since the copyright notice and copying permissions for the Texinfo
2552document (in contrast to the copying permissions for a program) are in
2553parts that appear only in the Info file or only in the printed manual,
2554this information must be given twice.@refill
2555
2556
2557@node Sample Beginning
2558@section Sample Texinfo File Beginning
2559
2560The following sample shows what is needed.@refill
2561
2562@example
2563\input texinfo @@c -*-texinfo-*-
2564@@c %**start of header
2565@@setfilename @var{name-of-info-file}
2566@@settitle @var{name-of-manual}
2567@@setchapternewpage odd
2568@@c %**end of header
2569
2570@@ifinfo
2571This file documents @dots{}
2572
2573Copyright @var{year} @var{copyright-owner}
2574
2575@group
2576Permission is granted to @dots{}
2577@@end ifinfo
2578@end group
2579
2580@group
2581@@c This title page illustrates only one of the
2582@@c two methods of forming a title page.
2583@end group
2584
2585@group
2586@@titlepage
2587@@title @var{name-of-manual-when-printed}
2588@@subtitle @var{subtitle-if-any}
2589@@subtitle @var{second-subtitle}
2590@@author @var{author}
2591@end group
2592
2593@group
2594@@c The following two commands
2595@@c start the copyright page.
2596@@page
2597@@vskip 0pt plus 1filll
2598Copyright @@copyright@{@} @var{year} @var{copyright-owner}
2599@end group
2600
2601Published by @dots{}
2602
2603Permission is granted to @dots{}
2604@@end titlepage
2605
2606@@ifnottex
2607@@node Top
2608@@top @var{title}
2609
2610This document describes @dots{}
2611
2612This document applies to version @dots{}
2613of the program named @dots{}
2614@@end ifnottex
2615
2616@group
2617@@menu
2618* Copying:: Your rights and freedoms.
2619* First Chapter:: Getting started @dots{}
2620* Second Chapter:: @dots{}
2621 @dots{}
2622 @dots{}
2623@@end menu
2624@end group
2625
2626@group
2627@@node First Chapter
2628@@chapter First Chapter
2629@@cindex Index entry for First Chapter
2630@end group
2631@end example
2632
2633
2634@node Header
2635@section The Texinfo File Header
2636@cindex Header for Texinfo files
2637@cindex Texinfo file header
2638
2639Texinfo files start with at least three lines that provide Info and
2640@TeX{} with necessary information. These are the @code{\input texinfo}
2641line, the @code{@@settitle} line, and the @code{@@setfilename} line. If
2642you want to run @TeX{} on just a part of the Texinfo file, you must
2643write the @code{@@settitle} and @code{@@setfilename} lines between
2644start-of-header and end-of-header lines.
2645
2646Thus, the beginning of a Texinfo file looks like this:
2647
2648@example
2649@group
2650\input texinfo @@c -*-texinfo-*-
2651@@setfilename sample.info
2652@@settitle Sample Document
2653@end group
2654@end example
2655
2656@noindent
2657or else like this:
2658
2659@example
2660@group
2661\input texinfo @@c -*-texinfo-*-
2662@@c %**start of header
2663@@setfilename sample.info
2664@@settitle Sample Document
2665@@c %**end of header
2666@end group
2667@end example
2668
2669@menu
2670* First Line:: The first line of a Texinfo file.
2671* Start of Header:: Formatting a region requires this.
2672* setfilename:: Tell Info the name of the Info file.
2673* settitle:: Create a title for the printed work.
2674* documentdescription:: Document summary for the HTML output.
2675* setchapternewpage:: Start chapters on right-hand pages.
2676* paragraphindent:: Specify paragraph indentation.
2677* exampleindent:: Specify environment indentation.
2678* End of Header:: Formatting a region requires this.
2679@end menu
2680
2681
2682@node First Line
2683@subsection The First Line of a Texinfo File
2684@cindex First line of a Texinfo file
2685@cindex Beginning line of a Texinfo file
2686@cindex Header of a Texinfo file
2687
2688Every Texinfo file that is to be the top-level input to @TeX{} must begin
2689with a line that looks like this:@refill
2690
2691@example
2692\input texinfo @@c -*-texinfo-*-
2693@end example
2694
2695@noindent
2696This line serves two functions:
2697
2698@enumerate
2699@item
2700When the file is processed by @TeX{}, the @samp{\input texinfo} command
2701tells @TeX{} to load the macros needed for processing a Texinfo file.
2702These are in a file called @file{texinfo.tex}, which is usually located
2703in the @file{/usr/lib/tex/macros} directory. @TeX{} uses the backslash,
2704@samp{\}, to mark the beginning of a command, just as Texinfo uses
2705@samp{@@}. The @file{texinfo.tex} file causes the switch from @samp{\}
2706to @samp{@@}; before the switch occurs, @TeX{} requires @samp{\}, which
2707is why it appears at the beginning of the file.@refill
2708
2709@item
2710When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode
2711specification tells Emacs to use Texinfo mode.@refill
2712@end enumerate
2713
2714
2715@node Start of Header
2716@subsection Start of Header
2717@cindex Start of header line
2718
2719Write a start-of-header line on the second line of a Texinfo file.
2720Follow the start-of-header line with @code{@@setfilename} and
2721@code{@@settitle} lines and, optionally, with other command lines, such
2722as @code{@@smallbook} or @code{@@footnotestyle}; and then by an
2723end-of-header line (@pxref{End of Header}).@refill
2724
2725With these lines, you can format part of a Texinfo file for Info or
2726typeset part for printing.@refill
2727
2728A start-of-header line looks like this:@refill
2729
2730@example
2731@@c %**start of header
2732@end example
2733
2734The odd string of characters, @samp{%**}, is to ensure that no other
2735comment is accidentally taken for a start-of-header line.@refill
2736
2737@node setfilename
2738@subsection @code{@@setfilename}
2739@cindex Info file requires @code{@@setfilename}
2740@findex setfilename
2741
2742In order to serve as the primary input file for either @code{makeinfo}
2743or @TeX{}, a Texinfo file must contain a line that looks like this:
2744
2745@example
2746@@setfilename @var{info-file-name}
2747@end example
2748
2749Write the @code{@@setfilename} command at the beginning of a line and
2750follow it on the same line by the Info file name. Do not write anything
2751else on the line; anything on the line after the command is considered
2752part of the file name, including what would otherwise be a
2753comment.
2754
2755The @code{@@setfilename} line specifies the name of the output file to
2756be generated. This name should be different from the name of the
2757Texinfo file. There are two conventions for choosing the name: you can
2758either remove the extension (such as @samp{.texi}) from the input file
2759name, or replace it with the @samp{.info} extension. When producing
2760HTML output, @code{makeinfo} will replace any extension with
2761@samp{html}, or add @samp{.html} if the given name has no extension.
2762
2763Some operating systems cannot handle long file names. You can run into
2764a problem even when the file name you specify is itself short enough.
2765This occurs because the Info formatters split a long Info file into
2766short indirect subfiles, and name them by appending @samp{-1},
2767@samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original
2768file name. (@xref{Tag and Split Files, , Tag Files and Split Files}.)
2769The subfile name @file{texinfo.info-10}, for example, is too long for
2770some systems; so the Info file name for this document is @file{texinfo}
2771rather than @file{texinfo.info}. When @code{makeinfo} is running on
2772operating systems such as MS-DOS which impose grave limits on file
2773names, it will sometimes remove some characters from the original file
2774name to leave enough space for the subfile suffix, thus producing files
2775named @file{texin-10}, @file{gcc.i12}, etc.
2776
2777@cindex Ignored before @code{@@setfilename}
2778@cindex @samp{\input} source line ignored
2779The Info formatting commands ignore everything written before the
2780@code{@@setfilename} line, which is why the very first line of
2781the file (the @code{\input} line) does not show up in the output.
2782
2783@pindex texinfo.cnf
2784The @code{@@setfilename} line produces no output when you typeset a
2785manual with @TeX{}, but it is nevertheless essential: it opens the
2786index, cross-reference, and other auxiliary files used by Texinfo, and
2787also reads @file{texinfo.cnf} if that file is present on your system
2788(@pxref{Preparing for TeX,, Preparing for @TeX{}}).
2789
--- 4 unchanged lines hidden (view full) ---
2794
2795In order to be made into a printed manual, a Texinfo file must contain
2796a line that looks like this:
2797
2798@example
2799@@settitle @var{title}
2800@end example
2801
2802In the HTML file produced by @command{makeinfo}, @var{title} serves as
2803the default document description in the @samp{<head>} part; see
2804@ref{documentdescription}, for how to change that.
2805
2806Write the @code{@@settitle} command at the beginning of a line and
2807follow it on the same line by the title. This tells @TeX{} the title
2808to use in a header or footer. Do not write anything else on the line;
2809anything on the line after the command is considered part of the
2810title, including a comment.@refill
2811
2812Conventionally, when @TeX{} formats a Texinfo file for double-sided
2813output, the title is printed in the left-hand (even-numbered) page
2814headings and the current chapter title is printed in the right-hand
2815(odd-numbered) page headings. (@TeX{} learns the title of each chapter
2816from each @code{@@chapter} command.) Page footers are not
2817printed.@refill
2818
2819Even if you are printing in a single-sided style, @TeX{} looks for an
2820@code{@@settitle} command line, in case you include the manual title
2821in the heading. @refill
2822
2823The @code{@@settitle} command should precede everything that generates
2824actual output in @TeX{}.@refill
2825
2826Although the title in the @code{@@settitle} command is usually the
2827same as the title on the title page, it does not affect the title as
2828it appears on the title page. Thus, the two do not need not match
2829exactly; and the title in the @code{@@settitle} command can be a
2830shortened or expanded version of the title as it appears on the title
2831page. (@xref{titlepage, , @code{@@titlepage}}.)@refill
2832
2833@TeX{} prints page headings only for that text that comes after the
2834@code{@@end titlepage} command in the Texinfo file, or that comes
2835after an @code{@@headings} command that turns on headings.
2836(@xref{headings on off, , The @code{@@headings} Command}, for more
2837information.)@refill
2838
2839You may, if you wish, create your own, customized headings and
2840footings. @xref{Headings, , Page Headings}, for a detailed discussion
2841of this process.@refill
2842
2843
2844@node documentdescription
2845@subsection @code{@@documentdescription}: Summary text
2846@cindex Document description
2847@cindex Description of document
2848@cindex Summary of document
2849@cindex <meta> HTML tag, and document description
2850
2851When producing HTML output for a document, @command{makeinfo} writes a
2852@samp{<meta>} element in the @samp{<head>} to give some idea of the
2853content of the document. By default, this @dfn{description} is the title
2854of the document, taken from the @code{@@settitle} command
2855(@pxref{settitle}). To change this, use the @code{@@documentdescription}
2856environment, as in:
2857
2858@example
2859@@documentdescription
2860descriptive text
2861@@end documendescription
2862@end example
2863
2864@noindent
2865This will produce the following output in the @samp{<head>} of the HTML:
2866
2867@example
2868<meta name=description content="descriptive text">
2869@end example
2870
2871@code{@@documentdescription} must be specified before the first node of
2872the document.
2873
2874
2875@findex documentdescription
2876@node setchapternewpage
2877@subsection @code{@@setchapternewpage}:
2878@cindex Starting chapters
2879@cindex Pages, starting odd
2880@findex setchapternewpage
2881
2882In an officially bound book, text is usually printed on both sides of
2883the paper, chapters start on right-hand pages, and right-hand pages have
2884odd numbers. But in short reports, text often is printed only on one
2885side of the paper. Also in short reports, chapters sometimes do not
2886start on new pages, but are printed on the same page as the end of the
2887preceding chapter, after a small amount of vertical whitespace.
2888
2889You can use the @code{@@setchapternewpage} command with various
2890arguments to specify how @TeX{} should start chapters and whether it
2891should format headers for printing on one or both sides of the paper
2892(single-sided or double-sided printing).
2893
2894Write the @code{@@setchapternewpage} command at the beginning of a
2895line followed by its argument.
2896
2897For example, you would write the following to cause each chapter to
2898start on a fresh odd-numbered page:
2899
2900@example
2901@@setchapternewpage odd
2902@end example
2903
2904You can specify one of three alternatives with the
2905@code{@@setchapternewpage} command:
2906
2907@table @asis
2908
2909@item @code{@@setchapternewpage off}
2910Cause @TeX{} to typeset a new chapter on the same page as the last
2911chapter, after skipping some vertical whitespace. Also, cause @TeX{} to
2912format page headers for single-sided printing.
2913
2914@item @code{@@setchapternewpage on}
2915Cause @TeX{} to start new chapters on new pages and to format page
2916headers for single-sided printing. This is the form most often used for
2917short reports or personal printing. This is the default.
2918
2919@item @code{@@setchapternewpage odd}
2920Cause @TeX{} to start new chapters on new, odd-numbered pages
2921(right-handed pages) and to typeset for double-sided printing. This is
2922the form most often used for books and manuals.
2923@end table
2924
2925Texinfo does not have an @code{@@setchapternewpage even} command,
2926because there is no printing tradition of starting chapters or books on
2927an even-numbered page.
2928
2929If you don't like the default headers that @code{@@setchapternewpage}
2930sets, you can explicit control them with the @code{@@headings} command.
2931@xref{headings on off, , The @code{@@headings} Command}.
2932
2933At the beginning of a manual or book, pages are not numbered---for
2934example, the title and copyright pages of a book are not numbered. By
2935convention, table of contents and frontmatter pages are numbered with
2936roman numerals and not in sequence with the rest of the document.
2937
2938Since an Info file does not have pages, the @code{@@setchapternewpage}
2939command has no effect on it.
2940
2941We recommend not including any @code{@@setchapternewpage} command in
2942your manual sources at all, since the desired output is not intrinsic to
2943the document. Instead, if you don't want the default option (no blank
2944pages, same headers on all pages) use the @option{--texinfo} option to
2945@command{texi2dvi} to specify the output you want.
2946
2947
2948
2949@node paragraphindent
2950@subsection Paragraph Indenting
2951@cindex Indenting paragraphs
2952@cindex Paragraph indentation
2953@findex paragraphindent
2954
2955The Texinfo processors may insert whitespace at the beginning of the
2956first line of each paragraph, thereby indenting that paragraph. You can
2957use the @code{@@paragraphindent} command to specify this indentation.
2958Write an @code{@@paragraphindent} command at the beginning of a line
2959followed by either @samp{asis} or a number:
2960
2961@example
2962@@paragraphindent @var{indent}
2963@end example
2964
2965The indentation is according to the value of @var{indent}:
2966
2967@table @asis
2968@item @code{asis}
2969Do not change the existing indentation (not implemented in @TeX{}).
2970
2971@item 0
2972Omit all indentation.
2973
2974@item @var{n}
2975Indent by @var{n} space characters in Info output, by @var{n} ems in
2976@TeX{}.
2977
2978@end table
2979
2980The default value of @var{indent} is @samp{asis}.
2981@code{@@paragraphindent} is ignored for HTML output.
2982
2983Write the @code{@@paragraphindent} command before or shortly after the
2984end-of-header line at the beginning of a Texinfo file. (If you write
2985the command between the start-of-header and end-of-header lines, the
2986region formatting commands indent paragraphs as specified.)
2987
2988A peculiarity of the @code{texinfo-format-buffer} and
2989@code{texinfo-format-region} commands is that they do not indent (nor
2990fill) paragraphs that contain @code{@@w} or @code{@@*} commands.
2991@xref{Refilling Paragraphs}, for further information.
2992
2993
2994@node exampleindent
2995@subsection @code{@@exampleindent}: Environment Indenting
2996@cindex Indenting environments
2997@cindex Environment indentation
2998@cindex Example indentation
2999@findex exampleindent
3000
3001The Texinfo processors indent each line of @code{@@example} and similar
3002environments. You can use the @code{@@exampleindent} command to specify
3003this indentation. Write an @code{@@exampleindent} command at the
3004beginning of a line followed by either @samp{asis} or a number:
3005
3006@example
3007@@exampleindent @var{indent}
3008@end example
3009
3010The indentation is according to the value of @var{indent}:
3011
3012@table @asis
3013@item @code{asis}
3014Do not change the existing indentation (not implemented in @TeX{}).
3015
3016@item 0
3017Omit all indentation.
3018
3019@item @var{n}
3020Indent environments by @var{n} space characters in Info output, by
3021@var{n} ems in @TeX{}.
3022
3023@end table
3024
3025The default value of @var{indent} is 5. @code{@@exampleindent} is
3026ignored for HTML output.
3027
3028Write the @code{@@exampleindent} command before or shortly after the
3029end-of-header line at the beginning of a Texinfo file. (If you write
3030the command between the start-of-header and end-of-header lines, the
3031region formatting commands indent examples as specified.)
3032
3033
3034@node End of Header
3035@subsection End of Header
3036@cindex End of header line
3037
3038Follow the header lines with an @w{end-of-header} line.
3039An end-of-header line looks like this:@refill
3040
3041@example
3042@@c %**end of header
3043@end example
3044
3045If you include the @code{@@setchapternewpage} command between the
3046start-of-header and end-of-header lines, @TeX{} will typeset a region as
3047that command specifies. Similarly, if you include an @code{@@smallbook}
3048command between the start-of-header and end-of-header lines, @TeX{} will
3049typeset a region in the ``small'' book format.@refill
3050
3051@ifinfo
3052The reason for the odd string of characters (@samp{%**}) is so that the
3053@code{texinfo-tex-region} command does not accidentally find
3054something that it should not when it is looking for the header.@refill
3055
3056The start-of-header line and the end-of-header line are Texinfo mode
3057variables that you can change.@refill
3058@end ifinfo
3059
3060@iftex
3061@xref{Start of Header}.
3062@end iftex
3063
3064
3065@node Info Summary and Permissions
3066@section Summary and Copying Permissions for Info
3067
3068The title page and the copyright page appear only in the printed copy of
3069the manual; therefore, the same information must be inserted in a
3070section that appears only in the Info file. This section usually
3071contains a brief description of the contents of the Info file, a
3072copyright notice, and copying permissions.@refill
3073
3074The copyright notice should read:
3075
3076@example
3077Copyright @var{year} @var{copyright-owner}
3078@end example
3079
3080@noindent
3081and be put on a line by itself.
3082
3083Standard text for the copyright permissions of free manuals is contained
3084in an appendix to this manual (@pxref{Documentation Copying, , GNU Free
3085Documentation License}).
3086
3087The permissions text appears in an Info file @emph{before} the first
3088node. This mean that a reader does @emph{not} see this text when
3089reading the file using Info (except when using the advanced Info command
3090@kbd{g *}).
3091
3092
3093@node Titlepage & Copyright Page
3094@section The Title and Copyright Pages
3095
3096A manual's name and author are usually printed on a title page.
3097Sometimes copyright information is printed on the title page as well;
3098more often, copyright information is printed on the back of the title
3099page.
3100
3101The title and copyright pages appear in the printed manual, but not in the
3102Info file. Because of this, it is possible to use several slightly
3103obscure @TeX{} typesetting commands that cannot be used in an Info file.
3104In addition, this part of the beginning of a Texinfo file contains the text
3105of the copying permissions that will appear in the printed manual.@refill
3106
3107@cindex Titlepage, for plain text
3108You may wish to include titlepage-like information for plain text
3109output. Simply place any such leading material between @code{@@ifinfo}
3110and @code{@@end ifinfo}; @command{makeinfo} includes this in its plain
3111text output. It will not show up in the Info readers.
3112
3113@xref{Documentation Copying, , GNU Free Documentation License}, for the
3114standard text for the copyright permissions.
3115
3116@menu
3117* titlepage:: Create a title for the printed document.
3118* titlefont center sp:: The @code{@@titlefont}, @code{@@center},
3119 and @code{@@sp} commands.
3120* title subtitle author:: The @code{@@title}, @code{@@subtitle},
3121 and @code{@@author} commands.
3122* Copyright & Permissions:: How to write the copyright notice and
3123 include copying permissions.
3124* end titlepage:: Turn on page headings after the title and
3125 copyright pages.
3126* headings on off:: An option for turning headings on and off
3127 and double or single sided printing.
3128@end menu
3129
3130
3131@node titlepage, titlefont center sp, Titlepage & Copyright Page, Titlepage & Copyright Page
3132@comment node-name, next, previous, up
3133@subsection @code{@@titlepage}
3134@cindex Title page
3135@findex titlepage
3136
3137Start the material for the title page and following copyright page
3138with @code{@@titlepage} on a line by itself and end it with
3139@code{@@end titlepage} on a line by itself.@refill
3140
3141The @code{@@end titlepage} command starts a new page and turns on page
3142numbering. (@xref{Headings, , Page Headings}, for details about how to
3143generate page headings.) All the material that you want to appear on
3144unnumbered pages should be put between the @code{@@titlepage} and
3145@code{@@end titlepage} commands. You can force the table of contents to
3146appear there with the @code{@@setcontentsaftertitlepage} command
3147(@pxref{Contents}).
--- 5 unchanged lines hidden (view full) ---
3153the copyright page is produced. (The @code{@@titlepage} command might
3154perhaps have been better named the @code{@@titleandadditionalpages}
3155command, but that would have been rather long!)
3156
3157When you write a manual about a computer program, you should write the
3158version of the program to which the manual applies on the title page.
3159If the manual changes more frequently than the program or is independent
3160of it, you should also include an edition number@footnote{We have found
3161that it is helpful to refer to versions of manuals as `editions' and
3162versions of programs as `versions'; otherwise, we find we are liable to
3163confuse each other in conversation by referring to both the
3164documentation and the software with the same words.} for the manual.
3165This helps readers keep track of which manual is for which version of
3166the program. (The `Top' node should also contain this information; see
3167@ref{makeinfo top, , @code{@@top}}.)
3168
3169Texinfo provides two main methods for creating a title page. One method
3170uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands
3171to generate a title page in which the words on the page are
3172centered.
3173
3174The second method uses the @code{@@title}, @code{@@subtitle}, and
3175@code{@@author} commands to create a title page with black rules under
--- 5 unchanged lines hidden (view full) ---
3181You may use either method, or you may combine them; see the examples in
3182the sections below.
3183
3184@findex shorttitlepage
3185@cindex Bastard title page
3186@cindex Title page, bastard
3187For extremely simple applications, and for the bastard title page in
3188traditional book front matter, Texinfo also provides a command
3189@code{@@shorttitlepage} which takes a single argument as the title. The
3190argument is typeset on a page by itself and followed by a blank page.
3191
3192
3193@node titlefont center sp
3194@subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp}
3195@findex titlefont
3196@findex center
3197@findex sp @r{(titlepage line spacing)}
3198
3199You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center}
3200commands to create a title page for a printed document. (This is the
3201first of the two methods for creating a title page in Texinfo.)@refill
3202
3203Use the @code{@@titlefont} command to select a large font suitable for
3204the title itself. You can use @code{@@titlefont} more than once if you
3205have an especially long title.
3206
3207@need 700
3208For example:
3209
3210@example
3211@@titlefont@{Texinfo@}
3212@end example
3213
3214Use the @code{@@center} command at the beginning of a line to center
3215the remaining text on that line. Thus,@refill
3216
3217@example
3218@@center @@titlefont@{Texinfo@}
3219@end example
3220
3221@noindent
3222centers the title, which in this example is ``Texinfo'' printed
3223in the title font.@refill
3224
3225Use the @code{@@sp} command to insert vertical space. For example:@refill
3226
3227@example
3228@@sp 2
3229@end example
3230
3231@noindent
3232This inserts two blank lines on the printed page. (@xref{sp, ,
3233@code{@@sp}}, for more information about the @code{@@sp}
3234command.)@refill
3235
3236A template for this method looks like this:@refill
3237
3238@example
3239@group
3240@@titlepage
3241@@sp 10
3242@@center @@titlefont@{@var{name-of-manual-when-printed}@}
3243@@sp 2
3244@@center @var{subtitle-if-any}
3245@@sp 2
3246@@center @var{author}
3247@dots{}
3248@@end titlepage
3249@end group
3250@end example
3251
3252The spacing of the example fits an 8.5 by 11 inch manual.@refill
3253
3254
3255@node title subtitle author
3256@subsection @code{@@title}, @code{@@subtitle}, and @code{@@author}
3257@findex title
3258@findex subtitle
3259@findex author
3260
3261You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author}
3262commands to create a title page in which the vertical and horizontal
3263spacing is done for you automatically. This contrasts with the method
3264described in the previous section, in which the @code{@@sp} command is
3265needed to adjust vertical spacing.
3266
3267Write the @code{@@title}, @code{@@subtitle}, or @code{@@author}
3268commands at the beginning of a line followed by the title, subtitle,
3269or author.@refill
3270
3271The @code{@@title} command produces a line in which the title is set
3272flush to the left-hand side of the page in a larger than normal font.
3273The title is underlined with a black rule. Only a single line is
3274allowed; the @code{@@*} command may not be used to break the title into
3275two lines. To handle very long titles, you may find it profitable to
3276use both @code{@@title} and @code{@@titlefont}; see the final example in
3277this section.
3278
3279The @code{@@subtitle} command sets subtitles in a normal-sized font
3280flush to the right-hand side of the page.@refill
3281
3282The @code{@@author} command sets the names of the author or authors in
3283a middle-sized font flush to the left-hand side of the page on a line
3284near the bottom of the title page. The names are underlined with a
3285black rule that is thinner than the rule that underlines the title.
3286(The black rule only occurs if the @code{@@author} command line is
3287followed by an @code{@@page} command line.)@refill
3288
3289There are two ways to use the @code{@@author} command: you can write
3290the name or names on the remaining part of the line that starts with
3291an @code{@@author} command:@refill
3292
3293@example
3294@@author by Jane Smith and John Doe
3295@end example
3296
3297@noindent
3298or you can write the names one above each other by using two (or more)
3299@code{@@author} commands:@refill
3300
3301@example
3302@group
3303@@author Jane Smith
3304@@author John Doe
3305@end group
3306@end example
3307
3308@noindent
3309(Only the bottom name is underlined with a black rule.)@refill
3310
3311@need 950
3312A template for this method looks like this:@refill
3313
3314@example
3315@group
3316@@titlepage
3317@@title @var{name-of-manual-when-printed}
3318@@subtitle @var{subtitle-if-any}
3319@@subtitle @var{second-subtitle}
3320@@author @var{author}
--- 15 unchanged lines hidden (view full) ---
3336@@title for MS-Windows and MS-DOS
3337@@subtitle Edition @@value@{e@} for Release @@value@{cde@}
3338@@author by Daniel Hagerty, Melissa Weisshaus
3339@@author and Eli Zaretskii
3340@end group
3341@end example
3342
3343@noindent
3344(The use of @code{@@value} here is explained in @ref{value
3345Example,,@code{@@value} Example}.)
3346
3347
3348@node Copyright & Permissions
3349@subsection Copyright Page and Permissions
3350@cindex Copyright page
3351@cindex Printed permissions
3352@cindex Permissions, printed
3353
3354By international treaty, the copyright notice for a book should be
3355either on the title page or on the back of the title page. The
3356copyright notice should include the year followed by the name of the
3357organization or person who owns the copyright.@refill
3358
3359When the copyright notice is on the back of the title page, that page
3360is customarily not numbered. Therefore, in Texinfo, the information
3361on the copyright page should be within @code{@@titlepage} and
3362@code{@@end titlepage} commands.@refill
3363
3364@findex vskip
3365@findex filll
3366@cindex Vertical whitespace (@samp{vskip})
3367Use the @code{@@page} command to cause a page break. To push the
3368copyright notice and the other text on the copyright page towards the
3369bottom of the page, you can write a somewhat mysterious line after the
3370@code{@@page} command that reads like this:@refill
3371
3372@example
3373@@vskip 0pt plus 1filll
3374@end example
3375
3376@noindent
3377This is a @TeX{} command that is not supported by the Info formatting
3378commands. The @code{@@vskip} command inserts whitespace. The
3379@samp{0pt plus 1filll} means to put in zero points of mandatory whitespace,
3380and as much optional whitespace as needed to push the
3381following text to the bottom of the page. Note the use of three
3382@samp{l}s in the word @samp{filll}; this is the correct usage in
3383@TeX{}.@refill
3384
3385@findex copyright
3386In a printed manual, the @code{@@copyright@{@}} command generates a
3387@samp{c} inside a circle. (In Info, it generates @samp{(C)}.) The
3388copyright notice itself has the following legally defined sequence:@refill
3389
3390@example
3391Copyright @copyright{} @var{year} @var{copyright-owner}
3392@end example
3393
3394It is customary to put information on how to get a manual after the
3395copyright notice, followed by the copying permissions for the manual.
3396
3397Permissions must be given here as well as in the summary segment within
3398@code{@@ifinfo} and @code{@@end ifinfo} that immediately follows the
3399header since this text appears only in the printed manual and the
3400@samp{ifinfo} text appears only in the Info file.
3401
3402@xref{Documentation Copying,,GNU Free Documentation License}, for the
3403standard text.
3404
3405
3406@node end titlepage
3407@subsection Heading Generation
3408@findex end titlepage
3409@cindex Headings, page, begin to appear
3410@cindex Titlepage end starts headings
3411@cindex End titlepage starts headings
3412
3413An @code{@@end titlepage} command on a line by itself not only marks
3414the end of the title and copyright pages, but also causes @TeX{} to start
3415generating page headings and page numbers.
3416
3417To repeat what is said elsewhere, Texinfo has two standard page heading
3418formats, one for documents which are printed on one side of each sheet of paper
3419(single-sided printing), and the other for documents which are printed on both
3420sides of each sheet (double-sided printing).
3421(@xref{setchapternewpage, ,@code{@@setchapternewpage}}.)
3422You can specify these formats in different ways:@refill
3423
3424@itemize @bullet
3425@item
3426The conventional way is to write an @code{@@setchapternewpage} command
3427before the title page commands, and then have the @code{@@end
3428titlepage} command start generating page headings in the manner desired.
3429(@xref{setchapternewpage, , @code{@@setchapternewpage}}.)@refill
3430
3431@item
3432Alternatively, you can use the @code{@@headings} command to prevent page
3433headings from being generated or to start them for either single or
3434double-sided printing. (Write an @code{@@headings} command immediately
3435after the @code{@@end titlepage} command. @xref{headings on off, , The
3436@code{@@headings} Command}, for more information.)@refill
3437
3438@item
3439Or, you may specify your own page heading and footing format.
3440@xref{Headings, , Page Headings}, for detailed
3441information about page headings and footings.@refill
3442@end itemize
3443
3444Most documents are formatted with the standard single-sided or
3445double-sided format, using @code{@@setchapternewpage odd} for
3446double-sided printing and no @code{@@setchapternewpage} command for
3447single-sided printing.@refill
3448
3449@node headings on off, , end titlepage, Titlepage & Copyright Page
3450@comment node-name, next, previous, up
3451@subsection The @code{@@headings} Command
3452@findex headings
3453
3454The @code{@@headings} command is rarely used. It specifies what kind of
3455page headings and footings to print on each page. Usually, this is
3456controlled by the @code{@@setchapternewpage} command. You need the
3457@code{@@headings} command only if the @code{@@setchapternewpage} command
3458does not do what you want, or if you want to turn off pre-defined page
--- 48 unchanged lines hidden (view full) ---
3507headings.@refill
3508
3509You can also specify your own style of page heading and footing.
3510@xref{Headings, , Page Headings}, for more information.@refill
3511
3512
3513@node The Top Node
3514@section The `Top' Node and Master Menu
3515@cindex @samp{@r{Top}} node
3516@cindex Master menu
3517@cindex Node, `Top'
3518
3519The `Top' node is the node from which you enter an Info file.@refill
3520
3521A `Top' node should contain a brief description of the Info file and an
3522extensive, master menu for the whole Info file.
3523This helps the reader understand what the Info file is
3524about. Also, you should write the version number of the program to
3525which the Info file applies; or, at least, the edition number.@refill
3526
3527The contents of the `Top' node should appear only in the Info file; none
3528of it should appear in printed output, so enclose it between
3529@code{@@ifinfo} and @code{@@end ifinfo} commands. (@TeX{} does not
3530print either an @code{@@node} line or a menu; they appear only in Info;
3531strictly speaking, you are not required to enclose these parts between
3532@code{@@ifinfo} and @code{@@end ifinfo}, but it is simplest to do so.
3533@xref{Conditionals, , Conditionally Visible Text}.)@refill
3534
3535@menu
3536* Title of Top Node:: Sketch what the file is about.
3537* Master Menu Parts:: A master menu has three or more parts.
3538@end menu
3539
3540
3541@node Title of Top Node
3542@subsection `Top' Node Title
3543
3544Sometimes, you will want to place an @code{@@top} sectioning command
3545line containing the title of the document immediately after the
3546@code{@@node Top} line (@pxref{makeinfo top command, , The @code{@@top}
3547Sectioning Command}, for more information).@refill
3548
3549For example, the beginning of the Top node of this manual contains an
3550@code{@@top} sectioning command, a short description, and edition and
3551version information. It looks like this:@refill
3552
3553@example
3554@group
3555@dots{}
3556@@end titlepage
3557
3558@@ifnottex
3559@@node Top, Copying, , (dir)
3560@@top Texinfo
3561
3562Texinfo is a documentation system@dots{}
3563@end group
3564
3565@group
3566This is edition@dots{}
3567@dots{}
3568@@end ifnottex
3569@end group
3570
3571@group
3572@@menu
3573* Copying:: Texinfo is freely
3574 redistributable.
3575* Overview:: What is Texinfo?
3576@dots{}
3577@end group
3578@@end menu
3579@end example
3580
3581In a `Top' node, the `Previous', and `Up' nodes usually refer to the top
3582level directory of the whole Info system, which is called @samp{(dir)}.
3583The `Next' node refers to the first node that follows the main or master
3584menu, which is usually the copying permissions, introduction, or first
3585chapter.@refill
3586
3587@node Master Menu Parts, , Title of Top Node, The Top Node
3588@subsection Parts of a Master Menu
3589@cindex Master menu parts
3590@cindex Parts of a master menu
3591
3592A @dfn{master menu} is a detailed main menu listing all the nodes in a
3593file.
3594
3595A master menu is enclosed in @code{@@menu} and @code{@@end menu}
3596commands and does not appear in the printed document.@refill
3597
3598Generally, a master menu is divided into parts.@refill
3599
3600@itemize @bullet
3601@item
3602The first part contains the major nodes in the Texinfo file: the nodes
3603for the chapters, chapter-like sections, and the appendices.@refill
3604
3605@item
3606The second part contains nodes for the indices.@refill
3607
3608@item
3609The third and subsequent parts contain a listing of the other, lower
3610level nodes, often ordered by chapter. This way, rather than go
3611through an intermediary menu, an inquirer can go directly to a
3612particular node when searching for specific information. These menu
3613items are not required; add them if you think they are a
3614convenience. If you do use them, put @code{@@detailmenu} before the
3615first one, and @code{@@end detailmenu} after the last; otherwise,
3616@code{makeinfo} will get confused.
3617@end itemize
3618
3619Each section in the menu can be introduced by a descriptive line. So
3620long as the line does not begin with an asterisk, it will not be
3621treated as a menu entry. (@xref{Writing a Menu}, for more
3622information.)@refill
3623
3624For example, the master menu for this manual looks like the following
3625(but has many more entries):@refill
3626
3627@example
3628@group
3629@@menu
3630* Copying:: Texinfo is freely
3631 redistributable.
3632* Overview:: What is Texinfo?
3633* Texinfo Mode:: Special features in GNU Emacs.
3634@dots{}
3635@dots{}
3636@end group
3637@group
3638* Command and Variable Index::
3639 An entry for each @@-command.
3640* Concept Index:: An entry for each concept.
3641@end group
3642
3643@group
3644@@detailmenu
3645 --- The Detailed Node Listing ---
3646
3647Overview of Texinfo
3648
3649* Info Files:: What is an Info file?
3650* Printed Manuals:: Characteristics of
3651 a printed manual.
3652@dots{}
3653@dots{}
3654@end group
3655
3656@group
3657Using Texinfo Mode
3658
3659* Info on a Region:: Formatting part of a file
3660 for Info.
3661@dots{}
3662@dots{}
3663@@end detailmenu
3664@@end menu
3665@end group
3666@end example
3667
3668@node Software Copying Permissions
3669@comment node-name, next, previous, up
3670@section Software Copying Permissions
3671@cindex Software copying permissions
3672@cindex Copying software
3673@cindex Distribution
3674@cindex License agreement
3675
3676If the Texinfo file has a section containing the ``General Public
3677License'' and the distribution information and a warranty disclaimer
3678for the software that is documented, this section usually follows the
3679`Top' node. The General Public License is very important to Project
3680GNU software. It ensures that you and others will continue to have a
3681right to use and share the software.@refill
3682
3683The copying and distribution information and the disclaimer are followed
3684by an introduction or else by the first chapter of the manual.@refill
3685
3686@cindex Introduction, as part of file
3687Although an introduction is not a required part of a Texinfo file, it
3688is very helpful. Ideally, it should state clearly and concisely what
3689the file is about and who would be interested in reading it. In
3690general, an introduction would follow the licensing and distribution
3691information, although sometimes people put it earlier in the document.
3692Usually, an introduction is put in an @code{@@unnumbered} section.
3693(@xref{unnumbered & appendix, , The @code{@@unnumbered} and
3694@code{@@appendix} Commands}.)@refill
3695
3696@node Ending a File, Structuring, Beginning a File, Top
3697@comment node-name, next, previous, up
3698@chapter Ending a Texinfo File
3699@cindex Ending a Texinfo file
3700@cindex Texinfo file ending
3701@cindex File ending
3702@findex bye
3703
3704The end of a Texinfo file should include commands to create indices and
3705(usually) to generate detailed and summary tables of contents. And it
3706must include the @code{@@bye} command that marks the last line processed
3707by @TeX{}.@refill
3708
3709@need 700
3710For example:
3711
3712@example
3713@@node Concept Index, , Variables Index, Top
3714@@c node-name, next, previous, up
3715@@unnumbered Concept Index
3716
3717@@printindex cp
3718
3719@@contents
3720@@bye
3721@end example
3722
3723@menu
3724* Printing Indices & Menus:: How to print an index in hardcopy and
3725 generate index menus in Info.
3726* Contents:: How to create a table of contents.
3727* File End:: How to mark the end of a file.
3728@end menu
3729
3730@node Printing Indices & Menus, Contents, Ending a File, Ending a File
3731@comment node-name, next, previous, up
3732@section Index Menus and Printing an Index
3733@findex printindex
3734@cindex Printing an index
3735@cindex Indices, printing and menus
3736@cindex Generating menus with indices
3737@cindex Menus generated with indices
3738
3739To print an index means to include it as part of a manual or Info
3740file. This does not happen automatically just because you use
3741@code{@@cindex} or other index-entry generating commands in the
3742Texinfo file; those just cause the raw data for the index to be
3743accumulated. To generate an index, you must include the
3744@code{@@printindex} command at the place in the document where you
3745want the index to appear. Also, as part of the process of creating a
3746printed manual, you must run a program called @code{texindex}
3747(@pxref{Hardcopy}) to sort the raw data to produce a sorted
3748index file. The sorted index file is what is actually used to
3749print the index.@refill
3750
3751Texinfo offers six different types of predefined index: the concept
3752index, the function index, the variables index, the keystroke index, the
3753program index, and the data type index (@pxref{Predefined Indices}). Each
3754index type has a two-letter name: @samp{cp}, @samp{fn}, @samp{vr},
3755@samp{ky}, @samp{pg}, and @samp{tp}. You may merge indices, or put them
3756into separate sections (@pxref{Combining Indices}); or you may define
3757your own indices (@pxref{New Indices, , Defining New Indices}).@refill
3758
3759The @code{@@printindex} command takes a two-letter index name, reads
3760the corresponding sorted index file and formats it appropriately into
3761an index.@refill
3762
3763@ignore
3764The two-letter index names are:
3765
3766@table @samp
3767@item cp
3768concept index
3769@item fn
3770function index
3771@item vr
3772variable index
3773@item ky
3774key index
3775@item pg
3776program index
3777@item tp
3778data type index
3779@end table
3780@end ignore
3781The @code{@@printindex} command does not generate a chapter heading
3782for the index. Consequently, you should precede the
3783@code{@@printindex} command with a suitable section or chapter command
3784(usually @code{@@unnumbered}) to supply the chapter heading and put
3785the index into the table of contents. Precede the @code{@@unnumbered}
3786command with an @code{@@node} line.@refill
3787
3788@need 1200
3789For example:
3790
3791@smallexample
3792@group
3793@@node Variable Index, Concept Index, Function Index, Top
3794@@comment node-name, next, previous, up
3795@@unnumbered Variable Index
3796
3797@@printindex vr
3798@end group
3799
3800@group
3801@@node Concept Index, , Variable Index, Top
3802@@comment node-name, next, previous, up
3803@@unnumbered Concept Index
3804
3805@@printindex cp
3806@end group
3807@end smallexample
3808
3809@noindent
3810Readers often prefer that the concept index come last in a book,
3811since that makes it easiest to find. Having just one index helps
3812readers also, since then they have only one place to look
3813(@pxref{synindex}).
3814
3815
3816@node Contents
3817@section Generating a Table of Contents
3818@cindex Table of contents
3819@cindex Contents, Table of
3820@cindex Short table of contents
3821@findex contents
3822@findex summarycontents
3823@findex shortcontents
3824
3825The @code{@@chapter}, @code{@@section}, and other structuring commands
3826supply the information to make up a table of contents, but they do not
3827cause an actual table to appear in the manual. To do this, you must use
3828the @code{@@contents} and/or @code{@@summarycontents} command(s).
3829
3830@table @code
3831@item @@contents
3832Generate a table of contents in a printed manual, including all
3833chapters, sections, subsections, etc., as well as appendices and
3834unnumbered chapters. (Headings generated by the @code{@@heading}
3835series of commands do not appear in the table of contents.)
3836
3837@item @@shortcontents
3838@itemx @@summarycontents
3839(@code{@@summarycontents} is a synonym for @code{@@shortcontents}; the
3840two commands are exactly the same.)@refill
3841
3842Generate a short or summary table of contents that lists only the
3843chapters (and appendices and unnumbered chapters). Omit sections, subsections
3844and subsubsections. Only a long manual needs a short table
3845of contents in addition to the full table of contents.@refill
3846
3847@end table
3848
3849Both contents commands should be written on a line by themselves.
3850The contents commands automatically generate a chapter-like heading at
3851the top of the first table of contents page, so don't include any
3852sectioning command such as @code{@@unnumbered} before them.
3853
--- 22 unchanged lines hidden (view full) ---
3876@findex setcontentsaftertitlepage
3877@findex setshortcontentsaftertitlepage
3878@cindex Contents, after title page
3879@cindex Table of contents, after title page
3880As an author, you can put the contents commands wherever you prefer.
3881But if you are a user simply printing a manual, you may wish to print
3882the contents after the title page even if the author put the contents
3883commands at the end of the document (as is the case in most existing
3884Texinfo documents). You can do this by specifying
3885@code{@@setcontentsaftertitlepage} and/or
3886@code{@@setshortcontentsaftertitlepage}. The first prints only the main
3887contents after the @code{@@end titlepage}; the second prints both the
3888short contents and the main contents. In either case, any subsequent
3889@code{@@contents} or @code{@@shortcontents} is ignored (unless no
3890@code{@@end titlepage} is ever encountered).
3891
3892You need to include the @code{@@set@dots{}contentsaftertitlepage}
3893commands early in the document (just after @code{@@setfilename}, for
3894example). Or, if you're using @command{texi2dvi} (@pxref{Format with
3895texi2dvi}), you can use its @option{--texinfo} option to specify this
3896without altering the source file at all. For example:
3897@example
3898texi2dvi --texinfo=@@setshortcontentsaftertitlepage foo.texi
3899@end example
3900
3901
3902@node File End
3903@section @code{@@bye} File Ending
3904@findex bye
3905
3906An @code{@@bye} command terminates @TeX{} or Info formatting. None of
3907the formatting commands see any of the file following @code{@@bye}.
3908The @code{@@bye} command should be on a line by itself.@refill
3909
3910If you wish, you may follow the @code{@@bye} line with notes. These notes
3911will not be formatted and will not appear in either Info or a printed
3912manual; it is as if text after @code{@@bye} were within @code{@@ignore}
3913@dots{} @code{@@end ignore}. Also, you may follow the @code{@@bye} line
3914with a local variables list. @xref{Compile-Command, , Using Local
3915Variables and the Compile Command}, for more information.@refill
3916
3917
3918@node Structuring
3919@chapter Chapter Structuring
3920@cindex Chapter structuring
3921@cindex Structuring of chapters
3922
3923The @dfn{chapter structuring} commands divide a document into a hierarchy of
--- 705 unchanged lines hidden (view full) ---
4629
4630@menu
4631* Node Names:: How to choose node and pointer names.
4632* Writing a Node:: How to write an @code{@@node} line.
4633* Node Line Tips:: Keep names short.
4634* Node Line Requirements:: Keep names unique, without @@-commands.
4635* First Node:: How to write a `Top' node.
4636* makeinfo top command:: How to use the @code{@@top} command.
4637* Top Node Summary:: Write a brief description for readers.
4638@end menu
4639
4640
4641@node Node Names
4642@subsection Choosing Node and Pointer Names
4643
4644@cindex Node names, choosing
4645The name of a node identifies the node. The pointers enable
--- 172 unchanged lines hidden (view full) ---
4818
4819@noindent
4820The corresponding node name is:
4821
4822@smallexample
4823unnumberedsec appendixsec heading
4824@end smallexample
4825
4826@cindex Case in nodename
4827@item
4828Case is significant.
4829@end itemize
4830
4831
4832@node First Node, makeinfo top command, Node Line Requirements, node
4833@comment node-name, next, previous, up
4834@subsection The First Node
4835@cindex Top node is first
4836@cindex First node
4837
4838The first node of a Texinfo file is the @dfn{Top} node, except in an
4839included file (@pxref{Include Files}). The Top node contains the main
4840or master menu for the document, and a short summary of the document
4841(@pxref{Top Node Summary}).
4842
4843@cindex Up node of Top node
4844@cindex (dir) as Up node of Top node
4845The Top node (which must be named @samp{top} or @samp{Top}) should have
4846as its `Up' node the name of a node in another file, where there is a
4847menu that leads to this file. Specify the file name in parentheses. If
4848the file is to be installed directly in the Info directory file, use
4849@samp{(dir)} as the parent of the Top node; this is short for
4850@samp{(dir)top}, and specifies the Top node in the @file{dir} file,
4851which contains the main menu for the Info system as a whole. For
4852example, the @code{@@node Top} line of this manual looks like this:
4853
4854@example
4855@@node Top, Copying, , (dir)
4856@end example
4857
4858@noindent
4859(You can use the Texinfo updating commands or the @code{makeinfo}
4860utility to insert these pointers automatically.)
4861
4862@cindex Previous node of Top node
4863Do not define the `Previous' node of the Top node to be @samp{(dir)}, as
4864it causes confusing behavior for users: if you are in the Top node and
4865hits @key{DEL} to go backwards, you wind up in the middle of the
4866some other entry in the @file{dir} file, which has nothing to do with
4867what you were reading.
4868
4869@xref{Installing an Info File}, for more information about installing
4870an Info file in the @file{info} directory.
4871
4872
4873@node makeinfo top command, Top Node Summary, First Node, node
4874@comment node-name, next, previous, up
4875@subsection The @code{@@top} Sectioning Command
4876@findex top @r{(@@-command)}
4877
4878A special sectioning command, @code{@@top}, has been created for use
4879with the @code{@@node Top} line. The @code{@@top} sectioning command tells
4880@code{makeinfo} that it marks the `Top' node in the file. It provides
4881the information that @code{makeinfo} needs to insert node
4882pointers automatically. Write the @code{@@top} command at the
4883beginning of the line immediately following the @code{@@node Top}
4884line. Write the title on the remaining part of the same line as the
4885@code{@@top} command.@refill
4886
4887In Info, the @code{@@top} sectioning command causes the title to appear on a
4888line by itself, with a line of asterisks inserted underneath.@refill
4889
4890In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
4891sectioning command is merely a synonym for @code{@@unnumbered}.
4892Neither of these formatters require an @code{@@top} command, and do
4893nothing special with it. You can use @code{@@chapter} or
4894@code{@@unnumbered} after the @code{@@node Top} line when you use
4895these formatters. Also, you can use @code{@@chapter} or
4896@code{@@unnumbered} when you use the Texinfo updating commands to
4897create or update pointers and menus.@refill
4898
4899
4900@node Top Node Summary, , makeinfo top command, node
4901@subsection The `Top' Node Summary
4902@cindex @samp{@r{Top}} node summary
4903
4904You can help readers by writing a summary in the `Top' node, after the
4905@code{@@top} line, before the main or master menu. The summary should
4906briefly describe the document. In Info, this summary will appear just
4907before the master menu. In a printed manual, this summary will appear
4908on a page of its own.@refill
4909
4910If you do not want the summary to appear on a page of its own in a
4911printed manual, you can enclose the whole of the `Top' node, including
4912the @code{@@node Top} line and the @code{@@top} sectioning command line
4913or other sectioning command line between @code{@@ifinfo} and @code{@@end
4914ifinfo}. This prevents any of the text from appearing in the printed
4915output. (@pxref{Conditionals, , Conditionally Visible Text}). You can
4916repeat the brief description from the `Top' node within @code{@@iftex}
4917@dots{} @code{@@end iftex} at the beginning of the first chapter, for
4918those who read the printed manual. This saves paper and may look
4919neater.@refill
4920
4921You should write the version number of the program to which the manual
4922applies in the summary. This helps the reader keep track of which
4923manual is for which version of the program. If the manual changes more
4924frequently than the program or is independent of it, you should also
4925include an edition number for the manual. (The title page should also
4926contain this information: see @ref{titlepage, ,
4927@code{@@titlepage}}.)@refill
4928
4929
4930@node makeinfo Pointer Creation
4931@section Creating Pointers with @code{makeinfo}
4932@cindex Creating pointers with @code{makeinfo}
4933@cindex Pointer creation with @code{makeinfo}
4934@cindex Automatic pointer creation with @code{makeinfo}
4935
4936The @code{makeinfo} program has a feature for automatically defining
4937node pointers for a hierarchically organized file.
--- 109 unchanged lines hidden (view full) ---
5047@cindex Nodes for menus are short
5048@cindex Short nodes for menus
5049
5050The short text before a menu may look awkward in a printed manual. To
5051avoid this, you can write a menu near the beginning of its node and
5052follow the menu by an @code{@@node} line, and then an @code{@@heading}
5053line located within @code{@@ifinfo} and @code{@@end ifinfo}. This way,
5054the menu, @code{@@node} line, and title appear only in the Info file,
5055not the printed document.@refill
5056
5057For example, the preceding two paragraphs follow an Info-only menu,
5058@code{@@node} line, and heading, and look like this:@refill
5059
5060@example
5061@group
5062@@menu
5063* Menu Location:: Put a menu in a short node.
5064* Writing a Menu:: What is a menu?
5065* Menu Parts:: A menu entry has three parts.
5066* Less Cluttered Menu Entry:: Two part menu entry.
--- 4 unchanged lines hidden (view full) ---
5071
5072@@node Menu Location, Writing a Menu, , Menus
5073@@ifinfo
5074@@heading Menus Need Short Nodes
5075@@end ifinfo
5076@end group
5077@end example
5078
5079The Texinfo file for this document contains more than a dozen
5080examples of this procedure. One is at the beginning of this chapter;
5081another is at the beginning of @ref{Cross References}. @refill
5082
5083
5084@node Writing a Menu, Menu Parts, Menu Location, Menus
5085@section Writing a Menu
5086@cindex Writing a menu
5087@cindex Menu writing
5088
5089A menu consists of an @code{@@menu} command on a line by
--- 1312 unchanged lines hidden (view full) ---
6402not something else that should not be changed.@refill
6403
6404@menu
6405* Useful Highlighting:: Highlighting provides useful information.
6406* code:: Indicating program code.
6407* kbd:: Showing keyboard input.
6408* key:: Specifying keys.
6409* samp:: A literal sequence of characters.
6410* verb:: A verbatim sequence of characters.
6411* var:: Indicating metasyntactic variables.
6412* env:: Indicating environment variables.
6413* file:: Indicating file names.
6414* command:: Indicating command names.
6415* option:: Indicating option names.
6416* dfn:: Specifying definitions.
6417* cite:: Referring to books not in the Info system.
6418* acronym:: Indicating acronyms.
--- 925 unchanged lines hidden (view full) ---
7344line.
7345@findex end
7346
7347@menu
7348* Block Enclosing Commands:: Different constructs for different purposes.
7349* quotation:: Writing a quotation.
7350* example:: Writing an example in a fixed-width font.
7351* verbatim:: Writing a verbatim example.
7352* verbatiminclude:: Including a file verbatim.
7353* lisp:: Illustrating Lisp code.
7354* small:: Forms for @code{@@smallbook}.
7355* display:: Writing an example in the current font.
7356* format:: Writing an example without narrowed margins.
7357* exdent:: Undo indentation on a line.
7358* flushleft & flushright:: Pushing text flush left or flush right.
7359* noindent:: Preventing paragraph indentation.
7360* cartouche:: Drawing rounded rectangles around examples.
--- 198 unchanged lines hidden (view full) ---
7559such as computer input or output (@code{@@example} interprets its text
7560as regular Texinfo commands). This is especially useful for including
7561automatically generated output in a Texinfo manual. Here is an example;
7562the output you see is just the same as the input, with a line
7563@code{@@verbatim} before and a line @code{@@end verbatim} after.
7564
7565@verbatim
7566This is an example of text written in a @verbatim
7567block. No character substitutions are made all commands
7568are ignored, until the next 'end verbatim' command.
7569
7570In the printed manual, the text is typeset in a
7571fixed-width font, and not indented or filled. All
7572spaces and blank lines are significant, including tabs.
7573@end verbatim
7574
7575Write a @code{@@verbatim} command at the beginning of a line by itself.
7576This line will disappear from the output. Mark the end of the verbatim
7577block with a @code{@@end verbatim} command, also written at the
7578beginning of a line by itself. The @code{@@end verbatim} will also
7579disappear from the output.
7580
7581For example:
7582@c urg: got to trick this a bit: can't use @end verbatim inside @verbatim
7583
7584@example
7585@exdent @@verbatim
7586@exdent @{
7587@exdent <tab>@@command with strange characters: @@'e
7588@exdent expand<tab>me
7589@exdent @}
7590@exdent @@end verbatim
--- 5 unchanged lines hidden (view full) ---
7596@verbatim
7597{
7598 @command with strange characters: @'e
7599expand me
7600}
7601@end verbatim
7602
7603Since the lines containing @code{@@verbatim} and @code{@@end verbatim}
7604will disappear, tyically you should put a blank line before the
7605@code{@@verbatim} and another blank line after the @code{@@end
7606verbatim}. Blank lines between the beginning @code{@@verbatim} and the
7607ending @code{@@end verbatim} will appear in the output.)
7608
7609
7610@node verbatiminclude
7611@section @code{@@verbatiminclude} @var{file}: Include a File Verbatim
7612@cindex Verbatim, include file
7613@cindex Including a file verbatim
7614@findex verbatiminclude
7615
--- 1190 unchanged lines hidden (view full) ---
8806
8807@menu
8808* syncodeindex:: How to merge two indices, using @code{@@code}
8809 font for the merged-from index.
8810* synindex:: How to merge two indices, using the
8811 default font of the merged-to index.
8812@end menu
8813
8814@node syncodeindex, synindex, Combining Indices, Combining Indices
8815@subsection @code{@@syncodeindex}
8816@findex syncodeindex
8817
8818When you want to combine functions and concepts into one index, you
8819should index the functions with @code{@@findex} and index the concepts
8820with @code{@@cindex}, and use the @code{@@syncodeindex} command to
8821redirect the function index entries into the concept index.@refill
8822@findex syncodeindex
--- 131 unchanged lines hidden (view full) ---
8954
8955The @code{@@defcodeindex} is like the @code{@@defindex} command, except
8956that, in the printed output, it prints entries in an @code{@@code} font
8957instead of a roman font. Thus, it parallels the @code{@@findex} command
8958rather than the @code{@@cindex} command.@refill
8959
8960You should define new indices within or right after the end-of-header
8961line of a Texinfo file, before any @code{@@synindex} or
8962@code{@@syncodeindex} commands (@pxref{Header}).@refill
8963
8964@node Insertions
8965@chapter Special Insertions
8966@cindex Inserting special characters and symbols
8967@cindex Special insertions
8968
8969Texinfo provides several commands for inserting characters that have
8970special meaning in Texinfo, such as braces, and for other graphic
8971elements that do not correspond to simple characters you can type.
--- 51 unchanged lines hidden (view full) ---
9023
9024@menu
9025* Inserting An Atsign:: How to insert @samp{@@}.
9026* Inserting Braces:: How to insert @samp{@{} and @samp{@}}.
9027@end menu
9028
9029@node Inserting An Atsign, Inserting Braces, Braces Atsigns, Braces Atsigns
9030@subsection Inserting @samp{@@} with @@@@
9031@findex @@ @r{(single @samp{@@})}
9032
9033@code{@@@@} stands for a single @samp{@@} in either printed or Info
9034output.
9035
9036Do not put braces after an @code{@@@@} command.
9037
9038
9039@node Inserting Braces
9040@subsection Inserting @samp{@{} and @samp{@}}with @@@{ and @@@}
9041@findex @{ @r{(single @samp{@{})}
9042@findex @} @r{(single @samp{@}})}
9043
9044@code{@@@{} stands for a single @samp{@{} in either printed or Info
9045output.
9046
9047@code{@@@}} stands for a single @samp{@}} in either printed or Info
9048output.
9049
9050Do not put braces after either an @code{@@@{} or an @code{@@@}}
--- 208 unchanged lines hidden (view full) ---
9259
9260Here is a table with the commands Texinfo provides for inserting
9261floating accents. The commands with non-alphabetic names do not take
9262braces around their argument (which is taken to be the next character).
9263(Exception: @code{@@,} @emph{does} take braces around its argument.)
9264This is so as to make the source as convenient to type and read as
9265possible, since accented characters are very common in some languages.
9266
9267@findex "
9268@cindex Umlaut accent
9269@findex '
9270@cindex Acute accent
9271@findex =
9272@cindex Macron accent
9273@findex ^
9274@cindex Circumflex accent
9275@findex `
9276@cindex Grave accent
9277@findex ~
9278@cindex Tilde accent
9279@findex ,
9280@cindex Cedilla accent
9281@findex dotaccent
9282@cindex Dot accent
9283@findex H
9284@cindex Hungarian umlaut accent
9285@findex ringaccent
9286@cindex Ring accent
9287@findex tieaccent
9288@cindex Tie-after accent
9289@findex u
9290@cindex Breve accent
9291@findex ubaraccent
9292@cindex Underbar accent
9293@findex udotaccent
9294@cindex Underdot accent
9295@findex v
9296@cindex Check accent
9297@multitable {@@questiondown@{@}} {Output} {macron/overbar accent}
9298@item Command @tab Output @tab What
9299@item @t{@@"o} @tab @"o @tab umlaut accent
9300@item @t{@@'o} @tab @'o @tab acute accent
9301@item @t{@@,@{c@}} @tab @,{c} @tab cedilla accent
9302@item @t{@@=o} @tab @=o @tab macron/overbar accent
9303@item @t{@@^o} @tab @^o @tab circumflex accent
--- 230 unchanged lines hidden (view full) ---
9534(a + b)(a + b) = a^2 + 2ab + b^2
9535@end example
9536
9537Thus, the @code{@@math} command has no effect on the Info output.
9538
9539@code{@@math} implies @code{@@tex}. This not only makes it possible to
9540write superscripts and subscripts (as in the above example), but also
9541allows you to use any of the plain @TeX{} math control sequences. It's
9542simplest to use @samp{\} instead of @samp{@@} for these commands. As
9543in:
9544@example
9545@@math@{\sin 2\pi \equiv \cos 3\pi@}
9546@end example
9547
9548@iftex
9549@noindent which looks like this in @TeX{}:
9550@display
9551@math{\sin 2\pi \equiv \cos 3\pi}
9552@end display
9553
9554@noindent and
9555@end iftex
9556@noindent which looks like the input in Info and HTML:
9557@example
9558\sin 2\pi \equiv \cos 3\pi
9559@end example
9560
9561@cindex Displayed equations
9562@cindex Equations, displayed
9563For displayed equations, you must at present use @TeX{} directly
9564(@pxref{Raw Formatter Commands}).
9565
9566
9567@node Glyphs
9568@section Glyphs for Examples
--- 797 unchanged lines hidden (view full) ---
10366refilled after the line break occurs, negating the effect of the line
10367break.@refill
10368@end quotation
10369
10370
10371@node - and hyphenation
10372@section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} hyphenate
10373
10374@findex -
10375@findex hyphenation
10376@cindex Hyphenation, helping @TeX{} do
10377@cindex Fine-tuning, and hyphenation
10378
10379Although @TeX{}'s hyphenation algorithm is generally pretty good, it
10380does miss useful hyphenation points from time to time. (Or, far more
10381rarely, insert an incorrect hyphenation.) So, for documents with an
10382unusual vocabulary or when fine-tuning for a printed edition, you may
10383wish to help @TeX{} out. Texinfo supports two commands for this:
10384
10385@table @code
10386@item @@-
10387Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does
10388not have to) hyphenate. This is especially useful when you notice
10389an overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull
10390hboxes}). @TeX{} will not insert any hyphenation points in a word
10391containing @code{@@-}.
10392
10393@item @@hyphenation@{@var{hy-phen-a-ted words}@}
10394Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you
10395put a @samp{-} at each hyphenation point. For example:
10396@example
10397@@hyphenation@{man-u-script man-u-scripts@}
10398@end example
10399@noindent @TeX{} only uses the specified hyphenation points when the
--- 1340 unchanged lines hidden (view full) ---
11740 all output formats); and how to set a
11741 flag to a string that you can insert.
11742@end menu
11743
11744
11745@node Conditional Commands
11746@section Conditional Commands
11747
11748@findex ifinfo
11749@code{@@ifinfo} begins segments of text that should be ignored by @TeX{}
11750when it typesets the printed manual. The segment of text appears only
11751in the Info file. The @code{@@ifinfo} command should appear on a line
11752by itself; end the Info-only text with a line containing @code{@@end
11753ifinfo} by itself. At the beginning of a Texinfo file, the Info
11754permissions are contained within a region marked by @code{@@ifinfo} and
11755@code{@@end ifinfo}. (@xref{Info Summary and Permissions}.)
11756
11757@findex iftex
11758@findex ifhtml
11759The @code{@@iftex} and @code{@@end iftex} commands are similar to the
11760@code{@@ifinfo} and @code{@@end ifinfo} commands, except that they
11761specify text that will appear in the printed manual but not in the Info
11762file. Likewise for @code{@@ifhtml} and @code{@@end ifhtml}, which
11763specify text to appear only in HTML output.@refill
11764
11765For example,
11766
11767@example
11768@@iftex
11769This text will appear only in the printed manual.
11770@@end iftex
11771@@ifinfo
11772However, this text will appear only in Info.
11773@@end ifinfo
11774@@ifhtml
11775And this text will only appear in HTML.
11776@@end ifhtml
11777@end example
11778
11779@noindent
11780The preceding example produces the following line:
11781@iftex
11782This text will appear only in the printed manual.
11783@end iftex
11784@ifinfo
11785However, this text will appear only in Info.
11786@end ifinfo
11787@ifhtml
11788And this text will only appear in HTML.
11789@end ifhtml
11790
11791@noindent
11792Notice that you only see one of the input lines, depending on which
11793version of the manual you are reading.
11794
11795
11796@node Conditional Not Commands
11797@section Conditional Not Commands
11798@findex ifnothtml
11799@findex ifnotinfo
11800@findex ifnottex
11801
11802You can specify text to be included in any output format @emph{other}
11803than some given one with the @code{@@ifnot@dots{}} commands:
11804@example
11805@@ifnothtml @dots{} @@end ifnothtml
11806@@ifnotinfo @dots{} @@end ifnotinfo
11807@@ifnottex @dots{} @@end ifnottex
11808@end example
11809@noindent
11810(The @code{@@ifnot@dots{}} command and the @code{@@end} command must
11811actually appear on lines by themselves.)
11812
11813If the output file is not being made for the given format, the region is
11814included. Otherwise, it is ignored.
11815
11816The regions delimited by these commands are ordinary Texinfo source as
11817with @code{@@iftex}, not raw formatter source as with @code{@@tex}
11818(@pxref{Raw Formatter Commands}).
11819
11820
11821@node Raw Formatter Commands
11822@section Raw Formatter Commands
11823@cindex @TeX{} commands, using ordinary
--- 251 unchanged lines hidden (view full) ---
12075@@ifclear @var{flag}
12076@end example
12077
12078
12079@node value Example
12080@subsection @code{@@value} Example
12081
12082You can use the @code{@@value} command to minimize the number of places
12083you need to change when you record an update to a manual. Here is how
12084it is done in @cite{The GNU Make Manual}:
12085
12086@enumerate
12087@item
12088Set the flags:
12089
12090@example
12091@group
12092@@set EDITION 0.35 Beta
12093@@set VERSION 3.63 Beta
12094@@set UPDATED 14 August 1992
12095@@set UPDATE-MONTH August 1992
12096@end group
12097@end example
12098
12099@item
12100Write text for the first @code{@@ifinfo} section, for people reading the
12101Texinfo file:
12102
12103@example
12104@group
12105This is Edition @@value@{EDITION@},
12106last updated @@value@{UPDATED@},
12107of @@cite@{The GNU Make Manual@},
12108for @@code@{make@}, version @@value@{VERSION@}.
12109@end group
12110@end example
12111
12112@item
12113Write text for the title page, for people reading the printed manual:
12114@c List only the month and the year since that looks less fussy on a
12115@c printed cover than a date that lists the day as well.
12116
12117@example
12118@group
12119@@title GNU Make
12120@@subtitle A Program for Directing Recompilation
12121@@subtitle Edition @@value@{EDITION@}, @dots{}
12122@@subtitle @@value@{UPDATE-MONTH@}
12123@end group
12124@end example
12125
12126@noindent
12127(On a printed cover, a date listing the month and the year looks less
12128fussy than a date listing the day as well as the month and year.)
12129
12130@item
12131Write text for the Top node, for people reading the Info file:
12132
12133@example
12134@group
12135This is Edition @@value@{EDITION@}
12136of the @@cite@{GNU Make Manual@},
12137last updated @@value@{UPDATED@}
12138for @@code@{make@} Version @@value@{VERSION@}.
12139@end group
12140@end example
12141
12142After you format the manual, the text in the first @code{@@ifinfo}
12143section looks like this:
12144
12145@example
12146@group
12147This is Edition 0.35 Beta, last updated 14 August 1992,
12148of `The GNU Make Manual', for `make', Version 3.63 Beta.
12149@end group
12150@end example
12151@end enumerate
12152
12153When you update the manual, change only the values of the flags; you do
12154not need to edit the three sections.
12155
12156
12157@node Internationalization
12158@chapter Internationalization
12159
12160@cindex Internationalization
12161Texinfo has some support for writing in languages other than English,
12162although this area still needs considerable work.
--- 492 unchanged lines hidden (view full) ---
12655always work.
12656
12657@item
12658The @TeX{} implementation cannot construct macros that define macros in
12659the natural way. To do this, you must use conditionals and raw @TeX{}.
12660For example:
12661
12662@example
12663@@ifinfo
12664@@macro ctor @{name, arg@}
12665@@macro \name\
12666something involving \arg\ somehow
12667@@end macro
12668@@end macro
12669@@end ifinfo
12670@@tex
12671\gdef\ctor#1@{\ctorx#1,@}
12672\gdef\ctorx#1,#2,@{\def#1@{something involving #2 somehow@}@}
12673@@end tex
12674@end example
12675
12676@item
12677It is best to avoid comments inside macro definitions.
--- 549 unchanged lines hidden (view full) ---
13227
13228You can change the values of these variables with the @kbd{M-x
13229edit-options} command (@pxref{Edit Options, , Editing Variable Values,
13230emacs, The GNU Emacs Manual}), with the @kbd{M-x set-variable} command
13231(@pxref{Examining, , Examining and Setting Variables, emacs, The GNU
13232Emacs Manual}), or with your @file{.emacs} initialization file
13233(@pxref{Init File, , , emacs, The GNU Emacs Manual}).@refill
13234
13235@cindex Customize Emacs package
13236@findex Development/Docs/Texinfo Customize group
13237Beginning with version 20, GNU Emacs offers a user-friendly interface,
13238called @dfn{Customize}, for changing values of user-definable variables.
13239@xref{Easy Customization, , Easy Customization Interface, emacs, The GNU
13240Emacs Manual}, for more details about this. The Texinfo variables can
13241be found in the @samp{Development/Docs/Texinfo} group, once you invoke
13242the @kbd{M-x customize} command.
13243
13244
13245@node Compile-Command, Requirements Summary, Texinfo Mode Printing, Hardcopy
13246@section Using the Local Variables List
13247@cindex Local variables
13248@cindex Compile command for formatting
13249@cindex Format with the compile command
13250
13251Yet another way to apply the @TeX{} formatting command to a Texinfo file
13252is to put that command in a @dfn{local variables list} at the end of the
13253Texinfo file. You can then specify the @code{tex} or @code{texi2dvi}
--- 384 unchanged lines hidden (view full) ---
13638sheet of film; but you can attempt to use it to mark the corners of a
13639book set to 7 by 9.25 inches with the @code{@@smallbook} command.
13640(Printers will not produce cropmarks for regular sized output that is
13641printed on regular sized paper.) Since different printing machines work
13642in different ways, you should explore the use of this command with a
13643spirit of adventure. You may have to redefine the command in
13644@file{texinfo.tex}.
13645
13646@findex mag @r{(@TeX{} command)}
13647@cindex Magnified printing
13648@cindex Larger or smaller pages
13649You can attempt to direct @TeX{} to typeset pages larger or smaller than
13650usual with the @code{\mag} @TeX{} command. Everything that is typeset
13651is scaled proportionally larger or smaller. (@code{\mag} stands for
13652``magnification''.) This is @emph{not} a Texinfo @@-command, but is a
13653plain @TeX{} command that is prefixed with a backslash. You have to
13654write this command between @code{@@tex} and @code{@@end tex}
--- 54 unchanged lines hidden (view full) ---
13709@node Creating and Installing Info Files
13710@chapter Creating and Installing Info Files
13711
13712This chapter describes how to create and install Info files. @xref{Info
13713Files}, for general information about the file format itself.
13714
13715@menu
13716* Creating an Info File::
13717* Installing an Info File::
13718@end menu
13719
13720
13721@node Creating an Info File
13722@section Creating an Info File
13723@cindex Creating an Info file
13724@cindex Info, creating an online file
13725@cindex Formatting a file for Info
--- 63 unchanged lines hidden (view full) ---
13789makeinfo --version
13790@end example
13791
13792@xref{makeinfo options}, for more information.
13793@end ifinfo
13794
13795
13796@node makeinfo options
13797@comment node-name, next, previous, up
13798@subsection Options for @code{makeinfo}
13799@cindex @code{makeinfo} options
13800@cindex Options for @code{makeinfo}
13801
13802The @code{makeinfo} command takes a number of options. Most often,
13803options are used to set the value of the fill column and specify the
13804footnote style. Each command line option is a word preceded by
13805@samp{--} or a letter preceded by @samp{-}. You can use abbreviations
--- 109 unchanged lines hidden (view full) ---
13915that does not support @code{@@macro}.
13916
13917@item --no-headers
13918@opindex --no-headers
13919@cindex Plain text output
13920@cindex ASCII text output
13921@cindex Generating plain text files
13922@cindex @file{INSTALL} file, generating
13923For Info output, do not include menus or node lines in the output and
13924write to standard output (unless @option{--output} is specified). This
13925results in an @sc{ascii} file that you cannot read in Info since it does
13926not contain the requisite nodes or menus. It is primarily useful to
13927extract certain pieces of a manual into separate files to be included in
13928a distribution, such as @file{INSTALL} files.
13929
13930@cindex Navigation links, omitting
13931For HTML output, if @samp{--no-split} is also specified, do not include a
13932navigation links at the top of each node. @xref{makeinfo html}.
13933
13934@item --no-split
13935@opindex --no-split
13936@cindex Splitting of output files
13937@cindex Output file splitting
13938Suppress the splitting stage of @code{makeinfo}. By default, large
13939output files (where the size is greater than 70k bytes) are split into
13940smaller subfiles. For Info output, each one is approximately 50k bytes.
13941For HTML output, each file contains one node (@pxref{makeinfo html}).
--- 475 unchanged lines hidden (view full) ---
14417which have special significance in HTML).
14418
14419The @samp{--footnote-style} option is currently ignored for HTML output;
14420footnotes are linked to the end of the output file.
14421
14422The HTML generated is mostly standard (i.e., HTML 2.0, RFC-1866). The
14423exception is that HTML 3.2 tables are generated from the
14424@code{@@multitable} command, but tagged to degrade as well as possible
14425in browsers without table support. Please report output from an
14426error-free run of @code{makeinfo} which violates the @w{HTML 3.2} DTD as
14427a bug.
14428
14429Navigation bars are inserted at the start of nodes, similarly to Info
14430output. The @samp{--no-headers} option will suppress this if used with
14431@samp{--no-split}. Header @code{<link>} elements in split output can
14432support info-like navigation with browsers like Lynx and @w{Emacs W3}
14433which implement this @w{HTML 1.0} feature. @samp{@@xref} commands to
14434other documents are generated assuming the other document is available
14435in split HTML form, and installed in the same HTML documentation tree,
--- 7 unchanged lines hidden (view full) ---
14443@cindex @file{dir} directory for Info installation
14444
14445Info files are usually kept in the @file{info} directory. You can read
14446Info files using the standalone Info program or the Info reader built
14447into Emacs. (@inforef{Top, info, info}, for an introduction to Info.)
14448
14449@menu
14450* Directory File:: The top level menu for all Info files.
14451* New Info File:: Listing a new info file.
14452* Other Info Directories:: How to specify Info files that are
14453 located in other directories.
14454* Installing Dir Entries:: How to specify what menu entry to add
14455 to the Info directory.
14456* Invoking install-info:: @code{install-info} options.
14457@end menu
14458
14459
--- 223 unchanged lines hidden (view full) ---
14683
14684When you install an Info file onto your system, you can use the program
14685@code{install-info} to update the Info directory file @file{dir}.
14686Normally the makefile for the package runs @code{install-info}, just
14687after copying the Info file into its proper installed location.
14688
14689@findex dircategory
14690@findex direntry
14691In order for the Info file to work with @code{install-info}, you should
14692use the commands @code{@@dircategory} and
14693@code{@@direntry}@dots{}@code{@@end direntry} in the Texinfo source
14694file. Use @code{@@direntry} to specify the menu entries to add to the
14695Info directory file, and use @code{@@dircategory} to specify which part
14696of the Info directory to put it in. Here is how these commands are used
14697in this manual:
14698
14699@smallexample
14700@@dircategory Texinfo documentation system
--- 31 unchanged lines hidden (view full) ---
14732Here are some recommended @code{@@dircategory} categories:
14733
14734@display
14735GNU packages
14736GNU programming tools
14737GNU programming documentation
14738GNU Emacs Lisp
14739GNU libraries
14740Linux
14741TeX
14742Individual utilities
14743@end display
14744
14745The idea is to include the `Invoking' node for every program installed
14746by a package under `Individual utilities', and an entry for the manual
14747as a whole in the appropriate other category.
14748
--- 135 unchanged lines hidden (view full) ---
14884
14885@item @@"
14886@itemx @@'
14887Generate an umlaut or acute accent, respectively, over the next
14888character, as in @"o and @'o. @xref{Inserting Accents}.
14889
14890@item @@*
14891Force a line break. Do not end a paragraph that uses @code{@@*} with
14892an @code{@@refill} command. @xref{Line Breaks}.@refill
14893
14894@item @@,@{@var{c}@}
14895Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting
14896Accents}.
14897
14898@item @@-
14899Insert a discretionary hyphenation point. @xref{- and hyphenation}.
14900
--- 15 unchanged lines hidden (view full) ---
14916@item @@?
14917Generate a question mark that really does end a sentence (usually after
14918an end-of-sentence capital letter). @xref{Ending a Sentence}.
14919
14920@item @@@@
14921Stands for an at sign, @samp{@@}.
14922@xref{Braces Atsigns, , Inserting @@ and braces}.
14923
14924@item @@^
14925@itemx @@`
14926Generate a circumflex (hat) or grave accent, respectively, over the next
14927character, as in @^o.
14928@xref{Inserting Accents}.
14929
14930@item @@@{
14931Stands for a left brace, @samp{@{}.
14932@xref{Braces Atsigns, , Inserting @@ and braces}.
14933
14934@item @@@}
14935Stands for a right-hand brace, @samp{@}}.@*
--- 376 unchanged lines hidden (view full) ---
15312
15313@item @@error@{@}
15314Indicate to the reader with a glyph that the following text is
15315an error message: @samp{@error{}}. @xref{Error Glyph}.@refill
15316
15317@item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
15318@itemx @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
15319Specify page footings resp.@: headings for even-numbered (left-hand)
15320pages. Only allowed inside @code{@@iftex}. @xref{Custom Headings, ,
15321How to Make Your Own Headings}.@refill
15322
15323@item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
15324@itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
15325Specify page footings resp.@: headings for every page. Not relevant to
15326Info. @xref{Custom Headings, , How to Make Your Own Headings}.@refill
15327
15328@item @@example
--- 82 unchanged lines hidden (view full) ---
15411Enter HTML completely. Pair with @code{@@end html}. @xref{Raw
15412Formatter Commands}.
15413
15414@item @@hyphenation@{@var{hy-phen-a-ted words}@}
15415Explicitly define hyphenation points. @xref{- and hyphenation,,
15416@code{@@-} and @code{@@hyphenation}}.
15417
15418@item @@i@{@var{text}@}
15419Print @var{text} in @i{italic} font. No effect in Info.
15420@xref{Fonts}.@refill
15421
15422@item @@ifclear @var{flag}
15423If @var{flag} is cleared, the Texinfo formatting commands format text
15424between @code{@@ifclear @var{flag}} and the following @code{@@end
15425ifclear} command.
15426@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
15427
15428@item @@ifhtml
15429@itemx @@ifinfo
15430Begin a stretch of text that will be ignored by @TeX{} when it typesets
15431the printed manual. The text appears only in the HTML resp.@: Info
15432file. Pair with @code{@@end ifhtml} resp.@: @code{@@end ifinfo}.
15433@xref{Conditionals}.
15434
15435@item @@ifnothtml
15436@itemx @@ifnotinfo
15437@itemx @@ifnottex
15438Begin a stretch of text that will be ignored in one output format but
15439not the others. The text appears only in the format not specified.
15440Pair with @code{@@end ifnothtml} resp.@: @code{@@end ifnotinfo} resp.@:
15441@code{@@end ifnotinfo}. @xref{Conditionals}.
15442
15443@item @@ifset @var{flag}
15444If @var{flag} is set, the Texinfo formatting commands format text
15445between @code{@@ifset @var{flag}} and the following @code{@@end ifset}
15446command.
15447@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
15448
15449@item @@iftex
15450Begin a stretch of text that will not appear in the Info file, but
--- 20 unchanged lines hidden (view full) ---
15471@code{@@inforef}}.@refill
15472
15473@item \input @var{macro-definitions-file}
15474Use the specified macro definitions file. This command is used only
15475in the first line of a Texinfo file to cause @TeX{} to make use of the
15476@file{texinfo} macro definitions file. The backslash in @code{\input}
15477is used instead of an @code{@@} because @TeX{} does not
15478recognize @code{@@} until after it has read the definitions file.
15479@xref{Header, , The Texinfo File Header}.@refill
15480
15481@item @@item
15482Indicate the beginning of a marked paragraph for @code{@@itemize} and
15483@code{@@enumerate}; indicate the beginning of the text of a first column
15484entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}.
15485@xref{Lists and Tables}.@refill
15486
15487@item @@itemize @var{mark-generating-character-or-command}
--- 89 unchanged lines hidden (view full) ---
15577@item @@O@{@}
15578@itemx @@o@{@}
15579Generate the uppercase and lowercase O-with-slash letters, respectively:
15580@O{}, @o{}.
15581
15582@item @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
15583@itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
15584Specify page footings resp.@: headings for odd-numbered (right-hand)
15585pages. Only allowed inside @code{@@iftex}. @xref{Custom Headings, ,
15586How to Make Your Own Headings}.@refill
15587
15588@item @@OE@{@}
15589@itemx @@oe@{@}
15590Generate the uppercase and lowercase OE ligatures, respectively:
15591@OE{}, @oe{}. @xref{Inserting Accents}.
15592
15593@item @@option@{@var{option-name}@}
--- 279 unchanged lines hidden (view full) ---
15873@xref{titlepage, , @code{@@titlepage}}.@refill
15874
15875@item @@today@{@}
15876Insert the current date, in `1 Jan 1900' style. @xref{Custom
15877Headings, , How to Make Your Own Headings}.@refill
15878
15879@item @@top @var{title}
15880In a Texinfo file to be formatted with @code{makeinfo}, identify the
15881topmost @code{@@node} line in the file, which must be written on the line
15882immediately preceding the @code{@@top} command. Used for
15883@code{makeinfo}'s node pointer insertion feature. The title is
15884underlined with asterisks. Both the @code{@@node} line and the @code{@@top}
15885line normally should be enclosed by @code{@@ifinfo} and @code{@@end
15886ifinfo}. In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
15887command is merely a synonym for @code{@@unnumbered}. @xref{makeinfo
15888Pointer Creation, , Creating Pointers with @code{makeinfo}}.
15889
15890@item @@u@{@var{c}@}
15891@itemx @@ubaraccent@{@var{c}@}
15892@itemx @@udotaccent@{@var{c}@}
15893Generate a breve, underbar, or underdot accent, respectively, over or
15894under the character @var{c}, as in @u{o}, @ubaraccent{o},
--- 65 unchanged lines hidden (view full) ---
15960Add @var{entry} to the index of variables. @xref{Index Entries, ,
15961Defining the Entries of an Index}.@refill
15962
15963@item @@vskip @var{amount}
15964In a printed manual, insert whitespace so as to push text on the
15965remainder of the page towards the bottom of the page. Used in
15966formatting the copyright page with the argument @samp{0pt plus
159671filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used
15968only in contexts ignored for Info. @xref{Copyright & Permissions, ,
15969The Copyright Page and Printed Permissions}.@refill
15970
15971@item @@vtable @var{formatting-command}
15972Begin a two-column table, using @code{@@item} for each entry.
15973Automatically enter each of the items in the first column into the
15974index of variables. Pair with @code{@@end vtable}. The same as
15975@code{@@table}, except for indexing. @xref{ftable vtable, ,
15976@code{@@ftable} and @code{@@vtable}}.@refill
15977
--- 154 unchanged lines hidden (view full) ---
16132@item
16133Write the prefatory sentence or phrase for a multi-item list or table as
16134a complete expression. Do not write ``You can set:''; instead, write
16135``You can set these variables:''. The former expression sounds cut off.
16136@end itemize
16137
16138@subsubheading Editions, Dates and Versions
16139
16140Write the edition and version numbers and date in three places in every
16141manual:
16142
16143@enumerate
16144@item
16145In the first @code{@@ifinfo} section, for people reading the Texinfo file.
16146
16147@item
16148In the @code{@@titlepage} section, for people reading the printed manual.
16149
16150@item
16151In the `Top' node, for people reading the Info file.
16152@end enumerate
16153
16154@noindent
16155Also, it helps to write a note before the first @code{@@ifinfo}
16156section to explain what you are doing.
16157
16158@need 800
16159@noindent
16160For example:
16161
16162@example
16163@group
16164@@c ===> NOTE! <==
16165@@c Specify the edition and version numbers and date
16166@@c in *three* places:
16167@@c 1. First ifinfo section 2. title page 3. top node
16168@@c To find the locations, search for !!set
16169@end group
16170
16171@group
16172@@ifinfo
16173@@c !!set edition, date, version
16174This is Edition 4.03, January 1992,
16175of the @@cite@{GDB Manual@} for GDB Version 4.3.
16176@dots{}
16177@end group
16178@end example
16179
16180@noindent
16181---or use @code{@@set} and @code{@@value}
16182(@pxref{value Example, , @code{@@value} Example}).
16183
16184@subsubheading Definition Commands
16185
16186Definition commands are @code{@@deffn}, @code{@@defun},
16187@code{@@defmac}, and the like, and enable you to write descriptions in
16188a uniform format.@refill
16189
16190@itemize @bullet
16191@item
--- 232 unchanged lines hidden (view full) ---
16424@item
16425Write notes for yourself at the very end of a Texinfo file after the
16426@code{@@bye}. None of the formatters process text after the
16427@code{@@bye}; it is as if the text were within @code{@@ignore} @dots{}
16428@code{@@end ignore}.
16429@end itemize
16430
16431
16432@node Sample Texinfo File
16433@appendix A Sample Texinfo File
16434@cindex Sample Texinfo file, no comments
16435
16436Here is a complete, short sample Texinfo file, without any commentary.
16437You can see this file, with comments, in the first chapter.
16438@xref{Short Sample, , A Short Sample Texinfo File}.
16439
16440@sp 1
16441@example
16442\input texinfo @@c -*-texinfo-*-
16443@@c %**start of header
16444@@setfilename sample.info
16445@@settitle Sample Document
16446@@c %**end of header
16447
16448@@ifinfo
16449This is a short example of a complete Texinfo file.
16450
16451Copyright (C) 2002 Free Software Foundation, Inc.
16452@@end ifinfo
16453
16454@@titlepage
16455@@comment The title is printed in a large font.
16456@@title Sample Title
16457
16458@@c The following two commands start the copyright page.
16459@@page
16460@@vskip 0pt plus 1filll
16461Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
16462@@end titlepage
16463
16464@@c Output the table of the contents at the beginning.
16465@@contents
16466
16467@@ifnottex
16468@@node Top
16469
16470This is the top node of a sample document.
16471@@end ifnottex
16472
16473@@menu
16474* First Chapter:: The first chapter is the
16475 only chapter in this sample.
16476* Concept Index:: This index has two entries.
16477@@end menu
16478
16479
16480@@node First Chapter
16481@@chapter First Chapter
16482@@cindex Chapter, first
16483
16484This is the contents of the first chapter.
16485@@cindex Another sample index entry
16486
16487Here is a numbered list.
16488
16489@@enumerate
16490@@item
16491This is the first item.
16492
16493@@item
16494This is the second item.
16495@@end enumerate
16496
16497The @@code@{makeinfo@} command transforms a Texinfo source file
16498such as this into an Info file or HTML; and @@TeX typesets it
16499for a printed manual.
16500
16501
16502@@node Concept Index
16503@@unnumbered Concept Index
16504
16505@@printindex cp
16506
16507@@bye
16508@end example
16509
16510
16511@node Include Files
16512@appendix Include Files
16513@cindex Include files
16514
16515When @TeX{} or an Info formatting command sees an @code{@@include}
16516command in a Texinfo file, it processes the contents of the file named
16517by the command and incorporates them into the DVI or Info file being
16518created. Index entries from the included file are incorporated into
16519the indices of the output file.@refill
16520
16521Include files let you keep a single large document as a collection of
16522conveniently small parts.
16523
16524@menu
16525* Using Include Files:: How to use the @code{@@include} command.
16526* texinfo-multiple-files-update:: How to create and update nodes and
16527 menus when using included files.
--- 199 unchanged lines hidden (view full) ---
16727@group
16728@@summarycontents
16729@@contents
16730
16731@@bye
16732@end group
16733@end example
16734
16735An included file, such as @file{foo.texinfo}, might look like
16736this:@refill
16737
16738@example
16739@group
16740@@node First, Second, , Top
16741@@chapter First Chapter
16742
16743Contents of first chapter @dots{}
16744@end group
--- 237 unchanged lines hidden (view full) ---
16982@code{@@evenheading} and @code{@@evenfooting} command generate headers
16983and footers for even-numbered (left-hand) pages.
16984@item
16985@code{@@oddheading} and @code{@@oddfooting} generate headers and footers
16986for odd-numbered (right-hand) pages.
16987@end itemize
16988
16989Write custom heading specifications in the Texinfo file immediately
16990after the @code{@@end titlepage} command. Enclose your specifications
16991between @code{@@iftex} and @code{@@end iftex} commands since the
16992@code{texinfo-format-buffer} command may not recognize them. Also,
16993you must cancel the predefined heading commands with the
16994@code{@@headings off} command before defining your own
16995specifications.@refill
16996
16997@need 1000
16998Here is how to tell @TeX{} to place the chapter name at the left, the
16999page number in the center, and the date at the right of every header
17000for both even- and odd-numbered pages:@refill
17001
17002@example
17003@group
17004@@iftex
17005@@headings off
17006@@everyheading @@thischapter @@| @@thispage @@| @@today@{@}
17007@@end iftex
17008@end group
17009@end example
17010
17011@noindent
17012You need to divide the left part from the central part and the central
17013part from the right part by inserting @samp{@@|} between parts.
17014Otherwise, the specification command will not be able to tell where
17015the text for one part ends and the next part begins.@refill
--- 83 unchanged lines hidden (view full) ---
17099@findex today
17100
17101Other @@-commands and text are printed in a header or footer just as
17102if they were in the body of a page. It is useful to incorporate text,
17103particularly when you are writing drafts:@refill
17104
17105@example
17106@group
17107@@iftex
17108@@headings off
17109@@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter
17110@@everyfooting @@| @@| Version: 0.27: @@today@{@}
17111@@end iftex
17112@end group
17113@end example
17114
17115Beware of overlong titles: they may overlap another part of the
17116header or footer and blot it out.@refill
17117
17118
17119@node Catching Mistakes
17120@appendix Formatting Mistakes
17121@cindex Structure, catching mistakes in
17122@cindex Nodes, catching mistakes
17123@cindex Catching mistakes
17124@cindex Correcting mistakes
17125@cindex Mistakes, catching
17126@cindex Problems, catching
17127@cindex Debugging the Texinfo structure
17128
17129Besides mistakes in the content of your documentation, there
17130are two kinds of mistake you can make with Texinfo: you can make mistakes
17131with @@-commands, and you can make mistakes with the structure of the
17132nodes and chapters.@refill
17133
17134Emacs has two tools for catching the @@-command mistakes and two for
17135catching structuring mistakes.@refill
17136
17137For finding problems with @@-commands, you can run @TeX{} or a region
17138formatting command on the region that has a problem; indeed, you can
17139run these commands on each region as you write it.@refill
17140
--- 1306 unchanged lines hidden (view full) ---
18447@end table
18448@tex
18449% Switch width of first column of tables back to default value
18450\global\tableindent=.8in
18451@end tex
18452@end ignore
18453
18454
18455@node Documentation Copying
18456@appendix GNU Free Documentation License
18457
18458@cindex FDL, GNU Free Documentation License
18459@center Version 1.1, March 2000
18460
18461@display
18462Copyright @copyright{} 2000 Free Software Foundation, Inc.
1846359 Temple Place, Suite 330, Boston, MA 02111-1307, USA
18464
18465Everyone is permitted to copy and distribute verbatim copies
18466of this license document, but changing it is not allowed.
18467@end display
18468
18469@enumerate 0
18470@item
18471PREAMBLE
18472
18473The purpose of this License is to make a manual, textbook, or other
18474written document @dfn{free} in the sense of freedom: to assure everyone
18475the effective freedom to copy and redistribute it, with or without
18476modifying it, either commercially or noncommercially. Secondarily,
18477this License preserves for the author and publisher a way to get
18478credit for their work, while not being considered responsible for
18479modifications made by others.
18480
18481This License is a kind of ``copyleft'', which means that derivative
18482works of the document must themselves be free in the same sense. It
18483complements the GNU General Public License, which is a copyleft
18484license designed for free software.
18485
18486We have designed this License in order to use it for manuals for free
18487software, because free software needs free documentation: a free
18488program should come with manuals providing the same freedoms that the
18489software does. But this License is not limited to software manuals;
18490it can be used for any textual work, regardless of subject matter or
18491whether it is published as a printed book. We recommend this License
18492principally for works whose purpose is instruction or reference.
18493
18494@item
18495APPLICABILITY AND DEFINITIONS
18496
18497This License applies to any manual or other work that contains a
18498notice placed by the copyright holder saying it can be distributed
18499under the terms of this License. The ``Document'', below, refers to any
18500such manual or work. Any member of the public is a licensee, and is
18501addressed as ``you''.
18502
18503A ``Modified Version'' of the Document means any work containing the
18504Document or a portion of it, either copied verbatim, or with
18505modifications and/or translated into another language.
18506
18507A ``Secondary Section'' is a named appendix or a front-matter section of
18508the Document that deals exclusively with the relationship of the
18509publishers or authors of the Document to the Document's overall subject
18510(or to related matters) and contains nothing that could fall directly
18511within that overall subject. (For example, if the Document is in part a
18512textbook of mathematics, a Secondary Section may not explain any
18513mathematics.) The relationship could be a matter of historical
18514connection with the subject or with related matters, or of legal,
18515commercial, philosophical, ethical or political position regarding
18516them.
18517
18518The ``Invariant Sections'' are certain Secondary Sections whose titles
18519are designated, as being those of Invariant Sections, in the notice
18520that says that the Document is released under this License.
18521
18522The ``Cover Texts'' are certain short passages of text that are listed,
18523as Front-Cover Texts or Back-Cover Texts, in the notice that says that
18524the Document is released under this License.
18525
18526A ``Transparent'' copy of the Document means a machine-readable copy,
18527represented in a format whose specification is available to the
18528general public, whose contents can be viewed and edited directly and
18529straightforwardly with generic text editors or (for images composed of
18530pixels) generic paint programs or (for drawings) some widely available
18531drawing editor, and that is suitable for input to text formatters or
18532for automatic translation to a variety of formats suitable for input
18533to text formatters. A copy made in an otherwise Transparent file
18534format whose markup has been designed to thwart or discourage
18535subsequent modification by readers is not Transparent. A copy that is
18536not ``Transparent'' is called ``Opaque''.
18537
18538Examples of suitable formats for Transparent copies include plain
18539@sc{ascii} without markup, Texinfo input format, La@TeX{} input format,
18540@acronym{SGML} or @acronym{XML} using a publicly available
18541@acronym{DTD}, and standard-conforming simple @acronym{HTML} designed
18542for human modification. Opaque formats include PostScript,
18543@acronym{PDF}, proprietary formats that can be read and edited only by
18544proprietary word processors, @acronym{SGML} or @acronym{XML} for which
18545the @acronym{DTD} and/or processing tools are not generally available,
18546and the machine-generated @acronym{HTML} produced by some word
18547processors for output purposes only.
18548
18549The ``Title Page'' means, for a printed book, the title page itself,
18550plus such following pages as are needed to hold, legibly, the material
18551this License requires to appear in the title page. For works in
18552formats which do not have any title page as such, ``Title Page'' means
18553the text near the most prominent appearance of the work's title,
18554preceding the beginning of the body of the text.
18555
18556@item
18557VERBATIM COPYING
18558
18559You may copy and distribute the Document in any medium, either
18560commercially or noncommercially, provided that this License, the
18561copyright notices, and the license notice saying this License applies
18562to the Document are reproduced in all copies, and that you add no other
18563conditions whatsoever to those of this License. You may not use
18564technical measures to obstruct or control the reading or further
18565copying of the copies you make or distribute. However, you may accept
18566compensation in exchange for copies. If you distribute a large enough
18567number of copies you must also follow the conditions in section 3.
18568
18569You may also lend copies, under the same conditions stated above, and
18570you may publicly display copies.
18571
18572@item
18573COPYING IN QUANTITY
18574
18575If you publish printed copies of the Document numbering more than 100,
18576and the Document's license notice requires Cover Texts, you must enclose
18577the copies in covers that carry, clearly and legibly, all these Cover
18578Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
18579the back cover. Both covers must also clearly and legibly identify
18580you as the publisher of these copies. The front cover must present
18581the full title with all words of the title equally prominent and
18582visible. You may add other material on the covers in addition.
18583Copying with changes limited to the covers, as long as they preserve
18584the title of the Document and satisfy these conditions, can be treated
18585as verbatim copying in other respects.
18586
18587If the required texts for either cover are too voluminous to fit
18588legibly, you should put the first ones listed (as many as fit
18589reasonably) on the actual cover, and continue the rest onto adjacent
18590pages.
18591
18592If you publish or distribute Opaque copies of the Document numbering
18593more than 100, you must either include a machine-readable Transparent
18594copy along with each Opaque copy, or state in or with each Opaque copy
18595a publicly-accessible computer-network location containing a complete
18596Transparent copy of the Document, free of added material, which the
18597general network-using public has access to download anonymously at no
18598charge using public-standard network protocols. If you use the latter
18599option, you must take reasonably prudent steps, when you begin
18600distribution of Opaque copies in quantity, to ensure that this
18601Transparent copy will remain thus accessible at the stated location
18602until at least one year after the last time you distribute an Opaque
18603copy (directly or through your agents or retailers) of that edition to
18604the public.
18605
18606It is requested, but not required, that you contact the authors of the
18607Document well before redistributing any large number of copies, to give
18608them a chance to provide you with an updated version of the Document.
18609
18610@item
18611MODIFICATIONS
18612
18613You may copy and distribute a Modified Version of the Document under
18614the conditions of sections 2 and 3 above, provided that you release
18615the Modified Version under precisely this License, with the Modified
18616Version filling the role of the Document, thus licensing distribution
18617and modification of the Modified Version to whoever possesses a copy
18618of it. In addition, you must do these things in the Modified Version:
18619
18620@enumerate A
18621@item
18622Use in the Title Page (and on the covers, if any) a title distinct
18623from that of the Document, and from those of previous versions
18624(which should, if there were any, be listed in the History section
18625of the Document). You may use the same title as a previous version
18626if the original publisher of that version gives permission.
18627
18628@item
18629List on the Title Page, as authors, one or more persons or entities
18630responsible for authorship of the modifications in the Modified
18631Version, together with at least five of the principal authors of the
18632Document (all of its principal authors, if it has less than five).
18633
18634@item
18635State on the Title page the name of the publisher of the
18636Modified Version, as the publisher.
18637
18638@item
18639Preserve all the copyright notices of the Document.
18640
18641@item
18642Add an appropriate copyright notice for your modifications
18643adjacent to the other copyright notices.
18644
18645@item
18646Include, immediately after the copyright notices, a license notice
18647giving the public permission to use the Modified Version under the
18648terms of this License, in the form shown in the Addendum below.
18649
18650@item
18651Preserve in that license notice the full lists of Invariant Sections
18652and required Cover Texts given in the Document's license notice.
18653
18654@item
18655Include an unaltered copy of this License.
18656
18657@item
18658Preserve the section entitled ``History'', and its title, and add to
18659it an item stating at least the title, year, new authors, and
18660publisher of the Modified Version as given on the Title Page. If
18661there is no section entitled ``History'' in the Document, create one
18662stating the title, year, authors, and publisher of the Document as
18663given on its Title Page, then add an item describing the Modified
18664Version as stated in the previous sentence.
18665
18666@item
18667Preserve the network location, if any, given in the Document for
18668public access to a Transparent copy of the Document, and likewise
18669the network locations given in the Document for previous versions
18670it was based on. These may be placed in the ``History'' section.
18671You may omit a network location for a work that was published at
18672least four years before the Document itself, or if the original
18673publisher of the version it refers to gives permission.
18674
18675@item
18676In any section entitled ``Acknowledgments'' or ``Dedications'',
18677preserve the section's title, and preserve in the section all the
18678substance and tone of each of the contributor acknowledgments
18679and/or dedications given therein.
18680
18681@item
18682Preserve all the Invariant Sections of the Document,
18683unaltered in their text and in their titles. Section numbers
18684or the equivalent are not considered part of the section titles.
18685
18686@item
18687Delete any section entitled ``Endorsements''. Such a section
18688may not be included in the Modified Version.
18689
18690@item
18691Do not retitle any existing section as ``Endorsements''
18692or to conflict in title with any Invariant Section.
18693@end enumerate
18694
18695If the Modified Version includes new front-matter sections or
18696appendices that qualify as Secondary Sections and contain no material
18697copied from the Document, you may at your option designate some or all
18698of these sections as invariant. To do this, add their titles to the
18699list of Invariant Sections in the Modified Version's license notice.
18700These titles must be distinct from any other section titles.
18701
18702You may add a section entitled ``Endorsements'', provided it contains
18703nothing but endorsements of your Modified Version by various
18704parties---for example, statements of peer review or that the text has
18705been approved by an organization as the authoritative definition of a
18706standard.
18707
18708You may add a passage of up to five words as a Front-Cover Text, and a
18709passage of up to 25 words as a Back-Cover Text, to the end of the list
18710of Cover Texts in the Modified Version. Only one passage of
18711Front-Cover Text and one of Back-Cover Text may be added by (or
18712through arrangements made by) any one entity. If the Document already
18713includes a cover text for the same cover, previously added by you or
18714by arrangement made by the same entity you are acting on behalf of,
18715you may not add another; but you may replace the old one, on explicit
18716permission from the previous publisher that added the old one.
18717
18718The author(s) and publisher(s) of the Document do not by this License
18719give permission to use their names for publicity for or to assert or
18720imply endorsement of any Modified Version.
18721
18722@item
18723COMBINING DOCUMENTS
18724
18725You may combine the Document with other documents released under this
18726License, under the terms defined in section 4 above for modified
18727versions, provided that you include in the combination all of the
18728Invariant Sections of all of the original documents, unmodified, and
18729list them all as Invariant Sections of your combined work in its
18730license notice.
18731
18732The combined work need only contain one copy of this License, and
18733multiple identical Invariant Sections may be replaced with a single
18734copy. If there are multiple Invariant Sections with the same name but
18735different contents, make the title of each such section unique by
18736adding at the end of it, in parentheses, the name of the original
18737author or publisher of that section if known, or else a unique number.
18738Make the same adjustment to the section titles in the list of
18739Invariant Sections in the license notice of the combined work.
18740
18741In the combination, you must combine any sections entitled ``History''
18742in the various original documents, forming one section entitled
18743``History''; likewise combine any sections entitled ``Acknowledgments'',
18744and any sections entitled ``Dedications''. You must delete all sections
18745entitled ``Endorsements.''
18746
18747@item
18748COLLECTIONS OF DOCUMENTS
18749
18750You may make a collection consisting of the Document and other documents
18751released under this License, and replace the individual copies of this
18752License in the various documents with a single copy that is included in
18753the collection, provided that you follow the rules of this License for
18754verbatim copying of each of the documents in all other respects.
18755
18756You may extract a single document from such a collection, and distribute
18757it individually under this License, provided you insert a copy of this
18758License into the extracted document, and follow this License in all
18759other respects regarding verbatim copying of that document.
18760
18761@item
18762AGGREGATION WITH INDEPENDENT WORKS
18763
18764A compilation of the Document or its derivatives with other separate
18765and independent documents or works, in or on a volume of a storage or
18766distribution medium, does not as a whole count as a Modified Version
18767of the Document, provided no compilation copyright is claimed for the
18768compilation. Such a compilation is called an ``aggregate'', and this
18769License does not apply to the other self-contained works thus compiled
18770with the Document, on account of their being thus compiled, if they
18771are not themselves derivative works of the Document.
18772
18773If the Cover Text requirement of section 3 is applicable to these
18774copies of the Document, then if the Document is less than one quarter
18775of the entire aggregate, the Document's Cover Texts may be placed on
18776covers that surround only the Document within the aggregate.
18777Otherwise they must appear on covers around the whole aggregate.
18778
18779@item
18780TRANSLATION
18781
18782Translation is considered a kind of modification, so you may
18783distribute translations of the Document under the terms of section 4.
18784Replacing Invariant Sections with translations requires special
18785permission from their copyright holders, but you may include
18786translations of some or all Invariant Sections in addition to the
18787original versions of these Invariant Sections. You may include a
18788translation of this License provided that you also include the
18789original English version of this License. In case of a disagreement
18790between the translation and the original English version of this
18791License, the original English version will prevail.
18792
18793@item
18794TERMINATION
18795
18796You may not copy, modify, sublicense, or distribute the Document except
18797as expressly provided for under this License. Any other attempt to
18798copy, modify, sublicense or distribute the Document is void, and will
18799automatically terminate your rights under this License. However,
18800parties who have received copies, or rights, from you under this
18801License will not have their licenses terminated so long as such
18802parties remain in full compliance.
18803
18804@item
18805FUTURE REVISIONS OF THIS LICENSE
18806
18807The Free Software Foundation may publish new, revised versions
18808of the GNU Free Documentation License from time to time. Such new
18809versions will be similar in spirit to the present version, but may
18810differ in detail to address new problems or concerns. See
18811@uref{http://www.gnu.org/copyleft/}.
18812
18813Each version of the License is given a distinguishing version number.
18814If the Document specifies that a particular numbered version of this
18815License ``or any later version'' applies to it, you have the option of
18816following the terms and conditions either of that specified version or
18817of any later version that has been published (not as a draft) by the
18818Free Software Foundation. If the Document does not specify a version
18819number of this License, you may choose any version ever published (not
18820as a draft) by the Free Software Foundation.
18821@end enumerate
18822
18823@page
18824@appendixsubsec ADDENDUM: How to use this License for your documents
18825
18826To use this License in a document you have written, include a copy of
18827the License in the document and put the following copyright and
18828license notices just after the title page:
18829
18830@smallexample
18831@group
18832 Copyright (C) @var{year} @var{your name}.
18833 Permission is granted to copy, distribute and/or modify this document
18834 under the terms of the GNU Free Documentation License, Version 1.1
18835 or any later version published by the Free Software Foundation;
18836 with the Invariant Sections being @var{list their titles}, with the
18837 Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}.
18838 A copy of the license is included in the section entitled ``GNU
18839 Free Documentation License''.
18840@end group
18841@end smallexample
18842
18843If you have no Invariant Sections, write ``with no Invariant Sections''
18844instead of saying which ones are invariant. If you have no
18845Front-Cover Texts, write ``no Front-Cover Texts'' instead of
18846``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
18847
18848If your document contains nontrivial examples of program code, we
18849recommend releasing these examples in parallel under your choice of
18850free software license, such as the GNU General Public License,
18851to permit their use in free software.
18852
18853
18854@node Command and Variable Index
18855@unnumbered Command and Variable Index
18856
18857This is an alphabetical list of all the @@-commands, assorted Emacs Lisp
18858functions, and several variables. To make the list easier to use, the
18859commands are listed without their preceding @samp{@@}.@refill
18860
18861@printindex fn
18862
18863
18864@node Concept Index
18865@unnumbered Concept Index
18866
18867@printindex cp
18868
18869
18870@bye