ifhub/inform7
1
0
Fork 0
mirror of https://github.com/ganelson/inform.git synced 2024-06-26 04:00:43 +03:00
Code Issues Projects Releases Wiki Activity

More on extension documentation examples

Browse source
This commit is contained in:
Graham Nelson 2023-07-21 11:49:36 +01:00
parent 1b3d40d592
commit f0ed01994d
36 changed files with 810 additions and 306 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
README.md
View file

@ -1,6 +1,6 @@
# Inform 7
[Version](notes/versioning.md): 10.2.0-beta+6W86 'Krypton' (19 July 2023)
[Version](notes/versioning.md): 10.2.0-beta+6W87 'Krypton' (21 July 2023)
## About Inform

4
build.txt
View file

@ -1,3 +1,3 @@
Prerelease: beta
Build Date: 19 July 2023
Build Number: 6W86
Build Date: 21 July 2023
Build Number: 6W87

2
docs/supervisor-module/1-ic.html
View file

@ -638,7 +638,7 @@ nests, respectively.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">shared_nest_list</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax"> *</span><span class="function-syntax">Supervisor::internal</span><button class="popup" onclick="togglePopup('usagePopup11')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup11">Usage of <span class="code-font"><span class="function-syntax">Supervisor::internal</span></span>:<br/>Project Services - <a href="5-ps2.html#SP39">&#167;39</a><br/>Extensions Index Page - <a href="7-eip.html#SP1_1">&#167;1.1</a><br/>Documentation Compiler - <a href="7-dc.html#SP4">&#167;4</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax"> *</span><span class="function-syntax">Supervisor::internal</span><button class="popup" onclick="togglePopup('usagePopup11')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup11">Usage of <span class="code-font"><span class="function-syntax">Supervisor::internal</span></span>:<br/>Project Services - <a href="5-ps2.html#SP39">&#167;39</a><br/>Extensions Index Page - <a href="7-eip.html#SP1_1">&#167;1.1</a><br/>Documentation Compiler - <a href="7-dc.html#SP7">&#167;7</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">RUN_ONLY_FROM_PHASE</span><span class="plain-syntax">(</span><span class="constant-syntax">NESTED_INBUILD_PHASE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">shared_internal_nest</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>

2
docs/supervisor-module/1-sm.html
View file

@ -106,6 +106,7 @@ which use this module:
<span class="definition-keyword">enum</span> <span class="constant-syntax">inform_template_CLASS</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">kit_configuration_CLASS</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">kit_dependency_CLASS</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">satellite_test_case_CLASS</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">DECLARE_CLASS</span><span class="plain-syntax">(</span><span class="reserved-syntax">build_methodology</span><span class="plain-syntax">)</span>
@ -145,6 +146,7 @@ which use this module:
<span class="identifier-syntax">DECLARE_CLASS</span><span class="plain-syntax">(</span><span class="reserved-syntax">inform_template</span><span class="plain-syntax">)</span>
<span class="identifier-syntax">DECLARE_CLASS</span><span class="plain-syntax">(</span><span class="reserved-syntax">kit_configuration</span><span class="plain-syntax">)</span>
<span class="identifier-syntax">DECLARE_CLASS</span><span class="plain-syntax">(</span><span class="reserved-syntax">kit_dependency</span><span class="plain-syntax">)</span>
<span class="identifier-syntax">DECLARE_CLASS</span><span class="plain-syntax">(</span><span class="reserved-syntax">satellite_test_case</span><span class="plain-syntax">)</span>
</pre>
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>&#167;3. </b>Like all modules, this one must define a <span class="extract"><span class="extract-syntax">start</span></span> and <span class="extract"><span class="extract-syntax">end</span></span> function:
</p>

2
docs/supervisor-module/2-nst.html
View file

@ -151,7 +151,7 @@ can't install to a read-only nest.
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>&#167;5. </b></p>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="function-syntax">Nests::get_location</span><button class="popup" onclick="togglePopup('usagePopup9')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup9">Usage of <span class="code-font"><span class="function-syntax">Nests::get_location</span></span>:<br/>Inbuild Control - <a href="1-ic.html#SP15">&#167;15</a><br/>Extensions Index Page - <a href="7-eip.html#SP1_2_1">&#167;1.2.1</a><br/>Documentation Compiler - <a href="7-dc.html#SP4">&#167;4</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax"> *</span><span class="identifier-syntax">N</span><span class="plain-syntax">) {</span>
<span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="function-syntax">Nests::get_location</span><button class="popup" onclick="togglePopup('usagePopup9')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup9">Usage of <span class="code-font"><span class="function-syntax">Nests::get_location</span></span>:<br/>Inbuild Control - <a href="1-ic.html#SP15">&#167;15</a><br/>Extensions Index Page - <a href="7-eip.html#SP1_2_1">&#167;1.2.1</a><br/>Documentation Compiler - <a href="7-dc.html#SP7">&#167;7</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax"> *</span><span class="identifier-syntax">N</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">N</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">N</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">location</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>

2
docs/supervisor-module/2-rqr.html
View file

@ -243,7 +243,7 @@ a requirement, then so will all other copies of it.
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">Requirements::meets</span><button class="popup" onclick="togglePopup('usagePopup8')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup8">Usage of <span class="code-font"><span class="function-syntax">Requirements::meets</span></span>:<br/>Extension Manager - <a href="4-em.html#SP6">&#167;6</a><br/>Extension Bundle Manager - <a href="4-ebm.html#SP6">&#167;6</a><br/>Kit Manager - <a href="4-km.html#SP7">&#167;7</a><br/>Language Manager - <a href="4-lm.html#SP5">&#167;5</a><br/>Pipeline Manager - <a href="4-pm.html#SP5">&#167;5</a><br/>Template Manager - <a href="4-tm.html#SP5">&#167;5</a><br/>Extension Services - <a href="5-es.html#SP22">&#167;22</a><br/>Kit Services - <a href="5-ks.html#SP15">&#167;15</a><br/>Inclusions - <a href="6-inc.html#SP6">&#167;6</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inbuild_edition</span><span class="plain-syntax"> *</span><span class="identifier-syntax">edition</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_requirement</span><span class="plain-syntax"> *</span><span class="identifier-syntax">req</span><span class="plain-syntax">) {</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">Requirements::meets</span><button class="popup" onclick="togglePopup('usagePopup8')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup8">Usage of <span class="code-font"><span class="function-syntax">Requirements::meets</span></span>:<br/>Extension Manager - <a href="4-em.html#SP6">&#167;6</a><br/>Extension Bundle Manager - <a href="4-ebm.html#SP6">&#167;6</a><br/>Kit Manager - <a href="4-km.html#SP7">&#167;7</a><br/>Language Manager - <a href="4-lm.html#SP5">&#167;5</a><br/>Pipeline Manager - <a href="4-pm.html#SP5">&#167;5</a><br/>Template Manager - <a href="4-tm.html#SP5">&#167;5</a><br/>Extension Services - <a href="5-es.html#SP21">&#167;21</a><br/>Kit Services - <a href="5-ks.html#SP15">&#167;15</a><br/>Inclusions - <a href="6-inc.html#SP6">&#167;6</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inbuild_edition</span><span class="plain-syntax"> *</span><span class="identifier-syntax">edition</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_requirement</span><span class="plain-syntax"> *</span><span class="identifier-syntax">req</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">req</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">req</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">work</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">req</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">work</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">genre</span><span class="plain-syntax">)</span>

6
docs/supervisor-module/4-ebm.html
View file

