JezK
Edit File: Debugging-with-TeX.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ --> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <!-- This manual is for GNU Texinfo (version 6.8, 8 June 2021), a documentation system that can produce both online information and a printed manual from a single source using semantic markup. Copyright (C) 1988, 1990-1993, 1995-1999, 2001-2021 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". --> <title>Debugging with TeX (GNU Texinfo 6.8)</title> <meta name="description" content="Debugging with TeX (GNU Texinfo 6.8)"> <meta name="keywords" content="Debugging with TeX (GNU Texinfo 6.8)"> <meta name="resource-type" content="document"> <meta name="distribution" content="global"> <meta name="Generator" content="texi2any"> <meta name="viewport" content="width=device-width,initial-scale=1"> <link href="index.html" rel="start" title="Top"> <link href="Command-and-Variable-Index.html" rel="index" title="Command and Variable Index"> <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> <link href="Catching-Mistakes.html" rel="up" title="Catching Mistakes"> <link href="Using-texinfo_002dshow_002dstructure.html" rel="next" title="Using texinfo-show-structure"> <link href="Debugging-with-Info.html" rel="prev" title="Debugging with Info"> <style type="text/css"> <!-- a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em} a.summary-letter {text-decoration: none} blockquote.indentedblock {margin-right: 0em} div.display {margin-left: 3.2em} div.example {margin-left: 3.2em} kbd {font-style: oblique} pre.display {font-family: inherit} pre.format {font-family: inherit} pre.menu-comment {font-family: serif} pre.menu-preformatted {font-family: serif} span.nolinebreak {white-space: nowrap} span.roman {font-family: initial; font-weight: normal} span.sansserif {font-family: sans-serif; font-weight: normal} span:hover a.copiable-anchor {visibility: visible} ul.no-bullet {list-style: none} --> </style> </head> <body lang="en"> <div class="section" id="Debugging-with-TeX"> <div class="header"> <p> Next: <a href="Using-texinfo_002dshow_002dstructure.html" accesskey="n" rel="next">Using <code>texinfo-show-structure</code></a>, Previous: <a href="Debugging-with-Info.html" accesskey="p" rel="prev">Catching Errors with Info Formatting</a>, Up: <a href="Catching-Mistakes.html" accesskey="u" rel="up">Catching Mistakes</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Command-and-Variable-Index.html" title="Index" rel="index">Index</a>]</p> </div> <hr> <span id="Debugging-with-TeX-1"></span><h4 class="subsection">D.9.3 Debugging with TeX</h4> <span id="index-Catching-errors-with-TeX-formatting"></span> <span id="index-Debugging-with-TeX-formatting"></span> <p>You can also catch mistakes when you format a file with TeX. </p> <p>Usually, you will want to do this after you have run <code>texinfo-format-buffer</code> (or, better, <code>makeinfo-buffer</code>) on the same file, because <code>texinfo-format-buffer</code> sometimes displays error messages that make more sense than TeX. (See <a href="Debugging-with-Info.html">Catching Errors with Info Formatting</a>, for more information.) </p> <p>For example, TeX was run on a Texinfo file, part of which is shown here: </p> <div class="example"> <pre class="example">---------- Buffer: texinfo.texi ---------- name of the Texinfo file as an extension. The @samp{??} are `wildcards' that cause the shell to substitute all the raw index files. (@xref{sorting indices, for more information about sorting indices.)@refill ---------- Buffer: texinfo.texi ---------- </pre></div> <p>(The cross-reference lacks a closing brace.) TeX produced the following output, after which it stopped: </p> <div class="example"> <pre class="example">---------- Buffer: *tex-shell* ---------- Runaway argument? {sorting indices, for more information about sorting indices.) @refill @ETC. ! Paragraph ended before @xref was complete. <to be read again> @par l.27 ? ---------- Buffer: *tex-shell* ---------- </pre></div> <p>In this case, TeX produced an accurate and understandable error message: </p> <div class="example"> <pre class="example">Paragraph ended before @xref was complete. </pre></div> <p>‘<samp>@par</samp>’ is an internal TeX command of no relevance to Texinfo. ‘<samp>l.27</samp>’ means that TeX detected the problem on line 27 of the Texinfo file. The ‘<samp>?</samp>’ is the prompt TeX uses in this circumstance. </p> <p>Unfortunately, TeX is not always so helpful, and sometimes you must truly be a Sherlock Holmes to discover what went wrong. </p> <p>In any case, if you run into a problem like this, you can do one of three things. </p> <ol> <li> You can tell TeX to continue running and ignore just this error by typing <tt class="key">RET</tt> at the ‘<samp>?</samp>’ prompt. </li><li> You can tell TeX to continue running and to ignore all errors as best it can by typing <kbd>r <span class="key">RET</span></kbd> at the ‘<samp>?</samp>’ prompt. <p>This is often the best thing to do. However, beware: the one error may produce a cascade of additional error messages as its consequences are felt through the rest of the file. To stop TeX when it is producing such an avalanche of error messages, type <kbd>C-c</kbd> (or <kbd>C-c C-c</kbd>, if you are running a shell inside Emacs). </p> </li><li> You can tell TeX to stop this run by typing <kbd>x <span class="key">RET</span></kbd> at the ‘<samp>?</samp>’ prompt. </li></ol> <p>If you are running TeX inside Emacs, you need to switch to the shell buffer and line at which TeX offers the ‘<samp>?</samp>’ prompt. </p> <p>Sometimes TeX will format a file without producing error messages even though there is a problem. This usually occurs if a command is not ended but TeX is able to continue processing anyhow. For example, if you fail to end an itemized list with the <code>@end itemize</code> command, TeX will write a DVI file that you can print out. The only error message that TeX will give you is the somewhat mysterious comment: </p> <div class="example"> <pre class="example">(@end occurred inside a group at level 1) </pre></div> <p>However, if you print the DVI file, you will find that the text of the file that follows the itemized list is entirely indented as if it were part of the last item in the itemized list. The error message is the way TeX says that it expected to find an <code>@end</code> command somewhere in the file; but that it could not determine where it was needed. </p> <p>Another source of notoriously hard-to-find errors is a missing <code>@end group</code> command. If you ever are stumped by incomprehensible errors, look for a missing <code>@end group</code> command first. </p> <p>If the Texinfo file lacks header lines, TeX may stop in the beginning of its run and display output that looks like the following. The ‘<samp>*</samp>’ indicates that TeX is waiting for input. </p> <div class="example"> <pre class="example">This is TeX, Version 3.14159 (Web2c 7.0) (test.texinfo [1]) * </pre></div> <p>In this case, simply type <kbd>\end <span class="key">RET</span></kbd> after the asterisk. Then write the header lines in the Texinfo file and run the TeX command again. (Note the use of the backslash, ‘<samp>\</samp>’. TeX uses ‘<samp>\</samp>’ instead of ‘<samp>@</samp>’; and in this circumstance, you are working directly with TeX, not with Texinfo.) </p> </div> <hr> <div class="header"> <p> Next: <a href="Using-texinfo_002dshow_002dstructure.html">Using <code>texinfo-show-structure</code></a>, Previous: <a href="Debugging-with-Info.html">Catching Errors with Info Formatting</a>, Up: <a href="Catching-Mistakes.html">Catching Mistakes</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Command-and-Variable-Index.html" title="Index" rel="index">Index</a>]</p> </div> </body> </html>