How Variables Really Work...
If you really looked at the example, you may have noticed that most of the variables in the example are defined more than one time... what's going on here?
Variables are defined in a "scope" that is the enclosing section of the configuration file. Thus, variables defined in the Global section are active all throughout the global section. Variables defined in the "Fancy:Sabres" section (to be described next) are active in that section. Additionally, variables flow through the following sections until the end of the file, or when they are undefined. This means, for example, that the $BGColor variable is set to "#FFFFFF" thoughtout the entire configuration file. It also means that the $SectionFilter variable is set to ["*sabre*",""] only in the first [[Fancy]] section (it is redefined in the second [[Fancy]] section).
The defined value of the variable is available to the theme that corresponds to that section of the configuration file. Thus, the first instance of the Fancy theme receives the values of $SectionFilter, $PageFilter, $PageName, $BGColor, $OutputPrefix, $PathPrefix, $DailyLink, and $MonthlyLink.
Theme Sections
Now that we know how to get MagicStats set up, we need to tell it what kind of statistics we want generated. The rest of the example configuration file is dedicated to creating two instances of the "Fancy" theme. Theme instantiations are denoted by double square brackets around their name: [[<themename>]]. The themename portion corresponds to a directory under your Resources/Themes directory.
As was mentioned before, MagicStats does not assign any meaning to the variables defined in the configuration file. It is up to the Themes to define which variables they use. Thus, if you look at the theme's configuration file (<themename>/<themename>.cfg) it will tell you exactly what variables it takes as input, give descriptions of all of its variables, and give default values for them. For example, take a look at the Dejavu configuration file.
MagicStats Command Line Options:
MagicStats several command line options, and although none are routinely used, they can be extremely valuable when debugging an installation, or just poking around. Lets review how a typical installation works:
MagicStats...
- ... is started with no command line options by the cron daemon.
- ... loads and parses the user's ~/.MagicStats/MagicStats.cfg file.
- ... loads themes and plugins found in the resources directories specified by the main config file.
- ... processes new hits from the specified input log files.
Given this process, MagicStats recognizes the following command line options:
- -H - Print out version and help information.
- -C <config file> - Override the default ~/.MagicStats/MagicStats.cfg to be used as the main configuration file.
- -V - Run in verbose mode, printing out information about pages generated and hits processed.
- -P - Print out all of the plugins that are found in step #3, then exit.
- -T - Print out all of the themes that are found in step #3, then exit.
- -N <number> - Only processes the first "number" hits from the log files.
- -G - Print out debug information. This can be useful when submitting a bug report.
- -lint <themename> - Run "lint" on a theme. This is only used by theme developers.
Conclusion:
This document explains the basics of how MagicStats works. Hopefully you understand enough about MagicStats to set up and maintain a fairly customized configuration that isn't straightforward variant of an "out of the box" configuration. I would really, really, really like feedback on what you think is terrible about this document, what you think is good, what needs to be explained more and expanded upon, and if I'm a total fool, please tell me! :)
-Chris