Documentation for the Inform-Blorb frontend, Blorb Resource Compiler, and
Blorb Packager by L. Ross Raszewski, Version .5b 

New in this version: 

bres has been updated with Blorb 2.0 chunks: IFhd, IFmd, Fpsc, and the OGGV
chunk type

The Inform-Blorb system was designed to make it easy to generate blorb files
for inform source code.  The first section of the document describes the
frontend.  Casual users will only need to read this section.
The remaining sections describe in detail the individual tools which make up
this package.

Questions, Bugs, concerns, donations, etc, may be sent to the author:
rraszews@hotmail.com

This program is copyright (c) 2006 by L. Ross Raszewski, but is freely
distributable and usable for all non-commercial applications (contact the
author if you wish to use it for a commerical product.)

iblorbb.zip contains MS-DOS executables for this sytem
iblorbs.zip contains source code for this system

-1. Justification
 Some people have questioned my choice of using separate tools and file
 formats for building blorbs in place of a unified format and single
 program, such as the "blurb" language (created by Graham Nelson for
 describing Blorb files). I thought it was worthwhile explaining myself
 here.
 - Why BLC instead of Blurb?
  blurb is a *descriptive* language. It describes the contents of a blorb
  file. BLC is a *control* language; it gives a set of orders to the
  blorb packager. The blc program, therefore, has no "intrinsic" knowledge
  of blorb itself, other than the general format of the file.
  Thus, if blorb were ever extended to include new resources or filetypes,
  blc could remain completely unchanged. Blurb, on the other hand, would
  need to be updated.  Blurb combines the resource specification
  with the blorb specification. As such, it is not as well suited to a
  two-phase blorbification process as a control language like blc.  A similar
  tact is taken by the "blorbtar" program. A blurb->blc converter will be
  included with iblorb.
 - Why RES instead of blurb?
  The actual resources of a game make up only a subset of what blurb allows.
  Implementign all of Blurb would therefore be overkill. RES is actually
  a simplified subset of Blurb. Blurb is a much more complex language, and
  would require a more complex parser. iblorb started life as a request for
  a painfully simple way of adding blorb resources to inform source, and
  that's what it is
 - Why three programs instead of one?
  I hadn't originally intended to write "front" at all. It's wasteful to
  run all three of the programs it calls (blc, bres, and inform) every time
  you want to compile your program; bres and blc only need to be called
  when the .res file changes (unless the story file is included in the blorb,
  in which case it's necessary to run inform and blc every time you compile,
  but not bres). Were bres and blc combined, it would be impossible to
  bundle game code with resources, as the .bli created by bres is needed
  to compile the inform source; the source code must be compiled _after_ the
  resource file has been processed, but _before_ the blorb is bundled.
 - Why bpal?
  I know of no other tools for constructing blorb palettes.
-1.-1: Survey of other blorbifiers:
  blorbtar, by Evin Roberts
   blorbtar is a blorbifier that uses a tar(1)-like interface. Not being
   saddled with configuration files is generally helpful. If your
   concern is bundling a blorb for an already-written game, this is a very nice
   tool. It does not generate inform headers, and does require that users be
   conversant with tar syntax.
 blurb, by Iain Merrick
   blurb is a blorbifier similar in many respects to iblorb. It uses a blurb
   file for input, and does not call inform in the middle of blorb.  In
   most respects, blurb is indistinguishable from iblorb in terms of
   functionality.
 perlblorb, by Graham Nelson
   perlblorb is much like blurb. Its major limitation is that it was written
   in perl for an Acorn machine, and therefore requires some effort to
   get running on any other machine.

0. The resource control file (.res) format
 The resource control file tells the system what resources you want to
 include in the zcode file.  Each resource line has this format:

 TYPE IDENT FILE

 For example, to add "C:\MyPic.png" to the resources for this story, with the
 inform name of "White_House", the line would be:

 PICTURE White_House C:\MyPic.png

 You can also add other blorb resoruces to this file:
 CODE File
  Tells the resource manager that you want to include the specified
  Z-Code or Glulx file in the blorb-file for this program (If the
  code is included in the blorb, you need only distribute one file
  for your users to get both the game itself and its picture/sound data,
  however, users without a blorb-capable interpreter will not be able to
  play the game)
 COPYRIGHT Text
  The copyright information for the resource file
 AUTHOR Text
  The name of the resource file's author
 NOTE Text
  Any other information you want to include about the resources.
 RELEASE Number
  The release number of this blorb file
 PALETTE file
  Include the pallette from the specified file, which is in blorb palette
  format.
 RESOLUTION file
  Include the resolution table from the specified file, which is in blorb
  resolution format.
 HIGHCOLOR
  Include directions to use a 16-bit palette
 TRUECOLOR
  include directions to use a 32-bit palette
  You can also put comments in the file by startign a line with
  an exclamation point (!)
 FRONTISPIECE name file
  This directive acts identically to PICTURE, but also generates a blorb
  Frontispiece (Fpsc) chunk refering to that picture.  The constant FRONTISPIECE_ib
  will be defined as a synonym for the name.
 HEADER file
  This will include the listed file as an IFhd (header) chunk.
 METADATA file
  This will include the listed file as an IFmd (metadata) chunk.

