Yonk 1.0b6  28 August 2003


What is Yonk?

Yonk is an IDE ("Incomplete" Development Environment) for the Inform
programming language.  It's designed to make life easier for text
adventure authors, by presenting maps and object relationships visually,
keeping track of some Inform and library coding rules, and reducing the
effort that goes into boring or repetitive tasks.  There are a handful
of "Visual Inform" editors for Windows and other platforms, but as far
as I know Yonk is the first of its kind for the Macintosh.

Yonk assumes that you're already familiar with the Inform programming
language. If not, the best place to start is with the Inform Designer's
Manual, available online at <http://www.inform-fiction.org/manual/>.
Yonk manages some of the details for you when it comes to writing Inform
code, but knowing the language is essential.

Yonk 1.0b4 is a beta test release of the program, and is definitely a
work in progress.  I've tested it against a variety of source files from
the IF-Archive library, and Yonk appears to handle them well -- but in
order to test more thoroughly I'd need to write several interactive
fiction games, and for the most part my talents lie elsewhere.  :-)  I'm
looking for feedback on all aspects of the program, from design to
interface to any bugs encountered.

Yonk is free software; see the About box for details.



What isn't Yonk?

Yonk isn't a general-purpose text editor.  Yonk is designed from the
ground up to read and write Inform -- it reads and writes ordinary text
files, but it converts those files to an internal data structure based
on Inform source code.  Yonk will complain if you feed it a file that
doesn't look like Inform code.

Yonk is not lint -- it doesn't check the syntax of your Inform code,
except at a very high level, and relies on the compiler to catch any
errors.  If you type a letter to Grandma where Yonk expects you to type
source code, Yonk won't know the difference (and will helpfully append a
comma or semicolon to your letter).

Yonk is not an Inform interpreter or a Z-machine.  Yonk will sometimes
display Inform source code in ways that simulate the player experience,
but it doesn't actually interpret the source code or play the game.



Using Yonk

Yonk's main window is a hierarchical list.  Every entry in this list is
a room, object, verb, variable, subroutine or other declaration from
your Inform source code.  You can change the order of items in this list
(or put them inside each other) by clicking and dragging;
double-clicking an item will open an editor window, allowing you to see
and change its contents.

Yonk's main window fully supports Cut, Copy and Paste, and puts Inform
source code on the Clipboard.  If you copy an object that has other
items inside it, the Clipboard will contain the source code for all of
these items.  You can drag an item to the desktop and create a text
clipping, or drag it to a text editor, make changes there, and then drag
the text back into Yonk.

Yonk's second window is a map and source code viewer, which shows the
currently selected item.  When a room is selected, the viewer displays
the available exits as buttons, and shows the text the player will see
when entering the room (or the Inform source code which prints that
text).  If you click a button, the viewer will show you source code for
that exit -- or, if the exit leads directly to another room (or a door),
Yonk will "go there" and display the new room.

For all other items, the viewer displays the item's Inform source code.



Input and Output

Yonk reads and writes text files containing Inform source code.  Yonk
isn't really a text editor, though -- it reads the Inform source code
into its own internal data structures, and then converts that data back
to Inform code for the output.  As a result, Yonk tends to ignore
comments and delete whitespace when reading a file, and it's always a
good idea to keep backup copies of any files you edit with Yonk.  (Yonk
won't overwrite a file unless it detects that Yonk wrote the file in
the first place, or unless you tell it to do so.)

When Yonk reads a source file, it breaks the file up into separate
declarations and builds these declarations into a hierarchical list.
Yonk understands Inform at a very high level:  It knows that everything
between "[" and "]" is a subroutine, for example, and that the
subroutine's name is the first word after the opening bracket -- but it
doesn't otherwise understand what it's reading.  Yonk uses similar
tactics to read objects, classes, verbs, and other declarations.

