1 This is Info file ../info/texinfo.info, produced by Makeinfo version
2 1.68 from the input file texinfo.texi.
4 INFO-DIR-SECTION Texinfo documentation system
6 * Texinfo: (texinfo). The GNU documentation format.
7 * install-info: (texinfo)Invoking install-info. Updating info/dir entries.
8 * texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
9 * texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
10 * makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
13 This file documents Texinfo, a documentation system that can produce
14 both on-line information and a printed manual from a single source file.
16 Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
19 This edition is for Texinfo version 3.12.
21 Permission is granted to make and distribute verbatim copies of this
22 manual provided the copyright notice and this permission notice are
23 preserved on all copies.
25 Permission is granted to copy and distribute modified versions of this
26 manual under the conditions for verbatim copying, provided that the
27 entire resulting derived work is distributed under the terms of a
28 permission notice identical to this one.
30 Permission is granted to copy and distribute translations of this
31 manual into another language, under the above conditions for modified
32 versions, except that this permission notice may be stated in a
33 translation approved by the Free Software Foundation.
36 File: texinfo.info, Node: setchapternewpage, Next: paragraphindent, Prev: settitle, Up: Header
41 In a book or a manual, text is usually printed on both sides of the
42 paper, chapters start on right-hand pages, and right-hand pages have
43 odd numbers. But in short reports, text often is printed only on one
44 side of the paper. Also in short reports, chapters sometimes do not
45 start on new pages, but are printed on the same page as the end of the
46 preceding chapter, after a small amount of vertical whitespace.
48 You can use the `@setchapternewpage' command with various arguments
49 to specify how TeX should start chapters and whether it should typeset
50 pages for printing on one or both sides of the paper (single-sided or
51 double-sided printing).
53 Write the `@setchapternewpage' command at the beginning of a line
54 followed by its argument.
56 For example, you would write the following to cause each chapter to
57 start on a fresh odd-numbered page:
59 @setchapternewpage odd
61 You can specify one of three alternatives with the
62 `@setchapternewpage' command:
64 `@setchapternewpage off'
65 Cause TeX to typeset a new chapter on the same page as the last
66 chapter, after skipping some vertical whitespace. Also, cause TeX
67 to format page headers for single-sided printing. (You can
68 override the headers format with the `@headings double' command;
69 see *Note The `@headings' Command: headings on off.)
71 `@setchapternewpage on'
72 Cause TeX to start new chapters on new pages and to typeset page
73 headers for single-sided printing. This is the form most often
74 used for short reports.
76 This alternative is the default.
78 `@setchapternewpage odd'
79 Cause TeX to start new chapters on new, odd-numbered pages
80 (right-handed pages) and to typeset for double-sided printing.
81 This is the form most often used for books and manuals.
83 Texinfo does not have an `@setchapternewpage even' command.
85 (You can countermand or modify an `@setchapternewpage' command with an
86 `@headings' command. *Note The `@headings' Command: headings on off.)
88 At the beginning of a manual or book, pages are not numbered--for
89 example, the title and copyright pages of a book are not numbered. By
90 convention, table of contents pages are numbered with roman numerals
91 and not in sequence with the rest of the document.
93 Since an Info file does not have pages, the `@setchapternewpage'
94 command has no effect on it.
96 Usually, you do not write an `@setchapternewpage' command for
97 single-sided printing, but accept the default which is to typeset for
98 single-sided printing and to start new chapters on new pages. Usually,
99 you write an `@setchapternewpage odd' command for double-sided printing.
102 File: texinfo.info, Node: paragraphindent, Next: End of Header, Prev: setchapternewpage, Up: Header
107 The Info formatting commands may insert spaces at the beginning of the
108 first line of each paragraph, thereby indenting that paragraph. You
109 can use the `@paragraphindent' command to specify the indentation.
110 Write an `@paragraphindent' command at the beginning of a line followed
111 by either `asis' or a number. The template is:
113 @paragraphindent INDENT
115 The Info formatting commands indent according to the value of INDENT:
117 * If the value of INDENT is `asis', the Info formatting commands do
118 not change the existing indentation.
120 * If the value of INDENT is zero, the Info formatting commands delete
121 existing indentation.
123 * If the value of INDENT is greater than zero, the Info formatting
124 commands indent the paragraph by that number of spaces.
126 The default value of INDENT is `asis'.
128 Write the `@paragraphindent' command before or shortly after the
129 end-of-header line at the beginning of a Texinfo file. (If you write
130 the command between the start-of-header and end-of-header lines, the
131 region formatting commands indent paragraphs as specified.)
133 A peculiarity of the `texinfo-format-buffer' and
134 `texinfo-format-region' commands is that they do not indent (nor fill)
135 paragraphs that contain `@w' or `@*' commands. *Note Refilling
136 Paragraphs::, for a detailed description of what goes on.
139 File: texinfo.info, Node: End of Header, Prev: paragraphindent, Up: Header
144 Follow the header lines with an end-of-header line. An end-of-header
145 line looks like this:
149 If you include the `@setchapternewpage' command between the
150 start-of-header and end-of-header lines, TeX will typeset a region as
151 that command specifies. Similarly, if you include an `@smallbook'
152 command between the start-of-header and end-of-header lines, TeX will
153 typeset a region in the "small" book format.
155 The reason for the odd string of characters (`%**') is so that the
156 `texinfo-tex-region' command does not accidentally find something that
157 it should not when it is looking for the header.
159 The start-of-header line and the end-of-header line are Texinfo mode
160 variables that you can change.
163 File: texinfo.info, Node: Info Summary and Permissions, Next: Titlepage & Copyright Page, Prev: Header, Up: Beginning a File
165 Summary and Copying Permissions for Info
166 ========================================
168 The title page and the copyright page appear only in the printed copy
169 of the manual; therefore, the same information must be inserted in a
170 section that appears only in the Info file. This section usually
171 contains a brief description of the contents of the Info file, a
172 copyright notice, and copying permissions.
174 The copyright notice should read:
176 Copyright YEAR COPYRIGHT-OWNER
178 and be put on a line by itself.
180 Standard text for the copyright permissions is contained in an
181 appendix to this manual; see *Note `ifinfo' Copying Permissions: ifinfo
182 Permissions, for the complete text.
184 The permissions text appears in an Info file *before* the first node.
185 This mean that a reader does *not* see this text when reading the file
186 using Info, except when using the advanced Info command `g *'.
189 File: texinfo.info, Node: Titlepage & Copyright Page, Next: The Top Node, Prev: Info Summary and Permissions, Up: Beginning a File
191 The Title and Copyright Pages
192 =============================
194 A manual's name and author are usually printed on a title page.
195 Sometimes copyright information is printed on the title page as well;
196 more often, copyright information is printed on the back of the title
199 The title and copyright pages appear in the printed manual, but not
200 in the Info file. Because of this, it is possible to use several
201 slightly obscure TeX typesetting commands that cannot be used in an
202 Info file. In addition, this part of the beginning of a Texinfo file
203 contains the text of the copying permissions that will appear in the
206 *Note Titlepage Copying Permissions: Titlepage Permissions, for the
207 standard text for the copyright permissions.
211 * titlepage:: Create a title for the printed document.
212 * titlefont center sp:: The `@titlefont', `@center',
214 * title subtitle author:: The `@title', `@subtitle',
215 and `@author' commands.
216 * Copyright & Permissions:: How to write the copyright notice and
217 include copying permissions.
218 * end titlepage:: Turn on page headings after the title and
220 * headings on off:: An option for turning headings on and off
221 and double or single sided printing.
224 File: texinfo.info, Node: titlepage, Next: titlefont center sp, Prev: Titlepage & Copyright Page, Up: Titlepage & Copyright Page
229 Start the material for the title page and following copyright page
230 with `@titlepage' on a line by itself and end it with `@end titlepage'
233 The `@end titlepage' command starts a new page and turns on page
234 numbering. (*Note Page Headings: Headings, for details about how to
235 generate page headings.) All the material that you want to appear on
236 unnumbered pages should be put between the `@titlepage' and `@end
237 titlepage' commands. By using the `@page' command you can force a page
238 break within the region delineated by the `@titlepage' and `@end
239 titlepage' commands and thereby create more than one unnumbered page.
240 This is how the copyright page is produced. (The `@titlepage' command
241 might perhaps have been better named the `@titleandadditionalpages'
242 command, but that would have been rather long!)
244 When you write a manual about a computer program, you should write the
245 version of the program to which the manual applies on the title page.
246 If the manual changes more frequently than the program or is
247 independent of it, you should also include an edition number(1) (*note
248 titlepage-Footnotes::) for the manual. This helps readers keep track
249 of which manual is for which version of the program. (The `Top' node
250 should also contain this information; see *Note `@top': makeinfo top.)
252 Texinfo provides two main methods for creating a title page. One
253 method uses the `@titlefont', `@sp', and `@center' commands to generate
254 a title page in which the words on the page are centered.
256 The second method uses the `@title', `@subtitle', and `@author'
257 commands to create a title page with black rules under the title and
258 author lines and the subtitle text set flush to the right hand side of
259 the page. With this method, you do not specify any of the actual
260 formatting of the title page. You specify the text you want, and
261 Texinfo does the formatting. You may use either method.
263 For extremely simple applications, Texinfo also provides a command
264 `@shorttitlepage' which takes a single argument as the title. The
265 argument is typeset on a page by itself and followed by a blank page.
268 File: texinfo.info, Node: titlepage-Footnotes, Up: titlepage
270 (1) We have found that it is helpful to refer to versions of manuals
271 as `editions' and versions of programs as `versions'; otherwise, we
272 find we are liable to confuse each other in conversation by referring
273 to both the documentation and the software with the same words.
276 File: texinfo.info, Node: titlefont center sp, Next: title subtitle author, Prev: titlepage, Up: Titlepage & Copyright Page
278 `@titlefont', `@center', and `@sp'
279 ----------------------------------
281 You can use the `@titlefont', `@sp', and `@center' commands to create
282 a title page for a printed document. (This is the first of the two
283 methods for creating a title page in Texinfo.)
285 Use the `@titlefont' command to select a large font suitable for the
292 Use the `@center' command at the beginning of a line to center the
293 remaining text on that line. Thus,
295 @center @titlefont{Texinfo}
297 centers the title, which in this example is "Texinfo" printed in the
300 Use the `@sp' command to insert vertical space. For example:
304 This inserts two blank lines on the printed page. (*Note `@sp': sp,
305 for more information about the `@sp' command.)
307 A template for this method looks like this:
311 @center @titlefont{NAME-OF-MANUAL-WHEN-PRINTED}
313 @center SUBTITLE-IF-ANY
319 The spacing of the example fits an 8 1/2 by 11 inch manual.
322 File: texinfo.info, Node: title subtitle author, Next: Copyright & Permissions, Prev: titlefont center sp, Up: Titlepage & Copyright Page
324 `@title', `@subtitle', and `@author'
325 ------------------------------------
327 You can use the `@title', `@subtitle', and `@author' commands to
328 create a title page in which the vertical and horizontal spacing is
329 done for you automatically. This contrasts with the method described in
330 the previous section, in which the `@sp' command is needed to adjust
333 Write the `@title', `@subtitle', or `@author' commands at the
334 beginning of a line followed by the title, subtitle, or author.
336 The `@title' command produces a line in which the title is set flush
337 to the left-hand side of the page in a larger than normal font. The
338 title is underlined with a black rule.
340 The `@subtitle' command sets subtitles in a normal-sized font flush
341 to the right-hand side of the page.
343 The `@author' command sets the names of the author or authors in a
344 middle-sized font flush to the left-hand side of the page on a line
345 near the bottom of the title page. The names are underlined with a
346 black rule that is thinner than the rule that underlines the title.
347 (The black rule only occurs if the `@author' command line is followed
348 by an `@page' command line.)
350 There are two ways to use the `@author' command: you can write the
351 name or names on the remaining part of the line that starts with an
354 @author by Jane Smith and John Doe
356 or you can write the names one above each other by using two (or more)
362 (Only the bottom name is underlined with a black rule.)
364 A template for this method looks like this:
367 @title NAME-OF-MANUAL-WHEN-PRINTED
368 @subtitle SUBTITLE-IF-ANY
369 @subtitle SECOND-SUBTITLE
375 Contrast this form with the form of a title page written using the
376 `@sp', `@center', and `@titlefont' commands:
380 @center @titlefont{Name of Manual When Printed}
382 @center Subtitle, If Any
384 @center Second subtitle
392 File: texinfo.info, Node: Copyright & Permissions, Next: end titlepage, Prev: title subtitle author, Up: Titlepage & Copyright Page
394 Copyright Page and Permissions
395 ------------------------------
397 By international treaty, the copyright notice for a book should be
398 either on the title page or on the back of the title page. The
399 copyright notice should include the year followed by the name of the
400 organization or person who owns the copyright.
402 When the copyright notice is on the back of the title page, that page
403 is customarily not numbered. Therefore, in Texinfo, the information on
404 the copyright page should be within `@titlepage' and `@end titlepage'
407 Use the `@page' command to cause a page break. To push the copyright
408 notice and the other text on the copyright page towards the bottom of
409 the page, you can write a somewhat mysterious line after the `@page'
410 command that reads like this:
412 @vskip 0pt plus 1filll
414 This is a TeX command that is not supported by the Info formatting
415 commands. The `@vskip' command inserts whitespace. The `0pt plus
416 1filll' means to put in zero points of mandatory whitespace, and as
417 much optional whitespace as needed to push the following text to the
418 bottom of the page. Note the use of three `l's in the word `filll';
419 this is the correct usage in TeX.
421 In a printed manual, the `@copyright{}' command generates a `c'
422 inside a circle. (In Info, it generates `(C)'.) The copyright notice
423 itself has the following legally defined sequence:
425 Copyright (C) YEAR COPYRIGHT-OWNER
427 It is customary to put information on how to get a manual after the
428 copyright notice, followed by the copying permissions for the manual.
430 Note that permissions must be given here as well as in the summary
431 segment within `@ifinfo' and `@end ifinfo' that immediately follows the
432 header since this text appears only in the printed manual and the
433 `ifinfo' text appears only in the Info file.
435 *Note Sample Permissions::, for the standard text.
438 File: texinfo.info, Node: end titlepage, Next: headings on off, Prev: Copyright & Permissions, Up: Titlepage & Copyright Page
443 An `@end titlepage' command on a line by itself not only marks the
444 end of the title and copyright pages, but also causes TeX to start
445 generating page headings and page numbers.
447 To repeat what is said elsewhere, Texinfo has two standard page
448 heading formats, one for documents which are printed on one side of
449 each sheet of paper (single-sided printing), and the other for
450 documents which are printed on both sides of each sheet (double-sided
451 printing). (*Note `@setchapternewpage': setchapternewpage.) You can
452 specify these formats in different ways:
454 * The conventional way is to write an `@setchapternewpage' command
455 before the title page commands, and then have the `@end titlepage'
456 command start generating page headings in the manner desired.
457 (*Note `@setchapternewpage': setchapternewpage.)
459 * Alternatively, you can use the `@headings' command to prevent page
460 headings from being generated or to start them for either single or
461 double-sided printing. (Write an `@headings' command immediately
462 after the `@end titlepage' command. *Note The `@headings'
463 Command: headings on off, for more information.)
465 * Or, you may specify your own page heading and footing format.
466 *Note Page Headings: Headings, for detailed information about page
467 headings and footings.
469 Most documents are formatted with the standard single-sided or
470 double-sided format, using `@setchapternewpage odd' for double-sided
471 printing and no `@setchapternewpage' command for single-sided printing.
474 File: texinfo.info, Node: headings on off, Prev: end titlepage, Up: Titlepage & Copyright Page
476 The `@headings' Command
477 -----------------------
479 The `@headings' command is rarely used. It specifies what kind of
480 page headings and footings to print on each page. Usually, this is
481 controlled by the `@setchapternewpage' command. You need the
482 `@headings' command only if the `@setchapternewpage' command does not
483 do what you want, or if you want to turn off pre-defined page headings
484 prior to defining your own. Write an `@headings' command immediately
485 after the `@end titlepage' command.
487 You can use `@headings' as follows:
490 Turn off printing of page headings.
493 Turn on page headings appropriate for single-sided printing.
496 Turn on page headings appropriate for double-sided printing. The
497 two commands, `@headings on' and `@headings double', are
500 `@headings singleafter'
501 `@headings doubleafter'
502 Turn on `single' or `double' headings, respectively, after the
503 current page is output.
506 Turn on page headings: `single' if `@setchapternewpage on',
509 For example, suppose you write `@setchapternewpage off' before the
510 `@titlepage' command to tell TeX to start a new chapter on the same
511 page as the end of the last chapter. This command also causes TeX to
512 typeset page headers for single-sided printing. To cause TeX to
513 typeset for double sided printing, write `@headings double' after the
514 `@end titlepage' command.
516 You can stop TeX from generating any page headings at all by writing
517 `@headings off' on a line of its own immediately after the line
518 containing the `@end titlepage' command, like this:
523 The `@headings off' command overrides the `@end titlepage' command,
524 which would otherwise cause TeX to print page headings.
526 You can also specify your own style of page heading and footing.
527 *Note Page Headings: Headings, for more information.
530 File: texinfo.info, Node: The Top Node, Next: Software Copying Permissions, Prev: Titlepage & Copyright Page, Up: Beginning a File
532 The `Top' Node and Master Menu
533 ==============================
535 The `Top' node is the node from which you enter an Info file.
537 A `Top' node should contain a brief description of the Info file and
538 an extensive, master menu for the whole Info file. This helps the
539 reader understand what the Info file is about. Also, you should write
540 the version number of the program to which the Info file applies; or,
541 at least, the edition number.
543 The contents of the `Top' node should appear only in the Info file;
544 none of it should appear in printed output, so enclose it between
545 `@ifinfo' and `@end ifinfo' commands. (TeX does not print either an
546 `@node' line or a menu; they appear only in Info; strictly speaking,
547 you are not required to enclose these parts between `@ifinfo' and `@end
548 ifinfo', but it is simplest to do so. *Note Conditionally Visible
553 * Title of Top Node:: Sketch what the file is about.
554 * Master Menu Parts:: A master menu has three or more parts.
557 File: texinfo.info, Node: Title of Top Node, Next: Master Menu Parts, Prev: The Top Node, Up: The Top Node
562 Sometimes, you will want to place an `@top' sectioning command line
563 containing the title of the document immediately after the `@node Top'
564 line (*note The `@top' Sectioning Command: makeinfo top command., for
567 For example, the beginning of the Top node of this manual contains an
568 `@top' sectioning command, a short description, and edition and version
569 information. It looks like this:
575 @node Top, Copying, , (dir)
578 Texinfo is a documentation system...
585 * Copying:: Texinfo is freely
587 * Overview:: What is Texinfo?
591 In a `Top' node, the `Previous', and `Up' nodes usually refer to the
592 top level directory of the whole Info system, which is called `(dir)'.
593 The `Next' node refers to the first node that follows the main or master
594 menu, which is usually the copying permissions, introduction, or first
598 File: texinfo.info, Node: Master Menu Parts, Prev: Title of Top Node, Up: The Top Node
600 Parts of a Master Menu
601 ----------------------
603 A "master menu" is a detailed main menu listing all the nodes in a
606 A master menu is enclosed in `@menu' and `@end menu' commands and
607 does not appear in the printed document.
609 Generally, a master menu is divided into parts.
611 * The first part contains the major nodes in the Texinfo file: the
612 nodes for the chapters, chapter-like sections, and the appendices.
614 * The second part contains nodes for the indices.
616 * The third and subsequent parts contain a listing of the other,
617 lower level nodes, often ordered by chapter. This way, rather
618 than go through an intermediary menu, an inquirer can go directly
619 to a particular node when searching for specific information.
620 These menu items are not required; add them if you think they are a
621 convenience. If you do use them, put `@detailmenu' before the
622 first one, and `@end detailmenu' after the last; otherwise,
623 `makeinfo' will get confused.
625 Each section in the menu can be introduced by a descriptive line. So
626 long as the line does not begin with an asterisk, it will not be
627 treated as a menu entry. (*Note Writing a Menu::, for more
630 For example, the master menu for this manual looks like the following
631 (but has many more entries):
634 * Copying:: Texinfo is freely
636 * Overview:: What is Texinfo?
637 * Texinfo Mode:: Special features in GNU Emacs.
640 * Command and Variable Index::
641 An entry for each @-command.
642 * Concept Index:: An entry for each concept.
645 --- The Detailed Node Listing ---
649 * Info Files:: What is an Info file?
650 * Printed Manuals:: Characteristics of
657 * Info on a Region:: Formatting part of a file
665 File: texinfo.info, Node: Software Copying Permissions, Prev: The Top Node, Up: Beginning a File
667 Software Copying Permissions
668 ============================
670 If the Texinfo file has a section containing the "General Public
671 License" and the distribution information and a warranty disclaimer for
672 the software that is documented, this section usually follows the `Top'
673 node. The General Public License is very important to Project GNU
674 software. It ensures that you and others will continue to have a right
675 to use and share the software.
677 The copying and distribution information and the disclaimer are
678 followed by an introduction or else by the first chapter of the manual.
680 Although an introduction is not a required part of a Texinfo file, it
681 is very helpful. Ideally, it should state clearly and concisely what
682 the file is about and who would be interested in reading it. In
683 general, an introduction would follow the licensing and distribution
684 information, although sometimes people put it earlier in the document.
685 Usually, an introduction is put in an `@unnumbered' section. (*Note
686 The `@unnumbered' and `@appendix' Commands: unnumbered & appendix.)
689 File: texinfo.info, Node: Ending a File, Next: Structuring, Prev: Beginning a File, Up: Top
691 Ending a Texinfo File
692 *********************
694 The end of a Texinfo file should include the commands that create
695 indices and generate detailed and summary tables of contents. And it
696 must include the `@bye' command that marks the last line processed by
701 @node Concept Index, , Variables Index, Top
702 @c node-name, next, previous, up
703 @unnumbered Concept Index
712 * Printing Indices & Menus:: How to print an index in hardcopy and
713 generate index menus in Info.
714 * Contents:: How to create a table of contents.
715 * File End:: How to mark the end of a file.
718 File: texinfo.info, Node: Printing Indices & Menus, Next: Contents, Prev: Ending a File, Up: Ending a File
720 Index Menus and Printing an Index
721 =================================
723 To print an index means to include it as part of a manual or Info
724 file. This does not happen automatically just because you use
725 `@cindex' or other index-entry generating commands in the Texinfo file;
726 those just cause the raw data for the index to be accumulated. To
727 generate an index, you must include the `@printindex' command at the
728 place in the document where you want the index to appear. Also, as
729 part of the process of creating a printed manual, you must run a
730 program called `texindex' (*note Format/Print Hardcopy::.) to sort the
731 raw data to produce a sorted index file. The sorted index file is what
732 is actually used to print the index.
734 Texinfo offers six different types of predefined index: the concept
735 index, the function index, the variables index, the keystroke index, the
736 program index, and the data type index (*note Predefined Indices::.).
737 Each index type has a two-letter name: `cp', `fn', `vr', `ky', `pg',
738 and `tp'. You may merge indices, or put them into separate sections
739 (*note Combining Indices::.); or you may define your own indices (*note
740 Defining New Indices: New Indices.).
742 The `@printindex' command takes a two-letter index name, reads the
743 corresponding sorted index file and formats it appropriately into an
746 The `@printindex' command does not generate a chapter heading for the
747 index. Consequently, you should precede the `@printindex' command with
748 a suitable section or chapter command (usually `@unnumbered') to supply
749 the chapter heading and put the index into the table of contents.
750 Precede the `@unnumbered' command with an `@node' line.
754 @node Variable Index, Concept Index, Function Index, Top
755 @comment node-name, next, previous, up
756 @unnumbered Variable Index
760 @node Concept Index, , Variable Index, Top
761 @comment node-name, next, previous, up
762 @unnumbered Concept Index
770 (Readers often prefer that the concept index come last in a book, since
771 that makes it easiest to find.)
774 File: texinfo.info, Node: Contents, Next: File End, Prev: Printing Indices & Menus, Up: Ending a File
776 Generating a Table of Contents
777 ==============================
779 The `@chapter', `@section', and other structuring commands supply the
780 information to make up a table of contents, but they do not cause an
781 actual table to appear in the manual. To do this, you must use the
782 `@contents' and `@summarycontents' commands:
785 Generate a table of contents in a printed manual, including all
786 chapters, sections, subsections, etc., as well as appendices and
787 unnumbered chapters. (Headings generated by the `@heading' series
788 of commands do not appear in the table of contents.) The
789 `@contents' command should be written on a line by itself.
793 (`@summarycontents' is a synonym for `@shortcontents'; the two
794 commands are exactly the same.)
796 Generate a short or summary table of contents that lists only the
797 chapters (and appendices and unnumbered chapters). Omit sections,
798 subsections and subsubsections. Only a long manual needs a short
799 table of contents in addition to the full table of contents.
801 Write the `@shortcontents' command on a line by itself right
802 *before* the `@contents' command.
804 The table of contents commands automatically generate a chapter-like
805 heading at the top of the first table of contents page. Write the table
806 of contents commands at the very end of a Texinfo file, just before the
807 `@bye' command, following any index sections--anything in the Texinfo
808 file after the table of contents commands will be omitted from the
811 When you print a manual with a table of contents, the table of
812 contents are printed last and numbered with roman numerals. You need
813 to place those pages in their proper place, after the title page,
814 yourself. (This is the only collating you need to do for a printed
815 manual. The table of contents is printed last because it is generated
816 after the rest of the manual is typeset.)
818 Here is an example of where to write table of contents commands:
825 Since an Info file uses menus instead of tables of contents, the Info
826 formatting commands ignore the `@contents' and `@shortcontents'
830 File: texinfo.info, Node: File End, Prev: Contents, Up: Ending a File
835 An `@bye' command terminates TeX or Info formatting. None of the
836 formatting commands see any of the file following `@bye'. The `@bye'
837 command should be on a line by itself.
839 If you wish, you may follow the `@bye' line with notes. These notes
840 will not be formatted and will not appear in either Info or a printed
841 manual; it is as if text after `@bye' were within `@ignore' ... `@end
842 ignore'. Also, you may follow the `@bye' line with a local variables
843 list. *Note Using Local Variables and the Compile Command:
844 Compile-Command, for more information.
847 File: texinfo.info, Node: Structuring, Next: Nodes, Prev: Ending a File, Up: Top
852 The "chapter structuring" commands divide a document into a hierarchy
853 of chapters, sections, subsections, and subsubsections. These commands
854 generate large headings; they also provide information for the table of
855 contents of a printed manual (*note Generating a Table of Contents:
858 The chapter structuring commands do not create an Info node structure,
859 so normally you should put an `@node' command immediately before each
860 chapter structuring command (*note Nodes::.). The only time you are
861 likely to use the chapter structuring commands without using the node
862 structuring commands is if you are writing a document that contains no
863 cross references and will never be transformed into Info format.
865 It is unlikely that you will ever write a Texinfo file that is
866 intended only as an Info file and not as a printable document. If you
867 do, you might still use chapter structuring commands to create a
868 heading at the top of each node--but you don't need to.
872 * Tree Structuring:: A manual is like an upside down tree ...
873 * Structuring Command Types:: How to divide a manual into parts.
874 * makeinfo top:: The `@top' command, part of the `Top' node.
876 * unnumbered & appendix::
877 * majorheading & chapheading::
879 * unnumberedsec appendixsec heading::
881 * unnumberedsubsec appendixsubsec subheading::
882 * subsubsection:: Commands for the lowest level sections.
883 * Raise/lower sections:: How to change commands' hierarchical level.
886 File: texinfo.info, Node: Tree Structuring, Next: Structuring Command Types, Prev: Structuring, Up: Structuring
888 Tree Structure of Sections
889 ==========================
891 A Texinfo file is usually structured like a book with chapters,
892 sections, subsections, and the like. This structure can be visualized
893 as a tree (or rather as an upside-down tree) with the root at the top
894 and the levels corresponding to chapters, sections, subsection, and
897 Here is a diagram that shows a Texinfo file with three chapters, each
898 of which has two sections.
902 -------------------------------------
904 Chapter 1 Chapter 2 Chapter 3
906 -------- -------- --------
908 Section Section Section Section Section Section
909 1.1 1.2 2.1 2.2 3.1 3.2
911 In a Texinfo file that has this structure, the beginning of Chapter 2
914 @node Chapter 2, Chapter 3, Chapter 1, top
917 The chapter structuring commands are described in the sections that
918 follow; the `@node' and `@menu' commands are described in following
919 chapters. (*Note Nodes::, and see *Note Menus::.)
922 File: texinfo.info, Node: Structuring Command Types, Next: makeinfo top, Prev: Tree Structuring, Up: Structuring
924 Types of Structuring Commands
925 =============================
927 The chapter structuring commands fall into four groups or series, each
928 of which contains structuring commands corresponding to the
929 hierarchical levels of chapters, sections, subsections, and
932 The four groups are the `@chapter' series, the `@unnumbered' series,
933 the `@appendix' series, and the `@heading' series.
935 Each command produces titles that have a different appearance on the
936 printed page or Info file; only some of the commands produce titles
937 that are listed in the table of contents of a printed book or manual.
939 * The `@chapter' and `@appendix' series of commands produce numbered
940 or lettered entries both in the body of a printed work and in its
943 * The `@unnumbered' series of commands produce unnumbered entries
944 both in the body of a printed work and in its table of contents.
945 The `@top' command, which has a special use, is a member of this
946 series (*note `@top': makeinfo top.).
948 * The `@heading' series of commands produce unnumbered headings that
949 do not appear in a table of contents. The heading commands never
952 * The `@majorheading' command produces results similar to using the
953 `@chapheading' command but generates a larger vertical whitespace
956 * When an `@setchapternewpage' command says to do so, the
957 `@chapter', `@unnumbered', and `@appendix' commands start new
958 pages in the printed manual; the `@heading' commands do not.
960 Here are the four groups of chapter structuring commands:
963 Numbered Unnumbered Lettered and numbered Unnumbered
964 In contents In contents In contents Not in contents
967 @chapter @unnumbered @appendix @chapheading
968 @section @unnumberedsec @appendixsec @heading
969 @subsection @unnumberedsubsec @appendixsubsec @subheading
970 @subsubsection @unnumberedsubsubsec @appendixsubsubsec @subsubheading
973 File: texinfo.info, Node: makeinfo top, Next: chapter, Prev: Structuring Command Types, Up: Structuring
978 The `@top' command is a special sectioning command that you use only
979 after an `@node Top' line at the beginning of a Texinfo file. The
980 `@top' command tells the `makeinfo' formatter which node is the `Top'
981 node. It has the same typesetting effect as `@unnumbered' (*note
982 `@unnumbered': (`@appendix')unnumbered & appendix.). For detailed
983 information, see *Note The `@top' Command: makeinfo top command.
986 File: texinfo.info, Node: chapter, Next: unnumbered & appendix, Prev: makeinfo top, Up: Structuring
991 `@chapter' identifies a chapter in the document. Write the command
992 at the beginning of a line and follow it on the same line by the title
995 For example, this chapter in this manual is entitled "Chapter
996 Structuring"; the `@chapter' line looks like this:
998 @chapter Chapter Structuring
1000 In TeX, the `@chapter' command creates a chapter in the document,
1001 specifying the chapter title. The chapter is numbered automatically.
1003 In Info, the `@chapter' command causes the title to appear on a line
1004 by itself, with a line of asterisks inserted underneath. Thus, in
1005 Info, the above example produces the following output:
1010 Texinfo also provides a command `@centerchap', which is analogous to
1011 `@unnumbered', but centers its argument in the printed output. This
1012 kind of stylistic choice is not usually offered by Texinfo.
1015 File: texinfo.info, Node: unnumbered & appendix, Next: majorheading & chapheading, Prev: chapter, Up: Structuring
1017 `@unnumbered', `@appendix'
1018 ==========================
1020 Use the `@unnumbered' command to create a chapter that appears in a
1021 printed manual without chapter numbers of any kind. Use the
1022 `@appendix' command to create an appendix in a printed manual that is
1023 labelled by letter instead of by number.
1025 For Info file output, the `@unnumbered' and `@appendix' commands are
1026 equivalent to `@chapter': the title is printed on a line by itself with
1027 a line of asterisks underneath. (*Note `@chapter': chapter.)
1029 To create an appendix or an unnumbered chapter, write an `@appendix'
1030 or `@unnumbered' command at the beginning of a line and follow it on
1031 the same line by the title, as you would if you were creating a chapter.
1034 File: texinfo.info, Node: majorheading & chapheading, Next: section, Prev: unnumbered & appendix, Up: Structuring
1036 `@majorheading', `@chapheading'
1037 ===============================
1039 The `@majorheading' and `@chapheading' commands put chapter-like
1040 headings in the body of a document.
1042 However, neither command causes TeX to produce a numbered heading or
1043 an entry in the table of contents; and neither command causes TeX to
1044 start a new page in a printed manual.
1046 In TeX, an `@majorheading' command generates a larger vertical
1047 whitespace before the heading than an `@chapheading' command but is
1050 In Info, the `@majorheading' and `@chapheading' commands are
1051 equivalent to `@chapter': the title is printed on a line by itself with
1052 a line of asterisks underneath. (*Note `@chapter': chapter.)
1055 File: texinfo.info, Node: section, Next: unnumberedsec appendixsec heading, Prev: majorheading & chapheading, Up: Structuring
1060 In a printed manual, an `@section' command identifies a numbered
1061 section within a chapter. The section title appears in the table of
1062 contents. In Info, an `@section' command provides a title for a
1063 segment of text, underlined with `='.
1065 This section is headed with an `@section' command and looks like this
1066 in the Texinfo file:
1068 @section @code{@@section}
1070 To create a section, write the `@section' command at the beginning of
1071 a line and follow it on the same line by the section title.
1075 @section This is a section
1085 File: texinfo.info, Node: unnumberedsec appendixsec heading, Next: subsection, Prev: section, Up: Structuring
1087 `@unnumberedsec', `@appendixsec', `@heading'
1088 ============================================
1090 The `@unnumberedsec', `@appendixsec', and `@heading' commands are,
1091 respectively, the unnumbered, appendix-like, and heading-like
1092 equivalents of the `@section' command. (*Note `@section': section.)
1095 The `@unnumberedsec' command may be used within an unnumbered
1096 chapter or within a regular chapter or appendix to provide an
1101 `@appendixsection' is a longer spelling of the `@appendixsec'
1102 command; the two are synonymous.
1104 Conventionally, the `@appendixsec' or `@appendixsection' command
1105 is used only within appendices.
1108 You may use the `@heading' command anywhere you wish for a
1109 section-style heading that will not appear in the table of
1113 File: texinfo.info, Node: subsection, Next: unnumberedsubsec appendixsubsec subheading, Prev: unnumberedsec appendixsec heading, Up: Structuring
1115 The `@subsection' Command
1116 =========================
1118 Subsections are to sections as sections are to chapters. (*Note
1119 `@section': section.) In Info, subsection titles are underlined with
1122 @subsection This is a subsection
1126 This is a subsection
1127 --------------------
1129 In a printed manual, subsections are listed in the table of contents
1130 and are numbered three levels deep.
1133 File: texinfo.info, Node: unnumberedsubsec appendixsubsec subheading, Next: subsubsection, Prev: subsection, Up: Structuring
1135 The `@subsection'-like Commands
1136 ===============================
1138 The `@unnumberedsubsec', `@appendixsubsec', and `@subheading'
1139 commands are, respectively, the unnumbered, appendix-like, and
1140 heading-like equivalents of the `@subsection' command. (*Note
1141 `@subsection': subsection.)
1143 In Info, the `@subsection'-like commands generate a title underlined
1144 with hyphens. In a printed manual, an `@subheading' command produces a
1145 heading like that of a subsection except that it is not numbered and
1146 does not appear in the table of contents. Similarly, an
1147 `@unnumberedsubsec' command produces an unnumbered heading like that of
1148 a subsection and an `@appendixsubsec' command produces a
1149 subsection-like heading labelled with a letter and numbers; both of
1150 these commands produce headings that appear in the table of contents.
1153 File: texinfo.info, Node: subsubsection, Next: Raise/lower sections, Prev: unnumberedsubsec appendixsubsec subheading, Up: Structuring
1155 The `subsub' Commands
1156 =====================
1158 The fourth and lowest level sectioning commands in Texinfo are the
1159 `subsub' commands. They are:
1162 Subsubsections are to subsections as subsections are to sections.
1163 (*Note `@subsection': subsection.) In a printed manual,
1164 subsubsection titles appear in the table of contents and are
1165 numbered four levels deep.
1167 `@unnumberedsubsubsec'
1168 Unnumbered subsubsection titles appear in the table of contents of
1169 a printed manual, but lack numbers. Otherwise, unnumbered
1170 subsubsections are the same as subsubsections. In Info, unnumbered
1171 subsubsections look exactly like ordinary subsubsections.
1173 `@appendixsubsubsec'
1174 Conventionally, appendix commands are used only for appendices and
1175 are lettered and numbered appropriately in a printed manual. They
1176 also appear in the table of contents. In Info, appendix
1177 subsubsections look exactly like ordinary subsubsections.
1180 The `@subsubheading' command may be used anywhere that you need a
1181 small heading that will not appear in the table of contents. In
1182 Info, subsubheadings look exactly like ordinary subsubsection
1185 In Info, `subsub' titles are underlined with periods. For example,
1187 @subsubsection This is a subsubsection
1191 This is a subsubsection
1192 .......................
1195 File: texinfo.info, Node: Raise/lower sections, Prev: subsubsection, Up: Structuring
1197 `@raisesections' and `@lowersections'
1198 =====================================
1200 The `@raisesections' and `@lowersections' commands raise and lower
1201 the hierarchical level of chapters, sections, subsections and the like.
1202 The `@raisesections' command changes sections to chapters, subsections
1203 to sections, and so on. The `@lowersections' command changes chapters
1204 to sections, sections to subsections, and so on.
1206 An `@lowersections' command is useful if you wish to include text
1207 that is written as an outer or standalone Texinfo file in another
1208 Texinfo file as an inner, included file. If you write the command at
1209 the beginning of the file, all your `@chapter' commands are formatted
1210 as if they were `@section' commands, all your `@section' command are
1211 formatted as if they were `@subsection' commands, and so on.
1213 `@raisesections' raises a command one level in the chapter
1214 structuring hierarchy:
1218 @subsection @section,
1220 @heading @chapheading,
1223 `@lowersections' lowers a command one level in the chapter
1224 structuring hierarchy:
1229 @subsection @subsubsection,
1230 @heading @subheading,
1233 An `@raisesections' or `@lowersections' command changes only those
1234 structuring commands that follow the command in the Texinfo file.
1235 Write an `@raisesections' or `@lowersections' command on a line of its
1238 An `@lowersections' command cancels an `@raisesections' command, and
1239 vice versa. Typically, the commands are used like this:
1242 @include somefile.texi
1245 Without the `@raisesections', all the subsequent sections in your
1246 document will be lowered.
1248 Repeated use of the commands continue to raise or lower the
1249 hierarchical level a step at a time.
1251 An attempt to raise above `chapters' reproduces chapter commands; an
1252 attempt to lower below `subsubsections' reproduces subsubsection
1256 File: texinfo.info, Node: Nodes, Next: Menus, Prev: Structuring, Up: Top
1261 "Nodes" are the primary segments of a Texinfo file. They do not
1262 themselves impose a hierarchic or any other kind of structure on a file.
1263 Nodes contain "node pointers" that name other nodes, and can contain
1264 "menus" which are lists of nodes. In Info, the movement commands can
1265 carry you to a pointed-to node or to a node listed in a menu. Node
1266 pointers and menus provide structure for Info files just as chapters,
1267 sections, subsections, and the like, provide structure for printed
1272 * Two Paths:: Different commands to structure
1273 Info output and printed output.
1274 * Node Menu Illustration:: A diagram, and sample nodes and menus.
1275 * node:: How to write a node, in detail.
1276 * makeinfo Pointer Creation:: How to create node pointers with `makeinfo'.
1279 File: texinfo.info, Node: Two Paths, Next: Node Menu Illustration, Prev: Nodes, Up: Nodes
1284 The node and menu commands and the chapter structuring commands are
1285 independent of each other:
1287 * In Info, node and menu commands provide structure. The chapter
1288 structuring commands generate headings with different kinds of
1289 underlining--asterisks for chapters, hyphens for sections, and so
1290 on; they do nothing else.
1292 * In TeX, the chapter structuring commands generate chapter and
1293 section numbers and tables of contents. The node and menu
1294 commands provide information for cross references; they do nothing
1297 You can use node pointers and menus to structure an Info file any way
1298 you want; and you can write a Texinfo file so that its Info output has a
1299 different structure than its printed output. However, most Texinfo
1300 files are written such that the structure for the Info output
1301 corresponds to the structure for the printed output. It is not
1302 convenient to do otherwise.
1304 Generally, printed output is structured in a tree-like hierarchy in
1305 which the chapters are the major limbs from which the sections branch
1306 out. Similarly, node pointers and menus are organized to create a
1307 matching structure in the Info output.