ifhub/inform7
1
0
Fork 0
mirror of https://github.com/ganelson/inform.git synced 2024-07-08 18:14:21 +03:00
Code Issues Projects Releases Wiki Activity
inform7/docs/core-module/2-up.html
Graham Nelson d8e8d824cc Tidied compilation modules
2019-04-22 15:42:10 +01:00

211 lines
20 KiB
HTML
Raw Blame History

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>1/wel</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="Content-Language" content="en-gb">
<link href="inweb.css" rel="stylesheet" rev="stylesheet" type="text/css">
</head>
<body>
<!--Weave of '2/up' generated by 7-->
<ul class="crumbs"><li><a href="../webs.html">&#9733;</a></li><li><a href="index.html">core</a></li><li><a href="index.html#2">Chapter 2: Bridge to Problems Module</a></li><li><b>Using Problems</b></li></ul><p class="purpose">Interface to the Problems module.</p>
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. </b></p>
<pre class="definitions">
<span class="definitionkeyword">define</span> <span class="constant">REDIRECT_PROBLEM_SOURCE_TO</span><span class="plain"> </span><span class="identifier">pathname_of_project</span>
<span class="definitionkeyword">define</span> <span class="constant">PROBLEMS_HTML_EMITTER</span><span class="plain"> </span><span class="identifier">HTMLFiles::char_out</span>
</pre>
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>Inform tops and tails its output of problem messages, and it also prints
non-problem messages when everything was fine. That all happens here:
</p>
<pre class="definitions">
<span class="definitionkeyword">define</span> <span class="constant">PROBLEMS_INITIAL_REPORTER</span><span class="plain"> </span><span class="functiontext">Problems::Using::start_problems_report</span>
<span class="definitionkeyword">define</span> <span class="constant">PROBLEMS_FINAL_REPORTER</span><span class="plain"> </span><span class="functiontext">Problems::Using::final_report</span>
</pre>
<pre class="display">
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Problems::Using::start_problems_report</span><span class="plain">(</span><span class="reserved">void</span><span class="plain">) {</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">STREAM_OPEN_TO_FILE</span><span class="plain">(</span><span class="identifier">problems_file</span><span class="plain">, </span><span class="identifier">filename_of_report</span><span class="plain">, </span><span class="identifier">UTF8_ENC</span><span class="plain">) == </span><span class="identifier">FALSE</span><span class="plain">)</span>
<span class="identifier">Problems::Fatal::filename_related</span><span class="plain">(</span><span class="string">"Can't open problem log"</span><span class="plain">, </span><span class="identifier">filename_of_report</span><span class="plain">);</span>
<span class="identifier">HTMLFiles::html_header</span><span class="plain">(</span><span class="identifier">problems_file</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"Translating the Source"</span><span class="plain">);</span>
<span class="plain">}</span>
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Problems::Using::final_report</span><span class="plain">(</span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">disaster_struck</span><span class="plain">, </span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">problems_count</span><span class="plain">) {</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">total_words</span><span class="plain"> = 0;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">problem_count</span><span class="plain"> &gt; 0) {</span>
<span class="identifier">Problems::Buffer::redirect_problem_stream</span><span class="plain">(</span><span class="identifier">problems_file</span><span class="plain">);</span>
<span class="identifier">Problems::issue_problem_begin</span><span class="plain">(</span><span class="string">"*"</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">disaster_struck</span><span class="plain">) </span>&lt;<span class="cwebmacro">Issue problem summary for an internal error</span> <span class="cwebmacronumber">2.1</span>&gt;
<span class="reserved">else</span><span class="plain"> </span>&lt;<span class="cwebmacro">Issue problem summary for a run with problem messages</span> <span class="cwebmacronumber">2.2</span>&gt;<span class="plain">;</span>
<span class="identifier">Problems::issue_problem_end</span><span class="plain">();</span>
<span class="identifier">Problems::Buffer::redirect_problem_stream</span><span class="plain">(</span><span class="identifier">NULL</span><span class="plain">);</span>
<span class="plain">} </span><span class="reserved">else</span><span class="plain"> {</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">rooms</span><span class="plain"> = 0, </span><span class="identifier">things</span><span class="plain"> = 0;</span>
<span class="identifier">HTMLFiles::html_outcome_image</span><span class="plain">(</span><span class="identifier">problems_file</span><span class="plain">, </span><span class="string">"ni_succeeded"</span><span class="plain">, </span><span class="string">"Succeeded"</span><span class="plain">);</span>
<span class="plain">#</span><span class="identifier">ifdef</span><span class="plain"> </span><span class="identifier">IF_MODULE</span>
<span class="identifier">PL::Spatial::get_world_size</span><span class="plain">(&amp;</span><span class="identifier">rooms</span><span class="plain">, &amp;</span><span class="identifier">things</span><span class="plain">);</span>
<span class="plain">#</span><span class="identifier">endif</span>
<span class="identifier">Problems::quote_number</span><span class="plain">(1, &amp;</span><span class="identifier">rooms</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">rooms</span><span class="plain"> == 1) </span><span class="identifier">Problems::quote_text</span><span class="plain">(2, </span><span class="string">"room"</span><span class="plain">); </span><span class="reserved">else</span><span class="plain"> </span><span class="identifier">Problems::quote_text</span><span class="plain">(2, </span><span class="string">"rooms"</span><span class="plain">);</span>
<span class="identifier">Problems::quote_number</span><span class="plain">(3, &amp;</span><span class="identifier">things</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">things</span><span class="plain"> == 1) </span><span class="identifier">Problems::quote_text</span><span class="plain">(4, </span><span class="string">"thing"</span><span class="plain">); </span><span class="reserved">else</span><span class="plain"> </span><span class="identifier">Problems::quote_text</span><span class="plain">(4, </span><span class="string">"things"</span><span class="plain">);</span>
<span class="identifier">total_words</span><span class="plain"> = </span><span class="identifier">TextFromFiles::total_word_count</span><span class="plain">(</span><span class="identifier">FIRST_OBJECT</span><span class="plain">(</span><span class="identifier">source_file</span><span class="plain">));</span>
<span class="identifier">Problems::quote_number</span><span class="plain">(5, &amp;</span><span class="identifier">total_words</span><span class="plain">);</span>
&lt;<span class="cwebmacro">Issue problem summaries for a run without problems</span> <span class="cwebmacronumber">2.3</span>&gt;<span class="plain">;</span>
<span class="plain">}</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The function Problems::Using::start_problems_report appears nowhere else.</p>
<p class="endnote">The function Problems::Using::final_report appears nowhere else.</p>
<p class="inwebparagraph"><a id="SP2_1"></a><b>&#167;2.1. </b>One of the slightly annoying things about internal errors is that Inform's
users persistently refer to them as "crashes" on bug report forms. I mean,
the effort we go to! They are entirely clean exits from the program! The
ingratitude of some &mdash; oh, all right.
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Issue problem summary for an internal error</span> <span class="cwebmacronumber">2.1</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="identifier">Problems::issue_problem_segment</span><span class="plain">(</span>
<span class="string">"What has happened here is that one of the checks Inform carries "</span>
<span class="string">"out internally, to see if it is working properly, has failed. "</span>
<span class="string">"There must be a bug in this copy of Inform. It may be worth "</span>
<span class="string">"checking whether you have the current, up-to-date version. "</span>
<span class="string">"If so, please report this problem via www.inform7.com/bugs. %P"</span>
<span class="string">"As for fixing your source text to avoid this bug, the last thing "</span>
<span class="string">"you changed is probably the cause, if there is a simple cause. "</span>
<span class="string">"Your source text might in fact be wrong, and the problem might be "</span>
<span class="string">"occurring because Inform has failed to find a good way to say so. "</span>
<span class="string">"But even if your source text looks correct, there are "</span>
<span class="string">"probably rephrasings which would achieve the same effect."</span><span class="plain">);</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP2">&#167;2</a>.</p>
<p class="inwebparagraph"><a id="SP2_2"></a><b>&#167;2.2. </b>Singular and plural versions of the same message, really:
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Issue problem summary for a run with problem messages</span> <span class="cwebmacronumber">2.2</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">problem_count</span><span class="plain"> == 1)</span>
<span class="identifier">Problems::issue_problem_segment</span><span class="plain">(</span>
<span class="string">"Because of this problem, the source could not be translated "</span>
<span class="string">"into a working game. (Correct the source text to "</span>
<span class="string">"remove the difficulty and click on Go once again.)"</span><span class="plain">);</span>
<span class="reserved">else</span>
<span class="identifier">Problems::issue_problem_segment</span><span class="plain">(</span>
<span class="string">"Problems occurring in translation prevented the game "</span>
<span class="string">"from being properly created. (Correct the source text to "</span>
<span class="string">"remove these problems and click on Go once again.)"</span><span class="plain">);</span>
<span class="identifier">HTMLFiles::outcome_image_tail</span><span class="plain">(</span><span class="identifier">problems_file</span><span class="plain">);</span>
<span class="identifier">text_stream</span><span class="plain"> *</span><span class="identifier">STATUS</span><span class="plain"> = </span><span class="functiontext">ProgressBar::begin_outcome</span><span class="plain">();</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">STATUS</span><span class="plain">) {</span>
<span class="identifier">WRITE_TO</span><span class="plain">(</span><span class="identifier">STATUS</span><span class="plain">, </span><span class="string">"Translation failed: %d problem%s found"</span><span class="plain">,</span>
<span class="identifier">problem_count</span><span class="plain">, (</span><span class="identifier">problem_count</span><span class="plain">==1)?</span><span class="string">""</span><span class="plain">:</span><span class="string">"s"</span><span class="plain">);</span>
<span class="functiontext">ProgressBar::end_outcome</span><span class="plain">();</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP2">&#167;2</a>.</p>
<p class="inwebparagraph"><a id="SP2_3"></a><b>&#167;2.3. </b>The success message needs to take different forms in <code class="display"><span class="extract">stdout</span></code> and in
the Problems log file. In the latter, we write as though the subsequent
conversion of Inform's output to a story file via Inform 6 had already been
completed successfully &mdash; this is because the Problems log is intended
to be viewed inside the Inform application, which will instead divert to
an error page if I6 should fail. So although the Problems file contains
an unwarranted claim, if not an actual falsehood, no human eye should see
it unless and until it comes true.
</p>
<p class="inwebparagraph">We don't want to make similar claims on <code class="display"><span class="extract">stdout</span></code>, where the user &mdash; who
might well not be running in the Inform application, but only on the
command line &mdash; deserves the truth.
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Issue problem summaries for a run without problems</span> <span class="cwebmacronumber">2.3</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="identifier">Problems::Buffer::redirect_problem_stream</span><span class="plain">(</span><span class="identifier">problems_file</span><span class="plain">);</span>
<span class="identifier">text_stream</span><span class="plain"> *</span><span class="identifier">OUT</span><span class="plain"> = </span><span class="identifier">problems_file</span><span class="plain">;</span>
<span class="identifier">HTML_OPEN</span><span class="plain">(</span><span class="string">"p"</span><span class="plain">);</span>
<span class="identifier">Problems::issue_problem_begin</span><span class="plain">(</span><span class="string">"**"</span><span class="plain">);</span>
<span class="identifier">Problems::issue_problem_segment</span><span class="plain">(</span>
<span class="string">"The %5-word source text has successfully been translated "</span>
<span class="string">"into a world with %1 %2 and %3 %4, and the index has been "</span>
<span class="string">"brought up to date."</span><span class="plain">);</span>
<span class="identifier">Problems::issue_problem_end</span><span class="plain">();</span>
<span class="identifier">HTMLFiles::outcome_image_tail</span><span class="plain">(</span><span class="identifier">problems_file</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">telemetry_recording</span><span class="plain">) {</span>
<span class="identifier">Telemetry::ensure_telemetry_file</span><span class="plain">();</span>
<span class="identifier">Problems::Buffer::redirect_problem_stream</span><span class="plain">(</span><span class="identifier">telmy</span><span class="plain">);</span>
<span class="identifier">Problems::issue_problem_begin</span><span class="plain">(</span><span class="string">"**"</span><span class="plain">);</span>
<span class="identifier">Problems::issue_problem_segment</span><span class="plain">(</span>
<span class="string">"The %5-word source text has successfully been translated "</span>
<span class="string">"into a world with %1 %2 and %3 %4, and the index has been "</span>
<span class="string">"brought up to date."</span><span class="plain">);</span>
<span class="identifier">Problems::issue_problem_end</span><span class="plain">();</span>
<span class="identifier">WRITE_TO</span><span class="plain">(</span><span class="identifier">telmy</span><span class="plain">, </span><span class="string">"\</span><span class="plain">n</span><span class="string">"</span><span class="plain">);</span>
<span class="plain">}</span>
<span class="identifier">Problems::Buffer::redirect_problem_stream</span><span class="plain">(</span><span class="identifier">STDOUT</span><span class="plain">);</span>
<span class="identifier">WRITE_TO</span><span class="plain">(</span><span class="identifier">STDOUT</span><span class="plain">, </span><span class="string">"\</span><span class="plain">n</span><span class="string">"</span><span class="plain">);</span>
<span class="identifier">Problems::issue_problem_begin</span><span class="plain">(</span><span class="string">"**"</span><span class="plain">);</span>
<span class="identifier">Problems::issue_problem_segment</span><span class="plain">(</span>
<span class="string">"The %5-word source text has successfully been translated "</span>
<span class="string">"into an intermediate description which can be run through "</span>
<span class="string">"Inform 6 to complete compilation. There were %1 %2 and %3 %4."</span><span class="plain">);</span>
<span class="identifier">Problems::issue_problem_end</span><span class="plain">();</span>
<span class="identifier">STREAM_FLUSH</span><span class="plain">(</span><span class="identifier">STDOUT</span><span class="plain">);</span>
<span class="identifier">Problems::Buffer::redirect_problem_stream</span><span class="plain">(</span><span class="identifier">NULL</span><span class="plain">);</span>
<span class="functiontext">ProgressBar::final_state_of_progress_bar</span><span class="plain">();</span>
<span class="identifier">text_stream</span><span class="plain"> *</span><span class="identifier">STATUS</span><span class="plain"> = </span><span class="functiontext">ProgressBar::begin_outcome</span><span class="plain">();</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">STATUS</span><span class="plain">) {</span>
<span class="identifier">WRITE_TO</span><span class="plain">(</span><span class="identifier">STATUS</span><span class="plain">, </span><span class="string">"Translation succeeded: %d room%s, %d thing%s"</span><span class="plain">,</span>
<span class="identifier">rooms</span><span class="plain">, (</span><span class="identifier">rooms</span><span class="plain">==1)?</span><span class="string">""</span><span class="plain">:</span><span class="string">"s"</span><span class="plain">,</span>
<span class="identifier">things</span><span class="plain">, (</span><span class="identifier">things</span><span class="plain">==1)?</span><span class="string">""</span><span class="plain">:</span><span class="string">"s"</span><span class="plain">);</span>
<span class="functiontext">ProgressBar::end_outcome</span><span class="plain">();</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP2">&#167;2</a>.</p>
<hr class="tocbar">
<ul class="toc"><li><i>(This section begins Chapter 2: Bridge to Problems Module.)</i></li><li><a href="2-sq.html">Continue with 'Supplementary Quotes'</a></li></ul><hr class="tocbar">
<!--End of weave-->
</body>
</html>
Reference in a new issue View git blame Copy permalink