-=-  -=-  -=-  -=- MagicStats 2.0 Notes List -=-  -=-  -=-  -=-

<a name="2.0pr12-2.0pr13">
NOTE: Incompatible changes between MagicStats2.0pr12 and MagicStats2.0pr13!

  MagicStats2.0pr13 breaks backwards compatibilty in the following two ways:
    1. The "UnescapeURL" AccessFilter plugin has been renamed "Unescape".
       FIX: Change name in your [Global/Filters] tag.

    2. Filters must be specified in list notation in config files.  In pr12 and
       earlier, MagicStats allowed filters to be specified as a string with a
       comma in it (to distinguish include vs exclude), or as a list of two
       strings.  MagicStats2.0pr13 and above will only support list notation.
       FIX: Change all occurances of $(SectionFilter) : "xyz,abc"; into 
            $(SectionFilter) : ["xyz", "abc"];  Note that empty strings must 
            still be represented.  For example: ["xyz*", ""] is a valid filter.


NOTE: Valid things to MSInsert:

1. Any Variables
2. Dates
  a. Date			- Current Date
  b. YesterdayDate
  c. TomorrowDate
  d. UpdateDate			- The date the page is being created

  z. Format tag
    i.   Numeric		- "%Y%m%d" Example: 19940915
    ii.  Long			- "%A, %B %d, %Y" Example: September 15, 1994
    iii. Short			- "%m/%d/%Y" Example: 9/23/97
    iv.  TimeDate		- "%c" Example: 9/23/97 8:34AM
    v.   NumericMonthly         - "%Y%m" Example 199409
    vi.  Arbitrary strftime	- Any output format...

3. Miscellaneous
  a. Version			- Current software version "2.0 beta 6"
  b. ElapsedSeconds		- The number of seconds since processing began.
  c. MagicStatsURL		- The URL of the MagicStats web page.
  d. MSCopyright                - MagicStats Copyright Message
  e. MSBuiltInURL               - URL of "BuiltIn" MagicStats resources


NOTE: Tags that are expanded in filenames:

1. %d/%D - Expands the current date as %Y%m%d.  Example "19980423"
2. %m/%M - Expands the current date as %Y%m.    Example "199804"
3. %y/%Y - Expands the current date as %Y.      Example "1998"
4. %%    - Expands as a single %


NOTE: Global AccessLog parameter format:

1. Simple string: Treated as a filename of an access log. 
      EX: AccessLog : "/usr/local/httpd/logs/access_log";
2. List of entities.  Each entry processed depending on its type:
  a. String: Treated as a filename.
      EX: AccessLog : [ "/usr/local/httpd/logs/access_log", "~/foo" ];
  b. List: List must be a list of strings, with maximum length 3.  The first
           item is the filename, as before.  The optional second item is a 
           domain to use for the access log.  The optional third item is the
           specific plugin to be used.
      EX: AccessLog : [[ "/usr/local/httpd/logs/access_log", 
                         "http://www.magicstats.com"], 
                       "~/foo" ];


NOTE: Variables passed into themes:

1. All VariableDefaults are passed in unless overridden
2. User defined variables.
3. ($MS.ThemeResURL) - URL of the current Theme resource directory.
4. ($MS.ThemeName)   - Name of the current theme...
5. ($MS.UserName)    - The username of the owner of the stats files.


NOTE: Variables passed into all files:

