home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 4 / FreshFish_May-June1994.bin / gnu / info / texi.info-10 (.txt) < prev    next >
GNU Info File  |  1994-02-24  |  44KB  |  886 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: Debugging with TeX,  Next: Using texinfo-show-structure,  Prev: Debugging with Info,  Up: Catching Mistakes
  21. Catching Errors with TeX Formatting
  22. ===================================
  23.    You can also catch mistakes when you format a file with TeX.
  24.    Usually, you do this after you have run `texinfo-format-buffer' (or,
  25. better, `makeinfo-buffer') on the same file, because
  26. `texinfo-format-buffer' sometimes displays error messages that make
  27. more sense than TeX.  (*Note Debugging with Info::, for more
  28. information.)
  29.    For example, TeX was run on a Texinfo file, part of which is shown
  30. here:
  31.      ---------- Buffer: texinfo.texi ----------
  32.      name of the texinfo file as an extension.  The
  33.      @samp{??} are `wildcards' that cause the shell to
  34.      substitute all the raw index files.  (@xref{sorting
  35.      indices, for more information about sorting
  36.      indices.)@refill
  37.      ---------- Buffer: texinfo.texi ----------
  38. (The cross reference lacks a closing brace.) TeX produced the following
  39. output, after which it stopped:
  40.      ---------- Buffer: *texinfo-tex-shell* ----------
  41.      Runaway argument?
  42.      {sorting indices, for more information about sorting
  43.      indices.) @refill @ETC.
  44.      ! Paragraph ended before @xref was complete.
  45.      <to be read again>
  46.                         @par
  47.      l.27
  48.      
  49.      ?
  50.      ---------- Buffer: *texinfo-tex-shell* ----------
  51.    In this case, TeX produced an accurate and understandable error
  52. message:
  53.      Paragraph ended before @xref was complete.
  54. `@par' is an internal TeX command of no relevance to Texinfo.  `l.27'
  55. means that TeX detected the problem on line 27 of the Texinfo file.
  56. The `?' is the prompt TeX uses in this circumstance.
  57.    Unfortunately, TeX is not always so helpful, and sometimes you must
  58. truly be a Sherlock Holmes to discover what went wrong.
  59.    In any case, if you run into a problem like this, you can do one of
  60. three things.
  61.   1. You can tell TeX to continue running and ignore just this error by
  62.      typing RET at the `?' prompt.
  63.   2. You can tell TeX to continue running and to ignore all errors as
  64.      best it can by typing `r RET' at the `?' prompt.
  65.      This is often the best thing to do.  However, beware: the one error
  66.      may produce a cascade of additional error messages as its
  67.      consequences are felt through the rest of the file.  (To stop TeX
  68.      when it is producing such an avalanche of error messages, type
  69.      `C-d' (or `C-c C-d', if you are running a shell inside Emacs
  70.      Version 18.))
  71.   3. You can tell TeX to stop this run by typing `x RET' at the `?'
  72.      prompt.
  73.    Please note that if you are running TeX inside Emacs, you need to
  74. switch to the shell buffer and line at which TeX offers the `?' prompt.
  75.    Sometimes TeX will format a file without producing error messages
  76. even though there is a problem.  This usually occurs if a command is
  77. not ended but TeX is able to continue processing anyhow.  For example,
  78. if you fail to end an itemized list with the `@end itemize' command,
  79. TeX will write a DVI file that you can print out.  The only error
  80. message that TeX will give you is the somewhat mysterious comment that
  81.      (@end occurred inside a group at level 1)
  82. However, if you print the DVI file, you will find that the text of the
  83. file that follows the itemized list is entirely indented as if it were
  84. part of the last item in the itemized list.  The error message is the
  85. way TeX says that it expected to find an `@end' command somewhere in
  86. the file; but that it could not determine where it was needed.
  87.    Another source of notoriously hard-to-find errors is a missing `@end
  88. group' command.  If you ever are stumped by incomprehensible errors,
  89. look for a missing `@end group' command first.
  90.    If the Texinfo file lacks header lines, TeX may stop in the
  91. beginning of its run and display output that looks like the following.
  92. The `*' indicates that TeX is waiting for input.
  93.      This is TeX, Version 2.0 for Berkeley UNIX
  94.      (preloaded format=plain-cm 87.10.25)
  95.      (test.texinfo [1])
  96.      *
  97. In this case, simply type `\end RET' after the asterisk.  Then write
  98. the header lines in the Texinfo file and run the TeX command again.
  99. (Note the use of the backslash, `\'.  TeX uses `\' instead of `@'; and
  100. in this circumstance, you are working directly with TeX, not with
  101. Texinfo.)
  102. File: texi.info,  Node: Using texinfo-show-structure,  Next: Using occur,  Prev: Debugging with TeX,  Up: Catching Mistakes
  103. Using `texinfo-show-structure'
  104. ==============================
  105.    It is not always easy to keep track of the nodes, chapters,
  106. sections, and subsections of a Texinfo file.  This is especially true
  107. if you are revising or adding to a Texinfo file that someone else has
  108. written.
  109.    In GNU Emacs, in Texinfo mode, the `texinfo-show-structure' command
  110. lists all the lines that begin with the @-commands that specify the
  111. structure: `@chapter', `@section', `@appendix', and so on.  With an
  112. argument (`C-u' as prefix argument, if interactive), the command also
  113. shows the `@node' lines.  The `texinfo-show-structure' command is bound
  114. to `C-c C-s' in Texinfo mode, by default.
  115.    The lines are displayed in a buffer called the `*Occur*' buffer.
  116. For example, when `texinfo-show-structure' was run on an earlier
  117. version of this appendix, it produced the following:
  118.      Lines matching "^@\\(chapter \\|sect\\|sub\\|unnum\\|major\\|
  119.      heading \\|appendix\\)" in buffer texinfo.texi.
  120.        4:@appendix Formatting Mistakes
  121.       52:@appendixsec Catching Errors with Info Formatting
  122.      222:@appendixsec Catching Errors with @TeX{} Formatting
  123.      338:@appendixsec Using @code{texinfo-show-structure}
  124.      407:@appendixsubsec Using @code{occur}
  125.      444:@appendixsec Finding Badly Referenced Nodes
  126.      513:@appendixsubsec Running @code{Info-validate}
  127.      573:@appendixsubsec Splitting a File Manually
  128.    This says that lines 4, 52, and 222 of `texinfo.texi' begin with the
  129. `@appendix', `@appendixsec', and `@appendixsec' commands respectively.
  130. If you move your cursor into the `*Occur*' window, you can position the
  131. cursor over one of the lines and use the `C-c C-c' command
  132. (`occur-mode-goto-occurrence'), to jump to the corresponding spot in
  133. the Texinfo file.  *Note Using Occur: (emacs)Other Repeating Search,
  134. for more information about `occur-mode-goto-occurrence'.
  135.    The first line in the `*Occur*' window describes the "regular
  136. expression" specified by TEXINFO-HEADING-PATTERN.  This regular
  137. expression is the pattern that `texinfo-show-structure' looks for.
  138. *Note Using Regular Expressions: (emacs)Regexps, for more information.
  139.    When you invoke the `texinfo-show-structure' command, Emacs will
  140. display the structure of the whole buffer.  If you want to see the
  141. structure of just a part of the buffer, of one chapter, for example,
  142. use the `C-x n' (`narrow-to-region') command to mark the region.
  143. (*Note Narrowing: (emacs)Narrowing.)  This is how the example used
  144. above was generated.  (To see the whole buffer again, use `C-x w'
  145. (`widen').)
  146.    If you call `texinfo-show-structure' with a prefix argument by
  147. typing `C-u C-c C-s', it will list lines beginning with `@node'