This is a sample of a resource file:

CODE foo.z5
PICTURE White_House C:\MyPic.png
SOUND Theme_Song C:\Music\theme.mod
SOUND Bang C:\Music\Bang.aif
PICTURE Plover_Egg C:\Pictures\Nature\plover.jpg
AUTHOR L. Ross Raszewski
COPYRIGHT (c) 2000
NOTE The Picture of the white house is a screencap from ZGI.
TRUECOLOR
RELEASE 1
To use the resources in your game, you include the .bli file created by
the system. In the above example, for example, you could do this:

Include "Foo.bli"; ! Created by frontend
Include "Sound";   ! Shameless self promotion
...

PlaySound(Theme_Song);



1. Using the Frontend
 Download and install an inform compiler
 Place the programs "front", "blc", and "bres" in your executable
 search path (That is, the current directory, or one of the directories
 listed by typing "PATH" from a DOS prompt, or "echo $path" from a
 *nix shell)
 The Front-end program must be invoked with at least one argument, but you
 will almost certainyl want more.
 > front foo
 will run the front-end with front.res as the resource definitions file, and
 will produce foo.bli and foo.blb.  (and a complaint from inform)
 All other parameters to front will be passed on to inform.  


 To compile "foo.z5" and "foo.blb" from "foo.inf", using resource file
 "foo.res", showing inform's compilation statistics, do this:

 > front foo foo.inf foo.z5 -s

Frontend assumes that bres, blc, and inform are all present, named thus, and
in the search path.  If there is a file in the current directory called
"infb.rc", it will be consulted first.

An infb.rc file containing these lines:

INFORM  infrmw32
BRES    c:\inform\bres

Will cause front to use "c:\inform\bres" for the resource compiler, and
"infrmw32" as the inform compiler (you can also use this to make your
favorite inform switches the default)



