home *** CD-ROM | disk | FTP | other *** search
/ OpenStep 4.2 / Openstep-4.2-Intel-User.iso / usr / lib / emacs / info / texinfo-1 < prev    next >
Text File  |  1991-01-10  |  49KB  |  1,284 lines

  1. Info file ../info/texinfo, produced by Makeinfo, -*- Text -*- from
  2. input file texinfo.texinfo.
  3.  
  4. This file documents Texinfo, a documentation system that uses a
  5. single source file to produce both on-line help and a printed manual.
  6.  
  7. This is edition 1.1 of the Texinfo documentation, and is for the
  8. Texinfo that is distributed as part of Version 18 of GNU Emacs.
  9.  
  10. Copyright (C) 1988 Free Software Foundation, Inc.
  11.  
  12. Permission is granted to make and distribute verbatim copies of this
  13. manual provided the copyright notice and this permission notice are
  14. preserved on all copies.
  15.  
  16. Permission is granted to copy and distribute modified versions of
  17. this manual under the conditions for verbatim copying, provided that
  18. the entire resulting derived work is distributed under the terms of a
  19. permission notice identical to this one.
  20.  
  21. Permission is granted to copy and distribute translations of this
  22. manual into another language, under the above conditions for modified
  23. versions, except that this permission notice may be stated in a
  24. translation approved by the Foundation.
  25.  
  26.  
  27. 
  28. File: texinfo,  Node: Top,  Next: License,  Prev: (dir),  Up: (dir)
  29.  
  30. * Menu:
  31.  
  32. * License::            Licensing information.
  33. * Overview::            What is Texinfo?
  34. * Texinfo Mode::        Special features in GNU Emacs.
  35. * Beginning a File::         What to put at the beginning of a Texinfo file.
  36. * Ending a File::         What to put at the end of a Texinfo file.
  37. * Structuring::             How to make nodes and chapters.
  38. * Quotations and Examples::    How to insert quotations and examples.
  39. * Lists and Tables::         How to make lists and tables.
  40. * Cross References::         How to make cross references.
  41. * Formatting Paragraphs::    How to format paragraphs.
  42. * Marking Text::         How to mark code, definitions, variables etc.
  43. * Conditionals::         Putting text in only Info or the printed work.
  44. * Printing Hardcopy::         How to print a hardcopy of the manual.
  45. * Creating an Info File::    How to create an on-line Info file.
  46. * Catching Mistakes::        How to find problems.
  47.  
  48. Indices, nodes containing large menus
  49.  
  50. * Command Index::         An item for each @-command.
  51. * Concept Index::          An item for each concept.
  52.  
  53. A detailed node listing
  54.  
  55. Overview
  56. * Info File::            Characteristics of the Info file.
  57. * Printed Manual::        Characteristics of the printed manual.
  58. * Conventions::            General syntactic conventions.
  59. * Short Sample::            A short sample Texinfo file.
  60.  
  61. Using Texinfo Mode
  62. * Info on a Region::        Formatting a region for Info.
  63. * Showing the Structure::    Showing the structure of a file.
  64. * Inserting::            Inserting frequently used commands.
  65.  
  66. Beginning a Texinfo File.
  67. * First Line::            The first line of a Texinfo file.
  68. * Start-of-Header::        Identifying the start of the header.
  69. * Setfilename::            Specifying the name of the Info file.
  70. * Settitle::            Specifying the title used by the headings.
  71. * Setchapternewpage::        Starting chapters on odd numbered pages.
  72. * Titlepage::            The title and copyright page.
  73. * Center::            Centering a line.
  74. * Copyright & Printed Permissions:: Ensuring free distributability.
  75. * Top Node::            The master menu.  
  76. * License and Distribution::    Your are free to copy and distribute this.
  77.  
  78. Ending a Texinfo File
  79. * Contents::            Generating tables of contents.
  80. * Indices::            Generating indices.
  81. * Index Entries::        Defining the entries of an index.
  82. * Combining Indices::        Putting two or more indices together.
  83. * Printing Indices & Menus::    Printing an index and generating menus.
  84.  
  85. Node and Chapter Structuring
  86. * Chapter::            Creating a chapter.
  87. * Unnumbered and Appendix::    Chapter-like parts.
  88. * Section::            Creating sections
  89. * Subsection::            Creating subsections.
  90. * Subsubsection::        Creating subsubsections.
  91.  
  92. * Node::            Creating nodes.
  93. * Menu::            Creating menus.
  94.  
  95.  
  96. Making quotations and examples
  97. * Quotation::            Inserting long quotations.
  98. * Example::            Inserting examples of code and the like.
  99. * Display::            Inserting displayed text.
  100.  
  101. Making lists and two column tables
  102. * Itemize::            Creating itemized lists.
  103. * Enumerate::            Creating enumerated lists.
  104. * Table::            Creating two column tables.
  105. * Itemx::            Putting an extra item in the 
  106.                 first column of a table.
  107.  
  108. Making Cross References
  109. * Xref::            Making a regular cross reference.
  110. * Pxref::            Making a parenthetical cross reference.
  111. * Inforef::            Making a cross reference to an Info file.
  112.  
  113.  
  114. Formatting Paragraphs
  115. * Refilling & Noindent::    Refilling paragraphs 
  116.                 and preventing indentation
  117. * Refill::            Using the `@refill' command.
  118. * Noindent::            Using the `@noindent' command.
  119.  
  120.  
  121. Breaks, Blank Lines and Groups
  122. * Line Breaks::            Inserting line breaks in TeX.
  123. * Sp::                Inserting blank lines.
  124. * Br::                Inserting paragraph breaks.
  125. * W::                Preventing line breaks.
  126. * Page::            Starting new pages.
  127. * Group::            Holding text together on one page.
  128. * Need::            Keeping text together.
  129.  
  130. Marking Text Within a Paragraph
  131. * Code::            A literal example of a piece of a program.
  132. * Samp::            A literal example of a sequence of characters.
  133. * File::            The name of a file.
  134. * Kbd::                The names of keys or else characters you type.
  135. * Key::                The conventional name for a key on a keyboard.
  136. * Ctrl::            Indicates the ASCII control character.
  137. * Var::                A variable.
  138. * Dfn::                The introductory or defining use of a term.
  139. * Cite::            The name of a book.
  140.  
  141. Inserting Braces, `@' and Periods
  142. * Braces Atsigns Periods::    Inserting braces, `@' and periods.
  143. * Dots Bullets Tex::        Inserting dots, bullets and the TeX logo
  144. * Emphasis::            Emphasizing text.
  145.  
  146. Emphasizing Text
  147. * Emph and Strong::        Emphasizing text.
  148. * Fonts::            Selecting italic, bold or typewriter fonts.
  149.  
  150. Creating an Info File
  151. * Installing an Info File::    Putting the Info file in the 
  152.                 `info' directory.
  153.  
  154. Catching Mistakes
  155. * Debugging with Info::            Catching errors with info formatting.
  156. * Using the Emacs Lisp Debugger::   Using the Emacs Lisp Debugger
  157. * Debugging with Tex::            Catching errors with TeX formatting.
  158. * Using texinfo-show-structure::    Using `texinfo-show-structure'
  159.                     to catch mistakes.
  160. * Using Occur::                Using `occur' to catch mistakes.
  161. * Running Info-Validate::        Checking for unreferenced nodes.
  162.  
  163. Finding badly referenced nodes
  164. * Info-Validating a Large File::     Running `Info-validate' 
  165.                      on a large file.
  166. * Splitting::                        Splitting a file manually.
  167.  
  168. Appendices
  169. * Command Syntax::        Details about the syntax.
  170. * Include Files::        Making one printed file out of 
  171.                 several Info files.
  172. * TeX Input::            Where TeX finds its `\input' file.
  173. * Sample Permissions::        You may copy GNU Software.
  174. * Ifinfo Permissions::        What to put in the `ifinfo' section.
  175. * Titlepage Permissions::    What to put in the `@titlepage' section.
  176.  
  177.  
  178. 
  179. File: texinfo,  Node: License,  Next: Overview,  Prev: Top,  Up: Top
  180.  
  181. Licensing Information
  182. *********************
  183.  
  184.   The programs currently being distributed that relate to Texinfo
  185. include two portions of GNU Emacs, plus two other separate programs
  186. (`texindex' and `texinfo.tex').  These programs are "free"; this
  187. means that everyone is free to use them and free to redistribute them
  188. on a free basis.  The Texinfo related programs are not in the public
  189. domain; they are copyrighted and there are restrictions on their
  190. distribution, but these restrictions are designed to permit
  191. everything that a good cooperating citizen would want to do.  What is
  192. not allowed is to try to prevent others from further sharing any
  193. version of these programs that they might get from you.
  194.  
  195.   Specifically, we want to make sure that you have the right to give
  196. away copies of the programs that relate to Texinfo, that you receive
  197. source code or else can get it if you want it, that you can change
  198. these programs or use pieces of them in new free programs, and that
  199. you know you can do these things.
  200.  
  201.   To make sure that everyone has such rights, we have to forbid you to
  202. deprive anyone else of these rights.  For example, if you distribute
  203. copies of the Texinfo related programs, you must give the recipients
  204. all the rights that you have.  You must make sure that they, too,
  205. receive or can get the source code.  And you must tell them their
  206. rights.
  207.  
  208.   Also, for our own protection, we must make certain that everyone
  209. finds out that there is no warranty for the programs that relate to
  210. Texinfo.  If these programs are modified by someone else and passed
  211. on, we want their recipients to know that what they have is not what
  212. we distributed, so that any problems introduced by others will not
  213. reflect on our reputation.
  214.  
  215.   The precise conditions of the licenses for the programs currently
  216. being distributed that relate to Texinfo are found in the General
  217. Public Licenses that accompany them.  The programs that are part of
  218. GNU Emacs are covered by the GNU Emacs copying terms (*note :
  219. (emacs)License.), and other programs are covered by licenses that are
  220. contained in their source files.
  221.  
  222.  
  223. 
  224. File: texinfo,  Node: Overview,  Next: Texinfo Mode,  Prev: License,  Up: Top
  225.  
  226. Overview of Texinfo
  227. *******************
  228.  
  229. Texinfo is a documentation system that uses a single source file for
  230. both on-line help and a printed manual.  This means that instead of
  231. writing two different documents, one for the on-line help and the
  232. other for the printed manual, only one document needs to be written. 
  233. When the system is revised, only one file has to be revised.
  234.  
  235. Using Texinfo, you can create a document with the normal features of
  236. a book such as chapters, sections, cross references and indices.  The
  237. chapters and sections of the printed manual can be made to correspond
  238. to the nodes of the on-line help.  The cross references and indices
  239. can be used in both the on-line help and in the printed document. 
  240. Indices are generated semi-automatically.  The ``GNU Emacs Manual''
  241. is a good example of a Texinfo file.
  242.  
  243. To make the printed manual, the Texinfo source file is processed by
  244. the TeX typesetting program; the resulting DVI file can be typeset
  245. and printed as a book.  To make the on-line help, the Texinfo source
  246. file is by processed the `M-x texinfo-format-buffer' command; the
  247. resulting Info file is installed in the `info' directory.
  248.  
  249. Since the Texinfo source file is used for a dual task--to create both
  250. the on-line help and the printed manual--it must be written in a
  251. special format that uses @-commands (words preceded by an `@') to
  252. indicate chapters, sections, nodes, examples, index entries and the
  253. like.
  254.  
  255. Before writing a Texinfo source file, you should be familiar with the
  256. on-line Info documentation reading program.  (*note info: (info)Info,
  257. for more information.)  If you are writing a document that will be
  258. both on-line and printed, you will need both Info and TeX.
  259.  
  260. To make an Info file, you use the `M-x texinfo-format-buffer' command
  261. in GNU Emacs.
  262.  
  263. To make a printed manual, you need to use TeX, a powerful,
  264. sophisticated typesetting program written by Donald Knuth.  TeX is
  265. freely distributable. It is written in a dialect of Pascal called WEB
  266. and can be compiled either in Pascal or (by using a conversion
  267. program that comes with the TeX distribution) in C.  (For information
  268. about getting TeX, *note : (emacs)TeX Mode.)
  269.  
  270. When TeX processes a Texinfo source file, TeX makes use of a macro
  271. definitions file called `texinfo.tex' that comes with the GNU Emacs
  272. distribution in the `emacs/man' sources directory.  (The first line
  273. of every Texinfo file has a command that says `\input texinfo'; this
  274. tells TeX to use the `texinfo.tex' file.)
  275.  
  276. If the `texinfo.tex' file has not already been copied to the
  277. directory which contains the other TeX macro definition files when
  278. Emacs was installed, you will probably want to copy it to that
  279. directory.  Usually, this is the `/usr/lib/tex/macros' directory. 
  280. For more information, *note @TeX{} Input Initialization: TeX Input.
  281.  
  282. Documentation for GNU utilities and libraries should be written in
  283. Texinfo format.
  284.  
  285. * Menu:
  286.  
  287. * Info File::         Characteristics of the Info file.
  288. * Printed Manual::    Characteristics of the Printed Manual.
  289. * Conventions::       General Syntactic Conventions.
  290. * Short Sample::      A short sample Texinfo file.
  291.  
  292.  
  293. 
  294. File: texinfo,  Node: Info File,  Next: Printed Manual,  Up: Overview
  295.  
  296. Characteristics of the Info file
  297. ================================
  298.  
  299. A Texinfo file can be transformed into a printed manual and an
  300. on-line Info file.
  301.  
  302. An on-line Info file is a file formatted so that the Info
  303. documentation reading program can operate on it.  Info files are
  304. divided into pieces called "nodes", each of which contains the
  305. discussion of one topic.  Each node has a name, and contains both
  306. text for the user to read and pointers to other nodes, which are
  307. identified by their names.  The Info program displays one node at a
  308. time, and provides commands with which the user can move to the other
  309. nodes to which the current node points.
  310.  
  311. *note info: (info)Info, for more information about using Info.
  312.  
  313. Normally, most of the nodes are arranged in a tree which branches down.
  314. Each node may have any number of child nodes that describe subtopics
  315. of the node's topic.  The names of these child nodes, if any, are
  316. listed in a "menu" within the parent node; this allows certain Info
  317. commands to be used to move to one of the child nodes.  Each child
  318. node records the parent node name, as its `Up' pointer.  Thus, if a
  319. node were at the logical level of a `chapter', its child nodes would
  320. be `sections'; likewise, the child nodes of a section would be
  321. subsections.
  322.  
  323. The root of the tree is the top node of the file, through which users
  324. enter the file from the Info directory.  By convention, this node is
  325. always called `Top'.  This node normally contains just a brief
  326. summary of the file's purpose, and a large menu through which the
  327. rest of the file is reached.
  328.  
  329. Generally you enter the Info file from the top; then you can either
  330. traverse the file systematically by going from node to node or you
  331. can search large menus that correspond to indices and go directly to
  332. the node that has the information you want.
  333.  
  334. If you want to read through an Info file in sequence, as if it were a
  335. printed manual, you can get the whole file with the advanced Info
  336. command `g *'.  (*note info: (info)Expert.)
  337.  
  338. All the children of any one parent are linked together in a
  339. bidirectional chain of `Next' and `Previous' pointers.  This means
  340. that all the nodes that are logically parallel to sections within a
  341. chapter are all linked together.  Normally the order in this chain is
  342. the same as the order of the children in the parent's menu.  The last
  343. child has no `Next' pointer, and the first child normally has the
  344. parent as its `Previous' pointer (as well as its `Up' pointer, of
  345. course).
  346.  
  347. Structuring the nodes in a tree is a matter of convention, not a
  348. requirement.  In fact, the `Up', `Previous' and `Next' pointers of a
  349. node can point to any other nodes, and the menu can contain any other
  350. nodes.  The structure of nodes can be any directed graph.  But it is
  351. usually more comprehensible to make it a tree.  Info provides another
  352. kind of pointer between nodes, called a reference, that can be
  353. sprinkled through the text of a node.  This is usually the best way
  354. to represent links that do not fit the tree structure.
  355.  
  356. Most often the nodes fall into a strict tree structure that
  357. corresponds to the structure of chapters and sections in the printed
  358. manual.  But there are times when this is not right for the material
  359. being discussed.  Therefore, Texinfo uses separate commands to
  360. specify the node structure of the Info file and the section structure
  361. of the printed manual.  Also, Texinfo requires that you specify menus
  362. explicitly, rather than generate them automatically based on an
  363. assumed tree structure.
  364.  
  365.  
  366. 
  367. File: texinfo,  Node: Printed Manual,  Next: Conventions,  Prev: Info File,  Up: Top
  368.  
  369. Characteristics of the Printed Manual
  370. =====================================
  371.  
  372. A Texinfo file can be formatted and typeset as a printed manual.  The
  373. printed manual will be the same as any other book; it will have a
  374. title page, copyright page, table of contents, and preface as you
  375. would expect, as well as chapters, numbered or unnumbered sections
  376. and subsections, not to mention page headers, cross references and
  377. indices.
  378.  
  379. Texinfo can be used for writing a book without ever having the
  380. intention of converting it into on-line help.  Texinfo can be used
  381. for writing a novel; and it can even be used to write a memo,
  382. although this application is not recommended since electronic mail is
  383. so much easier.
  384.  
  385. Texinfo uses the formatting language called TeX for typesetting.  A
  386. file called `texinfo.tex' contains information (definitions or
  387. "macros") that TeX uses when it typesets a Texinfo file.  (The macros
  388. tell TeX how to convert the Texinfo @-commands to TeX commands which
  389. TeX can then process to create the typeset document.) `texinfo.tex'
  390. contains the specifications for printing a document, either with 7
  391. inch by 9.25 inch pages or with 8.5 inch by 11 inch pages.  (This is
  392. 178 mm by 235 mm or else 216 mm by 280 mm.) Also, by changing the
  393. parameters in `texinfo.tex' you can easily change the size of the
  394. printed document.  In addition, you can readily change the style in
  395. which the printed document is formatted; for example, you can change
  396. the sizes and fonts used, the amount of indentation for each
  397. paragraph, the degree to which words are hyphenated, and the like. 
  398. By changing the specifications, you can make a book look dignified,
  399. old and serious, or light-hearted, young and cheery.
  400.  
  401. TeX is very powerful and has a great many features.  Because a
  402. Texinfo file must be able to present information both on a
  403. character-only terminal in Info form and in a typeset book, the
  404. commands that Texinfo supports are necessarily limited.
  405.  
  406.  
  407. 
  408. File: texinfo,  Node: Conventions,  Next: Short Sample,  Prev: Printed Manual,  Up: Overview
  409.  
  410. General Syntactic Conventions
  411. =============================
  412.  
  413. Texinfo files contain a strictly limited set of constructs.  The
  414. strict limits make it possible for Texinfo files to be understood
  415. both by TeX and by the code which converts them into Info files.
  416.  
  417. All ASCII printing characters except `@', `{' and `}' can appear in
  418. body text in a Texinfo file and stand for themselves.  `@' is the
  419. escape character which introduces commands.  `{' and `}' should be
  420. used only to surround arguments to certain commands.  `{' and `}'
  421. appearing anywhere else will be treated by TeX as a grouping but
  422. treated by the code that produces an Info file as themselves; this
  423. inconsistency is undesirable, so don't let it occur.  To put one of
  424. these special characters into the document, put an `@' character in
  425. front of it.  For example, you would insert `@@', `@{', and `@}'.
  426.  
  427. It is customary in TeX to use doubled single-quote characters to
  428. begin and end quotations, `"' like these `"'.  This convention should
  429. be followed in Texinfo files.  Also, three hyphens in a row, `--',
  430. are used for a dash--like this.  In TeX, a single or even a double
  431. hyphen produces a dash that is shorter than you want.
  432.  
  433. TeX ignores the line-breaks in the input text, except for blank
  434. lines, which separate paragraphs.  Info generally preserves the line
  435. breaks that are present in the input file.  Therefore, break the
  436. lines in the Texinfo file the way you want them to appear in the
  437. output Info file, and let TeX take care of itself.
  438.  
  439. Since Info does not normally refill paragraphs when it processes
  440. them, a line with @-commands in it will sometimes look bad after Info
  441. has run on it.  To cause Info to refill the paragraph after finishing
  442. with the other processing, you need to put the command `@refill' at
  443. the end of the paragraph. (*Note Refilling paragraphs and Preventing
  444. indentation: Refilling & Noindent.)
  445.  
  446. To prevent a paragraph from being indented in the printed manual, put
  447. the command `@noindent' on a line by itself before the start of the
  448. text that should not be indented.
  449.  
  450. If you mark off a region of the Texinfo file with the `@iftex' and
  451. `@end iftex' commands so that the region will appear only in the
  452. printed copy, you can use TeX commands that cannot be used in the
  453. Info file.
  454.  
  455. In order to be made into a printed manual, a Texinfo file *must*
  456. begin with lines that looks like
  457.  
  458.      \input texinfo   @c -*-texinfo-*-
  459.      @setfilename INFO-FILE-NAME
  460.      @settitle NAME OF MANUAL
  461.  
  462. The `\input texinfo' line tells TeX to use the `texinfo.tex' file. 
  463. This line is usually followed by a start-of-header line (not shown
  464. here) and then by the `@setfilename INFO-FILE-NAME' and `@settitle
  465. NAME OF MANUAL' lines.  These two lines are needed to provide a name
  466. for the Info file and to specify the name used on the left-hand page
  467. headers of the printed manual.
  468.  
  469. The two lines that contain the `@setfilename' and `@settitle'
  470. commands usually are sandwiched between the start-of-header line and
  471. the end-of-header line. (*Note Start-of-Header::, for more
  472. information.)  The start-of-header and end-of-header lines are needed
  473. if you are going to run TeX or Info on just part of a file.
  474.  
  475.  
  476. 
  477. File: texinfo,  Node: Short Sample,  Prev: Conventions,  Up: Overview
  478.  
  479. A Short Sample Texinfo File
  480. ===========================
  481.  
  482. A Texinfo file looks like the following, which is a complete but very
  483. short Texinfo file.  The `@comment' command introduces comments that
  484. will not appear in either the Info file or the printed manual; they
  485. are for the person who reads the Texinfo file.
  486.  
  487. The first part of the file, from `\input texinfo' through to `@end
  488. titlepage', looks more intimidating than it is.  Most of the material
  489. is standard boilerplate; when you write a manual, you just put in the
  490. name of your own manual in this section.
  491.  
  492. All the commands that tell TeX how to typeset the printed manual and
  493. tell `texinfo-format-buffer' how to create an Info file are preceded
  494. by `@'; thus, `@node' indicates a node and `@chapter' indicates the
  495. start of a chapter.
  496.  
  497.      \input texinfo   @c -*-texinfo-*-
  498.      @setfilename name-of-texinfo-file
  499.      @settitle Name of Manual
  500.      @setchapternewpage odd
  501.      
  502.      @ifinfo
  503.      @comment The following line inserts the copyright notice 
  504.      @comment into the Info file.
  505.      Copyright @copyright{} 1988 Free Software Foundation, Inc.
  506.      @end ifinfo
  507.      
  508.      @comment The titlepage section does not appear in the Info file.
  509.      @titlepage
  510.      @sp 10
  511.      @comment The title is printed in a large font.
  512.      @center @titlefont{Sample Title}
  513.      
  514.      @comment  The following two commands start the copyright page
  515.      @comment  for the printed manual.  This will not appear in the Info file.
  516.      @page
  517.      @vskip 0pt plus 1filll
  518.      Copyright @copyright{} year copyright-owner
  519.      @end titlepage
  520.      
  521.      @comment The Top node contains the master menu for the Info file.
  522.      @comment This appears only in the Info file, not the printed manual.
  523.      
  524.      @node    Top,       First Chapter, (dir),    (dir)
  525.      @comment node-name, next,          previous, up
  526.      
  527.      @menu
  528.      * First Chapter::    The first chapter is the 
  529.                           only chapter in this sample.
  530.      @end menu
  531.      
  532.      @node     First Chapter,     , Top,      Top
  533.      @comment  node-name,     next, previous, up
  534.      @chapter First Chapter
  535.      @cindex Reference to First Chapter
  536.      
  537.      This is the contents of the first chapter. 
  538.      
  539.      Here is a numbered list.
  540.      
  541.      @enumerate
  542.      @item
  543.      This is the first item.
  544.      
  545.      @item
  546.      This is the second item.
  547.      @end enumerate
  548.      
  549.      The @kbd{M-x texinfo-format-buffer} command transforms a Texinfo file
  550.      like this into an Info file; and @TeX{} typesets it for a printed
  551.      manual.
  552.      
  553.      @node    Concept Index,    ,  Previous Node, Top
  554.      @comment node-name,    next,  previous,      up
  555.      @unnumbered Concept Index
  556.      
  557.      @printindex cp
  558.      
  559.      @contents
  560.      @bye
  561.  
  562. Here is what the contents of the first chapter of the sample look like:
  563.  
  564.       This is the contents of the first chapter.
  565.  
  566.      Here is a numbered list.
  567.  
  568.        1. This is the first item.
  569.  
  570.        2. This is the second item.
  571.  
  572.      The `M-x texinfo-format-buffer' command transforms a Texinfo
  573.      file like this into an Info file; and TeX typesets it for a
  574.      printed manual.
  575.  
  576.  
  577. 
  578. File: texinfo,  Node: Texinfo Mode,  Next: Beginning a File,  Prev: Overview,  Up: Top
  579.  
  580. Using Texinfo Mode
  581. ******************
  582.  
  583. In GNU Emacs, Texinfo mode is a major mode for editing Texinfo files.
  584. This means that Emacs has commands and features especially designed
  585. for working with Texinfo files.  Like all other Emacs features, you
  586. can customize or enhance these as you wish.  In particular, the
  587. keybindings are very easy to change.  The keybindings described here
  588. are the default or standard ones.
  589.  
  590. The major features of Texinfo mode are:
  591.  
  592.    * Paragraph filling control.
  593.  
  594.    * A command to show the structure of the file.
  595.  
  596.    * Pre-defined keystroke commands to insert commonly used strings
  597.      of text.
  598.  
  599.    * Formatting a part of a file for Info, rather than the whole file.
  600.  
  601. In general, in Texinfo mode, the GNU Emacs editing commands are like
  602. those in text-mode.  The major difference is that the paragraph
  603. separation variable and syntax table are set up so expression
  604. commands skip Texinfo bracket groups.  This means, for example, that
  605. the `M-q' (`fill-paragraph') command will refill a paragraph but not
  606. the @-command on a line adjacent to it.
  607.  
  608. By convention, the Texinfo file name shall end with the extension
  609. `.texinfo' so that Emacs knows to use Texinfo mode for editing it.
  610.  
  611. * Menu:
  612.  
  613. * Info on a Region::        Formatting part of a file for Info.
  614. * Showing the Structure::    Showing the structure of a file.
  615. * Inserting::            Inserting frequently used commands.
  616.  
  617.  
  618. 
  619. File: texinfo,  Node: Info on a Region,  Next: Showing the Structure,  Prev: Texinfo Mode,  Up: Texinfo Mode
  620.  
  621. Formatting a Region for Info
  622. ============================
  623.  
  624. To see what part of a Texinfo file will look like after it has been
  625. transformed into an Info file, use the command `C-c C-f'
  626. (`texinfo-format-region').  This command formats the current region
  627. of the Texinfo file for Info and writes it to a temporary buffer
  628. called `*Info Region*'.
  629.  
  630. For `texinfo-format-region' to work, the file *must* include a line
  631. that has `@setfilename' in its header.
  632.  
  633. The command is:
  634.  
  635. `C-c C-f'
  636.      texinfo-format-region
  637.  
  638.  
  639. 
  640. File: texinfo,  Node: Showing the Structure,  Next: Inserting,  Prev: Info on a Region,  Up: Texinfo Mode
  641.  
  642. Showing the Structure of a File
  643. ===============================
  644.  
  645. You can show the structure of a Texinfo file by using the `C-c C-s'
  646. command (`texinfo-show-structure').  This command shows the structure
  647. of a Texinfo file by listing the lines with the @-commands for
  648. `@node', `@chapter', `@section' and the like.  These lines are
  649. displayed in another window called the `*Occur*' window.  In that
  650. window, you can position the cursor over one of the lines and use the
  651. `C-c C-c' command (`occur-mode-goto-occurrence'), to jump to the
  652. corresponding spot in the Texinfo file.
  653.  
  654. The two commands are:
  655.  
  656. `C-c C-s'
  657.      texinfo-show-structure
  658.  
  659. `C-c C-c'
  660.      occur-mode-goto-occurrence
  661.  
  662. Often, when you are working on a manual, you will be interested only
  663. in the structure of the current chapter.  In this case, you can mark
  664. off the region of the buffer that you are interested in with the `C-x
  665. n' (`narrow-to-region') command and `texinfo-show-structure' will
  666. work on only that region.  (To see the whole buffer again, use `C-x
  667. w' (`widen').)
  668.  
  669.  
  670. 
  671. File: texinfo,  Node: Inserting,  Prev: Showing the Structure,  Up: Texinfo Mode
  672.  
  673. Inserting Frequently Used Commands
  674. ==================================
  675.  
  676. Texinfo mode provides commands that insert various frequently used
  677. @-commands into the buffer.  You can use these commands to save
  678. keystrokes.  And you can insert balanced curly braces with the `M-{'
  679. command, (`texinfo-insert-braces') and later use the `M-}' command
  680. (`up-list') to move forward past the closing brace.
  681.  
  682. The special commands are invoked by typing `C-c' twice and then the
  683. first letter of the @-command.
  684.  
  685. `C-c C-c c'
  686.      texinfo-insert-@code
  687.  
  688. `C-c C-c d'
  689.      texinfo-insert-@dfn
  690.  
  691. `C-c C-c e'
  692.      texinfo-insert-@end
  693.  
  694. `C-c C-c i'
  695.      texinfo-insert-@item
  696.  
  697. `C-c C-c n'
  698.      texinfo-insert-@node
  699.  
  700. `C-c C-c s'
  701.      texinfo-insert-@samp
  702.  
  703. `C-c C-c v'
  704.      texinfo-insert-@var
  705.  
  706. `M-{'
  707.      texinfo-insert-braces
  708.  
  709. `M-}'
  710.      up-list
  711.  
  712. This list was generated by analyzing the frequency with which
  713. commands were used in the ``GNU Emacs Manual'' and the ``GDB
  714. Manual''.  If you wish to add your own insert commands, you can bind
  715. a keyboard macro to a key, use abbreviations or extend the code in
  716. `texinfo.el'.
  717.  
  718.  
  719. 
  720. File: texinfo,  Node: Beginning a File,  Next: Ending a File,  Prev: Texinfo Mode,  Up: Top
  721.  
  722. Beginning a Texinfo File
  723. ************************
  724.  
  725. Various pieces of information have to be provided to Texinfo at the
  726. beginning of a Texinfo file, such as the name of the file, the title
  727. of the document and the like.  Generally, the beginning of a Texinfo
  728. file has four parts:
  729.  
  730.   1. The header, marked by start-of-header and end-of-header lines,
  731.      that includes the commands for naming the Texinfo file and
  732.      telling TeX what definitions' file to use when processing the
  733.      file.
  734.  
  735.   2. A section, marked by the `@ifinfo' and `@end ifinfo' commands,
  736.      that contains a short statement of what the file is about, the
  737.      copyright notice and copying permissions. This section appears
  738.      only in the Info file.
  739.  
  740.   3. A section, marked by the `@titlepage' and `@end titlepage'
  741.      commands, that contains the title page, the copyright page and
  742.      copying permissions.  This section appears only in the printed
  743.      manual.
  744.  
  745.   4. The `Top' node that contains an extensive menu for the whole
  746.      Info file.  The contents of this node only appear in the Info
  747.      file.
  748.  
  749. If the Texinfo file has a section containing licensing information
  750. and a warranty disclaimer, that section usually follows the `Top'
  751. node.  The licensing section will be followed by a preface or else by
  752. the first chapter of the manual.
  753.  
  754. Since the copyright notice and the copying permissions are in
  755. sections that appear only in the Info file or only in the printed
  756. manual, this information has to be repeated twice.
  757.  
  758. The following sample shows what is needed.
  759.  
  760.      \input texinfo   @c -*-texinfo-*-
  761.      @comment %**start of header (This is for running Texinfo on a region.)
  762.      @setfilename name-of-texinfo-file
  763.      @settitle Name of Manual
  764.      @setchapternewpage odd
  765.      @comment %**end of header (This is for running Texinfo on a region.)
  766.      
  767.      @ifinfo
  768.      This file documents ...
  769.      
  770.      Copyright @copyright{} year  copyright-owner
  771.      
  772.      Permission is granted to ...
  773.      @end ifinfo
  774.      
  775.      @titlepage
  776.      @sp 10
  777.      @center @titlefont{Name of Manual When Printed}
  778.      @sp 2
  779.      @center Subtitle, If Any
  780.      @sp 2
  781.      @center Author
  782.      
  783.      @comment  The following two commands start the copyright page.
  784.      @page
  785.      @vskip 0pt plus 1filll
  786.      Copyright @copyright{} year copyright-owner
  787.      
  788.      Published by ...
  789.      
  790.      Permission is granted to ...
  791.      @end titlepage
  792.      
  793.      
  794.      @node Top, Overview, (dir), (dir)
  795.      
  796.      @menu
  797.      * First Chapter::        The first chapter is usually an overview.
  798.      * Second Chapter::        ...
  799.        <many more menu items here>
  800.      @end menu
  801.      
  802.      @node    First Chapter, Second Chapter, top,      top
  803.      @comment node-name,     next,           previous, up
  804.      @chapter First Chapter
  805.      @cindex Reference to First Chapter
  806.  
  807. * Menu:
  808.  
  809. * Header::            Necessary first lines.
  810. * Permissions for Info::    Copyright notice and copying permissions.
  811. * Titlepage & Copyright Page::    Printed title and copyright pages.
  812. * Top Node::            The top node and master menu.
  813. * License and Distribution::     The importance of the license.
  814.  
  815.  
  816. 
  817. File: texinfo,  Node: Header,  Next: Permissions for Info,  Prev: Beginning a File,  Up: Beginning a File
  818.  
  819. The Texinfo File Header
  820. =======================
  821.  
  822. Texinfo files start with at least three lines that provide Info and
  823. TeX with necessary information.  If you want to run TeX on just a
  824. part of the Texinfo File, you also have to mark these heading lines
  825. with start-of-header and end-of-header lines.
  826.  
  827. * Menu:
  828.  
  829. * First Line::            The first line of a Texinfo file.
  830. * Start-of-Header::        Identifying the start of the header.
  831. * Setfilename::            Specifying the name of the Info file.
  832. * Settitle::            Specifying the title used by the headings.
  833. * Setchapternewpage::        Starting chapters on odd numbered pages.
  834. * End-of-Header::        Identifying the end of the header.
  835.  
  836.  
  837. 
  838. File: texinfo,  Node: First Line,  Next: Start-of-Header,  Prev: Header,  Up: Header
  839.  
  840. The First Line of a Texinfo File
  841. --------------------------------
  842.  
  843. Every Texinfo file that is to be the top-level input to TeX must
  844. begin with a line that looks like this:
  845.  
  846.      \input texinfo   @c -*-texinfo-*-
  847.  
  848. The line serves two functions:
  849.  
  850.   1. When the file is processed by TeX, it loads the macros needed
  851.      for processing a Texinfo file.  These are in a file called
  852.      `texinfo.tex' which is usually located in the
  853.      `/usr/lib/tex/macros' directory.
  854.  
  855.   2. When the file is edited in GNU Emacs, it causes Texinfo mode to
  856.      be used.
  857.  
  858. The `\input texinfo' line should be followed by the start-of-header
  859. line.  This makes it possible for the command for running TeX on a
  860. part of the Texinfo file (`texinfo-hardcopy-region') to operate.  The
  861. reason for this is that the `texinfo-hardcopy-region' command will
  862. look on the line preceding the start-of-header line for the `\input
  863. texinfo' line.
  864.  
  865.  
  866. 
  867. File: texinfo,  Node: Start-of-Header,  Next: Setfilename,  Prev: First Line,  Up: Header
  868.  
  869. `start-of-header'
  870. -----------------
  871.  
  872. The start-of-header line should immediately follow the first line of
  873. the Texinfo file.
  874.  
  875. The `texinfo-hardcopy-region' command will look at the line preceding
  876. the start-of-header line to find the `\input texinfo' line.
  877.  
  878. Usually, the start-of-header line looks like this:
  879.  
  880.      @comment %**start of header (This is for running Texinfo on a region.)
  881.  
  882. The reason for the odd string of characters (`%**') is so that the
  883. `texinfo-hardcopy-region' command does not accidently find something
  884. that it shouldn't when it is looking for the header.
  885.  
  886. In the default configuration, the phrase `(This is for running
  887. Texinfo on a region.)' is not needed and is just included to make it
  888. easier for someone reading the Texinfo file.
  889.  
  890. The start-of-header line and the end-of-header line are Texinfo mode
  891. variables that you can change.
  892.  
  893.  
  894. 
  895. File: texinfo,  Node: Setfilename,  Next: Settitle,  Prev: Start-of-Header,  Up: Header
  896.  
  897. @setfilename
  898. ------------
  899.  
  900. In order to be made into an Info file, a Texinfo file must contain a
  901. line that looks like this:
  902.  
  903.      @setfilename INFO-FILE-NAME
  904.  
  905. This line specifies the name of the Info file to be generated.  In
  906. fact, there can be other things in the file before this line, but
  907. they are ignored in the generation of an Info file.  The
  908. `@setfilename' line is ignored when a printed manual is generated.
  909.  
  910.  
  911. 
  912. File: texinfo,  Node: Settitle,  Next: Setchapternewpage,  Prev: Setfilename,  Up: Header
  913.  
  914. @settitle
  915. ---------
  916.  
  917. In order to be made into a printed manual file, a Texinfo file must
  918. contain a line that specifies the title of the manual.  Texinfo uses
  919. this information during printing to put the title on every other page
  920. as a heading; Texinfo puts the current chapter title on the other
  921. pages.  Texinfo can find the name of the chapter title from the
  922. information provided by the `@chapter' command, but you must tell it
  923. the manual title with `@settitle':
  924.  
  925.      @settitle TITLE
  926.  
  927. This command, on a line by itself, causes TITLE to be used for the
  928. headings.  Usually, you will use the same words for the title on the
  929. title page and for the title specified by this command for the
  930. headings, but the two could be different.  For example, the title on
  931. the title page may be longer than the title specified by the
  932. `settitle' command.
  933.  
  934. The `@settitle' command should precede everything that generates
  935. actual output.
  936.  
  937.  
  938. 
  939. File: texinfo,  Node: Setchapternewpage,  Next: End-of-Header,  Prev: Settitle,  Up: Header
  940.  
  941. @setchapternewpage
  942. ------------------
  943.  
  944. Conventionally, chapters start on the page on the right hand side of
  945. a book; and the right hand page has an odd number.  To make sure that
  946. Texinfo does this, you can use the command `@setchapternewpage'.  For
  947. example, to cause each chapter to start on a fresh odd-numbered page:
  948.  
  949.      @setchapternewpage odd
  950.  
  951. Page numbering is turned on by the `@end titlepage' command, so the
  952. `@setchapternewpage' should come before it.  Although it can occur
  953. anywhere in the beginning of the file, it is most convenient to put
  954. it in this location.
  955.  
  956.  
  957. 
  958. File: texinfo,  Node: End-of-Header,  Prev: Setchapternewpage,  Up: Header
  959.  
  960. `end-of-header'
  961. ---------------
  962.  
  963. The end-of-header line should follow the line containing the
  964. `@setchapternewpage' command.
  965.  
  966. Usually, the end-of-header line looks like this:
  967.  
  968.      @comment %**end of header (This is for running Texinfo on a region.)
  969.  
  970. In the default configuration, the phrase `(This is for running
  971. Texinfo on a region.)' is not needed and is just included to make it
  972. easier for someone reading the Texinfo file.
  973.  
  974. The reason for the odd string of characters (`%**') is so that the
  975. `texinfo-hardcopy-region' command does not accidently find something
  976. that it shouldn't when it is looking for the header.
  977.  
  978. The start-of-header line and the end-of-header line are Texinfo mode
  979. variables that you can change.
  980.  
  981.  
  982. 
  983. File: texinfo,  Node: Permissions for Info,  Next: Titlepage & Copyright Page,  Prev: Header,  Up: Beginning a File
  984.  
  985. Copying Permissions for Info
  986. ============================
  987.  
  988. Since the title page and the copyright page appear only in the
  989. printed copy of the manual, the same information has to inserted in a
  990. section that appears only in the Info file.  This section usually
  991. contains a brief description of the contents of the Info file, a
  992. copyright notice and copying permissions.
  993.  
  994. The copyright notice should read:
  995.  
  996.      Copyright YEAR COPYRIGHT-OWNER
  997.  
  998. and be put on a line by itself.
  999.  
  1000. Standard text for the copyright permissions is contained in the
  1001. appendix.  *Note Ifinfo Permissions::, for the complete text.
  1002.  
  1003.  
  1004. 
  1005. File: texinfo,  Node: Titlepage & Copyright Page,  Next: Top Node,  Prev: Permissions for Info,  Up: Beginning a File
  1006.  
  1007. The Title and Copyright Pages
  1008. =============================
  1009.  
  1010. The title and copyright pages appear in the printed manual, but not
  1011. in the Info file.  Because of this, it is possible to use a couple of
  1012. slightly obscure TeX typesetting commands that could not be used in
  1013. an Info file.  In addition, this part of the beginning of a Texinfo
  1014. file contains the text of the copying permissions that will appear in
  1015. the printed manual.
  1016.  
  1017. * Menu:
  1018.  
  1019. * Titlepage::            Creating a title page for the printed manual.
  1020. * Center::            Centering a line.
  1021. * Copyright & Printed Permissions::     Inserting the copyright notice 
  1022.                     and printed permissions.
  1023.  
  1024.  
  1025. 
  1026. File: texinfo,  Node: Titlepage,  Next: Center,  Prev: Titlepage & Copyright Page,  Up: Titlepage & Copyright Page
  1027.  
  1028. @titlepage
  1029. ----------
  1030.  
  1031. Start the material for the title page and following copyright page
  1032. with `@titlepage' on a line by itself and end it with `@end
  1033. titlepage' on a line by itself.  The title page and copyright page
  1034. material appears only in the printed manual, not in the Info file.
  1035.  
  1036. Also, the `@end titlepage' command starts a new page and turns on
  1037. page numbering (generation of headings).  Therefore, all the material
  1038. that you want to appear on unnumbered pages should be put between the
  1039. `@titlepage' and `@end titlepage' commands.  By using the `@page'
  1040. command you can force a page break within the region delineated by
  1041. the `@titlepage' and `@end titlepage' commands and create more than
  1042. one unnumbered page.  This is how the copyright page is produced.
  1043.  
  1044. To select a large font suitable for the title itself, you can use the
  1045. command `@titlefont'.  For example:
  1046.  
  1047.      @center @titlefont{Texinfo}
  1048.  
  1049. Also, you can use `@sp' commands to adjust vertical spacing.   For
  1050. example:
  1051.  
  1052.      @sp 2
  1053.  
  1054. In the sample, the spacing was chosen to fit an 8 1/2 by 11 inch
  1055. manual.
  1056.  
  1057.  
  1058. 
  1059. File: texinfo,  Node: Center,  Next: Copyright & Printed Permissions,  Prev: Titlepage,  Up: Titlepage & Copyright Page
  1060.  
  1061. @center
  1062. -------
  1063.  
  1064. A line containing `@center TEXT' produces a line of output containing
  1065. TEXT, centered between the margins.
  1066.  
  1067.  
  1068. 
  1069. File: texinfo,  Node: Copyright & Printed Permissions,  Prev: Center,  Up: Titlepage & Copyright Page
  1070.  
  1071. The Copyright Page and Printed Permissions
  1072. ------------------------------------------
  1073.  
  1074. By international treaty, the copyright notice for a book should
  1075. either be on the title page or on the back of the title page.  Other
  1076. locations in a book are not official and do not provide copyright
  1077. protection.  The copyright notice should include the year followed by
  1078. the name of the person or organization who has the copyright.
  1079.  
  1080. When the copyright notice is on the back of the title page, the page
  1081. is not numbered.  Therefore, in Texinfo, the information on the
  1082. copyright page should be within the region delineated by the
  1083. `@titlepage' and `@end titlepage' commands.
  1084.  
  1085. To cause a page break, the `@page' command is used.  In the sample,
  1086. the `@page' command is followed by the somewhat mysterious line that
  1087. reads: `@vskip 0pt plus 1filll'.  This is a line that uses TeX
  1088. commands to push the copyright notice and the other text on the
  1089. copyright page towards the bottom of the page.  The `@vskip' command
  1090. means to skip lines and put in white space.  The `0pt plus 1filll'
  1091. means to put in zero points of mandatory white space, and as much
  1092. optional white space as needed.  Note the use of three `l's in the
  1093. word `filll'; this is the correct use in TeX.
  1094.  
  1095. The `@copyright{}' command generates a `c' inside a circle.  The
  1096. copyright notice itself has the following legally defined sequence:
  1097.  
  1098.      Copyright (C) YEAR COPYRIGHT-OWNER
  1099.  
  1100. It is customary to put information on how to get a manual after the
  1101. copyright notice (the address of the Free Software Foundation, for
  1102. example) and the permissions.
  1103.  
  1104. Note that the permissions have to be repeated here as well as in the
  1105. `ifinfo' section that immediately follows the header since this
  1106. section appears only in the printed manual and the `ifinfo' section
  1107. appears only in the Info file.
  1108.  
  1109. Standard text for the permissions appears in the appendix.   *Note
  1110. Sample Permissions::.
  1111.  
  1112.  
  1113. 
  1114. File: texinfo,  Node: Top Node,  Next: License and Distribution,  Prev: Titlepage & Copyright Page,  Up: Beginning a File
  1115.  
  1116. The Top Node and Master Menu
  1117. ============================
  1118.  
  1119. The `Top' node contains an extensive, master menu for the whole Info
  1120. file.  The contents of this node appear only in the Info file. 
  1121. Nothing in this node should appear in the printed file.  Since a node
  1122. line by itself and a menu by itself are not printed, the contents of
  1123. this node do not have to be within a region delineated by `@ifinfo'
  1124. and `@end ifinfo' commands.  However, any text within the node should
  1125. be marked off in that manner.  You may want to put a short summary
  1126. before the master menu inside a region delineated by `@ifinfo' and
  1127. `@end ifinfo' commands.  Usually, the `Previous' and `Up' nodes refer
  1128. to the top level directory of the whole Info system, with pointers to
  1129. `(dir)'.
  1130.  
  1131. Generally, the top menu is divided into parts.
  1132.  
  1133.    * The first part contains the major nodes in the Texinfo file: the
  1134.      nodes for the chapters, chapter-like sections and the major
  1135.      appendices.
  1136.  
  1137.    * The second part contains entries for the indices.  In an Info
  1138.      file, it is very useful to have indices here at the beginning of
  1139.      the file in the top node rather than at the end, as in a printed
  1140.      book.
  1141.  
  1142.    * The third and subsequent parts contain a listing of the other,
  1143.      lower level nodes, often ordered by chapter.  This way, an
  1144.      inquirer can go directly to a particular node if he or she is
  1145.      searching for specific information.  (These nodes are not
  1146.      required; use them if you think they are a convenience.)
  1147.  
  1148. Each section in the menu can be introduced a descriptive line.  So
  1149. long as the line does not begin with an asterisk, it will not be
  1150. treated as a menu item.  (*Note Making Menus: Menu, for more
  1151. information.)
  1152.  
  1153. For example, the Top node of this manual looks like this (but with
  1154. many more entries):
  1155.  
  1156.      @node Top, Overview, (dir), (dir)
  1157.      
  1158.      @menu
  1159.      * Overview::                    What is Texinfo?
  1160.      * Texinfo Mode::                Special features in GNU Emacs.
  1161.      ...
  1162.      
  1163.      Indices, nodes containing large menus
  1164.      
  1165.      * Command Index::               An item for each @-command.
  1166.      * Concept Index::               An item for each concept.
  1167.      
  1168.      A detailed node listing
  1169.      
  1170.      Overview
  1171.      * Info File::                   Characteristics of the Info file.
  1172.      * Printed Manual::              Characteristics of the printed manual.
  1173.      
  1174.      Using Texinfo Mode
  1175.      * Info on a Region::            Formatting a region for Info.
  1176.      * Showing the Structure::       Showing the structure of a file.
  1177.      ...
  1178.      ...
  1179.  
  1180.  
  1181. 
  1182. File: texinfo,  Node: License and Distribution,  Prev: Top Node,  Up: Beginning a File
  1183.  
  1184. Licensing and Distribution Information
  1185. ======================================
  1186.  
  1187. If the Texinfo file has a section containing the "General Public
  1188. License" and the distribution information and a warranty disclaimer,
  1189. this section usually follows the `Top' node.  The licensing and
  1190. distribution information and the disclaimer are followed by a preface
  1191. or else by the first chapter of the manual.
  1192.  
  1193. The licensing agreement is very important to Project GNU
  1194. documentation and software.  Without it, you may find that you can no
  1195. longer get the software or its documentation.  This sounds
  1196. paradoxical, but the state of the world is such that documentation
  1197. and software that does not have a "restrictive" license to make them
  1198. freely distributable may be lost to the public.  This has happened.
  1199.  
  1200. For a good example of the text that could be used for the
  1201. Distribution, General Public License and NO WARRANTY sections of your
  1202. document, see the latest version of the ``GNU Emacs Manual''.
  1203.  
  1204. Although a preface is not a required part of a Texinfo file, it is
  1205. very helpful.  Ideally, it should state clearly and concisely what
  1206. the file is about and who would be interested in reading it.  In
  1207. general, the preface would follow the licensing and distribution
  1208. information, although sometimes people put it earlier in the
  1209. document.  Usually, a preface is put in an `@unnumbered' section. 
  1210. (*Note Unnumbered and Appendix::.)
  1211.  
  1212.  
  1213. 
  1214. File: texinfo,  Node: Ending a File,  Next: Structuring,  Prev: Beginning a File,  Up: Top
  1215.  
  1216. Ending a Texinfo File
  1217. *********************
  1218.  
  1219. The end of a Texinfo file should include the indices, the commands to
  1220. generate detailed and summary tables of contents and the @-command
  1221. that tells TeX that it has reached the end of the file.
  1222.  
  1223. For example, a Texinfo file might be ended as follows:
  1224.  
  1225.      @node    Concept Index,     , Previous Node, Top
  1226.      @comment node-name,     next, previous,      up
  1227.      @unnumbered Concept Index
  1228.      
  1229.      @printindex cp
  1230.      
  1231.      @contents
  1232.      @bye
  1233.  
  1234. The `@bye' command should be on a line by itself and every Texinfo
  1235. file must end with such a line.  This command terminates TeX
  1236. processing and forces out unfinished pages.
  1237.  
  1238. * Menu:
  1239.  
  1240. * Contents::        Generating a table of contents
  1241. * Indices::        Generating, sorting and printing indices
  1242.  
  1243.  
  1244. 
  1245. File: texinfo,  Node: Contents,  Next: Indices,  Up: Ending a File
  1246.  
  1247. Generating a Table of Contents
  1248. ==============================
  1249.  
  1250. The commands `@chapter', `@section', etc., supply the information to
  1251. make up a table of contents, but they do not cause an actual table to
  1252. be generated.  To do this, you must use the commands `@contents' and
  1253. `@summarycontents'.
  1254.  
  1255. `@contents'
  1256.      The table of contents command outputs (into a printed manual) a
  1257.      complete table of contents, based on the `@chapter',
  1258.      `@unnumbered' and other sectioning commands.  This command
  1259.      should be used on a line by itself.
  1260.  
  1261. `@summarycontents'
  1262.      The summary contents command generates a summary table of
  1263.      contents that lists only the chapters (and appendices and
  1264.      unnumbered chapters); sections, subsections and subsubsections
  1265.      are omitted.  This command should be used on a line by itself. 
  1266.      Only large manuals need a summary table of contents.
  1267.  
  1268. You can use either one of these commands, or both.  Each command
  1269. automatically generates a chapter-like heading at the top of the page.
  1270. Tables of contents should be generated at the very end of the manual,
  1271. just before the `@bye' command; the tables of contents commands
  1272. should follow any indices that are output, so that the indices will
  1273. appear in the contents.
  1274.  
  1275.      INDICES...
  1276.      @summarycontents
  1277.      @contents
  1278.      @bye
  1279.  
  1280. The commands `@contents' and `@summarycontents' are ignored when an
  1281. Info file is being generated.
  1282.  
  1283.  
  1284.