|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|||||||||
|
|
|
|
|
|
|||||||||
|
|
|
|
|
|
|
|
|
|
Issa User ManualLast modified November 12, 2002. By Ben Haller. Copyright © 2002 Stick Software. [ A PDF version of this manual may be downloaded by clicking here. This manual is only available in English at present. ] Issa is a "fridge poetry" application for Mac OS X. This manual assumes that you have already downloaded a copy of Issa; if not, click here for Issa's main page at www.sticksoftware.com. It also assumes that you know all the basics of using the Macintosh in Mac OS X, including using the mouse, menus, and windows, and opening and saving files. Right now this "manual" is really an FAQ (frequently asked questions) list, because Issa is a simple enough app that it doesn't seem to merit a full manual — that would just be a lot of work and would probably be less effective at answering actual user questions. Let us know if you disagree, however; if a full manual is needed for Issa, it can be made. Please send comments on this manual to us at our support email address. Thanks! QuestionsWhat is Issa and what does it do, in a nutshell? Where are the tiles like "ed", "ing" and "an"? What are the different ways to select tiles? What keyboard controls does Issa have? How can I share my poems with others? How do wordlists work? Where can I get more? Can I save the way Issa is now and restore it later? What bugs and issues are known for Issa? What is shareware? How do I pay? What is Issa and what does it do, in a nutshell?Issa is a "fridge poetry" set for Mac OS X. It gives you a bunch of word tiles that you can arrange to form poetry. For example:  Everything about this poem, from the words and the font it uses to the background image it is presented upon, is configurable in Issa. For more information on the basic concept of Issa, as well as links to sample poems and wordlists, and an explanation of where Issa's name comes from, please check out its home page. This manual will try, for brevity, to concentrate on explaining the more difficult or confusing aspects of Issa. Where are the tiles like "ed", "ing" and "an"?This is the chief difference between Issa and the magnetic poetry you probably have on your fridge. Issa takes advantage of the fact that it is on a computer to both increase the available vocabulary and decrease the number of tiles. It does this by allowing a single tile to have more than one word on it. The words on a tile should all be related to each other, such that it makes sense to place them together. For example, "run", "runs", "running", "ran" and "runner" are on a single tile. This means that the "ending" tiles like "ed" and "ing" are not needed in Issa; just choose the word form you want. That begs the question "how do you choose the different forms?" This is as easy as a control-click on the tile (or, if you have a two-button mouse, a right-click). At the top of the menu shown, before the other contextual menu commands, will be the various word forms that exist for that tile. Choose the form you want, and the tile will change. You can also rotate through word forms by selecting a tile and pressing the "escape" key. Sometimes the word forms on a tile are less obviously related. For example, "be", "am", "are", "is", "being", "was" and "were" are all on one tile, which makes sense if you think about it, but might seem odd at first glance. Sometimes the tiles will be related semantically, not syntactically; one tile might have the names of the twelve months of the year, for example. Until you get to know how the tiles are organized, the easiest thing might be to do a Find for the word you want; it will be found even if it is not the currently shown form for a tile. Find "runner", for example, and the "run" tile will be selected. You can also use Issa's type-select feature by typing "is" (for example); the "be" tile will be selected. What is the virtual fridge?Issa lets you choose whether to keep your tiles inside a containing environment called the virtual fridge, or "loose" on your desktop. Which you choose is mostly a matter of taste; if you prefer to see your tiles on a coherent background, choose to use the virtual fridge. If you find that that interferes with seeing your work, and you'd prefer that Issa coexist more transparently with your other applications, you may choose not to use the virtual fridge. (There is also a transparency setting in Issa's preferences that you may find relevant to this choice.) The only side effect your choice has is on drag-selection; with no virtual fridge, you can't click in the background to start a drag-selection of tiles, since your click will go through to whatever application owns the area you clicked on. To drag-select without the virtual fridge, therefore, hold down the option key as you click in a tile. Be aware, however, that is Issa is not the active application, OS X will take the option-click as meaning "hide all other applications", so you will want to be sure Issa is active before doing a drag-select in this way. One of the nicest things about the virtual fridge is the various seamless background textures it can display below your tiles. These textures are generously provided by The3dStudio.com; you can surf to them for many more free textures that you can download. If you put your downloaded texture images in ~/Library/Issa, Issa will add them to the list of textures available in the Preferences panel, so you can use them in your virtual fridge. Please give The3dStudio your business if you can (they sell all sorts of 3D-related products), and let them know that their generosity towards Stick Software has come back around to them if you do. What are the different ways to select tiles?Issa's selection works much like selecting icons on the desktop in the Finder; you can use the mouse (with modifier keys if desired), you can type a word to select tiles with that word, or you can use the Find panel to search for the tile you want to select. This explanation will run on quite a bit, but really it works almost exactly like selection in the Finder, so you may not need to read all of this. The one thing that works differently is that, if you are not using the virtual fridge, you cannot "click off" in empty space to deselect, because unlike in the Finder, the empty space between the tiles is not "owned" by Issa. For this reason, clicking on the Stick Software logo tile (or any image tile, actually) will deselect completely; the image tile will not be left selected. This is intentional, and is to prevent the annoyance of being unable to deselect easily. To select a tile with the mouse, just click on the tile you want to select. You can hold down the shift key to select additional tiles that you click on; hold down the command key to toggle a clicked tile between being selected and deselected. You can double-click on a tile to select a "cascade" of tiles that are all sufficiently close to each other; this is a quick way to select an entire completed poem, for example. You can shift-double-click and command-double-click to augment the current selection by adding or toggling a cascade of tiles. Dragging out a selection rectangle in the virtual fridge works just as it does in the Finder, and shift and command will modify the way that works as expected. If you aren't using the virtual fridge, you can begin a drag-select from any tile by holding down the option key (sometimes labelled as the "alternate" or "alt" key), but you can't start a drag-select from the space between tiles, since without the virtual fridge that click goes to whatever application is behind Issa. (If Issa is not the active application, however, the option-click will cause all applications other than Issa to hide; this behavior is built into OS X and cannot be disabled as far as we can tell, unfortunately.) To select by typing, just type. Issa has to be the active application, of course. Whatever you type will be matched against the contents of the tiles (both the visible word form, and any alternate word forms on the tiles). If there are tiles that match exactly (you type "run" and the tile has "run"), all tiles with exact matches will be selected. If there are no exact matches, then it will match prefixes (you type "ze" and the tiles has "zebra"); if there are 10 or fewer tiles that have prefix matches, they will all be selected, if there are more than 10, only one matching tile will be selected. The point of this is to keep from selecting 50 tiles when you type "e"; it will just select one tile that starts with "e". This can be a good way to get inspiration, by the way; type a random letter and see what tiles get selected, and then work from one of them. Selection with the Find panel is exactly as you would expect; select the Find menu item, type the word you want, hit OK, and the tiles that match will be selected. The Find panel does a prefix match; if you want an exact match, choose Find Exact instead. Finally, there are menu commands and keyboard controls that change the selection. Select All selects all the tiles, Deselect All deselects them all. Invert Selection makes any tile that was selected be deselected, and any tile that was deselected becomes selected; this can be useful if you want to delete every tile except for the poem you just finished, for example: select the poem, invert the selection, hit delete. Blink Selection blinks the selection on and off a few times to make it more visible; hitting the space bar does the same thing. Finally, Match Tiles is a shortcut that finds every tile that exactly matches the selected tile or tiles (and they must match all word forms on the tile, not just the visible word form); hitting the tab key is a shortcut for this. This makes it easy to find another "and" tile, for example, when you already have one at hand. What keyboard controls does Issa have?The space bar blinks the current selection, just like selecting the Blink Selection menu item. More on this can be found in the section on selection. The escape key shows the next word form on the selected tile or tiles. More on this can be found in the section on word forms. The tab key selects all tiles identical to the selected tiles, just like the Match Selection menu item. More on this can be found in the section on selection. The delete and backspace keys delete the currently selected tiles, just like the Delete menu item. How can I share my poems with others?Issa makes it very easy to export your poems to formats that can be easily shared over e-mail or the web. Just select the tiles the poem is composed of (double-clicking to do a cascade-select may be an easy way to do this), and then choose an exporting option. Under the Tiles menu, you can choose to export the selection as a JPEG or TIFF image or an HTML page; these choices will save the exported poem to a file. Under the Edit menu, you can choose to copy the selected poem to the clipboard as text or as an image; these choices will modify the clipboard, but will not save a file to disk. Finally, you can choose an OS X service from the Services menu, such as Mail.app's "Mail Text" service that creates a new e-mail message with the service text. If you want to share your poems with other users — if you want a single "poetry space" shared among the users of your machine — you can do this by linking together Issa's tile record files. You probably don't want to attempt this unless you are comfortable with your Administrator priveleges and using Terminal and Unix, however. First, quit Issa so the files you'll be using aren't busy. Next, choose a "master" user that other users will link to, and delete the tile record files for all of the users but the master user (the tile record files are located at ~/Library/Preferences/IssaTiles for each user of Issa). Finally, use "ln -s" to create soft links to the master account's tile record in all of the other user accounts. If you've set this up properly, Issa should now share the tile record among the users of the machine. You probably want all the users to keep their tiles in the same screen area so that they fit properly for all users; you could probably link together Issa's defaults files (located at ~/Library/Preferences/com.stick.app.issa.plist) if you really wanted to, although then all of the user's preferences would be linked. Linking the defaults files together has not been tested by us, you do it at your own risk (although it seems unlikely that any very dire consequences could occur). How do wordlists work? Where can I get more?Wordlists are how Issa works with sets of words; they are how Issa manages its vocabulary. You can create wordlists in Issa by exporting the set of words you are currently using, or you can create or modify wordlists in a word processor (see the Can I make my own wordlists? section for details). You can download wordlists, e-mail them to friends, or post them on your web page. Inside Issa, you can replace your current set of tiles with new tales based on a wordlist of your choice, or you can merge in a wordlist, creating new tiles for the words in the wordlist while keeping your current tile set. Some wordlists are small and are designed to be merged into a larger, general vocabulary to provide special-interest terms related to things like sports or science. Other wordlists are large and are designed to be used as a base vocabulary. Regardless, you can use them however you see fit, and can modify them if you want to. The way Issa keeps track of wordlists is a little bit non-standard and bears explanation. If you choose Issa's "Set Word List" or "Merge Word List" menu items, you will not get an "open file dialog" to choose the word list you want. Instead, you will get a custom dialog box that shows only the wordlist files that Issa knows about. Issa knows about word lists that are built into it, and it knows about word lists located in your ~/Library/Issa folder. Any other wordlists (ones you download, receive in e-mail, or whatever) must be imported into Issa using the "Import Word List" menu command (double-clicking the wordlist file should work too). All this really does is copy the word list to ~/Library/Issa, and you can do this yourself if you prefer. The reason for this design is that Issa doesn't want to show the wordlist filenames when you set or merge them; it wants to present you with a more readable title and the number of words in the list. This design also allows Issa to show you things like the language the word list is localized for, a longer explanation of the contents of the file, and other information. Doing this within the standard file dialog would be difficult. Can I make my own wordlists?Making your own wordlists is fairly simple; all you need is a word processor that works with plain text files (the TextEdit application that ships as part of OS X works well). You might want to work from an existing wordlist, so you get the basic structure of the file for free. A typical wordlist would look something like this: // This is a word list for Issa. @title Music @longtitle These are a few of my favorite musicians @language English @dictionary http://www.gracenote.com/php/search2.php3?f=artist&q=%@&image=Go @author Ben Haller @version 1 @copyright Copyright (C) 2002 Stick Software @words "Brian Eno" Eno 2 "Caetano Veloso" Veloso "Laurie Anderson" Anderson "Kate Bush" KT "Gabriel Yacoub" Yacoub "John Coltrane" Coltrane "Tom Waits" Waits @end This is probably fairly self-explanatory. The "//", first of all, starts a comment at the top of the file, which similarly lasts until the end of the line. You can put // comments anywhere you want (but only as a full line of content, not as the end of a line with other content on it). At the top are some standard tags beginning with an '@' symbol that tell Issa the title, language, author and such. Those tags must occur one per line, and the remainder of the line after the tag is taken as the value for the tag. The @dictionary tag tells Issa where it should look up words in this word list when asked to define them; since these are all musicians, I put the URL for a music site. The "%@" near the end of the URL is where the word to be defined gets plugged in, so if Issa is asked to define "Brian Eno", it would generate a URL of http://www.gracenote.com/php/search2.php3?f=artist&q=Brian+Eno&image=Go. The @longtitle, @author, and @language tags give information that Issa shows to the user to help them choose a word list. The @version tag is not currently used, but will probably be used by a future version of Issa to facilitate automatic updating of a user's word lists; it should start at 1 and be incremented by one each time you publish a new revision of your word list. The @copyright tag provides a standard place for a copyright notice; this text may be displayed in future versions of Issa the way that @author and other tags are now. Between the @words tag and the @end tag are all the words. Each tile is one line; multiple wordforms for a single tile are just listed one after another on the same line. So the line '"Brian Eno" Eno' makes one tile with two wordforms on it: "Brian Eno" and "Eno". The quotes around "Brian Eno" are just used to indicate to Issa that the space is part of the "word", not a divider between two different words. The "2" at the end of the Brian Eno line makes Issa create two identical Brian Eno tiles (because he's my absolute favorite); if no number is given, only one tile is created. If you want to include a quote mark (") in a word, you need to preface it with a backslash (\") so Issa doesn't take it as establishing a quoted string. If you want to include a backslash, therefore, you need to quote it in the same manner (\\). This all probably sounds completely insane to people who have never programmed, while all the programmers are saying "yeah, of course" :->. For those who are a bit lost, here are a few examples. The column on the left is the string as it would be written in the wordlist file; the column on the right is exactly what will be shown in the resulting tile in Issa. foo foo "foo" foo foo bar foo (bar is taken as the second word form) "foo bar" foo bar "foo \"bar\"" foo "bar" foo\\bar foo\bar foo\ bar foo bar (the backslash quotes the space as a literal character) foo 2 foo (two tiles that each say foo) foo "2" foo (2 is the second wordform on the tile, since it was quoted) foo2 foo2 (numbers are not taken as a count unless they are separate) foo\ 2 foo 2 (the backslash quoted the space, continuing the word) If you do something sufficiently heinous, there are cases where Issa will log an error message to the console, which is helpful if you know how to look at the console. Most of these sorts of cases are pretty obscure, though; in general, you can write words plainly, and if you want something with spaces to be treated as a single word, you put quotes around it. That should get you a long way. Can I save the way Issa is now and restore it later?As a matter of fact you can. Suppose you want to look at different word lists and generally experiment in a destructive way, but you ultimately want to come back to the way you have Issa set up right now, right down to the position of every tile on your fridge. This is quite simple to do, although it isn't supported from within Issa's user interface (for reasons of limiting the complexity of the app). Just follow these steps to save your current state:
Then to restore yourself to that previous state, quit Issa and then just put your backup file back where it came from (making sure to give it the correct file name of "IssaTiles" again). You might keep a copy of the backup file so you can try again if this doesn't succeed for some reason. You can make as many backups of the IssaTiles file as you want. You can probably even mail them to friends, exchange them among different machines, and so on; this hasn't been tested, but I don't see any reason why it shouldn't work. If you back up your IssaTiles files properly, the worst you're likely to do by experimenting is to crash Issa. :-> Note this does not back up your user preferences regarding Issa (everything you set up in the Preferences panel, plus a few miscellaneous other things); those settings are kept in a separate file that you really probably don't want to mess with. What bugs and issues are known for Issa?In a previous version of this manual, we stated that a bug that caused Issa's tiles to draw incorrectly in rare cases was due to an Apple bug that had been fixed in 10.2. This assessment was incorrect; it was due to a bug in Issa that happened not to reproduce on 10.2 when we tried it. The bug has been fixed in Issa 1.0.2. Our apologies to Apple for this incorrect diagnosis. You may wish that Issa used the short, three-character versions of file extensions, such as ".tif" instead of ".tiff", ".jpg" instead of ".jpeg", and ".htm" instead of ".html". We didn't deem this worthy of a user-visible pref, but you can use Terminal to change Issa to use short extensions. Just quit Issa, go to Terminal and type "defaults write com.stick.app.issa IssaShortExtensions YES" and hit return. The next time you run Issa, the short extensions will be used instead. And by the way, we find it just as annoying as you probably do that OS X attempts to force particular extensions on you; you ought, of course, to be able to simply change the ".tiff" to ".tif" in the Save panel, but OS X is too smart for its own good. We have logged a bug on this with Apple; we'll see what happens. You may notice that when you ask Issa to Define the word on a tile, you may sometimes go to a web page that is not the dictionary web page that was given in the wordlist file that the tile is from. This will happen for any tiles which are merged in with Merge Word List, in fact, if the merged list's dictionary URL is different than your base word list's dictionary URL; the base word list dictionary URL is always used. This would be fairly easy to fix; the problem, and the reason we haven't fixed it, is the question of what we would then do if you tried to export your word list to a new wordlist file. What would we write out as the dictionary URL? Would we need to devise some modified word list file format that allowed each word to specify a different dictionary URL? That seems terribly gross. So for the moment we've chosen to punt on this. If you have an opinion (and if you care), feel free to drop us a line; we'll probably do something about this problem in the next version of Issa, whenever that happens. Some users may find that they have too many tiles for their taste, and on slow machines this might cause slow performance (although we have actually not heard any complaints about this from testers or users so far). If this happens, select some tiles you don't like and delete them. :-> Some people consider it objectionable that tiles cannot be edited. We do not consider this a bug, and we'll tell you why. Fridge poetry is... well, it's like this really groovy head space, you know? It's, like... ahem. The idea of fridge poetry, in our opinion, is that it is a constrained space for creativity. By working within those constraints, it can actually help you create. This is similar to why poetic forms like haiku or the sonnet are popular, or why music typically uses an eight-tone scale; by limiting the infinitude of options available to you, you sometimes gain more than you lose. We consider the constrained vocabulary of fridge poetry to be exactly this sort of thing — we didn't even want to put the "New Word Tile" command in, but we figured users would kill us if we took that extreme of a position. But we suggest that if you want to get the most out of Issa, you might try working with the tiles as given. If you compose your poem in your head without reference to the tiles that exist, and then create all the tiles you need, you might find Issa less than rewarding, and a word processor (or a pad of paper) might be a better environment for you to work on your poetry. What is shareware? How do I pay?As a closing note, we'd like to remind our readers that Issa is a shareware product. While Issa is not disabled in any way for non-registered users, it is still required that you pay the shareware fee if you use Issa beyond a trial usage. Issa costs $10. We at Stick Software hope that by not disabling our software, we make it easier and less annoying to use, and we hope that more users will register for our software as a result. Please be worthy of our trust. Information on how to pay and other registration details can be found at http://www.sticksoftware.com/software.html, or you can simply pay with a credit card (or other methods) with no further ado at either www.paypal.com or www.kagi.com. Comments on Issa, suggestions for future products, and other feedback are welcomed at our support email address. Thanks for your support! |
|
|
|