@ -135,7 +135,7 @@ which stores data about extensions used by the Inform compiler.
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::get</span><span class="plain-syntax">(</span><span class="identifier-syntax">pos</span><span class="plain-syntax">) == </span><span class="character-syntax">'.'</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Str::put</span><span class="plain-syntax">(</span><span class="identifier-syntax">pos</span><span class="plain-syntax">, </span><span class="character-syntax">'_'</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">new_name</span><span class="plain-syntax">, </span><span class="string-syntax">"%S-v%S.i7xd"</span><span class="plain-syntax">, </span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">edition</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">work</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">title</span><span class="plain-syntax">, </span><span class="identifier-syntax">new_version</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="5-es.html#SP23" class="function-link"><span class="function-syntax">Extensions::rename_directory</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">new_name</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="5-es.html#SP22" class="function-link"><span class="function-syntax">Extensions::rename_directory</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">new_name</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Str::clear</span><span class="plain-syntax">(</span><span class="identifier-syntax">key</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">key</span><span class="plain-syntax">, </span><span class="string-syntax">"%p"</span><span class="plain-syntax">, </span><span class="identifier-syntax">P</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">apparent_V</span><span class="plain-syntax"> = </span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">edition</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">version</span><span class="plain-syntax">;</span>
@ -408,7 +408,7 @@ copy name.
<span class="plain-syntax"> </span><span class="identifier-syntax">Str::delete_last_character</span><span class="plain-syntax">(</span><span class="identifier-syntax">subdir</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::eq</span><span class="plain-syntax">(</span><span class="identifier-syntax">subdir</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Examples"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> ;</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::eq</span><span class="plain-syntax">(</span><span class="identifier-syntax">subdir</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Images"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::eq</span><span class="plain-syntax">(</span><span class="identifier-syntax">subdir</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Tests"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> ;</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">error_text</span><span class="plain-syntax">)</span>
@ -549,7 +549,7 @@ directory, we need to <span class="extract"><span class="extract-syntax">rsync</
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">ExtensionBundleManager::document</span><button class="popup" onclick="togglePopup('usagePopup12')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup12">Usage of <span class="code-font"><span class="function-syntax">ExtensionBundleManager::document</span></span>:<br/><a href="4-ebm.html#SP1">&#167;1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">gen</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_copy</span><span class="plain-syntax"> *</span><span class="identifier-syntax">C</span><span class="plain-syntax">, </span><span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">dest</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><a href="5-es.html#SP13" class="function-link"><span class="function-syntax">Extensions::document</span></a><span class="plain-syntax">(</span><a href="5-es.html#SP4" class="function-link"><span class="function-syntax">Extensions::from_copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">C</span><span class="plain-syntax">), </span><span class="identifier-syntax">dest</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="5-es.html#SP12" class="function-link"><span class="function-syntax">Extensions::document</span></a><span class="plain-syntax">(</span><a href="5-es.html#SP4" class="function-link"><span class="function-syntax">Extensions::from_copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">C</span><span class="plain-syntax">), </span><span class="identifier-syntax">dest</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<nav role="progress"><div class="progresscontainer">

2
docs/supervisor-module/4-em.html
View file

@ -325,7 +325,7 @@ the current VM settings.
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">ExtensionManager::document</span><button class="popup" onclick="togglePopup('usagePopup12')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup12">Usage of <span class="code-font"><span class="function-syntax">ExtensionManager::document</span></span>:<br/><a href="4-em.html#SP2">&#167;2</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">gen</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_copy</span><span class="plain-syntax"> *</span><span class="identifier-syntax">C</span><span class="plain-syntax">, </span><span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">dest</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><a href="5-es.html#SP13" class="function-link"><span class="function-syntax">Extensions::document</span></a><span class="plain-syntax">(</span><a href="5-es.html#SP4" class="function-link"><span class="function-syntax">Extensions::from_copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">C</span><span class="plain-syntax">), </span><span class="identifier-syntax">dest</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="5-es.html#SP12" class="function-link"><span class="function-syntax">Extensions::document</span></a><span class="plain-syntax">(</span><a href="5-es.html#SP4" class="function-link"><span class="function-syntax">Extensions::from_copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">C</span><span class="plain-syntax">), </span><span class="identifier-syntax">dest</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<nav role="progress"><div class="progresscontainer">

76
docs/supervisor-module/5-es.html
View file

@ -59,7 +59,7 @@ function togglePopup(material_id) {
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="../inbuildn.html">Inbuild Modules</a></li><li><a href="index.html">supervisor</a></li><li><a href="index.html#5">Chapter 5: Genre Services</a></li><li><b>Extension Services</b></li></ul></div>
<p class="purpose">Behaviour specific to copies of the extension genre.</p>
<ul class="toc"><li><a href="5-es.html#SP1">&#167;1. Scanning metadata</a></li><li><a href="5-es.html#SP5">&#167;5. Cached metadata</a></li><li><a href="5-es.html#SP6">&#167;6. Search list</a></li><li><a href="5-es.html#SP8">&#167;8. Language element activation</a></li><li><a href="5-es.html#SP9">&#167;9. Graph</a></li><li><a href="5-es.html#SP10">&#167;10. Read source text</a></li><li><a href="5-es.html#SP15">&#167;15. Miscellaneous</a></li><li><a href="5-es.html#SP21">&#167;21. Version requirements</a></li><li><a href="5-es.html#SP23">&#167;23. File hierarchy tidying</a></li></ul><hr class="tocbar">
<ul class="toc"><li><a href="5-es.html#SP1">&#167;1. Scanning metadata</a></li><li><a href="5-es.html#SP5">&#167;5. Cached metadata</a></li><li><a href="5-es.html#SP6">&#167;6. Search list</a></li><li><a href="5-es.html#SP8">&#167;8. Language element activation</a></li><li><a href="5-es.html#SP9">&#167;9. Graph</a></li><li><a href="5-es.html#SP10">&#167;10. Read source text</a></li><li><a href="5-es.html#SP14">&#167;14. Miscellaneous</a></li><li><a href="5-es.html#SP20">&#167;20. Version requirements</a></li><li><a href="5-es.html#SP22">&#167;22. File hierarchy tidying</a></li></ul><hr class="tocbar">
<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>&#167;1. Scanning metadata. </b>An extension has a title and an author name, each of which is limited in
length to one character less than the following constants:
@ -194,7 +194,7 @@ alone, and the version number is returned.
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::ne_insensitive</span><span class="plain-syntax">(</span><span class="identifier-syntax">correct_leafname</span><span class="plain-syntax">, </span><span class="identifier-syntax">Filenames::get_leafname</span><span class="plain-syntax">(</span><span class="identifier-syntax">extension_source_filename</span><span class="plain-syntax">))) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">allow</span><span class="plain-syntax"> = </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">repair_mode</span><span class="plain-syntax">) &amp;&amp;</span>
<span class="plain-syntax"> (</span><a href="5-es.html#SP23" class="function-link"><span class="function-syntax">Extensions::rename_file</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">extension_source_filename</span><span class="plain-syntax">, </span><span class="identifier-syntax">correct_leafname</span><span class="plain-syntax">)))</span>
<span class="plain-syntax"> (</span><a href="5-es.html#SP22" class="function-link"><span class="function-syntax">Extensions::rename_file</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">extension_source_filename</span><span class="plain-syntax">, </span><span class="identifier-syntax">correct_leafname</span><span class="plain-syntax">)))</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">allow</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">allow</span><span class="plain-syntax"> == </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">error_text</span><span class="plain-syntax">)</span>
@ -731,7 +731,7 @@ in a minimal sort of way, with just an <span class="extract"><span class="extrac
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="function-syntax">Extensions::from_copy</span><button class="popup" onclick="togglePopup('usagePopup3')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup3">Usage of <span class="code-font"><span class="function-syntax">Extensions::from_copy</span></span>:<br/><a href="5-es.html#SP14">&#167;14</a><br/>Extension Manager - <a href="4-em.html#SP10">&#167;10</a><br/>Extension Bundle Manager - <a href="4-ebm.html#SP9">&#167;9</a><br/>Language Services - <a href="5-ls.html#SP10">&#167;10</a><br/>Project Services - <a href="5-ps2.html#SP35">&#167;35</a><br/>Source Text - <a href="6-st.html#SP13">&#167;13</a><br/>Inclusions - <a href="6-inc.html#SP6_1">&#167;6.1</a><br/>The Mini-Website - <a href="7-tm.html#SP2">&#167;2</a><br/>Extensions Index Page - <a href="7-eip.html#SP1_2_2_4_4_1">&#167;1.2.2.4.4.1</a>, <a href="7-eip.html#SP1_2_2_4_4_4">&#167;1.2.2.4.4.4</a>, <a href="7-eip.html#SP1_2_2_4_5">&#167;1.2.2.4.5</a>, <a href="7-eip.html#SP7">&#167;7</a><br/>The Installer - <a href="7-ti.html#SP2_4_1">&#167;2.4.1</a>, <a href="7-ti.html#SP2_4_2">&#167;2.4.2</a>, <a href="7-ti.html#SP2_4_2_1">&#167;2.4.2.1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inbuild_copy</span><span class="plain-syntax"> *</span><span class="identifier-syntax">C</span><span class="plain-syntax">) {</span>
<span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="function-syntax">Extensions::from_copy</span><button class="popup" onclick="togglePopup('usagePopup3')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup3">Usage of <span class="code-font"><span class="function-syntax">Extensions::from_copy</span></span>:<br/><a href="5-es.html#SP13">&#167;13</a><br/>Extension Manager - <a href="4-em.html#SP10">&#167;10</a><br/>Extension Bundle Manager - <a href="4-ebm.html#SP9">&#167;9</a><br/>Language Services - <a href="5-ls.html#SP10">&#167;10</a><br/>Project Services - <a href="5-ps2.html#SP35">&#167;35</a><br/>Source Text - <a href="6-st.html#SP13">&#167;13</a><br/>Inclusions - <a href="6-inc.html#SP6_1">&#167;6.1</a><br/>The Mini-Website - <a href="7-tm.html#SP2">&#167;2</a><br/>Extensions Index Page - <a href="7-eip.html#SP1_2_2_4_4_1">&#167;1.2.2.4.4.1</a>, <a href="7-eip.html#SP1_2_2_4_4_4">&#167;1.2.2.4.4.4</a>, <a href="7-eip.html#SP1_2_2_4_5">&#167;1.2.2.4.5</a>, <a href="7-eip.html#SP7">&#167;7</a><br/>The Installer - <a href="7-ti.html#SP2_4_1">&#167;2.4.1</a>, <a href="7-ti.html#SP2_4_2">&#167;2.4.2</a>, <a href="7-ti.html#SP2_4_2_1">&#167;2.4.2.1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inbuild_copy</span><span class="plain-syntax"> *</span><span class="identifier-syntax">C</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ext</span><span class="plain-syntax"> = </span><a href="4-ebm.html#SP3" class="function-link"><span class="function-syntax">ExtensionBundleManager::from_copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">C</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">ext</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="identifier-syntax">ext</span><span class="plain-syntax"> = </span><a href="4-em.html#SP4" class="function-link"><span class="function-syntax">ExtensionManager::from_copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">C</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">ext</span><span class="plain-syntax">;</span>
@ -955,9 +955,9 @@ This is that time.
<span class="plain-syntax"> </span><span class="identifier-syntax">SVEXPLAIN</span><span class="plain-syntax">(1, </span><span class="string-syntax">"(from %f)\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">synopsis</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">read_into_file</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">documentation</span><span class="plain-syntax"> =</span>
<span class="plain-syntax"> </span><a href="7-dc.html#SP3" class="function-link"><span class="function-syntax">DocumentationCompiler::compile</span></a><span class="plain-syntax">(</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TextFromFiles::torn_off_documentation</span><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">read_into_file</span><span class="plain-syntax">), </span><span class="identifier-syntax">E</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">doc</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TextFromFiles::torn_off_documentation</span><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">read_into_file</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">doc</span><span class="plain-syntax">) &gt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">documentation</span><span class="plain-syntax"> = </span><a href="7-dc.html#SP6" class="function-link"><span class="function-syntax">DocumentationCompiler::compile</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">doc</span><span class="plain-syntax">, </span><span class="identifier-syntax">E</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">documentation</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">read_into_file</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">your_ref</span><span class="plain-syntax"> = </span><span class="identifier-syntax">STORE_POINTER_inbuild_copy</span><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_copy</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="5-es.html#SP10_2" class="named-paragraph-link"><span class="named-paragraph">Break the text into sentences</span><span class="named-paragraph-number">10.2</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">body_text_unbroken</span><span class="plain-syntax"> = </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
@ -1015,65 +1015,51 @@ then its sentences will go to the extension's own tree.
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">compiled_documentation</span><span class="plain-syntax"> *</span><span class="function-syntax">Extensions::get_documentation</span><button class="popup" onclick="togglePopup('usagePopup14')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup14">Usage of <span class="code-font"><span class="function-syntax">Extensions::get_documentation</span></span>:<br/><a href="5-es.html#SP13">&#167;13</a><br/>The Mini-Website - <a href="7-tm.html#SP7">&#167;7</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax">) {</span>
<span class="reserved-syntax">compiled_documentation</span><span class="plain-syntax"> *</span><span class="function-syntax">Extensions::get_documentation</span><button class="popup" onclick="togglePopup('usagePopup14')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup14">Usage of <span class="code-font"><span class="function-syntax">Extensions::get_documentation</span></span>:<br/><a href="5-es.html#SP12">&#167;12</a><br/>The Mini-Website - <a href="7-tm.html#SP7">&#167;7</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">E</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><a href="2-cps.html#SP7" class="function-link"><span class="function-syntax">Copies::get_source_text</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_copy</span><span class="plain-syntax">); </span><span class="comment-syntax"> in the unlikely event this has not happened yet</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">documentation_sought</span><span class="plain-syntax"> == </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_copy</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">location_if_path</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">D</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Pathnames::down</span><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_copy</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">location_if_path</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Documentation"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Filenames::in</span><span class="plain-syntax">(</span><span class="identifier-syntax">D</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Documentation.txt"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">TextFiles::exists</span><span class="plain-syntax">(</span><span class="identifier-syntax">F</span><span class="plain-syntax">)) </span><span class="named-paragraph-container code-font"><a href="5-es.html#SP11_1" class="named-paragraph-link"><span class="named-paragraph">Fetch wording from stand-alone file</span><span class="named-paragraph-number">11.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Directories::exists</span><span class="plain-syntax">(</span><span class="identifier-syntax">D</span><span class="plain-syntax">)) </span><span class="named-paragraph-container code-font"><a href="5-es.html#SP11_1" class="named-paragraph-link"><span class="named-paragraph">Fetch wording from stand-alone directory</span><span class="named-paragraph-number">11.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">documentation_sought</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">documentation</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP11_1" class="paragraph-anchor"></a><b>&#167;11.1. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Fetch wording from stand-alone file</span><span class="named-paragraph-number">11.1</span></span><span class="comment-syntax"> =</span>
<p class="commentary firstcommentary"><a id="SP11_1" class="paragraph-anchor"></a><b>&#167;11.1. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Fetch wording from stand-alone directory</span><span class="named-paragraph-number">11.1</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">documentation</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">documentation</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">error_text</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">error_text</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="string-syntax">"this extension provides documentation both as a file and in its source"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="2-cps.html#SP5" class="function-link"><span class="function-syntax">Copies::attach_error</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_copy</span><span class="plain-syntax">, </span><a href="2-ce.html#SP2" class="function-link"><span class="function-syntax">CopyErrors::new_T</span></a><span class="plain-syntax">(</span><span class="constant-syntax">EXT_MISWORDED_CE</span><span class="plain-syntax">, -1, </span><span class="identifier-syntax">error_text</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">error_text</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">temp</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TextFiles::read</span><span class="plain-syntax">(</span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">, </span><span class="string-syntax">"unable to read file of extension documentation"</span><span class="plain-syntax">, </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> &amp;</span><a href="5-es.html#SP12" class="function-link"><span class="function-syntax">Extensions::read_extension_file_helper</span></a><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, </span><span class="identifier-syntax">temp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">documentation</span><span class="plain-syntax"> = </span><a href="7-dc.html#SP3" class="function-link"><span class="function-syntax">DocumentationCompiler::compile</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">temp</span><span class="plain-syntax">, </span><span class="identifier-syntax">E</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">temp</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">documentation</span><span class="plain-syntax"> = </span><a href="7-dc.html#SP2" class="function-link"><span class="function-syntax">DocumentationCompiler::compile_from_path</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">D</span><span class="plain-syntax">, </span><span class="identifier-syntax">E</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="5-es.html#SP11">&#167;11</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP12" class="paragraph-anchor"></a><b>&#167;12. </b></p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Extensions::read_extension_file_helper</span><button class="popup" onclick="togglePopup('usagePopup15')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup15">Usage of <span class="code-font"><span class="function-syntax">Extensions::read_extension_file_helper</span></span>:<br/><a href="5-es.html#SP11_1">&#167;11.1</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">text</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_file_position</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tfp</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">void</span><span class="plain-syntax"> *</span><span class="identifier-syntax">v_state</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">contents</span><span class="plain-syntax"> = (</span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *) </span><span class="identifier-syntax">v_state</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">contents</span><span class="plain-syntax">, </span><span class="string-syntax">"%S\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">text</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP13" class="paragraph-anchor"></a><b>&#167;13. </b>And this serves the <span class="extract"><span class="extract-syntax">-document</span></span> feature of inbuild:
<p class="commentary firstcommentary"><a id="SP12" class="paragraph-anchor"></a><b>&#167;12. </b>And this serves the <span class="extract"><span class="extract-syntax">-document</span></span> feature of inbuild:
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Extensions::document</span><button class="popup" onclick="togglePopup('usagePopup16')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup16">Usage of <span class="code-font"><span class="function-syntax">Extensions::document</span></span>:<br/>Extension Manager - <a href="4-em.html#SP10">&#167;10</a><br/>Extension Bundle Manager - <a href="4-ebm.html#SP9">&#167;9</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax">, </span><span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">dest</span><span class="plain-syntax">) {</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Extensions::document</span><button class="popup" onclick="togglePopup('usagePopup15')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup15">Usage of <span class="code-font"><span class="function-syntax">Extensions::document</span></span>:<br/>Extension Manager - <a href="4-em.html#SP10">&#167;10</a><br/>Extension Bundle Manager - <a href="4-ebm.html#SP9">&#167;9</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax">, </span><span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">dest</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">SVEXPLAIN</span><span class="plain-syntax">(1, </span><span class="string-syntax">"(documenting %X to %p)\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_copy</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">edition</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">work</span><span class="plain-syntax">, </span><span class="identifier-syntax">dest</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">compiled_documentation</span><span class="plain-syntax"> *</span><span class="identifier-syntax">cd</span><span class="plain-syntax"> = </span><a href="5-es.html#SP11" class="function-link"><span class="function-syntax">Extensions::get_documentation</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="7-dr.html#SP3" class="function-link"><span class="function-syntax">DocumentationRenderer::as_HTML</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">dest</span><span class="plain-syntax">, </span><span class="identifier-syntax">cd</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP14" class="paragraph-anchor"></a><b>&#167;14. </b>When the extension source text was read from its <span class="extract"><span class="extract-syntax">source_file</span></span>, we
<p class="commentary firstcommentary"><a id="SP13" class="paragraph-anchor"></a><b>&#167;13. </b>When the extension source text was read from its <span class="extract"><span class="extract-syntax">source_file</span></span>, we
attached a reference to say which <span class="extract"><span class="extract-syntax">inform_extension</span></span> it was, and here we
make use of that:
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="function-syntax">Extensions::corresponding_to</span><button class="popup" onclick="togglePopup('usagePopup17')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup17">Usage of <span class="code-font"><span class="function-syntax">Extensions::corresponding_to</span></span>:<br/>Source Text - <a href="6-st.html#SP4">&#167;4</a>, <a href="6-st.html#SP5">&#167;5</a><br/>Headings - <a href="6-hdn.html#SP18">&#167;18</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">source_file</span><span class="plain-syntax"> *</span><span class="identifier-syntax">sf</span><span class="plain-syntax">) {</span>
<span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="function-syntax">Extensions::corresponding_to</span><button class="popup" onclick="togglePopup('usagePopup16')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup16">Usage of <span class="code-font"><span class="function-syntax">Extensions::corresponding_to</span></span>:<br/>Source Text - <a href="6-st.html#SP4">&#167;4</a>, <a href="6-st.html#SP5">&#167;5</a><br/>Headings - <a href="6-hdn.html#SP18">&#167;18</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">source_file</span><span class="plain-syntax"> *</span><span class="identifier-syntax">sf</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">sf</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inbuild_copy</span><span class="plain-syntax"> *</span><span class="identifier-syntax">C</span><span class="plain-syntax"> = </span><span class="identifier-syntax">RETRIEVE_POINTER_inbuild_copy</span><span class="plain-syntax">(</span><span class="identifier-syntax">sf</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">your_ref</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">C</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
@ -1081,7 +1067,7 @@ make use of that:
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="5-es.html#SP4" class="function-link"><span class="function-syntax">Extensions::from_copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">C</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP15" class="paragraph-anchor"></a><b>&#167;15. Miscellaneous. </b></p>
<p class="commentary firstcommentary"><a id="SP14" class="paragraph-anchor"></a><b>&#167;14. Miscellaneous. </b></p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Extensions::write</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax">) {</span>
@ -1097,7 +1083,7 @@ make use of that:
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"%S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_copy</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">edition</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">work</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">raw_author_name</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP16" class="paragraph-anchor"></a><b>&#167;16. </b>Three pieces of information will be set later on, by other parts of Inform
<p class="commentary firstcommentary"><a id="SP15" class="paragraph-anchor"></a><b>&#167;15. </b>Three pieces of information will be set later on, by other parts of Inform
calling the routines below.
</p>
@ -1115,12 +1101,12 @@ that happens, the following function will be called to set the rubric.
<span class="plain-syntax"> </span><span class="identifier-syntax">LOGIF</span><span class="plain-syntax">(</span><span class="identifier-syntax">EXTENSIONS_CENSUS</span><span class="plain-syntax">, </span><span class="string-syntax">"Extension rubric: %S\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">rubric_as_lexed</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
<span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="function-syntax">Extensions::get_rubric</span><button class="popup" onclick="togglePopup('usagePopup18')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup18">Usage of <span class="code-font"><span class="function-syntax">Extensions::get_rubric</span></span>:<br/>Extensions Index Page - <a href="7-eip.html#SP1_2_2_4_4_4">&#167;1.2.2.4.4.4</a>, <a href="7-eip.html#SP1_2_2_4_5">&#167;1.2.2.4.5</a><br/>The Installer - <a href="7-ti.html#SP2_4_1">&#167;2.4.1</a>, <a href="7-ti.html#SP2_4_2">&#167;2.4.2</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax">) {</span>
<span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="function-syntax">Extensions::get_rubric</span><button class="popup" onclick="togglePopup('usagePopup17')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup17">Usage of <span class="code-font"><span class="function-syntax">Extensions::get_rubric</span></span>:<br/>Extensions Index Page - <a href="7-eip.html#SP1_2_2_4_4_4">&#167;1.2.2.4.4.4</a>, <a href="7-eip.html#SP1_2_2_4_5">&#167;1.2.2.4.5</a><br/>The Installer - <a href="7-ti.html#SP2_4_1">&#167;2.4.1</a>, <a href="7-ti.html#SP2_4_2">&#167;2.4.2</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">E</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">rubric_as_lexed</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP17" class="paragraph-anchor"></a><b>&#167;17. </b>The optional extra credit line is used to acknowledge I6 sources,
<p class="commentary firstcommentary"><a id="SP16" class="paragraph-anchor"></a><b>&#167;16. </b>The optional extra credit line is used to acknowledge I6 sources,
collaborators, translators and so on.
</p>
@ -1131,7 +1117,7 @@ collaborators, translators and so on.
<span class="plain-syntax"> </span><span class="identifier-syntax">LOGIF</span><span class="plain-syntax">(</span><span class="identifier-syntax">EXTENSIONS_CENSUS</span><span class="plain-syntax">, </span><span class="string-syntax">"Extension extra credit: %S\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">extra_credit_as_lexed</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP18" class="paragraph-anchor"></a><b>&#167;18. </b>The use option "authorial modesty" is unusual in applying to the extension
<p class="commentary firstcommentary"><a id="SP17" class="paragraph-anchor"></a><b>&#167;17. </b>The use option "authorial modesty" is unusual in applying to the extension
it is found in, not the whole source text. When we read it, we call one of
the following routines, depending on whether it was in an extension or in
the main source text:
@ -1147,21 +1133,21 @@ the main source text:
<span class="plain-syntax"> </span><span class="identifier-syntax">general_authorial_modesty</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP19" class="paragraph-anchor"></a><b>&#167;19. </b>The inclusion sentence for an extension is where it was Included in a
<p class="commentary firstcommentary"><a id="SP18" class="paragraph-anchor"></a><b>&#167;18. </b>The inclusion sentence for an extension is where it was Included in a
project's syntax tree (if it was). It isn't used in compilation, only for
problem messages and the index.
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Extensions::set_inclusion_sentence</span><button class="popup" onclick="togglePopup('usagePopup19')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup19">Usage of <span class="code-font"><span class="function-syntax">Extensions::set_inclusion_sentence</span></span>:<br/>Inclusions - <a href="6-inc.html#SP6_1">&#167;6.1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax">, </span><span class="identifier-syntax">parse_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">N</span><span class="plain-syntax">) {</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Extensions::set_inclusion_sentence</span><button class="popup" onclick="togglePopup('usagePopup18')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup18">Usage of <span class="code-font"><span class="function-syntax">Extensions::set_inclusion_sentence</span></span>:<br/>Inclusions - <a href="6-inc.html#SP6_1">&#167;6.1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax">, </span><span class="identifier-syntax">parse_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">N</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">inclusion_sentence</span><span class="plain-syntax"> = </span><span class="identifier-syntax">N</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
<span class="identifier-syntax">parse_node</span><span class="plain-syntax"> *</span><span class="function-syntax">Extensions::get_inclusion_sentence</span><button class="popup" onclick="togglePopup('usagePopup20')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup20">Usage of <span class="code-font"><span class="function-syntax">Extensions::get_inclusion_sentence</span></span>:<br/>Project Services - <a href="5-ps2.html#SP35">&#167;35</a><br/>Inclusions - <a href="6-inc.html#SP6_1_1">&#167;6.1.1</a><br/>Extensions Index Page - <a href="7-eip.html#SP1_2_2_4_4_1">&#167;1.2.2.4.4.1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax">) {</span>
<span class="identifier-syntax">parse_node</span><span class="plain-syntax"> *</span><span class="function-syntax">Extensions::get_inclusion_sentence</span><button class="popup" onclick="togglePopup('usagePopup19')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup19">Usage of <span class="code-font"><span class="function-syntax">Extensions::get_inclusion_sentence</span></span>:<br/>Project Services - <a href="5-ps2.html#SP35">&#167;35</a><br/>Inclusions - <a href="6-inc.html#SP6_1_1">&#167;6.1.1</a><br/>Extensions Index Page - <a href="7-eip.html#SP1_2_2_4_4_1">&#167;1.2.2.4.4.1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">E</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">inclusion_sentence</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP20" class="paragraph-anchor"></a><b>&#167;20. </b>An extension is "standard" if it's either the Standard Rules or Basic Inform.
<p class="commentary firstcommentary"><a id="SP19" class="paragraph-anchor"></a><b>&#167;19. </b>An extension is "standard" if it's either the Standard Rules or Basic Inform.
</p>
<pre class="displayed-code all-displayed-code code-font">
@ -1170,33 +1156,33 @@ problem messages and the index.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">standard</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP21" class="paragraph-anchor"></a><b>&#167;21. Version requirements. </b>When it's known that an extension must satisfy a given version requirement &mdash;
<p class="commentary firstcommentary"><a id="SP20" class="paragraph-anchor"></a><b>&#167;20. Version requirements. </b>When it's known that an extension must satisfy a given version requirement &mdash;
say, being version 7.2.1 or better &mdash; the following is called. Note that
if incompatible requirements are placed on it, the range in <span class="extract"><span class="extract-syntax">E-&gt;must_satisfy</span></span>
becomes empty and stays that way.
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Extensions::must_satisfy</span><button class="popup" onclick="togglePopup('usagePopup21')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup21">Usage of <span class="code-font"><span class="function-syntax">Extensions::must_satisfy</span></span>:<br/>Inclusions - <a href="6-inc.html#SP6">&#167;6</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_requirement</span><span class="plain-syntax"> *</span><span class="identifier-syntax">req</span><span class="plain-syntax">) {</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Extensions::must_satisfy</span><button class="popup" onclick="togglePopup('usagePopup20')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup20">Usage of <span class="code-font"><span class="function-syntax">Extensions::must_satisfy</span></span>:<br/>Inclusions - <a href="6-inc.html#SP6">&#167;6</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_requirement</span><span class="plain-syntax"> *</span><span class="identifier-syntax">req</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">must_satisfy</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">must_satisfy</span><span class="plain-syntax"> = </span><span class="identifier-syntax">req</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="identifier-syntax">VersionNumberRanges::intersect_range</span><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">must_satisfy</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">version_range</span><span class="plain-syntax">, </span><span class="identifier-syntax">req</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">version_range</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP22" class="paragraph-anchor"></a><b>&#167;22. </b>And it is certainly possible, if an extension is loaded for multiple
<p class="commentary firstcommentary"><a id="SP21" class="paragraph-anchor"></a><b>&#167;21. </b>And it is certainly possible, if an extension is loaded for multiple
reasons with different versioning needs, that the extension no longer meets
its requirements (even though it did when first loaded). This tests for that:
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">Extensions::satisfies</span><button class="popup" onclick="togglePopup('usagePopup22')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup22">Usage of <span class="code-font"><span class="function-syntax">Extensions::satisfies</span></span>:<br/>Project Services - <a href="5-ps2.html#SP35">&#167;35</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax">) {</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">Extensions::satisfies</span><button class="popup" onclick="togglePopup('usagePopup21')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup21">Usage of <span class="code-font"><span class="function-syntax">Extensions::satisfies</span></span>:<br/>Project Services - <a href="5-ps2.html#SP35">&#167;35</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">E</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="2-rqr.html#SP7" class="function-link"><span class="function-syntax">Requirements::meets</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_copy</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">edition</span><span class="plain-syntax">, </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">must_satisfy</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP23" class="paragraph-anchor"></a><b>&#167;23. File hierarchy tidying. </b></p>
<p class="commentary firstcommentary"><a id="SP22" class="paragraph-anchor"></a><b>&#167;22. File hierarchy tidying. </b></p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">Extensions::rename_directory</span><button class="popup" onclick="togglePopup('usagePopup23')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup23">Usage of <span class="code-font"><span class="function-syntax">Extensions::rename_directory</span></span>:<br/>Extension Bundle Manager - <a href="4-ebm.html#SP3">&#167;3</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">new_name</span><span class="plain-syntax">) {</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">Extensions::rename_directory</span><button class="popup" onclick="togglePopup('usagePopup22')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup22">Usage of <span class="code-font"><span class="function-syntax">Extensions::rename_directory</span></span>:<br/>Extension Bundle Manager - <a href="4-ebm.html#SP3">&#167;3</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">new_name</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">task</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">task</span><span class="plain-syntax">, </span><span class="string-syntax">"(Changing directory name '%p' to '%S')\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">new_name</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">rv</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Directories::rename</span><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">new_name</span><span class="plain-syntax">);</span>
@ -1204,7 +1190,7 @@ its requirements (even though it did when first loaded). This tests for that:
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">rv</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">Extensions::rename_file</span><button class="popup" onclick="togglePopup('usagePopup24')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup24">Usage of <span class="code-font"><span class="function-syntax">Extensions::rename_file</span></span>:<br/><a href="5-es.html#SP2_2">&#167;2.2</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">new_name</span><span class="plain-syntax">) {</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">Extensions::rename_file</span><button class="popup" onclick="togglePopup('usagePopup23')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup23">Usage of <span class="code-font"><span class="function-syntax">Extensions::rename_file</span></span>:<br/><a href="5-es.html#SP2_2">&#167;2.2</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">new_name</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">task</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">task</span><span class="plain-syntax">, </span><span class="string-syntax">"(Changing file name '%f' to '%S')\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="identifier-syntax">new_name</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">rv</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Filenames::rename</span><span class="plain-syntax">(</span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="identifier-syntax">new_name</span><span class="plain-syntax">);</span>

2
docs/supervisor-module/5-ks.html
View file

@ -140,7 +140,7 @@ use options.
<span class="plain-syntax"> </span><span class="identifier-syntax">CLASS_DEFINITION</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">kit_configuration</span><span class="plain-syntax">;</span>
</pre>
<ul class="endnotetexts"><li>The structure kit_configuration is private to this section.</li></ul>
<ul class="endnotetexts"><li>The structure kit_configuration is accessed in 7/dc and here.</li></ul>
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>&#167;5. </b>Here goes, then:
</p>

4
docs/supervisor-module/5-ps2.html
View file

@ -1165,10 +1165,10 @@ each extension against the intersection of all requirements put on it:
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Projects::check_extension_versions_d</span><span class="plain-syntax">(</span><span class="reserved-syntax">inform_project</span><span class="plain-syntax"> *</span><span class="identifier-syntax">proj</span><span class="plain-syntax">, </span><span class="reserved-syntax">build_vertex</span><span class="plain-syntax"> *</span><span class="identifier-syntax">V</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">V</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_copy</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">V</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_copy</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">edition</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">work</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">genre</span><span class="plain-syntax"> == </span><span class="identifier-syntax">extension_genre</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax"> = </span><a href="5-es.html#SP4" class="function-link"><span class="function-syntax">Extensions::from_copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">V</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_copy</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="5-es.html#SP22" class="function-link"><span class="function-syntax">Extensions::satisfies</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">) == </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="5-es.html#SP21" class="function-link"><span class="function-syntax">Extensions::satisfies</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">) == </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">copy_error</span><span class="plain-syntax"> *</span><span class="identifier-syntax">CE</span><span class="plain-syntax"> = </span><a href="2-ce.html#SP2" class="function-link"><span class="function-syntax">CopyErrors::new_T</span></a><span class="plain-syntax">(</span><span class="constant-syntax">SYNTAX_CE</span><span class="plain-syntax">, </span><span class="constant-syntax">ExtVersionTooLow_SYNERROR</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">I</span><span class="string-syntax">"two incompatible versions"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="2-ce.html#SP3" class="function-link"><span class="function-syntax">CopyErrors::supply_node</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">CE</span><span class="plain-syntax">, </span><a href="5-es.html#SP19" class="function-link"><span class="function-syntax">Extensions::get_inclusion_sentence</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> </span><a href="2-ce.html#SP3" class="function-link"><span class="function-syntax">CopyErrors::supply_node</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">CE</span><span class="plain-syntax">, </span><a href="5-es.html#SP18" class="function-link"><span class="function-syntax">Extensions::get_inclusion_sentence</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> </span><a href="2-cps.html#SP5" class="function-link"><span class="function-syntax">Copies::attach_error</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">proj</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_copy</span><span class="plain-syntax">, </span><span class="identifier-syntax">CE</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> }</span>

2
docs/supervisor-module/6-hdn.html
View file

@ -789,7 +789,7 @@ file and a line number of at least 1).
<span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="function-syntax">Headings::get_extension_containing</span><button class="popup" onclick="togglePopup('usagePopup9')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup9">Usage of <span class="code-font"><span class="function-syntax">Headings::get_extension_containing</span></span>:<br/><a href="6-hdn.html#SP22">&#167;22</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">heading</span><span class="plain-syntax"> *</span><span class="identifier-syntax">h</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">h</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) || (</span><span class="identifier-syntax">h</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">start_location</span><span class="plain-syntax">.</span><span class="identifier-syntax">file_of_origin</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">)) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="5-es.html#SP14" class="function-link"><span class="function-syntax">Extensions::corresponding_to</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">h</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">start_location</span><span class="plain-syntax">.</span><span class="identifier-syntax">file_of_origin</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="5-es.html#SP13" class="function-link"><span class="function-syntax">Extensions::corresponding_to</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">h</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">start_location</span><span class="plain-syntax">.</span><span class="identifier-syntax">file_of_origin</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP19" class="paragraph-anchor"></a><b>&#167;19. </b>Although Implied (0) headings do have text, contrary to the implication of

6
docs/supervisor-module/6-inc.html
View file

@ -325,7 +325,7 @@ Sausages by Mr Punch, and loaded it, but then read the sentence
<span class="plain-syntax"> </span><span class="identifier-syntax">LOOP_OVER</span><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">, </span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><a href="2-rqr.html#SP7" class="function-link"><span class="function-syntax">Requirements::meets</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_copy</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">edition</span><span class="plain-syntax">, </span><span class="identifier-syntax">req</span><span class="plain-syntax">)) &amp;&amp;</span>
<span class="plain-syntax"> (</span><a href="2-cps.html#SP7" class="function-link"><span class="function-syntax">Copies::source_text_has_been_read</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_copy</span><span class="plain-syntax">))) {</span>
<span class="plain-syntax"> </span><a href="5-es.html#SP21" class="function-link"><span class="function-syntax">Extensions::must_satisfy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">, </span><span class="identifier-syntax">req</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="5-es.html#SP20" class="function-link"><span class="function-syntax">Extensions::must_satisfy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">, </span><span class="identifier-syntax">req</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">E</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="6-inc.html#SP6_1" class="named-paragraph-link"><span class="named-paragraph">Read the extension file into the lexer, and break it into body and documentation</span><span class="named-paragraph-number">6.1</span></a></span><span class="plain-syntax">;</span>
@ -343,7 +343,7 @@ Sausages by Mr Punch, and loaded it, but then read the sentence
<span class="plain-syntax"> </span><a href="2-nst.html#SP10" class="function-link"><span class="function-syntax">Nests::search_for_best</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">req</span><span class="plain-syntax">, </span><a href="5-ps2.html#SP7" class="function-link"><span class="function-syntax">Projects::nest_list</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">for_project</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">search_result</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">E</span><span class="plain-syntax"> = </span><a href="5-es.html#SP4" class="function-link"><span class="function-syntax">Extensions::from_copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">search_result</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">copy</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="5-es.html#SP19" class="function-link"><span class="function-syntax">Extensions::set_inclusion_sentence</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">, </span><span class="identifier-syntax">at</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="5-es.html#SP18" class="function-link"><span class="function-syntax">Extensions::set_inclusion_sentence</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">, </span><span class="identifier-syntax">at</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="5-es.html#SP6" class="function-link"><span class="function-syntax">Extensions::set_associated_project</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">, </span><span class="identifier-syntax">for_project</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="2-nst.html#SP2" class="function-link"><span class="function-syntax">Nests::get_tag</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">search_result</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">nest</span><span class="plain-syntax">) == </span><span class="constant-syntax">INTERNAL_NEST_TAG</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">loaded_from_built_in_area</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
@ -378,7 +378,7 @@ report this problem at the inclusion line.
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">copy_error</span><span class="plain-syntax"> *</span><span class="identifier-syntax">CE</span><span class="plain-syntax"> = </span><a href="2-ce.html#SP2" class="function-link"><span class="function-syntax">CopyErrors::new_T</span></a><span class="plain-syntax">(</span><span class="constant-syntax">SYNTAX_CE</span><span class="plain-syntax">, </span><span class="constant-syntax">ExtInadequateVM_SYNERROR</span><span class="plain-syntax">, </span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">parsed_from</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="2-ce.html#SP3" class="function-link"><span class="function-syntax">CopyErrors::supply_node</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">CE</span><span class="plain-syntax">, </span><a href="5-es.html#SP19" class="function-link"><span class="function-syntax">Extensions::get_inclusion_sentence</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> </span><a href="2-ce.html#SP3" class="function-link"><span class="function-syntax">CopyErrors::supply_node</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">CE</span><span class="plain-syntax">, </span><a href="5-es.html#SP18" class="function-link"><span class="function-syntax">Extensions::get_inclusion_sentence</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> </span><a href="2-cps.html#SP5" class="function-link"><span class="function-syntax">Copies::attach_error</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">inclusions_errors_to</span><span class="plain-syntax">, </span><span class="identifier-syntax">CE</span><span class="plain-syntax">);</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="6-inc.html#SP6_1">&#167;6.1</a>.</li></ul>

4
docs/supervisor-module/6-st.html
View file

@ -171,7 +171,7 @@ source files.
<span class="plain-syntax"> </span><span class="identifier-syntax">paraphrase</span><span class="plain-syntax"> = </span><span class="identifier-syntax">I</span><span class="string-syntax">"source text"</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">referred</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">E</span><span class="plain-syntax"> = </span><a href="5-es.html#SP14" class="function-link"><span class="function-syntax">Extensions::corresponding_to</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">referred</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">E</span><span class="plain-syntax"> = </span><a href="5-es.html#SP13" class="function-link"><span class="function-syntax">Extensions::corresponding_to</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">referred</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">matched_filename</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax">;</span>
@ -202,7 +202,7 @@ source files.
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">SourceText::gloss_extension</span><span class="plain-syntax">(</span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">source_file</span><span class="plain-syntax"> *</span><span class="identifier-syntax">referred</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax"> = </span><a href="5-es.html#SP14" class="function-link"><span class="function-syntax">Extensions::corresponding_to</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">referred</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax"> = </span><a href="5-es.html#SP13" class="function-link"><span class="function-syntax">Extensions::corresponding_to</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">referred</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">E</span><span class="plain-syntax">) </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">" in the extension %X"</span><span class="plain-syntax">, </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_copy</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">edition</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">work</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>

429
docs/supervisor-module/7-dc.html
View file

@ -72,10 +72,11 @@ it's really not much more than the tree produced by <a href="7-dt.html" class="i
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">total_headings</span><span class="plain-syntax">[3];</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">total_examples</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">empty</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">cases</span><span class="plain-syntax">; </span><span class="comment-syntax"> of </span><span class="extract"><span class="extract-syntax">satellite_test_case</span></span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CLASS_DEFINITION</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">compiled_documentation</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">compiled_documentation</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationCompiler::new_wrapper</span><button class="popup" onclick="togglePopup('usagePopup1')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup1">Usage of <span class="code-font"><span class="function-syntax">DocumentationCompiler::new_wrapper</span></span>:<br/><a href="7-dc.html#SP3">&#167;3</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">source</span><span class="plain-syntax">) {</span>
<span class="reserved-syntax">compiled_documentation</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationCompiler::new_wrapper</span><button class="popup" onclick="togglePopup('usagePopup1')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup1">Usage of <span class="code-font"><span class="function-syntax">DocumentationCompiler::new_wrapper</span></span>:<br/><a href="7-dc.html#SP6">&#167;6</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">source</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">compiled_documentation</span><span class="plain-syntax"> *</span><span class="identifier-syntax">cd</span><span class="plain-syntax"> = </span><span class="identifier-syntax">CREATE</span><span class="plain-syntax">(</span><span class="reserved-syntax">compiled_documentation</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">title</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::new</span><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">original</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">source</span><span class="plain-syntax">);</span>
@ -86,21 +87,223 @@ it's really not much more than the tree produced by <a href="7-dt.html" class="i
<span class="plain-syntax"> </span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">total_headings</span><span class="plain-syntax">[1] = </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">total_headings</span><span class="plain-syntax">[2] = </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">empty</span><span class="plain-syntax"> = </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">cases</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NEW_LINKED_LIST</span><span class="plain-syntax">(</span><span class="reserved-syntax">satellite_test_case</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">cd</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">satellite_test_case</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">is_example</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">owning_heading</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">owning_node</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">compiled_documentation</span><span class="plain-syntax"> *</span><span class="identifier-syntax">owner</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">short_name</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">test_file</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ideal_transcript</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CLASS_DEFINITION</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">satellite_test_case</span><span class="plain-syntax">;</span>
</pre>
<ul class="endnotetexts"><li>The structure compiled_documentation is accessed in 2/wrk, 2/edt, 2/cps, 2/rqr, 2/jm, 3/bg, 3/is, 4/ebm, 4/km, 4/lm, 4/pm, 4/pbm, 4/pfm, 4/tm, 5/es, 5/ks, 5/ls, 5/ps2, 6/inc, 7/eip, 7/ti, 7/dr and here.</li></ul>
<ul class="endnotetexts"><li>The structure compiled_documentation is accessed in 2/wrk, 2/edt, 2/cps, 2/rqr, 2/jm, 3/bg, 3/is, 4/ebm, 4/km, 4/lm, 4/pm, 4/pbm, 4/pfm, 4/tm, 5/es, 5/ks, 5/ls, 5/ps2, 6/inc, 7/eip, 7/ti, 7/dr and here.</li><li>The structure satellite_test_case is accessed in 5/ks and here.</li></ul>
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>&#167;2. </b>We can compile either from a file...
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">compiled_documentation</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationCompiler::compile_from_file</span><span class="plain-syntax">(</span><span class="identifier-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax">,</span>
<span class="reserved-syntax">compiled_documentation</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationCompiler::compile_from_path</span><button class="popup" onclick="togglePopup('usagePopup2')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup2">Usage of <span class="code-font"><span class="function-syntax">DocumentationCompiler::compile_from_path</span></span>:<br/>Extension Services - <a href="5-es.html#SP11_1">&#167;11.1</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">associated_extension</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Filenames::in</span><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Documentation.txt"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">TextFiles::exists</span><span class="plain-syntax">(</span><span class="identifier-syntax">F</span><span class="plain-syntax">) == </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">compiled_documentation</span><span class="plain-syntax"> *</span><span class="identifier-syntax">cd</span><span class="plain-syntax"> =</span>
<span class="plain-syntax"> </span><a href="7-dc.html#SP5" class="function-link"><span class="function-syntax">DocumentationCompiler::compile_from_file</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="identifier-syntax">associated_extension</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">cd</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">EP</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Pathnames::down</span><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Examples"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">egs</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP2_1" class="named-paragraph-link"><span class="named-paragraph">Scan EP directory for examples</span><span class="named-paragraph-number">2.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">egs</span><span class="plain-syntax"> = </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">EP</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Pathnames::down</span><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Tests"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP2_1" class="named-paragraph-link"><span class="named-paragraph">Scan EP directory for examples</span><span class="named-paragraph-number">2.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">cd</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP2_1" class="paragraph-anchor"></a><b>&#167;2.1. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Scan EP directory for examples</span><span class="named-paragraph-number">2.1</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="identifier-syntax">scan_directory</span><span class="plain-syntax"> *</span><span class="identifier-syntax">D</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Directories::open</span><span class="plain-syntax">(</span><span class="identifier-syntax">EP</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">leafname</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">while</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Directories::next</span><span class="plain-syntax">(</span><span class="identifier-syntax">D</span><span class="plain-syntax">, </span><span class="identifier-syntax">leafname</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wchar_t</span><span class="plain-syntax"> </span><span class="identifier-syntax">first</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::get_first_char</span><span class="plain-syntax">(</span><span class="identifier-syntax">leafname</span><span class="plain-syntax">), </span><span class="identifier-syntax">last</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::get_last_char</span><span class="plain-syntax">(</span><span class="identifier-syntax">leafname</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Platform::is_folder_separator</span><span class="plain-syntax">(</span><span class="identifier-syntax">last</span><span class="plain-syntax">)) </span><span class="reserved-syntax">continue</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">first</span><span class="plain-syntax"> == </span><span class="character-syntax">'.'</span><span class="plain-syntax">) </span><span class="reserved-syntax">continue</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">first</span><span class="plain-syntax"> == </span><span class="character-syntax">'('</span><span class="plain-syntax">) </span><span class="reserved-syntax">continue</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">short_name</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::new</span><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Filenames::in</span><span class="plain-syntax">(</span><span class="identifier-syntax">EP</span><span class="plain-syntax">, </span><span class="identifier-syntax">leafname</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Filenames::write_unextended_leafname</span><span class="plain-syntax">(</span><span class="identifier-syntax">short_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">Str::get_at</span><span class="plain-syntax">(</span><span class="identifier-syntax">short_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">short_name</span><span class="plain-syntax">)-2) == </span><span class="character-syntax">'-'</span><span class="plain-syntax">) &amp;&amp;</span>
<span class="plain-syntax"> ((</span><span class="identifier-syntax">Str::get_at</span><span class="plain-syntax">(</span><span class="identifier-syntax">short_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">short_name</span><span class="plain-syntax">)-1) == </span><span class="character-syntax">'I'</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> || (</span><span class="identifier-syntax">Str::get_at</span><span class="plain-syntax">(</span><span class="identifier-syntax">short_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">short_name</span><span class="plain-syntax">)-1) == </span><span class="character-syntax">'i'</span><span class="plain-syntax">)))</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">continue</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">satellite_test_case</span><span class="plain-syntax"> *</span><span class="identifier-syntax">stc</span><span class="plain-syntax"> = </span><span class="identifier-syntax">CREATE</span><span class="plain-syntax">(</span><span class="reserved-syntax">satellite_test_case</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">stc</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">is_example</span><span class="plain-syntax"> = </span><span class="identifier-syntax">egs</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">stc</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">owning_heading</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">stc</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">owning_node</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">stc</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">owner</span><span class="plain-syntax"> = </span><span class="identifier-syntax">cd</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">stc</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">short_name</span><span class="plain-syntax"> = </span><span class="identifier-syntax">short_name</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">stc</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">test_file</span><span class="plain-syntax"> = </span><span class="identifier-syntax">F</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">stc</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">ideal_transcript</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">ideal_leafname</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">ideal_leafname</span><span class="plain-syntax">, </span><span class="string-syntax">"%S-I.txt"</span><span class="plain-syntax">, </span><span class="identifier-syntax">stc</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">short_name</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">IF</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Filenames::in</span><span class="plain-syntax">(</span><span class="identifier-syntax">EP</span><span class="plain-syntax">, </span><span class="identifier-syntax">ideal_leafname</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">TextFiles::exists</span><span class="plain-syntax">(</span><span class="identifier-syntax">IF</span><span class="plain-syntax">)) </span><span class="identifier-syntax">stc</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">ideal_transcript</span><span class="plain-syntax"> = </span><span class="identifier-syntax">IF</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">ideal_leafname</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">stc</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">is_example</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP2_1_2" class="named-paragraph-link"><span class="named-paragraph">Scan the example for its header and content</span><span class="named-paragraph-number">2.1.2</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ADD_TO_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">stc</span><span class="plain-syntax">, </span><span class="reserved-syntax">satellite_test_case</span><span class="plain-syntax">, </span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">cases</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">leafname</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Directories::close</span><span class="plain-syntax">(</span><span class="identifier-syntax">D</span><span class="plain-syntax">);</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP2">&#167;2</a> (twice).</li></ul>
<p class="commentary firstcommentary"><a id="SP2_1_1" class="paragraph-anchor"></a><b>&#167;2.1.1. </b></p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">example_scanning_state</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">star_count</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">long_title</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">body_text</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">placement</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">desc</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">errors</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">heterogeneous_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tree</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">scanning</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">past_header</span><span class="plain-syntax">;</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">example_scanning_state</span><span class="plain-syntax">;</span>
</pre>
<ul class="endnotetexts"><li>The structure example_scanning_state is accessed in 5/es, 7/dt, 7/dr and here.</li></ul>
<p class="commentary firstcommentary"><a id="SP2_1_2" class="paragraph-anchor"></a><b>&#167;2.1.2. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Scan the example for its header and content</span><span class="named-paragraph-number">2.1.2</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">example_scanning_state</span><span class="plain-syntax"> </span><span class="identifier-syntax">ess</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ess</span><span class="plain-syntax">.</span><span class="element-syntax">star_count</span><span class="plain-syntax"> = </span><span class="constant-syntax">1</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ess</span><span class="plain-syntax">.</span><span class="element-syntax">long_title</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ess</span><span class="plain-syntax">.</span><span class="element-syntax">body_text</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::new</span><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ess</span><span class="plain-syntax">.</span><span class="element-syntax">placement</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ess</span><span class="plain-syntax">.</span><span class="element-syntax">desc</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ess</span><span class="plain-syntax">.</span><span class="element-syntax">errors</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NEW_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">tree_node</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ess</span><span class="plain-syntax">.</span><span class="element-syntax">tree</span><span class="plain-syntax"> = </span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tree</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ess</span><span class="plain-syntax">.</span><span class="element-syntax">past_header</span><span class="plain-syntax"> = </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ess</span><span class="plain-syntax">.</span><span class="element-syntax">scanning</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::new</span><span class="plain-syntax">(); </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">ess</span><span class="plain-syntax">.</span><span class="element-syntax">scanning</span><span class="plain-syntax">, </span><span class="string-syntax">"%S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">Filenames::get_leafname</span><span class="plain-syntax">(</span><span class="identifier-syntax">stc</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">test_file</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TextFiles::read</span><span class="plain-syntax">(</span><span class="identifier-syntax">stc</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">test_file</span><span class="plain-syntax">, </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">, </span><span class="string-syntax">"unable to read file of example"</span><span class="plain-syntax">, </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> &amp;</span><a href="7-dc.html#SP4" class="function-link"><span class="function-syntax">DocumentationCompiler::read_example_helper</span></a><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, &amp;</span><span class="identifier-syntax">ess</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">placement_node</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">ess</span><span class="plain-syntax">.</span><span class="element-syntax">placement</span><span class="plain-syntax">) == </span><span class="constant-syntax">0</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><a href="7-dc.html#SP3" class="function-link"><span class="function-syntax">DocumentationCompiler::example_error</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">ess</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">I</span><span class="string-syntax">"example does not give its Location"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">placement_node</span><span class="plain-syntax"> = </span><a href="7-dt.html#SP16" class="function-link"><span class="function-syntax">DocumentationTree::find_section</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tree</span><span class="plain-syntax">, </span><span class="identifier-syntax">ess</span><span class="plain-syntax">.</span><span class="element-syntax">placement</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">placement_node</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><a href="7-dc.html#SP3" class="function-link"><span class="function-syntax">DocumentationCompiler::example_error</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">ess</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">I</span><span class="string-syntax">"example gives a Location which is not the name of any section"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">ess</span><span class="plain-syntax">.</span><span class="element-syntax">desc</span><span class="plain-syntax">) == </span><span class="constant-syntax">0</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><a href="7-dc.html#SP3" class="function-link"><span class="function-syntax">DocumentationCompiler::example_error</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">ess</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">I</span><span class="string-syntax">"example does not give its Description"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">content_node</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">ess</span><span class="plain-syntax">.</span><span class="element-syntax">body_text</span><span class="plain-syntax">) == </span><span class="constant-syntax">0</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><a href="7-dc.html#SP3" class="function-link"><span class="function-syntax">DocumentationCompiler::example_error</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">ess</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">I</span><span class="string-syntax">"example does not give any actual content"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">compiled_documentation</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ecd</span><span class="plain-syntax"> =</span>
<span class="plain-syntax"> </span><a href="7-dc.html#SP6" class="function-link"><span class="function-syntax">DocumentationCompiler::compile</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">ess</span><span class="plain-syntax">.</span><span class="element-syntax">body_text</span><span class="plain-syntax">, </span><span class="identifier-syntax">associated_extension</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">ecd</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">ecd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tree</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">ecd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tree</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">root</span><span class="plain-syntax">) &amp;&amp;</span>
<span class="plain-syntax"> (</span><span class="identifier-syntax">ecd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tree</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">root</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">child</span><span class="plain-syntax">) &amp;&amp;</span>
<span class="plain-syntax"> (</span><span class="identifier-syntax">ecd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tree</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">root</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">child</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">type</span><span class="plain-syntax"> == </span><span class="identifier-syntax">passage_TNT</span><span class="plain-syntax">))</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">content_node</span><span class="plain-syntax"> = </span><span class="identifier-syntax">ecd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tree</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">root</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">child</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><a href="7-dc.html#SP3" class="function-link"><span class="function-syntax">DocumentationCompiler::example_error</span></a><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">ess</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">I</span><span class="string-syntax">"example file content is missing or wrongly set out"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">example_node</span><span class="plain-syntax"> = </span><a href="7-dt.html#SP5" class="function-link"><span class="function-syntax">DocumentationTree::new_example</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tree</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ess</span><span class="plain-syntax">.</span><span class="element-syntax">long_title</span><span class="plain-syntax">, </span><span class="identifier-syntax">ess</span><span class="plain-syntax">.</span><span class="element-syntax">desc</span><span class="plain-syntax">, </span><span class="identifier-syntax">ess</span><span class="plain-syntax">.</span><span class="element-syntax">star_count</span><span class="plain-syntax">, ++(</span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">total_examples</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">placement_node</span><span class="plain-syntax">) </span><span class="identifier-syntax">Trees::make_child</span><span class="plain-syntax">(</span><span class="identifier-syntax">example_node</span><span class="plain-syntax">, </span><span class="identifier-syntax">placement_node</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">content_node</span><span class="plain-syntax">) </span><span class="identifier-syntax">Trees::make_child</span><span class="plain-syntax">(</span><span class="identifier-syntax">content_node</span><span class="plain-syntax">, </span><span class="identifier-syntax">example_node</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOOP_OVER_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">, </span><span class="identifier-syntax">tree_node</span><span class="plain-syntax">, </span><span class="identifier-syntax">ess</span><span class="plain-syntax">.</span><span class="element-syntax">errors</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Trees::make_child</span><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">, </span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">tree</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">root</span><span class="plain-syntax">);</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP2_1">&#167;2.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>&#167;3. </b></p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">DocumentationCompiler::example_error</span><button class="popup" onclick="togglePopup('usagePopup3')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup3">Usage of <span class="code-font"><span class="function-syntax">DocumentationCompiler::example_error</span></span>:<br/><a href="7-dc.html#SP2_1_2">&#167;2.1.2</a>, <a href="7-dc.html#SP4">&#167;4</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">example_scanning_state</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ess</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">text</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">err</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::new</span><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">err</span><span class="plain-syntax">, </span><span class="string-syntax">"Example file '%S': %S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">ess</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">scanning</span><span class="plain-syntax">, </span><span class="identifier-syntax">text</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax"> = </span><a href="7-dt.html#SP15" class="function-link"><span class="function-syntax">DocumentationTree::new_source_error</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">ess</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tree</span><span class="plain-syntax">, </span><span class="identifier-syntax">err</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ADD_TO_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">, </span><span class="identifier-syntax">tree_node</span><span class="plain-syntax">, </span><span class="identifier-syntax">ess</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">errors</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>&#167;4. </b></p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">DocumentationCompiler::read_example_helper</span><button class="popup" onclick="togglePopup('usagePopup4')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup4">Usage of <span class="code-font"><span class="function-syntax">DocumentationCompiler::read_example_helper</span></span>:<br/><a href="7-dc.html#SP2_1_2">&#167;2.1.2</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">text</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_file_position</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tfp</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">void</span><span class="plain-syntax"> *</span><span class="identifier-syntax">v_state</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">example_scanning_state</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ess</span><span class="plain-syntax"> = (</span><span class="reserved-syntax">example_scanning_state</span><span class="plain-syntax"> *) </span><span class="identifier-syntax">v_state</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">tfp</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">line_count</span><span class="plain-syntax"> == </span><span class="constant-syntax">1</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">match_results</span><span class="plain-syntax"> </span><span class="identifier-syntax">mr</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Regexp::create_mr</span><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">Regexp::match</span><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">text</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"Example *: *(%**) *(%c+?)"</span><span class="plain-syntax">)) ||</span>
<span class="plain-syntax"> (</span><span class="identifier-syntax">Regexp::match</span><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">text</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"Example *- *(%**) *(%c+?)"</span><span class="plain-syntax">))) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ess</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">star_count</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="identifier-syntax">exp</span><span class="plain-syntax">[0]);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">ess</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">star_count</span><span class="plain-syntax"> == </span><span class="constant-syntax">0</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><a href="7-dc.html#SP3" class="function-link"><span class="function-syntax">DocumentationCompiler::example_error</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">ess</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">I</span><span class="string-syntax">"this example should be marked (before the title) '*', '**', '***' or '****' for difficulty"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ess</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">star_count</span><span class="plain-syntax"> = </span><span class="constant-syntax">1</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">ess</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">star_count</span><span class="plain-syntax"> &gt; </span><span class="constant-syntax">4</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><a href="7-dc.html#SP3" class="function-link"><span class="function-syntax">DocumentationCompiler::example_error</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">ess</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">I</span><span class="string-syntax">"four stars '****' is the maximum difficulty rating allowed"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ess</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">star_count</span><span class="plain-syntax"> = </span><span class="constant-syntax">4</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ess</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">long_title</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="identifier-syntax">exp</span><span class="plain-syntax">[1]);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><a href="7-dc.html#SP3" class="function-link"><span class="function-syntax">DocumentationCompiler::example_error</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">ess</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">I</span><span class="string-syntax">"titling line of example file is malformed"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Regexp::dispose_of</span><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">ess</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">past_header</span><span class="plain-syntax"> == </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::is_whitespace</span><span class="plain-syntax">(</span><span class="identifier-syntax">text</span><span class="plain-syntax">)) { </span><span class="identifier-syntax">ess</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">past_header</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">; </span><span class="reserved-syntax">return</span><span class="plain-syntax">; }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">match_results</span><span class="plain-syntax"> </span><span class="identifier-syntax">mr</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Regexp::create_mr</span><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Regexp::match</span><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">text</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"(%C+?) *: *(%c+?)"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::eq</span><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="identifier-syntax">exp</span><span class="plain-syntax">[0], </span><span class="identifier-syntax">I</span><span class="string-syntax">"Location"</span><span class="plain-syntax">)) </span><span class="identifier-syntax">ess</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">placement</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="identifier-syntax">exp</span><span class="plain-syntax">[1]);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::eq</span><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="identifier-syntax">exp</span><span class="plain-syntax">[0], </span><span class="identifier-syntax">I</span><span class="string-syntax">"Description"</span><span class="plain-syntax">)) </span><span class="identifier-syntax">ess</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">desc</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="identifier-syntax">exp</span><span class="plain-syntax">[1]);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><a href="7-dc.html#SP3" class="function-link"><span class="function-syntax">DocumentationCompiler::example_error</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">ess</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">I</span><span class="string-syntax">"unknown datum in header line of example file"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><a href="7-dc.html#SP3" class="function-link"><span class="function-syntax">DocumentationCompiler::example_error</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">ess</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">I</span><span class="string-syntax">"header line of example file is malformed"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Regexp::dispose_of</span><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">ess</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">body_text</span><span class="plain-syntax">, </span><span class="string-syntax">"%S\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">text</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>&#167;5. </b></p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">compiled_documentation</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationCompiler::compile_from_file</span><button class="popup" onclick="togglePopup('usagePopup5')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup5">Usage of <span class="code-font"><span class="function-syntax">DocumentationCompiler::compile_from_file</span></span>:<br/><a href="7-dc.html#SP2">&#167;2</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">associated_extension</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">temp</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TextFiles::read</span><span class="plain-syntax">(</span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">, </span><span class="string-syntax">"unable to read file of documentation"</span><span class="plain-syntax">, </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> &amp;</span><a href="7-dc.html#SP2" class="function-link"><span class="function-syntax">DocumentationCompiler::read_file_helper</span></a><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, </span><span class="identifier-syntax">temp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> &amp;</span><a href="7-dc.html#SP5" class="function-link"><span class="function-syntax">DocumentationCompiler::read_file_helper</span></a><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, </span><span class="identifier-syntax">temp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">compiled_documentation</span><span class="plain-syntax"> *</span><span class="identifier-syntax">cd</span><span class="plain-syntax"> =</span>
<span class="plain-syntax"> </span><a href="7-dc.html#SP3" class="function-link"><span class="function-syntax">DocumentationCompiler::compile</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">temp</span><span class="plain-syntax">, </span><span class="identifier-syntax">associated_extension</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="7-dc.html#SP6" class="function-link"><span class="function-syntax">DocumentationCompiler::compile</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">temp</span><span class="plain-syntax">, </span><span class="identifier-syntax">associated_extension</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">temp</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">cd</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
@ -111,11 +314,11 @@ it's really not much more than the tree produced by <a href="7-dt.html" class="i
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">contents</span><span class="plain-syntax">, </span><span class="string-syntax">"%S\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">text</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>&#167;3. </b>...or from text:
<p class="commentary firstcommentary"><a id="SP6" class="paragraph-anchor"></a><b>&#167;6. </b>...or from text:
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">compiled_documentation</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationCompiler::compile</span><button class="popup" onclick="togglePopup('usagePopup2')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup2">Usage of <span class="code-font"><span class="function-syntax">DocumentationCompiler::compile</span></span>:<br/><a href="7-dc.html#SP2">&#167;2</a><br/>Extension Services - <a href="5-es.html#SP10">&#167;10</a>, <a href="5-es.html#SP11_1">&#167;11.1</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">source</span><span class="plain-syntax">,</span>
<span class="reserved-syntax">compiled_documentation</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationCompiler::compile</span><button class="popup" onclick="togglePopup('usagePopup6')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup6">Usage of <span class="code-font"><span class="function-syntax">DocumentationCompiler::compile</span></span>:<br/><a href="7-dc.html#SP2_1_2">&#167;2.1.2</a>, <a href="7-dc.html#SP5">&#167;5</a><br/>Extension Services - <a href="5-es.html#SP10">&#167;10</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">source</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">associated_extension</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">SVEXPLAIN</span><span class="plain-syntax">(1, </span><span class="string-syntax">"(compiling documentation: %d chars)\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">source</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">compiled_documentation</span><span class="plain-syntax"> *</span><span class="identifier-syntax">cd</span><span class="plain-syntax"> = </span><a href="7-dc.html#SP1" class="function-link"><span class="function-syntax">DocumentationCompiler::new_wrapper</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">source</span><span class="plain-syntax">);</span>
@ -123,7 +326,7 @@ it's really not much more than the tree produced by <a href="7-dt.html" class="i
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">associated_extension</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">title</span><span class="plain-syntax">, </span><span class="string-syntax">"%X"</span><span class="plain-syntax">, </span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">associated_extension</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_copy</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">edition</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">work</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::is_whitespace</span><span class="plain-syntax">(</span><span class="identifier-syntax">source</span><span class="plain-syntax">)) </span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">empty</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1" class="named-paragraph-link"><span class="named-paragraph">Parse the source</span><span class="named-paragraph-number">3.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1" class="named-paragraph-link"><span class="named-paragraph">Parse the source</span><span class="named-paragraph-number">6.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">empty</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">SVEXPLAIN</span><span class="plain-syntax">(1, </span><span class="string-syntax">"(resulting tree is empty)\n"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
@ -133,12 +336,12 @@ it's really not much more than the tree produced by <a href="7-dt.html" class="i
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">cd</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP3_1" class="paragraph-anchor"></a><b>&#167;3.1. </b>The source material is line-based, with semantic content sometimes spreading
<p class="commentary firstcommentary"><a id="SP6_1" class="paragraph-anchor"></a><b>&#167;6.1. </b>The source material is line-based, with semantic content sometimes spreading
across multiple lines, so we'll need to keep track of some state as we read
one line at a time:
</p>
<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Parse the source</span><span class="named-paragraph-number">3.1</span></span><span class="comment-syntax"> =</span>
<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Parse the source</span><span class="named-paragraph-number">6.1</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
@ -157,18 +360,18 @@ one line at a time:
<span class="plain-syntax"> *</span><span class="identifier-syntax">last_paste_code</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">; </span><span class="comment-syntax"> last code sample with a paste button</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">pending_code_sample_blanks</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">, </span><span class="identifier-syntax">code_is_tabular</span><span class="plain-syntax"> = </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">; </span><span class="comment-syntax"> used only when assembling code samples</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">programming_language</span><span class="plain-syntax"> *</span><span class="identifier-syntax">default_language</span><span class="plain-syntax"> = </span><a href="7-dc.html#SP4" class="function-link"><span class="function-syntax">DocumentationCompiler::get_language</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="string-syntax">"Inform"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">programming_language</span><span class="plain-syntax"> *</span><span class="identifier-syntax">default_language</span><span class="plain-syntax"> = </span><a href="7-dc.html#SP7" class="function-link"><span class="function-syntax">DocumentationCompiler::get_language</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="string-syntax">"Inform"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">programming_language</span><span class="plain-syntax"> *</span><span class="identifier-syntax">language</span><span class="plain-syntax"> = </span><span class="identifier-syntax">default_language</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1" class="named-paragraph-link"><span class="named-paragraph">Parse the source linewise</span><span class="named-paragraph-number">3.1.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1" class="named-paragraph-link"><span class="named-paragraph">Parse the source linewise</span><span class="named-paragraph-number">6.1.1</span></a></span><span class="plain-syntax">;</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP3">&#167;3</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP3_1_1" class="paragraph-anchor"></a><b>&#167;3.1.1. </b>Leading space on a line is removed but not ignored: it is converted into an
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP6">&#167;6</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP6_1_1" class="paragraph-anchor"></a><b>&#167;6.1.1. </b>Leading space on a line is removed but not ignored: it is converted into an
indentation level, measured as a tab count, using the exchange rate 4 spaces
to 1 tab.
</p>
<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Parse the source linewise</span><span class="named-paragraph-number">3.1.1</span></span><span class="comment-syntax"> =</span>
<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Parse the source linewise</span><span class="named-paragraph-number">6.1.1</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
@ -177,7 +380,7 @@ to 1 tab.
<span class="plain-syntax"> </span><span class="reserved-syntax">for</span><span class="plain-syntax"> (</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">i</span><span class="plain-syntax">=0; </span><span class="identifier-syntax">i</span><span class="plain-syntax">&lt;</span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">source</span><span class="plain-syntax">); </span><span class="identifier-syntax">i</span><span class="plain-syntax">++) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wchar_t</span><span class="plain-syntax"> </span><span class="identifier-syntax">c</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::get_at</span><span class="plain-syntax">(</span><span class="identifier-syntax">source</span><span class="plain-syntax">, </span><span class="identifier-syntax">i</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">c</span><span class="plain-syntax"> == </span><span class="character-syntax">'\n'</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1" class="named-paragraph-link"><span class="named-paragraph">Line read</span><span class="named-paragraph-number">3.1.1.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1" class="named-paragraph-link"><span class="named-paragraph">Line read</span><span class="named-paragraph-number">6.1.1.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Str::clear</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">indentation</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">; </span><span class="identifier-syntax">space_count</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">) == </span><span class="constant-syntax">0</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">Characters::is_whitespace</span><span class="plain-syntax">(</span><span class="identifier-syntax">c</span><span class="plain-syntax">))) {</span>
@ -188,13 +391,13 @@ to 1 tab.
<span class="plain-syntax"> </span><span class="identifier-syntax">PUT_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="identifier-syntax">c</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">) &gt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1" class="named-paragraph-link"><span class="named-paragraph">Line read</span><span class="named-paragraph-number">3.1.1.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_2" class="named-paragraph-link"><span class="named-paragraph">Check for runaway phrase definitions</span><span class="named-paragraph-number">3.1.1.2</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_3" class="named-paragraph-link"><span class="named-paragraph">Complete passage if in one</span><span class="named-paragraph-number">3.1.1.3</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">) &gt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1" class="named-paragraph-link"><span class="named-paragraph">Line read</span><span class="named-paragraph-number">6.1.1.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_2" class="named-paragraph-link"><span class="named-paragraph">Check for runaway phrase definitions</span><span class="named-paragraph-number">6.1.1.2</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_3" class="named-paragraph-link"><span class="named-paragraph">Complete passage if in one</span><span class="named-paragraph-number">6.1.1.3</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">)</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP3_1">&#167;3.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP3_1_1_1" class="paragraph-anchor"></a><b>&#167;3.1.1.1. </b>Trailing space is ignored and removed.
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP6_1">&#167;6.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP6_1_1_1" class="paragraph-anchor"></a><b>&#167;6.1.1.1. </b>Trailing space is ignored and removed.
</p>
<p class="commentary">Lines which are unindented and take the following shapes are headings:
@ -214,33 +417,33 @@ may either end or continue code samples; unindented lines, which are always
part of paragraphs; or indented ones, which are always part of code samples.
</p>
<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Line read</span><span class="named-paragraph-number">3.1.1.1</span></span><span class="comment-syntax"> =</span>
<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Line read</span><span class="named-paragraph-number">6.1.1.1</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="identifier-syntax">Str::trim_white_space</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">) == </span><span class="constant-syntax">0</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">current_paragraph</span><span class="plain-syntax">) </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_7" class="named-paragraph-link"><span class="named-paragraph">Complete paragraph or code</span><span class="named-paragraph-number">3.1.1.1.7</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">current_code</span><span class="plain-syntax">) </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_12" class="named-paragraph-link"><span class="named-paragraph">Insert line break in code</span><span class="named-paragraph-number">3.1.1.1.12</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">current_paragraph</span><span class="plain-syntax">) </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_7" class="named-paragraph-link"><span class="named-paragraph">Complete paragraph or code</span><span class="named-paragraph-number">6.1.1.1.7</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">current_code</span><span class="plain-syntax">) </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_12" class="named-paragraph-link"><span class="named-paragraph">Insert line break in code</span><span class="named-paragraph-number">6.1.1.1.12</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">indentation</span><span class="plain-syntax"> == </span><span class="constant-syntax">0</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">match_results</span><span class="plain-syntax"> </span><span class="identifier-syntax">mr</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Regexp::create_mr</span><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">Regexp::match</span><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"Section *: *(%c+?)"</span><span class="plain-syntax">)) ||</span>
<span class="plain-syntax"> (</span><span class="identifier-syntax">Regexp::match</span><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"Section *- *(%c+?)"</span><span class="plain-syntax">))) {</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_2" class="named-paragraph-link"><span class="named-paragraph">Insert a section heading</span><span class="named-paragraph-number">3.1.1.1.2</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_2" class="named-paragraph-link"><span class="named-paragraph">Insert a section heading</span><span class="named-paragraph-number">6.1.1.1.2</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">Regexp::match</span><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"Chapter *: *(%c+?)"</span><span class="plain-syntax">)) ||</span>
<span class="plain-syntax"> (</span><span class="identifier-syntax">Regexp::match</span><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"Chapter *- *(%c+?)"</span><span class="plain-syntax">))) {</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_1" class="named-paragraph-link"><span class="named-paragraph">Insert a chapter heading</span><span class="named-paragraph-number">3.1.1.1.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_1" class="named-paragraph-link"><span class="named-paragraph">Insert a chapter heading</span><span class="named-paragraph-number">6.1.1.1.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">Regexp::match</span><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"Example *: *(%**) *(%c+?)"</span><span class="plain-syntax">)) ||</span>
<span class="plain-syntax"> (</span><span class="identifier-syntax">Regexp::match</span><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"Example *- *(%**) *(%c+?)"</span><span class="plain-syntax">))) {</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_3" class="named-paragraph-link"><span class="named-paragraph">Insert an example heading</span><span class="named-paragraph-number">3.1.1.1.3</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_3" class="named-paragraph-link"><span class="named-paragraph">Insert an example heading</span><span class="named-paragraph-number">6.1.1.1.3</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Regexp::match</span><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"{defn *(%c*?)} *(%c+)"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_4" class="named-paragraph-link"><span class="named-paragraph">Begin a phrase definition</span><span class="named-paragraph-number">3.1.1.1.4</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_4" class="named-paragraph-link"><span class="named-paragraph">Begin a phrase definition</span><span class="named-paragraph-number">6.1.1.1.4</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Regexp::match</span><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"{end}"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_5" class="named-paragraph-link"><span class="named-paragraph">End a phrase definition</span><span class="named-paragraph-number">3.1.1.1.5</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_5" class="named-paragraph-link"><span class="named-paragraph">End a phrase definition</span><span class="named-paragraph-number">6.1.1.1.5</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">current_paragraph</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_8" class="named-paragraph-link"><span class="named-paragraph">Begin paragraph</span><span class="named-paragraph-number">3.1.1.1.8</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_9" class="named-paragraph-link"><span class="named-paragraph">Insert space in paragraph</span><span class="named-paragraph-number">3.1.1.1.9</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_10" class="named-paragraph-link"><span class="named-paragraph">Insert line in paragraph</span><span class="named-paragraph-number">3.1.1.1.10</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">current_paragraph</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_8" class="named-paragraph-link"><span class="named-paragraph">Begin paragraph</span><span class="named-paragraph-number">6.1.1.1.8</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_9" class="named-paragraph-link"><span class="named-paragraph">Insert space in paragraph</span><span class="named-paragraph-number">6.1.1.1.9</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_10" class="named-paragraph-link"><span class="named-paragraph">Insert line in paragraph</span><span class="named-paragraph-number">6.1.1.1.10</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Regexp::dispose_of</span><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
@ -251,10 +454,10 @@ part of paragraphs; or indented ones, which are always part of code samples.
<span class="plain-syntax"> </span><span class="identifier-syntax">Str::delete_n_characters</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="constant-syntax">4</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Str::delete_last_character</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Str::trim_white_space</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">language</span><span class="plain-syntax"> = </span><a href="7-dc.html#SP4" class="function-link"><span class="function-syntax">DocumentationCompiler::get_language</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">language</span><span class="plain-syntax"> = </span><a href="7-dc.html#SP7" class="function-link"><span class="function-syntax">DocumentationCompiler::get_language</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">language</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_7" class="named-paragraph-link"><span class="named-paragraph">Complete paragraph or code</span><span class="named-paragraph-number">3.1.1.1.7</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_6" class="named-paragraph-link"><span class="named-paragraph">Begin passage if not already in one</span><span class="named-paragraph-number">3.1.1.1.6</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_7" class="named-paragraph-link"><span class="named-paragraph">Complete paragraph or code</span><span class="named-paragraph-number">6.1.1.1.7</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_6" class="named-paragraph-link"><span class="named-paragraph">Begin passage if not already in one</span><span class="named-paragraph-number">6.1.1.1.6</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">err</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">err</span><span class="plain-syntax">, </span><span class="string-syntax">"cannot find a language called '%S'"</span><span class="plain-syntax">, </span><span class="identifier-syntax">line</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax"> = </span><a href="7-dt.html#SP15" class="function-link"><span class="function-syntax">DocumentationTree::new_source_error</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tree</span><span class="plain-syntax">, </span><span class="identifier-syntax">err</span><span class="plain-syntax">);</span>
@ -262,102 +465,102 @@ part of paragraphs; or indented ones, which are always part of code samples.
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">err</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_11" class="named-paragraph-link"><span class="named-paragraph">Begin code</span><span class="named-paragraph-number">3.1.1.1.11</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_13" class="named-paragraph-link"><span class="named-paragraph">Insert line in code sample</span><span class="named-paragraph-number">3.1.1.1.13</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_11" class="named-paragraph-link"><span class="named-paragraph">Begin code</span><span class="named-paragraph-number">6.1.1.1.11</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_13" class="named-paragraph-link"><span class="named-paragraph">Insert line in code sample</span><span class="named-paragraph-number">6.1.1.1.13</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_13" class="named-paragraph-link"><span class="named-paragraph">Insert line in code sample</span><span class="named-paragraph-number">3.1.1.1.13</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_13" class="named-paragraph-link"><span class="named-paragraph">Insert line in code sample</span><span class="named-paragraph-number">6.1.1.1.13</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> }</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP3_1_1">&#167;3.1.1</a> (twice).</li></ul>
<p class="commentary firstcommentary"><a id="SP3_1_1_1_1" class="paragraph-anchor"></a><b>&#167;3.1.1.1.1. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Insert a chapter heading</span><span class="named-paragraph-number">3.1.1.1.1</span></span><span class="comment-syntax"> =</span>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP6_1_1">&#167;6.1.1</a> (twice).</li></ul>
<p class="commentary firstcommentary"><a id="SP6_1_1_1_1" class="paragraph-anchor"></a><b>&#167;6.1.1.1.1. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Insert a chapter heading</span><span class="named-paragraph-number">6.1.1.1.1</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_3" class="named-paragraph-link"><span class="named-paragraph">Complete passage if in one</span><span class="named-paragraph-number">3.1.1.3</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_3" class="named-paragraph-link"><span class="named-paragraph">Complete passage if in one</span><span class="named-paragraph-number">6.1.1.3</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">chapter_number</span><span class="plain-syntax">++;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">section_number</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">level</span><span class="plain-syntax"> = </span><span class="constant-syntax">1</span><span class="plain-syntax">, </span><span class="identifier-syntax">id</span><span class="plain-syntax"> = </span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">total_headings</span><span class="plain-syntax">[0] + </span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">total_headings</span><span class="plain-syntax">[1] + </span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">total_headings</span><span class="plain-syntax">[2];</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">total_headings</span><span class="plain-syntax">[1]++;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">new_node</span><span class="plain-syntax"> = </span><a href="7-dt.html#SP3" class="function-link"><span class="function-syntax">DocumentationTree::new_heading</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tree</span><span class="plain-syntax">, </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="identifier-syntax">exp</span><span class="plain-syntax">[0], </span><span class="identifier-syntax">level</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">new_node</span><span class="plain-syntax"> = </span><a href="7-dt.html#SP3" class="function-link"><span class="function-syntax">DocumentationTree::new_heading</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tree</span><span class="plain-syntax">, </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="identifier-syntax">exp</span><span class="plain-syntax">[0], </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="identifier-syntax">exp</span><span class="plain-syntax">[0], </span><span class="identifier-syntax">level</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="identifier-syntax">chapter_number</span><span class="plain-syntax">, </span><span class="identifier-syntax">section_number</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_1_1" class="named-paragraph-link"><span class="named-paragraph">Place this new structural node in the tree</span><span class="named-paragraph-number">3.1.1.1.1.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_1_1" class="named-paragraph-link"><span class="named-paragraph">Place this new structural node in the tree</span><span class="named-paragraph-number">6.1.1.1.1.1</span></a></span><span class="plain-syntax">;</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP3_1_1_1">&#167;3.1.1.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP3_1_1_1_2" class="paragraph-anchor"></a><b>&#167;3.1.1.1.2. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Insert a section heading</span><span class="named-paragraph-number">3.1.1.1.2</span></span><span class="comment-syntax"> =</span>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP6_1_1_1">&#167;6.1.1.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP6_1_1_1_2" class="paragraph-anchor"></a><b>&#167;6.1.1.1.2. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Insert a section heading</span><span class="named-paragraph-number">6.1.1.1.2</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_3" class="named-paragraph-link"><span class="named-paragraph">Complete passage if in one</span><span class="named-paragraph-number">3.1.1.3</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_3" class="named-paragraph-link"><span class="named-paragraph">Complete passage if in one</span><span class="named-paragraph-number">6.1.1.3</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">section_number</span><span class="plain-syntax">++;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">level</span><span class="plain-syntax"> = </span><span class="constant-syntax">2</span><span class="plain-syntax">, </span><span class="identifier-syntax">id</span><span class="plain-syntax"> = </span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">total_headings</span><span class="plain-syntax">[0] + </span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">total_headings</span><span class="plain-syntax">[1] + </span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">total_headings</span><span class="plain-syntax">[2];</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">total_headings</span><span class="plain-syntax">[2]++;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">new_node</span><span class="plain-syntax"> = </span><a href="7-dt.html#SP3" class="function-link"><span class="function-syntax">DocumentationTree::new_heading</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tree</span><span class="plain-syntax">, </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="identifier-syntax">exp</span><span class="plain-syntax">[0], </span><span class="identifier-syntax">level</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">new_node</span><span class="plain-syntax"> = </span><a href="7-dt.html#SP3" class="function-link"><span class="function-syntax">DocumentationTree::new_heading</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tree</span><span class="plain-syntax">, </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="identifier-syntax">exp</span><span class="plain-syntax">[0], </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="identifier-syntax">exp</span><span class="plain-syntax">[0], </span><span class="identifier-syntax">level</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="identifier-syntax">chapter_number</span><span class="plain-syntax">, </span><span class="identifier-syntax">section_number</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_1_1" class="named-paragraph-link"><span class="named-paragraph">Place this new structural node in the tree</span><span class="named-paragraph-number">3.1.1.1.1.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_1_1" class="named-paragraph-link"><span class="named-paragraph">Place this new structural node in the tree</span><span class="named-paragraph-number">6.1.1.1.1.1</span></a></span><span class="plain-syntax">;</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP3_1_1_1">&#167;3.1.1.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP3_1_1_1_3" class="paragraph-anchor"></a><b>&#167;3.1.1.1.3. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Insert an example heading</span><span class="named-paragraph-number">3.1.1.1.3</span></span><span class="comment-syntax"> =</span>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP6_1_1_1">&#167;6.1.1.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP6_1_1_1_3" class="paragraph-anchor"></a><b>&#167;6.1.1.1.3. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Insert an example heading</span><span class="named-paragraph-number">6.1.1.1.3</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_3" class="named-paragraph-link"><span class="named-paragraph">Complete passage if in one</span><span class="named-paragraph-number">3.1.1.3</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_3" class="named-paragraph-link"><span class="named-paragraph">Complete passage if in one</span><span class="named-paragraph-number">6.1.1.3</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">level</span><span class="plain-syntax"> = </span><span class="constant-syntax">3</span><span class="plain-syntax">, </span><span class="identifier-syntax">star_count</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="identifier-syntax">exp</span><span class="plain-syntax">[0]);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">new_node</span><span class="plain-syntax"> = </span><a href="7-dt.html#SP5" class="function-link"><span class="function-syntax">DocumentationTree::new_example</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tree</span><span class="plain-syntax">, </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="identifier-syntax">exp</span><span class="plain-syntax">[1],</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">new_node</span><span class="plain-syntax"> = </span><a href="7-dt.html#SP5" class="function-link"><span class="function-syntax">DocumentationTree::new_example</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tree</span><span class="plain-syntax">, </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="identifier-syntax">exp</span><span class="plain-syntax">[1], </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">star_count</span><span class="plain-syntax">, ++(</span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">total_examples</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_1_1" class="named-paragraph-link"><span class="named-paragraph">Place this new structural node in the tree</span><span class="named-paragraph-number">3.1.1.1.1.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_1_1" class="named-paragraph-link"><span class="named-paragraph">Place this new structural node in the tree</span><span class="named-paragraph-number">6.1.1.1.1.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">star_count</span><span class="plain-syntax"> == </span><span class="constant-syntax">0</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_6" class="named-paragraph-link"><span class="named-paragraph">Begin passage if not already in one</span><span class="named-paragraph-number">3.1.1.1.6</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_6" class="named-paragraph-link"><span class="named-paragraph">Begin passage if not already in one</span><span class="named-paragraph-number">6.1.1.1.6</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax"> = </span><a href="7-dt.html#SP15" class="function-link"><span class="function-syntax">DocumentationTree::new_source_error</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tree</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">I</span><span class="string-syntax">"this example should be marked (before the title) '*', '**', '***' or '****' for difficulty"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Trees::make_child</span><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">, </span><span class="identifier-syntax">current_passage</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">star_count</span><span class="plain-syntax"> &gt; </span><span class="constant-syntax">4</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_6" class="named-paragraph-link"><span class="named-paragraph">Begin passage if not already in one</span><span class="named-paragraph-number">3.1.1.1.6</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_6" class="named-paragraph-link"><span class="named-paragraph">Begin passage if not already in one</span><span class="named-paragraph-number">6.1.1.1.6</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax"> = </span><a href="7-dt.html#SP15" class="function-link"><span class="function-syntax">DocumentationTree::new_source_error</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tree</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">I</span><span class="string-syntax">"four stars '****' is the maximum difficulty rating allowed"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Trees::make_child</span><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">, </span><span class="identifier-syntax">current_passage</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP3_1_1_1">&#167;3.1.1.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP3_1_1_1_4" class="paragraph-anchor"></a><b>&#167;3.1.1.1.4. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Begin a phrase definition</span><span class="named-paragraph-number">3.1.1.1.4</span></span><span class="comment-syntax"> =</span>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP6_1_1_1">&#167;6.1.1.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP6_1_1_1_4" class="paragraph-anchor"></a><b>&#167;6.1.1.1.4. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Begin a phrase definition</span><span class="named-paragraph-number">6.1.1.1.4</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_2" class="named-paragraph-link"><span class="named-paragraph">Check for runaway phrase definitions</span><span class="named-paragraph-number">3.1.1.2</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_2" class="named-paragraph-link"><span class="named-paragraph">Check for runaway phrase definitions</span><span class="named-paragraph-number">6.1.1.2</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">current_phrase_defn</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_6" class="named-paragraph-link"><span class="named-paragraph">Begin passage if not already in one</span><span class="named-paragraph-number">3.1.1.1.6</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_7" class="named-paragraph-link"><span class="named-paragraph">Complete paragraph or code</span><span class="named-paragraph-number">3.1.1.1.7</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_6" class="named-paragraph-link"><span class="named-paragraph">Begin passage if not already in one</span><span class="named-paragraph-number">6.1.1.1.6</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_7" class="named-paragraph-link"><span class="named-paragraph">Complete paragraph or code</span><span class="named-paragraph-number">6.1.1.1.7</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">current_phrase_defn</span><span class="plain-syntax"> =</span>
<span class="plain-syntax"> </span><a href="7-dt.html#SP9" class="function-link"><span class="function-syntax">DocumentationTree::new_phrase_defn</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tree</span><span class="plain-syntax">, </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="identifier-syntax">exp</span><span class="plain-syntax">[0], </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="identifier-syntax">exp</span><span class="plain-syntax">[1]);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Trees::make_child</span><span class="plain-syntax">(</span><span class="identifier-syntax">current_phrase_defn</span><span class="plain-syntax">, </span><span class="identifier-syntax">current_passage</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_3" class="named-paragraph-link"><span class="named-paragraph">Complete passage if in one</span><span class="named-paragraph-number">3.1.1.3</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_3" class="named-paragraph-link"><span class="named-paragraph">Complete passage if in one</span><span class="named-paragraph-number">6.1.1.3</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP3_1_1_1">&#167;3.1.1.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP3_1_1_1_5" class="paragraph-anchor"></a><b>&#167;3.1.1.1.5. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">End a phrase definition</span><span class="named-paragraph-number">3.1.1.1.5</span></span><span class="comment-syntax"> =</span>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP6_1_1_1">&#167;6.1.1.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP6_1_1_1_5" class="paragraph-anchor"></a><b>&#167;6.1.1.1.5. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">End a phrase definition</span><span class="named-paragraph-number">6.1.1.1.5</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">current_phrase_defn</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_3" class="named-paragraph-link"><span class="named-paragraph">Complete passage if in one</span><span class="named-paragraph-number">3.1.1.3</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_3" class="named-paragraph-link"><span class="named-paragraph">Complete passage if in one</span><span class="named-paragraph-number">6.1.1.3</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">current_passage</span><span class="plain-syntax"> = </span><span class="identifier-syntax">current_phrase_defn</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">parent</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">current_phrase_defn</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_6" class="named-paragraph-link"><span class="named-paragraph">Begin passage if not already in one</span><span class="named-paragraph-number">3.1.1.1.6</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_6" class="named-paragraph-link"><span class="named-paragraph">Begin passage if not already in one</span><span class="named-paragraph-number">6.1.1.1.6</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax"> = </span><a href="7-dt.html#SP15" class="function-link"><span class="function-syntax">DocumentationTree::new_source_error</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tree</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">I</span><span class="string-syntax">"{end} without {defn}"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Trees::make_child</span><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">, </span><span class="identifier-syntax">current_passage</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">language</span><span class="plain-syntax"> = </span><span class="identifier-syntax">default_language</span><span class="plain-syntax">;</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP3_1_1_1">&#167;3.1.1.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP3_1_1_1_1_1" class="paragraph-anchor"></a><b>&#167;3.1.1.1.1.1. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Place this new structural node in the tree</span><span class="named-paragraph-number">3.1.1.1.1.1</span></span><span class="comment-syntax"> =</span>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP6_1_1_1">&#167;6.1.1.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP6_1_1_1_1_1" class="paragraph-anchor"></a><b>&#167;6.1.1.1.1.1. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Place this new structural node in the tree</span><span class="named-paragraph-number">6.1.1.1.1.1</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_2" class="named-paragraph-link"><span class="named-paragraph">Check for runaway phrase definitions</span><span class="named-paragraph-number">3.1.1.2</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_2" class="named-paragraph-link"><span class="named-paragraph">Check for runaway phrase definitions</span><span class="named-paragraph-number">6.1.1.2</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">for</span><span class="plain-syntax"> (</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">j</span><span class="plain-syntax">=</span><span class="identifier-syntax">level</span><span class="plain-syntax">-1; </span><span class="identifier-syntax">j</span><span class="plain-syntax">&gt;=0; </span><span class="identifier-syntax">j</span><span class="plain-syntax">--)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">current_headings</span><span class="plain-syntax">[</span><span class="identifier-syntax">j</span><span class="plain-syntax">]) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Trees::make_child</span><span class="plain-syntax">(</span><span class="identifier-syntax">new_node</span><span class="plain-syntax">, </span><span class="identifier-syntax">current_headings</span><span class="plain-syntax">[</span><span class="identifier-syntax">j</span><span class="plain-syntax">]);</span>
@ -367,21 +570,21 @@ part of paragraphs; or indented ones, which are always part of code samples.
<span class="plain-syntax"> </span><span class="reserved-syntax">for</span><span class="plain-syntax"> (</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">j</span><span class="plain-syntax">=</span><span class="identifier-syntax">level</span><span class="plain-syntax">+1; </span><span class="identifier-syntax">j</span><span class="plain-syntax">&lt;4; </span><span class="identifier-syntax">j</span><span class="plain-syntax">++) </span><span class="identifier-syntax">current_headings</span><span class="plain-syntax">[</span><span class="identifier-syntax">j</span><span class="plain-syntax">] = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">language</span><span class="plain-syntax"> = </span><span class="identifier-syntax">default_language</span><span class="plain-syntax">;</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP3_1_1_1_1">&#167;3.1.1.1.1</a>, <a href="7-dc.html#SP3_1_1_1_2">&#167;3.1.1.1.2</a>, <a href="7-dc.html#SP3_1_1_1_3">&#167;3.1.1.1.3</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP3_1_1_2" class="paragraph-anchor"></a><b>&#167;3.1.1.2. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Check for runaway phrase definitions</span><span class="named-paragraph-number">3.1.1.2</span></span><span class="comment-syntax"> =</span>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP6_1_1_1_1">&#167;6.1.1.1.1</a>, <a href="7-dc.html#SP6_1_1_1_2">&#167;6.1.1.1.2</a>, <a href="7-dc.html#SP6_1_1_1_3">&#167;6.1.1.1.3</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP6_1_1_2" class="paragraph-anchor"></a><b>&#167;6.1.1.2. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Check for runaway phrase definitions</span><span class="named-paragraph-number">6.1.1.2</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">current_phrase_defn</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_6" class="named-paragraph-link"><span class="named-paragraph">Begin passage if not already in one</span><span class="named-paragraph-number">3.1.1.1.6</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_6" class="named-paragraph-link"><span class="named-paragraph">Begin passage if not already in one</span><span class="named-paragraph-number">6.1.1.1.6</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax"> = </span><a href="7-dt.html#SP15" class="function-link"><span class="function-syntax">DocumentationTree::new_source_error</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tree</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">I</span><span class="string-syntax">"{defn} has no {end}"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Trees::make_child</span><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">, </span><span class="identifier-syntax">current_passage</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">current_phrase_defn</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP3_1_1">&#167;3.1.1</a>, <a href="7-dc.html#SP3_1_1_1_4">&#167;3.1.1.1.4</a>, <a href="7-dc.html#SP3_1_1_1_1_1">&#167;3.1.1.1.1.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP3_1_1_1_6" class="paragraph-anchor"></a><b>&#167;3.1.1.1.6. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Begin passage if not already in one</span><span class="named-paragraph-number">3.1.1.1.6</span></span><span class="comment-syntax"> =</span>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP6_1_1">&#167;6.1.1</a>, <a href="7-dc.html#SP6_1_1_1_4">&#167;6.1.1.1.4</a>, <a href="7-dc.html#SP6_1_1_1_1_1">&#167;6.1.1.1.1.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP6_1_1_1_6" class="paragraph-anchor"></a><b>&#167;6.1.1.1.6. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Begin passage if not already in one</span><span class="named-paragraph-number">6.1.1.1.6</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
@ -397,56 +600,56 @@ part of paragraphs; or indented ones, which are always part of code samples.
<span class="plain-syntax"> </span><span class="identifier-syntax">current_paragraph</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP3_1_1_1">&#167;3.1.1.1</a>, <a href="7-dc.html#SP3_1_1_1_3">&#167;3.1.1.1.3</a> (twice), <a href="7-dc.html#SP3_1_1_1_4">&#167;3.1.1.1.4</a>, <a href="7-dc.html#SP3_1_1_1_5">&#167;3.1.1.1.5</a>, <a href="7-dc.html#SP3_1_1_2">&#167;3.1.1.2</a>, <a href="7-dc.html#SP3_1_1_1_8">&#167;3.1.1.1.8</a>, <a href="7-dc.html#SP3_1_1_1_11">&#167;3.1.1.1.11</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP3_1_1_3" class="paragraph-anchor"></a><b>&#167;3.1.1.3. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Complete passage if in one</span><span class="named-paragraph-number">3.1.1.3</span></span><span class="comment-syntax"> =</span>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP6_1_1_1">&#167;6.1.1.1</a>, <a href="7-dc.html#SP6_1_1_1_3">&#167;6.1.1.1.3</a> (twice), <a href="7-dc.html#SP6_1_1_1_4">&#167;6.1.1.1.4</a>, <a href="7-dc.html#SP6_1_1_1_5">&#167;6.1.1.1.5</a>, <a href="7-dc.html#SP6_1_1_2">&#167;6.1.1.2</a>, <a href="7-dc.html#SP6_1_1_1_8">&#167;6.1.1.1.8</a>, <a href="7-dc.html#SP6_1_1_1_11">&#167;6.1.1.1.11</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP6_1_1_3" class="paragraph-anchor"></a><b>&#167;6.1.1.3. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Complete passage if in one</span><span class="named-paragraph-number">6.1.1.3</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">current_passage</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_7" class="named-paragraph-link"><span class="named-paragraph">Complete paragraph or code</span><span class="named-paragraph-number">3.1.1.1.7</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_7" class="named-paragraph-link"><span class="named-paragraph">Complete paragraph or code</span><span class="named-paragraph-number">6.1.1.1.7</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">current_passage</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP3_1_1">&#167;3.1.1</a>, <a href="7-dc.html#SP3_1_1_1_1">&#167;3.1.1.1.1</a>, <a href="7-dc.html#SP3_1_1_1_2">&#167;3.1.1.1.2</a>, <a href="7-dc.html#SP3_1_1_1_3">&#167;3.1.1.1.3</a>, <a href="7-dc.html#SP3_1_1_1_4">&#167;3.1.1.1.4</a>, <a href="7-dc.html#SP3_1_1_1_5">&#167;3.1.1.1.5</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP3_1_1_1_7" class="paragraph-anchor"></a><b>&#167;3.1.1.1.7. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Complete paragraph or code</span><span class="named-paragraph-number">3.1.1.1.7</span></span><span class="comment-syntax"> =</span>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP6_1_1">&#167;6.1.1</a>, <a href="7-dc.html#SP6_1_1_1_1">&#167;6.1.1.1.1</a>, <a href="7-dc.html#SP6_1_1_1_2">&#167;6.1.1.1.2</a>, <a href="7-dc.html#SP6_1_1_1_3">&#167;6.1.1.1.3</a>, <a href="7-dc.html#SP6_1_1_1_4">&#167;6.1.1.1.4</a>, <a href="7-dc.html#SP6_1_1_1_5">&#167;6.1.1.1.5</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP6_1_1_1_7" class="paragraph-anchor"></a><b>&#167;6.1.1.1.7. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Complete paragraph or code</span><span class="named-paragraph-number">6.1.1.1.7</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">current_paragraph</span><span class="plain-syntax">) </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_7_1" class="named-paragraph-link"><span class="named-paragraph">Complete paragraph</span><span class="named-paragraph-number">3.1.1.1.7.1</span></a></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">current_code</span><span class="plain-syntax">) </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_7_2" class="named-paragraph-link"><span class="named-paragraph">Complete code</span><span class="named-paragraph-number">3.1.1.1.7.2</span></a></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">current_paragraph</span><span class="plain-syntax">) </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_7_1" class="named-paragraph-link"><span class="named-paragraph">Complete paragraph</span><span class="named-paragraph-number">6.1.1.1.7.1</span></a></span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">current_code</span><span class="plain-syntax">) </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_7_2" class="named-paragraph-link"><span class="named-paragraph">Complete code</span><span class="named-paragraph-number">6.1.1.1.7.2</span></a></span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP3_1_1_1">&#167;3.1.1.1</a> (twice), <a href="7-dc.html#SP3_1_1_1_4">&#167;3.1.1.1.4</a>, <a href="7-dc.html#SP3_1_1_3">&#167;3.1.1.3</a>, <a href="7-dc.html#SP3_1_1_1_8">&#167;3.1.1.1.8</a>, <a href="7-dc.html#SP3_1_1_1_11">&#167;3.1.1.1.11</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP3_1_1_1_8" class="paragraph-anchor"></a><b>&#167;3.1.1.1.8. </b>Line breaks are treated as spaces in the content of a paragraph, so that
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP6_1_1_1">&#167;6.1.1.1</a> (twice), <a href="7-dc.html#SP6_1_1_1_4">&#167;6.1.1.1.4</a>, <a href="7-dc.html#SP6_1_1_3">&#167;6.1.1.3</a>, <a href="7-dc.html#SP6_1_1_1_8">&#167;6.1.1.1.8</a>, <a href="7-dc.html#SP6_1_1_1_11">&#167;6.1.1.1.11</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP6_1_1_1_8" class="paragraph-anchor"></a><b>&#167;6.1.1.1.8. </b>Line breaks are treated as spaces in the content of a paragraph, so that
<span class="extract"><span class="extract-syntax">P-&gt;content</span></span> here can be a long text but one which contains no line breaks.
</p>
<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Begin paragraph</span><span class="named-paragraph-number">3.1.1.1.8</span></span><span class="comment-syntax"> =</span>
<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Begin paragraph</span><span class="named-paragraph-number">6.1.1.1.8</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_7" class="named-paragraph-link"><span class="named-paragraph">Complete paragraph or code</span><span class="named-paragraph-number">3.1.1.1.7</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_6" class="named-paragraph-link"><span class="named-paragraph">Begin passage if not already in one</span><span class="named-paragraph-number">3.1.1.1.6</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_7" class="named-paragraph-link"><span class="named-paragraph">Complete paragraph or code</span><span class="named-paragraph-number">6.1.1.1.7</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_6" class="named-paragraph-link"><span class="named-paragraph">Begin passage if not already in one</span><span class="named-paragraph-number">6.1.1.1.6</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">current_paragraph</span><span class="plain-syntax"> = </span><a href="7-dt.html#SP11" class="function-link"><span class="function-syntax">DocumentationTree::new_paragraph</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tree</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Trees::make_child</span><span class="plain-syntax">(</span><span class="identifier-syntax">current_paragraph</span><span class="plain-syntax">, </span><span class="identifier-syntax">current_passage</span><span class="plain-syntax">);</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP3_1_1_1">&#167;3.1.1.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP3_1_1_1_9" class="paragraph-anchor"></a><b>&#167;3.1.1.1.9. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Insert space in paragraph</span><span class="named-paragraph-number">3.1.1.1.9</span></span><span class="comment-syntax"> =</span>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP6_1_1_1">&#167;6.1.1.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP6_1_1_1_9" class="paragraph-anchor"></a><b>&#167;6.1.1.1.9. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Insert space in paragraph</span><span class="named-paragraph-number">6.1.1.1.9</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">cdoc_paragraph</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax"> = </span><span class="identifier-syntax">RETRIEVE_POINTER_cdoc_paragraph</span><span class="plain-syntax">(</span><span class="identifier-syntax">current_paragraph</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">content</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">content</span><span class="plain-syntax">) &gt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">content</span><span class="plain-syntax">, </span><span class="string-syntax">" "</span><span class="plain-syntax">);</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP3_1_1_1">&#167;3.1.1.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP3_1_1_1_10" class="paragraph-anchor"></a><b>&#167;3.1.1.1.10. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Insert line in paragraph</span><span class="named-paragraph-number">3.1.1.1.10</span></span><span class="comment-syntax"> =</span>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP6_1_1_1">&#167;6.1.1.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP6_1_1_1_10" class="paragraph-anchor"></a><b>&#167;6.1.1.1.10. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Insert line in paragraph</span><span class="named-paragraph-number">6.1.1.1.10</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">cdoc_paragraph</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax"> = </span><span class="identifier-syntax">RETRIEVE_POINTER_cdoc_paragraph</span><span class="plain-syntax">(</span><span class="identifier-syntax">current_paragraph</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">content</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">content</span><span class="plain-syntax">, </span><span class="string-syntax">"%S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">line</span><span class="plain-syntax">);</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP3_1_1_1">&#167;3.1.1.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP3_1_1_1_7_1" class="paragraph-anchor"></a><b>&#167;3.1.1.1.7.1. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Complete paragraph</span><span class="named-paragraph-number">3.1.1.1.7.1</span></span><span class="comment-syntax"> =</span>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP6_1_1_1">&#167;6.1.1.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP6_1_1_1_7_1" class="paragraph-anchor"></a><b>&#167;6.1.1.1.7.1. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Complete paragraph</span><span class="named-paragraph-number">6.1.1.1.7.1</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
@ -454,18 +657,18 @@ part of paragraphs; or indented ones, which are always part of code samples.
<span class="plain-syntax"> </span><span class="identifier-syntax">current_paragraph</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP3_1_1_1_7">&#167;3.1.1.1.7</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP3_1_1_1_11" class="paragraph-anchor"></a><b>&#167;3.1.1.1.11. </b>Line breaks are more significant in code samples, of course. Blank lines
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP6_1_1_1_7">&#167;6.1.1.1.7</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP6_1_1_1_11" class="paragraph-anchor"></a><b>&#167;6.1.1.1.11. </b>Line breaks are more significant in code samples, of course. Blank lines
at the end of a code sample are stripped out; and they cannot appear at the start
of a code sample either, since a non-blank indented line is needed to trigger one.
</p>
<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Begin code</span><span class="named-paragraph-number">3.1.1.1.11</span></span><span class="comment-syntax"> =</span>
<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Begin code</span><span class="named-paragraph-number">6.1.1.1.11</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_7" class="named-paragraph-link"><span class="named-paragraph">Complete paragraph or code</span><span class="named-paragraph-number">3.1.1.1.7</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP3_1_1_1_6" class="named-paragraph-link"><span class="named-paragraph">Begin passage if not already in one</span><span class="named-paragraph-number">3.1.1.1.6</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_7" class="named-paragraph-link"><span class="named-paragraph">Complete paragraph or code</span><span class="named-paragraph-number">6.1.1.1.7</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="7-dc.html#SP6_1_1_1_6" class="named-paragraph-link"><span class="named-paragraph">Begin passage if not already in one</span><span class="named-paragraph-number">6.1.1.1.6</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">paste_me</span><span class="plain-syntax"> = </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">, </span><span class="identifier-syntax">continue_me</span><span class="plain-syntax"> = </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">Str::get_at</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">) == </span><span class="character-syntax">'*'</span><span class="plain-syntax">) &amp;&amp;</span>
@ -482,7 +685,23 @@ of a code sample either, since a non-blank indented line is needed to trigger on
<span class="plain-syntax"> </span><span class="identifier-syntax">Str::delete_first_character</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Str::trim_white_space</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">continue_me</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">Str::get_at</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">) == </span><span class="character-syntax">'{'</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">Str::get_at</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="constant-syntax">1</span><span class="plain-syntax">) == </span><span class="character-syntax">'*'</span><span class="plain-syntax">) &amp;&amp;</span>
<span class="plain-syntax"> (</span><span class="identifier-syntax">Str::get_at</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="constant-syntax">2</span><span class="plain-syntax">) == </span><span class="character-syntax">'}'</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Str::delete_first_character</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Str::delete_first_character</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Str::delete_first_character</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Str::trim_white_space</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">paste_me</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">Str::get_at</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">) == </span><span class="character-syntax">'{'</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">Str::get_at</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="constant-syntax">1</span><span class="plain-syntax">) == </span><span class="character-syntax">'*'</span><span class="plain-syntax">) &amp;&amp;</span>
<span class="plain-syntax"> (</span><span class="identifier-syntax">Str::get_at</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="constant-syntax">2</span><span class="plain-syntax">) == </span><span class="character-syntax">'*'</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">Str::get_at</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="constant-syntax">3</span><span class="plain-syntax">) == </span><span class="character-syntax">'}'</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Str::delete_first_character</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Str::delete_first_character</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Str::delete_first_character</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Str::delete_first_character</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Str::trim_white_space</span><span class="plain-syntax">(</span><span class="identifier-syntax">line</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">continue_me</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">current_code</span><span class="plain-syntax"> = </span><a href="7-dt.html#SP12" class="function-link"><span class="function-syntax">DocumentationTree::new_code_sample</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tree</span><span class="plain-syntax">, </span><span class="identifier-syntax">paste_me</span><span class="plain-syntax">, </span><span class="identifier-syntax">language</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">continue_me</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">last_paste_code</span><span class="plain-syntax">) {</span>
@ -502,8 +721,8 @@ of a code sample either, since a non-blank indented line is needed to trigger on
<span class="plain-syntax"> </span><span class="identifier-syntax">pending_code_sample_blanks</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">code_is_tabular</span><span class="plain-syntax"> = </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP3_1_1_1">&#167;3.1.1.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP3_1_1_1_12" class="paragraph-anchor"></a><b>&#167;3.1.1.1.12. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Insert line break in code</span><span class="named-paragraph-number">3.1.1.1.12</span></span><span class="comment-syntax"> =</span>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP6_1_1_1">&#167;6.1.1.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP6_1_1_1_12" class="paragraph-anchor"></a><b>&#167;6.1.1.1.12. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Insert line break in code</span><span class="named-paragraph-number">6.1.1.1.12</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
@ -512,8 +731,8 @@ of a code sample either, since a non-blank indented line is needed to trigger on
<span class="plain-syntax"> </span><span class="identifier-syntax">code_is_tabular</span><span class="plain-syntax"> = </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP3_1_1_1">&#167;3.1.1.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP3_1_1_1_13" class="paragraph-anchor"></a><b>&#167;3.1.1.1.13. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Insert line in code sample</span><span class="named-paragraph-number">3.1.1.1.13</span></span><span class="comment-syntax"> =</span>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP6_1_1_1">&#167;6.1.1.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP6_1_1_1_13" class="paragraph-anchor"></a><b>&#167;6.1.1.1.13. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Insert line in code sample</span><span class="named-paragraph-number">6.1.1.1.13</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
@ -528,8 +747,8 @@ of a code sample either, since a non-blank indented line is needed to trigger on
<span class="plain-syntax"> </span><span class="identifier-syntax">Trees::make_child</span><span class="plain-syntax">(</span><a href="7-dt.html#SP14" class="function-link"><span class="function-syntax">DocumentationTree::new_code_line</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">cd</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tree</span><span class="plain-syntax">, </span><span class="identifier-syntax">line</span><span class="plain-syntax">, </span><span class="identifier-syntax">indentation</span><span class="plain-syntax">-1, </span><span class="identifier-syntax">code_is_tabular</span><span class="plain-syntax">),</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">current_code</span><span class="plain-syntax">);</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP3_1_1_1">&#167;3.1.1.1</a> (twice).</li></ul>
<p class="commentary firstcommentary"><a id="SP3_1_1_1_7_2" class="paragraph-anchor"></a><b>&#167;3.1.1.1.7.2. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Complete code</span><span class="named-paragraph-number">3.1.1.1.7.2</span></span><span class="comment-syntax"> =</span>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP6_1_1_1">&#167;6.1.1.1</a> (twice).</li></ul>
<p class="commentary firstcommentary"><a id="SP6_1_1_1_7_2" class="paragraph-anchor"></a><b>&#167;6.1.1.1.7.2. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Complete code</span><span class="named-paragraph-number">6.1.1.1.7.2</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
@ -538,11 +757,11 @@ of a code sample either, since a non-blank indented line is needed to trigger on
<span class="plain-syntax"> </span><span class="identifier-syntax">code_is_tabular</span><span class="plain-syntax"> = </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP3_1_1_1_7">&#167;3.1.1.1.7</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>&#167;4. </b></p>
<ul class="endnotetexts"><li>This code is used in <a href="7-dc.html#SP6_1_1_1_7">&#167;6.1.1.1.7</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP7" class="paragraph-anchor"></a><b>&#167;7. </b></p>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">programming_language</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationCompiler::get_language</span><button class="popup" onclick="togglePopup('usagePopup3')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup3">Usage of <span class="code-font"><span class="function-syntax">DocumentationCompiler::get_language</span></span>:<br/><a href="7-dc.html#SP3_1">&#167;3.1</a>, <a href="7-dc.html#SP3_1_1_1">&#167;3.1.1.1</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">) {</span>
<span class="identifier-syntax">programming_language</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationCompiler::get_language</span><button class="popup" onclick="togglePopup('usagePopup7')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup7">Usage of <span class="code-font"><span class="function-syntax">DocumentationCompiler::get_language</span></span>:<br/><a href="7-dc.html#SP6_1">&#167;6.1</a>, <a href="7-dc.html#SP6_1_1_1">&#167;6.1.1.1</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax"> *</span><span class="identifier-syntax">N</span><span class="plain-syntax"> = </span><a href="1-ic.html#SP16" class="function-link"><span class="function-syntax">Supervisor::internal</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">N</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">LP</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Pathnames::down</span><span class="plain-syntax">(</span><a href="2-nst.html#SP5" class="function-link"><span class="function-syntax">Nests::get_location</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">N</span><span class="plain-syntax">), </span><span class="identifier-syntax">I</span><span class="string-syntax">"PLs"</span><span class="plain-syntax">);</span>

