GemSay -- a UI addon for easy message macros and automatic notifications
By Gemminie <trueflint@gmail.com>

	Tired of announcing your CCs to your guild instead of your raid?  Want
to spice up your macros with a few random sayings?  Want to quickly tell people
about that Horde or Alliance enemy you just saw?  Try putting this in your
macros.  This small UI extension provides two messaging commands:

/gs <destination code(s)> <message>: Fills in special % codes in the message,
then sends the message to the destination(s) you specify, stopping with the
first one that works.  (See below for details.)  You can also type "/gs help".

/gsw <recipient> <message>: Also fills in % codes in the message.  Sends the
message as a /w to the designated recipient, who could be %t for your current
target.  You could also send messages to yourself to test what they'll look
like.

	GemSay can also store random messages, organized into categories, for
you to call upon from /gs or /gsw.  It's also capable of setting up message
triggers that will call a /gs or /gsw of your choice when certain events happen
in the game.

/gs random (or /gsr): Opens the Random Message Category Editor window.

/gs trigger (or /gst): Opens the Message Trigger Editor window.

INSTALLATION
------------

	GemSay comes in a .zip file, which means that most Windows systems will
just let you double-click it and open it like a folder.  It contains one
folder, named "GemSay" (how original)!  Put this GemSay folder in your World of
Warcraft\Interface\AddOns folder.  You have just installed GemSay!  You will
have to quit and restart WoW if you did this while WoW was running.

DESTINATION CODES
-----------------

	The /gs command's destination codes are a string of one-letter (or
-digit) codes, in the order to try them in, and as soon as one succeeds, it
stops trying -- don't worry; here are some examples.

*** First of all, this one will send the message to the instance-specific group
you're in, if you're in one.  If not, it will send it to the raid you're in, if
you're in one, but if you aren't, it will send the message to your party
instead.  If you're not in a party either, it won't send anything:

/gs irp Now summoning %tt -- please click the portal.

