mirror of
https://github.com/ganelson/inform.git
synced 2024-07-18 15:04:25 +03:00
192 lines
11 KiB
HTML
192 lines
11 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>Interacting with the GUI</title>
|
|
<link href="../docs-assets/Breadcrumbs.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<meta name="viewport" content="width=device-width initial-scale=1">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<meta http-equiv="Content-Language" content="en-gb">
|
|
|
|
<link href="../docs-assets/Contents.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Progress.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Navigation.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Fonts.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Base.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
|
|
</head>
|
|
<body class="commentary-font">
|
|
<nav role="navigation">
|
|
<h1><a href="../index.html">
|
|
<img src="../docs-assets/Inform.png" height=72">
|
|
</a></h1>
|
|
<ul><li><a href="../compiler.html">compiler tools</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="index.html"><span class="selectedlink">inform7</span></a></li>
|
|
<li><a href="../inter/index.html">inter</a></li>
|
|
</ul><h2>Inbuild Modules</h2><ul>
|
|
<li><a href="../supervisor-module/index.html">supervisor</a></li>
|
|
</ul><h2>Inform7 Modules</h2><ul>
|
|
<li><a href="../core-module/index.html">core</a></li>
|
|
<li><a href="../assertions-module/index.html">assertions</a></li>
|
|
<li><a href="../values-module/index.html">values</a></li>
|
|
<li><a href="../knowledge-module/index.html">knowledge</a></li>
|
|
<li><a href="../imperative-module/index.html">imperative</a></li>
|
|
<li><a href="../runtime-module/index.html">runtime</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="../bytecode-module/index.html">bytecode</a></li>
|
|
<li><a href="../building-module/index.html">building</a></li>
|
|
<li><a href="../codegen-module/index.html">codegen</a></li>
|
|
</ul><h2>Services</h2><ul>
|
|
<li><a href="../arch-module/index.html">arch</a></li>
|
|
<li><a href="../calculus-module/index.html">calculus</a></li>
|
|
<li><a href="../html-module/index.html">html</a></li>
|
|
<li><a href="../inflections-module/index.html">inflections</a></li>
|
|
<li><a href="../kinds-module/index.html">kinds</a></li>
|
|
<li><a href="../linguistics-module/index.html">linguistics</a></li>
|
|
<li><a href="../problems-module/index.html">problems</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="../../../inweb/docs/foundation-module/index.html">foundation</a></li>
|
|
|
|
</ul>
|
|
</nav>
|
|
<main role="main">
|
|
<!--Weave of 'Interacting with the GUI' generated by Inweb-->
|
|
<div class="breadcrumbs">
|
|
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="../compiler.html">Compiler Tools</a></li><li><a href="index.html">inform7</a></li><li><a href="index.html#M">Manual</a></li><li><b>Interacting with the GUI</b></li></ul></div>
|
|
<p class="purpose">A few notes on how the GUI apps should use the Inform command line.</p>
|
|
|
|
<ul class="toc"><li><a href="M-iwtg.html#SP1">§1. How the application should install extensions</a></li><li><a href="M-iwtg.html#SP2">§2. The extension census</a></li><li><a href="M-iwtg.html#SP3">§3. What happens in census mode</a></li></ul><hr class="tocbar">
|
|
|
|
<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>§1. How the application should install extensions. </b>When the Inform 7 application looks at a file chosen by the user to
|
|
be installed, it should look at the first line. (Note that this might have
|
|
any of <span class="extract"><span class="extract-syntax">0a</span></span>, <span class="extract"><span class="extract-syntax">0d</span></span>, <span class="extract"><span class="extract-syntax">0a0d</span></span>, <span class="extract"><span class="extract-syntax">0d0a</span></span>, or Unicode line division as its line
|
|
ending: and that the file might, or might not, begin with a Unicode BOM,
|
|
"byte order marker", code. Characters within the line will be encoded as
|
|
UTF-8, though — except possibly for some exotic forms of space — they
|
|
will all be found in the ISO Latin-1 set.) The first line is required to
|
|
have one of the following forms, possibly with white space before or after,
|
|
but definitely without line breaks before:
|
|
</p>
|
|
|
|
<blockquote>
|
|
<p>Locksmith Extra by Emily Short begins here.</p>
|
|
</blockquote>
|
|
|
|
<blockquote>
|
|
<p>Version 2 of Locksmith Extra by Emily Short begins here.</p>
|
|
</blockquote>
|
|
|
|
<blockquote>
|
|
<p>Version 060430 of Locksmith Extra by Emily Short begins here.</p>
|
|
</blockquote>
|
|
|
|
<blockquote>
|
|
<p>Version 2/060430 of Locksmith Extra by Emily Short begins here.</p>
|
|
</blockquote>
|
|
|
|
<p class="commentary">If the name of the extension finishes with a bracketed clause, that
|
|
should be disregarded. Such clauses are used to specify virtual machine
|
|
requirements, at present, and could conceivably be used for other purposes
|
|
later, so let's reserve them now.
|
|
</p>
|
|
|
|
<blockquote>
|
|
<p>Version 2 of Glulx Text Effects (for Glulx only) by Emily Short begins here.</p>
|
|
</blockquote>
|
|
|
|
<p class="commentary">The application should reject (that is, politely refuse to install) any
|
|
purported extension file whose first line does not conform to the above.
|
|
</p>
|
|
|
|
<p class="commentary">Ignoring any version number given, the Inform application should then
|
|
store the file in the external extensions area. For instance,
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">~/Library/Inform/Extensions/Emily Short/Glulx Text Effects</span>
|
|
(OS X)<span class="plain-syntax">My Documents\Inform\Extensions\Emily Short\Glulx Text Effects</span>
|
|
(Windows)Note that the file will probably not have the right name initially, and
|
|
will need to be renamed as well as moved. (Note the lack of a file
|
|
extension.) The subfolders <span class="extract"><span class="extract-syntax">Inform</span></span>, <span class="extract"><span class="extract-syntax">Extensions</span></span> and <span class="extract"><span class="extract-syntax">Emily Short</span></span> must be
|
|
created if not already present.
|
|
If to install such an extension would result in over-writing an extension
|
|
already present at that filename, the user should be given a warning and
|
|
asked if he wants to proceed.
|
|
However, note that it is not an error to install an extension with
|
|
the same name and author as one in the built-in extensions folder. This
|
|
does not result in overwriting, since the newly installed version will live
|
|
in the external area, not the built-in area.
|
|
An extension may be uninstalled simply by deleting the file: but the
|
|
application must not allow the user to uninstall any extension from
|
|
the built-in area. We must assume that the latter could be on a read-only
|
|
disc, or could be part of a cryptographically signed application bundle.
|
|
</pre>
|
|
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>§2. The extension census. </b>The Inform application should run Inform in "census mode" in order to
|
|
keep extension documentation up to date. Inform should be run in census mode
|
|
on three occasions:
|
|
</p>
|
|
|
|
<ul class="items"><li>(a) when the Inform application starts up;
|
|
</li><li>(b) when the Inform application installs a new extension;
|
|
</li><li>(c) when the Inform application uninstalls an extension.
|
|
</li></ul>
|
|
<p class="commentary">When <span class="extract"><span class="extract-syntax">inform7</span></span> is run in "census mode", it should be run with the command <span class="extract"><span class="extract-syntax">-census</span></span>.
|
|
All output from Inform should be ignored, including its return code: ideally,
|
|
not even a fatal error should provoke a reaction from the application. If the
|
|
census doesn't work for some file-system reason, never mind — it's not
|
|
mission-critical.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>§3. What happens in census mode. </b>The census has two purposes: first, to create provisional documentation
|
|
where needed for new and unused extensions; and second, to create the
|
|
following index files in the external documentation area (not in
|
|
the external extension area):
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> .../Extensions.html</span>
|
|
<span class="plain-syntax"> .../ExtIndex.html</span>
|
|
</pre>
|
|
<p class="commentary">Documentation for any individual extension is stored at, e.g.,
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> .../Extensions/Victoria Saxe-Coburg-Gotha/Werewolves.html</span>
|
|
</pre>
|
|
<p class="commentary">Inform can generate such a file, for an individual extension, in two ways: (a)
|
|
provisionally, with much less detail, and (b) fully. Whenever it
|
|
successfully compiles a work using extension X, it rewrites the
|
|
documentation for X fully, and updates both the two indexing pages.
|
|
</p>
|
|
|
|
<p class="commentary">When Inform runs in <span class="extract"><span class="extract-syntax">-census</span></span> mode, what it does is to scan for all extensions.
|
|
If Inform finds a valid extension with no documentation page, it writes a
|
|
provisional one; and again, it updates both the two indexing pages.
|
|
</p>
|
|
|
|
<p class="commentary">(Inform in fact runs a census on every compilation, as well, so <span class="extract"><span class="extract-syntax">-census</span></span> runs
|
|
do nothing "extra" that a normal run of Inform does not also do. On every
|
|
census, Inform automatically checks for misfiled or broken extensions, and
|
|
places a descriptive report of what's wrong on the <span class="extract"><span class="extract-syntax">Extensions.html</span></span> index
|
|
page — if people move around or edit extensions by hand, they may run into
|
|
these errors.)
|
|
</p>
|
|
|
|
<nav role="progress"><div class="progresscontainer">
|
|
<ul class="progressbar"><li class="progressprev"><a href="M-cu.html">❮</a></li><li class="progresscurrentchapter">M</li><li class="progresssection"><a href="M-cu.html">cu</a></li><li class="progresscurrent">iwtg</li><li class="progresssection"><a href="M-rc.html">rc</a></li><li class="progresssection"><a href="M-pm.html">pm</a></li><li class="progresschapter"><a href="1-mn.html">1</a></li><li class="progressnext"><a href="M-rc.html">❯</a></li></ul></div>
|
|
</nav><!--End of weave-->
|
|
|
|
</main>
|
|
</body>
|
|
</html>
|
|
|