mirror of
https://github.com/ganelson/inform.git
synced 2024-07-08 18:14:21 +03:00
156 lines
18 KiB
HTML
156 lines
18 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>Updating the Cross-References</title>
|
|
<meta name="viewport" content="width=device-width initial-scale=1">
|
|
<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>
|
|
<nav role="navigation">
|
|
<h1><a href="../index.html">
|
|
<img src="../docs-src/Figures/Inform.png" height=72">
|
|
</a></h1>
|
|
<ul><li><a href="../compiler.html">compiler tools</a></li>
|
|
<li><a href="../other.html">other tools</a></li>
|
|
<li><a href="../extensions.html">extensions and kits</a></li>
|
|
<li><a href="../units.html">unit test tools</a></li>
|
|
</ul><h2>Other Tools</h2><ul>
|
|
<li><a href="../inblorb/index.html">inblorb</a></li>
|
|
<li><a href="index.html"><span class="selectedlink">indoc</span></a></li>
|
|
<li><a href="../inpolicy/index.html">inpolicy</a></li>
|
|
<li><a href="../inrtps/index.html">inrtps</a></li>
|
|
</ul><h2>Foundation</h2><ul>
|
|
<li><a href="../../../inweb/docs/foundation-module/index.html">foundation</a></li>
|
|
|
|
</ul>
|
|
</nav>
|
|
<main role="main">
|
|
|
|
<!--Weave of 'Updating the Cross-References' generated by 7-->
|
|
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="../other.html">Other Tools</a></li><li><a href="index.html">indoc</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<button class="popup" onclick="togglePopup('usagePopup54')">...<span class="popuptext" id="usagePopup54">Usage of <b>Updater::add_reference_symbol</b>:<br>Rawtext Reader - <a href="2-rr.html#SP4_1_1">§4.1.1</a>, <a href="2-rr.html#SP4_6_2">§4.6.2</a></span></button></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"><a href="3-em.html#SP2">Errors::fatal</a></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"><a href="4-sm.html#SP3">Str::duplicate</a></span><span class="plain">(</span><span class="identifier">symbol_name</span><span class="plain">);</span>
|
|
<span class="functiontext"><a href="3-gi.html#SP5">Indexes::index_notify_of_symbol</a></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="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>
|
|
|
|
<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<button class="popup" onclick="togglePopup('usagePopup55')">...<span class="popuptext" id="usagePopup55">Usage of <b>Updater::write_xrefs_file</b>:<br>Main - <a href="1-mn.html#SP1_4">§1.4</a></span></button></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"><a href="2-str.html#SP24">Streams::open_to_file</a></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"><a href="3-em.html#SP2">Errors::fatal_with_file</a></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"> > </span><span class="constant">0</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">"_ doc%d \"%S\" \"%S\"\n"</span><span class="plain">,</span>
|
|
<span class="identifier">S</span><span class="plain">-></span><span class="element">allocation_id</span><span class="plain"> + </span><span class="constant">1</span><span class="plain">, </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"><a href="2-str.html#SP34">Streams::close</a></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="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<button class="popup" onclick="togglePopup('usagePopup56')">...<span class="popuptext" id="usagePopup56">Usage of <b>Updater::write_definitions_file</b>:<br>Main - <a href="1-mn.html#SP1_4">§1.4</a></span></button></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"><a href="2-str.html#SP24">Streams::open_to_file</a></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"><a href="3-em.html#SP2">Errors::fatal_with_file</a></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="plain">.</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="plain">.</span><span class="element">OUT</span><span class="plain"> = </span><span class="identifier">OUT</span><span class="plain">;</span>
|
|
<span class="functiontext"><a href="4-tf.html#SP5">TextFiles::read</a></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"><a href="#SP3">Updater::definitions_helper</a></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"><a href="2-str.html#SP34">Streams::close</a></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<button class="popup" onclick="togglePopup('usagePopup57')">...<span class="popuptext" id="usagePopup57">Usage of <b>Updater::definitions_helper</b>:<br>none</span></button></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"><a href="4-sm.html#SP23">Str::trim_white_space_at_end</a></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"><a href="4-pm.html#SP9">Regexp::create_mr</a></span><span class="plain">();</span>
|
|
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext"><a href="4-pm.html#SP10">Regexp::match</a></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=*\n"</span><span class="plain">, </span><span class="identifier">mr</span><span class="plain">.</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"><a href="4-pm.html#SP10">Regexp::match</a></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\n"</span><span class="plain">, </span><span class="identifier">line</span><span class="plain">);</span>
|
|
<span class="functiontext"><a href="4-pm.html#SP9">Regexp::dispose_of</a></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 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-->
|
|
<script>
|
|
function togglePopup(material_id) {
|
|
var popup = document.getElementById(material_id);
|
|
popup.classList.toggle("show");
|
|
}
|
|
</script>
|
|
|
|
<link href="Popups.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
</main>
|
|
</body>
|
|
</html>
|
|
|