1. ($MS.UserName)        - Current user name on host system...
2. ($MS.Update.Always")  - Constant for UpdateFreq value.
3. ($MS.Update.Daily")   - Constant for UpdateFreq value.
4. ($MS.Update.Weekly")  - Constant for UpdateFreq value.
5. ($MS.Update.Monthly") - Constant for UpdateFreq value.
6. ($MS.Update.Yearly")  - Constant for UpdateFreq value.
7. ($MS.Update.Never")   - Constant for UpdateFreq value.
8. ($MS.BuiltInURL)      - URL of BuiltIn resource directory


NOTE: Special Variables that may be used:

1. ($MS.<anything that doesn't match a pattern above>) is automatically checked
   to see if it corresponds to an MSInsert'able variable.  Parameters may be
   passed (as in MSInsert) by seperating them with : and = characters.  For 
   example, these are valid:

   a. $(MS.Date:FORMAT=Numeric)
   b. $(MS.Version)
   c. ...


NOTE: How to operate filters:

1. Each filter is broken into two pieces, the inclusion and exclusion part.

2. To be accepted, the access has to "Match" the inclusion part, and NOT 
   "match" the second part.

3. Each part of the filter may be of the following three types:
   a. !<accessfield>!<regex>!
   b. |<accessfield>|<UNIX Wildcard Match>|
   c. <UNIX Wildcard Match>

4. <AccessField> may currently be any of the following literal strings:
   a. "Url"      - The URL Requested
   b. "Host"     - The Host that requested the page
   c. "Type"     - GET, POST, etc...
   d. "Date"     - Date of access
   e. "Protocol" - HTTP/1.0 or HTTP/1.1
   f. "Status"   - Status code returned
   g. "Size"     - Size of the file returned
   h. "Auth"     - Authorization information

5. <regex> is currently a standard UNIX Regular Expression, including most of 
   the extensions that the Perl language includes.  This includes the following
   symbols in addition to expanding escape codes: *?, +?, ??, and assertions.

6. <UNIX Wildcard Match> consists of a match that could be used to match 
   filenames in a UNIX shell such as csh.  This includes the operators *, ?, 
   and [].

7. Multiple sections of filter type A and B may be combined into one filter 
   part.  See the following examples for more information.

8. Examples of filtering:
   a. "/~USER*", ""          - Match all urls that begin with /~USER
   b. "!URL!^/~USER!", ""    - Match all urls that begin with /~USER
   c. "|URL|/~USER*|", ""    - Match all urls that begin with /~USER
   d. "!HOST!com$!", ""      - Match all accesses from .com domains.
   d. "|HOST|*com|", ""      - Match all accesses from .com domains.
   e. "|STATUS|[45]??|", ""  - Match all 400 and 500 status codes.
   f. "!HOST!com$!|URL|/~USER*|", "" - Match all .com accesses to /~USER
   g. "!HOST!com$!|URL|/~USER*|", "|STATUS|[45]??|" - Match all .com accesses
      that begin with /~USER that are not errors.


NOTE: Project version numbers:

1. Project is to have a major and minor version number as well as release code
   (alpha, beta, etc) and release version.  For example: 1.0b2.

2. Version numbers without release codes are only for project versions that 
   have been thoroughly checked through public beta releases.

3. Public beta releases will have a release code of "b".  This signifies that 
   it is a beta product with potential flaws.  The beta cycle should be 
   iterated until a stable product is created.  All major features should be 
   implemented in the beta software release.

4. Pre-beta releases will have a release code of "pr".  This signifies a 
   "pre-release", that does not yet have all of the features implemented,
   but it testable and is ready for user input.  The PR phase should be
   interated only until the beta stage has been entered.

5. Versions prior to public beta releases will be designated with a release 
   code of "a".  This signifies an alpha release that may change drastically 
   when next released.  Not all functionality is required for an internal alpha
   release.

6. Major version numbers should only be incremented when significant changes 
   are made that are not backwards compatible with the old version.  Minor 
   version number is incremented upon implementation and debugging of newly 
   implemented minor features that keep backwards compatibility with versions 
   of the same major version number.

7. Example project sequence: 2.0a1, 2.0a2, 2.0a3, 2.0a4, 2.0b1, 2.0b2, 2.0b3a1,
   2.0b3, 2.0b4, 2.0, 2.1a1, 2.1a2, 2.1b1, 2.1b2, 2.1...