@rem This file introduces the new features of version 2.

@rem I have not provided a tutorial for these new features, but documentation
     and old tutorials have been updated where appropriate. It is presumed 
     that by the time you have completed the five tutorials, then you will 
     have a firm enough understanding of CAT to use this document as it stands.

@rem If you have created an adventure with CAT V1, you can just regenerate 
     it using CAT V2, and then re-compile it. This will give your adventure
     all the new features of V2. The only thing that you should be aware of
     is that V1 game save files will no longer load - and may crash your
     adventure if you attempt to load them.

@rem *************************************************************************

@rem GEN now supports a further 4 switches as follows:

     -R		Tells GEN to perform a report only run. The only file that
		will be written is GENOUT.TXT. This switch is useful if 
		you want to check the syntax of your definition files,
		without wasting all the time involved in creating C source.

     -C         This switch tells GEN to compress the text in your adventure.
                WARNING: compressing adventures with small amounts of text may
                         result in LARGER programs being generated. Compression
                         will be most successful in games with a lot of text.

     -Apath     This switch tells GEN to automatically copy GENSRC files from
		\CAT\GENSRC to the destination folder. A path can be optionally
		specified, telling GEN where the GENSRC files live on your 
		system.

     -Dpath     This switch tells GEN where to place the source it generates.
		For example, you could write all source to a ram drive with
		this option - thereby considerably reducing generation time.

@rem *************************************************************************

@rem GEN switches can now be specified in your GENLIST file. Any switches 
     included in the GENLIST file will override conflicting switches from the
     command line.

     For example, the following GENLIST will automatically copy GENSRC from
     \CAT\GENSRC, and output will be encrypted.

     -e
     -a 
     \cattutr5\first.d
     \cattutr1\tutor1.d
     \cattutr2\tutor2.d
     \cattutr3\tutor3.d
     \cattutr4\tutor4.d
     \cattutr5\tutor5.d
     \cat\std\zzstd.d
     \cat\std\zzrqd.d
     \cattutr5\last.d

@rem *************************************************************************

@rem GEN will now report on any text that is over 254 characters, and 
     is therefore likely to be unportable between compilers. The default 
     action of a C compiler is to lop off the extra characters and 
     say nothing - so it is important that GEN provides this check.

@rem *************************************************************************

@rem The " character can now be used in any text, as can the \ character.

@rem *************************************************************************

@rem @FIRST and @LAST logic modes are now supported. 

     FIRST logic is executed as soon as the program loads.... before the
           title screen is displayed AND before any decryption takes place.

     LAST  logic is executed just before the program ends.

     A typical use of @FIRST and @LAST logic processing would be to turn the
     mouse off in FIRST processing, and back on again in LAST processing. 
     Note: you will still need to use external functions to actually perform
     the task of turning the mouse on and off.

@rem *************************************************************************

@rem @ROOMSEEN can now be used to determine whether or not a room has been
     visited. CAT already had this information, but it was not accessible 
     through CAT logic.

@rem *************************************************************************

@rem Remarks can now be included in logic groups, for example.

     @rem this is a comment
     @if @iscarried(hammer) @do
        @rem This is another remark - 
             covering two lines
        @pmsg(carrying_hammer)
        @rem another comment
        @pmsg(testing)
     @endif
     @rem That's all folks!

@rem *************************************************************************

