1
0
Fork 0
mirror of https://github.com/ganelson/inform.git synced 2024-07-05 08:34:22 +03:00
inform7/docs/html-module/2-hf.html

412 lines
60 KiB
HTML
Raw Normal View History

2020-02-27 13:18:25 +02:00
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
2020-04-14 19:56:54 +03:00
<title>HTML Files</title>
2020-05-03 03:20:55 +03:00
<link href="../docs-assets/Breadcrumbs.css" rel="stylesheet" rev="stylesheet" type="text/css">
2020-03-19 02:11:25 +02:00
<meta name="viewport" content="width=device-width initial-scale=1">
2020-02-27 13:18:25 +02:00
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="Content-Language" content="en-gb">
2020-05-03 03:01:21 +03:00
2020-05-03 03:20:55 +03:00
<link href="../docs-assets/Contents.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Progress.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Navigation.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Fonts.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Base.css" rel="stylesheet" rev="stylesheet" type="text/css">
2020-05-03 03:01:21 +03:00
<script>
function togglePopup(material_id) {
var popup = document.getElementById(material_id);
popup.classList.toggle("show");
}
</script>
2020-05-03 03:20:55 +03:00
<link href="../docs-assets/Popups.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
2020-04-14 19:56:54 +03:00
2020-02-27 13:18:25 +02:00
</head>
2020-05-03 03:01:21 +03:00
<body class="commentary-font">
2020-03-19 02:11:25 +02:00
<nav role="navigation">
2020-04-14 19:56:54 +03:00
<h1><a href="../index.html">
2020-05-03 18:34:53 +03:00
<img src="../docs-assets/Inform.png" height=72">
2020-04-14 19:56:54 +03:00
</a></h1>
<ul><li><a href="../compiler.html">compiler tools</a></li>
2020-03-19 02:11:25 +02:00
<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>
2020-04-14 19:56:54 +03:00
</ul><h2>Compiler Webs</h2><ul>
2020-03-19 02:11:25 +02:00
<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>
2020-04-14 19:56:54 +03:00
</ul><h2>Inbuild Modules</h2><ul>
<li><a href="../supervisor-module/index.html">supervisor</a></li>
</ul><h2>Inform7 Modules</h2><ul>
2020-03-19 02:11:25 +02:00
<li><a href="../core-module/index.html">core</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>
2020-04-14 19:56:54 +03:00
<li><a href="../problems-module/index.html">problems</a></li>
2020-03-19 02:11:25 +02:00
<li><a href="../index-module/index.html">index</a></li>
2020-04-14 19:56:54 +03:00
</ul><h2>Inter Modules</h2><ul>
<li><a href="../bytecode-module/index.html">bytecode</a></li>
2020-03-19 02:11:25 +02:00
<li><a href="../building-module/index.html">building</a></li>
<li><a href="../codegen-module/index.html">codegen</a></li>
2020-04-14 19:56:54 +03:00
</ul><h2>Shared Modules</h2><ul>
<li><a href="../arch-module/index.html">arch</a></li>
<li><a href="../syntax-module/index.html">syntax</a></li>
<li><a href="../words-module/index.html">words</a></li>
<li><a href="index.html"><span class="selectedlink">html</span></a></li>
2020-03-19 02:11:25 +02:00
<li><a href="../../../inweb/docs/foundation-module/index.html">foundation</a></li>
2020-04-14 19:56:54 +03:00
</ul>
2020-03-19 02:11:25 +02:00
</nav>
<main role="main">
2020-05-03 03:01:21 +03:00
<!--Weave of 'HTML Files' generated by Inweb-->
<div class="breadcrumbs">
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="../compiler.html">Shared 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 Files</b></li></ul></div>
<p class="purpose">To provide utilities for writing HTML files such as the problems report, the extension documentation, the index files and so forth.</p>
2020-02-27 13:18:25 +02:00
<ul class="toc"><li><a href="2-hf.html#SP2">&#167;2. The "inform:" URL scheme</a></li><li><a href="2-hf.html#SP3">&#167;3. The "source:" URL scheme</a></li><li><a href="2-hf.html#SP4">&#167;4. Icons with and without tooltips</a></li><li><a href="2-hf.html#SP5">&#167;5. Outcome images</a></li><li><a href="2-hf.html#SP6">&#167;6. Header and footer</a></li><li><a href="2-hf.html#SP7">&#167;7. HTML paragraphs with indentation</a></li><li><a href="2-hf.html#SP8">&#167;8. Writing HTML characters</a></li><li><a href="2-hf.html#SP9">&#167;9. Writing streams in XML-escaped form</a></li></ul><hr class="tocbar">
2020-02-27 13:18:25 +02:00
2020-05-03 03:01:21 +03:00
<p class="commentary firstcommentary"><a id="SP1"></a><b>&#167;1. </b>Inform documentation &mdash; its HTML text and the images, etc., used within
2020-02-27 13:18:25 +02:00
it &mdash; is stored in two areas: "built-in" and "external". The built-in
area is expected to be within the Inform 7 application itself. For
instance, on OS X, this is at:
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary"><span class="extract"><span class="extract-syntax">...wherever.../Inform.app/Contents/Resources/</span></span> and/or
2020-02-27 13:18:25 +02:00
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary"><span class="extract"><span class="extract-syntax">...wherever.../Inform.app/Contents/Resources/English.lproj/</span></span>
2020-02-27 13:18:25 +02:00
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary">(The duplication is a complication to do with localisation which we
2020-02-27 13:18:25 +02:00
can ignore here.) The material stored in this built-in area is fixed: the
Inform application needs to work even if stored on a read-only disc, or
2020-04-14 19:56:54 +03:00
where the user has insufficient permissions to alter it. Inform itself neither
2020-02-27 13:18:25 +02:00
reads from, nor writes to, any file in the built-in documentation area.
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary">Documentation for the installed extensions does, however, change: it is
2020-04-14 19:56:54 +03:00
written by Inform as and when necessary. This is the material making up the
2020-02-27 13:18:25 +02:00
"external" area, and it needs to be somewhere which the user certainly
has the necessary permissions to write to. For instance:
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary"><span class="extract"><span class="extract-syntax">~/Library/Inform/Documentation/</span></span> (OS X)
2020-02-27 13:18:25 +02:00
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary"><span class="extract"><span class="extract-syntax">My Documents\Inform\Documentation\</span></span> (Windows)
2020-04-14 19:56:54 +03:00
</p>
2020-02-27 13:18:25 +02:00
2020-05-03 03:01:21 +03:00
<p class="commentary">Pages in these two areas, built-in and external, need to link to each other by
2020-02-27 13:18:25 +02:00
links: in addition, pages in the external area need access to images stored in
the built-in area.
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary">The other HTML files written by Inform are stored within the relevant
2020-02-27 13:18:25 +02:00
project's bundle: these are the report of Problems (if any) and the
Index. They, too, need access to images stored in the built-in area.
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary">The problem we face is that these three mini-websites &mdash; the built-in
2020-02-27 13:18:25 +02:00
documentation, the external documentation, and the project-specific
pages &mdash; are written by tools which cannot know the correct file URLs.
2020-04-14 19:56:54 +03:00
(For instance, it would not even help for the application to tell Inform
where the built-in area is: because the HTML written by Inform would then
2020-02-27 13:18:25 +02:00
cease to work if the user moved the application elsewhere in the
2020-04-14 19:56:54 +03:00
filing system after Inform had run.)
2020-02-27 13:18:25 +02:00
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary firstcommentary"><a id="SP2"></a><b>&#167;2. The "inform:" URL scheme. </b>We solve this by requiring that the Inform 7 application must support
2020-02-27 13:18:25 +02:00
a new URL scheme.
</p>
2020-05-03 03:01:21 +03:00
<ul class="items"><li>(a) <span class="extract"><span class="extract-syntax">&lt;inform://...&gt;</span></span> is interpreted as a file in the built-in documentation
2020-02-27 13:18:25 +02:00
area, except that
2020-05-03 03:01:21 +03:00
</li><li>(b) <span class="extract"><span class="extract-syntax">&lt;inform://Extensions/...whatever...&gt;</span></span> should be fetched by first
2020-02-27 13:18:25 +02:00
checking for "...whatever..." in the external area, and then &mdash; if
2020-05-03 03:01:21 +03:00
that fails &mdash; also checking for "...whatever..." in the <span class="extract"><span class="extract-syntax">ExtnDocs</span></span>
2020-02-27 13:18:25 +02:00
subfolder of the built-in area.
</li></ul>
2020-05-03 03:01:21 +03:00
<p class="commentary">For instance, Inform 7 for OS X would look for <span class="extract"><span class="extract-syntax">inform://Extensions/magic.png</span></span>
2020-02-27 13:18:25 +02:00
at the following locations:
</p>
2020-05-03 03:01:21 +03:00
<ul class="items"><li>(i) <span class="extract"><span class="extract-syntax">~/Library/Inform/Documentation/magic.png</span></span>
</li><li>(ii) <span class="extract"><span class="extract-syntax">.../Inform.app/Contents/Resources/ExtnDocs/magic.png</span></span>
2020-02-27 13:18:25 +02:00
</li></ul>
2020-05-03 03:01:21 +03:00
<p class="commentary">If no file was found in either place, the link should simply do nothing:
2020-02-27 13:18:25 +02:00
the application is required not to produce a 404 error page, or to
blank out the page currently showing.
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary firstcommentary"><a id="SP3"></a><b>&#167;3. The "source:" URL scheme. </b>The other non-standard Inform URL scheme is "source:", which is used
2020-02-27 13:18:25 +02:00
for a link which, when clicked, opens the Source panel with the given
line made visible.
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary">For instance, line 21 of file <span class="extract"><span class="extract-syntax">Bits and Pieces/marbles.txt</span></span> has URL
2020-02-27 13:18:25 +02:00
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary"><span class="extract"><span class="extract-syntax">source:Bits and Pieces/marbles.txt#line14</span></span>
2020-02-27 13:18:25 +02:00
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary">Filenames are given relative to the current project bundle. However, if only
a leafname is supplied, then this is read as a file within the <span class="extract"><span class="extract-syntax">Source</span></span>
2020-02-27 13:18:25 +02:00
subfolder of the project bundle. (Thus it is not possible to have a
source link to a source file at the root of the project bundle: but this is
no loss, since source is not allowed to be kept there.) For instance,
2020-05-03 03:01:21 +03:00
line 14 of file <span class="extract"><span class="extract-syntax">Source/story.ni</span></span> has URL
2020-02-27 13:18:25 +02:00
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary"><span class="extract"><span class="extract-syntax">source:story.ni#line14</span></span>
2020-02-27 13:18:25 +02:00
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary">The following routine writes the clickable source-reference icon, and
2020-04-14 19:56:54 +03:00
is the only place in Inform where "source:" is used.
2020-02-27 13:18:25 +02:00
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary">Source which is generated internally to Inform cannot be opened in the Source
2020-02-27 13:18:25 +02:00
panel, for obvious reasons, so we produce nothing if the location is internal.
</p>
2020-05-03 03:01:21 +03:00
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">source_link_case</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">HTMLFiles::set_source_link_case</span><span class="plain-syntax">(</span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">p</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">source_link_case</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Characters::toupper</span><span class="plain-syntax">(</span><span class="identifier-syntax">Str::get_first_char</span><span class="plain-syntax">(</span><span class="identifier-syntax">p</span><span class="plain-syntax">));</span>
<span class="plain-syntax">}</span>
<span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">abbreviate_links_within</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">HTMLFiles::set_link_abbreviation_path</span><span class="plain-syntax">(</span><span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">abbreviate_links_within</span><span class="plain-syntax"> = </span><span class="identifier-syntax">P</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
<span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="function-syntax">HTMLFiles::get_link_abbreviation_path</span><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">abbreviate_links_within</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
2020-05-03 03:01:21 +03:00
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">HTMLFiles::html_source_link</span><button class="popup" onclick="togglePopup('usagePopup1')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup1">Usage of <span class="code-font"><span class="function-syntax">HTMLFiles::html_source_link</span></span>:<br/><a href="2-hf.html#SP8">&#167;8</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="identifier-syntax">source_location</span><span class="plain-syntax"> </span><span class="identifier-syntax">sl</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">nonbreaking_space</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">sl</span><span class="plain-syntax">.</span><span class="identifier-syntax">file_of_origin</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">fn</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">fn</span><span class="plain-syntax">, </span><span class="string-syntax">"%f"</span><span class="plain-syntax">, </span><span class="identifier-syntax">TextFromFiles::get_filename</span><span class="plain-syntax">(</span><span class="identifier-syntax">sl</span><span class="plain-syntax">.</span><span class="identifier-syntax">file_of_origin</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> #</span><span class="identifier-syntax">ifdef</span><span class="plain-syntax"> </span><span class="identifier-syntax">SUPERVISOR_MODULE</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">abbreviate_links_within</span><span class="plain-syntax">) {</span>
2020-05-03 03:01:21 +03:00
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">pp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">pp</span><span class="plain-syntax">, </span><span class="string-syntax">"%p"</span><span class="plain-syntax">, </span><span class="identifier-syntax">abbreviate_links_within</span><span class="plain-syntax">);</span>
2020-05-03 03:01:21 +03:00
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">N</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">pp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::prefix_eq</span><span class="plain-syntax">(</span><span class="identifier-syntax">fn</span><span class="plain-syntax">, </span><span class="identifier-syntax">pp</span><span class="plain-syntax">, </span><span class="identifier-syntax">N</span><span class="plain-syntax">))</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Str::delete_n_characters</span><span class="plain-syntax">(</span><span class="identifier-syntax">fn</span><span class="plain-syntax">, </span><span class="identifier-syntax">N</span><span class="plain-syntax">+1);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">pp</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> #</span><span class="identifier-syntax">endif</span>
2020-05-03 03:01:21 +03:00
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">Str::begins_with_wide_string</span><span class="plain-syntax">(</span><span class="identifier-syntax">fn</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"Source"</span><span class="plain-syntax">)) &amp;&amp;</span>
<span class="plain-syntax"> (</span><span class="identifier-syntax">Str::get_at</span><span class="plain-syntax">(</span><span class="identifier-syntax">fn</span><span class="plain-syntax">, </span><span class="constant-syntax">6</span><span class="plain-syntax">) == </span><span class="identifier-syntax">FOLDER_SEPARATOR</span><span class="plain-syntax">))</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Str::delete_n_characters</span><span class="plain-syntax">(</span><span class="identifier-syntax">fn</span><span class="plain-syntax">, </span><span class="constant-syntax">7</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">nonbreaking_space</span><span class="plain-syntax">) </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&amp;nbsp;"</span><span class="plain-syntax">); </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">" "</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">source_link_case</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_OPEN_WITH</span><span class="plain-syntax">(</span><span class="string-syntax">"a"</span><span class="plain-syntax">, </span><span class="string-syntax">"href=\"source:%S?case=%c#line%d\""</span><span class="plain-syntax">, </span><span class="identifier-syntax">fn</span><span class="plain-syntax">, </span><span class="identifier-syntax">source_link_case</span><span class="plain-syntax">, </span><span class="identifier-syntax">sl</span><span class="plain-syntax">.</span><span class="identifier-syntax">line_number</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">else</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_OPEN_WITH</span><span class="plain-syntax">(</span><span class="string-syntax">"a"</span><span class="plain-syntax">, </span><span class="string-syntax">"href=\"source:%S#line%d\""</span><span class="plain-syntax">, </span><span class="identifier-syntax">fn</span><span class="plain-syntax">, </span><span class="identifier-syntax">sl</span><span class="plain-syntax">.</span><span class="identifier-syntax">line_number</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_TAG_WITH</span><span class="plain-syntax">(</span><span class="string-syntax">"img"</span><span class="plain-syntax">, </span><span class="string-syntax">"border=0 src=inform:/doc_images/Reveal.png"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_CLOSE</span><span class="plain-syntax">(</span><span class="string-syntax">"a"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">fn</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
2020-02-27 13:18:25 +02:00
</pre>
2020-05-03 03:01:21 +03:00
<p class="commentary firstcommentary"><a id="SP4"></a><b>&#167;4. Icons with and without tooltips. </b>Tooltips are the evanescent pop-up windows which appear, a little behind the
2020-02-27 13:18:25 +02:00
mouse arrow, when it is poised waiting over the icon. (We make heavy use of
these in the World index, for instance, to clarify what abbreviations mean.)
</p>
2020-05-03 03:01:21 +03:00
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">HTMLFiles::html_icon_with_tooltip</span><button class="popup" onclick="togglePopup('usagePopup2')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup2">Usage of <span class="code-font"><span class="function-syntax">HTMLFiles::html_icon_with_tooltip</span></span>:<br/><a href="2-hf.html#SP8">&#167;8</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="reserved-syntax">char</span><span class="plain-syntax"> *</span><span class="identifier-syntax">icon_name</span><span class="plain-syntax">, </span><span class="reserved-syntax">char</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tip</span><span class="plain-syntax">, </span><span class="reserved-syntax">char</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tip2</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">img</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">img</span><span class="plain-syntax">, </span><span class="string-syntax">"border=0 src=inform:/doc_images/%s "</span><span class="plain-syntax">, </span><span class="identifier-syntax">icon_name</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">tip</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">img</span><span class="plain-syntax">, </span><span class="string-syntax">"title=\"%s"</span><span class="plain-syntax">, </span><span class="identifier-syntax">tip</span><span class="plain-syntax">); </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">tip2</span><span class="plain-syntax">) </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">img</span><span class="plain-syntax">, </span><span class="string-syntax">" %s"</span><span class="plain-syntax">, </span><span class="identifier-syntax">tip2</span><span class="plain-syntax">); </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">img</span><span class="plain-syntax">, </span><span class="string-syntax">"\""</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_TAG_WITH</span><span class="plain-syntax">(</span><span class="string-syntax">"img"</span><span class="plain-syntax">, </span><span class="string-syntax">"%S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">img</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">img</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
2020-02-27 13:18:25 +02:00
</pre>
2020-05-03 03:01:21 +03:00
<p class="commentary firstcommentary"><a id="SP5"></a><b>&#167;5. Outcome images. </b>These are the two images used on the Problems page to visually indicate
2020-02-27 13:18:25 +02:00
success or failure. We also use special images on special occasions.
</p>
2020-05-03 03:01:21 +03:00
<pre class="definitions code-font"><span class="definition-keyword">define</span> <span class="constant-syntax">CENTRED_OUTCOME_IMAGE_STYLE</span><span class="plain-syntax"> </span><span class="constant-syntax">1</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">SIDE_OUTCOME_IMAGE_STYLE</span><span class="plain-syntax"> </span><span class="constant-syntax">2</span>
2020-02-27 13:18:25 +02:00
</pre>
2020-05-03 03:01:21 +03:00
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">outcome_image_style</span><span class="plain-syntax"> = </span><span class="constant-syntax">SIDE_OUTCOME_IMAGE_STYLE</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">HTMLFiles::html_outcome_image</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="reserved-syntax">char</span><span class="plain-syntax"> *</span><span class="identifier-syntax">image</span><span class="plain-syntax">, </span><span class="reserved-syntax">char</span><span class="plain-syntax"> *</span><span class="identifier-syntax">verdict</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">char</span><span class="plain-syntax"> *</span><span class="identifier-syntax">vn</span><span class="plain-syntax"> = </span><span class="string-syntax">""</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">be_festive</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> #</span><span class="identifier-syntax">ifdef</span><span class="plain-syntax"> </span><span class="identifier-syntax">CORE_MODULE</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Problems::Issue::internal_errors_have_occurred</span><span class="plain-syntax">() == </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">) </span><span class="identifier-syntax">be_festive</span><span class="plain-syntax"> = </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> #</span><span class="identifier-syntax">endif</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">be_festive</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">switch</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Time::feast</span><span class="plain-syntax">()) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">CHRISTMAS_FEAST:</span><span class="plain-syntax"> </span><span class="identifier-syntax">vn</span><span class="plain-syntax"> = </span><span class="string-syntax">"_2"</span><span class="plain-syntax">; </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">EASTER_FEAST:</span><span class="plain-syntax"> </span><span class="identifier-syntax">vn</span><span class="plain-syntax"> = </span><span class="string-syntax">"_3"</span><span class="plain-syntax">; </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">vn</span><span class="plain-syntax">[0]) </span><span class="identifier-syntax">outcome_image_style</span><span class="plain-syntax"> = </span><span class="constant-syntax">CENTRED_OUTCOME_IMAGE_STYLE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> #</span><span class="identifier-syntax">ifdef</span><span class="plain-syntax"> </span><span class="identifier-syntax">PROBLEMS_MODULE</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Problems::Issue::issue_problems_banner</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">verdict</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> #</span><span class="identifier-syntax">endif</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">switch</span><span class="plain-syntax"> (</span><span class="identifier-syntax">outcome_image_style</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">CENTRED_OUTCOME_IMAGE_STYLE:</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_OPEN</span><span class="plain-syntax">(</span><span class="string-syntax">"p"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_OPEN</span><span class="plain-syntax">(</span><span class="string-syntax">"center"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_TAG_WITH</span><span class="plain-syntax">(</span><span class="string-syntax">"img"</span><span class="plain-syntax">, </span><span class="string-syntax">"src=inform:/outcome_images/%s%s.png border=0"</span><span class="plain-syntax">, </span><span class="identifier-syntax">image</span><span class="plain-syntax">, </span><span class="identifier-syntax">vn</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_CLOSE</span><span class="plain-syntax">(</span><span class="string-syntax">"center"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_CLOSE</span><span class="plain-syntax">(</span><span class="string-syntax">"p"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">SIDE_OUTCOME_IMAGE_STYLE:</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::begin_html_table</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">, </span><span class="constant-syntax">4</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::first_html_column</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="constant-syntax">110</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_TAG_WITH</span><span class="plain-syntax">(</span><span class="string-syntax">"img"</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="string-syntax">"src=inform:/outcome_images/%s%s@2x.png border=1 width=100 height=100"</span><span class="plain-syntax">, </span><span class="identifier-syntax">image</span><span class="plain-syntax">, </span><span class="identifier-syntax">vn</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::next_html_column</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::comment</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"HEADNOTE"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_OPEN_WITH</span><span class="plain-syntax">(</span><span class="string-syntax">"p"</span><span class="plain-syntax">, </span><span class="string-syntax">"style=\"margin-top:0;\""</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"(Each time &lt;b&gt;Go&lt;/b&gt; or &lt;b&gt;Replay&lt;/b&gt; is clicked, Inform tries to "</span>
<span class="plain-syntax"> </span><span class="string-syntax">"translate the source text into a working story, and updates this report.)"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_CLOSE</span><span class="plain-syntax">(</span><span class="string-syntax">"p"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::comment</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"PROBLEMS BEGIN"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">HTMLFiles::outcome_image_tail</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUTPUT_STREAM</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">outcome_image_style</span><span class="plain-syntax"> == </span><span class="constant-syntax">SIDE_OUTCOME_IMAGE_STYLE</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::comment</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"PROBLEMS END"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::end_html_row</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::end_html_table</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::comment</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"FOOTNOTE"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
2020-02-27 13:18:25 +02:00
</pre>
2020-05-03 03:01:21 +03:00
<p class="commentary firstcommentary"><a id="SP6"></a><b>&#167;6. Header and footer. </b></p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">HTMLFiles::html_header</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">title</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::declare_as_HTML</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::begin_head</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::incorporate_CSS</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">,</span>
2020-05-03 18:34:53 +03:00
<span class="plain-syntax"> </span><span class="identifier-syntax">Supervisor::file_from_installation</span><span class="plain-syntax">(</span><span class="identifier-syntax">CSS_FOR_STANDARD_PAGES_IRES</span><span class="plain-syntax">));</span>
2020-05-03 03:01:21 +03:00
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::incorporate_javascript</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">,</span>
2020-05-03 18:34:53 +03:00
<span class="plain-syntax"> </span><span class="identifier-syntax">Supervisor::file_from_installation</span><span class="plain-syntax">(</span><span class="identifier-syntax">JAVASCRIPT_FOR_STANDARD_PAGES_IRES</span><span class="plain-syntax">));</span>
2020-05-03 03:01:21 +03:00
<span class="plain-syntax"> #</span><span class="identifier-syntax">ifdef</span><span class="plain-syntax"> </span><span class="identifier-syntax">INDEX_MODULE</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Index::scripting</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> #</span><span class="identifier-syntax">endif</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::end_head</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::begin_body</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::comment</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"CONTENT BEGINS"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">HTMLFiles::html_footer</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUTPUT_STREAM</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"\n"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::comment</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"CONTENT ENDS"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML::end_body</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
2020-02-27 13:18:25 +02:00
</pre>
2020-05-03 03:01:21 +03:00
<p class="commentary firstcommentary"><a id="SP7"></a><b>&#167;7. HTML paragraphs with indentation. </b></p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">HTMLFiles::open_para</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">depth</span><span class="plain-syntax">, </span><span class="reserved-syntax">char</span><span class="plain-syntax"> *</span><span class="identifier-syntax">class</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">margin</span><span class="plain-syntax"> = </span><span class="identifier-syntax">depth</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">margin</span><span class="plain-syntax"> &lt; </span><span class="constant-syntax">1</span><span class="plain-syntax">) </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"minimal HTML indentation is 1"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">margin</span><span class="plain-syntax"> &gt; </span><span class="constant-syntax">9</span><span class="plain-syntax">) </span><span class="identifier-syntax">margin</span><span class="plain-syntax"> = </span><span class="constant-syntax">9</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">HTML_OPEN_WITH</span><span class="plain-syntax">(</span><span class="string-syntax">"p"</span><span class="plain-syntax">, </span><span class="string-syntax">"class=\"%sin%d\""</span><span class="plain-syntax">, </span><span class="identifier-syntax">class</span><span class="plain-syntax">, </span><span class="identifier-syntax">margin</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">while</span><span class="plain-syntax"> (</span><span class="identifier-syntax">depth</span><span class="plain-syntax"> &gt; </span><span class="constant-syntax">9</span><span class="plain-syntax">) { </span><span class="identifier-syntax">depth</span><span class="plain-syntax">--; </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;"</span><span class="plain-syntax">); }</span>
<span class="plain-syntax">}</span>
2020-02-27 13:18:25 +02:00
</pre>
2020-05-03 03:01:21 +03:00
<p class="commentary firstcommentary"><a id="SP8"></a><b>&#167;8. Writing HTML characters. </b>The following routine is a low-level filter which takes ISO Latin-1
2020-02-27 13:18:25 +02:00
characters one at a time, feeding them out to the given stream with any
unsafe characters converted to suitable HTML elements. (The stream writer
will transcode to UTF-8 encoding, since all HTML file streams written by
Inform are declared as having the UTF-8 character encoding.)
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary">Recall that a source reference is fed into <span class="extract"><span class="extract-syntax">HTMLFiles::char_out</span></span> as the
2020-02-27 13:18:25 +02:00
following stream of characters:
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary"><span class="extract"><span class="extract-syntax">*source text*Source/story.ni*14*</span></span>
2020-02-27 13:18:25 +02:00
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary">(with <span class="extract"><span class="extract-syntax">SOURCE_REF_CHAR</span></span> used in place of the asterisk).
2020-02-27 13:18:25 +02:00
</p>
2020-05-03 03:01:21 +03:00
<p class="commentary">When we notice the trigger character, we cease to output HTML and instead
2020-02-27 13:18:25 +02:00
buffer up the reference until we reach the terminating trigger character:
2020-05-03 03:01:21 +03:00
we then parse a little, tidy up and send it to <span class="extract"><span class="extract-syntax">HTMLFiles::html_source_link</span></span> to be
turned into a <span class="extract"><span class="extract-syntax">source:</span></span> link.
2020-02-27 13:18:25 +02:00
</p>
2020-05-03 03:01:21 +03:00
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">source_ref_fields</span><span class="plain-syntax">[3] = { </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax"> }; </span><span class="comment-syntax"> paraphrase, filename, line</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">source_ref_field</span><span class="plain-syntax"> = -1; </span><span class="comment-syntax"> which field we are buffering</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">HTMLFiles::char_out</span><button class="popup" onclick="togglePopup('usagePopup3')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup3">Usage of <span class="code-font"><span class="function-syntax">HTMLFiles::char_out</span></span>:<br/>HTML Documentation - <a href="2-hd.html#SP9_5">&#167;9.5</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">charcode</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">source_ref_field</span><span class="plain-syntax"> &gt;= </span><span class="constant-syntax">0</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">source_ref_fields</span><span class="plain-syntax">[</span><span class="identifier-syntax">source_ref_field</span><span class="plain-syntax">] == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="identifier-syntax">source_ref_fields</span><span class="plain-syntax">[</span><span class="identifier-syntax">source_ref_field</span><span class="plain-syntax">] = </span><span class="identifier-syntax">Str::new</span><span class="plain-syntax">();</span>
<span class="plain-syntax"> #</span><span class="identifier-syntax">ifdef</span><span class="plain-syntax"> </span><span class="identifier-syntax">PROBLEMS_MODULE</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">charcode</span><span class="plain-syntax"> != </span><span class="identifier-syntax">SOURCE_REF_CHAR</span><span class="plain-syntax">) { </span><span class="identifier-syntax">PUT_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">source_ref_fields</span><span class="plain-syntax">[</span><span class="identifier-syntax">source_ref_field</span><span class="plain-syntax">], </span><span class="identifier-syntax">charcode</span><span class="plain-syntax">); </span><span class="reserved-syntax">return</span><span class="plain-syntax">; }</span>
<span class="plain-syntax"> #</span><span class="identifier-syntax">endif</span>
<span class="plain-syntax"> #</span><span class="identifier-syntax">ifndef</span><span class="plain-syntax"> </span><span class="identifier-syntax">PROBLEMS_MODULE</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PUT_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">source_ref_fields</span><span class="plain-syntax">[</span><span class="identifier-syntax">source_ref_field</span><span class="plain-syntax">], </span><span class="identifier-syntax">charcode</span><span class="plain-syntax">); </span><span class="reserved-syntax">return</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> #</span><span class="identifier-syntax">endif</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">switch</span><span class="plain-syntax">(</span><span class="identifier-syntax">charcode</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="character-syntax">'"'</span><span class="plain-syntax">: </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&amp;quot;"</span><span class="plain-syntax">); </span><span class="reserved-syntax">return</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="character-syntax">'&lt;'</span><span class="plain-syntax">: </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&amp;lt;"</span><span class="plain-syntax">); </span><span class="reserved-syntax">return</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="character-syntax">'&gt;'</span><span class="plain-syntax">: </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&amp;gt;"</span><span class="plain-syntax">); </span><span class="reserved-syntax">return</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="character-syntax">'&amp;'</span><span class="plain-syntax">: </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&amp;amp;"</span><span class="plain-syntax">); </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">NEWLINE_IN_STRING:</span><span class="plain-syntax"> </span><span class="identifier-syntax">HTML_TAG</span><span class="plain-syntax">(</span><span class="string-syntax">"br"</span><span class="plain-syntax">); </span><span class="reserved-syntax">return</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> #</span><span class="identifier-syntax">ifdef</span><span class="plain-syntax"> </span><span class="identifier-syntax">PROBLEMS_MODULE</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">FORCE_NEW_PARA_CHAR:</span><span class="plain-syntax"> </span><span class="identifier-syntax">HTML_CLOSE</span><span class="plain-syntax">(</span><span class="string-syntax">"p"</span><span class="plain-syntax">); </span><span class="identifier-syntax">HTML_OPEN_WITH</span><span class="plain-syntax">(</span><span class="string-syntax">"p"</span><span class="plain-syntax">, </span><span class="string-syntax">"class=\"in2\""</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="2-hf.html#SP4" class="function-link"><span class="function-syntax">HTMLFiles::html_icon_with_tooltip</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="string-syntax">"ornament_flower.png"</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&amp;nbsp;"</span><span class="plain-syntax">); </span><span class="reserved-syntax">return</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">SOURCE_REF_CHAR:</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">source_ref_field</span><span class="plain-syntax">++;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">source_ref_field</span><span class="plain-syntax"> == </span><span class="constant-syntax">3</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">source_ref_field</span><span class="plain-syntax"> = -1;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">source_location</span><span class="plain-syntax"> </span><span class="identifier-syntax">sl</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">sl</span><span class="plain-syntax">.</span><span class="identifier-syntax">file_of_origin</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TextFromFiles::filename_to_source_file</span><span class="plain-syntax">(</span><span class="identifier-syntax">source_ref_fields</span><span class="plain-syntax">[1]);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">sl</span><span class="plain-syntax">.</span><span class="identifier-syntax">line_number</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::atoi</span><span class="plain-syntax">(</span><span class="identifier-syntax">source_ref_fields</span><span class="plain-syntax">[2], </span><span class="constant-syntax">0</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="2-hf.html#SP3" class="function-link"><span class="function-syntax">HTMLFiles::html_source_link</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">sl</span><span class="plain-syntax">, </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="identifier-syntax">Str::clear</span><span class="plain-syntax">(</span><span class="identifier-syntax">source_ref_fields</span><span class="plain-syntax">[</span><span class="identifier-syntax">source_ref_field</span><span class="plain-syntax">]);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> #</span><span class="identifier-syntax">endif</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">default:</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PUT</span><span class="plain-syntax">(</span><span class="identifier-syntax">charcode</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
2020-02-27 13:18:25 +02:00
</pre>
2020-05-03 03:01:21 +03:00
<p class="commentary firstcommentary"><a id="SP9"></a><b>&#167;9. Writing streams in XML-escaped form. </b></p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">HTMLFiles::write_xml_safe_text</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">txt</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOOP_THROUGH_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">pos</span><span class="plain-syntax">, </span><span class="identifier-syntax">txt</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">wchar_t</span><span class="plain-syntax"> </span><span class="identifier-syntax">c</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::get</span><span class="plain-syntax">(</span><span class="identifier-syntax">pos</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">switch</span><span class="plain-syntax">(</span><span class="identifier-syntax">c</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="character-syntax">'&amp;'</span><span class="plain-syntax">: </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&amp;amp;"</span><span class="plain-syntax">); </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="character-syntax">'&lt;'</span><span class="plain-syntax">: </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&amp;lt;"</span><span class="plain-syntax">); </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="character-syntax">'&gt;'</span><span class="plain-syntax">: </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&amp;gt;"</span><span class="plain-syntax">); </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">default:</span><span class="plain-syntax"> </span><span class="identifier-syntax">PUT</span><span class="plain-syntax">(</span><span class="identifier-syntax">c</span><span class="plain-syntax">); </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
2020-02-27 13:18:25 +02:00
</pre>
2020-05-03 03:01:21 +03:00
<nav role="progress"><div class="progresscontainer">
<ul class="progressbar"><li class="progressprev"><a href="1-hm.html">&#10094;</a></li><li class="progresschapter"><a href="1-hm.html">1</a></li><li class="progresscurrentchapter">2</li><li class="progresscurrent">hf</li><li class="progresssection"><a href="2-jp.html">jp</a></li><li class="progresssection"><a href="2-hd.html">hd</a></li><li class="progressnext"><a href="2-jp.html">&#10095;</a></li></ul></div>
</nav><!--End of weave-->
2020-02-27 13:18:25 +02:00
2020-03-19 02:11:25 +02:00
</main>
2020-02-27 13:18:25 +02:00
</body>
</html>