mirror of
https://github.com/ganelson/inform.git
synced 2024-07-08 10:04:21 +03:00
205 lines
23 KiB
HTML
205 lines
23 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>2/rr</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/utsr' generated by 7-->
|
|
<ul class="crumbs"><li><a href="../webs.html">★</a></li><li><a href="index.html">indoc 4</a></li><li><a href="index.html#2">Chapter 2: Processing</a></li><li><b>Updating the Standard Rules</b></li></ul><p class="purpose">Rewriting the documentation cross-references in the Standard Rules extension, a feature used only for Inform's in-application documentation.</p>
|
|
|
|
<ul class="toc"><li><a href="#SP1">§1. Documentation symbols</a></li><li><a href="#SP2">§2. The Standard Rules</a></li><li><a href="#SP4">§4. Definitions File</a></li></ul><hr class="tocbar">
|
|
|
|
<p class="inwebparagraph"><a id="SP1"></a><b>§1. Documentation symbols. </b>These are non-whitespaced tags, such as <code class="display"><span class="extract">kind_thing</span></code>, which are associated
|
|
with specific numbered files of HTML documentation.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">This hash holds all known references to the Inform documentation provided
|
|
to the Standard Rules:
|
|
</p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Updater::add_reference_symbol</span><span class="plain">(</span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">symbol_name</span><span class="plain">, </span><span class="reserved">volume</span><span class="plain"> *</span><span class="identifier">V</span><span class="plain">, </span><span class="reserved">section</span><span class="plain"> *</span><span class="identifier">S</span><span class="plain">) {</span>
|
|
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">S</span><span class="plain">-</span><span class="element">>no_doc_reference_symbols</span><span class="plain"> >= </span><span class="constant">MAX_DRS_PER_SECTION</span><span class="plain">)</span>
|
|
<span class="functiontext">Errors::fatal</span><span class="plain">(</span><span class="string">"too many documentation reference symbols in this section"</span><span class="plain">);</span>
|
|
<span class="identifier">S</span><span class="plain">-</span><span class="element">>doc_reference_symbols</span><span class="plain">[</span><span class="identifier">S</span><span class="plain">-</span><span class="element">>no_doc_reference_symbols</span><span class="plain">++] = </span><span class="functiontext">Str::duplicate</span><span class="plain">(</span><span class="identifier">symbol_name</span><span class="plain">);</span>
|
|
<span class="functiontext">Indexes::index_notify_of_symbol</span><span class="plain">(</span><span class="identifier">symbol_name</span><span class="plain">, </span><span class="identifier">V</span><span class="plain">, </span><span class="identifier">S</span><span class="plain">);</span>
|
|
<span class="plain">}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="endnote">The function Updater::add_reference_symbol is used in 2/rr (<a href="2-rr.html#SP4_1_1">§4.1.1</a>, <a href="2-rr.html#SP4_6_2">§4.6.2</a>).</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP2"></a><b>§2. The Standard Rules. </b>The following feature is used only in Inform's master build process, that is,
|
|
by me: it updates the Standard Rules source text to reconcile documentation
|
|
references. "Documentation references" are tags such as <code class="display"><span class="extract">kind_person</span></code> (see the
|
|
example rawtext above): the idea is that when the Inform compiler wants to
|
|
compile a link to in-application documentation on, say, the kind "person", it
|
|
refers to the location internally using a tag, in this case <code class="display"><span class="extract">kind_person</span></code>. The
|
|
Standard Rules contain a large number of dull sentences such as:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">Document kind_person at doc45 "3.17" "Men, women and animals".</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">which enable Inform to produce accurate links to the current documentation.
|
|
This insulates the Inform compiler from its manual, and means the manual
|
|
can be heavily rewritten without need to recompile the compiler.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">What we do here is to filter an input file (presumably Inform's Standard Rules)
|
|
looking for a contiguous block of lines in the form
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">Document ... at doc12.</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">We then replace this whole block of lines with a fresh one of our own making,
|
|
which contains up to date information on which documentation symbols occur
|
|
in which files.
|
|
</p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Updater::rewrite_standard_rules_file</span><span class="plain">(</span><span class="reserved">filename</span><span class="plain"> *</span><span class="identifier">F</span><span class="plain">) {</span>
|
|
<span class="identifier">PRINT</span><span class="plain">(</span><span class="string">"indoc: rewriting documentation references in Standard Rules\</span><span class="plain">n</span><span class="string">"</span><span class="plain">);</span>
|
|
<span class="identifier">TEMPORARY_TEXT</span><span class="plain">(</span><span class="identifier">spool</span><span class="plain">);</span>
|
|
<span class="functiontext">TextFiles::read</span><span class="plain">(</span><span class="identifier">F</span><span class="plain">, </span><span class="constant">FALSE</span><span class="plain">, </span><span class="string">"can't open Standard Rules file"</span><span class="plain">,</span>
|
|
<span class="constant">TRUE</span><span class="plain">, </span><span class="functiontext">Updater::rewrite_helper</span><span class="plain">, </span><span class="identifier">NULL</span><span class="plain">, </span><span class="identifier">spool</span><span class="plain">);</span>
|
|
|
|
<span class="reserved">text_stream</span><span class="plain"> </span><span class="identifier">SR</span><span class="plain">;</span>
|
|
<span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">OUT</span><span class="plain"> = &</span><span class="identifier">SR</span><span class="plain">;</span>
|
|
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Streams::open_to_file</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="identifier">F</span><span class="plain">, </span><span class="constant">UTF8_ENC</span><span class="plain">) == </span><span class="constant">FALSE</span><span class="plain">)</span>
|
|
<span class="functiontext">Errors::fatal_with_file</span><span class="plain">(</span><span class="string">"can't write Standard Rules file"</span><span class="plain">, </span><span class="identifier">F</span><span class="plain">);</span>
|
|
|
|
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">first_time</span><span class="plain"> = 0;</span>
|
|
<span class="reserved">for</span><span class="plain"> (</span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">i</span><span class="plain">=0, </span><span class="identifier">L</span><span class="plain">=</span><span class="functiontext">Str::len</span><span class="plain">(</span><span class="identifier">spool</span><span class="plain">); </span><span class="identifier">i</span><span class="plain"><</span><span class="identifier">L</span><span class="plain">; ) {</span>
|
|
<span class="identifier">TEMPORARY_TEXT</span><span class="plain">(</span><span class="identifier">line</span><span class="plain">);</span>
|
|
<span class="reserved">while</span><span class="plain"> (</span><span class="identifier">i</span><span class="plain"><</span><span class="identifier">L</span><span class="plain">) {</span>
|
|
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">c</span><span class="plain"> = </span><span class="functiontext">Str::get_at</span><span class="plain">(</span><span class="identifier">spool</span><span class="plain">, </span><span class="identifier">i</span><span class="plain">++);</span>
|
|
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">c</span><span class="plain"> == </span><span class="character">'\</span><span class="plain">n</span><span class="character">'</span><span class="plain">) </span><span class="reserved">break</span><span class="plain">;</span>
|
|
<span class="identifier">PUT_TO</span><span class="plain">(</span><span class="identifier">line</span><span class="plain">, </span><span class="identifier">c</span><span class="plain">);</span>
|
|
<span class="plain">}</span>
|
|
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Regexp::match</span><span class="plain">(</span><span class="identifier">NULL</span><span class="plain">, </span><span class="identifier">line</span><span class="plain">, </span><span class="identifier">L</span><span class="string">" *Document %c* at doc%d+%c*"</span><span class="plain">)) {</span>
|
|
<span class="reserved">if</span><span class="plain"> (0 == (</span><span class="identifier">first_time</span><span class="plain">++))</span>
|
|
<<span class="cwebmacro">Write a new set of Document sentences to replace the old set</span> <span class="cwebmacronumber">2.1</span>><span class="plain">;</span>
|
|
<span class="plain">} </span><span class="reserved">else</span><span class="plain"> {</span>
|
|
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"%S\</span><span class="plain">n</span><span class="string">"</span><span class="plain">, </span><span class="identifier">line</span><span class="plain">);</span>
|
|
<span class="plain">}</span>
|
|
<span class="identifier">DISCARD_TEXT</span><span class="plain">(</span><span class="identifier">line</span><span class="plain">);</span>
|
|
<span class="plain">}</span>
|
|
<span class="functiontext">Streams::close</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">);</span>
|
|
<span class="identifier">DISCARD_TEXT</span><span class="plain">(</span><span class="identifier">spool</span><span class="plain">);</span>
|
|
<span class="plain">}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="endnote">The function Updater::rewrite_standard_rules_file is used in 1/mn (<a href="1-mn.html#SP1_4">§1.4</a>).</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP2_1"></a><b>§2.1. </b><code class="display">
|
|
<<span class="cwebmacrodefn">Write a new set of Document sentences to replace the old set</span> <span class="cwebmacronumber">2.1</span>> =
|
|
</code></p>
|
|
|
|
|
|
<pre class="displaydefn">
|
|
<span class="reserved">section</span><span class="plain"> *</span><span class="identifier">S</span><span class="plain">;</span>
|
|
<span class="identifier">LOOP_OVER</span><span class="plain">(</span><span class="identifier">S</span><span class="plain">, </span><span class="reserved">section</span><span class="plain">)</span>
|
|
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">S</span><span class="plain">-</span><span class="element">>no_doc_reference_symbols</span><span class="plain"> > 0) {</span>
|
|
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"Document "</span><span class="plain">);</span>
|
|
<span class="reserved">for</span><span class="plain"> (</span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">i</span><span class="plain">=0; </span><span class="identifier">i</span><span class="plain"><</span><span class="identifier">S</span><span class="plain">-</span><span class="element">>no_doc_reference_symbols</span><span class="plain">; </span><span class="identifier">i</span><span class="plain">++)</span>
|
|
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"%S "</span><span class="plain">, </span><span class="identifier">S</span><span class="plain">-</span><span class="element">>doc_reference_symbols</span><span class="plain">[</span><span class="identifier">i</span><span class="plain">]);</span>
|
|
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"at doc%d \</span><span class="plain">"</span><span class="string">%S\</span><span class="plain">"</span><span class="string"> \</span><span class="plain">"</span><span class="string">%S\</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">S</span><span class="plain">-</span><span class="element">>allocation_id</span><span class="plain"> + 1, </span><span class="identifier">S</span><span class="plain">-</span><span class="element">>label</span><span class="plain">, </span><span class="identifier">S</span><span class="plain">-</span><span class="element">>title</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">§2</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP3"></a><b>§3. </b></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Updater::rewrite_helper</span><span class="plain">(</span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">line</span><span class="plain">, </span><span class="reserved">text_file_position</span><span class="plain"> *</span><span class="identifier">tfp</span><span class="plain">, </span><span class="reserved">void</span><span class="plain"> *</span><span class="identifier">v_OUT</span><span class="plain">) {</span>
|
|
<span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">OUT</span><span class="plain"> = (</span><span class="reserved">text_stream</span><span class="plain"> *) </span><span class="identifier">v_OUT</span><span class="plain">;</span>
|
|
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"%S\</span><span class="plain">n</span><span class="string">"</span><span class="plain">, </span><span class="identifier">line</span><span class="plain">);</span>
|
|
<span class="plain">}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="endnote">The function Updater::rewrite_helper is used in <a href="#SP2">§2</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP4"></a><b>§4. Definitions File. </b>When writing HTML documentation to be placed inside the application, we
|
|
also write a one-off file containing all of the phrase definitions, which
|
|
the Inform index-generator can use:
|
|
</p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Updater::write_definitions_file</span><span class="plain">(</span><span class="reserved">void</span><span class="plain">) {</span>
|
|
<span class="reserved">text_stream</span><span class="plain"> </span><span class="identifier">DEFNS</span><span class="plain">;</span>
|
|
<span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">OUT</span><span class="plain"> = &</span><span class="identifier">DEFNS</span><span class="plain">;</span>
|
|
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Streams::open_to_file</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="identifier">indoc_settings</span><span class="plain">-</span><span class="element">>definitions_filename</span><span class="plain">, </span><span class="constant">UTF8_ENC</span><span class="plain">) == </span><span class="constant">FALSE</span><span class="plain">)</span>
|
|
<span class="functiontext">Errors::fatal_with_file</span><span class="plain">(</span><span class="string">"can't write definitions file"</span><span class="plain">, </span><span class="identifier">indoc_settings</span><span class="plain">-</span><span class="element">>definitions_filename</span><span class="plain">);</span>
|
|
<span class="reserved">formatted_file</span><span class="plain"> *</span><span class="identifier">ftd</span><span class="plain">;</span>
|
|
<span class="identifier">LOOP_OVER</span><span class="plain">(</span><span class="identifier">ftd</span><span class="plain">, </span><span class="reserved">formatted_file</span><span class="plain">) {</span>
|
|
<span class="reserved">definitions_helper_state</span><span class="plain"> </span><span class="identifier">dhs</span><span class="plain">;</span>
|
|
<span class="identifier">dhs</span><span class="element">.transcribe</span><span class="plain"> = </span><span class="constant">FALSE</span><span class="plain">;</span>
|
|
<span class="identifier">dhs</span><span class="element">.OUT</span><span class="plain"> = </span><span class="identifier">OUT</span><span class="plain">;</span>
|
|
<span class="functiontext">TextFiles::read</span><span class="plain">(</span><span class="identifier">ftd</span><span class="plain">-</span><span class="element">>name</span><span class="plain">, </span><span class="constant">FALSE</span><span class="plain">, </span><span class="string">"can't reopen written file"</span><span class="plain">,</span>
|
|
<span class="constant">TRUE</span><span class="plain">, </span><span class="functiontext">Updater::definitions_helper</span><span class="plain">, </span><span class="identifier">NULL</span><span class="plain">, &</span><span class="identifier">dhs</span><span class="plain">);</span>
|
|
<span class="plain">}</span>
|
|
|
|
<span class="functiontext">Streams::close</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">);</span>
|
|
<span class="plain">}</span>
|
|
|
|
<span class="reserved">typedef</span><span class="plain"> </span><span class="reserved">struct</span><span class="plain"> </span><span class="reserved">definitions_helper_state</span><span class="plain"> {</span>
|
|
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">transcribe</span><span class="plain">;</span>
|
|
<span class="reserved">struct</span><span class="plain"> </span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">OUT</span><span class="plain">;</span>
|
|
<span class="plain">} </span><span class="reserved">definitions_helper_state</span><span class="plain">;</span>
|
|
|
|
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Updater::definitions_helper</span><span class="plain">(</span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">line</span><span class="plain">, </span><span class="reserved">text_file_position</span><span class="plain"> *</span><span class="identifier">tfp</span><span class="plain">, </span><span class="reserved">void</span><span class="plain"> *</span><span class="identifier">v_dhs</span><span class="plain">) {</span>
|
|
<span class="reserved">definitions_helper_state</span><span class="plain"> *</span><span class="identifier">dhs</span><span class="plain"> = (</span><span class="reserved">definitions_helper_state</span><span class="plain"> *) </span><span class="identifier">v_dhs</span><span class="plain">;</span>
|
|
<span class="functiontext">Str::trim_white_space_at_end</span><span class="plain">(</span><span class="identifier">line</span><span class="plain">);</span>
|
|
<span class="reserved">match_results</span><span class="plain"> </span><span class="identifier">mr</span><span class="plain"> = </span><span class="functiontext">Regexp::create_mr</span><span class="plain">();</span>
|
|
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Regexp::match</span><span class="plain">(&</span><span class="identifier">mr</span><span class="plain">, </span><span class="identifier">line</span><span class="plain">, </span><span class="identifier">L</span><span class="string">" *<!--definition of (%c*?)--%c*"</span><span class="plain">)) {</span>
|
|
<span class="identifier">WRITE_TO</span><span class="plain">(</span><span class="identifier">dhs</span><span class="plain">-</span><span class="element">>OUT</span><span class="plain">, </span><span class="string">"*=%S=*\</span><span class="plain">n</span><span class="string">"</span><span class="plain">, </span><span class="identifier">mr</span><span class="element">.exp</span><span class="plain">[0]);</span>
|
|
<span class="identifier">dhs</span><span class="plain">-</span><span class="element">>transcribe</span><span class="plain"> = </span><span class="constant">TRUE</span><span class="plain">;</span>
|
|
<span class="plain">} </span><span class="reserved">else</span><span class="plain"> </span><span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Regexp::match</span><span class="plain">(&</span><span class="identifier">mr</span><span class="plain">, </span><span class="identifier">line</span><span class="plain">, </span><span class="identifier">L</span><span class="string">" *<!--end definition--%c*"</span><span class="plain">)) {</span>
|
|
<span class="identifier">dhs</span><span class="plain">-</span><span class="element">>transcribe</span><span class="plain"> = </span><span class="constant">FALSE</span><span class="plain">;</span>
|
|
<span class="plain">} </span><span class="reserved">else</span><span class="plain"> </span><span class="reserved">if</span><span class="plain"> (</span><span class="identifier">dhs</span><span class="plain">-</span><span class="element">>transcribe</span><span class="plain">) </span><span class="identifier">WRITE_TO</span><span class="plain">(</span><span class="identifier">dhs</span><span class="plain">-</span><span class="element">>OUT</span><span class="plain">, </span><span class="string">"%S\</span><span class="plain">n</span><span class="string">"</span><span class="plain">, </span><span class="identifier">line</span><span class="plain">);</span>
|
|
<span class="functiontext">Regexp::dispose_of</span><span class="plain">(&</span><span class="identifier">mr</span><span class="plain">);</span>
|
|
<span class="plain">}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="endnote">The function Updater::write_definitions_file is used in 1/mn (<a href="1-mn.html#SP1_4">§1.4</a>).</p>
|
|
|
|
<p class="endnote">The function Updater::definitions_helper appears nowhere else.</p>
|
|
|
|
<p class="endnote">The structure definitions_helper_state is accessed in 2/rr, 2/css and here.</p>
|
|
|
|
<hr class="tocbar">
|
|
<ul class="toc"><li><a href="2-rr.html">Back to 'Rawtext Reader'</a></li><li><a href="2-haj.html">Continue with 'HTML and JavaScript'</a></li></ul><hr class="tocbar">
|
|
<!--End of weave-->
|
|
</body>
|
|
</html>
|
|
|