@rem Full string support is now available.

     Ten strings are automatically provided, with sizes as follows:

     S1          - 200 characters
     S2          - 200 characters
     S3          - 100 characters
     S4          - 100 characters
     S5          - 100 characters
     S6          - 100 characters
     S7          -  50 characters
     S8          -  50 characters
     S9          -  50 characters
     S10         -  50 characters

     It is also possible to create up to 90 of your own strings. 

     Only the ten automatic strings will be saved as part of saved games, 
     therefore - you should only use the automatic strings to store information
     that is relevant to the current game position. 

     You can use your own strings to contain temporary data, or to hold any
     text that will never change - i.e. comparison strings etc.

     Strings can be defined with initial text, and this text will be 
     restored whenever the adventure is restarted.



     The following tokens can be used to define strings:
     ===================================================

     @STR name             - give the string a name
     
     @STRSIZE              - define size of string (up to 254 characters).
			     The default size of a string is 254 characters.

     @STRTXT               - Initial value of string.

     @ENDSTR               - End of string definition.



     The following tokens can be used to query strings:
     ==================================================

     @STRNO(str)           - return number of str.

     @STRLEN(str)          - return length of str.

     @STRASC(str)          - return ascii code of 1st character in str.
     
     @STRNUM(str)          - returns the numeric value contained in str.

     @PSTR(str)		   - prints str.

     @STRFCHR(str,c)       - return position of character c in str,
                             or -1 if no match.

     @STRFSTR(str1,str2)   - return position of str2 in str1, or -1 if no 
			     match.

     @STRCMP(str1,str2)    - returns  0 if str1 and str2 are the same.
                                     <0 if str1 is less than str2.
				     >0 if str2 is greater than str2.



     The following tokens can be used to affect strings:
     ===================================================

     @MSGTOSTR(msg,str)    - copy msg into str.

     @NUMTOSTR(val,str)    - Convert val to a string, and save in str.

     @OLTOSTR(obj,str)     - Copy object long text to str.

     @OSTOSTR(obj,str)     - Copy object short text to str.

     @RLTOSTR(room,str)    - Copy room long text to str.

     @RSTOSTR(room,str)    - Copy room short text to str.

     @GETSTR(str,size,sep) - get input from the player and place in str.
                             size is the maximum number of characters.
                             If sep is 1, separators will be allowed.
                             If sep is 0, separators will NOT be allowed.

     @STRCLR(str)          - clear str.

     @STRUPP(str)          - convert str to upper case.

     @STRLOW(str)          - convert str to lower case.

     @STRCAP(str)          - convert first character of str to upper case.

     @STRADDC(str,c)       - adds character c onto end of str.

     @STRCPY(str1,str2)    - copies str2 onto str1.
   
     @STRCAT(str1,str2)    - concatenate str2 onto str1.

     @STRPCPY(str1,str2,s,l) copies part of str2 into str1.
                             s= start position
                             l= number of characters to copy.


     *** WARNINGS ***

     When referring to a CAT string, you are actually referring to a number,
     it is therefore very important that you do not use standard C functions 
     to access them - always use the CAT logic tokens.

     The first character of a string is in position 0, and NOT 1.

     With any string functions where a string name appears anywhere other than
     as the first parameter, you must use @STRNO to convert the parameter
     to a string - otherwise CAT will presume the parameter is the number of
     an object. I.e.

        @rem Copy characters 10-14 from MY_STRING into S1.

        @STRPCPY(s1,@strno(my_string),10,5)

     It is your responsibility to ensure that you do not write past the end
     of any given string - i.e. if a string is defined with @STRSIZE 50, 
     then make sure it never contains more that 50 characters. 
     IF THIS HAPPENS, UNPREDICTABLE RESULTS MAY OCCUR!

@rem *************************************************************************

@rem Macros can now be included in any piece of text - these will be expanded
     whenever the text is displayed as follows:

     $1, $2, $3, $4 etc. - replaced with value in 1st, 2nd, 3rd, 4th string etc.

     #1, #2, #3, #4 etc. - replaced with value of 1st, 2nd, 3rd, 4th counter etc

     $A                  - replaced with the actor, from command line.

     $V                  - replaced with verb, from command line.

     $VC                 - replaced with compound verb, from command line.

     $N                  - replaced with noun, from command line.

     $NC                 - replaced with compound noun, from command line.

@rem For example, the following would print:

     BOB: "I have no time to PUT KEY IN BED" ...

     (If the user issued the command 'bob, put the key in the bed')

     @str    tmp_str		@Rem String number 11 (1-10 already defined)
     @strtxt I have no
     @endstr

     @msg    tmp_msg
     @msgtxt $A: "$11 time to $V $N $VC $NC"
     @endmsg

     @low
        @if @playeris(bob) @do 
           @pmsg(tmp_msg)
        @endif