Yonk doesn't read the contents of "include" files -- it understands that
you're including a file, but it doesn't learn anything about the
contents.  If you declare attributes or classes in an included file,
Yonk won't know they exist, which will make it slightly harder to work
with objects that depend on those declarations.  (Yonk will quietly
assume that attributes or classes are declared externally, if they're
used by a later object and it hasn't seen them before.)

Yonk also treats each instruction to the compiler (the "Switches"
statement, conditional directives such as #ifdef, "Replace" commands,
"Include" commands, etc.) as a separate declaration, and reads the
instruction literally.  If Yonk is baffled by a line of your input file,
but can still tell that it's valid Inform source code, it will read that
line as an instruction to the compiler.



Editing

Once a source file is loaded into memory, you can double-click a
declaration and open an editor window, or create a new declaration by
selecting from the Inform menu.  Editor windows are fill-in-the-blank
templates for source code; Yonk supplies the surrounding commas,
semicolons, words like "with" and "has", quotation marks (in some
contexts) and other punctuation, and leaves it to you to write the code
that goes in between.  The source code viewer shows the resulting code,
and allows you to check its syntax.

For object or class declarations, the editor is a window with two
panels.  The first panel displays the object's properties and
attributes, and allows you to edit properties by double-clicking on
them, or toggle attributes by clicking their checkboxes.  The editor
shows the attribute settings for an object or class based on the
settings of its parent class, and will automatically handle whether an
object has light, has ~light, or says nothing about light and inherits
the setting of its parent classes.  (If Yonk doesn't know the parent
class, it will show two checkboxes for each attribute, so that you can
explicitly state whether the object has light, has ~light, or says
nothing.)

The second panel of the object editor displays a compass rose of exits,
and provides a pull-down menu of available choices for each exit.  You
can set an exit to another room (or to a door) by selecting a choice
from the pull-down menu, or you can write Inform code for the exit by
double-clicking in the list of exits.  (You can also create and edit
exits via the properties list on the first panel.)



Rooms, Doors and Objects

Yonk does some fancy guesswork to decide what objects are "rooms" when
it's building a list of potential exits (or when displaying rooms in the
map view), but it's hard for a program to tell the difference between
rooms and other objects in Inform.  A room with no exits, that's only
visited when the player is moved there by an Inform subroutine, is
nearly impossible to distinguish from an ordinary object that the player
can pick up and carry around (and potentially an object could be coded
as both, in the case of a featureless white cube or a magic lamp).

Yonk believes that a "room" is an object with one or more of the
following:

  *  One of the twelve direction properties ("n_to", "s_to", etc.). 
  *  The "cant_go" property.
  *  A name that ends in "room" or "place".
  *  A short name that ends in "room" or "place".
  *  A class whose name ends in "room" or "place".

("Name" and "short name" here refer to the first line of the object
declaration, not to object properties.)  If an object meets any of the
above criteria, then Yonk will list it as a potential exit in the object
editor, and display it as a room in the map viewer.

Yonk also believes that a "door" is an object with a "door_to" or
"door_dir" property.  When displaying a door, the map viewer does its
best to provide a continuous map of connected rooms:  It does a reverse
lookup to find any objects that exit to that door, and displays any
found objects as "exits" from the door. For example, if an object
My_Room has the property "s_to My_Door", then the viewer shows My_Door
with an exit leading north to My_Room.

The map editor also scans the text of the door's "door_dir" property,
finds any exits that are mentioned there, and attaches the text from the
door's "door_to" property to those exit buttons.  This is the map
editor's second choice, though; if it finds a room with an exit leading
to the door, it'll show that instead.

Yonk believes that any object can potentially be a container of other
objects, and it allows you to put any declaration "inside" an object.
This means you can do things that don't make metaphysical sense, like
having a "living room" that contains a couch, a lamp and a global
variable, but it also gives you complete control over the order of
declarations -- you may want to put #ifdef statements around only the
couch, for example, or declare a "magic" attribute that goes just before
the lamp in your source code.

Yonk applies these rules when you're dragging and dropping items, and
will only hilite the objects you can drop things "into" as you drag
through the list.  Yonk also automatically updates the number of "->"
arrows in the declaration when you drop or paste an object.



Yonk and the Inform Libraries

If you include the standard Inform 6/10 libraries in your code, then
this section doesn't apply to you -- Yonk was developed with these
libraries, and will make correct assumptions about their contents.  If
you're using modified versions of the standard libraries, or an
alternate set (e.g., Platypus), then some of Yonk's features may not
work as well (or at all) depending on how much your libraries differ
from the standard ones.

If your source file includes files that are named Parser, VerbLib and
Grammar (regardless of their contents), then Yonk will act as if they
were the standard libraries, and follow the rules in the Inform
Designer's Manual for what order the program should be in.  (For
example, if you create a MAX_CARRIED constant, then Yonk will insert it
before the inclusion of VerbLib.)  If your source file doesn't contain
these three includes, then Yonk will create all new declarations at the
end of the file, and you'll have to put them in the proper order.

If you've altered the standard libraries so that any of the "program
order" rules in the Inform Designer's Manual no longer apply (or if
there are new rules that apply to your altered libraries), Yonk won't
know about the changed rules, and will continue to follow the original
ones.

In an object editor, Yonk will always display the standard library
attributes, regardless of whether you actually included them or not.  If
your modified libraries define new attributes, Yonk won't display them
unless it encounters an object that uses them.  (Actually this is true
for any attributes declared in an included file, not just for the ones
in alternate libraries.  Yonk uses a hard-coded list of all the
attributes in linklpa.h except "workflag", and puts them in order based
on their frequency of use, rather than the order that the library
declares them in.)

Yonk relies on the standard library compass directions (n_to, s_to,
etc.), the cant_go property, and the door_to and door_dir properties to
distinguish between rooms, doors and other objects.  The map viewer and
the "exits" panel of the object editor will not work properly for
objects that use alternate compass directions, and Yonk will fail to
recognize doors as such if they don't have door_dir or door_to.  To
paraphrase Henry Ford, you can have any compass directions you like in
your libraries (or your game) as long as they're named n_to, s_to, e_to
and so on.

