mirror of
https://github.com/ganelson/inform.git
synced 2024-07-05 08:34:22 +03:00
938 lines
97 KiB
HTML
938 lines
97 KiB
HTML
<!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">§2. Links and leafnames</a></li><li><a href="#SP7">§7. The table of contents</a></li><li><a href="#SP9">§9. Setting the body text</a></li><li><a href="#SP9_1">§9.1. Typesetting the standard matter</a></li><li><a href="#SP9_6">§9.6. Typesetting the headings</a></li><li><a href="#SP9_4_2_1">§9.4.2.1. Typesetting I7 tables in displayed source text</a></li><li><a href="#SP9_8">§9.8. Typesetting the body of an example</a></li></ul><hr class="tocbar">
|
|
|
|
<p class="inwebparagraph"><a id="SP1"></a><b>§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>§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"><</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">)) &&</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"> > 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"> > 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">§7.2</a>, <a href="#SP9_7_2">§9.7.2</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP3"></a><b>§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"><</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">> ::=</span>
|
|
<span class="identifier">chapter</span><span class="plain"> : ... | ==> 1</span>
|
|
<span class="identifier">section</span><span class="plain"> : ... ==> 2</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="inwebparagraph"><a id="SP4"></a><b>§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"> (<</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">>(</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">) > 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"> = <<</span><span class="identifier">r</span><span class="plain">>>;</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"><=</span><span class="identifier">Wordings::last_wn</span><span class="plain">(</span><span class="identifier">W</span><span class="plain">)) && (</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">§7</a>, <a href="#SP9">§9</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP5"></a><b>§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"><</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">> ::=</span>
|
|
<span class="identifier">example</span><span class="plain"> : <</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">> ... - ... | ==> </span><span class="identifier">R</span><span class="plain">[1]</span>
|
|
<span class="identifier">example</span><span class="plain"> : ... - ... ==> 0</span>
|
|
|
|
<span class="plain"><</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">> ::=</span>
|
|
<span class="plain">* | ==> 1</span>
|
|
<span class="plain">** | ==> 2</span>
|
|
<span class="plain">\*** | ==> 3</span>
|
|
<span class="plain">**** ==> 4</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="inwebparagraph"><a id="SP6"></a><b>§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">) > 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"> (<</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">>(</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">(<</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">>, 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">(<</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">>, 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"> <= </span><span class="identifier">Wordings::last_wn</span><span class="plain">(</span><span class="identifier">W</span><span class="plain">)) && ((</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"> >= </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"> = <<</span><span class="identifier">r</span><span class="plain">>>; *</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">§7</a>, <a href="#SP9">§9</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP7"></a><b>§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">></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">), &</span><span class="identifier">edhl</span><span class="plain">, &</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"> > 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>
|
|
<<span class="cwebmacro">Typeset the table of contents entry for this heading</span> <span class="cwebmacronumber">7.1</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">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"> > 0) && (</span><span class="identifier">example_count</span><span class="plain"> < 26) &&</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">), &</span><span class="identifier">asterisks</span><span class="plain">, &</span><span class="identifier">NW</span><span class="plain">, &</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>
|
|
<<span class="cwebmacro">Typeset the table of contents entry for this example</span> <span class="cwebmacronumber">7.2</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="plain">}</span>
|
|
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">heading_count</span><span class="plain"> > 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>§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">
|
|
<<span class="cwebmacrodefn">Typeset the table of contents entry for this heading</span> <span class="cwebmacronumber">7.1</span>> =
|
|
</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"> > 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">"&nbsp;&nbsp;&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"> > 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">§7</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP7_2"></a><b>§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">
|
|
<<span class="cwebmacrodefn">Typeset the table of contents entry for this example</span> <span class="cwebmacronumber">7.2</span>> =
|
|
</code></p>
|
|
|
|
|
|
<pre class="displaydefn">
|
|
<span class="identifier">WRITE</span><span class="plain">(</span><span class="string">"&nbsp;&nbsp;&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">§7</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP8"></a><b>§8. </b></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain"><</span><span class="identifier">table</span><span class="plain">-</span><span class="identifier">sentence</span><span class="plain">> ::=</span>
|
|
<span class="plain"><</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">> </span><span class="identifier">table</span><span class="plain"> ...</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="inwebparagraph"><a id="SP9"></a><b>§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>
|
|
<<span class="cwebmacro">Handle a paragraph break</span> <span class="cwebmacronumber">9.1</span>><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">></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>
|
|
<<span class="cwebmacro">Determine indentation of new paragraph</span> <span class="cwebmacronumber">9.2</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">), &</span><span class="identifier">edhl</span><span class="plain">, &</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"> > 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>
|
|
<<span class="cwebmacro">Typeset the heading of this chapter or section</span> <span class="cwebmacronumber">9.6</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">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"> < 26) && (</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">), &</span><span class="identifier">asterisks</span><span class="plain">, &</span><span class="identifier">NW</span><span class="plain">, &</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><<span class="cwebmacro">Close the previous example's text</span> <span class="cwebmacronumber">9.9</span>><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>
|
|
<<span class="cwebmacro">Typeset the heading of this example</span> <span class="cwebmacronumber">9.7</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="cwebmacro">Open the new example's text</span> <span class="cwebmacronumber">9.8</span>><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>
|
|
|
|
<<span class="cwebmacro">Handle a line or column break, if there is one</span> <span class="cwebmacronumber">9.4</span>><span class="plain">;</span>
|
|
<<span class="cwebmacro">Transcribe an ordinary word of the documentation</span> <span class="cwebmacronumber">9.5</span>><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><<span class="cwebmacro">Close the previous example's text</span> <span class="cwebmacronumber">9.9</span>><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><<span class="cwebmacro">Handle a paragraph break</span> <span class="cwebmacronumber">9.1</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="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">§7.1</a>, <a href="#SP7_2">§7.2</a>, <a href="#SP9_6">§9.6</a>, <a href="#SP9_7">§9.7</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP9_1"></a><b>§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">
|
|
<<span class="cwebmacrodefn">Handle a paragraph break</span> <span class="cwebmacronumber">9.1</span>> =
|
|
</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><<span class="cwebmacro">End I7 table in extension documentation</span> <span class="cwebmacronumber">9.1.1</span>><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">§9</a> (twice).</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP9_2"></a><b>§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">
|
|
<<span class="cwebmacrodefn">Determine indentation of new paragraph</span> <span class="cwebmacronumber">9.2</span>> =
|
|
</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">§9</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP9_3"></a><b>§9.3. </b>Positions for paste icons in extension documentation are marked with
|
|
asterisk and colon:
|
|
</p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain"><</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">> ::=</span>
|
|
<span class="plain">* : ...</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="inwebparagraph"><a id="SP9_4"></a><b>§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">
|
|
<<span class="cwebmacrodefn">Handle a line or column break, if there is one</span> <span class="cwebmacronumber">9.4</span>> =
|
|
</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">) > 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"> > 0) </span><<span class="cwebmacro">Handle the start of a line which is indented</span> <span class="cwebmacronumber">9.4.2</span>><span class="plain">;</span>
|
|
<span class="reserved">if</span><span class="plain"> (<</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">>(</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">(<</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">>, 1);</span>
|
|
<<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>><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">) && ((</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>
|
|
<<span class="cwebmacro">End table cell for I7 table in extension documentation</span> <span class="cwebmacronumber">9.4.3</span>><span class="plain">;</span>
|
|
<<span class="cwebmacro">Begin table cell for I7 table in extension documentation</span> <span class="cwebmacronumber">9.4.4</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="plain">}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="endnote">This code is used in <a href="#SP9">§9</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP9_5"></a><b>§9.5. </b>See Javascript Pastes for further explanation of the general method here.
|
|
</p>
|
|
|
|
|
|
<p class="macrodefinition"><code class="display">
|
|
<<span class="cwebmacrodefn">Transcribe an ordinary word of the documentation</span> <span class="cwebmacronumber">9.5</span>> =
|
|
</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">></span><span class="identifier">Wordings::first_wn</span><span class="plain">(</span><span class="identifier">W</span><span class="plain">))</span>
|
|
<span class="plain">&& ((</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">&& (</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">§9</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP9_4_1"></a><b>§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">
|
|
<<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>> =
|
|
</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"><=</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"><</span><span class="identifier">y</span><span class="plain">) && ((</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">) > 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">§9.4</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP9_4_2"></a><b>§9.4.2. </b>The first step of indentation is handled using the <code class="display"><span class="extract"><blockquote></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"><table></span></code>.
|
|
</p>
|
|
|
|
|
|
<p class="macrodefinition"><code class="display">
|
|
<<span class="cwebmacrodefn">Handle the start of a line which is indented</span> <span class="cwebmacronumber">9.4.2</span>> =
|
|
</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>
|
|
<<span class="cwebmacro">Begin I7 table in extension documentation</span> <span class="cwebmacronumber">9.4.2.1</span>><span class="plain">;</span>
|
|
<span class="plain">} </span><span class="reserved">else</span><span class="plain"> {</span>
|
|
<span class="reserved">if</span><span class="plain"> (</span><span class="identifier">mid_I7_table</span><span class="plain">) </span><<span class="cwebmacro">Begin new row of I7 table in extension documentation</span> <span class="cwebmacronumber">9.4.2.2</span>>
|
|
<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"> (<</span><span class="identifier">table</span><span class="plain">-</span><span class="identifier">sentence</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">)))</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"><</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">"&nbsp;&nbsp;&nbsp;&nbsp;"</span><span class="plain">);</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="endnote">This code is used in <a href="#SP9_4">§9.4</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP9_6"></a><b>§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">
|
|
<<span class="cwebmacrodefn">Typeset the heading of this chapter or section</span> <span class="cwebmacronumber">9.6</span>> =
|
|
</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"> > 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">§9</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP9_7"></a><b>§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">
|
|
<<span class="cwebmacrodefn">Typeset the heading of this example</span> <span class="cwebmacronumber">9.7</span>> =
|
|
</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>
|
|
<<span class="cwebmacro">Typeset the lettered oval example icon</span> <span class="cwebmacronumber">9.7.1</span>><span class="plain">;</span>
|
|
<span class="identifier">HTML_CLOSE</span><span class="plain">(</span><span class="string">"td"</span><span class="plain">);</span>
|
|
|
|
<span class="comment">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>
|
|
<<span class="cwebmacro">Incorporate link to the example opened up</span> <span class="cwebmacronumber">9.7.2</span>><span class="plain">;</span>
|
|
<span class="reserved">while</span><span class="plain"> (</span><span class="identifier">asterisks</span><span class="plain">-- > 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">"&nbsp;Example&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">§9</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP9_7_1"></a><b>§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">
|
|
<<span class="cwebmacrodefn">Typeset the lettered oval example icon</span> <span class="cwebmacronumber">9.7.1</span>> =
|
|
</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>
|
|
<<span class="cwebmacro">Incorporate link to the example opened up</span> <span class="cwebmacronumber">9.7.2</span>><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">§9.7</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP9_7_2"></a><b>§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">
|
|
<<span class="cwebmacrodefn">Incorporate link to the example opened up</span> <span class="cwebmacronumber">9.7.2</span>> =
|
|
</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">§9.7</a>, <a href="#SP9_7_1">§9.7.1</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP9_4_2_1"></a><b>§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">
|
|
<<span class="cwebmacrodefn">Begin I7 table in extension documentation</span> <span class="cwebmacronumber">9.4.2.1</span>> =
|
|
</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">§9.4.2</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP9_4_3"></a><b>§9.4.3. </b>Drinka.
|
|
</p>
|
|
|
|
|
|
<p class="macrodefinition"><code class="display">
|
|
<<span class="cwebmacrodefn">End table cell for I7 table in extension documentation</span> <span class="cwebmacronumber">9.4.3</span>> =
|
|
</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">§9.4</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP9_4_4"></a><b>§9.4.4. </b>Pinta.
|
|
</p>
|
|
|
|
|
|
<p class="macrodefinition"><code class="display">
|
|
<<span class="cwebmacrodefn">Begin table cell for I7 table in extension documentation</span> <span class="cwebmacronumber">9.4.4</span>> =
|
|
</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">§9.4</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP9_4_2_2"></a><b>§9.4.2.2. </b>Milka.
|
|
</p>
|
|
|
|
|
|
<p class="macrodefinition"><code class="display">
|
|
<<span class="cwebmacrodefn">Begin new row of I7 table in extension documentation</span> <span class="cwebmacronumber">9.4.2.2</span>> =
|
|
</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">§9.4.2</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP9_1_1"></a><b>§9.1.1. </b>Day.
|
|
</p>
|
|
|
|
|
|
<p class="macrodefinition"><code class="display">
|
|
<<span class="cwebmacrodefn">End I7 table in extension documentation</span> <span class="cwebmacronumber">9.1.1</span>> =
|
|
</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">§9.1</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP9_8"></a><b>§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">
|
|
<<span class="cwebmacrodefn">Open the new example's text</span> <span class="cwebmacronumber">9.8</span>> =
|
|
</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">§9</a>.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP9_9"></a><b>§9.9. </b>And here the inset table ends:
|
|
</p>
|
|
|
|
|
|
<p class="macrodefinition"><code class="display">
|
|
<<span class="cwebmacrodefn">Close the previous example's text</span> <span class="cwebmacronumber">9.9</span>> =
|
|
</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">§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>
|
|
|