12
docs/supervisor-module/7-dr.html
View file

@ -137,7 +137,7 @@ except the examples, and then up to 26 pages holding the content of examples A t
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">DocumentationRenderer::as_HTML</span><button class="popup" onclick="togglePopup('usagePopup3')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup3">Usage of <span class="code-font"><span class="function-syntax">DocumentationRenderer::as_HTML</span></span>:<br/>Extension Services - <a href="5-es.html#SP13">&#167;13</a><br/>The Mini-Website - <a href="7-tm.html#SP7">&#167;7</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="reserved-syntax">compiled_documentation</span><span class="plain-syntax"> *</span><span class="identifier-syntax">cd</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">extras</span><span class="plain-syntax">) {</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">DocumentationRenderer::as_HTML</span><button class="popup" onclick="togglePopup('usagePopup3')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup3">Usage of <span class="code-font"><span class="function-syntax">DocumentationRenderer::as_HTML</span></span>:<br/>Extension Services - <a href="5-es.html#SP12">&#167;12</a><br/>The Mini-Website - <a href="7-tm.html#SP7">&#167;7</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="reserved-syntax">compiled_documentation</span><span class="plain-syntax"> *</span><span class="identifier-syntax">cd</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">extras</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">cd</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">OUT</span><span class="plain-syntax"> = </span><a href="7-dr.html#SP2" class="function-link"><span class="function-syntax">DocumentationRenderer::open_subpage</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"index.html"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">) {</span>
@ -551,12 +551,7 @@ in a hierarchical fashion.
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">M</span><span class="plain-syntax">) </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">matter</span><span class="plain-syntax">, </span><span class="string-syntax">"\n\n"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">paste</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">paste</span><span class="plain-syntax">, </span><span class="string-syntax">"&lt;span class=\"paste\"&gt;%cV&lt;/span&gt;"</span><span class="plain-syntax">, </span><span class="constant-syntax">0x2318</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="comment-syntax"> the Unicode for "place of interest", the Swedish castle which became the Apple action symbol</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PasteButtons::paste_text_using</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">matter</span><span class="plain-syntax">, </span><span class="identifier-syntax">paste</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">paste</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&amp;nbsp;"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="7-tm.html#SP8" class="function-link"><span class="function-syntax">ExtensionWebsite::paste_button</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">matter</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">matter</span><span class="plain-syntax">)</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="7-dr.html#SP8">&#167;8</a>.</li></ul>
@ -677,7 +672,6 @@ and this is fiddly but elementary in the usual way of HTML tables:
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::end_html_row</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::end_html_table</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::begin_span</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"indexdullblue"</span><span class="plain-syntax">);</span>
</pre>
@ -722,6 +716,8 @@ in the next section.
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::end_span</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::begin_span</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"indexblack"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="7-dr.html#SP10" class="function-link"><span class="function-syntax">DocumentationRenderer::render_text</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">name</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_TAG</span><span class="plain-syntax">(</span><span class="string-syntax">"br"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="7-dr.html#SP10" class="function-link"><span class="function-syntax">DocumentationRenderer::render_text</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">description</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::end_span</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_CLOSE</span><span class="plain-syntax">(</span><span class="string-syntax">"b"</span><span class="plain-syntax">);</span>

