diff options
Diffstat (limited to 'doc/groff.html.node/Debugging.html')
| -rw-r--r-- | doc/groff.html.node/Debugging.html | 317 |
1 files changed, 317 insertions, 0 deletions
diff --git a/doc/groff.html.node/Debugging.html b/doc/groff.html.node/Debugging.html new file mode 100644 index 0000000..594201c --- /dev/null +++ b/doc/groff.html.node/Debugging.html @@ -0,0 +1,317 @@ +<!DOCTYPE html> +<html> +<!-- Created by GNU Texinfo 7.0.3, https://www.gnu.org/software/texinfo/ --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<!-- This manual documents GNU troff version 1.23.0. + +Copyright © 1994-2023 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, no Front-Cover Texts, and no Back-Cover Texts. A +copy of the license is included in the section entitled "GNU Free +Documentation License". --> +<title>Debugging (The GNU Troff Manual)</title> + +<meta name="description" content="Debugging (The GNU Troff Manual)"> +<meta name="keywords" content="Debugging (The GNU Troff Manual)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +<link href="index.html" rel="start" title="Top"> +<link href="Request-Index.html" rel="index" title="Request Index"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="GNU-troff-Reference.html" rel="up" title="GNU troff Reference"> +<link href="Implementation-Differences.html" rel="next" title="Implementation Differences"> +<link href="Gtroff-Internals.html" rel="prev" title="Gtroff Internals"> +<style type="text/css"> +<!-- +a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em} +div.example {margin-left: 3.2em} +p.flushright-paragraph {text-align:right} +span.r {font-family: initial; font-weight: normal; font-style: normal} +span:hover a.copiable-link {visibility: visible} +strong.def-name {font-family: monospace; font-weight: bold; font-size: larger} +--> +</style> + + +</head> + +<body lang="en"> +<div class="section-level-extent" id="Debugging"> +<div class="nav-panel"> +<p> +Next: <a href="Implementation-Differences.html" accesskey="n" rel="next">Implementation Differences</a>, Previous: <a href="Gtroff-Internals.html" accesskey="p" rel="prev"><code class="code">gtroff</code> Internals</a>, Up: <a href="GNU-troff-Reference.html" accesskey="u" rel="up">GNU <code class="code">troff</code> Reference</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Request-Index.html" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<h3 class="section" id="Debugging-1">5.37 Debugging</h3> +<a class="index-entry-id" id="index-debugging"></a> + +<div class="flushright"><p class="flushright-paragraph"><i class="slanted">Standard troff voodoo, just put a power of two backslashes in +front of it until it works and if you still have problems add a \c.</i> +— Ron Natalie +</p></div> +<p>GNU <code class="code">troff</code> is not the easiest language to debug, in part thanks to +its design features of recursive interpolation and the use of +multi-stage pipeline processing in the surrounding system. Nevertheless +there exist several features useful for troubleshooting. +</p> +<p>Preprocessors use the <code class="code">lf</code> request to preserve the identity of the +line numbers and names of input files. GNU <code class="code">troff</code> emits a variety +of error diagnostics and supports several categories of warning; the +output of these can be selectively suppressed. A trace of the +formatter’s input processing stack can be emitted when errors or +warnings occur by means of GNU <code class="code">troff</code>’s <samp class="option">-b</samp> option, or +produced on demand with the <code class="code">backtrace</code> request. The <code class="code">tm</code> +and related requests can be used to emit customized diagnostic messages +or for instrumentation while troubleshooting. The <code class="code">ex</code> and +<code class="code">ab</code> requests cause early termination with successful and error +exit codes respectively, to halt further processing when continuing +would be fruitless. Examine the state of the formatter with requests +that write lists of defined names (macros, strings, and diversions), +environments, registers, and page location traps to the standard error +stream. +</p> +<dl class="first-deffn"> +<dt class="deffn" id="index-_002elf"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.lf</code></strong> <var class="def-var-arguments">line [<span class="r"><i class="slanted">file</i></span>]</var><a class="copiable-link" href='#index-_002elf'> ¶</a></span></dt> +<dd><a class="index-entry-id" id="index-lf"></a> +<a class="index-entry-id" id="index-soelim"></a> +<a class="index-entry-id" id="index-multi_002dfile-documents"></a> +<a class="index-entry-id" id="index-documents_002c-multi_002dfile"></a> +<a class="index-entry-id" id="index-setting-input-line-number-_0028lf_0029"></a> +<a class="index-entry-id" id="index-input-line-number_002c-setting-_0028lf_0029"></a> +<a class="index-entry-id" id="index-number_002c-input-line_002c-setting-_0028lf_0029"></a> +<p>Set the input line number (and, optionally, the file name) GNU +<code class="code">troff</code> shall use for error and warning messages. <var class="var">line</var> is +the input line number of the <em class="emph">next</em> line. Without an argument, the +request is ignored. +</p> +<p><code class="code">lf</code>’s primary purpose is to aid the debugging of documents that +undergo preprocessing. Programs like <code class="command">tbl</code> that transform input +in their own languages into <code class="code">roff</code> requests use it so that any +diagnostic messages emitted by <code class="code">troff</code> correspond to the source +document. +</p></dd></dl> + +<dl class="first-deffn"> +<dt class="deffn" id="index-_002etm"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.tm</code></strong> <var class="def-var-arguments">message</var><a class="copiable-link" href='#index-_002etm'> ¶</a></span></dt> +<dd><a class="index-entry-id" id="index-tm"></a> +</dd><dt class="deffnx def-cmd-deffn" id="index-_002etm1"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.tm1</code></strong> <var class="def-var-arguments">message</var><a class="copiable-link" href='#index-_002etm1'> ¶</a></span></dt> +<dd><a class="index-entry-id" id="index-tm1"></a> +</dd><dt class="deffnx def-cmd-deffn" id="index-_002etmc"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.tmc</code></strong> <var class="def-var-arguments">message</var><a class="copiable-link" href='#index-_002etmc'> ¶</a></span></dt> +<dd><a class="index-entry-id" id="index-tmc"></a> +<a class="index-entry-id" id="index-printing-to-stderr-_0028tm_002c-tm1_002c-tmc_0029"></a> +<a class="index-entry-id" id="index-stderr_002c-printing-to-_0028tm_002c-tm1_002c-tmc_0029"></a> +<p>Send <var class="var">message</var>, which consumes the remainder of the input line and +cannot contain special characters, to the standard error stream, +followed by a newline. Leading spaces in <var class="var">message</var> are ignored. +</p> +<p><code class="code">tm1</code> is similar, but recognizes and strips a leading neutral +double quote from <var class="var">message</var> to allow the embedding of leading +spaces. +</p> +<p><code class="code">tmc</code> works as <code class="code">tm1</code>, but does not append a newline. +</p></dd></dl> + +<dl class="first-deffn"> +<dt class="deffn" id="index-_002eab"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.ab</code></strong> <var class="def-var-arguments">[<span class="r"><i class="slanted">message</i></span>]</var><a class="copiable-link" href='#index-_002eab'> ¶</a></span></dt> +<dd><a class="index-entry-id" id="index-ab"></a> +<a class="index-entry-id" id="index-aborting-_0028ab_0029"></a> +<p>Write any <var class="var">message</var> to the standard error stream (like <code class="code">tm</code>) +and then abort GNU <code class="code">troff</code>; that is, stop processing and terminate +with a failure status. +</p></dd></dl> + +<dl class="first-deffn"> +<dt class="deffn" id="index-_002eex"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.ex</code></strong><a class="copiable-link" href='#index-_002eex'> ¶</a></span></dt> +<dd><a class="index-entry-id" id="index-ex"></a> +<a class="index-entry-id" id="index-ex-request_002c-use-in-debugging"></a> +<a class="index-entry-id" id="index-exiting-_0028ex_0029"></a> +<p>Exit GNU <code class="code">troff</code>; that is, stop processing and terminate with a +successful status. To stop processing only the current file, use the +<code class="code">nx</code> request; see <a class="ref" href="I_002fO.html">I/O</a>. +</p></dd></dl> + +<p>When doing something involved, it is useful to leave the debugging +statements in the code and have them turned on by a command-line flag. +</p> +<div class="example"> +<div class="group"><pre class="example-preformatted">.if \n[DB] .tm debugging output +</pre></div></div> + +<p>To activate such statements, use the <samp class="option">-r</samp> option to set the +register. +</p> +<div class="example"> +<div class="group"><pre class="example-preformatted">groff -rDB=1 <i class="slanted">file</i> +</pre></div></div> + +<p>If it is known in advance that there are many errors and no useful +output, GNU <code class="code">troff</code> can be forced to suppress formatted output with +the <samp class="option">-z</samp> option. +</p> +<dl class="first-deffn"> +<dt class="deffn" id="index-_002epev"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.pev</code></strong><a class="copiable-link" href='#index-_002epev'> ¶</a></span></dt> +<dd><a class="index-entry-id" id="index-pev"></a> +<a class="index-entry-id" id="index-dumping-environments-_0028pev_0029"></a> +<a class="index-entry-id" id="index-environments_002c-dumping-_0028pev_0029"></a> +<p>Report the state of the current environment followed by that of all +other environments to the standard error stream. +</p></dd></dl> + +<dl class="first-deffn"> +<dt class="deffn" id="index-_002epm"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.pm</code></strong><a class="copiable-link" href='#index-_002epm'> ¶</a></span></dt> +<dd><a class="index-entry-id" id="index-pm"></a> +<a class="index-entry-id" id="index-dumping-symbol-table-_0028pm_0029"></a> +<a class="index-entry-id" id="index-symbol-table_002c-dumping-_0028pm_0029"></a> +<p>Report, to the standard error stream, the names of all defined macros, +strings, and diversions with their sizes in bytes. +</p></dd></dl> + +<dl class="first-deffn"> +<dt class="deffn" id="index-_002epnr"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.pnr</code></strong><a class="copiable-link" href='#index-_002epnr'> ¶</a></span></dt> +<dd><a class="index-entry-id" id="index-pnr"></a> +<a class="index-entry-id" id="index-dumping-registers-_0028pnr_0029"></a> +<a class="index-entry-id" id="index-registers_002c-dumping-_0028pnr_0029"></a> +<p>Report the names and contents of all currently defined registers to the +standard error stream. +</p></dd></dl> + +<dl class="first-deffn"> +<dt class="deffn" id="index-_002eptr"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.ptr</code></strong><a class="copiable-link" href='#index-_002eptr'> ¶</a></span></dt> +<dd><a class="index-entry-id" id="index-ptr"></a> +<a class="index-entry-id" id="index-dumping-page-location-traps-_0028ptr_0029"></a> +<a class="index-entry-id" id="index-listing-page-location-traps-_0028ptr_0029"></a> +<a class="index-entry-id" id="index-traps_002c-page-location_002c-dumping-_0028ptr_0029"></a> +<a class="index-entry-id" id="index-traps_002c-page-location_002c-listing-_0028ptr_0029"></a> +<p>Report the names and positions of all page location traps to the +standard error stream. Empty slots in the list, where a trap has been +planted but subsequently (re)moved, are printed as well. +</p></dd></dl> + +<dl class="first-deffn"> +<dt class="deffn" id="index-_002efl"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.fl</code></strong><a class="copiable-link" href='#index-_002efl'> ¶</a></span></dt> +<dd><a class="index-entry-id" id="index-fl"></a> +<a class="index-entry-id" id="index-flush-output-_0028fl_0029"></a> +<a class="index-entry-id" id="index-output_002c-flush-_0028fl_0029"></a> +<a class="index-entry-id" id="index-interactive-use-of-gtroff"></a> +<a class="index-entry-id" id="index-gtroff_002c-interactive-use"></a> +<p>Instruct <code class="code">gtroff</code> to flush its output immediately. The intent is +for interactive use, but this behaviour is currently not implemented in +<code class="code">gtroff</code>. Contrary to Unix <code class="code">troff</code>, TTY output is sent to a +device driver also (<code class="code">grotty</code>), making it non-trivial to communicate +interactively. +</p> +<p>This request causes a line break. +</p></dd></dl> + +<dl class="first-deffn"> +<dt class="deffn" id="index-_002ebacktrace"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.backtrace</code></strong><a class="copiable-link" href='#index-_002ebacktrace'> ¶</a></span></dt> +<dd><a class="index-entry-id" id="index-backtrace"></a> +<a class="index-entry-id" id="index-backtrace-of-input-stack-_0028backtrace_0029"></a> +<a class="index-entry-id" id="index-input-stack_002c-backtrace-_0028backtrace_0029"></a> +<p>Write the state of the input stack to the standard error stream. +</p> +<p>Consider the following in a file <samp class="file">test</samp>. +</p> +<div class="example"> +<div class="group"><pre class="example-preformatted">.de xxx +. backtrace +.. +.de yyy +. xxx +.. +. +.yyy + error→ troff: backtrace: 'test':2: macro 'xxx' + error→ troff: backtrace: 'test':5: macro 'yyy' + error→ troff: backtrace: file 'test':8 +</pre></div></div> + +<p>The <samp class="option">-b</samp> option of GNU <code class="code">troff</code> causes a backtrace to be +generated on each error or warning. Some warnings have to be enabled; +See <a class="xref" href="Warnings.html">Warnings</a>. +</p></dd></dl> + +<dl class="first-deffn"> +<dt class="deffn" id="index-_005cn_005bslimit_005d"><span class="category-def">Register: </span><span><strong class="def-name"><code class="t">\n[slimit]</code></strong><a class="copiable-link" href='#index-_005cn_005bslimit_005d'> ¶</a></span></dt> +<dd><a class="index-entry-id" id="index-slimit"></a> +<a class="index-entry-id" id="index-input-stack_002c-setting-limit"></a> +<p>If greater than 0, sets the maximum quantity of objects on GNU +<code class="code">troff</code>’s internal input stack. If less than or equal to 0, +there is no limit: recursion can continue until program memory is +exhausted. The default is 1,000. +</p></dd></dl> + +<dl class="first-deffn"> +<dt class="deffn" id="index-_002ewarnscale"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.warnscale</code></strong> <var class="def-var-arguments">su</var><a class="copiable-link" href='#index-_002ewarnscale'> ¶</a></span></dt> +<dd><a class="index-entry-id" id="index-warnscale"></a> +<p>Set the scaling unit used in certain warnings to <var class="var">su</var>, which can take the values ‘<samp class="samp">u</samp>’, ‘<samp class="samp">i</samp>’, ‘<samp class="samp">c</samp>’, +‘<samp class="samp">p</samp>’, and ‘<samp class="samp">P</samp>’. The default is ‘<samp class="samp">i</samp>’. +</p></dd></dl> + +<dl class="first-deffn"> +<dt class="deffn" id="index-_002espreadwarn"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.spreadwarn</code></strong> <var class="def-var-arguments">[<span class="r"><i class="slanted">limit</i></span>]</var><a class="copiable-link" href='#index-_002espreadwarn'> ¶</a></span></dt> +<dd><a class="index-entry-id" id="index-spreadwarn"></a> +<p>Emit a <code class="code">break</code> warning if the additional space inserted for each +space between words in an output line adjusted to both margins with +‘<samp class="samp">.ad b</samp>’<!-- /@w --> is larger than or equal to <var class="var">limit</var>. A negative +value is treated as zero; an absent argument toggles the warning on and +off without changing <var class="var">limit</var>. The default scaling unit is ‘<samp class="samp">m</samp>’. +At startup, <code class="code">spreadwarn</code> is inactive and <var class="var">limit</var> is 3<span class="dmn">m</span>. +</p> +<p>For example, +</p> +<div class="example"> +<div class="group"><pre class="example-preformatted">.spreadwarn 0.2m +</pre></div></div> + +<p>causes a warning if <code class="code">break</code> warnings are not suppressed and +<code class="code">gtroff</code> must add 0.2<span class="dmn">m</span> or more for each inter-word space in a +line. See <a class="xref" href="Warnings.html">Warnings</a>. +</p></dd></dl> + +<a class="index-entry-id" id="index-warnings"></a> +<p>GNU <code class="code">troff</code> has command-line options for reporting warnings +(<samp class="option">-w</samp>) and backtraces (<samp class="option">-b</samp>) when a warning or an error +occurs. +</p> +<dl class="first-deffn"> +<dt class="deffn" id="index-_002ewarn"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.warn</code></strong> <var class="def-var-arguments">[<span class="r"><i class="slanted">n</i></span>]</var><a class="copiable-link" href='#index-_002ewarn'> ¶</a></span></dt> +<dd><a class="index-entry-id" id="index-warn"></a> +</dd><dt class="deffnx def-cmd-deffn" id="index-_005cn_005b_002ewarn_005d"><span class="category-def">Register: </span><span><strong class="def-name"><code class="t">\n[.warn]</code></strong><a class="copiable-link" href='#index-_005cn_005b_002ewarn_005d'> ¶</a></span></dt> +<dd><a class="index-entry-id" id="index-_002ewarn-1"></a> +<a class="index-entry-id" id="index-warning-level-_0028warn_0029"></a> +<p>Select the categories, or “types”, of reported warnings. +<var class="var">n</var> is the sum of the numeric codes associated with each +warning category that is to be enabled; all other categories are +disabled. The categories and their associated codes are listed in +<a class="ref" href="Warnings.html">Warnings</a>. For example, ‘<samp class="samp">.warn 0</samp>’ disables all warnings, and +‘<samp class="samp">.warn 1</samp>’ disables all warnings except those about missing glyphs. +If no argument is given, all warning categories are enabled. +</p> +<p>The read-only register <code class="code">.warn</code> contains the sum of the numeric +codes of enabled warning categories. +</p></dd></dl> + + + +<ul class="mini-toc"> +<li><a href="Warnings.html" accesskey="1">Warnings</a></li> +</ul> +</div> +<hr> +<div class="nav-panel"> +<p> +Next: <a href="Implementation-Differences.html">Implementation Differences</a>, Previous: <a href="Gtroff-Internals.html"><code class="code">gtroff</code> Internals</a>, Up: <a href="GNU-troff-Reference.html">GNU <code class="code">troff</code> Reference</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Request-Index.html" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> |