ifhub/inform7
1
0
Fork 0
mirror of https://github.com/ganelson/inform.git synced 2024-07-16 14:04:24 +03:00
Code Issues Projects Releases Wiki Activity
inform7/docs/supervisor-module/7-dt.html
Graham Nelson 097d74b62d Progress towards extension pages
2023-07-17 22:54:02 +01:00

355 lines
70 KiB
HTML
Raw Blame History

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Documentation Tree</title>
<link href="../docs-assets/Breadcrumbs.css" rel="stylesheet" rev="stylesheet" type="text/css">
<meta name="viewport" content="width=device-width initial-scale=1">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="Content-Language" content="en-gb">
<link href="../docs-assets/Contents.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Progress.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Navigation.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Fonts.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Base.css" rel="stylesheet" rev="stylesheet" type="text/css">
<script>
function togglePopup(material_id) {
var popup = document.getElementById(material_id);
popup.classList.toggle("show");
}
</script>
<link href="../docs-assets/Popups.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
</head>
<body class="commentary-font">
<nav role="navigation">
<h1><a href="../index.html">
<img src="../docs-assets/Inform.png" height=72">
</a></h1>
<ul><li><a href="../index.html">home</a></li>
</ul><h2>Compiler</h2><ul>
<li><a href="../structure.html">structure</a></li>
<li><a href="../inbuildn.html">inbuild</a></li>
<li><a href="../inform7n.html">inform7</a></li>
<li><a href="../intern.html">inter</a></li>
<li><a href="../services.html">services</a></li>
<li><a href="../secrets.html">secrets</a></li>
</ul><h2>Other Tools</h2><ul>
<li><a href="../inblorbn.html">inblorb</a></li>
<li><a href="../indocn.html">indoc</a></li>
<li><a href="../inform6.html">inform6</a></li>
<li><a href="../inpolicyn.html">inpolicy</a></li>
<li><a href="../inrtpsn.html">inrtps</a></li>
</ul><h2>Resources</h2><ul>
<li><a href="../extensions.html">extensions</a></li>
<li><a href="../kits.html">kits</a></li>
</ul><h2>Repository</h2><ul>
<li><a href="https://github.com/ganelson/inform"><img src="../docs-assets/github.png" height=18> github</a></li>
</ul><h2>Related Projects</h2><ul>
<li><a href="../../../inweb/index.html">inweb</a></li>
<li><a href="../../../intest/index.html">intest</a></li>
</ul>
</nav>
<main role="main">
<!--Weave of 'Documentation Tree' generated by Inweb-->
<div class="breadcrumbs">
<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#7">Chapter 7: Extension Indexing</a></li><li><b>Documentation Tree</b></li></ul></div>
<p class="purpose">A data structure to hold segments of Inform resource documentation.</p>
<ul class="toc"><li><a href="7-dt.html#SP1">&#167;1. The tree itself</a></li></ul><hr class="tocbar">
<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>&#167;1. The tree itself. </b>We will store the content in a heterogeneous tree: see <a href="../../../inweb/foundation-module/2-trs.html" class="internal">Trees (in foundation)</a>.
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">tree_type</span><span class="plain-syntax"> *</span><span class="identifier-syntax">cdoc_tree_TT</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">; </span><span class="comment-syntax"> The only tree type we use in this section</span>
<span class="identifier-syntax">tree_node_type</span>
<span class="plain-syntax"> *</span><span class="identifier-syntax">heading_TNT</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">example_TNT</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">passage_TNT</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">paragraph_TNT</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">code_sample_TNT</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">code_line_TNT</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="identifier-syntax">heterogeneous_tree</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationTree::new</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">DocumentationTree::new</span></span>:<br/>Documentation Compiler - <a href="7-dc.html#SP1">&#167;1</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="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">cdoc_tree_TT</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">cdoc_tree_TT</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Trees::new_type</span><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="string-syntax">"documentation tree"</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> &amp;</span><a href="7-dt.html#SP2" class="function-link"><span class="function-syntax">DocumentationTree::verify_root</span></a><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">heading_TNT</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Trees::new_node_type</span><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="string-syntax">"heading"</span><span class="plain-syntax">, </span><span class="constant-syntax">cdoc_heading_CLASS</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> &amp;</span><a href="7-dt.html#SP4" class="function-link"><span class="function-syntax">DocumentationTree::heading_verifier</span></a><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">example_TNT</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Trees::new_node_type</span><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="string-syntax">"example"</span><span class="plain-syntax">, </span><span class="constant-syntax">cdoc_example_CLASS</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> &amp;</span><a href="7-dt.html#SP6" class="function-link"><span class="function-syntax">DocumentationTree::example_verifier</span></a><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">passage_TNT</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Trees::new_node_type</span><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="string-syntax">"passage"</span><span class="plain-syntax">, </span><span class="constant-syntax">cdoc_passage_CLASS</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> &amp;</span><a href="7-dt.html#SP8" class="function-link"><span class="function-syntax">DocumentationTree::passage_verifier</span></a><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">paragraph_TNT</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Trees::new_node_type</span><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="string-syntax">"paragraph"</span><span class="plain-syntax">, </span><span class="constant-syntax">cdoc_paragraph_CLASS</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> &amp;</span><a href="7-dt.html#SP9" class="function-link"><span class="function-syntax">DocumentationTree::paragraph_verifier</span></a><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">code_sample_TNT</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Trees::new_node_type</span><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="string-syntax">"code sample"</span><span class="plain-syntax">, </span><span class="constant-syntax">cdoc_code_sample_CLASS</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> &amp;</span><a href="7-dt.html#SP11" class="function-link"><span class="function-syntax">DocumentationTree::code_sample_verifier</span></a><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">code_line_TNT</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Trees::new_node_type</span><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="string-syntax">"line"</span><span class="plain-syntax">, </span><span class="constant-syntax">cdoc_code_line_CLASS</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> &amp;</span><a href="7-dt.html#SP12" class="function-link"><span class="function-syntax">DocumentationTree::code_line_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="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>
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>&#167;2. </b>The root of the tree is required to be a heading node.
</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">DocumentationTree::verify_root</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">DocumentationTree::verify_root</span></span>:<br/><a href="7-dt.html#SP1">&#167;1</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">tree_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="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="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="identifier-syntax">N</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">next</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="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>
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>&#167;3. </b>Heading nodes are used for the root (which has ID 0 and level 0) and then for
all chapter and section headings (which have levels 1 and 2 respectively). All
ID numbers are unique. The root heading is the only one with an empty "count",
which is otherwise something like <span class="extract"><span class="extract-syntax">5</span></span> (chapter 5) or <span class="extract"><span class="extract-syntax">3.4</span></span> (section 4 in chapter 3).
</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">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">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#SP2_1_1_1_1">&#167;2.1.1.1.1</a>, <a href="7-dc.html#SP2_1_1_1_2">&#167;2.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="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">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>
<span class="plain-syntax">}</span>
</pre>
<ul class="endnotetexts"><li>The structure cdoc_heading is accessed in 1/sm, 3/bs2, 6/hdn, 7/dr and here.</li></ul>
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>&#167;4. </b>A heading node can only have headings or examples as children, except that
it can have a single passage node as its first child. If so, this is introductory
text.
</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">DocumentationTree::heading_verifier</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">DocumentationTree::heading_verifier</span></span>:<br/><a href="7-dt.html#SP1">&#167;1</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">tree_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="reserved-syntax">for</span><span class="plain-syntax"> (</span><span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">C</span><span class="plain-syntax"> = </span><span class="identifier-syntax">N</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">child</span><span class="plain-syntax">; </span><span class="identifier-syntax">C</span><span class="plain-syntax">; </span><span class="identifier-syntax">C</span><span class="plain-syntax"> = </span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">next</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">-&gt;</span><span class="element-syntax">type</span><span class="plain-syntax"> != </span><span class="identifier-syntax">heading_TNT</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">type</span><span class="plain-syntax"> != </span><span class="identifier-syntax">example_TNT</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">C</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="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">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">C</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">) &amp;&amp; (</span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">next</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="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>
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>&#167;5. </b>Example nodes are used for the lettered examples in a documentation segment.
They have a "difficulty rating" in stars, 0 to 4. Numbers are unique from 1, 2, ...;
letters are unique from A, B, C, ...
</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">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">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#SP2_1_1_1_3">&#167;2.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="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">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>
<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>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">DocumentationTree::example_verifier</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">DocumentationTree::example_verifier</span></span>:<br/><a href="7-dt.html#SP1">&#167;1</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">tree_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="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">N</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">child</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) || (</span><span class="identifier-syntax">N</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="identifier-syntax">N</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">child</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">next</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="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>
<p class="commentary firstcommentary"><a id="SP7" class="paragraph-anchor"></a><b>&#167;7. </b>Passage nodes contain passages of documentation which fall under examples
or headings.
</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">cdoc_passage</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_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#SP2_1_1_1_4_1">&#167;2.1.1.1.4.1</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>
</pre>
<ul class="endnotetexts"><li>The structure cdoc_passage is private to this section.</li></ul>
<p class="commentary firstcommentary"><a id="SP8" class="paragraph-anchor"></a><b>&#167;8. </b>A passage node is essentially a holder for a mixed list of paragraphs and
indented code samples.
</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">DocumentationTree::passage_verifier</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">DocumentationTree::passage_verifier</span></span>:<br/><a href="7-dt.html#SP1">&#167;1</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">tree_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="reserved-syntax">for</span><span class="plain-syntax"> (</span><span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">C</span><span class="plain-syntax"> = </span><span class="identifier-syntax">N</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">child</span><span class="plain-syntax">; </span><span class="identifier-syntax">C</span><span class="plain-syntax">; </span><span class="identifier-syntax">C</span><span class="plain-syntax"> = </span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">next</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">-&gt;</span><span class="element-syntax">type</span><span class="plain-syntax"> != </span><span class="identifier-syntax">paragraph_TNT</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">type</span><span class="plain-syntax"> != </span><span class="identifier-syntax">code_sample_TNT</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="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>
<p class="commentary firstcommentary"><a id="SP9" class="paragraph-anchor"></a><b>&#167;9. </b>A paragraph node holds a body paragraph of text. It has no children.
</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">cdoc_paragraph</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">content</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_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('usagePopup9')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup9">Usage of <span class="code-font"><span class="function-syntax">DocumentationTree::new_paragraph</span></span>:<br/>Documentation Compiler - <a href="7-dc.html#SP2_1_1_1_4">&#167;2.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">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>
<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">paragraph_TNT</span><span class="plain-syntax">, </span><span class="identifier-syntax">STORE_POINTER_cdoc_paragraph</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">int</span><span class="plain-syntax"> </span><span class="function-syntax">DocumentationTree::paragraph_verifier</span><button class="popup" onclick="togglePopup('usagePopup10')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup10">Usage of <span class="code-font"><span class="function-syntax">DocumentationTree::paragraph_verifier</span></span>:<br/><a href="7-dt.html#SP1">&#167;1</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">tree_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="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">N</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">child</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="comment-syntax"> This must be a leaf node</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>
<ul class="endnotetexts"><li>The structure cdoc_paragraph is accessed in 7/dc, 7/dr and here.</li></ul>
<p class="commentary firstcommentary"><a id="SP10" class="paragraph-anchor"></a><b>&#167;10. </b>A code sample node holds a single code sample.
</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">cdoc_code_sample</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">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">with_paste_marker</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('usagePopup11')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup11">Usage of <span class="code-font"><span class="function-syntax">DocumentationTree::new_code_sample</span></span>:<br/>Documentation Compiler - <a href="7-dc.html#SP2_1_1_1_8">&#167;2.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="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="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>
<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">code_sample_TNT</span><span class="plain-syntax">, </span><span class="identifier-syntax">STORE_POINTER_cdoc_code_sample</span><span class="plain-syntax">(</span><span class="identifier-syntax">C</span><span class="plain-syntax">));</span>
<span class="plain-syntax">}</span>
</pre>
<ul class="endnotetexts"><li>The structure cdoc_code_sample is accessed in 7/dr and here.</li></ul>
<p class="commentary firstcommentary"><a id="SP11" class="paragraph-anchor"></a><b>&#167;11. </b>A code sample's children form a list of code lines.
</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">DocumentationTree::code_sample_verifier</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">DocumentationTree::code_sample_verifier</span></span>:<br/><a href="7-dt.html#SP1">&#167;1</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">tree_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="reserved-syntax">for</span><span class="plain-syntax"> (</span><span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">C</span><span class="plain-syntax"> = </span><span class="identifier-syntax">N</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">child</span><span class="plain-syntax">; </span><span class="identifier-syntax">C</span><span class="plain-syntax">; </span><span class="identifier-syntax">C</span><span class="plain-syntax"> = </span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">next</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">-&gt;</span><span class="element-syntax">type</span><span class="plain-syntax"> != </span><span class="identifier-syntax">code_line_TNT</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="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">N</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">child</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><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP12" class="paragraph-anchor"></a><b>&#167;12. </b>A code line node holds a single line of code, and has no children. The
indentation is relative to the start of the code sample, so usually starts
at 0, and is measured in tab stops.
</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">cdoc_code_line</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">content</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">indentation</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">tabular</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_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('usagePopup13')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup13">Usage of <span class="code-font"><span class="function-syntax">DocumentationTree::new_code_line</span></span>:<br/>Documentation Compiler - <a href="7-dc.html#SP2_1_1_1_10">&#167;2.1.1.1.10</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>
<span class="plain-syntax"> </span><span class="identifier-syntax">C</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">indentation</span><span class="plain-syntax"> = </span><span class="identifier-syntax">indentation</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">tabular</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">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">code_line_TNT</span><span class="plain-syntax">, </span><span class="identifier-syntax">STORE_POINTER_cdoc_code_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="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">DocumentationTree::code_line_verifier</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">DocumentationTree::code_line_verifier</span></span>:<br/><a href="7-dt.html#SP1">&#167;1</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">tree_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="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">N</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">child</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="comment-syntax"> This must be a leaf node</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>
<ul class="endnotetexts"><li>The structure cdoc_code_line is accessed in 6/hdn, 7/dc, 7/dr and here.</li></ul>
<p class="commentary firstcommentary"><a id="SP13" class="paragraph-anchor"></a><b>&#167;13. </b>This utility function returns the <span class="extract"><span class="extract-syntax">eg</span></span>th example node, if it exists, and <span class="extract"><span class="extract-syntax">NULL</span></span>
if not.
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">tree_node</span><span class="plain-syntax"> *</span><span class="function-syntax">DocumentationTree::find_example</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::find_example</span></span>:<br/>Documentation Renderer - <a href="7-dr.html#SP8">&#167;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">T</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">eg</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">eg</span><span class="plain-syntax"> &lt; </span><span class="constant-syntax">1</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="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">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#SP13" 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_chapter</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">DocumentationTree::find_chapter</span></span>:<br/>Documentation Renderer - <a href="7-dr.html#SP8">&#167;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">T</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">ch</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">ch</span><span class="plain-syntax"> &lt; </span><span class="constant-syntax">1</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">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">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#SP13" 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="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">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>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">DocumentationTree::find_visit</span><span class="plain-syntax">(</span><span class="identifier-syntax">tree_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="identifier-syntax">state</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</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">dc_find_example_task</span><span class="plain-syntax"> *</span><span class="identifier-syntax">task</span><span class="plain-syntax"> = (</span><span class="reserved-syntax">dc_find_example_task</span><span class="plain-syntax"> *) </span><span class="identifier-syntax">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">task</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">result</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">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_example</span><span class="plain-syntax"> &gt; </span><span class="constant-syntax">0</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">example_TNT</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">RETRIEVE_POINTER_cdoc_example</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="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">number</span><span class="plain-syntax"> == </span><span class="identifier-syntax">task</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">to_find_example</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">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_heading</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="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">1</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">Str::eq</span><span class="plain-syntax">(</span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">count</span><span class="plain-syntax">, </span><span class="identifier-syntax">task</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">to_find_heading</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>
<ul class="endnotetexts"><li>The structure dc_find_example_task is private to this section.</li></ul>
<nav role="progress"><div class="progresscontainer">
<ul class="progressbar"><li class="progressprev"><a href="7-ti.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="progresssection"><a href="7-tm.html">tm</a></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="progresscurrent">dt</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-dc.html">&#10095;</a></li></ul></div>
</nav><!--End of weave-->
</main>
</body>
</html>
Reference in a new issue View git blame Copy permalink