<ulclass="crumbs"><li><ahref="../webs.html">Source</a></li><li><ahref="../other.html">Other Tools</a></li><li><ahref="index.html">inblorb</a></li><li><ahref="index.html#M">Manual</a></li><li><b>The Blurb Language</b></li></ul><pclass="purpose">A specification for the Blurb language, which describes how to package up a work of interactive fiction.</p>
<ulclass="toc"><li><ahref="#SP1">§1. What Blurb is</a></li><li><ahref="#SP2">§2. Some simple examples</a></li><li><ahref="#SP7">§7. Specification of the Blurb language</a></li></ul><hrclass="tocbar">
<pclass="inwebparagraph"><aid="SP1"></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>
<pclass="inwebparagraph">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>
<pclass="inwebparagraph"><aid="SP2"></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
<spanclass="plain">release source "Extensions/Emily Short/Locksmith.i7x" using "extsrc.html" from "Extended"</span>
</pre>
<pclass="inwebparagraph">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>
<pclass="inwebparagraph">("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>
<pclass="inwebparagraph"><aid="SP7"></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 (<codeclass="display"><spanclass="extract">CR</span></code>, <codeclass="display"><spanclass="extract">LF</span></code>,
<codeclass="display"><spanclass="extract">CR LF</span></code> or <codeclass="display"><spanclass="extract">LF CR</span></code>), though the same line-end marker should be used
throughout the file.
</p>
<pclass="inwebparagraph">Each command occupies one and only one line of text. (In Blorb 2001, the
now-deprecated <codeclass="display"><spanclass="extract">palette</span></code> 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>
<pclass="inwebparagraph">In the following description:
</p>
<pclass="inwebparagraph"><codeclass="display"><spanclass="extract"><string></span></code> means any text within double-quotes, not
containing either double-quote or new-line characters, of up to 2048 bytes.
</p>
<pclass="inwebparagraph"><codeclass="display"><spanclass="extract"><filename></span></code> means any double-quoted filename.
</p>
<pclass="inwebparagraph"><codeclass="display"><spanclass="extract"><number></span></code> means a decimal number in the range 0 to 32767.
</p>
<pclass="inwebparagraph"><codeclass="display"><spanclass="extract"><id></span></code> means either nothing at all, or a <codeclass="display"><spanclass="extract"><number></span></code>,
or a sequence of up to 20 letters, digits or underscore characters <codeclass="display"><spanclass="extract">_</span></code>.
</p>
<pclass="inwebparagraph"><codeclass="display"><spanclass="extract"><dim></span></code> indicates screen dimensions, and must take the form
<pclass="inwebparagraph"><codeclass="display"><spanclass="extract"><ratio></span></code> is a fraction in the form
<codeclass="display"><spanclass="extract"><number></span></code>/<codeclass="display"><spanclass="extract"><number></span></code>. 0/0 is legal but
otherwise both numbers must be positive.
</p>
<pclass="inwebparagraph"><codeclass="display"><spanclass="extract"><colour></span></code> is a colour expressed as six hexadecimal digits,
as in some HTML tags: for instance <codeclass="display"><spanclass="extract">F5DEB3</span></code> is the colour of wheat, with red
value <codeclass="display"><spanclass="extract">F5</span></code> (on a scale <codeclass="display"><spanclass="extract">00</span></code>, none, to <codeclass="display"><spanclass="extract">FF</span></code>, full), green value <codeclass="display"><spanclass="extract">DE</span></code> and blue
value <codeclass="display"><spanclass="extract">B3</span></code>. Hexadecimal digits may be given in either upper or lower case.
</p>
<pclass="inwebparagraph"><aid="SP8"></a><b>§8. </b>The full set of commands is as follows. First, core commands for making
a blorb:
</p>
<preclass="display">
<spanclass="plain">author <string></span>
</pre>
<pclass="inwebparagraph">Adds this author name to the file.
<spanclass="plain">sound <id><filename> repeat <number> ... unsupported by Inblorb</span>
<spanclass="plain">sound <id><filename> repeat forever ... unsupported by Inblorb</span>
<spanclass="plain">sound <id><filename> music ... unsupported by Inblorb</span>
<spanclass="plain">sound <id><filename> song ... unsupported by Inblorb</span>
</pre>
<pclass="inwebparagraph">Tells us to take a sound sample from the named file and make it the sound
effect with the given number. Most forms of <codeclass="display"><spanclass="extract">sound</span></code> 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 <codeclass="display"><spanclass="extract">music</span></code> and <codeclass="display"><spanclass="extract">song</span></code> keywords specify unusual
sound formats. Nowadays the straight <codeclass="display"><spanclass="extract">sound</span></code> command should always
<pclass="inwebparagraph">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 <codeclass="display"><spanclass="extract">css</span></code> is used), the "index.html" is released from the template,
the source of the project is run through <codeclass="display"><spanclass="extract">release source</span></code> using "source.html"
from the template (assuming <codeclass="display"><spanclass="extract">source public</span></code> is used), and any extra files
specified in the template's "(extras.txt)" are released as well. See
"Writing with Inform" for more.
</p>
<pclass="inwebparagraph"><aid="SP14"></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>
<pclass="inwebparagraph">The encoding part is taken care of by:
</p>
<preclass="display">
<spanclass="plain">base64 <filename> to <filename></span>
</pre>
<pclass="inwebparagraph">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 <codeclass="display"><spanclass="extract">[BASESIXTYFOURTOP]</span></code> and <codeclass="display"><spanclass="extract">[BASESIXTYFOURTAIL]</span></code>,
allowing Javascript wrapper code to surround the encoded data.
</p>
<pclass="inwebparagraph">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
<ulclass="toc"><li><ahref="M-ui.html">Back to 'Using Inblorb'</a></li><li><ahref="M-rc.html">Continue with 'Reference Card'</a></li></ul><hrclass="tocbar">