/usr/share/doc/texinfo/html/Debugging-with-TeX.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This manual is for GNU Texinfo (version 5.2, 26 September 2013),
a documentation system that can produce both online information and a
printed manual from a single source using semantic markup.

Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997,
1998, 1999, 2001, 2001, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
2010, 2011, 2012, 2013 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 the Front-Cover Texts being "A GNU Manual",
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled "GNU Free Documentation
License".

(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
modify this GNU manual.  Buying copies from the FSF supports it in
developing GNU and promoting software freedom." -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GNU Texinfo 5.2: Debugging with TeX</title>

<meta name="description" content="GNU Texinfo 5.2: Debugging with TeX">
<meta name="keywords" content="GNU Texinfo 5.2: Debugging with TeX">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Command-and-Variable-Index.html#Command-and-Variable-Index" rel="index" title="Command and Variable Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Catching-Mistakes.html#Catching-Mistakes" rel="up" title="Catching Mistakes">
<link href="Using-texinfo_002dshow_002dstructure.html#Using-texinfo_002dshow_002dstructure" rel="next" title="Using texinfo-show-structure">
<link href="Debugging-with-Info.html#Debugging-with-Info" rel="previous" title="Debugging with Info">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {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}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Debugging-with-TeX"></a>
<div class="header">
<p>
Next: <a href="Using-texinfo_002dshow_002dstructure.html#Using-texinfo_002dshow_002dstructure" accesskey="n" rel="next">Using <tt>texinfo-show-structure</tt></a>, Previous: <a href="Debugging-with-Info.html#Debugging-with-Info" accesskey="p" rel="previous">Debugging with Info</a>, Up: <a href="Catching-Mistakes.html#Catching-Mistakes" accesskey="u" rel="up">Catching Mistakes</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Command-and-Variable-Index.html#Command-and-Variable-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Debugging-with-TeX-1"></a>
<h3 class="section">E.3 Debugging with TeX</h3>
<a name="index-Catching-errors-with-TeX-formatting"></a>
<a name="index-Debugging-with-TeX-formatting"></a>

<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#Debugging-with-Info">Debugging with Info</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.
&lt;to be read again&gt;
                  @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>&lsquo;<samp>@par</samp>&rsquo; is an internal TeX command of no relevance to Texinfo.
&lsquo;<samp>l.27</samp>&rsquo; means that TeX detected the problem on line 27 of the
Texinfo file.  The &lsquo;<samp>?</samp>&rsquo; 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 &lsquo;<samp>?</samp>&rsquo; 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 &lsquo;<samp>?</samp>&rsquo; 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 &lsquo;<samp>?</samp>&rsquo; 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 &lsquo;<samp>?</samp>&rsquo; 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 &lsquo;<samp>*</samp>&rsquo; 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, &lsquo;<samp>\</samp>&rsquo;.  TeX uses &lsquo;<samp>\</samp>&rsquo;
instead of &lsquo;<samp>@</samp>&rsquo;; and in this circumstance, you are working
directly with TeX, not with Texinfo.)
</p>
<hr>
<div class="header">
<p>
Next: <a href="Using-texinfo_002dshow_002dstructure.html#Using-texinfo_002dshow_002dstructure" accesskey="n" rel="next">Using <tt>texinfo-show-structure</tt></a>, Previous: <a href="Debugging-with-Info.html#Debugging-with-Info" accesskey="p" rel="previous">Debugging with Info</a>, Up: <a href="Catching-Mistakes.html#Catching-Mistakes" accesskey="u" rel="up">Catching Mistakes</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Command-and-Variable-Index.html#Command-and-Variable-Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
texinfo-doc-nonfree 5.2.0-1 / usr / share / doc / texinfo / html / Debugging-with-TeX.html
