ifhub/inform7
1
0
Fork 0
mirror of https://github.com/ganelson/inform.git synced 2024-07-08 18:14:21 +03:00
Code Issues Projects Releases Wiki Activity
inform7/docs/indoc/2-exm.html
Graham Nelson 6e1fb88642 Improved syntax-colouring of weave
2020-04-07 23:02:44 +01:00

803 lines
97 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>2/ss</title>
<meta name="viewport" content="width=device-width initial-scale=1">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="Content-Language" content="en-gb">
<link href="../inweb.css" rel="stylesheet" rev="stylesheet" type="text/css">
</head>
<body>
<nav role="navigation">
<h1><a href="../webs.html">Sources</a></h1>
<ul>
<li><a href="../compiler.html">compiler tools</a></li>
<li><a href="../other.html"><b>other tools</b></a></li>
<li><a href="../extensions.html">extensions and kits</a></li>
<li><a href="../units.html">unit test tools</a></li>
</ul>
<h2>Other Tools</h2>
<ul>
<li><a href="../inblorb/index.html">inblorb</a></li>
<li><a href="../indoc/index.html">indoc</a></li>
<li><a href="../inpolicy/index.html">inpolicy</a></li>
<li><a href="../inrtps/index.html">inrtps</a></li>
</ul>
<h2>Foundation</h2>
<ul>
<li><a href="../../../inweb/docs/foundation-module/index.html">foundation</a></li>
</ul>
</nav>
<main role="main">
<!--Weave of '2/exm' generated by 7-->
<ul class="crumbs"><li><a href="../webs.html">Source</a></li><li><a href="../other.html">Other Tools</a></li><li><a href="index.html">indoc</a></li><li><a href="index.html#2">Chapter 2: Processing</a></li><li><b>Examples</b></li></ul><p class="purpose">Keeping track of the metadata on and sequencing of the examples.</p>
<ul class="toc"><li><a href="#SP1">&#167;1. Definitions</a></li><li><a href="#SP5">&#167;5. Example scanning</a></li><li><a href="#SP8">&#167;8. Rendering example cues</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. Definitions. </b></p>
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>Examples are created in no particular order, and their allocation numbers
do not necessarily correspond to the numbering displayed in the final
documentation produced. We'll occasionally refer to ENO, or "example
numbering order", for this internal ordering.
</p>
<p class="inwebparagraph">Since a single example can appear in multiple volumes, in different places in
each, we must record where it occurs in each one. In some forms of output,
examples aren't given in full until several sections after the one they belong
to (for example, to hold them back to the end of the current chapter, or even
the current volume), so we also need to remember where it will actually go.
</p>
<pre class="display">
<span class="reserved">typedef</span><span class="plain"> </span><span class="reserved">struct</span><span class="plain"> </span><span class="reserved">example</span><span class="plain"> {</span>
<span class="reserved">struct</span><span class="plain"> </span><span class="reserved">filename</span><span class="plain"> *</span><span class="identifier">ex_filename</span><span class="plain">;</span>
<span class="reserved">struct</span><span class="plain"> </span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">ex_outline</span><span class="plain">;</span>
<span class="reserved">struct</span><span class="plain"> </span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">ex_public_name</span><span class="plain">;</span>
<span class="reserved">struct</span><span class="plain"> </span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">ex_rubric</span><span class="plain">;</span>
<span class="reserved">struct</span><span class="plain"> </span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">ex_rubric_pared_down</span><span class="plain">;</span>
<span class="reserved">struct</span><span class="plain"> </span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">ex_stars</span><span class="plain">;</span>
<span class="reserved">struct</span><span class="plain"> </span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">ex_sort_key</span><span class="plain">;</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">ex_star_count</span><span class="plain">;</span>
<span class="reserved">struct</span><span class="plain"> </span><span class="reserved">section</span><span class="plain"> *</span><span class="identifier">example_belongs_to_section</span><span class="plain">[</span><span class="constant">MAX_VOLUMES</span><span class="plain">]; </span><span class="comment">e.g., an example might belong to section 7</span>
<span class="reserved">struct</span><span class="plain"> </span><span class="reserved">section</span><span class="plain"> *</span><span class="identifier">example_displayed_at_section</span><span class="plain">[</span><span class="constant">MAX_VOLUMES</span><span class="plain">]; </span><span class="comment">but be held back and appear at end of section 23</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">example_position</span><span class="plain">[</span><span class="constant">MAX_VOLUMES</span><span class="plain">]; </span><span class="comment">sequence, counting from 0</span>
<span class="constant">MEMORY_MANAGEMENT</span>
<span class="plain">} </span><span class="reserved">example</span><span class="plain">;</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The structure example is accessed in 2/rnd, 2/rr, 3/cai, 3/ei, 4/cr and here.</p>
<p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>Examples are referenced both by a flat array (in ENO order) and in a hash
of their names:
</p>
<pre class="definitions">
<span class="definitionkeyword">define</span> <span class="constant">MAX_EXAMPLES</span><span class="plain"> </span><span class="constant">1000</span>
</pre>
<pre class="display">
<span class="reserved">example</span><span class="plain"> *</span><span class="identifier">examples</span><span class="plain">[</span><span class="constant">MAX_EXAMPLES</span><span class="plain">];</span>
<span class="reserved">dictionary</span><span class="plain"> *</span><span class="identifier">examples_by_name</span><span class="plain"> = </span><span class="identifier">NULL</span><span class="plain">;</span>
</pre>
<p class="inwebparagraph"></p>
<p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b>These are used temporarily during recipe book construction.
</p>
<pre class="display">
<span class="reserved">dictionary</span><span class="plain"> *</span><span class="identifier">recipe_location</span><span class="plain"> = </span><span class="identifier">NULL</span><span class="plain">;</span>
<span class="reserved">dictionary</span><span class="plain"> *</span><span class="identifier">recipe_sort_prefix</span><span class="plain"> = </span><span class="identifier">NULL</span><span class="plain">;</span>
<span class="reserved">dictionary</span><span class="plain"> *</span><span class="identifier">recipe_subheading_of</span><span class="plain"> = </span><span class="identifier">NULL</span><span class="plain">;</span>
<span class="reserved">dictionary</span><span class="plain"> *</span><span class="identifier">recipe_translates_as</span><span class="plain"> = </span><span class="identifier">NULL</span><span class="plain">;</span>
</pre>
<p class="inwebparagraph"></p>
<p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. Example scanning. </b>Each Example has its own file, which consists of a three-line header, and
then some rawtext. The following scanner goes through a whole directory
to look for example files, and then scans their headers, ignoring the text
below for the time being. A sample:
</p>
<pre class="display">
<span class="plain">*** Plural assertions</span>
<span class="plain">(Clothing kinds; Get Me to the Church on Time)</span>
<span class="plain">Using kinds of clothing to prevent the player from wearing several...</span>
</pre>
<p class="inwebparagraph">Note that the title of the work appears after the semicolon on line 2.
</p>
<p class="inwebparagraph">An exception to this is the <code class="display"><span class="extract">(Recipes).txt</span></code> file, which is not an example,
but is instead a layout plan for how examples appear in volume 1 of the
Inform documentation.
</p>
<pre class="display">
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Examples::scan_examples</span><span class="plain">(</span><span class="reserved">void</span><span class="plain">) {</span>
<span class="reserved">scan_directory</span><span class="plain"> *</span><span class="identifier">dir</span><span class="plain"> = </span><span class="functiontext">Directories::open</span><span class="plain">(</span><span class="identifier">indoc_settings</span><span class="plain">-&gt;</span><span class="element">examples_directory</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">dir</span><span class="plain"> == </span><span class="identifier">NULL</span><span class="plain">) </span><span class="functiontext">Errors::fatal</span><span class="plain">(</span><span class="string">"can't open examples directory"</span><span class="plain">);</span>
<span class="identifier">TEMPORARY_TEXT</span><span class="plain">(</span><span class="identifier">leafname</span><span class="plain">);</span>
<span class="reserved">while</span><span class="plain"> (</span><span class="functiontext">Directories::next</span><span class="plain">(</span><span class="identifier">dir</span><span class="plain">, </span><span class="identifier">leafname</span><span class="plain">)) {</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Str::get_last_char</span><span class="plain">(</span><span class="identifier">leafname</span><span class="plain">) == </span><span class="constant">FOLDER_SEPARATOR</span><span class="plain">) </span><span class="reserved">continue</span><span class="plain">;</span>
<span class="reserved">filename</span><span class="plain"> *</span><span class="identifier">exloc</span><span class="plain"> = </span><span class="functiontext">Filenames::in_folder</span><span class="plain">(</span><span class="identifier">indoc_settings</span><span class="plain">-&gt;</span><span class="element">examples_directory</span><span class="plain">, </span><span class="identifier">leafname</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Regexp::match</span><span class="plain">(</span><span class="identifier">NULL</span><span class="plain">, </span><span class="identifier">leafname</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"%(Recipes%)%c*"</span><span class="plain">)) </span>&lt;<span class="cwebmacro">Scan the Recipe Book catalogue</span> <span class="cwebmacronumber">5.2</span>&gt;
<span class="reserved">else</span><span class="plain"> </span>&lt;<span class="cwebmacro">Scan a regular example</span> <span class="cwebmacronumber">5.1</span>&gt;<span class="plain">;</span>
<span class="plain">}</span>
<span class="functiontext">Directories::close</span><span class="plain">(</span><span class="identifier">dir</span><span class="plain">);</span>
&lt;<span class="cwebmacro">Use the Recipe Book catalogue to place examples in the RB</span> <span class="cwebmacronumber">5.3</span>&gt;<span class="plain">;</span>
<span class="reserved">volume</span><span class="plain"> *</span><span class="identifier">V</span><span class="plain">;</span>
<span class="identifier">LOOP_OVER</span><span class="plain">(</span><span class="identifier">V</span><span class="plain">, </span><span class="reserved">volume</span><span class="plain">) {</span>
&lt;<span class="cwebmacro">Work out the sequence of examples within this volume</span> <span class="cwebmacronumber">5.4</span>&gt;<span class="plain">;</span>
&lt;<span class="cwebmacro">Work out where each example is displayed within this volume</span> <span class="cwebmacronumber">5.6</span>&gt;<span class="plain">;</span>
<span class="plain">}</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The function Examples::scan_examples is used in 1/mn (<a href="1-mn.html#SP1_2">&#167;1.2</a>).</p>
<p class="inwebparagraph"><a id="SP5_1"></a><b>&#167;5.1. </b><code class="display">
&lt;<span class="cwebmacrodefn">Scan a regular example</span> <span class="cwebmacronumber">5.1</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="reserved">example</span><span class="plain"> *</span><span class="identifier">E</span><span class="plain"> = </span><span class="identifier">CREATE</span><span class="plain">(</span><span class="reserved">example</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">no_examples</span><span class="plain"> &gt;= </span><span class="constant">MAX_EXAMPLES</span><span class="plain">)</span>
<span class="functiontext">Errors::fatal</span><span class="plain">(</span><span class="string">"too many examples"</span><span class="plain">);</span>
<span class="identifier">examples</span><span class="plain">[</span><span class="identifier">no_examples</span><span class="plain">++] = </span><span class="identifier">E</span><span class="plain">;</span>
<span class="reserved">examples_helper_state</span><span class="plain"> </span><span class="identifier">ehs</span><span class="plain">;</span>
<span class="identifier">ehs</span><span class="plain">.</span><span class="element">E</span><span class="plain"> = </span><span class="identifier">E</span><span class="plain">;</span>
<span class="identifier">ehs</span><span class="plain">.</span><span class="element">ef</span><span class="plain"> = </span><span class="identifier">exloc</span><span class="plain">;</span>
<span class="functiontext">TextFiles::read</span><span class="plain">(</span><span class="identifier">exloc</span><span class="plain">, </span><span class="constant">FALSE</span><span class="plain">, </span><span class="string">"can't read example file"</span><span class="plain">,</span>
<span class="constant">TRUE</span><span class="plain">, </span><span class="functiontext">Examples::examples_helper</span><span class="plain">, </span><span class="identifier">NULL</span><span class="plain">, &amp;</span><span class="identifier">ehs</span><span class="plain">);</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP5">&#167;5</a>.</p>
<p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b></p>
<pre class="display">
<span class="reserved">typedef</span><span class="plain"> </span><span class="reserved">struct</span><span class="plain"> </span><span class="reserved">examples_helper_state</span><span class="plain"> {</span>
<span class="reserved">struct</span><span class="plain"> </span><span class="reserved">example</span><span class="plain"> *</span><span class="identifier">E</span><span class="plain">;</span>
<span class="reserved">struct</span><span class="plain"> </span><span class="reserved">filename</span><span class="plain"> *</span><span class="identifier">ef</span><span class="plain">;</span>
<span class="plain">} </span><span class="reserved">examples_helper_state</span><span class="plain">;</span>
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Examples::examples_helper</span><span class="plain">(</span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">line</span><span class="plain">, </span><span class="reserved">text_file_position</span><span class="plain"> *</span><span class="identifier">tfp</span><span class="plain">, </span><span class="reserved">void</span><span class="plain"> *</span><span class="identifier">v_ehs</span><span class="plain">) {</span>
<span class="reserved">examples_helper_state</span><span class="plain"> *</span><span class="identifier">ehs</span><span class="plain"> = (</span><span class="reserved">examples_helper_state</span><span class="plain"> *) </span><span class="identifier">v_ehs</span><span class="plain">;</span>
<span class="reserved">example</span><span class="plain"> *</span><span class="identifier">E</span><span class="plain"> = </span><span class="identifier">ehs</span><span class="plain">-&gt;</span><span class="element">E</span><span class="plain">;</span>
<span class="functiontext">Str::trim_white_space_at_end</span><span class="plain">(</span><span class="identifier">line</span><span class="plain">);</span>
<span class="reserved">match_results</span><span class="plain"> </span><span class="identifier">mr</span><span class="plain"> = </span><span class="functiontext">Regexp::create_mr</span><span class="plain">();</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">tfp</span><span class="plain">-&gt;</span><span class="element">line_count</span><span class="plain"> == </span><span class="constant">1</span><span class="plain">) </span>&lt;<span class="cwebmacro">Scan line 1 of the example header</span> <span class="cwebmacronumber">6.1</span>&gt;<span class="plain">;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">tfp</span><span class="plain">-&gt;</span><span class="element">line_count</span><span class="plain"> == </span><span class="constant">2</span><span class="plain">) </span>&lt;<span class="cwebmacro">Scan line 2 of the example header</span> <span class="cwebmacronumber">6.2</span>&gt;<span class="plain">;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">tfp</span><span class="plain">-&gt;</span><span class="element">line_count</span><span class="plain"> == </span><span class="constant">3</span><span class="plain">) </span>&lt;<span class="cwebmacro">Scan line 3 of the example header</span> <span class="cwebmacronumber">6.3</span>&gt;<span class="plain">;</span>
<span class="functiontext">Regexp::dispose_of</span><span class="plain">(&amp;</span><span class="identifier">mr</span><span class="plain">);</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The function Examples::examples_helper is used in <a href="#SP5_1">&#167;5.1</a>.</p>
<p class="endnote">The structure examples_helper_state is accessed in 2/rr and here.</p>
<p class="inwebparagraph"><a id="SP6_1"></a><b>&#167;6.1. </b><code class="display">
&lt;<span class="cwebmacrodefn">Scan line 1 of the example header</span> <span class="cwebmacronumber">6.1</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Regexp::match</span><span class="plain">(&amp;</span><span class="identifier">mr</span><span class="plain">, </span><span class="identifier">line</span><span class="plain">, </span><span class="identifier">L</span><span class="string">" *(%*+) (%c*)"</span><span class="plain">)) {</span>
<span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">asterisk_text</span><span class="plain"> = </span><span class="identifier">mr</span><span class="plain">.</span><span class="element">exp</span><span class="plain">[0];</span>
<span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">sname</span><span class="plain"> = </span><span class="identifier">mr</span><span class="plain">.</span><span class="element">exp</span><span class="plain">[1];</span>
<span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">ex_stars</span><span class="plain"> = </span><span class="functiontext">Str::duplicate</span><span class="plain">(</span><span class="identifier">asterisk_text</span><span class="plain">);</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">starc</span><span class="plain"> = </span><span class="constant">0</span><span class="plain">;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Str::eq_wide_string</span><span class="plain">(</span><span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">ex_stars</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"*"</span><span class="plain">)) </span><span class="identifier">starc</span><span class="plain">=1;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Str::eq_wide_string</span><span class="plain">(</span><span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">ex_stars</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"**"</span><span class="plain">)) </span><span class="identifier">starc</span><span class="plain">=2;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Str::eq_wide_string</span><span class="plain">(</span><span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">ex_stars</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"***"</span><span class="plain">)) </span><span class="identifier">starc</span><span class="plain">=3;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Str::eq_wide_string</span><span class="plain">(</span><span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">ex_stars</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"****"</span><span class="plain">)) </span><span class="identifier">starc</span><span class="plain">=4;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">starc</span><span class="plain"> == </span><span class="constant">0</span><span class="plain">) {</span>
<span class="functiontext">Errors::in_text_file</span><span class="plain">(</span><span class="string">"star count for example must be * to ****"</span><span class="plain">, </span><span class="identifier">tfp</span><span class="plain">);</span>
<span class="identifier">starc</span><span class="plain"> = </span><span class="constant">1</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">ex_star_count</span><span class="plain"> = </span><span class="identifier">starc</span><span class="plain">;</span>
<span class="reserved">section</span><span class="plain"> *</span><span class="identifier">S</span><span class="plain"> = </span><span class="functiontext">Dictionaries::read_value</span><span class="plain">(</span><span class="identifier">volumes</span><span class="plain">[0]-&gt;</span><span class="element">sections_by_name</span><span class="plain">, </span><span class="identifier">sname</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">S</span><span class="plain">) </span><span class="identifier">E</span><span class="plain">-&gt;</span><span class="identifier">example_belongs_to_section</span><span class="plain">[0] = </span><span class="identifier">S</span><span class="plain">;</span>
<span class="reserved">else</span><span class="plain"> {</span>
<span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">example_belongs_to_section</span><span class="plain">[0] = </span><span class="identifier">NULL</span><span class="plain">;</span>
<span class="functiontext">Errors::in_text_file</span><span class="plain">(</span><span class="string">"example belongs to an unknown section"</span><span class="plain">, </span><span class="identifier">tfp</span><span class="plain">);</span>
<span class="plain">}</span>
<span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">ex_filename</span><span class="plain"> = </span><span class="identifier">ehs</span><span class="plain">-&gt;</span><span class="element">ef</span><span class="plain">;</span>
<span class="plain">} </span><span class="reserved">else</span><span class="plain"> {</span>
<span class="functiontext">Errors::in_text_file</span><span class="plain">(</span><span class="string">"example has a malformed first line"</span><span class="plain">, </span><span class="identifier">tfp</span><span class="plain">);</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP6">&#167;6</a>.</p>
<p class="inwebparagraph"><a id="SP6_2"></a><b>&#167;6.2. </b><code class="display">
&lt;<span class="cwebmacrodefn">Scan line 2 of the example header</span> <span class="cwebmacronumber">6.2</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Regexp::match</span><span class="plain">(&amp;</span><span class="identifier">mr</span><span class="plain">, </span><span class="identifier">line</span><span class="plain">, </span><span class="identifier">L</span><span class="string">" *%((%c*?)%)"</span><span class="plain">)) {</span>
<span class="reserved">match_results</span><span class="plain"> </span><span class="identifier">mr2</span><span class="plain"> = </span><span class="functiontext">Regexp::create_mr</span><span class="plain">();</span>
<span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">ex_rubric</span><span class="plain"> = </span><span class="functiontext">Str::duplicate</span><span class="plain">(</span><span class="identifier">mr</span><span class="plain">.</span><span class="identifier">exp</span><span class="plain">[0]);</span>
<span class="identifier">TEMPORARY_TEXT</span><span class="plain">(</span><span class="identifier">rb</span><span class="plain">);</span>
<span class="functiontext">Str::copy</span><span class="plain">(</span><span class="identifier">rb</span><span class="plain">, </span><span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">ex_rubric</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Regexp::match</span><span class="plain">(&amp;</span><span class="identifier">mr2</span><span class="plain">, </span><span class="identifier">rb</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"(%c*?) *-- *(%c*)"</span><span class="plain">)) </span><span class="functiontext">Str::copy</span><span class="plain">(</span><span class="identifier">rb</span><span class="plain">, </span><span class="identifier">mr2</span><span class="plain">.</span><span class="element">exp</span><span class="plain">[1]);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Regexp::match</span><span class="plain">(&amp;</span><span class="identifier">mr2</span><span class="plain">, </span><span class="identifier">rb</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"(%c*); *(%c*?)"</span><span class="plain">)) </span><span class="functiontext">Str::copy</span><span class="plain">(</span><span class="identifier">rb</span><span class="plain">, </span><span class="identifier">mr2</span><span class="plain">.</span><span class="element">exp</span><span class="plain">[0]);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Regexp::match</span><span class="plain">(&amp;</span><span class="identifier">mr2</span><span class="plain">, </span><span class="identifier">rb</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"(%c*?): *(%c*?)"</span><span class="plain">)) </span><span class="functiontext">Str::copy</span><span class="plain">(</span><span class="identifier">rb</span><span class="plain">, </span><span class="identifier">mr2</span><span class="plain">.</span><span class="element">exp</span><span class="plain">[1]);</span>
<span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">ex_rubric_pared_down</span><span class="plain"> = </span><span class="functiontext">Str::duplicate</span><span class="plain">(</span><span class="identifier">rb</span><span class="plain">);</span>
<span class="identifier">DISCARD_TEXT</span><span class="plain">(</span><span class="identifier">rb</span><span class="plain">);</span>
<span class="identifier">TEMPORARY_TEXT</span><span class="plain">(</span><span class="identifier">name</span><span class="plain">);</span>
<span class="functiontext">Str::copy</span><span class="plain">(</span><span class="identifier">name</span><span class="plain">, </span><span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">ex_rubric</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Regexp::match</span><span class="plain">(&amp;</span><span class="identifier">mr2</span><span class="plain">, </span><span class="identifier">name</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"%c*;(%c*?)"</span><span class="plain">)) </span><span class="functiontext">Str::copy</span><span class="plain">(</span><span class="identifier">name</span><span class="plain">, </span><span class="identifier">mr2</span><span class="plain">.</span><span class="element">exp</span><span class="plain">[0]);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Regexp::match</span><span class="plain">(&amp;</span><span class="identifier">mr2</span><span class="plain">, </span><span class="identifier">name</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"(%c*?): (%d+). %c*"</span><span class="plain">)) {</span>
<span class="functiontext">Str::clear</span><span class="plain">(</span><span class="identifier">name</span><span class="plain">);</span>
<span class="identifier">WRITE_TO</span><span class="plain">(</span><span class="identifier">name</span><span class="plain">, </span><span class="string">"%S %S"</span><span class="plain">, </span><span class="identifier">mr2</span><span class="plain">.</span><span class="element">exp</span><span class="plain">[0], </span><span class="identifier">mr2</span><span class="plain">.</span><span class="element">exp</span><span class="plain">[1]);</span>
<span class="plain">}</span>
<span class="functiontext">Str::trim_white_space</span><span class="plain">(</span><span class="identifier">name</span><span class="plain">);</span>
<span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">ex_public_name</span><span class="plain"> = </span><span class="functiontext">Str::duplicate</span><span class="plain">(</span><span class="identifier">name</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">examples_by_name</span><span class="plain"> == </span><span class="identifier">NULL</span><span class="plain">) </span><span class="identifier">examples_by_name</span><span class="plain"> = </span><span class="functiontext">Dictionaries::new</span><span class="plain">(100, </span><span class="constant">FALSE</span><span class="plain">);</span>
<span class="functiontext">Dictionaries::create</span><span class="plain">(</span><span class="identifier">examples_by_name</span><span class="plain">, </span><span class="identifier">name</span><span class="plain">);</span>
<span class="functiontext">Dictionaries::write_value</span><span class="plain">(</span><span class="identifier">examples_by_name</span><span class="plain">, </span><span class="identifier">name</span><span class="plain">, </span><span class="identifier">E</span><span class="plain">);</span>
<span class="identifier">DISCARD_TEXT</span><span class="plain">(</span><span class="identifier">name</span><span class="plain">);</span>
<span class="functiontext">Regexp::dispose_of</span><span class="plain">(&amp;</span><span class="identifier">mr2</span><span class="plain">);</span>
<span class="plain">} </span><span class="reserved">else</span><span class="plain"> {</span>
<span class="functiontext">Errors::in_text_file</span><span class="plain">(</span><span class="string">"example has a malformed second line"</span><span class="plain">, </span><span class="identifier">tfp</span><span class="plain">);</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP6">&#167;6</a>.</p>
<p class="inwebparagraph"><a id="SP6_3"></a><b>&#167;6.3. </b><code class="display">
&lt;<span class="cwebmacrodefn">Scan line 3 of the example header</span> <span class="cwebmacronumber">6.3</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">ex_outline</span><span class="plain"> = </span><span class="functiontext">Str::duplicate</span><span class="plain">(</span><span class="identifier">line</span><span class="plain">);</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP6">&#167;6</a>.</p>
<p class="inwebparagraph"><a id="SP5_2"></a><b>&#167;5.2. </b>The RB catalogue has a rather arcane format: see the file itself to be
</p>
<ul class="items"><li>(slightly) enlightened.
</li></ul>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Scan the Recipe Book catalogue</span> <span class="cwebmacronumber">5.2</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="reserved">examples_rb_helper_state</span><span class="plain"> </span><span class="identifier">erbhs</span><span class="plain">;</span>
<span class="identifier">erbhs</span><span class="plain">.</span><span class="element">current_rch</span><span class="plain"> = </span><span class="functiontext">Str::new</span><span class="plain">();</span>
<span class="identifier">erbhs</span><span class="plain">.</span><span class="element">current_rcsh</span><span class="plain"> = </span><span class="functiontext">Str::new</span><span class="plain">();</span>
<span class="identifier">erbhs</span><span class="plain">.</span><span class="element">no_recipe_headings</span><span class="plain"> = </span><span class="constant">0</span><span class="plain">;</span>
<span class="identifier">erbhs</span><span class="plain">.</span><span class="element">no_recipe_subheadings</span><span class="plain"> = </span><span class="constant">0</span><span class="plain">;</span>
<span class="functiontext">TextFiles::read</span><span class="plain">(</span><span class="identifier">exloc</span><span class="plain">, </span><span class="constant">FALSE</span><span class="plain">, </span><span class="string">"can't read Recipe Book catalogue file"</span><span class="plain">,</span>
<span class="constant">TRUE</span><span class="plain">, </span><span class="functiontext">Examples::examples_rb_helper</span><span class="plain">, </span><span class="identifier">NULL</span><span class="plain">, &amp;</span><span class="identifier">erbhs</span><span class="plain">);</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP5">&#167;5</a>.</p>
<p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. </b></p>
<pre class="display">
<span class="reserved">typedef</span><span class="plain"> </span><span class="reserved">struct</span><span class="plain"> </span><span class="reserved">examples_rb_helper_state</span><span class="plain"> {</span>
<span class="reserved">struct</span><span class="plain"> </span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">current_rch</span><span class="plain">;</span>
<span class="reserved">struct</span><span class="plain"> </span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">current_rcsh</span><span class="plain">;</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">no_recipe_headings</span><span class="plain">;</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">no_recipe_subheadings</span><span class="plain">;</span>
<span class="plain">} </span><span class="reserved">examples_rb_helper_state</span><span class="plain">;</span>
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Examples::examples_rb_helper</span><span class="plain">(</span><span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">line</span><span class="plain">, </span><span class="reserved">text_file_position</span><span class="plain"> *</span><span class="identifier">tfp</span><span class="plain">, </span><span class="reserved">void</span><span class="plain"> *</span><span class="identifier">v_erbhs</span><span class="plain">) {</span>
<span class="reserved">examples_rb_helper_state</span><span class="plain"> *</span><span class="identifier">erbhs</span><span class="plain"> = (</span><span class="reserved">examples_rb_helper_state</span><span class="plain"> *) </span><span class="identifier">v_erbhs</span><span class="plain">;</span>
<span class="functiontext">Str::trim_white_space</span><span class="plain">(</span><span class="identifier">line</span><span class="plain">);</span>
<span class="reserved">match_results</span><span class="plain"> </span><span class="identifier">mr</span><span class="plain"> = </span><span class="functiontext">Regexp::create_mr</span><span class="plain">();</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Regexp::match</span><span class="plain">(&amp;</span><span class="identifier">mr</span><span class="plain">, </span><span class="identifier">line</span><span class="plain">, </span><span class="identifier">L</span><span class="string">" *(%c*?) *== *(%c*?)"</span><span class="plain">)) </span>&lt;<span class="cwebmacro">Scan a translation line</span> <span class="cwebmacronumber">7.1</span>&gt;
<span class="reserved">else</span><span class="plain"> </span><span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Regexp::match</span><span class="plain">(&amp;</span><span class="identifier">mr</span><span class="plain">, </span><span class="identifier">line</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"&gt;(%c*)"</span><span class="plain">)) </span>&lt;<span class="cwebmacro">Scan a major heading</span> <span class="cwebmacronumber">7.2</span>&gt;
<span class="reserved">else</span><span class="plain"> </span><span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Regexp::match</span><span class="plain">(&amp;</span><span class="identifier">mr</span><span class="plain">, </span><span class="identifier">line</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"%*(%c*)"</span><span class="plain">)) </span>&lt;<span class="cwebmacro">Scan a minor heading</span> <span class="cwebmacronumber">7.3</span>&gt;
<span class="reserved">else</span><span class="plain"> </span><span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Str::len</span><span class="plain">(</span><span class="identifier">line</span><span class="plain">) &gt; </span><span class="constant">0</span><span class="plain">) </span>&lt;<span class="cwebmacro">Scan an example name</span> <span class="cwebmacronumber">7.4</span>&gt;<span class="plain">;</span>
<span class="functiontext">Regexp::dispose_of</span><span class="plain">(&amp;</span><span class="identifier">mr</span><span class="plain">);</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The function Examples::examples_rb_helper is used in <a href="#SP5_2">&#167;5.2</a>.</p>
<p class="endnote">The structure examples_rb_helper_state is private to this section.</p>
<p class="inwebparagraph"><a id="SP7_1"></a><b>&#167;7.1. </b><code class="display">
&lt;<span class="cwebmacrodefn">Scan a translation line</span> <span class="cwebmacronumber">7.1</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">recipe_translates_as</span><span class="plain"> == </span><span class="identifier">NULL</span><span class="plain">) </span><span class="identifier">recipe_translates_as</span><span class="plain"> = </span><span class="functiontext">Dictionaries::new</span><span class="plain">(100, </span><span class="constant">TRUE</span><span class="plain">);</span>
<span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">trans</span><span class="plain"> = </span><span class="functiontext">Dictionaries::create_text</span><span class="plain">(</span><span class="identifier">recipe_translates_as</span><span class="plain">, </span><span class="identifier">mr</span><span class="plain">.</span><span class="element">exp</span><span class="plain">[0]);</span>
<span class="functiontext">Str::copy</span><span class="plain">(</span><span class="identifier">trans</span><span class="plain">, </span><span class="identifier">mr</span><span class="plain">.</span><span class="element">exp</span><span class="plain">[1]);</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP7">&#167;7</a>.</p>
<p class="inwebparagraph"><a id="SP7_2"></a><b>&#167;7.2. </b><code class="display">
&lt;<span class="cwebmacrodefn">Scan a major heading</span> <span class="cwebmacronumber">7.2</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="functiontext">Str::copy</span><span class="plain">(</span><span class="identifier">erbhs</span><span class="plain">-&gt;</span><span class="element">current_rch</span><span class="plain">, </span><span class="identifier">mr</span><span class="plain">.</span><span class="identifier">exp</span><span class="plain">[0]);</span>
<span class="identifier">erbhs</span><span class="plain">-&gt;</span><span class="element">no_recipe_headings</span><span class="plain">++;</span>
<span class="functiontext">Str::clear</span><span class="plain">(</span><span class="identifier">erbhs</span><span class="plain">-&gt;</span><span class="element">current_rcsh</span><span class="plain">);</span>
<span class="identifier">erbhs</span><span class="plain">-&gt;</span><span class="element">no_recipe_subheadings</span><span class="plain"> = </span><span class="constant">0</span><span class="plain">;</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP7">&#167;7</a>.</p>
<p class="inwebparagraph"><a id="SP7_3"></a><b>&#167;7.3. </b><code class="display">
&lt;<span class="cwebmacrodefn">Scan a minor heading</span> <span class="cwebmacronumber">7.3</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="functiontext">Str::copy</span><span class="plain">(</span><span class="identifier">erbhs</span><span class="plain">-&gt;</span><span class="element">current_rcsh</span><span class="plain">, </span><span class="identifier">mr</span><span class="plain">.</span><span class="element">exp</span><span class="plain">[0]);</span>
<span class="identifier">erbhs</span><span class="plain">-&gt;</span><span class="element">no_recipe_subheadings</span><span class="plain">++;</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP7">&#167;7</a>.</p>
<p class="inwebparagraph"><a id="SP7_4"></a><b>&#167;7.4. </b><code class="display">
&lt;<span class="cwebmacrodefn">Scan an example name</span> <span class="cwebmacronumber">7.4</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">recipe_subheading_of</span><span class="plain"> == </span><span class="identifier">NULL</span><span class="plain">) </span><span class="identifier">recipe_subheading_of</span><span class="plain"> = </span><span class="functiontext">Dictionaries::new</span><span class="plain">(100, </span><span class="constant">TRUE</span><span class="plain">);</span>
<span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">rso</span><span class="plain"> = </span><span class="functiontext">Dictionaries::create_text</span><span class="plain">(</span><span class="identifier">recipe_subheading_of</span><span class="plain">, </span><span class="identifier">line</span><span class="plain">);</span>
<span class="functiontext">Str::copy</span><span class="plain">(</span><span class="identifier">rso</span><span class="plain">, </span><span class="identifier">erbhs</span><span class="plain">-&gt;</span><span class="element">current_rcsh</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">recipe_location</span><span class="plain"> == </span><span class="identifier">NULL</span><span class="plain">) </span><span class="identifier">recipe_location</span><span class="plain"> = </span><span class="functiontext">Dictionaries::new</span><span class="plain">(100, </span><span class="constant">TRUE</span><span class="plain">);</span>
<span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">rl</span><span class="plain"> = </span><span class="functiontext">Dictionaries::create_text</span><span class="plain">(</span><span class="identifier">recipe_location</span><span class="plain">, </span><span class="identifier">line</span><span class="plain">);</span>
<span class="functiontext">Str::copy</span><span class="plain">(</span><span class="identifier">rl</span><span class="plain">, </span><span class="identifier">erbhs</span><span class="plain">-&gt;</span><span class="element">current_rcsh</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Str::eq_wide_string</span><span class="plain">(</span><span class="identifier">line</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"About the examples"</span><span class="plain">)) </span><span class="functiontext">Str::copy</span><span class="plain">(</span><span class="identifier">rl</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"PREFACE"</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Str::eq_wide_string</span><span class="plain">(</span><span class="identifier">line</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"Basic room, container, and supporter descriptions"</span><span class="plain">))</span>
<span class="functiontext">Str::copy</span><span class="plain">(</span><span class="identifier">rl</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"PREFACE"</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">recipe_sort_prefix</span><span class="plain"> == </span><span class="identifier">NULL</span><span class="plain">) </span><span class="identifier">recipe_sort_prefix</span><span class="plain"> = </span><span class="functiontext">Dictionaries::new</span><span class="plain">(100, </span><span class="constant">TRUE</span><span class="plain">);</span>
<span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">rsp</span><span class="plain"> = </span><span class="functiontext">Dictionaries::create_text</span><span class="plain">(</span><span class="identifier">recipe_sort_prefix</span><span class="plain">, </span><span class="identifier">line</span><span class="plain">);</span>
<span class="identifier">WRITE_TO</span><span class="plain">(</span><span class="identifier">rsp</span><span class="plain">, </span><span class="string">"%02d_%02d"</span><span class="plain">, </span><span class="identifier">erbhs</span><span class="plain">-&gt;</span><span class="element">no_recipe_headings</span><span class="plain">, </span><span class="identifier">erbhs</span><span class="plain">-&gt;</span><span class="element">no_recipe_subheadings</span><span class="plain">);</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP7">&#167;7</a>.</p>
<p class="inwebparagraph"><a id="SP5_3"></a><b>&#167;5.3. </b><code class="display">
&lt;<span class="cwebmacrodefn">Use the Recipe Book catalogue to place examples in the RB</span> <span class="cwebmacronumber">5.3</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="reserved">volume</span><span class="plain"> *</span><span class="identifier">V</span><span class="plain">;</span>
<span class="identifier">LOOP_OVER</span><span class="plain">(</span><span class="identifier">V</span><span class="plain">, </span><span class="reserved">volume</span><span class="plain">) {</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">V</span><span class="plain">-&gt;</span><span class="element">allocation_id</span><span class="plain"> == </span><span class="constant">0</span><span class="plain">) </span><span class="reserved">continue</span><span class="plain">; </span><span class="comment">placings in WWI are already made</span>
<span class="reserved">example</span><span class="plain"> *</span><span class="identifier">E</span><span class="plain">;</span>
<span class="identifier">LOOP_OVER</span><span class="plain">(</span><span class="identifier">E</span><span class="plain">, </span><span class="reserved">example</span><span class="plain">) {</span>
<span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">to_find</span><span class="plain"> = </span><span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">ex_rubric_pared_down</span><span class="plain">;</span>
<span class="reserved">text_stream</span><span class="plain"> *</span><span class="identifier">sname</span><span class="plain"> = </span><span class="functiontext">Dictionaries::get_text</span><span class="plain">(</span><span class="identifier">recipe_location</span><span class="plain">, </span><span class="identifier">to_find</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">sname</span><span class="plain"> == </span><span class="identifier">NULL</span><span class="plain">) </span><span class="functiontext">Errors::with_text</span><span class="plain">(</span><span class="string">"recipe book lookup failed (1): %S"</span><span class="plain">, </span><span class="identifier">to_find</span><span class="plain">);</span>
<span class="reserved">else</span><span class="plain"> {</span>
<span class="reserved">section</span><span class="plain"> *</span><span class="identifier">S</span><span class="plain"> = (</span><span class="reserved">section</span><span class="plain"> *) </span><span class="functiontext">Dictionaries::read_value</span><span class="plain">(</span><span class="identifier">V</span><span class="plain">-&gt;</span><span class="element">sections_by_name</span><span class="plain">, </span><span class="identifier">sname</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">S</span><span class="plain"> == </span><span class="identifier">NULL</span><span class="plain">) </span><span class="functiontext">Errors::with_text</span><span class="plain">(</span>
<span class="string">"recipe book lookup failed: %S refers to nonexistent section"</span><span class="plain">, </span><span class="identifier">to_find</span><span class="plain">);</span>
<span class="reserved">else</span><span class="plain"> {</span>
<span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">example_belongs_to_section</span><span class="plain">[</span><span class="identifier">V</span><span class="plain">-&gt;</span><span class="identifier">allocation_id</span><span class="plain">] = </span><span class="identifier">S</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="plain">}</span>
<span class="plain">}</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP5">&#167;5</a>.</p>
<p class="inwebparagraph"><a id="SP5_4"></a><b>&#167;5.4. </b>At this point, then, we know which section every example belongs to. But
we still have to put them in order within those sections: we want 1-star
examples first, then 2-star, and so on. The following does that. In the
first volume, examples of equal star rating are in essentially random order,
but in subsequent volumes, they appear in that same order, since this means
their example numbers as shown in the documentation are increasing; which
looks tidy.
</p>
<p class="inwebparagraph">As noted above, <code class="display"><span class="extract">example_sequence</span></code> and <code class="display"><span class="extract">example_position</span></code> are essentially
inverse permutations.
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Work out the sequence of examples within this volume</span> <span class="cwebmacronumber">5.4</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="reserved">example</span><span class="plain"> *</span><span class="identifier">E</span><span class="plain">;</span>
<span class="identifier">LOOP_OVER</span><span class="plain">(</span><span class="identifier">E</span><span class="plain">, </span><span class="reserved">example</span><span class="plain">) {</span>
<span class="identifier">V</span><span class="plain">-&gt;</span><span class="element">examples_sequence</span><span class="plain">[</span><span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">allocation_id</span><span class="plain">] = </span><span class="identifier">E</span><span class="plain">;</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">last_resort</span><span class="plain"> = </span><span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">allocation_id</span><span class="plain">;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">V</span><span class="plain">-&gt;</span><span class="element">allocation_id</span><span class="plain"> &gt; </span><span class="constant">0</span><span class="plain">) </span><span class="identifier">last_resort</span><span class="plain"> = </span><span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">example_position</span><span class="plain">[0];</span>
<span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">ex_sort_key</span><span class="plain"> = </span><span class="functiontext">Str::new</span><span class="plain">();</span>
<span class="identifier">WRITE_TO</span><span class="plain">(</span><span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">ex_sort_key</span><span class="plain">, </span><span class="string">"%08d-%08d-%08d"</span><span class="plain">,</span>
<span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">example_belongs_to_section</span><span class="plain">[</span><span class="identifier">V</span><span class="plain">-&gt;</span><span class="identifier">allocation_id</span><span class="plain">]-&gt;</span><span class="element">allocation_id</span><span class="plain">,</span>
<span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">ex_star_count</span><span class="plain">,</span>
<span class="identifier">last_resort</span><span class="plain">);</span>
<span class="plain">}</span>
<span class="identifier">qsort</span><span class="plain">(</span><span class="identifier">V</span><span class="plain">-&gt;</span><span class="element">examples_sequence</span><span class="plain">, (</span><span class="identifier">size_t</span><span class="plain">) </span><span class="identifier">no_examples</span><span class="plain">, </span><span class="reserved">sizeof</span><span class="plain">(</span><span class="reserved">example</span><span class="plain"> *),</span>
<span class="functiontext">Examples::sort_comparison</span><span class="plain">);</span>
<span class="reserved">for</span><span class="plain"> (</span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">n</span><span class="plain">=0; </span><span class="identifier">n</span><span class="plain">&lt;</span><span class="identifier">no_examples</span><span class="plain">; </span><span class="identifier">n</span><span class="plain">++) {</span>
<span class="reserved">example</span><span class="plain"> *</span><span class="identifier">E</span><span class="plain"> = </span><span class="identifier">V</span><span class="plain">-&gt;</span><span class="element">examples_sequence</span><span class="plain">[</span><span class="identifier">n</span><span class="plain">];</span>
<span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">example_position</span><span class="plain">[</span><span class="identifier">V</span><span class="plain">-&gt;</span><span class="element">allocation_id</span><span class="plain">] = </span><span class="identifier">n</span><span class="plain"> + </span><span class="constant">1</span><span class="plain">; </span><span class="comment">to count from 1 when displayed</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP5">&#167;5</a>.</p>
<p class="inwebparagraph"><a id="SP5_5"></a><b>&#167;5.5. </b></p>
<pre class="display">
<span class="reserved">int</span><span class="plain"> </span><span class="functiontext">Examples::sort_comparison</span><span class="plain">(</span><span class="reserved">const</span><span class="plain"> </span><span class="reserved">void</span><span class="plain"> *</span><span class="identifier">ent1</span><span class="plain">, </span><span class="reserved">const</span><span class="plain"> </span><span class="reserved">void</span><span class="plain"> *</span><span class="identifier">ent2</span><span class="plain">) {</span>
<span class="reserved">const</span><span class="plain"> </span><span class="reserved">example</span><span class="plain"> *</span><span class="identifier">E1</span><span class="plain"> = *((</span><span class="reserved">const</span><span class="plain"> </span><span class="reserved">example</span><span class="plain"> **) </span><span class="identifier">ent1</span><span class="plain">);</span>
<span class="reserved">const</span><span class="plain"> </span><span class="reserved">example</span><span class="plain"> *</span><span class="identifier">E2</span><span class="plain"> = *((</span><span class="reserved">const</span><span class="plain"> </span><span class="reserved">example</span><span class="plain"> **) </span><span class="identifier">ent2</span><span class="plain">);</span>
<span class="reserved">return</span><span class="plain"> </span><span class="functiontext">Str::cmp</span><span class="plain">(</span><span class="identifier">E1</span><span class="plain">-&gt;</span><span class="element">ex_sort_key</span><span class="plain">, </span><span class="identifier">E2</span><span class="plain">-&gt;</span><span class="element">ex_sort_key</span><span class="plain">);</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The function Examples::sort_comparison is used in <a href="#SP5_4">&#167;5.4</a>.</p>
<p class="inwebparagraph"><a id="SP5_6"></a><b>&#167;5.6. </b>In some granularities, examples are held back to the end of the chapter,
or even the end of the volume, to appear. This is where that's worked out.
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Work out where each example is displayed within this volume</span> <span class="cwebmacronumber">5.6</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="reserved">example</span><span class="plain"> *</span><span class="identifier">E</span><span class="plain">;</span>
<span class="identifier">LOOP_OVER</span><span class="plain">(</span><span class="identifier">E</span><span class="plain">, </span><span class="reserved">example</span><span class="plain">) {</span>
<span class="reserved">section</span><span class="plain"> *</span><span class="identifier">S</span><span class="plain"> = </span><span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">example_belongs_to_section</span><span class="plain">[</span><span class="identifier">V</span><span class="plain">-&gt;</span><span class="element">allocation_id</span><span class="plain">];</span>
<span class="reserved">section</span><span class="plain"> *</span><span class="identifier">hang_here</span><span class="plain"> = </span><span class="identifier">NULL</span><span class="plain">;</span>
<span class="reserved">for</span><span class="plain"> (</span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">p</span><span class="plain"> = </span><span class="constant">0</span><span class="plain">; </span><span class="identifier">p</span><span class="plain"> &lt; </span><span class="identifier">V</span><span class="plain">-&gt;</span><span class="element">vol_section_count</span><span class="plain">; </span><span class="identifier">p</span><span class="plain">++) {</span>
<span class="reserved">section</span><span class="plain"> *</span><span class="identifier">HS</span><span class="plain"> = </span><span class="identifier">V</span><span class="plain">-&gt;</span><span class="element">sections</span><span class="plain">[</span><span class="identifier">p</span><span class="plain">];</span>
<span class="reserved">if</span><span class="plain"> (((</span><span class="identifier">indoc_settings</span><span class="plain">-&gt;</span><span class="element">examples_granularity</span><span class="plain"> == </span><span class="constant">SECTION_GRANULARITY</span><span class="plain">) &amp;&amp; (</span><span class="identifier">S</span><span class="plain"> == </span><span class="identifier">HS</span><span class="plain">))</span>
<span class="plain">||</span>
<span class="plain">((</span><span class="identifier">indoc_settings</span><span class="plain">-&gt;</span><span class="element">examples_granularity</span><span class="plain"> == </span><span class="constant">CHAPTER_GRANULARITY</span><span class="plain">) &amp;&amp; (</span><span class="identifier">HS</span><span class="plain">-&gt;</span><span class="element">in_which_chapter</span><span class="plain"> == </span><span class="identifier">S</span><span class="plain">-&gt;</span><span class="element">in_which_chapter</span><span class="plain">))</span>
<span class="plain">||</span>
<span class="plain">(</span><span class="identifier">indoc_settings</span><span class="plain">-&gt;</span><span class="element">examples_granularity</span><span class="plain"> == </span><span class="constant">BOOK_GRANULARITY</span><span class="plain">))</span>
<span class="identifier">hang_here</span><span class="plain"> = </span><span class="identifier">HS</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">hang_here</span><span class="plain">)</span>
<span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">example_displayed_at_section</span><span class="plain">[</span><span class="identifier">V</span><span class="plain">-&gt;</span><span class="element">allocation_id</span><span class="plain">] = </span><span class="identifier">hang_here</span><span class="plain">;</span>
<span class="reserved">else</span>
<span class="functiontext">Errors::fatal</span><span class="plain">(</span><span class="string">"miscalculated example ownership"</span><span class="plain">);</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP5">&#167;5</a>.</p>
<p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. Rendering example cues. </b>An example cue is a rendered chunk describing and naming an example. The text
of the example may or may not follow: if it doesn't, the description is a
link which opens it. Depending on the examples mode, the text of the
example may be either (a) included in the file and always visible, (b) included
but hidden by default until an icon is clicked, or (c) stored in an external,
that is, separate file.
</p>
<pre class="display">
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Examples::render_example_cue</span><span class="plain">(</span><span class="constant">OUTPUT_STREAM</span><span class="plain">, </span><span class="reserved">example</span><span class="plain"> *</span><span class="identifier">E</span><span class="plain">, </span><span class="reserved">volume</span><span class="plain"> *</span><span class="identifier">V</span><span class="plain">, </span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">writing_index</span><span class="plain">) {</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">indoc_settings</span><span class="plain">-&gt;</span><span class="element">format</span><span class="plain"> == </span><span class="constant">PLAIN_FORMAT</span><span class="plain">) </span>&lt;<span class="cwebmacro">Render example cue in plain text</span> <span class="cwebmacronumber">8.1</span>&gt;
<span class="reserved">else</span><span class="plain"> </span><span class="reserved">if</span><span class="plain"> (</span><span class="identifier">indoc_settings</span><span class="plain">-&gt;</span><span class="element">format</span><span class="plain"> == </span><span class="constant">HTML_FORMAT</span><span class="plain">) </span>&lt;<span class="cwebmacro">Render example cue in HTML</span> <span class="cwebmacronumber">8.2</span>&gt;<span class="plain">;</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The function Examples::render_example_cue is used in 2/rnd (<a href="2-rnd.html#SP9_1_2">&#167;9.1.2</a>, <a href="2-rnd.html#SP15">&#167;15</a>), 3/ei (<a href="3-ei.html#SP7">&#167;7</a>).</p>
<p class="inwebparagraph"><a id="SP8_1"></a><b>&#167;8.1. </b><code class="display">
&lt;<span class="cwebmacrodefn">Render example cue in plain text</span> <span class="cwebmacronumber">8.1</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"\nExample %d (%S): %S\n%S\n\n"</span><span class="plain">,</span>
<span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">example_position</span><span class="plain">[</span><span class="identifier">V</span><span class="plain">-&gt;</span><span class="element">allocation_id</span><span class="plain">], </span><span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">ex_stars</span><span class="plain">, </span><span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">ex_public_name</span><span class="plain">, </span><span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">ex_outline</span><span class="plain">);</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP8">&#167;8</a>.</p>
<p class="inwebparagraph"><a id="SP8_2"></a><b>&#167;8.2. </b><code class="display">
&lt;<span class="cwebmacrodefn">Render example cue in HTML</span> <span class="cwebmacronumber">8.2</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">writing_index</span><span class="plain"> == </span><span class="constant">FALSE</span><span class="plain">) {</span>
<span class="identifier">TEMPORARY_TEXT</span><span class="plain">(</span><span class="identifier">anchor</span><span class="plain">);</span>
<span class="identifier">WRITE_TO</span><span class="plain">(</span><span class="identifier">anchor</span><span class="plain">, </span><span class="string">"e%d"</span><span class="plain">, </span><span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">allocation_id</span><span class="plain">);</span>
<span class="functiontext">HTML::anchor</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="identifier">anchor</span><span class="plain">);</span>
<span class="identifier">DISCARD_TEXT</span><span class="plain">(</span><span class="identifier">anchor</span><span class="plain">);</span>
<span class="plain">}</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">indoc_settings</span><span class="plain">-&gt;</span><span class="element">navigation</span><span class="plain">-&gt;</span><span class="element">simplified_examples</span><span class="plain"> == </span><span class="constant">FALSE</span><span class="plain">) </span>&lt;<span class="cwebmacro">Render the example cue left surround</span> <span class="cwebmacronumber">8.2.1</span>&gt;<span class="plain">;</span>
<span class="identifier">TEMPORARY_TEXT</span><span class="plain">(</span><span class="identifier">url</span><span class="plain">);</span>
<span class="identifier">TEMPORARY_TEXT</span><span class="plain">(</span><span class="identifier">onclick</span><span class="plain">);</span>
<span class="functiontext">Examples::open_example_url</span><span class="plain">(</span><span class="identifier">url</span><span class="plain">, </span><span class="identifier">E</span><span class="plain">, </span><span class="identifier">V</span><span class="plain">, </span><span class="identifier">V</span><span class="plain">, </span><span class="identifier">writing_index</span><span class="plain">);</span>
<span class="functiontext">Examples::open_example_onclick</span><span class="plain">(</span><span class="identifier">onclick</span><span class="plain">, </span><span class="identifier">E</span><span class="plain">, </span><span class="identifier">V</span><span class="plain">, </span><span class="identifier">V</span><span class="plain">, </span><span class="identifier">writing_index</span><span class="plain">);</span>
<span class="functiontext">HTML::begin_link_with_class_onclick</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"eglink"</span><span class="plain">, </span><span class="identifier">url</span><span class="plain">, </span><span class="identifier">onclick</span><span class="plain">);</span>
<span class="identifier">DISCARD_TEXT</span><span class="plain">(</span><span class="identifier">url</span><span class="plain">);</span>
<span class="identifier">DISCARD_TEXT</span><span class="plain">(</span><span class="identifier">onclick</span><span class="plain">);</span>
&lt;<span class="cwebmacro">Render the example difficulty asterisks</span> <span class="cwebmacronumber">8.2.2</span>&gt;<span class="plain">;</span>
&lt;<span class="cwebmacro">Render the example name</span> <span class="cwebmacronumber">8.2.3</span>&gt;<span class="plain">;</span>
<span class="functiontext">HTML::end_link</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">);</span>
<span class="identifier">HTML_TAG</span><span class="plain">(</span><span class="string">"br"</span><span class="plain">);</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"%S"</span><span class="plain">, </span><span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">ex_outline</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">indoc_settings</span><span class="plain">-&gt;</span><span class="element">navigation</span><span class="plain">-&gt;</span><span class="element">simplified_examples</span><span class="plain"> == </span><span class="constant">FALSE</span><span class="plain">) </span>&lt;<span class="cwebmacro">Render the example cue right surround</span> <span class="cwebmacronumber">8.2.4</span>&gt;<span class="plain">;</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"\n"</span><span class="plain">);</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP8">&#167;8</a>.</p>
<p class="inwebparagraph"><a id="SP8_2_1"></a><b>&#167;8.2.1. </b>The "surround" is an table-implemented area which contains the descriptive
panel about the example. It has one row of three cells:
</p>
<pre class="display">
<span class="plain">[ ( 22 ) ] [ Example: Whatever ] [ RB ]</span>
</pre>
<p class="inwebparagraph">holding the "oval", the icon with the example number; the description of the
example, including its name; and the cross-link to the same example in the
other book.
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Render the example cue left surround</span> <span class="cwebmacronumber">8.2.1</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="identifier">HTML_OPEN_WITH</span><span class="plain">(</span><span class="string">"table"</span><span class="plain">, </span><span class="string">"class=\"egcue\""</span><span class="plain">);</span>
<span class="identifier">HTML_OPEN</span><span class="plain">(</span><span class="string">"tr"</span><span class="plain">);</span>
<span class="identifier">HTML_OPEN_WITH</span><span class="plain">(</span><span class="string">"td"</span><span class="plain">, </span><span class="string">"class=\"egcellforoval\""</span><span class="plain">); </span><span class="comment">The Oval begins</span>
<span class="functiontext">HTML::begin_div_with_class_S</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"egovalfornumber overstruckimage"</span><span class="plain">);</span>
<span class="identifier">TEMPORARY_TEXT</span><span class="plain">(</span><span class="identifier">url</span><span class="plain">);</span>
<span class="identifier">TEMPORARY_TEXT</span><span class="plain">(</span><span class="identifier">onclick</span><span class="plain">);</span>
<span class="functiontext">Examples::open_example_url</span><span class="plain">(</span><span class="identifier">url</span><span class="plain">, </span><span class="identifier">E</span><span class="plain">, </span><span class="identifier">V</span><span class="plain">, </span><span class="identifier">V</span><span class="plain">, </span><span class="identifier">writing_index</span><span class="plain">);</span>
<span class="functiontext">Examples::open_example_onclick</span><span class="plain">(</span><span class="identifier">onclick</span><span class="plain">, </span><span class="identifier">E</span><span class="plain">, </span><span class="identifier">V</span><span class="plain">, </span><span class="identifier">V</span><span class="plain">, </span><span class="identifier">writing_index</span><span class="plain">);</span>
<span class="functiontext">HTML::begin_link_with_class_onclick</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"eglink"</span><span class="plain">, </span><span class="identifier">url</span><span class="plain">, </span><span class="identifier">onclick</span><span class="plain">);</span>
<span class="identifier">DISCARD_TEXT</span><span class="plain">(</span><span class="identifier">url</span><span class="plain">);</span>
<span class="identifier">DISCARD_TEXT</span><span class="plain">(</span><span class="identifier">onclick</span><span class="plain">);</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"&lt;b&gt;%d&lt;/b&gt;"</span><span class="plain">, </span><span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">example_position</span><span class="plain">[0]);</span>
<span class="functiontext">HTML::end_link</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">);</span>
<span class="functiontext">HTML::end_div</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">);</span>
<span class="identifier">HTML_CLOSE</span><span class="plain">(</span><span class="string">"td"</span><span class="plain">); </span><span class="comment">The Oval ends</span>
<span class="identifier">HTML_OPEN_WITH</span><span class="plain">(</span><span class="string">"td"</span><span class="plain">, </span><span class="string">"class=\"egnamecell\""</span><span class="plain">);</span>
<span class="identifier">HTML_OPEN_WITH</span><span class="plain">(</span><span class="string">"p"</span><span class="plain">, </span><span class="string">"class=\"egcuetext\""</span><span class="plain">); </span><span class="comment">The Descriptive Panel Area begins</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP8_2">&#167;8.2</a>.</p>
<p class="inwebparagraph"><a id="SP8_2_2"></a><b>&#167;8.2.2. </b><code class="display">
&lt;<span class="cwebmacrodefn">Render the example difficulty asterisks</span> <span class="cwebmacronumber">8.2.2</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="reserved">for</span><span class="plain"> (</span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">starcc</span><span class="plain">=0; </span><span class="identifier">starcc</span><span class="plain"> &lt; </span><span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">ex_star_count</span><span class="plain">; </span><span class="identifier">starcc</span><span class="plain">++) {</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">indoc_settings</span><span class="plain">-&gt;</span><span class="element">navigation</span><span class="plain">-&gt;</span><span class="element">simplified_examples</span><span class="plain">) </span><span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"*"</span><span class="plain">);</span>
<span class="reserved">else</span><span class="plain"> </span><span class="functiontext">HTMLUtilities::asterisk_image</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"asterisk.png"</span><span class="plain">);</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP8_2">&#167;8.2</a>.</p>
<p class="inwebparagraph"><a id="SP8_2_3"></a><b>&#167;8.2.3. </b><code class="display">
&lt;<span class="cwebmacrodefn">Render the example name</span> <span class="cwebmacronumber">8.2.3</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="identifier">HTML_OPEN</span><span class="plain">(</span><span class="string">"b"</span><span class="plain">);</span>
<span class="identifier">TEMPORARY_TEXT</span><span class="plain">(</span><span class="identifier">text_of_name</span><span class="plain">);</span>
<span class="functiontext">Str::copy</span><span class="plain">(</span><span class="identifier">text_of_name</span><span class="plain">, </span><span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">ex_rubric</span><span class="plain">);</span>
<span class="reserved">match_results</span><span class="plain"> </span><span class="identifier">mr</span><span class="plain"> = </span><span class="functiontext">Regexp::create_mr</span><span class="plain">();</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Regexp::match</span><span class="plain">(&amp;</span><span class="identifier">mr</span><span class="plain">, </span><span class="identifier">text_of_name</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"%c*;(%c*?)"</span><span class="plain">)) </span><span class="functiontext">Str::copy</span><span class="plain">(</span><span class="identifier">text_of_name</span><span class="plain">, </span><span class="identifier">mr</span><span class="plain">.</span><span class="element">exp</span><span class="plain">[0]);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">Regexp::match</span><span class="plain">(&amp;</span><span class="identifier">mr</span><span class="plain">, </span><span class="identifier">text_of_name</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"(%c*?): (%d+)%c*"</span><span class="plain">)) {</span>
<span class="functiontext">Str::clear</span><span class="plain">(</span><span class="identifier">text_of_name</span><span class="plain">);</span>
<span class="identifier">WRITE_TO</span><span class="plain">(</span><span class="identifier">text_of_name</span><span class="plain">, </span><span class="string">"%S %S"</span><span class="plain">, </span><span class="identifier">mr</span><span class="plain">.</span><span class="element">exp</span><span class="plain">[0], </span><span class="identifier">mr</span><span class="plain">.</span><span class="element">exp</span><span class="plain">[1]);</span>
<span class="plain">}</span>
<span class="functiontext">Str::trim_white_space</span><span class="plain">(</span><span class="identifier">text_of_name</span><span class="plain">);</span>
<span class="functiontext">Rawtext::escape_HTML_characters_in</span><span class="plain">(</span><span class="identifier">text_of_name</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">indoc_settings</span><span class="plain">-&gt;</span><span class="element">navigation</span><span class="plain">-&gt;</span><span class="element">simplified_examples</span><span class="plain"> == </span><span class="constant">FALSE</span><span class="plain">) {</span>
<span class="identifier">HTML_OPEN_WITH</span><span class="plain">(</span><span class="string">"span"</span><span class="plain">, </span><span class="string">"class=\"egbanner\""</span><span class="plain">);</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"Example"</span><span class="plain">);</span>
<span class="identifier">HTML_CLOSE</span><span class="plain">(</span><span class="string">"span"</span><span class="plain">);</span>
<span class="identifier">HTML_OPEN_WITH</span><span class="plain">(</span><span class="string">"span"</span><span class="plain">, </span><span class="string">"class=\"egname\""</span><span class="plain">);</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"%S"</span><span class="plain">, </span><span class="identifier">text_of_name</span><span class="plain">);</span>
<span class="identifier">HTML_CLOSE</span><span class="plain">(</span><span class="string">"span"</span><span class="plain">);</span>
<span class="plain">} </span><span class="reserved">else</span><span class="plain"> {</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"Example %d: %S"</span><span class="plain">, </span><span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">example_position</span><span class="plain">[0], </span><span class="identifier">text_of_name</span><span class="plain">);</span>
<span class="plain">}</span>
<span class="identifier">DISCARD_TEXT</span><span class="plain">(</span><span class="identifier">text_of_name</span><span class="plain">);</span>
<span class="functiontext">Regexp::dispose_of</span><span class="plain">(&amp;</span><span class="identifier">mr</span><span class="plain">);</span>
<span class="identifier">HTML_CLOSE</span><span class="plain">(</span><span class="string">"b"</span><span class="plain">);</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP8_2">&#167;8.2</a>.</p>
<p class="inwebparagraph"><a id="SP8_2_4"></a><b>&#167;8.2.4. </b><code class="display">
&lt;<span class="cwebmacrodefn">Render the example cue right surround</span> <span class="cwebmacronumber">8.2.4</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="identifier">HTML_CLOSE</span><span class="plain">(</span><span class="string">"p"</span><span class="plain">);</span>
<span class="identifier">HTML_CLOSE</span><span class="plain">(</span><span class="string">"td"</span><span class="plain">); </span><span class="comment">The Descriptive Panel Area ends</span>
<span class="identifier">HTML_OPEN_WITH</span><span class="plain">(</span><span class="string">"td"</span><span class="plain">, </span><span class="string">"class=\"egcrossref\""</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">no_volumes</span><span class="plain"> &gt; </span><span class="constant">1</span><span class="plain">)</span>
&lt;<span class="cwebmacro">Render the cross-link to the same example in the other book</span> <span class="cwebmacronumber">8.2.4.1</span>&gt;<span class="plain">;</span>
<span class="identifier">HTML_CLOSE</span><span class="plain">(</span><span class="string">"td"</span><span class="plain">);</span>
<span class="identifier">HTML_CLOSE</span><span class="plain">(</span><span class="string">"tr"</span><span class="plain">);</span>
<span class="identifier">HTML_CLOSE</span><span class="plain">(</span><span class="string">"table"</span><span class="plain">);</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP8_2">&#167;8.2</a>.</p>
<p class="inwebparagraph"><a id="SP8_2_4_1"></a><b>&#167;8.2.4.1. </b><code class="display">
&lt;<span class="cwebmacrodefn">Render the cross-link to the same example in the other book</span> <span class="cwebmacronumber">8.2.4.1</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="reserved">char</span><span class="plain"> *</span><span class="identifier">cross_to</span><span class="plain"> = </span><span class="string">"RB"</span><span class="plain">; </span><span class="reserved">volume</span><span class="plain"> *</span><span class="identifier">V_to</span><span class="plain"> = </span><span class="identifier">volumes</span><span class="plain">[1];</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">V</span><span class="plain">-&gt;</span><span class="element">allocation_id</span><span class="plain"> == </span><span class="constant">1</span><span class="plain">) { </span><span class="identifier">cross_to</span><span class="plain"> = </span><span class="string">"WI"</span><span class="plain">; </span><span class="identifier">V_to</span><span class="plain"> = </span><span class="identifier">volumes</span><span class="plain">[0]; }</span>
<span class="functiontext">HTML::comment</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"START IGNORE"</span><span class="plain">);</span>
<span class="functiontext">HTML::begin_div_with_class_S</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"egovalforxref overstruckimage"</span><span class="plain">);</span>
<span class="identifier">TEMPORARY_TEXT</span><span class="plain">(</span><span class="identifier">url</span><span class="plain">);</span>
<span class="functiontext">Examples::open_example_url</span><span class="plain">(</span><span class="identifier">url</span><span class="plain">, </span><span class="identifier">E</span><span class="plain">, </span><span class="identifier">V</span><span class="plain">, </span><span class="identifier">V_to</span><span class="plain">, </span><span class="identifier">writing_index</span><span class="plain">);</span>
<span class="functiontext">HTML::begin_link</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="identifier">url</span><span class="plain">);</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"&lt;i&gt;%s&lt;/i&gt;"</span><span class="plain">, </span><span class="identifier">cross_to</span><span class="plain">);</span>
<span class="functiontext">HTML::end_link</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">);</span>
<span class="functiontext">HTML::end_div</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">);</span>
<span class="functiontext">HTML::comment</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"END IGNORE"</span><span class="plain">);</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP8_2_4">&#167;8.2.4</a>.</p>
<p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. </b>The following is a URL for a link which opens the example. Note that in
some cases this should work by a Javascript function call instead...
</p>
<pre class="display">
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Examples::open_example_url</span><span class="plain">(</span><span class="constant">OUTPUT_STREAM</span><span class="plain">, </span><span class="reserved">example</span><span class="plain"> *</span><span class="identifier">E</span><span class="plain">, </span><span class="reserved">volume</span><span class="plain"> *</span><span class="identifier">from_V</span><span class="plain">, </span><span class="reserved">volume</span><span class="plain"> *</span><span class="identifier">V</span><span class="plain">, </span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">writing_index</span><span class="plain">) {</span>
<span class="reserved">if</span><span class="plain"> ((</span><span class="identifier">indoc_settings</span><span class="plain">-&gt;</span><span class="element">examples_mode</span><span class="plain"> == </span><span class="constant">EXMODE_openable_internal</span><span class="plain">) &amp;&amp; (</span><span class="identifier">writing_index</span><span class="plain"> == </span><span class="constant">0</span><span class="plain">) &amp;&amp; (</span><span class="identifier">from_V</span><span class="plain"> == </span><span class="identifier">V</span><span class="plain">))</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"#"</span><span class="plain">);</span>
<span class="reserved">else</span>
<span class="functiontext">Examples::goto_example_url</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="identifier">E</span><span class="plain">, </span><span class="identifier">V</span><span class="plain">);</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The function Examples::open_example_url is used in <a href="#SP8_2">&#167;8.2</a>, <a href="#SP8_2_1">&#167;8.2.1</a>, <a href="#SP8_2_4_1">&#167;8.2.4.1</a>.</p>
<p class="inwebparagraph"><a id="SP10"></a><b>&#167;10. </b>...and this is it, used for the <code class="display"><span class="extract">onclick</span></code> field:
</p>
<pre class="display">
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Examples::open_example_onclick</span><span class="plain">(</span><span class="constant">OUTPUT_STREAM</span><span class="plain">, </span><span class="reserved">example</span><span class="plain"> *</span><span class="identifier">E</span><span class="plain">, </span><span class="reserved">volume</span><span class="plain"> *</span><span class="identifier">from_V</span><span class="plain">, </span><span class="reserved">volume</span><span class="plain"> *</span><span class="identifier">V</span><span class="plain">, </span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">writing_index</span><span class="plain">) {</span>
<span class="reserved">if</span><span class="plain"> ((</span><span class="identifier">indoc_settings</span><span class="plain">-&gt;</span><span class="element">examples_mode</span><span class="plain"> == </span><span class="constant">EXMODE_openable_internal</span><span class="plain">) &amp;&amp;</span>
<span class="plain">(</span><span class="identifier">writing_index</span><span class="plain"> == </span><span class="constant">0</span><span class="plain">) &amp;&amp;</span>
<span class="plain">(</span><span class="identifier">from_V</span><span class="plain"> == </span><span class="identifier">V</span><span class="plain">)) {</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"showExample('example%d'); return false;"</span><span class="plain">, </span><span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">allocation_id</span><span class="plain">);</span>
<span class="plain">}</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The function Examples::open_example_onclick is used in <a href="#SP8_2">&#167;8.2</a>, <a href="#SP8_2_1">&#167;8.2.1</a>.</p>
<p class="inwebparagraph"><a id="SP11"></a><b>&#167;11. </b>The actual URL holding the contents of an example are as follows:
</p>
<pre class="display">
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">Examples::goto_example_url</span><span class="plain">(</span><span class="constant">OUTPUT_STREAM</span><span class="plain">, </span><span class="reserved">example</span><span class="plain"> *</span><span class="identifier">E</span><span class="plain">, </span><span class="reserved">volume</span><span class="plain"> *</span><span class="identifier">V</span><span class="plain">) {</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"%S#e%d"</span><span class="plain">, </span><span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">example_belongs_to_section</span><span class="plain">[</span><span class="identifier">V</span><span class="plain">-&gt;</span><span class="element">allocation_id</span><span class="plain">]-&gt;</span><span class="element">unanchored_URL</span><span class="plain">, </span><span class="identifier">E</span><span class="plain">-&gt;</span><span class="element">allocation_id</span><span class="plain">);</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The function Examples::goto_example_url is used in <a href="#SP9">&#167;9</a>, 3/ei (<a href="3-ei.html#SP3_2">&#167;3.2</a>), 4/cr (<a href="4-cr.html#SP6_2">&#167;6.2</a>).</p>
<hr class="tocbar">
<ul class="toc"><li><a href="2-ss.html">Back to 'Structural Scan'</a></li><li><a href="2-rnd.html">Continue with 'Renderer'</a></li></ul><hr class="tocbar">
<!--End of weave-->
</main>
</body>
</html>
Reference in a new issue View git blame Copy permalink