SayHelp screen 99: Long tutorial
--------------------------------
`
Right, someone surprised me by saying that the sayhelp documentation was
 confusing.  I suppose that one of the problems with developing a program
 is over-familiarity.  Believe me, the documentation on previous versions
 were far worse.  I'd better not take up technical writing as a career.
`
Things you type appear as:    > "Type from after the '>' character
Example computer output as:   - Spelvin says, "This is an example"
`
I will not echo the 'I've done that' reports from the computer.
`
--------------------  SIMPLE VERBS
`
I originally wrote say because I wanted to provide a way of switching verbs
 quickly.  This works as follows:
`
A 'verb' is defined as the text that forms the verb after which your speech
 appears.  The normal (or 'default') verbs are 'says' or 'say'. If you want to
 change those to 'purrs', for example:
`
   > sayset def purrs,       [This sets the 'Spelvin purrs' verb others see]
   > sayset +def purr,       [This sets the 'You purr' verb which only you see]
`
The verb switching facility works by looking at the first character of the
 message you give say, and seeing if it knows to associate that character
 with a verb.  The character is called the macro character.
`
   > "%It's a green Wombat!                [Would normally produce..]
   - Spelvin says, "%It's a green Wombat!"
`
   > sayset % gasps,                       [But after this 'sayset'..]
   > "%It's a green Wombat!
   - Spelvin gasps, "It's a green Wombat!"
`
If you want to see a 'You gasp' type message, you'll need to tell say about
 that verb too.  Put a '+' before the '%', the macro character.
`
   > sayset +% gasp,
   > "%It's a green Wombat!
   - You gasp, "It's a green Wombat!"
`
Of course, you're not limited to the macro '%'. You may use any other
 single character. '~' and '@' no longer cause errors.
 If you want to set space as a macro, you must type
`
   > sayset sp squeaks,              > sayset +sp squeak,
`
To see your current state, type 'sayset' on its own.
`
You can clear verbs by putting a blank verb: > sayset def   > sayset +def
`
You can clear *everything* (verbs, quotes and filters) from a macro with
`
   > sayset clear def          > sayset clear %        ..and so on.
