____________________________________
   
                             WHAT'S NEW in 3.0?
                      ____________________________________
                      

  Version 3.0 is the first major revision of PERCEPS in 6 months, and it has
  a number of powerful new features.  I have tried to address most of the 
  concerns and feature requests brought to my attention by the PERCEPS user
  community since the introduction of version 2.0.  The following document
  describes the new features added since version 2.1.1.
  
  Contents:

 	 A) Documentation of non-class items.
 	 B) Nested class support.
 	 C) Support for unions.
 	 D) Input custom filtering.
 	 E) Inline, abstract class, & pure virtual function detection.
 	 F) Support for comments placed before members.
 	 G) Recursive directory searching.
 	 H) Custom sorts.
 	 I) Loop conditionals.
 	 J) Global variable multi-file templates.
 	 K) Item name regular expression matching.
         L) Exception handling support


  A) Documentation of non-class items:
  
  By far the most asked-for feature, PERCEPS now detects and documents 
  non-member functions, global variables, typedef statements, and macro
  definitions.  This extends the functionality of PERCEPS and makes it
  a useful tool for documenting conventional C-code as well as C++.  The
  rules governing commenting of these items are straightforward.  All
  comments referring to a non-class item must come either before the
  item or on the line containing its declaration.  As with classes, all
  comments preceding the item must follow a short description comment
  unless the -u command-line option is specified.  Variable declarations
  with the "extern" keyword are ignored, and only function definitions,
  not declarations, are documented.  The functionality of the {foreach}
  statement in templates has been extended to support the newly documented
  items.  {foreach item} will loop over all items (not just classes), and
  {foreach union}, {foreach func}, {foreach global}, {foreach typedef},
  and {foreach macro} statements are now supported and loop over the 
  corresponding items.  {if} statements have also been extended in the
  obvious way to allow testing of item types (e.g. {if macro} is true if
  the current item is a macro, etc.)  See the documentation for details.
  

  B) Nested class support:
  
  Perceps will now detect and document nested classes.  Nested classes
  are documented separately from their containers, and are assigned
  the name "Containerclass::Nestedclass".  For documentation purposes,
  the container class treats the nested class as a member variable
  of type class (or struct).  For html documentation, PERCEPS will
  attempt to link the container and nested classes' documentation pages.
  Perhaps the best way to understand handling of nested classes is to 
  study the example files.
  
  
  C) Support for unions:
  
  Unions are now documented.  For documentation purposes, unions are
  treated just like classes.
  

  D) Input custom filtering:
  
  Input files can now be passed to a plugin filter before processing.
  If the filter file "input.flt" exists in the template directory,
  input files will automatically be passed through this filter before
  any other processing occurs.  This feature can be used to perform
  any macro substitutions necessary to obtain correct documentation
  or otherwise clean up the code.
  
  
  E) Inline, abstract class, & pure virtual function detection:
  
  PERCEPS now detects existence of inline functions within a class
  declaration and pure virtual member functions.  In templates, the 
  {if hasinlines} statement will be true if the corresponding class
  has any inline code, the {if pure} statement will be true if the
  corresponding member is a pure virtual function, and the {if abstract}
  statement will be true if the corresponding class is abstract (has
  pure virtual functions).
  
  
  F) Support for comments placed before members:
  
  PERCEPS can now optionally treat comments coming BEFORE a member as
  corresponding to that member.  To use this option, set the -b command
  line switch.  Note that, with the -b option, comments corresponding to
  the class as a whole MUST come before the class.
  
  
  G) Recursive directory searching:
  
  PERCEPS will now accept directories as command line arguments.  If a 
  directory is specified, it will be searched for all files matching a 
  suffix list.  Allowable suffixes can be specified on the command line
  with the -s switch, or the default suffix list can be used.  The default
  suffix list can easily be changed by editing line 7 of the PERCEPS
  source.
  
  If the -f command line switch is specified, directories will be searched
  recursively.  The "subdir" global variable will be set to the directory
  where each item is found.  This global can then be used to build
  documentation that respects the folder hierarchy of the code distribution.
  
  PERCEPS will search each directory for a ".perceps" file, which can
  be used to specify per-directory options. Currently, the .perceps file
  may contain 3 different statement types:
  
      suffixes suffix-list
      
        Sets the suffix list for the directory and all subdirectories to
        "suffix-list," which is a comma-delimited list of allowable
        suffixes for documentable files.
        
      (+/-)recursive
      
        Turns recursive subdirectory searching (on/off)
        
      global variable = value
      
        Sets the default value of the global variable "variable" to
        "value" for all files in the directory.  This default value
        can be overridden using global variable statements within
        documented files.
  
  
  H) Custom sorts:
  
  Items in {foreach} loops can now be subjected to a customizable sorting
  function.  The statement {foreach ITEM sort} will sort ITEMs in default
  alphabetical order.  For custom sorts, the syntax is:
  
      {foreach ITEM sort SORTFUNC}
      
  where SORTFUNC can be either 1) a quoted block of perl statements comprising
  the sort function, or 2) a file (in the template directory) containing
  perl statements comprising the sort function.  The rules for creating sort
  functions are the same as with the perl "sort" command.  The sort function
  should compare the variables $a and $b and return either -1,0,or 1 to
  establish their sort order.  As an example, the following statement will
  sort items in reverse alphabetical order:
  
     {foreach ITEM sort "$b cmp $a;"}
     
  Due to limitations in the PERCEPS template file parser, quoted blocks 
  cannot contain subexpressions in braces.
  
  
  I) Loop conditionals:
  
  The conditional statements {if first}, {if last}, and {if mid} have been 
  added and can be used to test whether the current item corresponding to
  an enclosing {foreach} block is the first or last item in the loop, or
  is neither.
  
  
  J) Global variable multi-file templates:
  
  Just as the "CLASS" keyword can be inserted in template file names to 
  generate a separate version of the output file for each documented class, 
  template files containing the pattern "@GLOBAL@", where GLOBAL is any global
  variable, will be used to generate separate output files for each value of
  GLOBAL.
  
  When output files names are generated, any spaces or file delimiter 
  characters in the global value will be replaced with an underscore "_".
  In order to allow linking to these files from within other templates, the
  syntax of the {name} and {GLOBAL} tags has been extended.  The {name @} and
  {GLOBAL @} tags will be replaced with the corresponding global name
  after the underscore substitution described above has been performed.
  
  
  K) Item name regular expression matching:
  
  The statement {if name /regexp/} is true if the current item (the one
  which would substitute for the {name} tag) matches the perl regular
  expression "regexp." Due to limitations in the PERCEPS template file 
  parser, regexp cannot contain braces.
  

  L) Exception handling support
  
  Functions that throw exceptions are now recognized and the exception
  handling code is parsed.  A set of template tags has been provided
  to work with exception data.  See the documentation for details.