2. Bres: the Blorb Resource Compiler
The format of a bres input file is discussed in section 0.
Bres takes a .res file, and produces two additional files, a BLC
control file, and an inform file (the default extension, .bli,
was chosen to decrease the likilhood of accidentally writing over
one's own source).

Typing bres with no arguments will explain its various invocations

3. BLC: the Blorb Packager
BLC generates a blorb (.blb) file, based on the contents of a blorb
control file (.blc), which is usually produced by bres, but can also be
made by hand.

Each line in a BLC control file describes one chunk of the blorb file, and
has the following format:

Use Number Type Text

Use is the type of resource usage: Pict, Snd, or Exec.  If the chunk is
    not a resource, this should be 0, 1, 2 or 3
    a Use of 0 tells blc that the chunk data is a newline-terminated string
    which follows the chunk type
    a use of 1 tells blc that the chunk data is a 2-byte integer whose
    which appears printed out after the chunk type 
    a Use of 2 tells blc that the chunk data is in a file whose name is a
    newline terminated string which follows the chunk type
    a use of 3 tells blc that the chunk data is a 4-byte integer

Number is the resource number for the chunk, or any number if it is
    not a resource.
Type is the chunk type: JPEG, PNG, FORM (Aiff), MOD, ZCOD, GLUL, ANNO, (c),
    etc.
Text: For a resource, this is the name of the file to be included as this
    chunk's data.  For other chunks, this is the literal text of the chunk,
    which ends at the first newline.

A sample BLC file (based on the example .res file above):

Pict 1 PNG C:\MyPic.png
Snd 3 MOD C:\Music\theme.mod
Snd 4 FORM C:\Music\Bang.aif
Pict 2 JPEG C:\Pictures\Nature\plover.jpg
0 0 AUTH L. Ross Raszewski
0 0 (c) (c) 2000
0 0 ANNO The Picture of the white house is a screencap from ZGI.
1 0 RelN 123
2 0 Plte C:\pictures\nat_pal.plt


4. BPal: The Blorb Palette Editor
BPal is a versatile tool for the creation and manipulation of blorb palette
chunks. The format produced by bpal is identical to the blorb Plte chunk data
segment.  Palettes generated by bpal can be included in a bres resource or
BLC control file as explained above.

BPal's interface is a simple command-line interpreter. The following
functions can be performed:

l      -> load a palette file into bpal for manipulation
i      -> extract the palette from a PNG image if possible
m      -> merge a palette file into the current palette. Entries are
          not duplicated, and the user is warned if some entries were not
          copied due to space limitations (a palette can have no more than
          256 colors according to the blorb standard)
v      -> Toggle output of bpal; in verbose mode, bpal prints confirmation
          messages for most operations. In quiet mode, bpal prints messages
          only on severe errors.
s      -> Save the current palette to a file
a      -> Add a specific RGB color entry to the palette
e      -> Change the value of an entry in the palette
o      -> Organize palette entries by color
d      -> Remove an entry from the palette
c      -> clear the palette
h      -> command summary
q      -> quit

Probably the most useful thing to do with bpal is to extract the palette
from a PNG image; after constructing an image with the optimal palette for
the game (via some graphic manipulation tool), the PNG palette of this image
can be extracted for use in a blorb file.
(One ancient technique for ensuring that images looked correct on an 8-bit
display was to paste all the images from a game onto a single image, and let
the imaging tool construct the optimal palette. This image's palette could
then be used by the production as the palette for the entire game.
Such a method can be used with the images for a blorb file, and
the resulting PNG palette should represent the colors which the
interpreter should render)

To build foo.plt from the palette of image foo.png:

>bpal
bpal: Blorb Palette Editor (Feb  4 2000)
Version .1b by L. Ross Raszewski
Starting command interpreter...
type 'h' for command summary

i foo.png                                       ( import foo.png )
o                                               ( optional; sort the palette )
s foo.plt                                       ( save the palette )
q



5. Bmerge - the blorb merger
 bmerge is designed to take several separate blorb files, and combine them
 into a single blorb.  This is primarily intended to ease distribution;
 you can create several small blorb files by deleting lines from the BLC
 file for a program, then recombine them later. For example:

Exec 0 GLUL C:\test.ulx
Pict 1 PNG C:\MyPic.png
Snd 3 MOD C:\Music\theme.mod
Snd 4 FORM C:\Music\Bang.aif
Pict 2 JPEG C:\Pictures\Nature\plover.jpg
0 0 AUTH L. Ross Raszewski
0 0 (c) (c) 2000
0 0 ANNO The Picture of the white house is a screencap from ZGI.
1 0 RelN 123
2 0 Plte C:\pictures\nat_pal.plt

Suppose this is the BLC file generated for a game. Because blorb files can be
very large, you may prefer to split this into several parts:

Exec 0 GLUL C:\test.ulx
Pict 1 PNG C:\MyPic.png
Pict 2 JPEG C:\Pictures\Nature\plover.jpg
0 0 AUTH L. Ross Raszewski
0 0 (c) (c) 2000
0 0 ANNO The Picture of the white house is a screencap from ZGI.
1 0 RelN 123
2 0 Plte C:\pictures\nat_pal.plt

This blc file will generate a blorb containing only the images, and this:

Exec 0 GLUL C:\test.ulx
Snd 3 MOD C:\Music\theme.mod
Snd 4 FORM C:\Music\Bang.aif
0 0 AUTH L. Ross Raszewski
0 0 (c) (c) 2000
1 0 RelN 123

Contains only the sounds. Both contain the executable code and
supplementary information, and a player could download the first to play
the game with graphics, but not sound, and the second to play the game
with sound but not graphics.

If the player later wants to play the game with all of its multimedia, he
need not download a (very lage) combined file. Instead, he may download the
two independent parts (or however many parts you've split the blorb into),
and use bmerge:

bmerge file1.blb file2.blb out.blb

will combine the blorb files 'file1' and 'file2' into 'out.blb'

If the blorb files given as input contain overlapping chunks (In this example,
both blorb files contain the Glulx resource, and identical AUTH, (c) and RelN
chunks), the user will be prompted to select one of the two versions.

The optional command line parameter -1 or -2 will suppress this prompt;
bmerge -1 file1.blb file2.blb out.blb will merge files 1 and 2, using
resources from file 1 if there is an overlap, and -2 will use resources
from file 2.

You can also use bmerge to distribute updates; you could release a new blorb
file which contains only those resources which have been changed.
bmerge -2 old new out
would create a new file which replaces the resources in 'old' with those
in 'new', leaving the unchanged resources alone.

6. BDiff - Blorb Diff 

Blorb Diff is a program for generating patches to existing blorb files
to include updated information.

bdiff takes two blorb files, and composes a "delta blorb" -- this
is a normal blorb file encapsulating the differences between the two
input blorbs.

Suppose you've released a game in blorb format. Later, you wish to release
a bugfix. Let's say that this bugfix changes one image and a ZCode resource.
If the game is very large, some users may prefer not to download the entire
blorb again.

bdiff mygame_v1.blb mygame_v2.blb patch.blb

The file patch.blb will contain only the game code and the changed picture
(A more useful case would be when you have changed several resources without
noting carefully which have changed.)

Users who already had mygame_v1.blb could reconstruct mygame_v2.blb using
blorb merge:
bmerge -2 mygame_v1.blb patch.blb mygame_patched.blb

(Note: the output of bmerge may not be identical to the original
mygame_v2.blb; blorb diff and blorb merge may re-organize the blorb file
to speed processing. However, the files will contain all the same information
and will operate identically.)

(Another note: If mygame_v1 contains a resource which does not appear
in mygame_v2, that resource will also appear in mygame_patched; blorb
merge will not discard chunks. Presumably, however, any chunk which does
not appear in mygame_v2 is unused, so it can be safely ignored)


Version History:
.1b: First release
.2b: Fixed spurious constant definition for bres CODE directive, added
     makefile, various code cleaning and commenting
.3b: Various code cleaning, added support for RelN, Plte and Reso chunks
.3b+: added bpal version 1.0
.3b++: added bmerge 1.0
.4b: added bdiff
