mirror of
https://github.com/ganelson/inform.git
synced 2024-05-17 08:28:42 +03:00
615 lines
35 KiB
HTML
615 lines
35 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>The Blurb Language</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="../index.html">home</a></li>
|
|
</ul><h2>Compiler</h2><ul>
|
|
<li><a href="../structure.html">structure</a></li>
|
|
<li><a href="../inbuildn.html">inbuild</a></li>
|
|
<li><a href="../inform7n.html">inform7</a></li>
|
|
<li><a href="../intern.html">inter</a></li>
|
|
<li><a href="../services.html">services</a></li>
|
|
<li><a href="../secrets.html">secrets</a></li>
|
|
</ul><h2>Other Tools</h2><ul>
|
|
<li><a href="../inblorbn.html">inblorb</a></li>
|
|
<li><a href="../indocn.html">indoc</a></li>
|
|
<li><a href="../inform6.html">inform6</a></li>
|
|
<li><a href="../inpolicyn.html">inpolicy</a></li>
|
|
<li><a href="../inrtpsn.html">inrtps</a></li>
|
|
</ul><h2>Resources</h2><ul>
|
|
<li><a href="../extensions.html">extensions</a></li>
|
|
<li><a href="../kits.html">kits</a></li>
|
|
</ul><h2>Repository</h2><ul>
|
|
<li><a href="https://github.com/ganelson/inform"><img src="../docs-assets/github.png" height=18> github</a></li>
|
|
</ul><h2>Related Projects</h2><ul>
|
|
<li><a href="../../../inweb/index.html">inweb</a></li>
|
|
<li><a href="../../../intest/index.html">intest</a></li>
|
|
|
|
</ul>
|
|
</nav>
|
|
<main role="main">
|
|
<!--Weave of 'The Blurb Language' generated by Inweb-->
|
|
<div class="breadcrumbs">
|
|
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="index.html">inblorb</a></li><li><a href="index.html#M">Manual</a></li><li><b>The Blurb Language</b></li></ul></div>
|
|
<p class="purpose">A specification for the Blurb language, which describes how to package up a work of interactive fiction.</p>
|
|
|
|
<ul class="toc"><li><a href="M-tbl.html#SP1">§1. What Blurb is</a></li><li><a href="M-tbl.html#SP2">§2. Some simple examples</a></li><li><a href="M-tbl.html#SP7">§7. Specification of the Blurb language</a></li></ul><hr class="tocbar">
|
|
|
|
<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>§1. What Blurb is. </b>"Blurb" is a mini-language for specifying how the materials in a work
|
|
of IF should be packaged up for release. It was originally codified in 2001
|
|
as a standard way to describe how a blorb file should be put together, but
|
|
it was extended in 2005 and again in 2008 so that it could also organise
|
|
accompanying files released along with the blorb.
|
|
</p>
|
|
|
|
<p class="commentary">The original Blurb language was documented in chapter 43 of the DM4
|
|
(i.e., the "Inform Designer's Manual", fourth edition, 2001); for clarity,
|
|
we will call that language "Blurb 2001". Today's Blurb language is a little
|
|
different. Some features of Blurb 2001 are deprecated and no longer used,
|
|
while numerous other syntaxes are new. Because of this the DM4 specification
|
|
is no longer useful, so we will give a full description below of Blurb as
|
|
it currently stands.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>§2. Some simple examples. </b>This first script instructs Inblorb to carry out its mission — it makes a
|
|
simple Blorb wrapping up a story file with bibliographic data, but nothing
|
|
more, and nothing else is released.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> storyfile "/Users/gnelson/Examples/Zinc.inform/Build/output.ulx" include</span>
|
|
<span class="plain-syntax"> ifiction "/Users/gnelson/Examples/Zinc.inform/Metadata.iFiction" include</span>
|
|
</pre>
|
|
<p class="commentary">These two lines tell Inblorb to include the story file and the iFiction
|
|
record respectively.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>§3. </b>A more ambitious Blorb can be made like so:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> storyfile leafname "Audiophilia.gblorb"</span>
|
|
<span class="plain-syntax"> storyfile "/Users/gnelson/Examples/Audiophilia.inform/Build/output.ulx" include</span>
|
|
<span class="plain-syntax"> ifiction "/Users/gnelson/Examples/Audiophilia.inform/Metadata.iFiction" include</span>
|
|
<span class="plain-syntax"> cover "/Users/gnelson/Examples/Audiophilia Materials/Cover.png"</span>
|
|
<span class="plain-syntax"> picture 1 "/Users/gnelson/Examples/Audiophilia Materials/Cover.png"</span>
|
|
<span class="plain-syntax"> sound 3 "/Users/gnelson/Examples/Audiophilia Materials/Sounds/Powermac.aiff"</span>
|
|
<span class="plain-syntax"> sound 4 "/Users/gnelson/Examples/Audiophilia Materials/Sounds/Bach.ogg"</span>
|
|
</pre>
|
|
<p class="commentary">The cover image is included only once, but declaring it as picture 1 makes it
|
|
available to the story file for display internally as well as externally.
|
|
Resource ID 2, apparently skipped, is in fact the story file.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>§4. </b>And here's a very short script, which makes Inblorb generate a solution
|
|
file from the Skein of a project:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> project folder "/Users/gnelson/Examples/Zinc.inform"</span>
|
|
<span class="plain-syntax"> release to "/Users/gnelson/Examples/Zinc Materials/Release"</span>
|
|
<span class="plain-syntax"> solution</span>
|
|
</pre>
|
|
<p class="commentary">This time no blorb file is made. The opening line tells Inblorb which Inform
|
|
project we're dealing with, allowing it to look at the various files inside —
|
|
its Skein, for instance, which is used to create a solution. The second line
|
|
tells Inblorb where to put all of its output — everything it makes. Only
|
|
the third line directly causes Inblorb to do anything.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>§5. </b>More ambitiously, this time we'll make a website for a project, but again
|
|
without making a blorb:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> project folder "/Users/gnelson/Examples/Audiophilia.inform"</span>
|
|
<span class="plain-syntax"> release to "/Users/gnelson/Examples/Audiophilia Materials/Release"</span>
|
|
<span class="plain-syntax"> placeholder [IFID] = "AD5648BA-18A2-48A6-9554-4F6C53484824"</span>
|
|
<span class="plain-syntax"> placeholder [RELEASE] = "1"</span>
|
|
<span class="plain-syntax"> placeholder [YEAR] = "2009"</span>
|
|
<span class="plain-syntax"> placeholder [TITLE] = "Audiophilia"</span>
|
|
<span class="plain-syntax"> placeholder [AUTHOR] = "Graham Nelson"</span>
|
|
<span class="plain-syntax"> placeholder [BLURB] = "A test project for sound effect production."</span>
|
|
<span class="plain-syntax"> template path "/Users/gnelson/Library/Inform/Templates"</span>
|
|
<span class="plain-syntax"> css</span>
|
|
<span class="plain-syntax"> website "Standard"</span>
|
|
</pre>
|
|
<p class="commentary">The first novelty here is the setting of placeholders. These are named pieces
|
|
of text which appear on the website being generated: where the text "[RELEASE]"
|
|
appears in the template, Inblorb writes the value we've set for it, in this
|
|
case "1". Some of these values look like numbers, but to Inblorb they all
|
|
hold text. A few placeholder names are reserved by Inblorb for its own use,
|
|
and it will produce errors if we try to set those, but none of those in
|
|
this example is reserved.
|
|
</p>
|
|
|
|
<p class="commentary">Template paths tell Inblorb where to find templates. Any number of these
|
|
can be set — including none at all, but if so then commands needing a
|
|
named template, like <span class="extract"><span class="extract-syntax">website</span></span>, can't be used. Inblorb looks for any
|
|
template it needs by trying each template path in turn (the earliest
|
|
defined having the highest priority). The blurb files produced by <span class="extract"><span class="extract-syntax">inform7</span></span>
|
|
in its <span class="extract"><span class="extract-syntax">-release</span></span> mode contain a chain of three template paths, for the
|
|
individual project folder, the user's library of installed templates, and
|
|
the built-in stock inside the Inform user interface application,
|
|
respectively.
|
|
</p>
|
|
|
|
<p class="commentary">The command <span class="extract"><span class="extract-syntax">css</span></span> tells Inblorb that it is allowed to use CSS styles to
|
|
make its web pages more appealing to look at: this results in generally
|
|
better HTML, easier to use in other contexts, too.
|
|
</p>
|
|
|
|
<p class="commentary">All of that set things up so that the <span class="extract"><span class="extract-syntax">website</span></span> command could be used,
|
|
which actually does something — it creates a website in the release-to
|
|
location, taking its design from the template named. If we were to add
|
|
any of these commands —
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> source public</span>
|
|
<span class="plain-syntax"> solution public</span>
|
|
<span class="plain-syntax"> ifiction public</span>
|
|
</pre>
|
|
<p class="commentary">— then the website would be graced with these additions.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP6" class="paragraph-anchor"></a><b>§6. </b>The previous examples all involved Inform projects, but Inblorb can also
|
|
deal with stand-alone files of Inform source text — notably extensions.
|
|
For example, here we make a website out of an extension:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> release to "Test Site"</span>
|
|
<span class="plain-syntax"> placeholder [TITLE] = "Locksmith"</span>
|
|
<span class="plain-syntax"> placeholder [AUTHOR] = "Emily Short"</span>
|
|
<span class="plain-syntax"> placeholder [RUBRIC] = "Implicit handling of doors and... (...and so on)"</span>
|
|
<span class="plain-syntax"> template path "/Users/gnelson/Library/Inform/Templates"</span>
|
|
<span class="plain-syntax"> css</span>
|
|
<span class="plain-syntax"> release file "style.css" from "Extended"</span>
|
|
<span class="plain-syntax"> release file "index.html" from "Extended"</span>
|
|
<span class="plain-syntax"> release file "Extensions/Emily Short/Locksmith.i7x"</span>
|
|
<span class="plain-syntax"> release source "Extensions/Emily Short/Locksmith.i7x" using "extsrc.html" from "Extended"</span>
|
|
</pre>
|
|
<p class="commentary">This time we're using a template called "Extended", and the script tells
|
|
Inblorb exactly what to do with it. The "release file... from..." command
|
|
tells Inblorb to extract the named file from this template and to copy it
|
|
into the release folder — if it's a ".html" file, placeholders are
|
|
substituted with their values. The simpler form, "release file ...", just
|
|
tells Inblorb to copy that actual file — here, it puts a copy of the
|
|
extension itself into the release folder. The final line produces a run
|
|
of pages, in all likelihood, for the source and documentation of the
|
|
extension, with the design drawn from "Extended" again.
|
|
</p>
|
|
|
|
<p class="commentary">("Extended" isn't supplied inside Inform; it's a template we're using to
|
|
help generate the Inform website, rather than something meant for end users.
|
|
There's nothing very special about it, in any case.)
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP7" class="paragraph-anchor"></a><b>§7. Specification of the Blurb language. </b>A blorb script should be a text file, using the Unicode character set and
|
|
encoded as UTF-8 without a byte order marker — in other words, a plain
|
|
text file. It consists of lines of up to 10239 bytes in length each,
|
|
divided by any of the four line-end markers in common use (<span class="extract"><span class="extract-syntax">CR</span></span>, <span class="extract"><span class="extract-syntax">LF</span></span>,
|
|
<span class="extract"><span class="extract-syntax">CR LF</span></span> or <span class="extract"><span class="extract-syntax">LF CR</span></span>), though the same line-end marker should be used
|
|
throughout the file.
|
|
</p>
|
|
|
|
<p class="commentary">Each command occupies one and only one line of text. (In Blorb 2001, the
|
|
now-deprecated <span class="extract"><span class="extract-syntax">palette</span></span> command could occupy multiple lines, but Inblorb
|
|
will choke on such a usage.) Lines are permitted to be empty or to contain
|
|
only white space. Lines whose first non-white-space character is an
|
|
exclamation mark are treated as comments, that is, ignored. "White space"
|
|
means spaces and tab characters. An entirely empty blurb file, containing
|
|
nothing but white space, is perfectly legal though useless.
|
|
</p>
|
|
|
|
<p class="commentary">In the following description:
|
|
</p>
|
|
|
|
<p class="commentary"><span class="extract"><span class="extract-syntax"><string></span></span> means any text within double-quotes, not
|
|
containing either double-quote or new-line characters, of up to 2048 bytes.
|
|
</p>
|
|
|
|
<p class="commentary"><span class="extract"><span class="extract-syntax"><filename></span></span> means any double-quoted filename.
|
|
</p>
|
|
|
|
<p class="commentary"><span class="extract"><span class="extract-syntax"><number></span></span> means a decimal number in the range 0 to 32767.
|
|
</p>
|
|
|
|
<p class="commentary"><span class="extract"><span class="extract-syntax"><id></span></span> means either nothing at all, or a <span class="extract"><span class="extract-syntax"><number></span></span>,
|
|
or a sequence of up to 20 letters, digits or underscore characters <span class="extract"><span class="extract-syntax">_</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary"><span class="extract"><span class="extract-syntax"><dim></span></span> indicates screen dimensions, and must take the form
|
|
<span class="extract"><span class="extract-syntax"><number></span></span><span class="extract"><span class="extract-syntax">x</span></span><span class="extract"><span class="extract-syntax"><number></span></span>.
|
|
</p>
|
|
|
|
<p class="commentary"><span class="extract"><span class="extract-syntax"><ratio></span></span> is a fraction in the form
|
|
<span class="extract"><span class="extract-syntax"><number></span></span>/<span class="extract"><span class="extract-syntax"><number></span></span>. 0/0 is legal but
|
|
otherwise both numbers must be positive.
|
|
</p>
|
|
|
|
<p class="commentary"><span class="extract"><span class="extract-syntax"><colour></span></span> is a colour expressed as six hexadecimal digits,
|
|
as in some HTML tags: for instance <span class="extract"><span class="extract-syntax">F5DEB3</span></span> is the colour of wheat, with red
|
|
value <span class="extract"><span class="extract-syntax">F5</span></span> (on a scale <span class="extract"><span class="extract-syntax">00</span></span>, none, to <span class="extract"><span class="extract-syntax">FF</span></span>, full), green value <span class="extract"><span class="extract-syntax">DE</span></span> and blue
|
|
value <span class="extract"><span class="extract-syntax">B3</span></span>. Hexadecimal digits may be given in either upper or lower case.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP8" class="paragraph-anchor"></a><b>§8. </b>The full set of commands is as follows. First, core commands for making
|
|
a blorb:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> author <string></span>
|
|
</pre>
|
|
<p class="commentary">Adds this author name to the file.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> copyright <string></span>
|
|
</pre>
|
|
<p class="commentary">Adds this copyright declaration to the blorb file. It would normally consist of
|
|
short text such as "(c) J. Mango Pineapple 2007" rather than a lengthy legal
|
|
discourse.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> release <number></span>
|
|
</pre>
|
|
<p class="commentary">Gives this release number to the blorb file.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> auxiliary <filename> <string></span>
|
|
</pre>
|
|
<p class="commentary">Tells us that an auxiliary file — for instance, a PDF manual — is associated
|
|
with the release but will not be embedded directly into the blorb file. For
|
|
instance,
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> auxiliary "map.png" "Black Pete's treasure map"</span>
|
|
</pre>
|
|
<p class="commentary">The string should be a textual description of the contents. Every auxiliary
|
|
file should have a filename including an extension usefully describing its
|
|
format, as in ".png": if there is no extension, then the auxiliary resource
|
|
is assumed to be a mini-website housed in a subfolder with this name.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> ifiction <filename> include</span>
|
|
</pre>
|
|
<p class="commentary">The file should be a valid iFiction record for the work. This is an XML file
|
|
specified in the Treaty of Babel, a cross-IF-system standard for specifying
|
|
bibliographic data; it will be embedded into the blorb.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> storyfile <filename> ... unsupported by Inblorb</span>
|
|
<span class="plain-syntax"> storyfile <filename> include</span>
|
|
</pre>
|
|
<p class="commentary">Specifies the filename of the story file which these resources are being
|
|
attached to. Blorb 2001 allowed for blorbs to be made which held everything
|
|
to do with the release except the story file; that way a release
|
|
might consist of one story file plus one Blorb file containing its pictures
|
|
and sounds. The Blorb file would then contain a note of the release number,
|
|
serial code and checksum of the associated story file so that an
|
|
interpreter can try to match up the two files at run-time. If the <span class="extract"><span class="extract-syntax">include</span></span>
|
|
option is used, however, the entire story file is embedded within the Blorb
|
|
file, so that game and resources are all bound up in one single file.
|
|
Inblorb always does this, and does not support <span class="extract"><span class="extract-syntax">storyfile</span></span> without
|
|
<span class="extract"><span class="extract-syntax">include</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP9" class="paragraph-anchor"></a><b>§9. </b>Second, now-deprecated commands describing our ideal screen display:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> palette 16 bit ... unsupported by Inblorb</span>
|
|
<span class="plain-syntax"> palette 32 bit ... unsupported by Inblorb</span>
|
|
<span class="plain-syntax"> palette { <colour-1> ... <colour-N> } ... unsupported by Inblorb</span>
|
|
</pre>
|
|
<p class="commentary">Blorb allows designers to signal to the interpreter that a particular
|
|
colour-scheme is in use. The first two options simply suggest that the
|
|
pictures are best displayed using at least 16-bit, or 32-bit, colours. The
|
|
third option specifies colours used in the pictures in terms of
|
|
red/green/blue levels, and the braces allow the sequence of colours to
|
|
continue over many lines. At least one and at most 256 colours may be
|
|
defined in this way. This is only a "clue" to the interpreter; see the
|
|
Blorb specification for details.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> resolution <dim> ... unsupported by Inblorb</span>
|
|
<span class="plain-syntax"> resolution <dim> min <dim> ... unsupported by Inblorb</span>
|
|
<span class="plain-syntax"> resolution <dim> max <dim> ... unsupported by Inblorb</span>
|
|
<span class="plain-syntax"> resolution <dim> min <dim> max <dim> ... unsupported by Inblorb</span>
|
|
</pre>
|
|
<p class="commentary">Allows the designer to signal a preferred screen size, in real pixels, in
|
|
case the interpreter should have any choice over this. The minimum and
|
|
maximum values are the extreme values at which the designer thinks the game
|
|
will be playable: they're optional, the default values being 0 by 0 and
|
|
infinity by infinity.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP10" class="paragraph-anchor"></a><b>§10. </b>Third, commands for adding audiovisual resources:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> sound <id> <filename></span>
|
|
<span class="plain-syntax"> sound <id> <filename> repeat <number> ... unsupported by Inblorb</span>
|
|
<span class="plain-syntax"> sound <id> <filename> repeat forever ... unsupported by Inblorb</span>
|
|
<span class="plain-syntax"> sound <id> <filename> music ... unsupported by Inblorb</span>
|
|
<span class="plain-syntax"> sound <id> <filename> song ... unsupported by Inblorb</span>
|
|
</pre>
|
|
<p class="commentary">Tells us to take a sound sample from the named file and make it the sound
|
|
effect with the given number. Most forms of <span class="extract"><span class="extract-syntax">sound</span></span> are now deprecated:
|
|
repeat information (the number of repeats to be played) is meaningful
|
|
only with Z-machine version 3 story files using sound effects, and Inform 7
|
|
does not generate those; the <span class="extract"><span class="extract-syntax">music</span></span> and <span class="extract"><span class="extract-syntax">song</span></span> keywords specify unusual
|
|
sound formats. Nowadays the straight <span class="extract"><span class="extract-syntax">sound</span></span> command should always
|
|
be used regardless of format.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> picture <id> <filename></span>
|
|
<span class="plain-syntax"> picture <id> <filename> scale <ratio> ... unsupported by Inblorb</span>
|
|
<span class="plain-syntax"> picture <id> <filename> scale min <ratio> ... unsupported by Inblorb</span>
|
|
<span class="plain-syntax"> picture <id> <filename> scale <ratio> min <ratio> ... unsupported by Inblorb</span>
|
|
</pre>
|
|
<p class="commentary">(and so on) is a similar command for images. In 2001, the image file was required
|
|
to be a PNG, but it can now alternatively be a JPEG.
|
|
</p>
|
|
|
|
<p class="commentary">Optionally, the designer can specify a scale factor at which the
|
|
interpreter will display the image — or, alternatively, a range of
|
|
acceptable scale factors, from which the interpreter may choose its own
|
|
scale factor. (By default an image is not scaleable and an interpreter must
|
|
display it pixel-for-pixel.) There are three optional scale factors given:
|
|
the preferred scale factor, the minimum and the maximum allowed. The
|
|
minimum and maximum each default to the preferred value if not given, and
|
|
the default preferred scale factor is 1. Scale factors are expressed as
|
|
fractions: so for instance,
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> picture "flag/png" scale 3/1</span>
|
|
</pre>
|
|
<p class="commentary">means "always display three times its normal size", whereas
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> picture "backdrop/png" scale min 1/10 max 8/1</span>
|
|
</pre>
|
|
<p class="commentary">means "you can display this anywhere between one tenth normal size and
|
|
eight times normal size, but if possible it ought to be just its normal
|
|
size".
|
|
</p>
|
|
|
|
<p class="commentary">Inblorb does not support any of the scaled forms of <span class="extract"><span class="extract-syntax">picture</span></span>. As with
|
|
the exotic forms of <span class="extract"><span class="extract-syntax">sound</span></span>, they now seem pass\'e. We no longer need to
|
|
worry too much about the size of the blorb file, nor about screens with
|
|
very low resolution; an iPhone today has a screen resolution close to that
|
|
of a typical desktop of 2001.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> cover <filename></span>
|
|
</pre>
|
|
<p class="commentary">specifies that this is the cover art; it must also be declared with a
|
|
<span class="extract"><span class="extract-syntax">picture</span></span> command in the usual way, and must have picture ID 1.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP11" class="paragraph-anchor"></a><b>§11. </b>Three commands help us to specify locations.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> project folder <filename></span>
|
|
</pre>
|
|
<p class="commentary">Tells Inblorb to look for associated resources, such as the Skein file,
|
|
within this Inform project.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> release to <filename></span>
|
|
</pre>
|
|
<p class="commentary">Tells Inblorb that all of its output should go into this folder. (Well,
|
|
except that the blorb file itself will be written to the location specified
|
|
in the command line arguments, but see the description above of how Inblorb
|
|
then contrives to move it.) The folder must already exist, and Inblorb
|
|
won't create it. Under some circumstances Inform will seem to be creating
|
|
the release folder if it doesn't already exist, but that's always the work
|
|
of <span class="extract"><span class="extract-syntax">inform7</span></span>, not Inblorb.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> template path <filename></span>
|
|
</pre>
|
|
<p class="commentary">Sets a search path for templates — a folder in which to look for them. There
|
|
can be any number of template paths set, and Inblorb checks them in order
|
|
of declaration (i.e., most important first).
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP12" class="paragraph-anchor"></a><b>§12. </b>Next we come to commands for specifying what Inblorb should release.
|
|
At present it has seven forms of output: Blorb file, solution file, source
|
|
text, iFiction record, miscellaneous file, website and interpreter.
|
|
</p>
|
|
|
|
<p class="commentary">No explicit single command causes a Blorb file to be generated; it will be
|
|
made automatically if one of the above commands to include the story file,
|
|
pictures, etc., is present in the script, and otherwise not generated.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> solution</span>
|
|
<span class="plain-syntax"> solution public</span>
|
|
</pre>
|
|
<p class="commentary">causes a solution file to be generated in the release folder. The mechanism
|
|
for this is described in "Writing with Inform". The difference between
|
|
the two commands affects only a website also being made, if one is: a
|
|
public solution will be included in its links, thus being made available
|
|
to the public who read the website.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> ifiction</span>
|
|
<span class="plain-syntax"> ifiction public</span>
|
|
</pre>
|
|
<p class="commentary">is similar, but for the iFiction record of the project.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> source</span>
|
|
<span class="plain-syntax"> source public</span>
|
|
</pre>
|
|
<p class="commentary">is again similar, but here there's a twist. If the source is public, then
|
|
Inblorb doesn't just include it on a website: it generates multiple HTML
|
|
pages to show it off in HTML form, as well as including the plain text
|
|
original.
|
|
</p>
|
|
|
|
<p class="commentary">Miscellaneous files can be released like so:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> release file <filename></span>
|
|
</pre>
|
|
<p class="commentary">Here Inblorb acts as no more than a file-copy utility; a verbatim copy of
|
|
the named file is placed in the release folder.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP13" class="paragraph-anchor"></a><b>§13. </b>Finally we come to web pages.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> css</span>
|
|
</pre>
|
|
<p class="commentary">enables the use of CSS-defined styles within the HTML generated by Inblorb.
|
|
This has an especially marked effect when Inblorb is generating HTML
|
|
versions of Inform source text, and is a good thing. Unless there is
|
|
reason not to, every blurb script generating websites ought to contain
|
|
this command.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> release file <filename> from <template></span>
|
|
</pre>
|
|
<p class="commentary">causes the named file to be found from the given template. If it can't be
|
|
found in that template, Inblorb tries to find it from a template called
|
|
"Standard". If it isn't there either, or Inblorb can't find any template
|
|
called "Standard" in any of its template paths (see above), then an
|
|
error message is produced. But if all goes well the file is copied into
|
|
the release folder. If it has the file extension ".html" (in lower case,
|
|
and using that exact form, i.e., not ".HTM" or some other variation)
|
|
then any placeholders in the file will be expanded with their values.
|
|
A few reserved placeholders have special effects, causing Inblorb to
|
|
expand interesting text in their places — see "Writing with Inform"
|
|
for more on this.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> release source <filename>| using |<filename> from <template></span>
|
|
</pre>
|
|
<p class="commentary">makes Inblorb convert the Inform source text in the first filename into a
|
|
suite of web pages using the style of the given file from the given template.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> website <template></span>
|
|
</pre>
|
|
<p class="commentary">saves the best until last: it makes a complete website for an Inform project,
|
|
using the named template. This means that the CSS file is copied into place
|
|
(assuming <span class="extract"><span class="extract-syntax">css</span></span> is used), the "index.html" is released from the template,
|
|
the source of the project is run through <span class="extract"><span class="extract-syntax">release source</span></span> using "source.html"
|
|
from the template (assuming <span class="extract"><span class="extract-syntax">source public</span></span> is used), and any extra files
|
|
specified in the template's "(extras.txt)" are released as well. See
|
|
"Writing with Inform" for more.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP14" class="paragraph-anchor"></a><b>§14. </b>An optional addition for a website is to incorporate a playable-in-browser
|
|
form of the story, by base64-encoding the story file within a Javascript
|
|
wrapper, then calling an interpreter such as Parchment.
|
|
</p>
|
|
|
|
<p class="commentary">The encoding part is taken care of by:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> base64 <filename> to <filename></span>
|
|
</pre>
|
|
<p class="commentary">This performs an RFC 1113-standard encoding on the binary file in (almost
|
|
always our story file) into a textual base-64 file out. The file is topped
|
|
and tailed with the text in placeholders <span class="extract"><span class="extract-syntax">[BASESIXTYFOURTOP]</span></span> and <span class="extract"><span class="extract-syntax">[BASESIXTYFOURTAIL]</span></span>,
|
|
allowing Javascript wrapper code to surround the encoded data.
|
|
</p>
|
|
|
|
<p class="commentary">The interpreter itself is copied into place in the Release folder in a
|
|
process rather like the construction of a website from a template. The
|
|
necessary blurb command is:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> interpreter <interpreter-name> <vm-letter></span>
|
|
</pre>
|
|
<p class="commentary">Interpreter names are like template names; Inform often uses "Parchment".
|
|
The VM letter should be "g" if we need this to handle a Glulx story file
|
|
(blorbed up), or "z" if we need it to handle a Z-machine story file.
|
|
(This needs to be said because Inform doesn't have a way of knowing which
|
|
formats a given interpreter can handle; so it has to leave checking to
|
|
Inblorb to do. Thus, if an Inform user tries to release a Z-machine-only
|
|
interpreter with a Glulx story file, it's Inblorb which issues the error,
|
|
not Inform itself.)
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP15" class="paragraph-anchor"></a><b>§15. </b>Finally (really finally this time), three commands to do with the
|
|
"status" page, an HTML page written by Inblorb to report back on
|
|
what it has done. If requested, this is constructed for reading within
|
|
the Inform application — it is not a valid HTML page in other
|
|
contexts, and expects to have access to Javascript functions provided
|
|
by Inform, and so on.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> status <template> <filename></span>
|
|
<span class="plain-syntax"> status alternative <link to Inform documentation></span>
|
|
<span class="plain-syntax"> status instruction <link to Inform source text></span>
|
|
</pre>
|
|
<p class="commentary">The first simply requests the page to be made. It's made from a single
|
|
template file, but in exactly the same way that website pages are generated
|
|
from website templates — that is, placeholders are expanded. The second
|
|
filename is where to write the result.
|
|
</p>
|
|
|
|
<p class="commentary">The other two commands allow Inform to insert information which Inblorb
|
|
otherwise has no access to: options for fancy release tricks not currently
|
|
being used (with links to the documentation on them), and links to source
|
|
text "Release along with..." sentences.
|
|
</p>
|
|
|
|
<nav role="progress"><div class="progresscontainer">
|
|
<ul class="progressbar"><li class="progressprev"><a href="M-ui.html">❮</a></li><li class="progresscurrentchapter">M</li><li class="progresssection"><a href="M-ui.html">ui</a></li><li class="progresscurrent">tbl</li><li class="progresssection"><a href="M-rc.html">rc</a></li><li class="progresschapter"><a href="1-bsc.html">1</a></li><li class="progresschapter"><a href="2-bw.html">2</a></li><li class="progresschapter"><a href="3-rls.html">3</a></li><li class="progressnext"><a href="M-rc.html">❯</a></li></ul></div>
|
|
</nav><!--End of weave-->
|
|
|
|
</main>
|
|
</body>
|
|
</html>
|
|
|