mirror of
https://github.com/ganelson/inform.git
synced 2024-07-08 01:54:21 +03:00
140 lines
16 KiB
HTML
140 lines
16 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/utc' 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 Cross-References</b></li></ul><p class="purpose">Writing the documentation cross-references to a file used by Inform's in-application documentation.</p>
|
|
|
|
<ul class="toc"><li><a href="#SP1">§1. Documentation symbols</a></li><li><a href="#SP2">§2. Cross-references file</a></li><li><a href="#SP3">§3. 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:
|
|
</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. Cross-references file. </b>Until January 2020, Inform managed cross-references to its dcumentation in a
|
|
clumsy way, with explicit 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">in the Standard Rules extension, which correlated "tags" such as <code class="display"><span class="extract">kind_person</span></code>
|
|
with named passages in the documentation; in this way, the compiler learned
|
|
how to annotate its problem messages and Index with links.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">That meant that Indoc had to update the Standard Rules each time it ran, which
|
|
was far from elegant. This has now gone, and instead we write a stand-alone
|
|
"cross-references file" which Inform reads separately from any extensions.
|
|
</p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Updater::write_xrefs_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="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 cross-references file"</span><span class="plain">, </span><span class="identifier">F</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="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="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">"_ 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>
|
|
|
|
<span class="functiontext">Streams::close</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">);</span>
|
|
<span class="plain">}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="endnote">The function Updater::write_xrefs_file is used in 1/mn (<a href="1-mn.html#SP1_4">§1.4</a>).</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP3"></a><b>§3. 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>
|
|
|