See?  It tries "i" (instance group, like a battleground, Dungeon Finder group,
etc.), and if that works, it stops.  But if you're not in one of those, it
tries "r" (raid) next, and if that succeeds, it stops.  If you're not in a
raid, though, it fails, and we skip to "p" (party).  (The %tt is a message %
code and gets filled in with the name of your current target, but don't worry
about that for now -- there's more about those later.)  Let's try another one.

*** This next command will send the message to the instance, raid, your current
party, or if you're not in a party it will just say it:

/gs irps Sheeping %tt -- you hit %to, you tank %to!

The complete list of destination codes for the /gs command is:

Code	Meaning
----	-------
a	Raid warning (skips if you're not in a raid)
d	Debug -- just print it, so only you can see it (never skips)
e	Emote, like /em (always succeeds; never skips)
g	Your guild (skips if you're not in a guild)
i	The instance group you're in (if you're not, skips to the next one)
o	Officer chat in your guild (skips if you're not in a guild)
p	Your party (skips if you're not in a party)
r	Your raid (skips if you're not in a raid)
s	Say, just as if you'd done /say (never skips)
y	Yell, like /yell (never skips)
w(name)	Whisper to player name
<digit>	Numbered chat channel (skips if you're not in that channel)

MESSAGE % CODES
---------------

	You probably already know that WoW replaces a "%tt" in any message you
send with the name of your current target, or "<no target>" if you don't have
anything targeted.  GemSay expands on that, providing several more "%" codes
that give more information about your target, your pet, or yourself, or a
random string from a category you have defined.

	Also, GemSay keeps you from looking dumb.  If there are target-related
"%" codes in the message (%tc, %tf, %tt, %tl, %tr, %ts, %tn, %to, %tp, or %tq),
but you have nothing targeted, GemSay will say nothing, just popping up a
message on your screen that nobody else will see.  If there are no
target-related "%" codes in your message, no check is performed and your
command happens as normal.

	The general format for GemSay's message codes is:

%[<upper or lower case prefix>][<unit codes>]<information code>

where the upper or lower case prefix is either ^ or _ (more on this later), the
unit code(s) specify what unit to get information about if necessary, and the
information code is the item of information to get.

(this needs reformatting)

	Here are the target-related % codes.  The "Example" column below is
based on the assumption that your target is Janora, a female level 85 Night Elf
Hunter.

Code	is substituted with:				Example
----	--------------------				-------
 %tc	The target's class				Hunter
 %tf	The target's faction (Alliance/Horde)		Alliance
 %tl	The target's level				85
 %tn	Nominative-case pronoun (he/she/it)		she
 %to	Objective-case pronoun (him/her/it)		her
 %tp	Possessive-case pronoun (his/her/its)		her
 %tq	Long possessive-case pronoun (his/hers/its)	hers
 %tr	The target's race				Night Elf
 %ts	The target's sex (male/female/unknown)		female
 %tt	The target's name				Janora

%TN, %TO, %TP, %TQ, and %TS will do the same thing as %tn, %to, %tp, %tq, and
%ts, but the first letter will be capitalized, so you can use them at the
beginning of sentences.  Here are lots of examples:

Code	is substituted with:				Example
----	--------------------				-------
 %TN	Nominative-case pronoun (He/She/It)		She
 %TO	Objective-case pronoun (Him/Her/It)		Her
 %TP	Possessive-case pronoun (His/Her/Its)		Her
 %TQ	Long possessive-case pronoun (His/Hers/Its)	Hers
 %TS	The target's sex (Male/Female/Unknown)		Female

	If you use an "f" in place of the "t", GemSay will look at your focus
instead of your target (the focus is part of WoW, not GemSay -- you can set
your currently focused unit by targeting something and typing "/focus", and
this can be bound to a key using WoW's regular keybinding interface).

Code	is substituted with:				Example
----	--------------------				-------
 %fc	The focus's class				Hunter
 %ff	The focus's faction (Alliance/Horde)		Alliance
 %fl	The focus's level				85
 %fn	Nominative-case pronoun (he/she/it)		she
 %fo	Objective-case pronoun (him/her/it)		her
 %fp	Possessive-case pronoun (his/her/its)		her
 %fq	Long possessive-case pronoun (his/hers/its)	hers
 %fr	The focus's race				Night Elf
 %fs	The focus's sex (male/female/unknown)		female
 %ft	The focus's name				Janora

	Also, if you use a "p" instead of a "t" or "f", GemSay will use your
information instead of the target's (so %pt will print your name), and if you
use an "e", GemSay will use your pet's information (%et becomes your pet's
name).  If you use "e" and don't have a pet present, no message will go out.
Here, have another two bucketfuls of examples.  (In this case, assume you are
Gemminie, a female level 90 Gnome Warlock, with a Succubus named Anneth out.
Yes, I'm doing all of this to make Anneth famous.)

Code	is substituted with:				Example
----	--------------------				-------
 %pc	Your class					Warlock
 %pf	Your faction (Alliance/Horde)			Alliance
 %pl	Your level					90
 %pn    Nominative-case pronoun (he/she/it)		she
 %po    Objective-case pronoun (him/her/it)		her
 %pp    Possessive-case pronoun (his/her/its)		her
 %pq    Long possessive-case pronoun (his/hers/its)	hers
 %pr	Your race					Gnome
 %ps	Your sex (male/female/unknown)			female
 %pt	Your name					Gemminie

 %ec	Your pet's class				NPC
 %ef	Your pet's faction (Alliance/Horde)		Alliance
 %el	Your pet's level				90
 %en    Nominative-case pronoun (he/she/it)		she
 %eo    Objective-case pronoun (him/her/it)		her
 %ep    Possessive-case pronoun (his/her/its)		her
 %eq    Long possessive-case pronoun (his/hers/its)	hers
 %er	Your pet's race					Demon
 %es	Your pet's sex (male/female/unknown)		female
 %et	Your pet's name					Anneth

	Then there is the special target %st.  It becomes the name of the unit
that you're actually casting the spell on, even if they're not actually your
target (or focus, etc.).  There are only a few situations when this is useful
-- for example, if you're resurrecting a player who has already released their
spirit, so their corpse can be clicked but can't be targeted.  Unfortunately,
in cases like this there is no way to determine anything else about the target;
WoW only provides the script with the target's name.  Also, WoW only gives the
target's name to the scripting API as part of the UNIT_SPELLCAST_SENT event
(called "Cast Button Pressed" in GemSay) -- although GemSay remembers the
target from the last "Cast Button Pressed" event, it may be possible for your
target to change.  Also, a UNIT_SPELLCAST_FAILED event can go out before
UNIT_SPELLCAST_SENT does in the case where the failure can be determined on the
client side (like you're out of mana or the target is friendly).  I've done
what I can, though.

 %st	Your current spell's target's name			Gordok Reaver

	A few notes about some of these codes: If you use %tl, but the target's
level is too high for you to see, GemSay will give you "??".  Also, for NPCs,
GemSay will indicate whether they're rare or elite.  A rare (silver dragon) mob
will show up as "90 Rare", an elite (gold dragon) mob will appear as "90+", a
rare elite will appear as "90+ Rare", and a world boss will appear as "??++".

	WoW doesn't seem to keep very good track of the race of its NPCs, so
GemSay tries its best when you use %tr.  If you're looking at a mob that is
obviously a dwarf, WoW won't tell GemSay that it's a dwarf; GemSay will do what
it can and give you "Humanoid."  For Beasts, GemSay is a little more specific;
you can get "Bear," "Cat," "Wolf," etc.  You may still get "unknown," though,
which means it's an ooze, a bug, or some other typeless mob.

	Likewise, with %tc, GemSay does what it can with the class of NPCs.
The information that WoW gives out is often nonsensical.  The best GemSay can
do is give you "NPC" so you don't end up saying that some undead ghoul is a
Paladin.

	If your target is an NPC, using %tf to get its faction will probably
result in "unaffiliated."  Some NPCs are affiliated with either Alliance or
Horde, though.

	The following codes aren't target-related -- they're based on *your*
location, not your target's, so using them won't trigger GemSay to check
whether you have a target before sending your message.

	For those who don't have any UI mods that show your map coordinates,
they are just two numbers from 0 to 100 that measure where on your current map
you are -- the first number is how far east you are from the left edge of the
map, and the second is how far south you are from the north edge of the map.
So (0, 0) = extreme northwest corner, (100, 0) = extreme northeast corner,
(100, 100) = extreme southeast corner, etc.  If you're in an instance, though,
this doesn't work; the coordinates are always (0, 0).  [Is this still true, now
that instances have maps?]  Examples?  Why not:

Code	is substituted with:				Example
----	--------------------				-------
 %m	Your map coordinates				(36, 23)
 %w	The minimap zone text of your location		Trade District
 %x	The real zone text of your location		The Stockade
 %y	Subzone text of your location (can be blank)	The Canals
 %z	The zone text of your location			Stormwind Stockade

	You can make any of these % codes give its result in ALL CAPS by using
%^ instead of just % -- for example, %^tt will become the target's name in all
caps (JANORA).  Likewise, %_ changes the results to all lowercase -- for
example, %_tr would become the target's race in lowercase (night elf).  And now
to overwhelm you with examples.  Note that %^ptc and %p^tc should do the same
thing -- the order of prefixes isn't important, except that the % must be
first, and the code letter must be last.

Code	is substituted with:				Example
----	--------------------				-------
 %^tc	The target's class				HUNTER
 %^tf	The target's faction (ALLIANCE/HORDE)		ALLIANCE
 %^tn	Nominative-case pronoun (HE/SHE/IT)		SHE
 %^to	Objective-case pronoun (HIM/HER/IT)		HER
 %^tp	Possessive-case pronoun (HIS/HER/ITS)		HER
 %^tq	Long possessive-case pronoun (HIS/HERS/ITS)	HERS
 %^tr	The target's race				NIGHT ELF
 %^ts	The target's sex (MALE/FEMALE/UNKNOWN)		FEMALE
 %^tt	The target's name				JANORA

 %^pc	Your class					WARLOCK
 %^pf	Your faction (ALLIANCE/HORDE)			ALLIANCE
 %^pn	Nominative-case pronoun (HE/SHE/IT)		SHE
 %^po	Objective-case pronoun (HIM/HER/IT)		HER
 %^pp	Possessive-case pronoun (HIS/HER/ITS)		HER
 %^pq	Long possessive-case pronoun (HIS/HERS/ITS)	HERS
 %^pr	Your race					GNOME
 %^ps	Your sex (MALE/FEMALE/UNKNOWN)			FEMALE
 %^pt	Your name					GEMMINIE

 %^ec	Your pet's class				NPC
 %^ef	Your pet's faction (ALLIANCE/HORDE)		ALLIANCE
 %^en	Nominative-case pronoun (HE/SHE/IT)		SHE
 %^eo	Objective-case pronoun (HIM/HER/IT)		HER
 %^ep	Possessive-case pronoun (HIS/HER/ITS)		HER
 %^eq	Long possessive-case pronoun (HIS/HERS/ITS)	HERS
 %^er	Your pet's race					DEMON
 %^es	Your pet's sex (MALE/FEMALE/UNKNOWN)		FEMALE
 %^et	Your pet's name					ANNETH

 %^m	Your map coordinates				(36, 23)
 %^w	The minimap zone text of your location		TRADE DISTRICT
 %^x	The real zone text of your location		THE STOCKADE
 %^y	Subzone text of your location (can be blank)	THE CANALS
 %^z	The zone text of your location			STORMWIND STOCKADE

 %_tc	The target's class				hunter
 %_tf	The target's faction (alliance/horde)		alliance
 %_tr	The target's race				night elf
 %_tt	The target's name				janora

 %_pc	Your class					warlock
 %_pf	Your faction (alliance/horde)			alliance
 %_pr	Your race					gnome
 %_pt	Your name					gemminie

 %_ec	Your pet's class				npc
 %_ef	Your pet's faction (alliance/horde)		alliance
 %_er	Your pet's race					demon
 %_et	Your pet's name					anneth

 %_m	Your map coordinates				(36, 23)
 %_w	The minimap zone text of your location		trade district
 %_x	The real zone text of your location		the stockade
 %_y	Subzone text of your location (can be blank)	the canals
 %_z	The zone text of your location			stormwind stockade

MESSAGE / CODES
---------------

	(This is an expansion of an idea sent to me by Yltseirp of Cairne.)  If
you begin the message with some typical WoW message / commands, it will
actually override the destination code.  These are:

/e, /em, or /me: Emote
/g: Guild chat
/i: Instance chat
/o: Guild officer chat
/p: Party chat
/ra: Raid chat
/rw: Raid warning
/s: Regular say
/y: Yell
/<number>: The given numbered chat channel

	For example,

/gs s /em pours holy water over %tt's head, just to be sure.

will cause the message to appear as an emote, even though the destination code
is "s".  If your "destination override" is successful when your original
destination wouldn't have been (for example, if you did a "/gs rp /s" when you
were in a party that wasn't a raid), it is treated as a success, and GemSay
stops trying to send your message.

	What's more, you can also use WoW's extensive list of emote commands,
like /laugh, /cheer, /cry, /rasp, /silly, /flirt, etc.  However, the text you
put after the emote command doesn't work the way you may expect.  Putting
anything after the emote command simply means to pay attention to your target,
if you have one.  For example,

/gs s /laugh x

will cause you to do a laugh sound and animation, and will print "You laugh at
<target name>." if you have a target.  If you don't have a target, it'll just
print "You laugh."  However, if you do

/gs s /laugh

with nothing after the "/laugh", you'll just see "You laugh." no matter whether
you have a target selected or not.  The laugh sound and animation will still
happen, though.  It's this way because of an intrinsic limitation of WoW: you
can't customize the text that prints when you do a built-in emote.  The
flipside of this is that opposite-faction players will be able to understand
the built-in emote text as usual.

Why would you want to do this?  Just wait until we get to random messages
... oh look, here we are!

RANDOM MESSAGES
---------------

	The %g code can be used to generate a random message from one of the
categories you've defined.  This also has nothing to do with your target and
won't trigger GemSay to check whether you have a target.

Code		is substituted with:
----		--------------------
 %g<category>	A random string from the given category

Use /gsr to open the random string editor window.  You can make categories, and
in each category you can put a list of messages, random words, or whatever you
want.  Suppose you make a category called "jokes" and put a bunch of witty
sayings in it.  Then,

/gs rp %gjokes

will say one of your random jokes to your raid or party.  The random strings
can contain other % codes -- including %g codes to look up other random
messages!  There is protection so you don't enter an infinite loop by having a
message in "jokes" that contains "%gjokes".

	Your messages can contain anything you want, but your message category
names can contain only letters, numbers and _ (the underscore character).

	The %^ and %_ functions don't work on %g; you can't do %^gjokes to tell
your joke in all caps.  This is because _ can be a part of your category name.
Also, I'm lazy.  (If you want to shout, type your joke in all caps to begin
with.)

CATEGORY EDITOR WINDOW
----------------------

	Type /gsr to open this window -- to make it go away, it has both an X
button and a Close button that are equivalent, and hitting Esc works too.  You
can drag it around your screen with the mouse.

	You can define global categories and messages that you can access from
all your characters, and you can define categories and messages that will only
appear for the character you're currently logged in as.  There's a pair of
radio buttons at the top of the window that lets you pick which list of
categories you're currently looking at -- one says "Global" next to it, and the
other says "<your current character> of <your current server>."  These buttons
don't actually change any of your messages; they only change which ones you're
looking at right now.  If you have global and character-specific categories
with the same name, %g will pick a random message from among all the strings in
both lists.  In this way you could have generic jokes that all your characters
tell, but also have specific ones that would only show up for particular
characters now and then.

	On the left you see a list (initially blank) of categories (these are
the category names you reference from %g).  On the right you see a list of the
messages in the selected category; this list will be blank until you select a
category.  You can select a category by clicking on its name in the left list,
at which point its messages should appear in the right list.

	Under the list of categories you will see buttons that let you add a
new category, change the name of a category, or delete a category, and there
are likewise buttons under the message list that let you add a new message,
edit a message, or delete a message.  You can also edit a category name by
clicking on the highlighted one again -- same thing with messages.

	If you use a message "/ code" to override the destination code, you can
have your target messages go to different destinations.  For example, you might
have a "resurrection" category with messages like:

Please try to die less often, %tt.  I think Elune is raising Her mighty eyebrow
at you.  I've heard that eyebrow is three feet long.

and

/em sighs in exasperation and resurrects %tt yet again.

	If you then called upon GemSay with

/gs s %gresurrection

you would get either a regular "say" message or an emote!  You could also do
the same with a "/gs e %gresurrection" and messages that were either just
emotes or "say" messages prefixed with "/s", but that's just another way to do
the same thing.

TRIGGER EDITOR WINDOW
---------------------

	Type /gst to open this window.  It has an X button to close it, and Esc
also works.  It is draggable with the mouse like the category editor window.

	This window lets you define /gs and /gsw commands to be issued whenever
you do certain things.  You can announce who you're resurrecting or summoning,
or which mob you're sheeping.  Or you can just add flavor or humor to your
gameplay.

	First of all, you will see your list of current triggers in the
left-hand panel.  These are saved on a per-character basis.  Click "New
Trigger" to make a new one.

	In the right-hand area of the window you'll see controls appear that
will let you edit your new trigger.  The first thing you'll need to do is use
the pulldown menu near the top to select what sort of event you want to trigger
on.  There are several possibilities.  For example, you can select "Attack,"
and you can then go on to set up what you will say when you attack a target
with your weapon (it triggers when you turn autoattack on, which is what
happens when you press the Attack button -- some abilities turn this on
automatically, too).

	Possibly the one you'll want to use most often is "Cast Started," which
applies to spells, abilities, and even usable items.  When you select "Cast
Started" (or in fact "Cast" Anything) from the pulldown menu, you'll see a
little box that looks like a button on your action bar -- in fact, it works the
same way.  Next to it is a message that says, "Drag Spell or Item Here," and
that's just what you do.  Drag a spell/ability from your spellbook or an item
from your inventory onto this button.  GemSay will remember what
spell/ability/item effect you want to trigger on, and its name will appear next
to the button.  If you try to give it an item that doesn't have a use effect,
GemSay will complain; pick something else.  Beware of dragging an icon from
your action bars to this button -- it will remove the icon from your action
bar, and you can't get it back without going to the spellbook or your
inventory!

	Whether you're setting up a "Cast *" trigger or not, the next thing to
set is the frequency -- the percent chance out of 100 that you'll see this
message when this trigger is tripped.  Some messages (like resurrect, summon or
sheep notifications) you'll probably want at 100%, which is the default for new
messages.  But other messages (like those connected with activities you do a
lot) you might want to tone down, so you only do them occasionally.  On my
Warlock, I have various entertaining messages assigned to my Immolate spell
having to do with mocking the mob I just set on fire, but if I say them every
single time I cast Immolate, it can get very tiresome, especially to other
people in my party.  I dialed it back (actually, I added the frequency slider
so I could dial it back) to 10%, and it's a lot more fun now.

	After that, the only thing left is to set the actual GemSay command
you're going to use.  First you select either /gs or /gsw from the pulldown,
then you fill in either your destination codes or your /gsw whisper recipient
in the "Destination" blank, and then you type your message in the "Message"
blank.  All % codes are filled out in messages, as is usual for GemSay.

	Once you have things set the way you want, press the "Save" button.
Assuming you have all the blanks filled in (you'll see an error box if you
don't), your new trigger should now be listed in the list on the left-hand side
of the window.  This is pretty straightforward, but note that "Cast *" triggers
also contain the name of the "spell" to trigger on -- and sometimes that spell
name isn't very closely related to the name of the item.  Every food item shows
up as "Food," for example (although if you have a Food trigger, it will work
for any type of food).  As another example of this, the "Vengeance of the
Illidari" trinket's effect is called "Arcane Energy."  For the most part you'll
just have to remember.  GemSay will remember the icon, though, so that should
help.

	To edit an existing trigger, just left-click on its name in the list,
and its info will appear to the right.  Remember that no changes are saved
until you hit Save, though.  You can hit Cancel if you decide you don't want to
change anything about that one.  Also, you can hit "Delete Trigger" when you
have a trigger selected, and that trigger will be removed from the system.

SOME EXAMPLES OF USING GEMSAY
-----------------------------

***	First of all, if you'd like to warn other people about a PvP opponent
in the vicinity, you could make a macro that does something like:

/gs rp3 Sighted %tt (%tl %tr %tc) @ %w %m.

where we're assuming that channel 3 is LocalDefense.  This will result in your
saying to your raid, party, or LocalDefense:

Sighted Janora (85 Night Elf Hunter) @ Mazthoril (59, 60).

***	If you'd like to have a number of random sayings, and pick one to say
every now and then, use /gsr to create a "sayings" category, put a bunch of
messages in it, and make a macro with this command:

/gs rps %gsayings

***	You can even make Mad Libs -- use /gse to create a "noun" category, a
"verb" category, and an "adjective" category, then do

/gs rps %tt, I want to %gverb your %gadjective %gnoun.

Or, for even more variety, make a "madlibs" category with a bunch of sentences
like that (only without the "/gs rps" at the beginning), and put this in your
macro:

/gs rps %gmadlibs

***	Now, I know that some of the grammar talk above will be confusing
("Nommi-what case?"), so here are some examples.

	NOMINATIVE CASE: Suppose you're a warlock, and you want to make a
summoning macro (Yes, Im aware that summoning doesn't work like this anymore,
but it used to, so just read the examples).  You might do something like this:

/cast Ritual of Summoning
/gs rp Hey guys, I'm summoning %tt.  If you don't click the portal, %tn's going
to be eaten by demons in 5 ... 4 ... 3 ... 2 ...

The %tn will be replaced by "he" or "she" as appropriate for your target.
Nominative case is used for the subject of a sentence or clause.

	OBJECTIVE CASE: If you don't like passive voice (there I go being all
grammatical again), you might try rewriting it in active voice:

/gs rp Hey guys, I'm summoning %tt.  If you don't click the portal, demons will
eat %to in 5 ... 4 ... 3 ... 2 ...

In this case, %to becomes either "him" or "her" -- objective case is used for a
direct or indirect object, or the object of a preposition.

	POSSESSIVE CASE: Not *really* a pronoun, these are used to describe
whose it is:

/gs rp Hey guys, I'm summoning %tt.  If you don't click the portal, demons will
come to eat %tp face in 5 ... 4 ... 3 ... 2 ...

("... demons will come to eat his/her face").  Possessive case "pronouns" are
really just adjectives.

	LONG-FORM POSSESSIVE CASE: Certain rare grammatical situations require
this.

/gs rp Hey guys, I'm summoning %tt.  If you don't click the portal, %tq will be
a horrible fate ...

("... his/hers will be a horrible fate").  Long-form possessive case "pronouns"
are only used as predicate adjectives ("This hat is mine" as opposed to "This
is my hat") and when a possessive gets nominalized ("Give me my hat, not
hers").

	Grammar lesson over.  Who said games can't be educational?  :)

*** Suppose you're a Priest, and you want to automatically say something about
whom you're resurrecting.  First let's think about this: You can cast
Resurrection on somebody whether they're in your party or not, but if you're in
a raid or party, they're the ones who will want to know who you're rezzing, so
you'll want something like "/gs irps."  Also, you won't have a target if
they've already released their spirit, so you don't want to say anything in
that case, or you'll get "<no target>" (thank goodness GemSay automatically
prevents that!).  You don't want the message to be the same all the time --
that would be boring! -- but you probably always want to clearly denote who's
getting a rez right now.  That means there should be an unchanging part and a
variable part to your message.

	So how do you do that? First, you need a message category.  Type /gsr,
press "New Category," and call it something (suppose you call it "rez").  Then
press "New Message," enter a message, and press OK.  Add as many clever
messages as you can think of.  I've got a collection of these started; they're
in the rez_macros.txt file that should come with GemSay.

	Next, make a trigger to use your messages.  Type /gst, press "New
Trigger," select "Cast Started" as the event type (you don't want "Cast Button
Pressed" because you don't want a message to go out if you're casting on
somebody you can't rez, like somebody who is already alive), open your
spellbook, and drag your Resurrection icon into the box.  You'll probably want
this message to appear 100% of the time (hopefully people aren't in need of
Resurrection so often that this becomes tiresome!).  Then set the command to
/gs, use "irps" as the destination, and type this into the Message blank:

*> Now rezzing %tt. <*  %grez

	Now every time you cast Resurrection, it will say (depending on your
target's name and the messages you entered in the "rez" category):

*> Now rezzing Ishikawa. <*  Stop slacking; you can sleep when you're ... um
... OK, never mind.

*** Suppose you're a Mage, and you want to automatically notify people that
you're going to Polymorph something.  Well, "irps" as a destination works here,
because you can help people with Polymorph whether you're in their party or
not.

	This works the same way as the Resurrection macro.  Make your Polymorph
message category (let's call it "sheep"), put messages in it, then make a "Cast
Started" trigger for the Polymorph spell.  Set the command to /gs, use "irps"
as the destination, and use this in the Message blank:

*> Sheeping %tt. <*  %gsheep

	You have a bit more complication because of the existence of other
Polymorph variations such as Polymorph: Pig and Polymorph: Turtle.  However, if
you have a macro or addon that randomly selects a Polymorph spell for you, such
as

/castrandom Polymorph, Polymorph: Pig

(note: this macro needs to be updated) then GemSay will trigger as normal when
those spells are cast.  You will have to make a separate trigger (and
potentially a set of categories) for Polymorph: Pig, or that will be cast with
no messages.

*** What if you're a Warlock, and you want to send your raid/party a message
whenever you Soulstone somebody?  It works just like the above.  First, create
a "Cast Started" trigger and drag the Soulstone icon from your spell book into
the box.  Then proceed as in the other examples.

*** If you're a Hunter or Warlock (or Frost Mage with the Water Elemental out),
you can say something when your pet attacks.  Make a new trigger and select
"Pet Attack" as the event type.  You probably want the frequency to be about
10% for this one, or it will get annoying fast.  Set the command to /gs and the
destination to "s".  Then set the message to be something like

Oh dear, %et thinks %tt looks tasty ...

The "e" prefix means GemSay will substitute your pet's name in there instead of
your target's.  Note that this trigger goes off whenever your pet attacks,
whether it's because you ordered it to or because it attacked on its own
(e.g. it was set on Defensive and reacted when something attacked it or you).

SPELL EVENT NOTES
-----------------

You might see cast_process.txt for more discussion about this, but here are
some tips based on what I've found for binding events to spells.

First of all, you probably never want to bind anything to "Cast Button Pressed"
unless you really want a message to go out whether or not the cast succeeds.
If you're out of mana, casting on an invalid target, out of reagents, out of
range or line of sight, don't have any combo points on the target, or any other
reason why the ability would fail immediately, the message would still go out.
But what event you want to bind a message to varies on the type of spell or
ability.  So here are the spell/ability types I'm talking about, and how to
handle them:

TYPICAL: Most spells and abilities have a cast time and are neither instant nor
channeled.  You will most likely want to bind your messages to "Cast Start,"
because this event (called UNIT_SPELLCAST_START internally) fires once the
server determines that you are able to cast that spell on that target.

INSTANT-CAST: The UNIT_SPELLCAST_START event will never occur for instant-cast
spells.  The UNIT_SPELLCAST_SUCCEEDED event is the one you want to bind things
to for instant-cast spells, and in GemSay I've called this "Cast Succeeded."
Note that this holds true for instant-cast channeled spells as well, and most
channeled spells are instant-cast.

NON-INSTANT CHANNELED: There may still be a few non-instant channeled spells --
but I can't think of any.  The three I used to use as examples were Ritual of
Refreshment (the mage table), Ritual of Summoning (warlock summons) and Ritual
of Souls (the soulwell), but those have all been changed; mage tables and
soulwells aren't channeled anymore, and warlock summons are now instant-cast
channeled.  If any more non-instant channeled abilities exist, they give you
the possibility of more than one message: a "Cast Start" message when the cast
begins, and a "Cast Succeeded" message when the casting phase ends and the
channeling phase starts.

	Now go have fun!

KNOWN ISSUES
------------

	Here are the known bugs and other issues as of version 1.5
(2008/10/18):

UNTESTED: I don't know whether it really works in raid warning.

UNTESTED: %g should be capable of handling the situation where you have global
and character-specific categories with the same name, effectively combining the
two lists into one big list and picking a random message from that, but I
haven't actually tried it out.

INCOMPLETE: I currently don't know how to tell whether you have the right to
speak in guild officer chat, so I can't test for that when you attempt to send
a message there.  Currently I'm only testing whether you're in a guild at all
when you use "/gs o <msg>".

INCOMPLETE: There's no frame around the EditBox when you're editing a message.
I don't know how to put a frame around a multiline EditBox.  Everything I tried
just put a frame behind it that was 1 line high, or sometimes a squashed frame
that was 0 lines high.  But it works fine without a frame; it just looks odd.

BUG: %p* codes (announcing details about you yourself, the player) are somehow
considered "targety" and get suppressed if you have no target, even though it
shouldn't matter. [2013-06-19: Is this still happening?]

BUG: The main editor window remains active and clickable when there's a dialog
box popped up in front of it.  This despite the fact that I'm setting
enableMouse and enableKeyboard to false on the main window when the dialog box
pops up.  Apparently I'm doing this wrong, but I don't know what the right way
is to temporarily make the main window insensitive. [2013-06-19: Is this still
happening?]

BUG: If you're editing a message and highlight text with the mouse, the
highlighting escapes from the box and goes all the way to the right side of the
screen if you select text from more than one line.  I currently don't know how
to prevent this.

BUG: When you're creating/editing a "Cast *" trigger, and you drag an icon off
one of your action bars into the editor window's button, your icon is gone from
your action bar, and you can't drag it back.  I don't currently know how to put
it back on the action bar -- once you grab it from the action bar, it's already
gone; the UI doesn't seem to remember what slot it used to be in, so I can't
put it back.  I wish I knew how to resolve this.