@rem *************************************************************************

@rem Verb checking will now tell you which object is in error. For example
     if the user typed 'Put the key in the box', and the box was not available,
     then the adventure would have just reported:

        You don't see that here.

     Now, you will get:
 
        BOX: You don't see that here.

@rem *************************************************************************

@rem A command line interface has been provided for user input in adventures.
     The following keys map as follows:


     7  8  9
      \ | /     The numeric keypad can be used for directional movement.
                (i.e. 8-North, 3-Southeast etc)
     4- 5 -6 

      / | \     additionally 5-Up and 0-Down.
     1  2  3

      
     [          Repeat last command line

     ]          Delete entire command line

     *          Delete one word from command line

     Ctrl(A)    Repeat last verb
          B     Repeat last noun
          C     Repeat last compound verb
          D     Repeat last compound noun
          E     Examine
          F     Drop
          G     Get
          I     Inventory
          J     Jump
          K     Kill
          L     Look
          N     No
          O     Open
          P     Close
          Q     Quit
          R     Restore
          S     Save
          T     Lock
          U     Unlock
          V     Vocabulary
          W     Whoami
          X     Exits
          Y     Yes
          Z     Copyright line


@rem The standard advertisement has been changed to include details of these 
     command line editing keys.

@rem *************************************************************************

@rem A new program (CATHELP) has been provided to allow quick access to the
     Cross reference manual CATMAN.TXT. 

     When you supply keywords to CATHELP, it will scan the manual for headings
     that contain your keywords, and display each of the matching sections.
     You can supply as many keywords as you like.

     For example, the following command would find all topics relating to 
     strings, and messages: CATHELP str msg

     Or this would find details of all definition tokens: CATHELP defin

     Or this would find all details to do with logic: CATHELP logic
 

     CATHELP will look in the current folder, the root folder, the \CAT folder
     and the \CATSRC folder for a CATMAN.TXT file. If it doesn't find the 
     file in any of these folders, it will give up.

     
     If you are running CATHELP from the GEM desktop, then you will have the
     opportunity to type your keywords on the parameters screen.

@rem *************************************************************************

@rem The player can now use 'EXCEPT' in commands. For example:

        GET ALL EXCEPT THE HAT.

        PUT EVERYTHING EXCEPT THE KEY INTO THE CHEST.

@rem *************************************************************************

@rem RAMSAVE and RAMLOAD are now supported to allow the game position to 
     be saved to memory.

@rem *************************************************************************

Runnable adventures for CATTUTR4 have been removed due to disk space crisis!

@rem *************************************************************************

@rem And finally, for CATEXPRT users....

@rem External functions are now called WITHOUT the preceding underbar (_).
     You still need to use the underbar in CAT source, but this will be 
     stripped before the call is placed in the generated C source.

     This change will allow the advanced user to call C library functions,
     as well as their own custom C functions - DIRECTLY from CAT source.

@rem For portability reasons, all machine specific code from the GENSRC files
     has been moved to a separate file - PORTAB.I. This should greatly smooth
     the efforts required to port CAT adventures to another machine.

@rem *************************************************************************




*** VERSION 1.0 PROBLEMS CORRECTED AS FOLLOWS: ***

@rem *************************************************************************

@rem The @RANDOM function was returning negative numbers on some C compilers.
     This should now be fixed.

@rem *************************************************************************

@rem In version 1, expressions like @PVAL(1*2+tony/apple) were not being 
     processed properly. With version 2, the above expression will be 
     correctly parsed to: PVAL(1*2+O_TONY/O_APPLE)

@rem *************************************************************************

@rem @FIRSTOB and @LASTOB will now include objects that are worn.

@rem *************************************************************************

@rem Counters are now reset to zero at the start of every game. 

@rem *************************************************************************

@rem Not all messages were encrypted/decrypted properly. This has been 
     corrected.

@rem *************************************************************************

@rem @ENDGAME can now be used in initialisation logic.

@rem *************************************************************************

