mirror of
https://github.com/ganelson/inform.git
synced 2024-07-16 22:14:23 +03:00
191 lines
9.8 KiB
HTML
191 lines
9.8 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>Booklet Title</title>
|
|
<meta name="viewport" content="width=device-width initial-scale=1">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<meta http-equiv="Content-Language" content="en-gb">
|
|
<link href="../inweb.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
</head>
|
|
<body>
|
|
<nav role="navigation">
|
|
<h1><a href="../webs.html">Sources</a></h1>
|
|
<ul>
|
|
<li><a href="../compiler.html">compiler</a></li>
|
|
<li><a href="../other.html"><b>other tools</b></a></li>
|
|
<li><a href="../extensions.html">extensions and kits</a></li>
|
|
<li><a href="../units.html">unit test tools</a></li>
|
|
</ul>
|
|
<h2>Other Tools</h2>
|
|
<ul>
|
|
<li><a href="../inblorb/index.html">inblorb</a></li>
|
|
<li><a href="../indoc/index.html">indoc</a></li>
|
|
<li><a href="../inpolicy/index.html">inpolicy</a></li>
|
|
<li><a href="../inrtps/index.html">inrtps</a></li>
|
|
</ul>
|
|
<h2>Foundation</h2>
|
|
<ul>
|
|
<li><a href="../../../inweb/docs/foundation-module/index.html">foundation</a></li>
|
|
</ul>
|
|
|
|
|
|
</nav>
|
|
<main role="main">
|
|
|
|
<!--Weave of 'M/ui' generated by 7-->
|
|
<ul class="crumbs"><li><a href="../webs.html">Source</a></li><li><a href="../other.html">Other Tools</a></li><li><a href="index.html">inblorb 4</a></li><li><a href="index.html#M">Manual</a></li><li><b>Using Inblorb</b></li></ul><p class="purpose">How to use this tool, either from the command line or inside the Inform app.</p>
|
|
|
|
<ul class="toc"><li><a href="#SP1">§1. What Inblorb is</a></li><li><a href="#SP2">§2. Inblorb at the command line</a></li><li><a href="#SP3">§3. Inblorb within the Inform user interface</a></li></ul><hr class="tocbar">
|
|
|
|
<p class="inwebparagraph"><a id="SP1"></a><b>§1. What Inblorb is. </b>Inblorb is a command-line tool which forms one of the components of the
|
|
Inform 7 design system for interactive fiction. Inblorb is the successor to
|
|
cBlorb (2008), which was itself the successor to perlBlorb (2001).
|
|
All installations of Inform 7 contain it, though few users are aware of that.
|
|
They typically write sentences such as:
|
|
</p>
|
|
|
|
<blockquote>
|
|
<p>Release along with public source text, cover art, and a website.</p>
|
|
|
|
</blockquote>
|
|
|
|
<p class="inwebparagraph">Inform 7 uses the instructions in such sentences to contribute to the
|
|
writing of a script called a "blurb". In effect, this is a detailed set
|
|
of instructions for Inblorb to follow, and when the user clicks Release
|
|
in the Inform application, the Inblorb tool is called. (This is a slightly
|
|
simplified description — see below for the full details.)
|
|
</p>
|
|
|
|
<p class="inwebparagraph">Inblorb has two main jobs: to bind up the translated project, together with
|
|
any pictures, sounds, or cover art, into a single file called a "blorb" which
|
|
can be given to players on other machines to play; and to produce associated
|
|
websites, solution files and so on as demanded by "Release..." instruction(s)
|
|
in the source text.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">"Blorb" is a general-purpose wrapper format designed as a way to gather
|
|
together audiovisual media and bibliographic data for works of IF. The
|
|
format was devised and formally specified by Andrew Plotkin around 2000,
|
|
and its name is borrowed from that of a magic spell in Infocom's classic
|
|
work, "Enchanter". ("The blorb spell (safely protect a small object as
|
|
though in a strong box).")
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP2"></a><b>§2. Inblorb at the command line. </b>If you have compiled the standard distribution of the command-line tools
|
|
for Inform then the Inblorb executable will be at <code class="display"><span class="extract">inblorb/Tangled/inblorb/</span></code>.
|
|
Usage is very simple:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">$ inblorb/Tangled/inblorb [OPTIONS] BLURBFILE [BLORBFILE]</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">This follows the given blurb file. Not all blurbs instruct Inblorb to make
|
|
a blorb, which is why BLORBFILE is optional.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">The OPTIONS are very simple. Inblorb's predecessor cBlorb needed to be told
|
|
what platform it was running on, by specifying <code class="display"><span class="extract">-osx</span></code>, <code class="display"><span class="extract">-windows</span></code> or
|
|
<code class="display"><span class="extract">-linux</span></code> at the command line, but these have gone. What remains is:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><code class="display"><span class="extract">-verbose</span></code> causes Inblorb to print a running narrative of what it's doing;
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><code class="display"><span class="extract">-project X</span></code> tells Inblorb to assume the usual settings for this project,
|
|
which means that BLURBFILE is set to <code class="display"><span class="extract">X/Release.blurb</span></code> and BLORBFILE
|
|
to <code class="display"><span class="extract">X/Build/output.gblorb</span></code>. <code class="display"><span class="extract">X</span></code> is usually something like <code class="display"><span class="extract">Whatever.inform</span></code>.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP3"></a><b>§3. Inblorb within the Inform user interface. </b>This is the sequence of events when the user clicks Release in the user
|
|
interface application (the "interface"):
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<ul class="items"><li>(1) The interface calls the Inform 7 compiler as normal except that the
|
|
<code class="display"><span class="extract">-release</span></code> command-line switch is specified.
|
|
</li></ul>
|
|
<ul class="items"><li>(2) If Problems occur, the compiler exits with a return code of 1, and the
|
|
interface displays those, and then stops the process.
|
|
</li></ul>
|
|
<ul class="items"><li>(3) If no Problems occur, the compiler generates Inform 6 code, and also
|
|
two additional files for the project's <code class="display"><span class="extract">Build</span></code> folder:
|
|
<ul class="items"><li>(a) <code class="display"><span class="extract">Metadata.iFiction</span></code>, an iFiction record;
|
|
</li><li>(b) <code class="display"><span class="extract">Release.blurb</span></code>, a blurb file of instructions for Inblorb to follow later.
|
|
</li></ul>
|
|
</li></ul>
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<ul class="items"><li>(4) The interface next calls the Inform 6 compiler. The interface calls it
|
|
with the <code class="display"><span class="extract">S</span></code> and <code class="display"><span class="extract">D</span></code> switches, for strict checking and for debugging, off
|
|
instead of on. Inform 6 should certainly not produce syntax errors, though
|
|
it will surely produce warnings; all the same it can fail if, say, Z-machine
|
|
memory limits are exceeded. The interface should deal with such failures
|
|
exactly as it would in a non-Release run.
|
|
</li></ul>
|
|
<ul class="items"><li>(5) Inform 6 having returned 0 to indicate success, the interface next calls
|
|
Inblorb as follows. Let <code class="display"><span class="extract">Path</span></code> be the path to the folder containing the Inform
|
|
project being released, which we'll call <code class="display"><span class="extract">This.inform</span></code>. Then the interface
|
|
should call:
|
|
</li></ul>
|
|
|
|
<pre class="display">
|
|
<span class="plain">inblorb "Path/This.inform/Release.blurb" "Path/This.inform/Build/output.gblorb"</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<ul class="items"><li> These two filename arguments are the Blurb script for Inblorb to
|
|
follow, which was written by Inform 7 at step 3, and the filename of the Blorb
|
|
file which it should write. Note that the interface should give this the
|
|
extension ".gblorb" if the Glulx setting is in force, and ".zblorb" if
|
|
the Z-machine.
|
|
</li></ul>
|
|
<ul class="items"><li>(6) Like its predecessors, Inblorb can produce error messages, and it returns
|
|
0 (success) or 1 (failure). But the interface doesn't actually need to look
|
|
at that, because Inblorb also produces a much fuller report in the form of
|
|
an HTML page to be displayed on the Problems tab. This is <code class="display"><span class="extract">StatusCblorb.html</span></code>,
|
|
in the project's <code class="display"><span class="extract">Build</span></code> folder. (This is a change made in 2010: in the past,
|
|
the interface simply chose between a generic success and failure page on the
|
|
basis of the return code. The filename <code class="display"><span class="extract">StatusCblorb.html</span></code> is not hard-wired:
|
|
it just happens to be what the Blurb file generated by Inform 7 requests.)
|
|
</li></ul>
|
|
<ul class="items"><li>(7) There are no more tools to call, but the interface has one last duty (if
|
|
Inblorb succeeded) — to move the blorb somewhere sensible on disc, where the
|
|
user can see it. Leaving it where it is will not do — the user never looks
|
|
inside the Build project of a folder, which on Mac OS X, for instance, is
|
|
not even visible. To see what to do, the interface must look at the textual
|
|
output from Inblorb, printed to <code class="display"><span class="extract">stdout</span></code> (of course the interface is free
|
|
to redirect this if it wants to). If Inblorb printed a line in the form:
|
|
</li></ul>
|
|
|
|
<pre class="display">
|
|
<span class="plain">Copy blorb to: [[...]]</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<ul class="items"><li> then the interface should do as it's told. For instance:
|
|
</li></ul>
|
|
|
|
<pre class="display">
|
|
<span class="plain">Copy blorb to: [[/Users/gnelson/Examples/Bronze Materials/Release/Bronze.gblorb]]</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<ul class="items"><li> If Inblorb printed no such line, the interface should put up a Save As...
|
|
dialogue box, and invite the user to choose a destination.
|
|
</li></ul>
|
|
<hr class="tocbar">
|
|
<ul class="toc"><li><i>(This section begins Manual.)</i></li><li><a href="M-tbl.html">Continue with 'The Blurb Language'</a></li></ul><hr class="tocbar">
|
|
<!--End of weave-->
|
|
</main>
|
|
</body>
|
|
</html>
|
|
|