In a sense these are all "cosmetic" problems, and you can continue to
use Yonk in spite of them -- but if you're using non-standard libraries,
then Yonk doesn't do as much work for you as it otherwise would have.
Some of these issues may be addressed in later versions of the program.



Troubleshooting and Frequently Asked Questions


Q:  Yonk gave me an error message when it tried to read my source file,
but I can compile it without any problems.  Is something wrong with my
code?

A:  It's more likely that there's something wrong with Yonk.  Yonk was
tested against a variety of source files from the IF-Archive library,
but it's always possible that Yonk will be stumped by unusual (but
valid) syntax in an Inform file.  If you can, please send me a copy of
the relevant part of your code, so that I can improve Yonk's
file-reading routines.



Q:  Yonk read my file successfully, but it says that one of my objects
is a "compiler directive".  What does this mean?

A:  Yonk's first guess when it hits an unknown word in the source code
is that this line of the source code is a directive to the compiler,
such as "#ifdef TEST_VERSION;" or "Switches d;".  If your object
declaration begins with an unknown word (i.e., it belongs to a class
that was declared in an included file), and it looks enough like a
compiler directive to fool the file-reading routine, then Yonk will
mis-label the declaration.  When this happens, Yonk still writes the
object to the output file correctly -- but editing the object calls up
the editor for a compiler directive, instead of using the object editor.

A future version of Yonk will read the contents of files you include,
which will fix this problem.



Q:  Yonk ate all the comments in my source file!

A:  [burp] It sure did.  Yonk discards any comments that aren't part of
a declaration, which is another good reason not to feed Yonk the one and
only copy of the source file you've been working on for months. A future
version of Yonk will allow you to attach comments to declarations, so
that any "unattached" comments in the source file will be associated
with the declaration that follows them.

Yonk also eats whitespace, although it does supply some in the output.



Q:  Yonk re-arranged my source file!

A:  Yonk will move an object that explicitly names its parent (e.g., an
object declared as "object photo wallet" instead of "object -> -> ->
photo") to the place where it belongs in the hierarchical tree, inside
its parent object. This could create a problem at compile time if there
were attribute, global, constant or class declarations that fell in
between the two objects, and the child object needed those declarations
to come before it did.

Possible solutions include moving the other declarations manually to put
them above the moved object, or putting the object back where it
originally was and moving it as part of your Initialise subroutine,
instead of using an explicit parent.

Yonk will also re-arrange the order of attribute settings on your
objects: An object in the input file that "has static scenery" will
appear in the output file as "has scenery static".  This has no effect
on the compiler.




Q:  I'm using the map viewer to "walk around" in my game, but it stops
whenever it gets to a door or an exit with an Inform subroutine.

A:  The map viewer can't actually execute Inform source code to
determine where the exit should go (in many cases, this would require
running a walkthrough up to the point where the player encounters the
exit), so it simply displays the source code instead.  In many cases you
can continue the "walk" by using the arrow keys to select the adjoining
room in the main window.



Q:  Yonk is complaining about a "null InformObject", or some equally
cryptic message.

A:  This is a sign that Yonk's internal data structures have been
corrupted. Save the game you're working on and report the circumstances
to the web page or e-mail address below.



Q:  Yonk is complaining about a "NilObjectException" or other cryptic
message.

A:  That would be the advanced version of the above problem.  If this
occurs while reading a file, Yonk may successfully continue reading,
although at least one declaration will be lost.  If it occurs elsewhere,
Yonk will probably be forced to quit.  Please report the circumstances
and (if possible) how to reproduce it.



Q:  How do I report bugs in Yonk?

A:  Use the "Send Feedback..." command in Yonk's Help menu.




Q:  Can I use Yonk with Platypus or other non-standard Inform libraries?

A:  Yes and no.  See the section on "Yonk and the Inform Libraries" for
a list of features that are only available if you use the standard
libraries.



Q:  Can I use Yonk with Glulx?

A:  Yes.  Yonk is totally agnostic about the compiler's target machine.



Q:  Is there a Windows version of Yonk?

A:  Not that I'm aware of.  Yonk is open source, so if you'd like to
download the source code and port it to other platforms, feel free.



Q:  What language is Yonk written in?  Is the source code available?

A:  Yonk is written in REALbasic, and uses several open source or
freeware classes and plug-ins -- see the About box for a complete list
of credits.  Yonk's source code is available under the terms of the
General Public License (GPL), and can be downloaded from
<http://www.ravenna.com/~forbes/yonk/source/>.

In the unlikely event that you'd like to use Yonk source code in a
commercial (non-GPL) project, contact me for alternative licensing terms.



Q:  What does the word "Yonk" mean?  Why is Yonk's icon a cannon?

A:  Yonk is named after one of the spells in Infocom's classic
"Enchanter" series of text adventures, following in the footsteps of
other IF utilities such as Blorb and Nitfol.  In the game SORCERER,
"yonk" was a spell that augmented the power of certain other spells --
and the scroll containing the Yonk spell was found inside a cannon.