51
docs/supervisor-module/7-dt.html
View file

@ -100,7 +100,7 @@ function togglePopup(material_id) {
<span class="plain-syntax"> &amp;</span><a href="7-dt.html#SP15" class="function-link"><span class="function-syntax">DocumentationTree::source_error_verifier</span></a><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">heterogeneous_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tree</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Trees::new</span><span class="plain-syntax">(</span><span class="identifier-syntax">cdoc_tree_TT</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Trees::make_root</span><span class="plain-syntax">(</span><span class="identifier-syntax">tree</span><span class="plain-syntax">, </span><a href="7-dt.html#SP3" class="function-link"><span class="function-syntax">DocumentationTree::new_heading</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">tree</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"(root)"</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Trees::make_root</span><span class="plain-syntax">(</span><span class="identifier-syntax">tree</span><span class="plain-syntax">, </span><a href="7-dt.html#SP3" class="function-link"><span class="function-syntax">DocumentationTree::new_heading</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">tree</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"(root)"</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">tree</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
@ -124,19 +124,21 @@ which is otherwise something like <span class="extract"><span class="extract-syn
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">cdoc_heading</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">count</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">recognition_name</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">level</span><span class="plain-syntax">; </span><span class="comment-syntax"> 0 = root, 1 = chapter, 2 = section</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">ID</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CLASS_DEFINITION</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">cdoc_heading</span><span class="plain-syntax">;</span>
<span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationTree::new_heading</span><button class="popup" onclick="togglePopup('usagePopup3')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup3">Usage of <span class="code-font"><span class="function-syntax">DocumentationTree::new_heading</span></span>:<br/><a href="7-dt.html#SP1">&#167;1</a><br/>Documentation Compiler - <a href="7-dc.html#SP3_1_1_1_1">&#167;3.1.1.1.1</a>, <a href="7-dc.html#SP3_1_1_1_2">&#167;3.1.1.1.2</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">heterogeneous_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tree</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">title</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">level</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">ID</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">cc</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">sc</span><span class="plain-syntax">) {</span>
<span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationTree::new_heading</span><button class="popup" onclick="togglePopup('usagePopup3')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup3">Usage of <span class="code-font"><span class="function-syntax">DocumentationTree::new_heading</span></span>:<br/><a href="7-dt.html#SP1">&#167;1</a><br/>Documentation Compiler - <a href="7-dc.html#SP6_1_1_1_1">&#167;6.1.1.1.1</a>, <a href="7-dc.html#SP6_1_1_1_2">&#167;6.1.1.1.2</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">heterogeneous_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tree</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">title</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">recognise_as</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">level</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">ID</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">cc</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">sc</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">cdoc_heading</span><span class="plain-syntax"> *</span><span class="identifier-syntax">H</span><span class="plain-syntax"> = </span><span class="identifier-syntax">CREATE</span><span class="plain-syntax">(</span><span class="reserved-syntax">cdoc_heading</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">H</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">count</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::new</span><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">cc</span><span class="plain-syntax"> &gt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">H</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">count</span><span class="plain-syntax">, </span><span class="string-syntax">"%d"</span><span class="plain-syntax">, </span><span class="identifier-syntax">cc</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">cc</span><span class="plain-syntax"> &gt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">sc</span><span class="plain-syntax"> &gt; </span><span class="constant-syntax">0</span><span class="plain-syntax">)) </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">H</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">count</span><span class="plain-syntax">, </span><span class="string-syntax">"."</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">sc</span><span class="plain-syntax"> &gt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">H</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">count</span><span class="plain-syntax">, </span><span class="string-syntax">"%d"</span><span class="plain-syntax">, </span><span class="identifier-syntax">sc</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">H</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">name</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">title</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">H</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">recognition_name</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">recognise_as</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">H</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">level</span><span class="plain-syntax"> = </span><span class="identifier-syntax">level</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">H</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">ID</span><span class="plain-syntax"> = </span><span class="identifier-syntax">ID</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">Trees::new_node</span><span class="plain-syntax">(</span><span class="identifier-syntax">tree</span><span class="plain-syntax">, </span><span class="identifier-syntax">heading_TNT</span><span class="plain-syntax">, </span><span class="identifier-syntax">STORE_POINTER_cdoc_heading</span><span class="plain-syntax">(</span><span class="identifier-syntax">H</span><span class="plain-syntax">));</span>
@ -166,23 +168,25 @@ letters are unique from A, B, C, ...
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">cdoc_example</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">description</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">star_count</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">number</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">char</span><span class="plain-syntax"> </span><span class="identifier-syntax">letter</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CLASS_DEFINITION</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">cdoc_example</span><span class="plain-syntax">;</span>
<span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationTree::new_example</span><button class="popup" onclick="togglePopup('usagePopup5')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup5">Usage of <span class="code-font"><span class="function-syntax">DocumentationTree::new_example</span></span>:<br/>Documentation Compiler - <a href="7-dc.html#SP3_1_1_1_3">&#167;3.1.1.1.3</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">heterogeneous_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tree</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">title</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">star_count</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">ecount</span><span class="plain-syntax">) {</span>
<span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationTree::new_example</span><button class="popup" onclick="togglePopup('usagePopup5')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup5">Usage of <span class="code-font"><span class="function-syntax">DocumentationTree::new_example</span></span>:<br/>Documentation Compiler - <a href="7-dc.html#SP2_1_2">&#167;2.1.2</a>, <a href="7-dc.html#SP6_1_1_1_3">&#167;6.1.1.1.3</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">heterogeneous_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tree</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">title</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">desc</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">star_count</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">ecount</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">cdoc_example</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax"> = </span><span class="identifier-syntax">CREATE</span><span class="plain-syntax">(</span><span class="reserved-syntax">cdoc_example</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">name</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">title</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">description</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">desc</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">star_count</span><span class="plain-syntax"> = </span><span class="identifier-syntax">star_count</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">number</span><span class="plain-syntax"> = </span><span class="identifier-syntax">ecount</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">letter</span><span class="plain-syntax"> = </span><span class="character-syntax">'A'</span><span class="plain-syntax"> + (</span><span class="reserved-syntax">char</span><span class="plain-syntax">) </span><span class="identifier-syntax">ecount</span><span class="plain-syntax"> - </span><span class="constant-syntax">1</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">Trees::new_node</span><span class="plain-syntax">(</span><span class="identifier-syntax">tree</span><span class="plain-syntax">, </span><span class="identifier-syntax">example_TNT</span><span class="plain-syntax">, </span><span class="identifier-syntax">STORE_POINTER_cdoc_example</span><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">));</span>
<span class="plain-syntax">}</span>
</pre>
<ul class="endnotetexts"><li>The structure cdoc_example is accessed in 3/bs2, 7/dr and here.</li></ul>
<ul class="endnotetexts"><li>The structure cdoc_example is accessed in 3/bs2, 7/dc, 7/dr and here.</li></ul>
<p class="commentary firstcommentary"><a id="SP6" class="paragraph-anchor"></a><b>&#167;6. </b>An example node always has a single child: the passage containing its content.
</p>
@ -202,7 +206,7 @@ or headings.
<span class="plain-syntax"> </span><span class="identifier-syntax">CLASS_DEFINITION</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">cdoc_passage</span><span class="plain-syntax">;</span>
<span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationTree::new_passage</span><button class="popup" onclick="togglePopup('usagePopup7')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup7">Usage of <span class="code-font"><span class="function-syntax">DocumentationTree::new_passage</span></span>:<br/>Documentation Compiler - <a href="7-dc.html#SP3_1_1_1_6">&#167;3.1.1.1.6</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">heterogeneous_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tree</span><span class="plain-syntax">) {</span>
<span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationTree::new_passage</span><button class="popup" onclick="togglePopup('usagePopup7')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup7">Usage of <span class="code-font"><span class="function-syntax">DocumentationTree::new_passage</span></span>:<br/>Documentation Compiler - <a href="7-dc.html#SP6_1_1_1_6">&#167;6.1.1.1.6</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">heterogeneous_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tree</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">cdoc_passage</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax"> = </span><span class="identifier-syntax">CREATE</span><span class="plain-syntax">(</span><span class="reserved-syntax">cdoc_passage</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">Trees::new_node</span><span class="plain-syntax">(</span><span class="identifier-syntax">tree</span><span class="plain-syntax">, </span><span class="identifier-syntax">passage_TNT</span><span class="plain-syntax">, </span><span class="identifier-syntax">STORE_POINTER_cdoc_passage</span><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">));</span>
<span class="plain-syntax">}</span>
@ -235,7 +239,7 @@ phrases. The "tag" is optional and is for potential cross-referencing; the
<span class="plain-syntax"> </span><span class="identifier-syntax">CLASS_DEFINITION</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">cdoc_phrase_defn</span><span class="plain-syntax">;</span>
<span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationTree::new_phrase_defn</span><button class="popup" onclick="togglePopup('usagePopup9')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup9">Usage of <span class="code-font"><span class="function-syntax">DocumentationTree::new_phrase_defn</span></span>:<br/>Documentation Compiler - <a href="7-dc.html#SP3_1_1_1_4">&#167;3.1.1.1.4</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">heterogeneous_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tree</span><span class="plain-syntax">,</span>
<span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationTree::new_phrase_defn</span><button class="popup" onclick="togglePopup('usagePopup9')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup9">Usage of <span class="code-font"><span class="function-syntax">DocumentationTree::new_phrase_defn</span></span>:<br/>Documentation Compiler - <a href="7-dc.html#SP6_1_1_1_4">&#167;6.1.1.1.4</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">heterogeneous_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tree</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tag</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">prototype</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">cdoc_phrase_defn</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax"> = </span><span class="identifier-syntax">CREATE</span><span class="plain-syntax">(</span><span class="reserved-syntax">cdoc_phrase_defn</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">P</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">tag</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">tag</span><span class="plain-syntax">);</span>
@ -263,7 +267,7 @@ phrases. The "tag" is optional and is for potential cross-referencing; the
<span class="plain-syntax"> </span><span class="identifier-syntax">CLASS_DEFINITION</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">cdoc_paragraph</span><span class="plain-syntax">;</span>
<span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationTree::new_paragraph</span><button class="popup" onclick="togglePopup('usagePopup11')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup11">Usage of <span class="code-font"><span class="function-syntax">DocumentationTree::new_paragraph</span></span>:<br/>Documentation Compiler - <a href="7-dc.html#SP3_1_1_1_8">&#167;3.1.1.1.8</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">heterogeneous_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tree</span><span class="plain-syntax">,</span>
<span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationTree::new_paragraph</span><button class="popup" onclick="togglePopup('usagePopup11')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup11">Usage of <span class="code-font"><span class="function-syntax">DocumentationTree::new_paragraph</span></span>:<br/>Documentation Compiler - <a href="7-dc.html#SP6_1_1_1_8">&#167;6.1.1.1.8</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">heterogeneous_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tree</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">content</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">cdoc_paragraph</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax"> = </span><span class="identifier-syntax">CREATE</span><span class="plain-syntax">(</span><span class="reserved-syntax">cdoc_paragraph</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">P</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">content</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">content</span><span class="plain-syntax">);</span>
@ -287,7 +291,7 @@ phrases. The "tag" is optional and is for potential cross-referencing; the
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">programming_language</span><span class="plain-syntax"> *</span><span class="identifier-syntax">language</span><span class="plain-syntax">;</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">cdoc_code_sample</span><span class="plain-syntax">;</span>
<span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationTree::new_code_sample</span><button class="popup" onclick="togglePopup('usagePopup13')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup13">Usage of <span class="code-font"><span class="function-syntax">DocumentationTree::new_code_sample</span></span>:<br/>Documentation Compiler - <a href="7-dc.html#SP3_1_1_1_11">&#167;3.1.1.1.11</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">heterogeneous_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tree</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">paste_me</span><span class="plain-syntax">,</span>
<span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationTree::new_code_sample</span><button class="popup" onclick="togglePopup('usagePopup13')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup13">Usage of <span class="code-font"><span class="function-syntax">DocumentationTree::new_code_sample</span></span>:<br/>Documentation Compiler - <a href="7-dc.html#SP6_1_1_1_11">&#167;6.1.1.1.11</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">heterogeneous_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tree</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">paste_me</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">programming_language</span><span class="plain-syntax"> *</span><span class="identifier-syntax">language</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">cdoc_code_sample</span><span class="plain-syntax"> *</span><span class="identifier-syntax">C</span><span class="plain-syntax"> = </span><span class="identifier-syntax">CREATE</span><span class="plain-syntax">(</span><span class="reserved-syntax">cdoc_code_sample</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">with_paste_marker</span><span class="plain-syntax"> = </span><span class="identifier-syntax">paste_me</span><span class="plain-syntax">;</span>
@ -323,7 +327,7 @@ at 0, and is measured in tab stops.
<span class="plain-syntax"> </span><span class="identifier-syntax">CLASS_DEFINITION</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">cdoc_code_line</span><span class="plain-syntax">;</span>
<span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationTree::new_code_line</span><button class="popup" onclick="togglePopup('usagePopup15')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup15">Usage of <span class="code-font"><span class="function-syntax">DocumentationTree::new_code_line</span></span>:<br/>Documentation Compiler - <a href="7-dc.html#SP3_1_1_1_13">&#167;3.1.1.1.13</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">heterogeneous_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tree</span><span class="plain-syntax">,</span>
<span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationTree::new_code_line</span><button class="popup" onclick="togglePopup('usagePopup15')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup15">Usage of <span class="code-font"><span class="function-syntax">DocumentationTree::new_code_line</span></span>:<br/>Documentation Compiler - <a href="7-dc.html#SP6_1_1_1_13">&#167;6.1.1.1.13</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">heterogeneous_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tree</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">content</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">indentation</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">tabular</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">cdoc_code_line</span><span class="plain-syntax"> *</span><span class="identifier-syntax">C</span><span class="plain-syntax"> = </span><span class="identifier-syntax">CREATE</span><span class="plain-syntax">(</span><span class="reserved-syntax">cdoc_code_line</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">content</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">content</span><span class="plain-syntax">);</span>
@ -348,7 +352,7 @@ at 0, and is measured in tab stops.
<span class="plain-syntax"> </span><span class="identifier-syntax">CLASS_DEFINITION</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">cdoc_source_error</span><span class="plain-syntax">;</span>
<span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationTree::new_source_error</span><button class="popup" onclick="togglePopup('usagePopup17')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup17">Usage of <span class="code-font"><span class="function-syntax">DocumentationTree::new_source_error</span></span>:<br/>Documentation Compiler - <a href="7-dc.html#SP3_1_1_1">&#167;3.1.1.1</a>, <a href="7-dc.html#SP3_1_1_1_3">&#167;3.1.1.1.3</a>, <a href="7-dc.html#SP3_1_1_1_5">&#167;3.1.1.1.5</a>, <a href="7-dc.html#SP3_1_1_2">&#167;3.1.1.2</a>, <a href="7-dc.html#SP3_1_1_1_11">&#167;3.1.1.1.11</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">heterogeneous_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tree</span><span class="plain-syntax">,</span>
<span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationTree::new_source_error</span><button class="popup" onclick="togglePopup('usagePopup17')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup17">Usage of <span class="code-font"><span class="function-syntax">DocumentationTree::new_source_error</span></span>:<br/>Documentation Compiler - <a href="7-dc.html#SP3">&#167;3</a>, <a href="7-dc.html#SP6_1_1_1">&#167;6.1.1.1</a>, <a href="7-dc.html#SP6_1_1_1_3">&#167;6.1.1.1.3</a>, <a href="7-dc.html#SP6_1_1_1_5">&#167;6.1.1.1.5</a>, <a href="7-dc.html#SP6_1_1_2">&#167;6.1.1.2</a>, <a href="7-dc.html#SP6_1_1_1_11">&#167;6.1.1.1.11</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">heterogeneous_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tree</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">content</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">cdoc_source_error</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax"> = </span><span class="identifier-syntax">CREATE</span><span class="plain-syntax">(</span><span class="reserved-syntax">cdoc_source_error</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">error_message</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">content</span><span class="plain-syntax">);</span>
@ -371,6 +375,7 @@ if not.
<span class="plain-syntax"> </span><span class="reserved-syntax">dc_find_example_task</span><span class="plain-syntax"> </span><span class="identifier-syntax">task</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">task</span><span class="plain-syntax">.</span><span class="element-syntax">to_find_example</span><span class="plain-syntax"> = </span><span class="identifier-syntax">eg</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">task</span><span class="plain-syntax">.</span><span class="element-syntax">to_find_heading</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">task</span><span class="plain-syntax">.</span><span class="element-syntax">to_find_section</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">task</span><span class="plain-syntax">.</span><span class="element-syntax">result</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Trees::traverse_from</span><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">root</span><span class="plain-syntax">, &amp;</span><a href="7-dt.html#SP16" class="function-link"><span class="function-syntax">DocumentationTree::find_visit</span></a><span class="plain-syntax">, (</span><span class="reserved-syntax">void</span><span class="plain-syntax"> *) &amp;</span><span class="identifier-syntax">task</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">task</span><span class="plain-syntax">.</span><span class="element-syntax">result</span><span class="plain-syntax">;</span>
@ -381,6 +386,18 @@ if not.
<span class="plain-syntax"> </span><span class="reserved-syntax">dc_find_example_task</span><span class="plain-syntax"> </span><span class="identifier-syntax">task</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">task</span><span class="plain-syntax">.</span><span class="element-syntax">to_find_example</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">task</span><span class="plain-syntax">.</span><span class="element-syntax">to_find_heading</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::new</span><span class="plain-syntax">(); </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">task</span><span class="plain-syntax">.</span><span class="element-syntax">to_find_heading</span><span class="plain-syntax">, </span><span class="string-syntax">"%d"</span><span class="plain-syntax">, </span><span class="identifier-syntax">ch</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">task</span><span class="plain-syntax">.</span><span class="element-syntax">to_find_section</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">task</span><span class="plain-syntax">.</span><span class="element-syntax">result</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Trees::traverse_from</span><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">root</span><span class="plain-syntax">, &amp;</span><a href="7-dt.html#SP16" class="function-link"><span class="function-syntax">DocumentationTree::find_visit</span></a><span class="plain-syntax">, (</span><span class="reserved-syntax">void</span><span class="plain-syntax"> *) &amp;</span><span class="identifier-syntax">task</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">task</span><span class="plain-syntax">.</span><span class="element-syntax">result</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
<span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationTree::find_section</span><button class="popup" onclick="togglePopup('usagePopup21')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup21">Usage of <span class="code-font"><span class="function-syntax">DocumentationTree::find_section</span></span>:<br/>Documentation Compiler - <a href="7-dc.html#SP2_1_2">&#167;2.1.2</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">heterogeneous_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">T</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">name</span><span class="plain-syntax">) == </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">dc_find_example_task</span><span class="plain-syntax"> </span><span class="identifier-syntax">task</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">task</span><span class="plain-syntax">.</span><span class="element-syntax">to_find_example</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">task</span><span class="plain-syntax">.</span><span class="element-syntax">to_find_heading</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">task</span><span class="plain-syntax">.</span><span class="element-syntax">to_find_section</span><span class="plain-syntax"> = </span><span class="identifier-syntax">name</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">task</span><span class="plain-syntax">.</span><span class="element-syntax">result</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Trees::traverse_from</span><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">root</span><span class="plain-syntax">, &amp;</span><a href="7-dt.html#SP16" class="function-link"><span class="function-syntax">DocumentationTree::find_visit</span></a><span class="plain-syntax">, (</span><span class="reserved-syntax">void</span><span class="plain-syntax"> *) &amp;</span><span class="identifier-syntax">task</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">task</span><span class="plain-syntax">.</span><span class="element-syntax">result</span><span class="plain-syntax">;</span>
@ -389,6 +406,7 @@ if not.
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">dc_find_example_task</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">to_find_example</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">to_find_heading</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">to_find_section</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">result</span><span class="plain-syntax">;</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">dc_find_example_task</span><span class="plain-syntax">;</span>
@ -409,6 +427,15 @@ if not.
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">task</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">to_find_section</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">N</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">type</span><span class="plain-syntax"> == </span><span class="identifier-syntax">heading_TNT</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">cdoc_heading</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax"> = </span><span class="identifier-syntax">RETRIEVE_POINTER_cdoc_heading</span><span class="plain-syntax">(</span><span class="identifier-syntax">N</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">content</span><span class="plain-syntax">);</span>
<span class="identifier-syntax">LOG</span><span class="plain-syntax">(</span><span class="string-syntax">"Want %S find %S\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">task</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">to_find_section</span><span class="plain-syntax">, </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">recognition_name</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">level</span><span class="plain-syntax"> == </span><span class="constant-syntax">2</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">Str::eq_insensitive</span><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">recognition_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">task</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">to_find_section</span><span class="plain-syntax">))) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">task</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">result</span><span class="plain-syntax"> = </span><span class="identifier-syntax">N</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>

25
docs/supervisor-module/7-eip.html
View file

@ -500,7 +500,7 @@ the usual ones seen in Mac OS X applications such as iTunes.
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax"> = </span><a href="5-es.html#SP4" class="function-link"><span class="function-syntax">Extensions::from_copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">res</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">copy</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">parse_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">at</span><span class="plain-syntax"> = </span><a href="5-es.html#SP19" class="function-link"><span class="function-syntax">Extensions::get_inclusion_sentence</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">parse_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">at</span><span class="plain-syntax"> = </span><a href="5-es.html#SP18" class="function-link"><span class="function-syntax">Extensions::get_inclusion_sentence</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">at</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wording</span><span class="plain-syntax"> </span><span class="identifier-syntax">W</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Node::get_text</span><span class="plain-syntax">(</span><span class="identifier-syntax">at</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">source_location</span><span class="plain-syntax"> </span><span class="identifier-syntax">sl</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Lexer::word_location</span><span class="plain-syntax">(</span><span class="identifier-syntax">Wordings::first_wn</span><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">));</span>
@ -518,7 +518,7 @@ the usual ones seen in Mac OS X applications such as iTunes.
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">" "</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">inclusion_text</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">inclusion_text</span><span class="plain-syntax">, </span><span class="string-syntax">"Include %X.\n\n\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">res</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">copy</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">edition</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">work</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PasteButtons::paste_text</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">inclusion_text</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="7-tm.html#SP8" class="function-link"><span class="function-syntax">ExtensionWebsite::paste_button</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">inclusion_text</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">inclusion_text</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><a href="7-eip.html#SP3" class="function-link"><span class="function-syntax">ExtensionIndex::add_to_key</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">key_list</span><span class="plain-syntax">, </span><span class="constant-syntax">PASTE_SYMBOL</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">I</span><span class="string-syntax">"Source text to Include this (click to paste in)"</span><span class="plain-syntax">);</span>
@ -593,7 +593,7 @@ the first and last word and just look at what is in between:
<span class="plain-syntax"> </span><span class="reserved-syntax">else</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"Installed in this project"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">R</span><span class="plain-syntax"> = </span><a href="5-es.html#SP16" class="function-link"><span class="function-syntax">Extensions::get_rubric</span></a><span class="plain-syntax">(</span><a href="5-es.html#SP4" class="function-link"><span class="function-syntax">Extensions::from_copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">res</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">copy</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">R</span><span class="plain-syntax"> = </span><a href="5-es.html#SP15" class="function-link"><span class="function-syntax">Extensions::get_rubric</span></a><span class="plain-syntax">(</span><a href="5-es.html#SP4" class="function-link"><span class="function-syntax">Extensions::from_copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">res</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">copy</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">R</span><span class="plain-syntax">) &gt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"%S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">R</span><span class="plain-syntax">); </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"--"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::end_span</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">);</span>
@ -604,7 +604,7 @@ the first and last word and just look at what is in between:
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::begin_span</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"smaller"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">R</span><span class="plain-syntax"> = </span><a href="5-es.html#SP16" class="function-link"><span class="function-syntax">Extensions::get_rubric</span></a><span class="plain-syntax">(</span><a href="5-es.html#SP4" class="function-link"><span class="function-syntax">Extensions::from_copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">res</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">copy</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">R</span><span class="plain-syntax"> = </span><a href="5-es.html#SP15" class="function-link"><span class="function-syntax">Extensions::get_rubric</span></a><span class="plain-syntax">(</span><a href="5-es.html#SP4" class="function-link"><span class="function-syntax">Extensions::from_copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">res</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">copy</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">R</span><span class="plain-syntax">) &gt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"%S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">R</span><span class="plain-syntax">); </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"--"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::end_span</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">);</span>
</pre>
@ -639,7 +639,7 @@ the first and last word and just look at what is in between:
<pre class="definitions code-font"><span class="definition-keyword">define</span> <span class="constant-syntax">PROBLEM_SYMBOL</span><span class="plain-syntax"> </span><span class="string-syntax">"border=\"0\" height=\"12\" src=\"inform:/doc_images/census_problem.png\""</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">REVEAL_SYMBOL</span><span class="plain-syntax"> </span><span class="string-syntax">"border=\"0\" src=\"inform:/doc_images/Reveal.png\""</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">HELP_SYMBOL</span><span class="plain-syntax"> </span><span class="string-syntax">"border=\"0\" src=\"inform:/doc_images/help.png\""</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">PASTE_SYMBOL</span><span class="plain-syntax"> </span><span class="string-syntax">"border=\"0\" src=\"inform:/doc_images/paste.png\""</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">PASTE_SYMBOL</span><span class="plain-syntax"> </span><span class="string-syntax">"paste"</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">BUILT_IN_SYMBOL</span><span class="plain-syntax"> </span><span class="string-syntax">"border=\"0\" src=\"inform:/doc_images/builtin_ext.png\""</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">PROJECT_SPECIFIC_SYMBOL</span><span class="plain-syntax"> </span><span class="string-syntax">"border=\"0\" src=\"inform:/doc_images/folder4.png\""</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">LEGACY_AREA_SYMBOL</span><span class="plain-syntax"> </span><span class="string-syntax">"border=\"0\" src=\"inform:/doc_images/pspec_ext.png\""</span>
@ -651,6 +651,7 @@ the first and last word and just look at what is in between:
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">image_URL</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">gloss</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">displayed</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">ideograph</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CLASS_DEFINITION</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">extensions_key_item</span><span class="plain-syntax">;</span>
@ -667,6 +668,8 @@ the first and last word and just look at what is in between:
<span class="plain-syntax"> </span><span class="identifier-syntax">eki</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">image_URL</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">as_text</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">eki</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">gloss</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">gloss</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">eki</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">displayed</span><span class="plain-syntax"> = </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">eki</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">ideograph</span><span class="plain-syntax"> = </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::eq</span><span class="plain-syntax">(</span><span class="identifier-syntax">as_text</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"paste"</span><span class="plain-syntax">)) </span><span class="identifier-syntax">eki</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">ideograph</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ADD_TO_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">eki</span><span class="plain-syntax">, </span><span class="reserved-syntax">extensions_key_item</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">as_text</span><span class="plain-syntax">)</span>
@ -686,7 +689,7 @@ the first and last word and just look at what is in between:
<span class="plain-syntax"> </span><span class="reserved-syntax">extensions_key_item</span><span class="plain-syntax"> *</span><span class="identifier-syntax">eki</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOOP_OVER_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">eki</span><span class="plain-syntax">, </span><span class="reserved-syntax">extensions_key_item</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::eq</span><span class="plain-syntax">(</span><span class="identifier-syntax">eki</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">image_URL</span><span class="plain-syntax">, </span><span class="identifier-syntax">as_text</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_TAG_WITH</span><span class="plain-syntax">(</span><span class="string-syntax">"img"</span><span class="plain-syntax">, </span><span class="string-syntax">"%S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">eki</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">image_URL</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="7-eip.html#SP3" class="function-link"><span class="function-syntax">ExtensionIndex::render_icon</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">eki</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&amp;nbsp;%S &amp;nbsp;&amp;nbsp;"</span><span class="plain-syntax">, </span><span class="identifier-syntax">eki</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">gloss</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">eki</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">displayed</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
@ -696,13 +699,21 @@ the first and last word and just look at what is in between:
<span class="plain-syntax"> </span><span class="reserved-syntax">extensions_key_item</span><span class="plain-syntax"> *</span><span class="identifier-syntax">eki</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOOP_OVER_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">eki</span><span class="plain-syntax">, </span><span class="reserved-syntax">extensions_key_item</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">eki</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">displayed</span><span class="plain-syntax"> == </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_TAG_WITH</span><span class="plain-syntax">(</span><span class="string-syntax">"img"</span><span class="plain-syntax">, </span><span class="string-syntax">"%S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">eki</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">image_URL</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="7-eip.html#SP3" class="function-link"><span class="function-syntax">ExtensionIndex::render_icon</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">eki</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&amp;nbsp;%S &amp;nbsp;&amp;nbsp;"</span><span class="plain-syntax">, </span><span class="identifier-syntax">eki</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">gloss</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">eki</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">displayed</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_CLOSE</span><span class="plain-syntax">(</span><span class="string-syntax">"p"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">ExtensionIndex::render_icon</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="reserved-syntax">extensions_key_item</span><span class="plain-syntax"> *</span><span class="identifier-syntax">eki</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">eki</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">ideograph</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><a href="7-tm.html#SP8" class="function-link"><span class="function-syntax">ExtensionWebsite::paste_ideograph</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_TAG_WITH</span><span class="plain-syntax">(</span><span class="string-syntax">"img"</span><span class="plain-syntax">, </span><span class="string-syntax">"%S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">eki</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">image_URL</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
</pre>
<ul class="endnotetexts"><li>The structure extensions_key_item is private to this section.</li></ul>
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>&#167;4. Icons for virtual machines. </b>And everything else is cosmetic: printing, or showing icons to signify,

4
docs/supervisor-module/7-ti.html
View file

@ -197,7 +197,7 @@ produces a second report.
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"Specifically:"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_CLOSE</span><span class="plain-syntax">(</span><span class="string-syntax">"p"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="2-cps.html#SP5" class="function-link"><span class="function-syntax">Copies::list_attached_errors_to_HTML</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">C</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">rubric</span><span class="plain-syntax"> = </span><a href="5-es.html#SP16" class="function-link"><span class="function-syntax">Extensions::get_rubric</span></a><span class="plain-syntax">(</span><a href="5-es.html#SP4" class="function-link"><span class="function-syntax">Extensions::from_copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">C</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">rubric</span><span class="plain-syntax"> = </span><a href="5-es.html#SP15" class="function-link"><span class="function-syntax">Extensions::get_rubric</span></a><span class="plain-syntax">(</span><a href="5-es.html#SP4" class="function-link"><span class="function-syntax">Extensions::from_copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">C</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">rubric</span><span class="plain-syntax">) &gt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"The extension says this about itself:"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_CLOSE</span><span class="plain-syntax">(</span><span class="string-syntax">"p"</span><span class="plain-syntax">);</span>
@ -213,7 +213,7 @@ produces a second report.
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_OPEN</span><span class="plain-syntax">(</span><span class="string-syntax">"p"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"This looks like a valid extension"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">rubric</span><span class="plain-syntax"> = </span><a href="5-es.html#SP16" class="function-link"><span class="function-syntax">Extensions::get_rubric</span></a><span class="plain-syntax">(</span><a href="5-es.html#SP4" class="function-link"><span class="function-syntax">Extensions::from_copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">C</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">rubric</span><span class="plain-syntax"> = </span><a href="5-es.html#SP15" class="function-link"><span class="function-syntax">Extensions::get_rubric</span></a><span class="plain-syntax">(</span><a href="5-es.html#SP4" class="function-link"><span class="function-syntax">Extensions::from_copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">C</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">rubric</span><span class="plain-syntax">) &gt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">", and says this about itself:"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_CLOSE</span><span class="plain-syntax">(</span><span class="string-syntax">"p"</span><span class="plain-syntax">);</span>

17
docs/supervisor-module/7-tm.html
View file

@ -283,6 +283,23 @@ examples provided in the extension.
<span class="plain-syntax"> </span><span class="identifier-syntax">no_EXW_breadcrumbs</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP8" class="paragraph-anchor"></a><b>&#167;8. </b>This is a new-look paste button, using a "command-V" ideograph rather than
a somewhat enigmatic icon.
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">ExtensionWebsite::paste_button</span><button class="popup" onclick="togglePopup('usagePopup12')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup12">Usage of <span class="code-font"><span class="function-syntax">ExtensionWebsite::paste_button</span></span>:<br/>Extensions Index Page - <a href="7-eip.html#SP1_2_2_4_4_1">&#167;1.2.2.4.4.1</a><br/>Documentation Renderer - <a href="7-dr.html#SP8_2">&#167;8.2</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">matter</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">paste</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><a href="7-tm.html#SP8" class="function-link"><span class="function-syntax">ExtensionWebsite::paste_ideograph</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">paste</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PasteButtons::paste_text_using</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">matter</span><span class="plain-syntax">, </span><span class="identifier-syntax">paste</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">paste</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&amp;nbsp;"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">ExtensionWebsite::paste_ideograph</span><button class="popup" onclick="togglePopup('usagePopup13')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup13">Usage of <span class="code-font"><span class="function-syntax">ExtensionWebsite::paste_ideograph</span></span>:<br/>Extensions Index Page - <a href="7-eip.html#SP3">&#167;3</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">OUTPUT_STREAM</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="comment-syntax"> the Unicode for "place of interest", the Swedish castle which became the Apple action symbol</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&lt;span class=\"paste\"&gt;%cV&lt;/span&gt;"</span><span class="plain-syntax">, </span><span class="constant-syntax">0x2318</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<nav role="progress"><div class="progresscontainer">
<ul class="progressbar"><li class="progressprev"><a href="6-vmg.html">&#10094;</a></li><li class="progresschapter"><a href="P-wtmd.html">P</a></li><li class="progresschapter"><a href="1-sm.html">1</a></li><li class="progresschapter"><a href="2-gnr.html">2</a></li><li class="progresschapter"><a href="3-bg.html">3</a></li><li class="progresschapter"><a href="4-em.html">4</a></li><li class="progresschapter"><a href="5-es.html">5</a></li><li class="progresschapter"><a href="6-st.html">6</a></li><li class="progresscurrentchapter">7</li><li class="progresscurrent">tm</li><li class="progresssection"><a href="7-eip.html">eip</a></li><li class="progresssection"><a href="7-ti.html">ti</a></li><li class="progresssection"><a href="7-dt.html">dt</a></li><li class="progresssection"><a href="7-dc.html">dc</a></li><li class="progresssection"><a href="7-dr.html">dr</a></li><li class="progressnext"><a href="7-eip.html">&#10095;</a></li></ul></div>
</nav><!--End of weave-->

2
inbuild/supervisor-module/Chapter 1/Supervisor Module.w
View file

@ -47,6 +47,7 @@ which use this module:
@e inform_template_CLASS
@e kit_configuration_CLASS
@e kit_dependency_CLASS
@e satellite_test_case_CLASS
=
DECLARE_CLASS(build_methodology)
@ -86,6 +87,7 @@ DECLARE_CLASS(inform_project)
DECLARE_CLASS(inform_template)
DECLARE_CLASS(kit_configuration)
DECLARE_CLASS(kit_dependency)
DECLARE_CLASS(satellite_test_case)
@ Like all modules, this one must define a |start| and |end| function:

2
inbuild/supervisor-module/Chapter 4/Extension Bundle Manager.w
View file

@ -331,7 +331,7 @@ inbuild_copy *ExtensionBundleManager::claim_folder_as_copy(pathname *P, inbuild_
Str::delete_last_character(subdir);
if (Str::eq(subdir, I"Examples")) {
;
} else if (Str::eq(subdir, I"Images")) {
} else if (Str::eq(subdir, I"Tests")) {
;
} else {
TEMPORARY_TEXT(error_text)

26
inbuild/supervisor-module/Chapter 5/Extension Services.w
View file

@ -777,9 +777,9 @@ void Extensions::read_source_text_for(inform_extension *E) {
SVEXPLAIN(1, "(from %f)\n", F);
DISCARD_TEXT(synopsis)
if (E->read_into_file) {
E->documentation =
DocumentationCompiler::compile(
TextFromFiles::torn_off_documentation(E->read_into_file), E);
text_stream *doc = TextFromFiles::torn_off_documentation(E->read_into_file);
if (Str::len(doc) > 0) E->documentation = DocumentationCompiler::compile(doc, E);
else E->documentation = NULL;
E->read_into_file->your_ref = STORE_POINTER_inbuild_copy(E->as_copy);
@<Break the text into sentences@>;
E->body_text_unbroken = FALSE;
@ -830,36 +830,24 @@ compiled_documentation *Extensions::get_documentation(inform_extension *E) {
if (E->documentation_sought == FALSE) {
if (E->as_copy->location_if_path) {
pathname *D = Pathnames::down(E->as_copy->location_if_path, I"Documentation");
filename *F = Filenames::in(D, I"Documentation.txt");
if (TextFiles::exists(F)) @<Fetch wording from stand-alone file@>;
if (Directories::exists(D)) @<Fetch wording from stand-alone directory@>;
}
E->documentation_sought = TRUE;
}
return E->documentation;
}
@<Fetch wording from stand-alone file@> =
if (E->documentation == NULL) {
@<Fetch wording from stand-alone directory@> =
if (E->documentation) {
TEMPORARY_TEXT(error_text)
WRITE_TO(error_text,
"this extension provides documentation both as a file and in its source");
Copies::attach_error(E->as_copy, CopyErrors::new_T(EXT_MISWORDED_CE, -1, error_text));
DISCARD_TEXT(error_text)
} else {
TEMPORARY_TEXT(temp)
TextFiles::read(F, FALSE, "unable to read file of extension documentation", TRUE,
&Extensions::read_extension_file_helper, NULL, temp);
E->documentation = DocumentationCompiler::compile(temp, E);
DISCARD_TEXT(temp)
E->documentation = DocumentationCompiler::compile_from_path(D, E);
}
@ =
void Extensions::read_extension_file_helper(text_stream *text, text_file_position *tfp,
void *v_state) {
text_stream *contents = (text_stream *) v_state;
WRITE_TO(contents, "%S\n", text);
}
@ And this serves the |-document| feature of inbuild:
=

212
inbuild/supervisor-module/Chapter 7/Documentation Compiler.w
View file

@ -14,6 +14,7 @@ typedef struct compiled_documentation {
int total_headings[3];
int total_examples;
int empty;
struct linked_list *cases; /* of |satellite_test_case| */
CLASS_DEFINITION
} compiled_documentation;
@ -28,11 +29,200 @@ compiled_documentation *DocumentationCompiler::new_wrapper(text_stream *source)
cd->total_headings[1] = 0;
cd->total_headings[2] = 0;
cd->empty = FALSE;
cd->cases = NEW_LINKED_LIST(satellite_test_case);
return cd;
}
typedef struct satellite_test_case {
int is_example;
struct text_stream *owning_heading;
struct tree_node *owning_node;
struct compiled_documentation *owner;
struct text_stream *short_name;
struct filename *test_file;
struct filename *ideal_transcript;
CLASS_DEFINITION
} satellite_test_case;
@ We can compile either from a file...
=
compiled_documentation *DocumentationCompiler::compile_from_path(pathname *P,
inform_extension *associated_extension) {
filename *F = Filenames::in(P, I"Documentation.txt");
if (TextFiles::exists(F) == FALSE) return NULL;
compiled_documentation *cd =
DocumentationCompiler::compile_from_file(F, associated_extension);
if (cd == NULL) return NULL;
pathname *EP = Pathnames::down(P, I"Examples");
int egs = TRUE;
@<Scan EP directory for examples@>;
egs = FALSE;
EP = Pathnames::down(P, I"Tests");
@<Scan EP directory for examples@>;
return cd;
}
@<Scan EP directory for examples@> =
scan_directory *D = Directories::open(EP);
TEMPORARY_TEXT(leafname)
while (Directories::next(D, leafname)) {
wchar_t first = Str::get_first_char(leafname), last = Str::get_last_char(leafname);
if (Platform::is_folder_separator(last)) continue;
if (first == '.') continue;
if (first == '(') continue;
text_stream *short_name = Str::new();
filename *F = Filenames::in(EP, leafname);
Filenames::write_unextended_leafname(short_name, F);
if ((Str::get_at(short_name, Str::len(short_name)-2) == '-') &&
((Str::get_at(short_name, Str::len(short_name)-1) == 'I')
|| (Str::get_at(short_name, Str::len(short_name)-1) == 'i')))
continue;
satellite_test_case *stc = CREATE(satellite_test_case);
stc->is_example = egs;
stc->owning_heading = NULL;
stc->owning_node = NULL;
stc->owner = cd;
stc->short_name = short_name;
stc->test_file = F;
stc->ideal_transcript = NULL;
TEMPORARY_TEXT(ideal_leafname)
WRITE_TO(ideal_leafname, "%S-I.txt", stc->short_name);
filename *IF = Filenames::in(EP, ideal_leafname);
if (TextFiles::exists(IF)) stc->ideal_transcript = IF;
DISCARD_TEXT(ideal_leafname)
if (stc->is_example) {
@<Scan the example for its header and content@>;
}
ADD_TO_LINKED_LIST(stc, satellite_test_case, cd->cases);
}
DISCARD_TEXT(leafname)
Directories::close(D);
@
=
typedef struct example_scanning_state {
int star_count;
struct text_stream *long_title;
struct text_stream *body_text;
struct text_stream *placement;
struct text_stream *desc;
struct linked_list *errors;
struct heterogeneous_tree *tree;
struct text_stream *scanning;
int past_header;
} example_scanning_state;
@<Scan the example for its header and content@> =
example_scanning_state ess;
ess.star_count = 1;
ess.long_title = NULL;
ess.body_text = Str::new();
ess.placement = NULL;
ess.desc = NULL;
ess.errors = NEW_LINKED_LIST(tree_node);
ess.tree = cd->tree;
ess.past_header = FALSE;
ess.scanning = Str::new(); WRITE_TO(ess.scanning, "%S", Filenames::get_leafname(stc->test_file));
TextFiles::read(stc->test_file, FALSE, "unable to read file of example", TRUE,
&DocumentationCompiler::read_example_helper, NULL, &ess);
tree_node *placement_node = NULL;
if (Str::len(ess.placement) == 0) {
DocumentationCompiler::example_error(&ess,
I"example does not give its Location");
} else {
placement_node = DocumentationTree::find_section(cd->tree, ess.placement);
if (placement_node == NULL) {
DocumentationCompiler::example_error(&ess,
I"example gives a Location which is not the name of any section");
}
}
if (Str::len(ess.desc) == 0) {
DocumentationCompiler::example_error(&ess,
I"example does not give its Description");
}
tree_node *content_node = NULL;
if (Str::len(ess.body_text) == 0) {
DocumentationCompiler::example_error(&ess,
I"example does not give any actual content");
} else {
compiled_documentation *ecd =
DocumentationCompiler::compile(ess.body_text, associated_extension);
if ((ecd) && (ecd->tree) && (ecd->tree->root) &&
(ecd->tree->root->child) &&
(ecd->tree->root->child->type == passage_TNT))
content_node = ecd->tree->root->child;
else {
DocumentationCompiler::example_error(&ess,
I"example file content is missing or wrongly set out");
}
}
tree_node *example_node = DocumentationTree::new_example(cd->tree,
ess.long_title, ess.desc, ess.star_count, ++(cd->total_examples));
if (placement_node) Trees::make_child(example_node, placement_node);
if (content_node) Trees::make_child(content_node, example_node);
tree_node *E;
LOOP_OVER_LINKED_LIST(E, tree_node, ess.errors)
Trees::make_child(E, cd->tree->root);
@ =
void DocumentationCompiler::example_error(example_scanning_state *ess, text_stream *text) {
text_stream *err = Str::new();
WRITE_TO(err, "Example file '%S': %S", ess->scanning, text);
tree_node *E = DocumentationTree::new_source_error(ess->tree, err);
ADD_TO_LINKED_LIST(E, tree_node, ess->errors);
}
@ =
void DocumentationCompiler::read_example_helper(text_stream *text, text_file_position *tfp,
void *v_state) {
example_scanning_state *ess = (example_scanning_state *) v_state;
if (tfp->line_count == 1) {
match_results mr = Regexp::create_mr();
if ((Regexp::match(&mr, text, L"Example *: *(%**) *(%c+?)")) ||
(Regexp::match(&mr, text, L"Example *- *(%**) *(%c+?)"))) {
ess->star_count = Str::len(mr.exp[0]);
if (ess->star_count == 0) {
DocumentationCompiler::example_error(ess,
I"this example should be marked (before the title) '*', '**', '***' or '****' for difficulty");
ess->star_count = 1;
}
if (ess->star_count > 4) {
DocumentationCompiler::example_error(ess,
I"four stars '****' is the maximum difficulty rating allowed");
ess->star_count = 4;
}
ess->long_title = Str::duplicate(mr.exp[1]);
} else {
DocumentationCompiler::example_error(ess,
I"titling line of example file is malformed");
}
Regexp::dispose_of(&mr);
} else if (ess->past_header == FALSE) {
if (Str::is_whitespace(text)) { ess->past_header = TRUE; return; }
match_results mr = Regexp::create_mr();
if (Regexp::match(&mr, text, L"(%C+?) *: *(%c+?)")) {
if (Str::eq(mr.exp[0], I"Location")) ess->placement = Str::duplicate(mr.exp[1]);
else if (Str::eq(mr.exp[0], I"Description")) ess->desc = Str::duplicate(mr.exp[1]);
else {
DocumentationCompiler::example_error(ess,
I"unknown datum in header line of example file");
}
} else {
DocumentationCompiler::example_error(ess,
I"header line of example file is malformed");
}
Regexp::dispose_of(&mr);
} else {
WRITE_TO(ess->body_text, "%S\n", text);
}
}
@
=
compiled_documentation *DocumentationCompiler::compile_from_file(filename *F,
inform_extension *associated_extension) {
@ -197,7 +387,7 @@ part of paragraphs; or indented ones, which are always part of code samples.
section_number = 0;
int level = 1, id = cd->total_headings[0] + cd->total_headings[1] + cd->total_headings[2];
cd->total_headings[1]++;
tree_node *new_node = DocumentationTree::new_heading(cd->tree, mr.exp[0], level,
tree_node *new_node = DocumentationTree::new_heading(cd->tree, mr.exp[0], mr.exp[0], level,
id, chapter_number, section_number);
@<Place this new structural node in the tree@>;
@ -206,14 +396,14 @@ part of paragraphs; or indented ones, which are always part of code samples.
section_number++;
int level = 2, id = cd->total_headings[0] + cd->total_headings[1] + cd->total_headings[2];
cd->total_headings[2]++;
tree_node *new_node = DocumentationTree::new_heading(cd->tree, mr.exp[0], level,
tree_node *new_node = DocumentationTree::new_heading(cd->tree, mr.exp[0], mr.exp[0], level,
id, chapter_number, section_number);
@<Place this new structural node in the tree@>;
@<Insert an example heading@> =
@<Complete passage if in one@>;
int level = 3, star_count = Str::len(mr.exp[0]);
tree_node *new_node = DocumentationTree::new_example(cd->tree, mr.exp[1],
tree_node *new_node = DocumentationTree::new_example(cd->tree, mr.exp[1], NULL,
star_count, ++(cd->total_examples));
@<Place this new structural node in the tree@>;
if (star_count == 0) {
@ -341,7 +531,23 @@ of a code sample either, since a non-blank indented line is needed to trigger on
Str::delete_first_character(line);
Str::trim_white_space(line);
continue_me = TRUE;
} else if ((Str::get_at(line, 0) == '{') && (Str::get_at(line, 1) == '*') &&
(Str::get_at(line, 2) == '}')) {
Str::delete_first_character(line);
Str::delete_first_character(line);
Str::delete_first_character(line);
Str::trim_white_space(line);
paste_me = TRUE;
} else if ((Str::get_at(line, 0) == '{') && (Str::get_at(line, 1) == '*') &&
(Str::get_at(line, 2) == '*') && (Str::get_at(line, 3) == '}')) {
Str::delete_first_character(line);
Str::delete_first_character(line);
Str::delete_first_character(line);
Str::delete_first_character(line);
Str::trim_white_space(line);
continue_me = TRUE;
}
current_code = DocumentationTree::new_code_sample(cd->tree, paste_me, language);
if (continue_me) {
if (last_paste_code) {

10
inbuild/supervisor-module/Chapter 7/Documentation Renderer.w
View file

@ -471,12 +471,7 @@ int DocumentationRenderer::body_visitor(tree_node *N, void *state, int L) {
if (M) WRITE_TO(matter, "\n\n");
} else break;
}
TEMPORARY_TEXT(paste)
WRITE_TO(paste, "<span class=\"paste\">%cV</span>", 0x2318);
/* the Unicode for "place of interest", the Swedish castle which became the Apple action symbol */
PasteButtons::paste_text_using(OUT, matter, paste);
DISCARD_TEXT(paste)
WRITE("&nbsp;");
ExtensionWebsite::paste_button(OUT, matter);
DISCARD_TEXT(matter)
@<Render the body of the code sample@> =
@ -568,7 +563,6 @@ and this is fiddly but elementary in the usual way of HTML tables:
HTML::end_html_row(OUT);
@<End I7 table in extension documentation@> =
HTML::end_html_row(OUT);
HTML::end_html_table(OUT);
HTML::begin_span(OUT, I"indexdullblue");
@ -611,6 +605,8 @@ void DocumentationRenderer::render_example_heading(OUTPUT_STREAM, tree_node *EN,
HTML::end_span(OUT);
HTML::begin_span(OUT, I"indexblack");
DocumentationRenderer::render_text(OUT, E->name);
HTML_TAG("br");
DocumentationRenderer::render_text(OUT, E->description);
HTML::end_span(OUT);
HTML_CLOSE("b");

33
inbuild/supervisor-module/Chapter 7/Documentation Tree.w
View file

@ -41,7 +41,7 @@ heterogeneous_tree *DocumentationTree::new(void) {
&DocumentationTree::source_error_verifier);
}
heterogeneous_tree *tree = Trees::new(cdoc_tree_TT);
Trees::make_root(tree, DocumentationTree::new_heading(tree, I"(root)", 0, 0, 0, 0));
Trees::make_root(tree, DocumentationTree::new_heading(tree, I"(root)", NULL, 0, 0, 0, 0));
return tree;
}
@ -63,19 +63,21 @@ which is otherwise something like |5| (chapter 5) or |3.4| (section 4 in chapter
typedef struct cdoc_heading {
struct text_stream *count;
struct text_stream *name;
struct text_stream *recognition_name;
int level; /* 0 = root, 1 = chapter, 2 = section */
int ID;
CLASS_DEFINITION
} cdoc_heading;
tree_node *DocumentationTree::new_heading(heterogeneous_tree *tree,
text_stream *title, int level, int ID, int cc, int sc) {
text_stream *title, text_stream *recognise_as, int level, int ID, int cc, int sc) {
cdoc_heading *H = CREATE(cdoc_heading);
H->count = Str::new();
if (cc > 0) WRITE_TO(H->count, "%d", cc);
if ((cc > 0) && (sc > 0)) WRITE_TO(H->count, ".");
if (sc > 0) WRITE_TO(H->count, "%d", sc);
H->name = Str::duplicate(title);
H->recognition_name = Str::duplicate(recognise_as);
H->level = level;
H->ID = ID;
return Trees::new_node(tree, heading_TNT, STORE_POINTER_cdoc_heading(H));
@ -102,6 +104,7 @@ letters are unique from A, B, C, ...
=
typedef struct cdoc_example {
struct text_stream *name;
struct text_stream *description;
int star_count;
int number;
char letter;
@ -109,9 +112,10 @@ typedef struct cdoc_example {
} cdoc_example;
tree_node *DocumentationTree::new_example(heterogeneous_tree *tree,
text_stream *title, int star_count, int ecount) {
text_stream *title, text_stream *desc, int star_count, int ecount) {
cdoc_example *E = CREATE(cdoc_example);
E->name = Str::duplicate(title);
E->description = Str::duplicate(desc);
E->star_count = star_count;
E->number = ecount;
E->letter = 'A' + (char) ecount - 1;
@ -289,6 +293,7 @@ tree_node *DocumentationTree::find_example(heterogeneous_tree *T, int eg) {
dc_find_example_task task;
task.to_find_example = eg;
task.to_find_heading = NULL;
task.to_find_section = NULL;
task.result = NULL;
Trees::traverse_from(T->root, &DocumentationTree::find_visit, (void *) &task, 0);
return task.result;
@ -299,6 +304,18 @@ tree_node *DocumentationTree::find_chapter(heterogeneous_tree *T, int ch) {
dc_find_example_task task;
task.to_find_example = 0;
task.to_find_heading = Str::new(); WRITE_TO(task.to_find_heading, "%d", ch);
task.to_find_section = NULL;
task.result = NULL;
Trees::traverse_from(T->root, &DocumentationTree::find_visit, (void *) &task, 0);
return task.result;
}
tree_node *DocumentationTree::find_section(heterogeneous_tree *T, text_stream *name) {
if (Str::len(name) == 0) return NULL;
dc_find_example_task task;
task.to_find_example = 0;
task.to_find_heading = NULL;
task.to_find_section = name;
task.result = NULL;
Trees::traverse_from(T->root, &DocumentationTree::find_visit, (void *) &task, 0);
return task.result;
@ -307,6 +324,7 @@ tree_node *DocumentationTree::find_chapter(heterogeneous_tree *T, int ch) {
typedef struct dc_find_example_task {
int to_find_example;
struct text_stream *to_find_heading;
struct text_stream *to_find_section;
struct tree_node *result;
} dc_find_example_task;
@ -327,5 +345,14 @@ int DocumentationTree::find_visit(tree_node *N, void *state, int L) {
return FALSE;
}
}
if ((task->to_find_section) && (N->type == heading_TNT)) {
cdoc_heading *E = RETRIEVE_POINTER_cdoc_heading(N->content);
LOG("Want %S find %S\n", task->to_find_section, E->recognition_name);
if ((E->level == 2) && (Str::eq_insensitive(E->recognition_name, task->to_find_section))) {
task->result = N;
return FALSE;
}
}
return TRUE;
}

19
inbuild/supervisor-module/Chapter 7/Extensions Index Page.w
View file

@ -383,7 +383,7 @@ the usual ones seen in Mac OS X applications such as iTunes.
WRITE(" ");
TEMPORARY_TEXT(inclusion_text)
WRITE_TO(inclusion_text, "Include %X.\n\n\n", res->copy->edition->work);
PasteButtons::paste_text(OUT, inclusion_text);
ExtensionWebsite::paste_button(OUT, inclusion_text);
DISCARD_TEXT(inclusion_text)
ExtensionIndex::add_to_key(key_list, PASTE_SYMBOL,
I"Source text to Include this (click to paste in)");
@ -481,7 +481,7 @@ There is just no need to do this efficiently in either running time or memory.
@d PROBLEM_SYMBOL "border=\"0\" height=\"12\" src=\"inform:/doc_images/census_problem.png\""
@d REVEAL_SYMBOL "border=\"0\" src=\"inform:/doc_images/Reveal.png\""
@d HELP_SYMBOL "border=\"0\" src=\"inform:/doc_images/help.png\""
@d PASTE_SYMBOL "border=\"0\" src=\"inform:/doc_images/paste.png\""
@d PASTE_SYMBOL "paste"
@d BUILT_IN_SYMBOL "border=\"0\" src=\"inform:/doc_images/builtin_ext.png\""
@d PROJECT_SPECIFIC_SYMBOL "border=\"0\" src=\"inform:/doc_images/folder4.png\""
@d LEGACY_AREA_SYMBOL "border=\"0\" src=\"inform:/doc_images/pspec_ext.png\""
@ -493,6 +493,7 @@ typedef struct extensions_key_item {
struct text_stream *image_URL;
struct text_stream *gloss;
int displayed;
int ideograph;
CLASS_DEFINITION
} extensions_key_item;
@ -509,6 +510,8 @@ void ExtensionIndex::add_to_key(linked_list *L, char *URL, text_stream *gloss) {
eki->image_URL = Str::duplicate(as_text);
eki->gloss = Str::duplicate(gloss);
eki->displayed = FALSE;
eki->ideograph = FALSE;
if (Str::eq(as_text, I"paste")) eki->ideograph = TRUE;
ADD_TO_LINKED_LIST(eki, extensions_key_item, L);
}
DISCARD_TEXT(as_text)
@ -528,7 +531,7 @@ void ExtensionIndex::render_key(OUTPUT_STREAM, linked_list *L) {
extensions_key_item *eki;
LOOP_OVER_LINKED_LIST(eki, extensions_key_item, L) {
if (Str::eq(eki->image_URL, as_text)) {
HTML_TAG_WITH("img", "%S", eki->image_URL);
ExtensionIndex::render_icon(OUT, eki);
WRITE("&nbsp;%S &nbsp;&nbsp;", eki->gloss);
eki->displayed = TRUE;
}
@ -538,7 +541,7 @@ void ExtensionIndex::render_key(OUTPUT_STREAM, linked_list *L) {
extensions_key_item *eki;
LOOP_OVER_LINKED_LIST(eki, extensions_key_item, L) {
if (eki->displayed == FALSE) {
HTML_TAG_WITH("img", "%S", eki->image_URL);
ExtensionIndex::render_icon(OUT, eki);
WRITE("&nbsp;%S &nbsp;&nbsp;", eki->gloss);
eki->displayed = TRUE;
}
@ -546,6 +549,14 @@ void ExtensionIndex::render_key(OUTPUT_STREAM, linked_list *L) {
HTML_CLOSE("p");
}
void ExtensionIndex::render_icon(OUTPUT_STREAM, extensions_key_item *eki) {
if (eki->ideograph) {
ExtensionWebsite::paste_ideograph(OUT);
} else {
HTML_TAG_WITH("img", "%S", eki->image_URL);
}
}
@h Icons for virtual machines.
And everything else is cosmetic: printing, or showing icons to signify,
the current VM or some set of permitted VMs. The following plots the

16
inbuild/supervisor-module/Chapter 7/The Mini-Website.w
View file

@ -216,3 +216,19 @@ void ExtensionWebsite::titling_and_navigation(OUTPUT_STREAM, text_stream *subtit
HTML_CLOSE("div");
no_EXW_breadcrumbs = 0;
}
@ This is a new-look paste button, using a "command-V" ideograph rather than
a somewhat enigmatic icon.
=
void ExtensionWebsite::paste_button(OUTPUT_STREAM, text_stream *matter) {
TEMPORARY_TEXT(paste)
ExtensionWebsite::paste_ideograph(paste);
PasteButtons::paste_text_using(OUT, matter, paste);
DISCARD_TEXT(paste)
WRITE("&nbsp;");
}
void ExtensionWebsite::paste_ideograph(OUTPUT_STREAM) {
/* the Unicode for "place of interest", the Swedish castle which became the Apple action symbol */
WRITE("<span class=\"paste\">%cV</span>", 0x2318);
}

104
inform7/Figures/memory-diagnostics.txt
View file

@ -1,33 +1,33 @@
Total memory consumption was 139568K = 136 MB
Total memory consumption was 137254K = 134 MB
---- was used for 2122779 objects, in 374830 frames in 0 x 800K = 0K = 0 MB:
---- was used for 2122978 objects, in 374831 frames in 0 x 800K = 0K = 0 MB:
30.2% inter_tree_node_array 60 x 8192 = 491520 objects, 43255680 bytes
19.2% text_stream_array 4881 x 100 = 488100 objects, 27489792 bytes
17.7% linked_list 45342 objects, 25391520 bytes
10.0% inter_symbol_array 135 x 1024 = 138240 objects, 14381280 bytes
9.8% inter_error_stash_array 107 x 1024 = 109568 objects, 14028128 bytes
7.4% parse_node 133764 objects, 10701120 bytes
5.3% verb_conjugation 164 objects, 7610912 bytes
30.7% inter_tree_node_array 60 x 8192 = 491520 objects, 43255680 bytes
19.5% text_stream_array 4882 x 100 = 488200 objects, 27495424 bytes
18.0% linked_list 45345 objects, 25393200 bytes
10.2% inter_symbol_array 135 x 1024 = 138240 objects, 14381280 bytes
9.9% inter_error_stash_array 107 x 1024 = 109568 objects, 14028128 bytes
7.6% parse_node 133764 objects, 10701120 bytes
5.4% verb_conjugation 164 objects, 7610912 bytes
4.0% parse_node_annotation_array 357 x 500 = 178500 objects, 5723424 bytes
3.1% scan_directory 1091 objects, 4503648 bytes
2.4% pcalc_prop_array 26 x 1000 = 26000 objects, 3536832 bytes
3.2% scan_directory 1091 objects, 4503648 bytes
2.5% pcalc_prop_array 26 x 1000 = 26000 objects, 3536832 bytes
2.2% inter_name_array 67 x 1000 = 67000 objects, 3218144 bytes
1.9% kind_array 68 x 1000 = 68000 objects, 2722176 bytes
1.5% inter_schema_token 14176 objects, 2154752 bytes
1.4% inter_name_generator_array 51 x 1000 = 51000 objects, 2041632 bytes
1.3% package_request 21340 objects, 1877920 bytes
1.2% vocabulary_entry_array 163 x 100 = 16300 objects, 1830816 bytes
1.1% dict_entry_array 490 x 100 = 49000 objects, 1583680 bytes
1.3% vocabulary_entry_array 163 x 100 = 16300 objects, 1830816 bytes
1.1% dict_entry_array 491 x 100 = 49100 objects, 1586912 bytes
1.0% inter_symbols_table 26913 objects, 1507128 bytes
1.0% match_trie_array 11 x 1000 = 11000 objects, 1496352 bytes
1.0% i6_schema_array 24 x 100 = 2400 objects, 1440768 bytes
0.9% inter_package 26913 objects, 1291824 bytes
0.7% map_data 677 objects, 1137360 bytes
0.8% map_data 677 objects, 1137360 bytes
0.7% id_body 977 objects, 1117688 bytes
0.7% adjective_meaning 208 objects, 1030016 bytes
0.7% inter_schema_node 9066 objects, 1015392 bytes
0.6% excerpt_meaning 3162 objects, 986544 bytes
0.7% excerpt_meaning 3162 objects, 986544 bytes
0.6% production 3985 objects, 924520 bytes
0.6% ptoken 8652 objects, 899808 bytes
0.6% grammatical_usage 3648 objects, 875520 bytes
@ -47,7 +47,7 @@ Total memory consumption was 139568K = 136 MB
0.1% hierarchy_location 1189 objects, 171216 bytes
0.1% linguistic_stock_item 3338 objects, 160224 bytes
0.1% rule_family_data 404 objects, 148672 bytes
---- nonterminal 773 objects, 142232 bytes
0.1% nonterminal 773 objects, 142232 bytes
---- nascent_array 2130 objects, 136320 bytes
---- inference 1705 objects, 122760 bytes
---- pcalc_term_array 3 x 1000 = 3000 objects, 120096 bytes
@ -65,8 +65,8 @@ Total memory consumption was 139568K = 136 MB
---- spatial_data 677 objects, 64992 bytes
---- kind_constructor 79 objects, 64464 bytes
---- linked_list_item_array 4 x 1000 = 4000 objects, 64128 bytes
---- actions_rcd_data 1954 objects, 62528 bytes
---- scenes_rcd_data 1954 objects, 62528 bytes
---- actions_rcd_data 1954 objects, 62528 bytes
---- booking 868 objects, 62496 bytes
---- kind_macro_definition 9 objects, 62280 bytes
---- command_grammar 130 objects, 58240 bytes
@ -81,8 +81,8 @@ Total memory consumption was 139568K = 136 MB
---- heading 212 objects, 47488 bytes
---- text_substitution 438 objects, 42048 bytes
---- to_family_data 525 objects, 42000 bytes
---- anl_clause_array 1 x 1000 objects, 40032 bytes
---- activity_list_array 1 x 1000 objects, 40032 bytes
---- anl_clause_array 1 x 1000 objects, 40032 bytes
---- shared_variable_access_list_array 12 x 100 = 1200 objects, 38784 bytes
---- parsing_data 677 objects, 37912 bytes
---- production_list 627 objects, 35112 bytes
@ -109,14 +109,14 @@ Total memory consumption was 139568K = 136 MB
---- pcalc_prop_deferral 86 objects, 17888 bytes
---- to_phrase_request 63 objects, 17136 bytes
---- understanding_reference_array 2 x 100 = 200 objects, 16064 bytes
---- action_name_list_array 1 x 1000 objects, 16032 bytes
---- match_avinue_array 1 x 1000 objects, 16032 bytes
---- action_name_list_array 1 x 1000 objects, 16032 bytes
---- adjective 140 objects, 15680 bytes
---- JSON_value 174 objects, 15312 bytes
---- booking_list 407 objects, 13024 bytes
---- web_bibliographic_datum 203 objects, 12992 bytes
---- adjective_iname_holder 323 objects, 12920 bytes
---- tree_node 149 objects, 11920 bytes
---- tree_node 148 objects, 11840 bytes
---- uniqueness_count 482 objects, 11568 bytes
---- inter_construct 32 objects, 11008 bytes
---- stopwatch_timer 124 objects, 9920 bytes
@ -145,8 +145,8 @@ Total memory consumption was 139568K = 136 MB
---- command_line_switch 55 objects, 4400 bytes
---- semver_range 42 objects, 4368 bytes
---- use_option 31 objects, 4216 bytes
---- either_or_property_data 62 objects, 3968 bytes
---- parse_node_annotation_type 124 objects, 3968 bytes
---- either_or_property_data 62 objects, 3968 bytes
---- method_set 109 objects, 3488 bytes
---- definition 48 objects, 3456 bytes
---- property_setting_bp_data 86 objects, 3440 bytes
@ -157,8 +157,8 @@ Total memory consumption was 139568K = 136 MB
---- JSON_single_requirement 55 objects, 2640 bytes
---- part_of_inference_data 79 objects, 2528 bytes
---- parentage_inference_data 79 objects, 2528 bytes
---- kind_constructor_casting_rule_array 1 x 100 objects, 2432 bytes
---- kind_constructor_instance_rule_array 1 x 100 objects, 2432 bytes
---- kind_constructor_casting_rule_array 1 x 100 objects, 2432 bytes
---- equation_symbol 30 objects, 2400 bytes
---- scene 1 object, 2352 bytes
---- build_step 28 objects, 2016 bytes
@ -181,24 +181,24 @@ Total memory consumption was 139568K = 136 MB
---- runtime_kind_structure 13 objects, 1040 bytes
---- quantifier 16 objects, 1024 bytes
---- web_md 7 objects, 1008 bytes
---- pipeline_stage 20 objects, 960 bytes
---- named_rulebook_outcome 15 objects, 960 bytes
---- pipeline_stage 20 objects, 960 bytes
---- JSON_pair_requirement 29 objects, 928 bytes
---- control_structure_phrase 12 objects, 864 bytes
---- kit_configuration 21 objects, 840 bytes
---- cached_understanding 21 objects, 840 bytes
---- phrase_option_array 1 x 100 objects, 824 bytes
---- copy_error 7 objects, 784 bytes
---- inform_kit 7 objects, 784 bytes
---- copy_error 7 objects, 784 bytes
---- internal_test 15 objects, 720 bytes
---- relation_guard 5 objects, 640 bytes
---- implication 13 objects, 624 bytes
---- chapter_md 7 objects, 616 bytes
---- cdoc_paragraph 18 objects, 576 bytes
---- code_generation 1 object, 576 bytes
---- inter_warehouse_room 10 objects, 560 bytes
---- generated_segment 14 objects, 560 bytes
---- module 7 objects, 560 bytes
---- generated_segment 14 objects, 560 bytes
---- inter_warehouse_room 10 objects, 560 bytes
---- inter_annotation_form 14 objects, 560 bytes
---- rulebook_outcome 17 objects, 544 bytes
---- small_word_set 11 objects, 528 bytes
@ -210,76 +210,76 @@ Total memory consumption was 139568K = 136 MB
---- source_file 5 objects, 400 bytes
---- tree_node_type 8 objects, 384 bytes
---- article_usage 8 objects, 384 bytes
---- module_request 8 objects, 320 bytes
---- tree_inventory 1 object, 320 bytes
---- grammatical_category 8 objects, 320 bytes
---- door_dir_notice 5 objects, 320 bytes
---- cached_kind_declaration 8 objects, 320 bytes
---- pronoun 8 objects, 320 bytes
---- tree_inventory 1 object, 320 bytes
---- module_request 8 objects, 320 bytes
---- door_dir_notice 5 objects, 320 bytes
---- inter_pipeline 1 object, 312 bytes
---- cdoc_code_sample 6 objects, 288 bytes
---- compiled_documentation 4 objects, 288 bytes
---- up_family 9 objects, 288 bytes
---- explicit_bp_data 5 objects, 280 bytes
---- compilation_unit 5 objects, 280 bytes
---- door_to_notice 5 objects, 280 bytes
---- compilation_unit 5 objects, 280 bytes
---- contents_entry 7 objects, 280 bytes
---- kit_dependency 5 objects, 240 bytes
---- explicit_bp_data 5 objects, 280 bytes
---- compiled_documentation 3 objects, 264 bytes
---- verb_usage_tier 5 objects, 240 bytes
---- kit_dependency 5 objects, 240 bytes
---- inform_project 1 object, 232 bytes
---- local_block_value 4 objects, 224 bytes
---- adjective_meaning_family 7 objects, 224 bytes
---- local_block_value 4 objects, 224 bytes
---- test_scenario 1 object, 216 bytes
---- release_instructions 1 object, 208 bytes
---- attachment_instruction 5 objects, 200 bytes
---- code_generator 5 objects, 200 bytes
---- build_skill 5 objects, 200 bytes
---- cdoc_heading 4 objects, 192 bytes
---- code_generator 5 objects, 200 bytes
---- cdoc_example 4 objects, 192 bytes
---- plural_dictionary_entry 4 objects, 192 bytes
---- element_activation 6 objects, 192 bytes
---- cdoc_passage 7 objects, 168 bytes
---- heterogeneous_tree 4 objects, 160 bytes
---- imperative_defn_family 4 objects, 160 bytes
---- cdoc_example 4 objects, 160 bytes
---- inference_subject_family 5 objects, 160 bytes
---- cdoc_heading 3 objects, 168 bytes
---- inter_architecture 4 objects, 160 bytes
---- imperative_defn_family 4 objects, 160 bytes
---- inference_subject_family 5 objects, 160 bytes
---- inbuild_nest 3 objects, 120 bytes
---- heterogeneous_tree 3 objects, 120 bytes
---- inform_language 1 object, 104 bytes
---- article 2 objects, 80 bytes
---- compile_task_data 1 object, 80 bytes
---- group_together_function 2 objects, 80 bytes
---- figures_data 1 object, 56 bytes
---- build_methodology 1 object, 56 bytes
---- inter_warehouse 1 object, 56 bytes
---- figures_data 1 object, 56 bytes
---- HTML_file_state 1 object, 48 bytes
---- inform_kit_ittt 1 object, 48 bytes
---- star_invention 1 object, 48 bytes
---- target_pragma_setting 1 object, 40 bytes
---- tree_type 1 object, 40 bytes
---- loop_over_scope 1 object, 40 bytes
---- kind_template_definition 1 object, 40 bytes
---- I6_generation_data 1 object, 40 bytes
---- by_function_bp_data 1 object, 40 bytes
---- tree_type 1 object, 40 bytes
---- target_pragma_setting 1 object, 40 bytes
---- loop_over_scope 1 object, 40 bytes
100.0% was used for memory not allocated for objects:
62.3% text stream storage 89055024 bytes in 508489 claims
61.6% text stream storage 86685820 bytes in 508181 claims
3.8% dictionary storage 5479936 bytes in 7752 claims
---- sorting 2624 bytes in 531 claims
5.0% source text 7200000 bytes in 3 claims
7.5% source text details 10800000 bytes in 2 claims
5.1% source text 7200000 bytes in 3 claims
7.6% source text details 10800000 bytes in 2 claims
0.1% documentation fragments 262144 bytes in 1 claim
---- linguistic stock array 81920 bytes in 2 claims
---- small word set array 105600 bytes in 22 claims
3.2% inter symbols storage 4703712 bytes in 28290 claims
11.7% inter bytecode storage 16758140 bytes in 15 claims
4.3% inter links storage 6222976 bytes in 11 claims
3.3% inter symbols storage 4703712 bytes in 28290 claims
11.9% inter bytecode storage 16758140 bytes in 15 claims
4.4% inter links storage 6222976 bytes in 11 claims
0.1% inter tree location list storage 191232 bytes in 32 claims
1.2% instance-of-kind counting 1731856 bytes in 1 claim
---- compilation workspace for objects 21936 bytes in 25 claims
---- lists for type-checking invocations 16000 bytes in 1 claim
---- code generation workspace for objects 3488 bytes in 19 claims
0.1% emitter array storage 281184 bytes in 2006 claims
0.2% emitter array storage 281184 bytes in 2006 claims
-136.-4% was overhead - -194989176 bytes = -190419K = -185 MB
-138.-7% was overhead - -194999584 bytes = -190429K = -185 MB

26
inform7/Figures/timings-diagnostics.txt
View file

@ -1,29 +1,29 @@
100.0% in inform7 run
67.4% in compilation to Inter
45.4% in //Sequence::undertake_queued_tasks//
4.5% in //MajorNodes::pre_pass//
45.7% in //Sequence::undertake_queued_tasks//
4.2% in //MajorNodes::pre_pass//
3.4% in //MajorNodes::pass_1//
1.8% in //ImperativeDefinitions::assess_all//
1.8% in //RTPhrasebook::compile_entries//
1.9% in //ImperativeDefinitions::assess_all//
1.5% in //RTKindConstructors::compile//
1.5% in //RTPhrasebook::compile_entries//
1.1% in //Sequence::lint_inter//
0.7% in //Sequence::undertake_queued_tasks//
0.3% in //CompletionModule::compile//
0.3% in //ImperativeDefinitions::compile_first_block//
0.3% in //MajorNodes::pass_2//
0.3% in //RTKindConstructors::compile_permissions//
0.3% in //Sequence::undertake_queued_tasks//
0.3% in //Sequence::undertake_queued_tasks//
0.3% in //World::stage_V//
4.6% not specifically accounted for
27.6% in running Inter pipeline
9.4% in step 14/15: generate inform6 -> auto.inf
6.8% in step 5/15: load-binary-kits
6.0% in step 6/15: make-synoptic-module
1.8% in step 9/15: make-identifiers-unique
5.0% not specifically accounted for
28.2% in running Inter pipeline
9.6% in step 14/15: generate inform6 -> auto.inf
6.9% in step 5/15: load-binary-kits
5.8% in step 6/15: make-synoptic-module
1.9% in step 9/15: make-identifiers-unique
0.3% in step 12/15: eliminate-redundant-operations
0.3% in step 4/15: compile-splats
0.3% in step 7/15: shorten-wiring
0.3% in step 8/15: detect-indirect-calls
1.9% not specifically accounted for
4.1% in supervisor
2.3% not specifically accounted for
3.4% in supervisor
0.8% not specifically accounted for

2
inform7/Internal/Inter/Architecture16Kit/kit_metadata.json
View file

@ -2,7 +2,7 @@
"is": {
"type": "kit",
"title": "Architecture16Kit",
"version": "10.2.0-beta+6W86"
"version": "10.2.0-beta+6W87"
},
"compatibility": "16-bit",
"kit-details": {

2
inform7/Internal/Inter/Architecture32Kit/kit_metadata.json
View file

@ -2,7 +2,7 @@
"is": {
"type": "kit",
"title": "Architecture32Kit",
"version": "10.2.0-beta+6W86"
"version": "10.2.0-beta+6W87"
},
"compatibility": "32-bit",
"kit-details": {

2
inform7/Internal/Inter/BasicInformKit/kit_metadata.json
View file

@ -2,7 +2,7 @@
"is": {
"type": "kit",
"title": "BasicInformKit",
"version": "10.2.0-beta+6W86"
"version": "10.2.0-beta+6W87"
},
"needs": [ {
"need": {

2
inform7/Internal/Inter/CommandParserKit/kit_metadata.json
View file

@ -2,7 +2,7 @@
"is": {
"type": "kit",
"title": "CommandParserKit",
"version": "10.2.0-beta+6W86"
"version": "10.2.0-beta+6W87"
},
"needs": [ {
"need": {

2
inform7/Internal/Inter/EnglishLanguageKit/kit_metadata.json
View file

@ -2,7 +2,7 @@
"is": {
"type": "kit",
"title": "EnglishLanguageKit",
"version": "10.2.0-beta+6W86"
"version": "10.2.0-beta+6W87"
},
"needs": [ {
"need": {

2
inform7/Internal/Inter/WorldModelKit/kit_metadata.json
View file

@ -2,7 +2,7 @@
"is": {
"type": "kit",
"title": "WorldModelKit",
"version": "10.2.0-beta+6W86"
"version": "10.2.0-beta+6W87"
},
"needs": [ {
"need": {