home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 4 / FreshFish_May-June1994.bin / gnu / info / texi.info-4 (.txt) < prev    next >
GNU Info File  |  1994-02-24  |  50KB  |  944 lines
  1. This is Info file texi.info, produced by Makeinfo-1.55 from the input
  2. file texi.texi.
  3.    This file documents Texinfo, a documentation system that uses a
  4. single source file to produce both on-line information and a printed
  5. manual.
  6.    Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation,
  7.    This is the second edition of the Texinfo documentation,
  8. and is consistent with version 2 of `texinfo.tex'.
  9.    Permission is granted to make and distribute verbatim copies of this
  10. manual provided the copyright notice and this permission notice are
  11. preserved on all copies.
  12.    Permission is granted to copy and distribute modified versions of
  13. this manual under the conditions for verbatim copying, provided that
  14. the entire resulting derived work is distributed under the terms of a
  15. permission notice identical to this one.
  16.    Permission is granted to copy and distribute translations of this
  17. manual into another language, under the above conditions for modified
  18. versions, except that this permission notice may be stated in a
  19. translation approved by the Free Software Foundation.
  20. File: texi.info,  Node: Node Line Requirements,  Next: First Node,  Prev: Node Line Tips,  Up: node
  21. `@node' Line Requirements
  22. -------------------------
  23.    Here are several requirements for `@node' lines:
  24.    * All the node names for a single Info file must be unique.
  25.      Duplicates confuse the Info movement commands.  This means, for
  26.      example, that if you end every chapter with a summary, you must
  27.      name each summary node differently.  You cannot just call each one
  28.      "Summary".  You may, however, duplicate the titles of chapters,
  29.      sections, and the like.  Thus you can end each chapter in a book
  30.      with a section called "Summary", so long as the node names for
  31.      those sections are all different.
  32.    * A pointer name must be the name of a node.
  33.      The node to which a pointer points may come before or after the
  34.      node containing the pointer.
  35.    * You cannot use any of the Texinfo @-commands in a node name;
  36.      @-commands confuse Info.
  37.      Thus, the beginning of the section called `@chapter' looks like
  38.      this:
  39.           @node  chapter, unnumbered & appendix, makeinfo top, Structuring
  40.           @comment  node-name,  next,  previous,  up
  41.           @section @code{@@chapter}
  42.           @findex chapter
  43.    * You cannot use commas, colons, or apostrophes within a node name;
  44.      these confuse TeX or the Info formatters.
  45.      For example, the following is a section title:
  46.           @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
  47.      The corresponding node name is:
  48.           unnumberedsec appendixsec heading
  49.    * Case is significant.
  50. File: texi.info,  Node: First Node,  Next: makeinfo top command,  Prev: Node Line Requirements,  Up: node
  51. The First Node
  52. --------------
  53.    The first node of a Texinfo file is the `Top' node, except in an
  54. included file (*note Include Files::.).
  55.    The `Top' node (which must be named `top' or `Top') should have as
  56. its `Up' and `Previous' nodes the name of a node in another file, where
  57. there is a menu that leads to this file.  Specify the file name in
  58. parentheses.  If the file is to be installed directly in the Info
  59. directory file, use `(dir)' as the parent of the `Top' node; this is
  60. short for `(dir)top', and specifies the `Top' node in the `dir' file,
  61. which contains the main menu for Info.  For example, the `@node Top'
  62. line of this manual looks like this:
  63.      @node Top, Overview, (dir), (dir)
  64. (You may use the Texinfo updating commands or the `makeinfo' utility to
  65. insert these `Next' and `(dir)' pointers automatically.)
  66.    *Note Install an Info File::, for more information about installing
  67. an Info file in the `info' directory.
  68.    The `Top' node contains the main or master menu for the document.
  69. File: texi.info,  Node: makeinfo top command,  Next: Top Node Summary,  Prev: First Node,  Up: node
  70. The `@top' Sectioning Command
  71. -----------------------------
  72.    A special sectioning command, `@top', has been created for use with
  73. the `@node Top' line.  The `@top' sectioning command tells `makeinfo'
  74. that it marks the `Top' node in the file.  It provides the information
  75. that `makeinfo' needs to insert node pointers automatically.  Write the
  76. `@top' command at the beginning of the line immediately following the
  77. `@node Top' line.  Write the title on the remaining part of the same
  78. line as the `@top' command.
  79.    In Info, the `@top' sectioning command causes the title to appear on
  80. a line by itself, with a line of asterisks inserted underneath.
  81.    In TeX and `texinfo-format-buffer', the `@top' sectioning command is
  82. merely a synonym for `@unnumbered'.  Neither of these formatters
  83. require an `@top' command, and do nothing special with it.  You can use
  84. `@chapter' or `@unnumbered' after the `@node Top' line when you use
  85. these formatters.  Also, you can use `@chapter' or `@unnumbered' when
  86. you use the Texinfo updating commands to create or update pointers and
  87. menus.
  88.    Whatever sectioning command follows an `@node Top' line, whether it
  89. be `@top' or `@chapter', the `@node Top' line and the immediately
  90. following line and any additional text must be enclosed between
  91. `@ifinfo' and `@end ifinfo' commands.  (*Note Conditionals::.)  This
  92. prevents the title and the accompanying text from appearing in printed
  93. output.  Write the `@ifinfo' command before the `@node' line and write
  94. the `@end ifinfo' command after the `@top' or other sectioning command
  95. and after any additional text.  (You can write the `@end ifinfo'
  96. command after the `@end menu' command if you like.)
  97. File: texi.info,  Node: Top Node Summary,  Prev: makeinfo top command,  Up: node
  98. The `Top' Node Summary
  99. ----------------------
  100.    You can help readers by writing a summary in the `Top' node, after
  101. the `@top' line, before the main or master menu.  The summary should
  102. briefly describe the Info file.  You should also write the version
  103. number of the program to which the manual applies in this section.  This
  104. helps the reader keep track of which manual is for which version of the
  105. program.  If the manual changes more frequently than the program or is
  106. independent of it, you should also include an edition number for the
  107. manual.  (The title page should also contain this information: see
  108. *Note `@titlepage': titlepage.)
  109.    Put the whole of the `Top' node, including the `@top' sectioning
  110. command line if you have one, between `@ifinfo' and `@end ifinfo' so
  111. none of the text appears in the printed output (*note Conditionally
  112. Visible Text: Conditionals.).  (You may want to repeat the brief
  113. description from the `Top' node within `@iftex' ... `@end iftex' at the
  114. beginning of the first chapter, for those who read the printed manual.)
  115. File: texi.info,  Node: makeinfo Pointer Creation,  Prev: node,  Up: Nodes
  116. Creating Pointers with `makeinfo'
  117. =================================
  118.    The `makeinfo' program has a feature for automatically creating node
  119. pointers for a hierarchically organized file that lacks them.
  120.    When you take advantage of this feature, you do not need to write the
  121. `Next', `Previous', and `Up' pointers after the name of a node.
  122. However, you must write a sectioning command, such as `@chapter' or
  123. `@section', on the line immediately following each truncated `@node'
  124. line.  You cannot write a comment line after a node line; the section
  125. line must follow it immediately.
  126.    In addition, you must follow the `Top' `@node' line with a line
  127. beginning with `@top' to mark the `Top' node in the file. *Note `@top':
  128. makeinfo top.
  129.    Finally, you must write the name of each node (except for the `Top'
  130. node) in a menu that is one or more hierarchical levels above the
  131. node's hierarchical level.
  132.    This node pointer insertion feature in `makeinfo' is an alternative
  133. to the menu and pointer creation and update commands in Texinfo mode.
  134. (*Note Updating Nodes and Menus::.)  It is especially helpful to people
  135. who do not use GNU Emacs for writing Texinfo documents.
  136. File: texi.info,  Node: Menus,  Next: Cross References,  Prev: Nodes,  Up: Top
  137. Menus
  138. *****
  139.    "Menus" contain pointers to subordinate nodes.(1) In Info, you use
  140. menus to go to such nodes.  Menus have no effect in printed manuals and
  141. do not appear in them.
  142.    By con