`
--------------------  QUOTES
`
You can also set customised quotes for 'def' or a given macro character.
`
   > sayset quotes def <<%m>>
   > "I'm hungry.
   - Spelvin says, <<I'm hungry>>
`
If a macro doesn't have its own quotes, it will use those for 'def'.
`
To set quotes to 'default', miss the %m bit out:  > sayset quotes &
`
--------------------  SPLIT SPEECH AND ADHOC VERBS
`
After I had written the verb macro code, I decided to allow verbs to appear
 in the middle of speech.  This is not universally popular, and so a player
 may request only to see speech once it has been forced into the normal
 style, like  Spelvin says, "Whatever".
`
   > sayset normal           [Forces others' speech into non-split format]
   > sayset !normal          [You can see the split style speech]
`
 To utter spech in a split format, type ',,' where the verb should go.
`
   > "This is,,split style speech.
   - "This is," Spelvin says, "split style speech."
`
   > "This is split too,,
   - "This is split too," Spelvin says.
`
   > "%You can also,,use macros.
   - "You can also," Spelvin gasps, "use macros."
`
If you want to, you may use a verb without setting a macro, by allowing
 'ad-hoc' verbs.
`
   > sayset !adhoc                             [Disallows 'adhoc' verbs]
   > sayset adhoc                              [Allows 'adhoc' verbs]
   > "This,,complains,,is getting confusing.
   - "This," complains Spelvin, "is getting confusing."
`
   > "You wouldn't dare!,,growls %n, looking all fierce,,
   - "You wouldn't dare!" growls Spelvin, looking all fierce.
`
The trailing commas here distinguish a simple split say from an adhoc verb.
 Otherwise, you'd get:
`
   > "You wouldn't dare!,,growls %n, looking all fierce.
   - "You wouldn't dare!" says Spelvin, "growls %n, looking all fierce."
`
`
A detail here is that in split speech, the name usually appears after the verb.
 Putting a comma at the end of a verb makes say put the name before the verb.
`
   > "Look,,squeaks,,         - "Look," squeaks Spelvin.
   > "Look,,squeaks,,,        - "Look," Spelvin squeaks.
`
This also happens to verbs set with sayset. A trailing comma has no effect on
 non-split style speech.
`
`
Two special verb styles are available and both influence split speech.
`
There is an old form which disables you from using split speech for a macro:
`
   > sayset ! says, "%m"
`
   > "!This,,is,,split,,not,,at,,all
   - Spelvin says, "This,,is,,split,,not,,at,,all"
`
A second form allows you to put text after the second half of a split message:
`
   > sayset ! says%2 and growls.
`
   > "!Shut up!
   - Spelvin says, "Shut up!" and growls.
   > "!It's mine.,,bog off!
   - "It's mine." Spelvin says, "Bog off!" and growls.
`
----------------  QUERY
`
After writing split speech, I decided to do something about saying 'bye' to
 people who had just left, but whose departure the lag had hidden.
`
   > sayset !query            [Disables this facility]
   > sayset query             [Enables this facility]
   > "?Riss,,Bye!
   - Spelvin says, "Bye!" to Riss.
or - Riss is here but asleep.
or - I don't see that here.
`
   > "?Riss,,?Kimi,,?Fuzz,,Aaargh!
   - Spelvin says, "Aaargh!" to Fuzz, Riss and Kimi
(This only works if Riss, Kimi *and* Fuzz are all present and awake.)
`
If you don't put a message at the end, you will just get a status report.
`
   > "?Riss
   - Riss is here and awake.
or - Riss is here but asleep
`
Note, if you're using this, you can't use the macro '?'
`
---------------  OOC (Out Of Character) MODE
`
This was requested by Riss.
`
The intention here is to distinguish between a character who can answer
 techincal questions and ones who are capable of asking questions like
 'What is a Florida?'
`
The flag _ooc is changed from _ooc:yes to nonexistence. Hopefully, pose and
 other programs will support it sometime.
`
   > sayset !ooc      [Unsets OOC mode]
   > sayset ooc
   > "Type @link ba = #2
   - Spelvin says (OOC), (Type @link bs = #2)
`
You can customise OOC mode by typing 'ooc' where you could type 'def'.
`
---------------  FILTERS
`
This was the other major introduction to speech.  A filter is a program,
 seperate from the say program, which is called by say to modify text or
 perform some other function.  If you are familiar with pipes in Unix, then
 this is similar.
`
To see a brief description of what sort of filters are available, type
`
   > sayfilter
`
Name         | Description, For more help, type 'sayhelp <filtername>'
-------------+----------------------------------------------------------
$RandomVerbs | Not a filter. Selects random verbs.
Reverse      | Reverses speech character by character
Replace      | Standard text replacing filter
-------------+----------------------------------------------------------
`
Because filters have help on them, I can only give general help here.
`
Filter help from  > sayhelp <filtername>
`
A 'filter' which begins with '$' is a verb-program and supplies verbs via a
 program rather than reading fixed properties.
`
   > sayhelp $RandomVerbs
   - ....
   > sayset def $RandomVerbs
`
 If a verb program takes commands, they are issued with
`
   > ",,<command>
`
 See the verb-program helps for more information. eg > sayhelp $RandomVerbs
`
A normal filter modifies spoken text. You add a filter to a macro with
`
   > sayfilter def fadd <Filtername>     ['def' can also be '%' etc]
`
List which filters are on a macro with
`
   > sayfilter def flist
   - def/1 : Replace
   - def/2 : Jumble
   - def/3 : Quotation
`
And remove a filter with
   > sayfilter def ftake <filtername>
or > sayfilter def ftake.<position-in-flist-list>
`
To send a command to a filter on a macro, eg 'def',
`
   > sayfilter def <command>
`
If you wanted to send the command 'foo bar 5' to the filter 'Quotation' (number
 3 on the list), but you thought 'Replace' might know about it too, you can
 type:
`
   > sayfilter def foo.3 bar 5
`
This also works in taking fliters off macros.
`
          > sayfilter def ftake.2
but also: > sayfilter def ftake Jumble
`
-------------------------------------------------------------------------------
Sorry, this is scruffy at the end, but I'm tired and this should get you to the
 stage of being able to read sayhelp 1-11.
. Err, sorry. I said it was late. 3-10
-------------------------------------------------------------------------------