ifhub/inform7
1
0
Fork 0
mirror of https://github.com/ganelson/inform.git synced 2024-07-03 07:24:58 +03:00
Code Issues Projects Releases Wiki Activity
inform7/docs/html-module/2-hd.html
Graham Nelson a693ee4653 Documentation tidy-up
2020-03-22 10:50:19 +00:00

938 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/jp</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"><b>compiler</b></a></li>
<li><a href="../other.html">other tools</a></li>
<li><a href="../extensions.html">extensions and kits</a></li>
<li><a href="../units.html">unit test tools</a></li>
</ul>
<h2>Compiler Webs</h2>
<ul>
<li><a href="../inbuild/index.html">inbuild</a></li>
<li><a href="../inform7/index.html">inform7</a></li>
<li><a href="../inter/index.html">inter</a></li>
</ul>
<h2>Inbuild Modules</h2>
<ul>
<li><a href="../inbuild-module/index.html">inbuild</a></li>
<li><a href="../arch-module/index.html">arch</a></li>
<li><a href="../words-module/index.html">words</a></li>
<li><a href="../syntax-module/index.html">syntax</a></li>
<li><a href="../html-module/index.html">html</a></li>
</ul>
<h2>Inform7 Modules</h2>
<ul>
<li><a href="../core-module/index.html">core</a></li>
<li><a href="../problems-module/index.html">problems</a></li>
<li><a href="../inflections-module/index.html">inflections</a></li>
<li><a href="../linguistics-module/index.html">linguistics</a></li>
<li><a href="../kinds-module/index.html">kinds</a></li>
<li><a href="../if-module/index.html">if</a></li>
<li><a href="../multimedia-module/index.html">multimedia</a></li>
<li><a href="../index-module/index.html">index</a></li>
</ul>
<h2>Inter Modules</h2>
<ul>
<li><a href="../inter-module/index.html">inter</a></li>
<li><a href="../building-module/index.html">building</a></li>
<li><a href="../codegen-module/index.html">codegen</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/hd' generated by 7-->
<ul class="crumbs"><li><a href="../webs.html">Source</a></li><li><a href="../compiler.html">Compiler Modules</a></li><li><a href="index.html">html</a></li><li><a href="index.html#2">Chapter 2: HTML</a></li><li><b>HTML Documentation</b></li></ul><p class="purpose">To translate a passage of source text into HTML-format documentation, for use in the automatically generated documentation pages on each installed extension.</p>
<ul class="toc"><li><a href="#SP2">&#167;2. Links and leafnames</a></li><li><a href="#SP7">&#167;7. The table of contents</a></li><li><a href="#SP9">&#167;9. Setting the body text</a></li><li><a href="#SP9_1">&#167;9.1. Typesetting the standard matter</a></li><li><a href="#SP9_6">&#167;9.6. Typesetting the headings</a></li><li><a href="#SP9_4_2_1">&#167;9.4.2.1. Typesetting I7 tables in displayed source text</a></li><li><a href="#SP9_8">&#167;9.8. Typesetting the body of an example</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. </b>This is a port of a simplified version of the Inform documentation tool
<code class="display"><span class="extract">indoc</span></code>, and like all Perl scripts ported to C, it bears a few scars.
</p>
<p class="inwebparagraph">Documentation is extracted from extensions by lexing them (ignoring all
of the actual source text and picking up only after the divider line)
and then running the code below on the word range for the lexed
documentation. Our task is therefore to print out this documentation
in an HTML format which matches the look and feel of pages produced
by <code class="display"><span class="extract">indoc</span></code> for the manuals.
</p>
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. Links and leafnames. </b>Matters are complicated because an extension typically has not only a
run of source text, but also up to 26 examples: suppose there are X
of these. The extension then needs to produce X+1 pages of HTML: the
primary one, which just has the body text, and then X variants which
duplicate the primary one except that one of the examples is opened up
to reveal its content. Each of these pages will have X anchor points
named <code class="display"><span class="extract">#eg1</span></code> up to <code class="display"><span class="extract">#egX</span></code>, for the positions of the examples.
</p>
<p class="inwebparagraph">The pages will typically be filenamed with the extension title, followed
by <code class="display"><span class="extract">-eg1</span></code>, <code class="display"><span class="extract">-eg2</span></code>, ..., in the case of the example variants, and then
<code class="display"><span class="extract">.html</span></code>.
</p>
<p class="inwebparagraph">The following routine prints the leafname part of an HTML reference to the
extension documentation, at anchor point <code class="display"><span class="extract">to_example_anchor</span></code> (or if 0 then
at the top) of the version with example <code class="display"><span class="extract">to_example_variant</span></code> opened (or if
0 then the original with all examples closed). What complicates it is that
the base leafname might be any of the above variant filenames, so we may
need to strip off an existing ending. For instance, if we are in example 2
and want to link to anchor 5 on example 4, the base leafname might be
<code class="display"><span class="extract">Gusher-eg2</span></code> and we need to remove the <code class="display"><span class="extract">-eg2</span></code> and replace with <code class="display"><span class="extract">-eg4</span></code>
before we can add the <code class="display"><span class="extract">#eg5</span></code>.
</p>
<p class="inwebparagraph">This will fail if anyone's extension has a title ending in <code class="display"><span class="extract">-eg</span></code> followed
by a number. I believe I can live with the guilt.
</p>
<pre class="display">
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">HTML::Documentation::href_of_example</span><span class="plain">(</span><span class="identifier">OUTPUT_STREAM</span><span class="plain">, </span><span class="identifier">text_stream</span><span class="plain"> *</span><span class="identifier">base_leafname</span><span class="plain">,</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">to_example_variant</span><span class="plain">, </span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">to_example_anchor</span><span class="plain">) {</span>
<span class="reserved">for</span><span class="plain"> (</span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">i</span><span class="plain">=0, </span><span class="identifier">L</span><span class="plain"> = </span><span class="identifier">Str::len</span><span class="plain">(</span><span class="identifier">base_leafname</span><span class="plain">); </span><span class="identifier">i</span><span class="plain">&lt;</span><span class="identifier">L</span><span class="plain">; </span><span class="identifier">i</span><span class="plain">++) {</span>
<span class="reserved">if</span><span class="plain"> ((</span><span class="identifier">Str::includes_wide_string_at</span><span class="plain">(</span><span class="identifier">base_leafname</span><span class="plain">, </span><span class="identifier">L</span><span class="string">"-eg"</span><span class="plain">, </span><span class="identifier">i</span><span class="plain">)) &amp;&amp;</span>
<span class="plain">(</span><span class="identifier">Characters::isdigit</span><span class="plain">(</span><span class="identifier">Str::get_at</span><span class="plain">(</span><span class="identifier">base_leafname</span><span class="plain">, </span><span class="identifier">i</span><span class="plain">+3)))) </span><span class="reserved">break</span><span class="plain">;</span>
<span class="identifier">PUT</span><span class="plain">(</span><span class="identifier">Str::get_at</span><span class="plain">(</span><span class="identifier">base_leafname</span><span class="plain">, </span><span class="identifier">i</span><span class="plain">));</span>
<span class="plain">}</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">to_example_variant</span><span class="plain"> &gt; 0) </span><span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"-eg%d"</span><span class="plain">, </span><span class="identifier">to_example_variant</span><span class="plain">);</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">".html"</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">to_example_anchor</span><span class="plain"> &gt; 0) </span><span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"#eg%d"</span><span class="plain">, </span><span class="identifier">to_example_anchor</span><span class="plain">);</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The function HTML::Documentation::href_of_example is used in <a href="#SP7_2">&#167;7.2</a>, <a href="#SP9_7_2">&#167;9.7.2</a>.</p>
<p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. </b>The extension documentation text can optionally include section and
chapter headings, and also examples. Here we parse the opening of a paragraph
to see if it might be a heading. For instance, a paragraph consisting of
</p>
<blockquote>
<p>Section: Black Gold</p>
</blockquote>
<p class="inwebparagraph">matches successfully and sets the level to 2 and the name to the word range
"Black Gold".
</p>
<pre class="display">
<span class="plain">&lt;</span><span class="identifier">extension</span><span class="plain">-</span><span class="identifier">documentation</span><span class="plain">-</span><span class="identifier">heading</span><span class="plain">&gt; ::=</span>
<span class="identifier">chapter</span><span class="plain"> : ... | ==&gt; 1</span>
<span class="identifier">section</span><span class="plain"> : ... ==&gt; 2</span>
</pre>
<p class="inwebparagraph"></p>
<p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b></p>
<pre class="display">
<span class="reserved">int</span><span class="plain"> </span><span class="functiontext">HTML::Documentation::extension_documentation_heading</span><span class="plain">(</span><span class="identifier">wording</span><span class="plain"> </span><span class="identifier">W</span><span class="plain">, </span><span class="reserved">int</span><span class="plain"> *</span><span class="identifier">level</span><span class="plain">, </span><span class="identifier">wording</span><span class="plain"> *</span><span class="identifier">HW</span><span class="plain">) {</span>
<span class="reserved">if</span><span class="plain"> (&lt;</span><span class="identifier">extension</span><span class="plain">-</span><span class="identifier">documentation</span><span class="plain">-</span><span class="identifier">heading</span><span class="plain">&gt;(</span><span class="identifier">W</span><span class="plain">)) {</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">Wordings::length</span><span class="plain">(</span><span class="identifier">W</span><span class="plain">) &gt; 10) </span><span class="reserved">return</span><span class="plain"> </span><span class="identifier">FALSE</span><span class="plain">; </span> <span class="comment">not enough space: this runs into the end-of-file padding</span>
<span class="plain">*</span><span class="identifier">level</span><span class="plain"> = &lt;&lt;</span><span class="identifier">r</span><span class="plain">&gt;&gt;;</span>
<span class="identifier">W</span><span class="plain"> = </span><span class="identifier">Wordings::trim_first_word</span><span class="plain">(</span><span class="identifier">Wordings::trim_first_word</span><span class="plain">(</span><span class="identifier">W</span><span class="plain">));</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">end</span><span class="plain"> = </span><span class="identifier">Wordings::first_wn</span><span class="plain">(</span><span class="identifier">W</span><span class="plain">);</span>
<span class="reserved">while</span><span class="plain"> ((</span><span class="identifier">end</span><span class="plain">&lt;=</span><span class="identifier">Wordings::last_wn</span><span class="plain">(</span><span class="identifier">W</span><span class="plain">)) &amp;&amp; (</span><span class="identifier">Lexer::word</span><span class="plain">(</span><span class="identifier">end</span><span class="plain">) != </span><span class="identifier">PARBREAK_V</span><span class="plain">)) </span><span class="identifier">end</span><span class="plain">++;</span>
<span class="identifier">end</span><span class="plain">--;</span>
<span class="plain">*</span><span class="identifier">HW</span><span class="plain"> = </span><span class="identifier">Wordings::up_to</span><span class="plain">(</span><span class="identifier">W</span><span class="plain">, </span><span class="identifier">end</span><span class="plain">);</span>
<span class="reserved">return</span><span class="plain"> </span><span class="identifier">TRUE</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="reserved">return</span><span class="plain"> </span><span class="identifier">FALSE</span><span class="plain">;</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The function HTML::Documentation::extension_documentation_heading is used in <a href="#SP7">&#167;7</a>, <a href="#SP9">&#167;9</a>.</p>
<p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b>And here we do the same to identify an example, which has to satisfy a
more exacting specification: a paragraph in the shape
</p>
<blockquote>
<p>Example: *** Gelignite Anderson - A Tale of the Texas Oilmen</p>
</blockquote>
<p class="inwebparagraph">which would result in the name being set to the range "Gelignite Anderson",
an asterisk count of 3, and the rubric being "A Tale of the Texas Oilmen".
</p>
<pre class="display">
<span class="plain">&lt;</span><span class="identifier">extension</span><span class="plain">-</span><span class="identifier">example</span><span class="plain">-</span><span class="identifier">header</span><span class="plain">&gt; ::=</span>
<span class="identifier">example</span><span class="plain"> : &lt;</span><span class="identifier">row</span><span class="plain">-</span><span class="identifier">of</span><span class="plain">-</span><span class="identifier">asterisks</span><span class="plain">&gt; ... - ... | ==&gt; </span><span class="identifier">R</span><span class="plain">[1]</span>
<span class="identifier">example</span><span class="plain"> : ... - ... ==&gt; 0</span>
<span class="plain">&lt;</span><span class="identifier">row</span><span class="plain">-</span><span class="identifier">of</span><span class="plain">-</span><span class="identifier">asterisks</span><span class="plain">&gt; ::=</span>
<span class="plain">* | ==&gt; 1</span>
<span class="plain">** | ==&gt; 2</span>
<span class="plain">\*** | ==&gt; 3</span>
<span class="plain">**** ==&gt; 4</span>
</pre>
<p class="inwebparagraph"></p>
<p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b></p>
<pre class="display">
<span class="reserved">int</span><span class="plain"> </span><span class="functiontext">HTML::Documentation::extension_documentation_example</span><span class="plain">(</span><span class="identifier">wording</span><span class="plain"> </span><span class="identifier">W</span><span class="plain">,</span>
<span class="reserved">int</span><span class="plain"> *</span><span class="identifier">asterisks</span><span class="plain">, </span><span class="identifier">wording</span><span class="plain"> *</span><span class="identifier">egn</span><span class="plain">, </span><span class="identifier">wording</span><span class="plain"> *</span><span class="identifier">egr</span><span class="plain">) {</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">Wordings::length</span><span class="plain">(</span><span class="identifier">W</span><span class="plain">) &gt; 10) </span><span class="reserved">return</span><span class="plain"> </span><span class="identifier">FALSE</span><span class="plain">; </span> <span class="comment">not enough space: this runs into the end-of-file padding</span>
<span class="reserved">if</span><span class="plain"> (&lt;</span><span class="identifier">extension</span><span class="plain">-</span><span class="identifier">example</span><span class="plain">-</span><span class="identifier">header</span><span class="plain">&gt;(</span><span class="identifier">W</span><span class="plain">)) {</span>
<span class="identifier">wording</span><span class="plain"> </span><span class="identifier">NW</span><span class="plain"> = </span><span class="identifier">GET_RW</span><span class="plain">(&lt;</span><span class="identifier">extension</span><span class="plain">-</span><span class="identifier">example</span><span class="plain">-</span><span class="identifier">header</span><span class="plain">&gt;, 1);</span>
<span class="identifier">wording</span><span class="plain"> </span><span class="identifier">RW</span><span class="plain"> = </span><span class="identifier">Wordings::first_word</span><span class="plain">(</span><span class="identifier">GET_RW</span><span class="plain">(&lt;</span><span class="identifier">extension</span><span class="plain">-</span><span class="identifier">example</span><span class="plain">-</span><span class="identifier">header</span><span class="plain">&gt;, 2));</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">r2</span><span class="plain"> = </span><span class="identifier">Wordings::first_wn</span><span class="plain">(</span><span class="identifier">RW</span><span class="plain">);</span>
<span class="reserved">while</span><span class="plain"> ((</span><span class="identifier">r2</span><span class="plain"> &lt;= </span><span class="identifier">Wordings::last_wn</span><span class="plain">(</span><span class="identifier">W</span><span class="plain">)) &amp;&amp; ((</span><span class="identifier">Lexer::word</span><span class="plain">(</span><span class="identifier">r2</span><span class="plain">) == </span><span class="identifier">PARBREAK_V</span><span class="plain">) == </span><span class="identifier">FALSE</span><span class="plain">)) </span><span class="identifier">r2</span><span class="plain">++;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">r2</span><span class="plain"> &gt;= </span><span class="identifier">Wordings::last_wn</span><span class="plain">(</span><span class="identifier">W</span><span class="plain">)) </span><span class="reserved">return</span><span class="plain"> </span><span class="identifier">FALSE</span><span class="plain">;</span>
<span class="identifier">r2</span><span class="plain">--;</span>
<span class="comment">a successful match has now been made</span>
<span class="plain">*</span><span class="identifier">asterisks</span><span class="plain"> = &lt;&lt;</span><span class="identifier">r</span><span class="plain">&gt;&gt;; *</span><span class="identifier">egn</span><span class="plain"> = </span><span class="identifier">NW</span><span class="plain">; *</span><span class="identifier">egr</span><span class="plain"> = </span><span class="identifier">RW</span><span class="plain">;</span>
<span class="reserved">return</span><span class="plain"> </span><span class="identifier">TRUE</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="reserved">return</span><span class="plain"> </span><span class="identifier">FALSE</span><span class="plain">;</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The function HTML::Documentation::extension_documentation_example is used in <a href="#SP7">&#167;7</a>, <a href="#SP9">&#167;9</a>.</p>
<p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. The table of contents. </b>The user sees chapters as A subheadings, numbered upwards from 1, and
sees sections as B subheadings, numbered from 1 within each chapter.
It is legal to have only A subheadings; only B subheadings; or a mixture
of the two.
</p>
<p class="inwebparagraph">If a scan can find any headings at all then we will wish to typeset
a table of contents up front. The following routine looks for what material
might go into a TOC, and sets one if it finds anything: otherwise, it sets
nothing and has no effect. Because of the compulsory paragraph break
following the divider line in the extension, we can safely assume that
every headng will follow a paragraph break word, even one right at the
top of the extension's documentation.
</p>
<p class="inwebparagraph">(Examples are included in the table of contents only if they occur after
the first heading, which I think is reasonable enough: there can be at most
26 per extension, enabling them to be lettered as Example A to Example Z.)
</p>
<pre class="display">
<span class="reserved">void</span><span class="plain"> </span><span class="functiontext">HTML::Documentation::set_table_of_contents</span><span class="plain">(</span><span class="identifier">wording</span><span class="plain"> </span><span class="identifier">W</span><span class="plain">, </span><span class="identifier">OUTPUT_STREAM</span><span class="plain">, </span><span class="identifier">text_stream</span><span class="plain"> *</span><span class="identifier">base_leafname</span><span class="plain">) {</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">heading_count</span><span class="plain"> = 0, </span><span class="identifier">chapter_count</span><span class="plain"> = 0, </span><span class="identifier">section_count</span><span class="plain"> = 0, </span><span class="identifier">example_count</span><span class="plain"> = 0;</span>
<span class="identifier">LOOP_THROUGH_WORDING</span><span class="plain">(</span><span class="identifier">i</span><span class="plain">, </span><span class="identifier">W</span><span class="plain">) {</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">edhl</span><span class="plain">, </span><span class="identifier">asterisks</span><span class="plain">;</span>
<span class="identifier">wording</span><span class="plain"> </span><span class="identifier">NW</span><span class="plain"> = </span><span class="identifier">EMPTY_WORDING</span><span class="plain">, </span><span class="identifier">RUBW</span><span class="plain"> = </span><span class="identifier">EMPTY_WORDING</span><span class="plain">;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">Lexer::word</span><span class="plain">(</span><span class="identifier">i</span><span class="plain">) == </span><span class="identifier">PARBREAK_V</span><span class="plain">) { </span> <span class="comment">the lexer records this to mean a paragraph break</span>
<span class="reserved">while</span><span class="plain"> (</span><span class="identifier">Lexer::word</span><span class="plain">(</span><span class="identifier">i</span><span class="plain">) == </span><span class="identifier">PARBREAK_V</span><span class="plain">) </span><span class="identifier">i</span><span class="plain">++; </span><span class="reserved">if</span><span class="plain"> (</span><span class="identifier">i</span><span class="plain">&gt;</span><span class="identifier">Wordings::last_wn</span><span class="plain">(</span><span class="identifier">W</span><span class="plain">)) </span><span class="reserved">break</span><span class="plain">;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">HTML::Documentation::extension_documentation_heading</span><span class="plain">(</span><span class="identifier">Wordings::from</span><span class="plain">(</span><span class="identifier">W</span><span class="plain">, </span><span class="identifier">i</span><span class="plain">), &amp;</span><span class="identifier">edhl</span><span class="plain">, &amp;</span><span class="identifier">NW</span><span class="plain">)) {</span>
<span class="identifier">heading_count</span><span class="plain">++;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">heading_count</span><span class="plain"> == 1) {</span>
<span class="identifier">HTML_CLOSE</span><span class="plain">(</span><span class="string">"p"</span><span class="plain">);</span>
<span class="identifier">HTML_TAG</span><span class="plain">(</span><span class="string">"hr"</span><span class="plain">); </span> <span class="comment">ruled line at top of TOC</span>
<span class="identifier">HTML_OPEN</span><span class="plain">(</span><span class="string">"p"</span><span class="plain">);</span>
<span class="plain">}</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">edhl</span><span class="plain"> == 1) {</span>
<span class="identifier">chapter_count</span><span class="plain">++; </span><span class="identifier">section_count</span><span class="plain"> = 0;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">chapter_count</span><span class="plain"> &gt; 1) </span><span class="identifier">HTML_TAG</span><span class="plain">(</span><span class="string">"br"</span><span class="plain">); </span> <span class="comment">skip a line between chapters in TOC</span>
<span class="plain">}</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">edhl</span><span class="plain"> == 2) </span><span class="identifier">section_count</span><span class="plain">++;</span>
&lt;<span class="cwebmacro">Typeset the table of contents entry for this heading</span> <span class="cwebmacronumber">7.1</span>&gt;<span class="plain">;</span>
<span class="identifier">i</span><span class="plain"> = </span><span class="identifier">Wordings::last_wn</span><span class="plain">(</span><span class="identifier">NW</span><span class="plain">); </span><span class="reserved">continue</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="reserved">if</span><span class="plain"> ((</span><span class="identifier">heading_count</span><span class="plain"> &gt; 0) &amp;&amp; (</span><span class="identifier">example_count</span><span class="plain"> &lt; 26) &amp;&amp;</span>
<span class="plain">(</span><span class="functiontext">HTML::Documentation::extension_documentation_example</span><span class="plain">(</span>
<span class="identifier">Wordings::from</span><span class="plain">(</span><span class="identifier">W</span><span class="plain">, </span><span class="identifier">i</span><span class="plain">), &amp;</span><span class="identifier">asterisks</span><span class="plain">, &amp;</span><span class="identifier">NW</span><span class="plain">, &amp;</span><span class="identifier">RUBW</span><span class="plain">))) {</span>
<span class="reserved">if</span><span class="plain"> (++</span><span class="identifier">example_count</span><span class="plain"> == 1) {</span>
<span class="identifier">HTML_TAG</span><span class="plain">(</span><span class="string">"br"</span><span class="plain">);</span>
<span class="identifier">HTML_OPEN</span><span class="plain">(</span><span class="string">"b"</span><span class="plain">);</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"Examples"</span><span class="plain">);</span>
<span class="identifier">HTML_CLOSE</span><span class="plain">(</span><span class="string">"b"</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="plain">}</span>
&lt;<span class="cwebmacro">Typeset the table of contents entry for this example</span> <span class="cwebmacronumber">7.2</span>&gt;<span class="plain">;</span>
<span class="identifier">i</span><span class="plain"> = </span><span class="identifier">Wordings::last_wn</span><span class="plain">(</span><span class="identifier">RUBW</span><span class="plain">); </span><span class="reserved">continue</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="plain">}</span>
<span class="plain">}</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">heading_count</span><span class="plain"> &gt; 0) {</span>
<span class="identifier">HTML_CLOSE</span><span class="plain">(</span><span class="string">"p"</span><span class="plain">);</span>
<span class="identifier">HTML_TAG</span><span class="plain">(</span><span class="string">"hr"</span><span class="plain">); </span> <span class="comment">ruled line at foot of TOC, if there is one</span>
<span class="identifier">HTML_OPEN</span><span class="plain">(</span><span class="string">"p"</span><span class="plain">);</span>
<span class="plain">}</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The function HTML::Documentation::set_table_of_contents appears nowhere else.</p>
<p class="inwebparagraph"><a id="SP7_1"></a><b>&#167;7.1. </b>Internally, we are numbering all headings independently upwards from 1, and
we set anchor points in the documentation called <code class="display"><span class="extract">#docsec1</span></code>, <code class="display"><span class="extract">#docsec2</span></code>,
and so on: some of these will be chapter headings, some section headings.
These are the destinations of links from heading lines in the TOC.
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Typeset the table of contents entry for this heading</span> <span class="cwebmacronumber">7.1</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="reserved">switch</span><span class="plain"> (</span><span class="identifier">edhl</span><span class="plain">) {</span>
<span class="reserved">case</span><span class="plain"> 1:</span>
<span class="identifier">HTML_OPEN</span><span class="plain">(</span><span class="string">"b"</span><span class="plain">);</span>
<span class="identifier">HTML_OPEN_WITH</span><span class="plain">(</span><span class="string">"a"</span><span class="plain">, </span><span class="string">"style=\</span><span class="plain">"</span><span class="string">text-decoration: none\</span><span class="plain">"</span><span class="string"> href=#docsec%d"</span><span class="plain">, </span><span class="identifier">heading_count</span><span class="plain">);</span>
<span class="identifier">HTML::begin_colour</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"000000"</span><span class="plain">);</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"Chapter %d: "</span><span class="plain">, </span><span class="identifier">chapter_count</span><span class="plain">);</span>
<span class="identifier">HTML::end_colour</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">"a"</span><span class="plain">);</span>
<span class="identifier">HTML_CLOSE</span><span class="plain">(</span><span class="string">"b"</span><span class="plain">);</span>
<span class="reserved">break</span><span class="plain">;</span>
<span class="reserved">case</span><span class="plain"> 2:</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">chapter_count</span><span class="plain"> &gt; 0) </span> <span class="comment">if there are chapters as well as sections...</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"&amp;nbsp;&amp;nbsp;&amp;nbsp;"</span><span class="plain">); </span> <span class="comment">...then set an indentation before entry</span>
<span class="identifier">HTML_OPEN_WITH</span><span class="plain">(</span><span class="string">"a"</span><span class="plain">, </span><span class="string">"style=\</span><span class="plain">"</span><span class="string">text-decoration: none\</span><span class="plain">"</span><span class="string"> href=#docsec%d"</span><span class="plain">, </span><span class="identifier">heading_count</span><span class="plain">);</span>
<span class="identifier">HTML::begin_colour</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"000000"</span><span class="plain">);</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"Section "</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">chapter_count</span><span class="plain"> &gt; 0) </span> <span class="comment">if there are chapters as well as sections...</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"%d.%d: "</span><span class="plain">, </span><span class="identifier">chapter_count</span><span class="plain">, </span><span class="identifier">section_count</span><span class="plain">); </span> <span class="comment">quote in form S.C</span>
<span class="reserved">else</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"%d: "</span><span class="plain">, </span><span class="identifier">section_count</span><span class="plain">); </span> <span class="comment">otherwise quote section number only</span>
<span class="identifier">HTML::end_colour</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">"a"</span><span class="plain">);</span>
<span class="reserved">break</span><span class="plain">;</span>
<span class="reserved">default</span><span class="plain">: </span><span class="identifier">internal_error</span><span class="plain">(</span><span class="string">"unable to set this heading level in extension TOC"</span><span class="plain">);</span>
<span class="plain">}</span>
<span class="functiontext">HTML::Documentation::set_body_text</span><span class="plain">(</span><span class="identifier">NW</span><span class="plain">, </span><span class="identifier">OUT</span><span class="plain">, </span><span class="constant">EDOC_FRAGMENT_ONLY</span><span class="plain">, </span><span class="identifier">NULL</span><span class="plain">);</span>
<span class="identifier">HTML_TAG</span><span class="plain">(</span><span class="string">"br"</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_2"></a><b>&#167;7.2. </b>The TOC entries for examples are similar. Here the link is to the variant
page in the current family which has the given example open, and moreover,
to the anchor in that page corresponding to the top of the example: thus as
far as the user is concerned it opens the example and goes there.
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Typeset the table of contents entry for this example</span> <span class="cwebmacronumber">7.2</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"&amp;nbsp;&amp;nbsp;&amp;nbsp;"</span><span class="plain">); </span> <span class="comment">always indent TOC entries for examples</span>
<span class="identifier">TEMPORARY_TEXT</span><span class="plain">(</span><span class="identifier">link</span><span class="plain">);</span>
<span class="identifier">WRITE_TO</span><span class="plain">(</span><span class="identifier">link</span><span class="plain">, </span><span class="string">"style=\</span><span class="plain">"</span><span class="string">text-decoration: none\</span><span class="plain">"</span><span class="string"> href=\</span><span class="plain">"</span><span class="string">"</span><span class="plain">);</span>
<span class="functiontext">HTML::Documentation::href_of_example</span><span class="plain">(</span><span class="identifier">link</span><span class="plain">, </span><span class="identifier">base_leafname</span><span class="plain">, </span><span class="identifier">example_count</span><span class="plain">, </span><span class="identifier">example_count</span><span class="plain">);</span>
<span class="identifier">WRITE_TO</span><span class="plain">(</span><span class="identifier">link</span><span class="plain">, </span><span class="string">"\</span><span class="plain">"</span><span class="string">"</span><span class="plain">);</span>
<span class="identifier">HTML_OPEN_WITH</span><span class="plain">(</span><span class="string">"a"</span><span class="plain">, </span><span class="string">"%S"</span><span class="plain">, </span><span class="identifier">link</span><span class="plain">);</span>
<span class="identifier">HTML::begin_colour</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"000000"</span><span class="plain">);</span>
<span class="identifier">PUT</span><span class="plain">(</span><span class="character">'A'</span><span class="plain">+</span><span class="identifier">example_count</span><span class="plain">-1); </span> <span class="comment">the letter A to Z</span>
<span class="functiontext">HTML::Documentation::set_body_text</span><span class="plain">(</span><span class="identifier">NW</span><span class="plain">, </span><span class="identifier">OUT</span><span class="plain">, </span><span class="constant">EDOC_FRAGMENT_ONLY</span><span class="plain">, </span><span class="identifier">NULL</span><span class="plain">);</span>
<span class="identifier">HTML::end_colour</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">"a"</span><span class="plain">);</span>
<span class="identifier">HTML_TAG</span><span class="plain">(</span><span class="string">"br"</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="SP8"></a><b>&#167;8. </b></p>
<pre class="display">
<span class="plain">&lt;</span><span class="identifier">table</span><span class="plain">-</span><span class="identifier">sentence</span><span class="plain">&gt; ::=</span>
<span class="plain">&lt;</span><span class="reserved">if</span><span class="plain">-</span><span class="identifier">start</span><span class="plain">-</span><span class="identifier">of</span><span class="plain">-</span><span class="identifier">paragraph</span><span class="plain">&gt; </span><span class="identifier">table</span><span class="plain"> ...</span>
</pre>
<p class="inwebparagraph"></p>
<p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. Setting the body text. </b></p>
<pre class="definitions">
<span class="definitionkeyword">define</span> <span class="constant">EDOC_ALL_EXAMPLES_CLOSED</span><span class="plain"> -1 </span> <span class="comment">do not change this without also changing Extensions</span>
<span class="definitionkeyword">define</span> <span class="constant">EDOC_FRAGMENT_ONLY</span><span class="plain"> -2 </span> <span class="comment">must differ from this and from all example variant numbers</span>
</pre>
<pre class="display">
<span class="reserved">int</span><span class="plain"> </span><span class="functiontext">HTML::Documentation::set_body_text</span><span class="plain">(</span><span class="identifier">wording</span><span class="plain"> </span><span class="identifier">W</span><span class="plain">, </span><span class="identifier">OUTPUT_STREAM</span><span class="plain">,</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">example_which_is_open</span><span class="plain">, </span><span class="identifier">text_stream</span><span class="plain"> *</span><span class="identifier">base_leafname</span><span class="plain">) {</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">heading_count</span><span class="plain"> = 0, </span><span class="identifier">chapter_count</span><span class="plain"> = 0, </span><span class="identifier">section_count</span><span class="plain"> = 0, </span><span class="identifier">example_count</span><span class="plain"> = 0;</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">mid_example</span><span class="plain"> = </span><span class="identifier">FALSE</span><span class="plain">, </span><span class="identifier">skipping_text_of_an_example</span><span class="plain"> = </span><span class="identifier">FALSE</span><span class="plain">,</span>
<span class="identifier">start_table_next_line</span><span class="plain"> = </span><span class="identifier">FALSE</span><span class="plain">, </span><span class="identifier">mid_I7_table</span><span class="plain"> = </span><span class="identifier">FALSE</span><span class="plain">, </span><span class="identifier">row_of_table_is_empty</span><span class="plain"> = </span><span class="identifier">FALSE</span><span class="plain">,</span>
<span class="identifier">mid_displayed_source_text</span><span class="plain"> = </span><span class="identifier">FALSE</span><span class="plain">, </span><span class="identifier">indentation</span><span class="plain"> = 0, </span><span class="identifier">close_I6_position</span><span class="plain"> = -1;</span>
<span class="identifier">HTML_OPEN</span><span class="plain">(</span><span class="string">"p"</span><span class="plain">);</span>
<span class="identifier">LOOP_THROUGH_WORDING</span><span class="plain">(</span><span class="identifier">i</span><span class="plain">, </span><span class="identifier">W</span><span class="plain">) {</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">edhl</span><span class="plain">, </span><span class="identifier">asterisks</span><span class="plain">;</span>
<span class="identifier">wording</span><span class="plain"> </span><span class="identifier">NW</span><span class="plain"> = </span><span class="identifier">EMPTY_WORDING</span><span class="plain">, </span><span class="identifier">RUBW</span><span class="plain"> = </span><span class="identifier">EMPTY_WORDING</span><span class="plain">;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">Lexer::word</span><span class="plain">(</span><span class="identifier">i</span><span class="plain">) == </span><span class="identifier">PARBREAK_V</span><span class="plain">) { </span> <span class="comment">the lexer records this to mean a paragraph break</span>
&lt;<span class="cwebmacro">Handle a paragraph break</span> <span class="cwebmacronumber">9.1</span>&gt;<span class="plain">;</span>
<span class="reserved">while</span><span class="plain"> (</span><span class="identifier">Lexer::word</span><span class="plain">(</span><span class="identifier">i</span><span class="plain">) == </span><span class="identifier">PARBREAK_V</span><span class="plain">) </span><span class="identifier">i</span><span class="plain">++;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">i</span><span class="plain">&gt;</span><span class="identifier">Wordings::last_wn</span><span class="plain">(</span><span class="identifier">W</span><span class="plain">)) </span><span class="reserved">break</span><span class="plain">; </span> <span class="comment">treat multiple paragraph breaks as one</span>
&lt;<span class="cwebmacro">Determine indentation of new paragraph</span> <span class="cwebmacronumber">9.2</span>&gt;<span class="plain">;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="functiontext">HTML::Documentation::extension_documentation_heading</span><span class="plain">(</span><span class="identifier">Wordings::from</span><span class="plain">(</span><span class="identifier">W</span><span class="plain">, </span><span class="identifier">i</span><span class="plain">), &amp;</span><span class="identifier">edhl</span><span class="plain">, &amp;</span><span class="identifier">NW</span><span class="plain">)) {</span>
<span class="identifier">heading_count</span><span class="plain">++;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">edhl</span><span class="plain"> == 1) {</span>
<span class="identifier">chapter_count</span><span class="plain">++; </span><span class="identifier">section_count</span><span class="plain"> = 0;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">chapter_count</span><span class="plain"> &gt; 1) {</span>
<span class="identifier">HTML_CLOSE</span><span class="plain">(</span><span class="string">"p"</span><span class="plain">);</span>
<span class="identifier">HTML_TAG</span><span class="plain">(</span><span class="string">"hr"</span><span class="plain">); </span> <span class="comment">rule a line between chapters</span>
<span class="plain">}</span>
<span class="plain">}</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">edhl</span><span class="plain"> == 2) </span><span class="identifier">section_count</span><span class="plain">++;</span>
&lt;<span class="cwebmacro">Typeset the heading of this chapter or section</span> <span class="cwebmacronumber">9.6</span>&gt;<span class="plain">;</span>
<span class="identifier">i</span><span class="plain"> = </span><span class="identifier">Wordings::last_wn</span><span class="plain">(</span><span class="identifier">NW</span><span class="plain">); </span><span class="reserved">continue</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="reserved">if</span><span class="plain"> ((</span><span class="identifier">example_count</span><span class="plain"> &lt; 26) &amp;&amp; (</span><span class="functiontext">HTML::Documentation::extension_documentation_example</span><span class="plain">(</span>
<span class="identifier">Wordings::from</span><span class="plain">(</span><span class="identifier">W</span><span class="plain">, </span><span class="identifier">i</span><span class="plain">), &amp;</span><span class="identifier">asterisks</span><span class="plain">, &amp;</span><span class="identifier">NW</span><span class="plain">, &amp;</span><span class="identifier">RUBW</span><span class="plain">))) {</span>
<span class="identifier">skipping_text_of_an_example</span><span class="plain"> = </span><span class="identifier">FALSE</span><span class="plain">;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">mid_example</span><span class="plain">) </span>&lt;<span class="cwebmacro">Close the previous example's text</span> <span class="cwebmacronumber">9.9</span>&gt;<span class="character">;</span>
<span class="identifier">mid_example</span><span class="plain"> = </span><span class="identifier">FALSE</span><span class="plain">;</span>
<span class="identifier">example_count</span><span class="plain">++;</span>
&lt;<span class="cwebmacro">Typeset the heading of this example</span> <span class="cwebmacronumber">9.7</span>&gt;<span class="plain">;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">example_count</span><span class="plain"> == </span><span class="identifier">example_which_is_open</span><span class="plain">) {</span>
&lt;<span class="cwebmacro">Open the new example's text</span> <span class="cwebmacronumber">9.8</span>&gt;<span class="character">;</span>
<span class="identifier">mid_example</span><span class="plain"> = </span><span class="identifier">TRUE</span><span class="plain">;</span>
<span class="plain">} </span><span class="reserved">else</span><span class="plain"> </span><span class="identifier">skipping_text_of_an_example</span><span class="plain"> = </span><span class="identifier">TRUE</span><span class="plain">;</span>
<span class="identifier">i</span><span class="plain"> = </span><span class="identifier">Wordings::last_wn</span><span class="plain">(</span><span class="identifier">RUBW</span><span class="plain">); </span><span class="reserved">continue</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="plain">}</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">skipping_text_of_an_example</span><span class="plain">) </span><span class="reserved">continue</span><span class="plain">;</span>
&lt;<span class="cwebmacro">Handle a line or column break, if there is one</span> <span class="cwebmacronumber">9.4</span>&gt;<span class="plain">;</span>
&lt;<span class="cwebmacro">Transcribe an ordinary word of the documentation</span> <span class="cwebmacronumber">9.5</span>&gt;<span class="plain">;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">close_I6_position</span><span class="plain"> == </span><span class="identifier">i</span><span class="plain">) </span><span class="identifier">WRITE</span><span class="plain">(</span><span class="string">" -)"</span><span class="plain">);</span>
<span class="plain">}</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">mid_example</span><span class="plain">) </span>&lt;<span class="cwebmacro">Close the previous example's text</span> <span class="cwebmacronumber">9.9</span>&gt;<span class="character">;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">example_which_is_open</span><span class="plain"> != </span><span class="constant">EDOC_FRAGMENT_ONLY</span><span class="plain">) </span>&lt;<span class="cwebmacro">Handle a paragraph break</span> <span class="cwebmacronumber">9.1</span>&gt;<span class="plain">;</span>
<span class="identifier">HTML_CLOSE</span><span class="plain">(</span><span class="string">"p"</span><span class="plain">);</span>
<span class="reserved">return</span><span class="plain"> </span><span class="identifier">example_count</span><span class="plain">;</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">The function HTML::Documentation::set_body_text is used in <a href="#SP7_1">&#167;7.1</a>, <a href="#SP7_2">&#167;7.2</a>, <a href="#SP9_6">&#167;9.6</a>, <a href="#SP9_7">&#167;9.7</a>.</p>
<p class="inwebparagraph"><a id="SP9_1"></a><b>&#167;9.1. Typesetting the standard matter. </b>A paragraph break might mean the end of displayed matter (and if so, then also
the end of any table being displayed). Otherwise, it just means a paragraph
break, and a chance to restore our tired variables.
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Handle a paragraph break</span> <span class="cwebmacronumber">9.1</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">mid_displayed_source_text</span><span class="plain">) {</span>
<span class="identifier">HTML::end_colour</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">mid_I7_table</span><span class="plain">) </span>&lt;<span class="cwebmacro">End I7 table in extension documentation</span> <span class="cwebmacronumber">9.1.1</span>&gt;<span class="plain">;</span>
<span class="identifier">HTML_CLOSE</span><span class="plain">(</span><span class="string">"blockquote"</span><span class="plain">);</span>
<span class="plain">} </span><span class="reserved">else</span><span class="plain"> {</span>
<span class="identifier">HTML_CLOSE</span><span class="plain">(</span><span class="string">"p"</span><span class="plain">);</span>
<span class="plain">}</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"\</span><span class="plain">n</span><span class="string">"</span><span class="plain">);</span>
<span class="identifier">HTML_OPEN</span><span class="plain">(</span><span class="string">"p"</span><span class="plain">);</span>
<span class="identifier">mid_displayed_source_text</span><span class="plain"> = </span><span class="identifier">FALSE</span><span class="plain">; </span><span class="identifier">mid_I7_table</span><span class="plain"> = </span><span class="identifier">FALSE</span><span class="plain">;</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP9">&#167;9</a> (twice).</p>
<p class="inwebparagraph"><a id="SP9_2"></a><b>&#167;9.2. </b>The indentation setting is made here because a tab anywhere else does
not mean a paragraph has been indented. Here <code class="display"><span class="extract">i</span></code> is at the number of the
first word after the paragraph break; the break character corresponding
to it is the one before that word, so describes the kind of whitespace
between the paragraph break and the first nonwhitespace of the new
paragraph.
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Determine indentation of new paragraph</span> <span class="cwebmacronumber">9.2</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="identifier">indentation</span><span class="plain"> = 0; </span><span class="reserved">if</span><span class="plain"> (</span><span class="identifier">Lexer::break_before</span><span class="plain">(</span><span class="identifier">i</span><span class="plain">) == </span><span class="character">'\</span><span class="plain">t</span><span class="character">'</span><span class="plain">) </span><span class="identifier">indentation</span><span class="plain"> = 1;</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP9">&#167;9</a>.</p>
<p class="inwebparagraph"><a id="SP9_3"></a><b>&#167;9.3. </b>Positions for paste icons in extension documentation are marked with
asterisk and colon:
</p>
<pre class="display">
<span class="plain">&lt;</span><span class="identifier">extension</span><span class="plain">-</span><span class="identifier">documentation</span><span class="plain">-</span><span class="identifier">paste</span><span class="plain">-</span><span class="identifier">marker</span><span class="plain">&gt; ::=</span>
<span class="plain">* : ...</span>
</pre>
<p class="inwebparagraph"></p>
<p class="inwebparagraph"><a id="SP9_4"></a><b>&#167;9.4. </b>Two lower-level sorts of breaks can also occur in the middle of a paragraph:
line breaks, indicated by newlines plus some tabs, and column breaks inside
I7 source tables, indicated by tabs. We have to deal with those before we
can move on to the subsequent word.
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Handle a line or column break, if there is one</span> <span class="cwebmacronumber">9.4</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">Lexer::indentation_level</span><span class="plain">(</span><span class="identifier">i</span><span class="plain">) &gt; 0) </span><span class="identifier">indentation</span><span class="plain"> = </span><span class="identifier">Lexer::indentation_level</span><span class="plain">(</span><span class="identifier">i</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">indentation</span><span class="plain"> &gt; 0) </span>&lt;<span class="cwebmacro">Handle the start of a line which is indented</span> <span class="cwebmacronumber">9.4.2</span>&gt;<span class="plain">;</span>
<span class="reserved">if</span><span class="plain"> (&lt;</span><span class="identifier">extension</span><span class="plain">-</span><span class="identifier">documentation</span><span class="plain">-</span><span class="identifier">paste</span><span class="plain">-</span><span class="identifier">marker</span><span class="plain">&gt;(</span><span class="identifier">Wordings::from</span><span class="plain">(</span><span class="identifier">W</span><span class="plain">, </span><span class="identifier">i</span><span class="plain">))) {</span>
<span class="identifier">wording</span><span class="plain"> </span><span class="identifier">W</span><span class="plain"> = </span><span class="identifier">GET_RW</span><span class="plain">(&lt;</span><span class="identifier">extension</span><span class="plain">-</span><span class="identifier">documentation</span><span class="plain">-</span><span class="identifier">paste</span><span class="plain">-</span><span class="identifier">marker</span><span class="plain">&gt;, 1);</span>
&lt;<span class="cwebmacro">Incorporate an icon linking to a Javascript function to paste the text which follows</span> <span class="cwebmacronumber">9.4.1</span>&gt;<span class="plain">;</span>
<span class="identifier">i</span><span class="plain">++; </span><span class="reserved">continue</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="identifier">indentation</span><span class="plain"> = 0;</span>
<span class="reserved">if</span><span class="plain"> ((</span><span class="identifier">mid_I7_table</span><span class="plain">) &amp;&amp; ((</span><span class="identifier">Lexer::break_before</span><span class="plain">(</span><span class="identifier">i</span><span class="plain">) == </span><span class="character">'\</span><span class="plain">t</span><span class="character">'</span><span class="plain">) || (</span><span class="identifier">Lexer::indentation_level</span><span class="plain">(</span><span class="identifier">i</span><span class="plain">) == 1))) {</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">row_of_table_is_empty</span><span class="plain"> == </span><span class="identifier">FALSE</span><span class="plain">)</span>
&lt;<span class="cwebmacro">End table cell for I7 table in extension documentation</span> <span class="cwebmacronumber">9.4.3</span>&gt;<span class="plain">;</span>
&lt;<span class="cwebmacro">Begin table cell for I7 table in extension documentation</span> <span class="cwebmacronumber">9.4.4</span>&gt;<span class="plain">;</span>
<span class="identifier">row_of_table_is_empty</span><span class="plain"> = </span><span class="identifier">FALSE</span><span class="plain">;</span>
<span class="plain">}</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP9">&#167;9</a>.</p>
<p class="inwebparagraph"><a id="SP9_5"></a><b>&#167;9.5. </b>See Javascript Pastes for further explanation of the general method here.
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Transcribe an ordinary word of the documentation</span> <span class="cwebmacronumber">9.5</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="identifier">wchar_t</span><span class="plain"> *</span><span class="identifier">p</span><span class="plain"> = </span><span class="identifier">Lexer::word_raw_text</span><span class="plain">(</span><span class="identifier">i</span><span class="plain">); </span><span class="reserved">int</span><span class="plain"> </span><span class="identifier">j</span><span class="plain">;</span>
<span class="reserved">if</span><span class="plain"> ((</span><span class="identifier">i</span><span class="plain">&gt;</span><span class="identifier">Wordings::first_wn</span><span class="plain">(</span><span class="identifier">W</span><span class="plain">))</span>
<span class="plain">&amp;&amp; ((</span><span class="identifier">p</span><span class="plain">[1] != 0) || (</span><span class="identifier">Lexer::is_punctuation</span><span class="plain">(</span><span class="identifier">p</span><span class="plain">[0]) == </span><span class="identifier">FALSE</span><span class="plain">)</span>
<span class="plain">|| (</span><span class="identifier">p</span><span class="plain">[0] == </span><span class="character">'('</span><span class="plain">) || (</span><span class="identifier">p</span><span class="plain">[0] == </span><span class="character">'{'</span><span class="plain">) || (</span><span class="identifier">p</span><span class="plain">[0] == </span><span class="character">'}'</span><span class="plain">))</span>
<span class="plain">&amp;&amp; (</span><span class="identifier">compare_word</span><span class="plain">(</span><span class="identifier">i</span><span class="plain">-1, </span><span class="identifier">OPENBRACKET_V</span><span class="plain">)==</span><span class="identifier">FALSE</span><span class="plain">))</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">" "</span><span class="plain">); </span> <span class="comment">restore normal spacing around punctuation</span>
<span class="reserved">for</span><span class="plain"> (</span><span class="identifier">j</span><span class="plain">=0; </span><span class="identifier">p</span><span class="plain">[</span><span class="identifier">j</span><span class="plain">]; </span><span class="identifier">j</span><span class="plain">++) </span><span class="functiontext">HTMLFiles::char_out</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="identifier">p</span><span class="plain">[</span><span class="identifier">j</span><span class="plain">]); </span> <span class="comment">set the actual word</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">Lexer::word</span><span class="plain">(</span><span class="identifier">i</span><span class="plain">) == </span><span class="identifier">OPENI6_V</span><span class="plain">) </span><span class="identifier">close_I6_position</span><span class="plain"> = </span><span class="identifier">i</span><span class="plain">+1; </span> <span class="comment">ensure I6 literals are closed</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP9">&#167;9</a>.</p>
<p class="inwebparagraph"><a id="SP9_4_1"></a><b>&#167;9.4.1. </b>A paste causes the same material to be set twice: once in the argument to
the Javascript paste function (which is passed to the application when the
user clicks on the paste icon, and thus ends up in the Source panel), and
once also in the HTML documentation. That's why the code here ranges forward
to see how far it should go (to the next paragraph break which is not followed
by further tabbed matter, or in other words, to the end of the display),
but does not advance <code class="display"><span class="extract">i</span></code> commensurately.
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Incorporate an icon linking to a Javascript function to paste the text which follows</span> <span class="cwebmacronumber">9.4.1</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">x</span><span class="plain"> = </span><span class="identifier">i</span><span class="plain">+2, </span><span class="identifier">y</span><span class="plain"> = </span><span class="identifier">Wordings::last_wn</span><span class="plain">(</span><span class="identifier">W</span><span class="plain">), </span><span class="identifier">j</span><span class="plain">;</span>
<span class="reserved">for</span><span class="plain"> (</span><span class="identifier">j</span><span class="plain">=</span><span class="identifier">x</span><span class="plain">; </span><span class="identifier">j</span><span class="plain">&lt;=</span><span class="identifier">y</span><span class="plain">; </span><span class="identifier">j</span><span class="plain">++) </span> <span class="comment">first find the end of the quoted passage</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">Lexer::word</span><span class="plain">(</span><span class="identifier">j</span><span class="plain">) == </span><span class="identifier">PARBREAK_V</span><span class="plain">) {</span>
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">possible_end</span><span class="plain"> = </span><span class="identifier">j</span><span class="plain">-1;</span>
<span class="reserved">while</span><span class="plain"> (</span><span class="identifier">Lexer::word</span><span class="plain">(</span><span class="identifier">j</span><span class="plain">) == </span><span class="identifier">PARBREAK_V</span><span class="plain">) </span><span class="identifier">j</span><span class="plain">++;</span>
<span class="reserved">if</span><span class="plain"> ((</span><span class="identifier">j</span><span class="plain">&lt;</span><span class="identifier">y</span><span class="plain">) &amp;&amp; ((</span><span class="identifier">Lexer::break_before</span><span class="plain">(</span><span class="identifier">j</span><span class="plain">) == </span><span class="character">'\</span><span class="plain">t</span><span class="character">'</span><span class="plain">) || (</span><span class="identifier">Lexer::indentation_level</span><span class="plain">(</span><span class="identifier">j</span><span class="plain">) &gt; 0))) </span><span class="reserved">continue</span><span class="plain">;</span>
<span class="identifier">y</span><span class="plain"> = </span><span class="identifier">possible_end</span><span class="plain">; </span><span class="reserved">break</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="functiontext">HTML::Javascript::paste_W</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="identifier">Wordings::new</span><span class="plain">(</span><span class="identifier">x</span><span class="plain">, </span><span class="identifier">y</span><span class="plain">));</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP9_4">&#167;9.4</a>.</p>
<p class="inwebparagraph"><a id="SP9_4_2"></a><b>&#167;9.4.2. </b>The first step of indentation is handled using the <code class="display"><span class="extract">&lt;blockquote&gt;</span></code> tag;
within that, further tab stops are simulated by printing a row of four
non-breaking spaces for each indentation level above 1. A paragraph
of indented (i.e., display matter) beginning with the word "Table" is
taken to be an I7 table, and we remember that the next line break will
take us past the titling line and into the table entries, which we will
need to achieve with an HTML <code class="display"><span class="extract">&lt;table&gt;</span></code>.
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Handle the start of a line which is indented</span> <span class="cwebmacronumber">9.4.2</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="reserved">int</span><span class="plain"> </span><span class="identifier">j</span><span class="plain">;</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">mid_displayed_source_text</span><span class="plain">) {</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">start_table_next_line</span><span class="plain">) {</span>
<span class="identifier">start_table_next_line</span><span class="plain"> = </span><span class="identifier">FALSE</span><span class="plain">;</span>
<span class="identifier">mid_I7_table</span><span class="plain"> = </span><span class="identifier">TRUE</span><span class="plain">;</span>
&lt;<span class="cwebmacro">Begin I7 table in extension documentation</span> <span class="cwebmacronumber">9.4.2.1</span>&gt;<span class="plain">;</span>
<span class="plain">} </span><span class="reserved">else</span><span class="plain"> {</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">mid_I7_table</span><span class="plain">) </span>&lt;<span class="cwebmacro">Begin new row of I7 table in extension documentation</span> <span class="cwebmacronumber">9.4.2.2</span>&gt;
<span class="reserved">else</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="plain">}</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">mid_I7_table</span><span class="plain">) </span><span class="identifier">row_of_table_is_empty</span><span class="plain"> = </span><span class="identifier">TRUE</span><span class="plain">;</span>
<span class="plain">} </span><span class="reserved">else</span><span class="plain"> {</span>
<span class="identifier">HTML_OPEN</span><span class="plain">(</span><span class="string">"blockquote"</span><span class="plain">);</span>
<span class="identifier">HTML::begin_colour</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"000080"</span><span class="plain">);</span>
<span class="identifier">mid_displayed_source_text</span><span class="plain"> = </span><span class="identifier">TRUE</span><span class="plain">;</span>
<span class="reserved">if</span><span class="plain"> (&lt;</span><span class="identifier">table</span><span class="plain">-</span><span class="identifier">sentence</span><span class="plain">&gt;(</span><span class="identifier">Wordings::from</span><span class="plain">(</span><span class="identifier">W</span><span class="plain">, </span><span class="identifier">i</span><span class="plain">)))</span>
<span class="identifier">start_table_next_line</span><span class="plain"> = </span><span class="identifier">TRUE</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="identifier">indentation</span><span class="plain">--;</span>
<span class="reserved">for</span><span class="plain"> (</span><span class="identifier">j</span><span class="plain">=0; </span><span class="identifier">j</span><span class="plain">&lt;</span><span class="identifier">indentation</span><span class="plain">; </span><span class="identifier">j</span><span class="plain">++) </span><span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;"</span><span class="plain">);</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP9_4">&#167;9.4</a>.</p>
<p class="inwebparagraph"><a id="SP9_6"></a><b>&#167;9.6. Typesetting the headings. </b>That is thankfully all for the tormented logic of all those changes of state:
from here to the rest of the section, all we do is to generate pretty HTML,
and without altering any variables or causing any side-effects at all.
First, the headings. Recall that heading number <code class="display"><span class="extract">N</span></code> is required to be at
anchor <code class="display"><span class="extract">#docsecN</span></code>.
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Typeset the heading of this chapter or section</span> <span class="cwebmacronumber">9.6</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="identifier">HTML_OPEN</span><span class="plain">(</span><span class="string">"p"</span><span class="plain">);</span>
<span class="identifier">HTML_TAG_WITH</span><span class="plain">(</span><span class="string">"a"</span><span class="plain">, </span><span class="string">"name=docsec%d"</span><span class="plain">, </span><span class="identifier">heading_count</span><span class="plain">);</span>
<span class="identifier">HTML_OPEN</span><span class="plain">(</span><span class="string">"b"</span><span class="plain">);</span>
<span class="reserved">switch</span><span class="plain"> (</span><span class="identifier">edhl</span><span class="plain">) {</span>
<span class="reserved">case</span><span class="plain"> 1:</span>
<span class="identifier">HTML::begin_colour</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"800000"</span><span class="plain">);</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"Chapter %d: "</span><span class="plain">, </span><span class="identifier">chapter_count</span><span class="plain">);</span>
<span class="reserved">break</span><span class="plain">;</span>
<span class="reserved">case</span><span class="plain"> 2:</span>
<span class="identifier">HTML::begin_colour</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"000000"</span><span class="plain">);</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"Section "</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">chapter_count</span><span class="plain"> &gt; 0) </span><span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"%d."</span><span class="plain">, </span><span class="identifier">chapter_count</span><span class="plain">);</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"%d: "</span><span class="plain">, </span><span class="identifier">section_count</span><span class="plain">);</span>
<span class="reserved">break</span><span class="plain">;</span>
<span class="plain">}</span>
<span class="functiontext">HTML::Documentation::set_body_text</span><span class="plain">(</span><span class="identifier">NW</span><span class="plain">, </span><span class="identifier">OUT</span><span class="plain">, </span><span class="constant">EDOC_FRAGMENT_ONLY</span><span class="plain">, </span><span class="identifier">NULL</span><span class="plain">);</span>
<span class="identifier">HTML::end_colour</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">"b"</span><span class="plain">);</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP9">&#167;9</a>.</p>
<p class="inwebparagraph"><a id="SP9_7"></a><b>&#167;9.7. </b>An example is set with a two-table header, and followed optionally by a
table of its inset copy, shaded to distinguish it from the rest of the
page. The heading is constructed with a main table of one row of two cells,
in the following section. The left-hand cell then contains a further table,
in the next section.
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Typeset the heading of this example</span> <span class="cwebmacronumber">9.7</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="identifier">HTML_OPEN</span><span class="plain">(</span><span class="string">"hr"</span><span class="plain">); </span> <span class="comment">rule a line before the example heading</span>
<span class="identifier">HTML_OPEN</span><span class="plain">(</span><span class="string">"p"</span><span class="plain">);</span>
<span class="identifier">HTML_OPEN_WITH</span><span class="plain">(</span><span class="string">"a"</span><span class="plain">, </span><span class="string">"name=eg%d"</span><span class="plain">, </span><span class="identifier">example_count</span><span class="plain">); </span> <span class="comment">provide the anchor point</span>
<span class="identifier">HTML::begin_plain_html_table</span><span class="plain">(</span><span class="identifier">OUT</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="comment">Left hand cell: the oval icon</span>
<span class="identifier">HTML_OPEN_WITH</span><span class="plain">(</span><span class="string">"td"</span><span class="plain">, </span><span class="string">"halign=\</span><span class="plain">"</span><span class="string">left\</span><span class="plain">"</span><span class="string"> valign=\</span><span class="plain">"</span><span class="string">top\</span><span class="plain">"</span><span class="string"> cellpadding=0 cellspacing=0 width=38px"</span><span class="plain">);</span>
&lt;<span class="cwebmacro">Typeset the lettered oval example icon</span> <span class="cwebmacronumber">9.7.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="comment">Right hand cell: the asterisks and title, with rubric underneath</span>
<span class="identifier">HTML_OPEN_WITH</span><span class="plain">(</span><span class="string">"td"</span><span class="plain">, </span><span class="string">"cellpadding=0 cellspacing=0 halign=\</span><span class="plain">"</span><span class="string">left\</span><span class="plain">"</span><span class="string"> valign=\</span><span class="plain">"</span><span class="string">top\</span><span class="plain">"</span><span class="string">"</span><span class="plain">);</span>
&lt;<span class="cwebmacro">Incorporate link to the example opened up</span> <span class="cwebmacronumber">9.7.2</span>&gt;<span class="plain">;</span>
<span class="reserved">while</span><span class="plain"> (</span><span class="identifier">asterisks</span><span class="plain">-- &gt; 0)</span>
<span class="identifier">HTML_TAG_WITH</span><span class="plain">(</span><span class="string">"img"</span><span class="plain">, </span><span class="string">"border=\</span><span class="plain">"</span><span class="string">0\</span><span class="plain">"</span><span class="string"> src='inform:/doc_images/asterisk.png'"</span><span class="plain">);</span>
<span class="identifier">HTML_OPEN</span><span class="plain">(</span><span class="string">"b"</span><span class="plain">);</span>
<span class="identifier">HTML::begin_colour</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"505050"</span><span class="plain">);</span>
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"&amp;nbsp;Example&amp;nbsp;"</span><span class="plain">);</span>
<span class="identifier">HTML::end_colour</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">);</span>
<span class="identifier">HTML::begin_colour</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"000000"</span><span class="plain">);</span>
<span class="functiontext">HTML::Documentation::set_body_text</span><span class="plain">(</span><span class="identifier">NW</span><span class="plain">, </span><span class="identifier">OUT</span><span class="plain">, </span><span class="constant">EDOC_FRAGMENT_ONLY</span><span class="plain">, </span><span class="identifier">base_leafname</span><span class="plain">);</span>
<span class="identifier">HTML::end_colour</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">"b"</span><span class="plain">);</span>
<span class="identifier">HTML_CLOSE</span><span class="plain">(</span><span class="string">"a"</span><span class="plain">); </span> <span class="comment">end the textual link</span>
<span class="identifier">HTML_TAG</span><span class="plain">(</span><span class="string">"br"</span><span class="plain">);</span>
<span class="functiontext">HTML::Documentation::set_body_text</span><span class="plain">(</span><span class="identifier">RUBW</span><span class="plain">, </span><span class="identifier">OUT</span><span class="plain">, </span><span class="constant">EDOC_FRAGMENT_ONLY</span><span class="plain">, </span><span class="identifier">base_leafname</span><span class="plain">);</span>
<span class="identifier">HTML_OPEN</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="identifier">HTML_CLOSE</span><span class="plain">(</span><span class="string">"tr"</span><span class="plain">);</span>
<span class="identifier">HTML::end_html_table</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">);</span>
<span class="identifier">HTML_OPEN</span><span class="plain">(</span><span class="string">"p"</span><span class="plain">);</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP9">&#167;9</a>.</p>
<p class="inwebparagraph"><a id="SP9_7_1"></a><b>&#167;9.7.1. </b>The little oval icon with its superimposed boldface letter is much harder to
get right on all browsers than it looks, and the following is the result of
some pretty grim experimentation. Basically, we make a tight, borderless,
one-cell-in-one-row table, use CSS to make a transparent PNG image of an oval
the background image for the table, then put a boldface letter in the centre
of its one and only cell. (Things were even worse when IE6 for Windows still
had its infamous PNG transparency bug.)
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Typeset the lettered oval example icon</span> <span class="cwebmacronumber">9.7.1</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="identifier">HTML::begin_plain_html_table</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">);</span>
<span class="identifier">HTML_OPEN_WITH</span><span class="plain">(</span><span class="string">"tr"</span><span class="plain">, </span><span class="string">"class=\</span><span class="plain">"</span><span class="string">oval\</span><span class="plain">"</span><span class="string">"</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">"width=38px height=30px align=\</span><span class="plain">"</span><span class="string">left\</span><span class="plain">"</span><span class="string"> valign=\</span><span class="plain">"</span><span class="string">center\</span><span class="plain">"</span><span class="string">"</span><span class="plain">);</span>
&lt;<span class="cwebmacro">Incorporate link to the example opened up</span> <span class="cwebmacronumber">9.7.2</span>&gt;<span class="plain">;</span>
<span class="identifier">HTML_OPEN_WITH</span><span class="plain">(</span><span class="string">"div"</span><span class="plain">,</span>
<span class="string">"class=\</span><span class="plain">"</span><span class="string">paragraph Body\</span><span class="plain">"</span><span class="string"> style=\</span><span class="plain">"</span><span class="string">line-height: 1px; margin-bottom: 0px; "</span>
<span class="string">"margin-top: 0px; padding-bottom: 0pt; padding-top: 0px; text-align: center; "</span>
<span class="string">"color: #202020; font-size: 14px; line-height: 1px;\</span><span class="plain">"</span><span class="string">"</span><span class="plain">);</span>
<span class="identifier">HTML_OPEN</span><span class="plain">(</span><span class="string">"b"</span><span class="plain">);</span>
<span class="identifier">PUT</span><span class="plain">(</span><span class="character">'A'</span><span class="plain"> + </span><span class="identifier">example_count</span><span class="plain"> - 1);</span>
<span class="identifier">HTML_CLOSE</span><span class="plain">(</span><span class="string">"b"</span><span class="plain">);</span>
<span class="identifier">HTML_CLOSE</span><span class="plain">(</span><span class="string">"div"</span><span class="plain">);</span>
<span class="identifier">HTML_CLOSE</span><span class="plain">(</span><span class="string">"a"</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="identifier">HTML_CLOSE</span><span class="plain">(</span><span class="string">"tr"</span><span class="plain">);</span>
<span class="identifier">HTML::end_html_table</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">);</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP9_7">&#167;9.7</a>.</p>
<p class="inwebparagraph"><a id="SP9_7_2"></a><b>&#167;9.7.2. </b>Clicking on the example banner opens it up, if it's currently closed, or
closes it up, if it's currently open.
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Incorporate link to the example opened up</span> <span class="cwebmacronumber">9.7.2</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="identifier">TEMPORARY_TEXT</span><span class="plain">(</span><span class="identifier">url</span><span class="plain">);</span>
<span class="identifier">WRITE_TO</span><span class="plain">(</span><span class="identifier">url</span><span class="plain">, </span><span class="string">"href=\</span><span class="plain">"</span><span class="string">"</span><span class="plain">);</span>
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">example_count</span><span class="plain"> == </span><span class="identifier">example_which_is_open</span><span class="plain">) </span> <span class="comment">this example currently open</span>
<span class="functiontext">HTML::Documentation::href_of_example</span><span class="plain">(</span><span class="identifier">url</span><span class="plain">, </span><span class="identifier">base_leafname</span><span class="plain">, </span><span class="constant">EDOC_ALL_EXAMPLES_CLOSED</span><span class="plain">, </span><span class="identifier">example_count</span><span class="plain">);</span>
<span class="reserved">else</span><span class="plain"> </span> <span class="comment">this example not yet open</span>
<span class="functiontext">HTML::Documentation::href_of_example</span><span class="plain">(</span><span class="identifier">url</span><span class="plain">, </span><span class="identifier">base_leafname</span><span class="plain">, </span><span class="identifier">example_count</span><span class="plain">, </span><span class="identifier">example_count</span><span class="plain">);</span>
<span class="identifier">WRITE_TO</span><span class="plain">(</span><span class="identifier">url</span><span class="plain">, </span><span class="string">"\</span><span class="plain">"</span><span class="string"> style=\</span><span class="plain">"</span><span class="string">text-decoration: none\</span><span class="plain">"</span><span class="string">"</span><span class="plain">);</span>
<span class="identifier">HTML_OPEN_WITH</span><span class="plain">(</span><span class="string">"a"</span><span class="plain">, </span><span class="string">"%S"</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">url</span><span class="plain">);</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP9_7">&#167;9.7</a>, <a href="#SP9_7_1">&#167;9.7.1</a>.</p>
<p class="inwebparagraph"><a id="SP9_4_2_1"></a><b>&#167;9.4.2.1. Typesetting I7 tables in displayed source text. </b>Unsurprisingly, I7 tables are set (after their titling lines) as HTML tables,
and this is fiddly but elementary in the usual way of HTML tables:
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Begin I7 table in extension documentation</span> <span class="cwebmacronumber">9.4.2.1</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="identifier">HTML::end_colour</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">HTML::begin_plain_html_table</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">);</span>
<span class="identifier">HTML::first_html_column</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, 0);</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP9_4_2">&#167;9.4.2</a>.</p>
<p class="inwebparagraph"><a id="SP9_4_3"></a><b>&#167;9.4.3. </b>Drinka.
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">End table cell for I7 table in extension documentation</span> <span class="cwebmacronumber">9.4.3</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="identifier">HTML::end_colour</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">);</span>
<span class="identifier">HTML::next_html_column</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, 0);</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP9_4">&#167;9.4</a>.</p>
<p class="inwebparagraph"><a id="SP9_4_4"></a><b>&#167;9.4.4. </b>Pinta.
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Begin table cell for I7 table in extension documentation</span> <span class="cwebmacronumber">9.4.4</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="identifier">HTML::begin_colour</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="identifier">I</span><span class="string">"000080"</span><span class="plain">);</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP9_4">&#167;9.4</a>.</p>
<p class="inwebparagraph"><a id="SP9_4_2_2"></a><b>&#167;9.4.2.2. </b>Milka.
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Begin new row of I7 table in extension documentation</span> <span class="cwebmacronumber">9.4.2.2</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="identifier">HTML::end_html_row</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">);</span>
<span class="identifier">HTML::first_html_column</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, 0);</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP9_4_2">&#167;9.4.2</a>.</p>
<p class="inwebparagraph"><a id="SP9_1_1"></a><b>&#167;9.1.1. </b>Day.
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">End I7 table in extension documentation</span> <span class="cwebmacronumber">9.1.1</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="identifier">HTML::end_html_row</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">);</span>
<span class="identifier">HTML::end_html_table</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">);</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP9_1">&#167;9.1</a>.</p>
<p class="inwebparagraph"><a id="SP9_8"></a><b>&#167;9.8. Typesetting the body of an example. </b>This is done just the way all other extension documentation material is
handled, except that it is inside an inset box: which is provided by
a shaded HTML table, containing just one row, which contains just one
cell. Here the inset table begins:
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Open the new example's text</span> <span class="cwebmacronumber">9.8</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="identifier">HTML::begin_html_table</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, </span><span class="string">"#f0f0f0"</span><span class="plain">, </span><span class="identifier">TRUE</span><span class="plain">, 0, 0, 0, 0, 0);</span>
<span class="identifier">HTML::first_html_column</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">, 0);</span>
<span class="identifier">HTML_OPEN</span><span class="plain">(</span><span class="string">"p"</span><span class="plain">);</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP9">&#167;9</a>.</p>
<p class="inwebparagraph"><a id="SP9_9"></a><b>&#167;9.9. </b>And here the inset table ends:
</p>
<p class="macrodefinition"><code class="display">
&lt;<span class="cwebmacrodefn">Close the previous example's text</span> <span class="cwebmacronumber">9.9</span>&gt; =
</code></p>
<pre class="displaydefn">
<span class="identifier">HTML::end_html_row</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">);</span>
<span class="identifier">HTML::end_html_table</span><span class="plain">(</span><span class="identifier">OUT</span><span class="plain">);</span>
<span class="identifier">HTML_OPEN</span><span class="plain">(</span><span class="string">"p"</span><span class="plain">);</span>
</pre>
<p class="inwebparagraph"></p>
<p class="endnote">This code is used in <a href="#SP9">&#167;9</a> (twice).</p>
<hr class="tocbar">
<ul class="toc"><li><a href="2-jp.html">Back to 'Javascript Pastes'</a></li><li><i>(This section ends Chapter 2: HTML.)</i></li></ul><hr class="tocbar">
<!--End of weave-->
</main>
</body>
</html>
Reference in a new issue View git blame Copy permalink