/***************************************************/
/*                    M K L O G                    */
/*                                                 */
/*     Quake III Log File Statistics Generator     */
/*                                                 */
/*         (c) Martin Kilcoyne 1999 / 2000         */
/***************************************************/


Author	: Martin "Killer" Kilcoyne
Version	: 1.2 - 3rd January 2000
E-Mail	: killer@planetquake.com
Website	: http://www.planetquake.com/killer


After playing Quake III for a while and discovering the log file which it
updates for every game you play I decided it might be nice to see how well you
fare against your opponents statistically. Not only that but I wanted some
programming to do and this seemed like as good a project as any :-) Anyway,
MKLOG is the result.

Please read the INSTALLATION and RUNNING instructions carefully. The program is
easy to use but please read them before mailing me and asking me why it isn't
working :-)

It is very much a work in progress and I intend to keep improving and updating
it with new features. I'm sure there are some bugs in it and I'll endeavour to
fix those with further releases of the program. If you find any show stopping
bugs, don't hesitate to mail me and let me know but please make sure you check
the "KNOWN LIMITATIONS" section at the bottom of this document and also the 
Frequently Asked Questions file ("faq.txt") before you do.

Check my site for the latest version of MKLOG and details about planned
features for future version. It is updated on a regular basis and is worth a
visit I reckon :-)

If you have any suggestions for additional features to include in new versions
of MKLOG by all means mail me (mail address at top of document).


/************/
/* FEATURES */
/************/
- Output to template dictated HTML files (individual templates for index,
  players and map pages for maximum customisation).
- Input from Quake III generated log file.
- Statistics for total FRAGS, SUICIDES, GAMES, PLAYERS and MAPS contained in
  the log file.
- Individual statistics for each player.
   - FRAG, SUICIDE, GAME and TIME totals for each player.
   - Frag breakdown, weapon by weapon, for each player.
   - Suicide breakdown, weapon by weapon, for each player.
   - Pickup breakdown detailing WEAPONS, AMMO, HEALTH, ARMOUR and POWERUPS.
- Statistics for total FRAGS, SUICIDES and GAMES for each map played.
- Statistics for MEAN FRAGS PER MINUTE for each map played.
- Statistics for MEAN SUICIDES PER MINUTE for each map played.
- Fast execution even on large log files.

See "changes.txt" for details of new features in this version.


/****************/
/* INSTALLATION */
/****************/
You can install MKLOG to a directory of your choice as you can specify the 
path to the log file using command line arguments. For simplicity's sake I
recommend installing the program to:

C:\mklog

For your information the following files will be created upon installation:

C:\mklog\mklog.exe			- The actual executable program.
C:\mklog\mklog.txt			- This text file.
C:\mklog\changes.txt			- Changes in this version.
c:\mklog\faq.txt			- Frequently asked questions.
C:\mklog\templates\index_template.html	- Template for the index file.
C:\mklog\templates\player_template.html - Template for the player files.
C:\mklog\templates\map_template.html	- Template for the map files.


/*****************/
/* RUNNING MKLOG */
/*****************/
MKLOG is a simple DOS executable so running it is easy. Start up a DOS prompt 
by going to "Start->Programs->MS-DOS Prompt". Now change to the directory in 
which MKLOG was installed. You can run the program with the default options by 
simply typing "mklog". Default options are detailed below.

There are vaious command line options:

mklog -l <PATH_TO_LOG_FILE>	- This allows you to specify the exact path to 
				  the log file on which you wish to generate 
				  statistics. The path must include the actual 
				  name of the log file e.g
 				  "C:\quake3\baseq3\games.log". The path can 
				  contain spaces as long as it is enclosed in 
				  double quotes.
				  * DEFAULT: "games.log"

mklog -itemp <PATH_TO_INDEX_TEMPLATE>
				- This allows you to specify the path to an 
				  alternate index file template. The path must 
				  include the actual name of the template file 
				  e.g. "templates\my_index_template.html". The 
				  path can contain spaces as long as it is
				  enclosed in double quotes.
				  * DEFAULT: "templates\index_template.html"

mklog -ptemp <PATH_TO_PLAYER_TEMPLATE>
				- This allows you to specify the path to an 
				  alternate player file template. The path must
				  include the actual name of the template file 
				  e.g. "templates\my_player_template.html". The
				  path can contain spaces as long as it is
				  enclosed in double quotes.
				  * DEFAULT: "templates\player_template.html"

mklog -mtemp <PATH_TO_MAP_TEMPLATE>
				- This allows you to specify the path to an 
				  alternate map file template. The path must 
				  include the actual name of the template file 
				  e.g. "templates\my_map_template.html". The 
				  path can contain spaces as long as it is
				  enclosed in double quotes.
				  * DEFAULT: "templates\map_template.html"

mklog -fmin <MINIMUM_FRAGS_FOR_PLAYER_LINK>
				- This option allows you to specify the minimum
				  number of frags a player must have for him to
				  be linked when you use a <!--PLAYER_LINKS-->
				  or a <!--PLAYER_HUMAN_LINKS--> identifier.
				  The value must me a positive integer value.
				  e.g. mklog -fmin 5 will only produce links to
				  players with 5 or more frags. Note ALL the
				  players statistics files are still generated.
				  * DEFAULT: 0 (i.e. print all player links)

I recommend you use a batch file to run MKLOG with your preferred options, it
saves a lot of typing on the command line where it is easy to make mistakes. To
create a batch file you can use Notepad to write the command line you want, for
example something like:

mklog -l c:\quake3\baseq3\games.log -ptemp my_cool_template.html -fmin 10

Then save the file as a .BAT file (rename it if necessary, Notepad doesn't like
saving files other than .TXT). You can then run MKLOG by just typing the name
of the bat file in a DOS window in the MKLOG directory.

All the output files will be generated in the same directory as the executable.
So once the program has run all you need to do is to fire up a web browser and
open "mklog_index.html".


/********************/
/* TEMPLATE DETAILS */
/********************/
The use of HTML templates in MKLOG enables you to customise the output so it 
looks how you want it to look. If you don't want to customise the output or 
can't be bothered then there are 3 default templates included which show you 
all the stats that are available.

The use of custom templates is simple. All you need to do is to create a web
page which looks just how you want and wherever you want a certain statistic 
you just need to insert one of the special identifiers which are listed below.
If you are still not sure how to go about creating a custom template then just 
have a look at the default ones and I'm sure you'll soon get the hang of it.

Here is a list of the special identifiers you can use in your HTML templates:

Links
=====
<!--PLAYER_LINKS-->			- "<br>" separated list of
					  alphabetically sorted links to each
					  individual player stats file.
<!--PLAYER_HUMAN_LINKS-->		- As above but any bots are not 
					  included in the links.
<!--MAP_LINKS-->			- "<br>" separated list of
					  alphabetically sorted links to each
					  individual map stats file.

Overall Log File Totals
=======================
<!--TOTAL_FRAGS-->			- Total frags in log file.
<!--TOTAL_SUICIDES-->			- Total suicides in log file.
<!--TOTAL_GAMES-->			- Total games in log file.
<!--TOTAL_PLAYERS-->			- Total different players in log file.
<!--TOTAL_MAPS-->			- Total different maps in log file.

Player Statistics
=================
<!--PLAYER_NAME-->			- Players name.
<!--PLAYER_TYPE-->			- Players type: "Bot" or "Human".
<!--PLAYER_TOTAL_FRAGS-->		- Total frags.
<!--PLAYER_TOTAL_SUICIDES-->		- Total suicides.
<!--PLAYER_TOTAL_GAMES-->		- Total games played.
<!--PLAYER_TOTAL_TIME-->		- Total time played in the format:
					  HOURS:MINUTES:SECONDS
					  e.g. 4:09:35

<!--PLAYER_FRAGS_PER_MINUTE-->		- Mean frags per minute to 4 d.p.
<!--PLAYER_SUICIDES_PER_MINUTE-->	- Mean suicides per minute to 4 d.p.
<!--PLAYER_FRAGS_PER_GAME-->		- Mean frags per game to 4 d.p.
<!--PLAYER_SUICIDES_PER_GAME-->		- Mean suicides per game to 4 d.p.

<!--PLAYER_GAUNTLET_FRAGS-->		- Number of Gauntlet frags.
<!--PLAYER_MACHINEGUN_FRAGS-->		- Number of Machinegun frags.
<!--PLAYER_SHOTGUN_FRAGS-->		- Number of Shotgun frags.
<!--PLAYER_GRENADE_FRAGS-->		- Number of direct Grenade frags.
<!--PLAYER_GRENADE_SPLASH_FRAGS-->	- Number of Grenade splash damage frags.
<!--PLAYER_ROCKET_FRAGS-->		- Number of direct Rocket frags.
<!--PLAYER_ROCKET_SPLASH_FRAGS-->	- Number of Rocket splash damage frags.
<!--PLAYER_LIGHTNING_FRAGS-->		- Number of Lightning Gun frags.
<!--PLAYER_RAILGUN_FRAGS-->		- Number of Railgun frags.
<!--PLAYER_PLASMA_FRAGS-->		- Number of Plasma Gun frags.
<!--PLAYER_PLASMA_SPLASH_FRAGS-->	- Number of Plasma splash damage frags.
<!--PLAYER_BFG_FRAGS-->			- Number of direct BFG frags.
<!--PLAYER_BFG_SPLASH_FRAGS-->		- Number of BFG splash damage frags.
<!--PLAYER_TELEFRAG_FRAGS-->		- Number of telefrags.

<!--PLAYER_MACHINEGUN_SUICIDES-->	- Number of Machinegun suicides.
<!--PLAYER_GRENADE_SUICIDES-->		- Number of direct Grenade suicides.
<!--PLAYER_GRENADE_SPLASH_SUICIDES-->	- Number of Grenade splash suicides.
<!--PLAYER_ROCKET_SUICIDES-->		- Number of direct Rocket suicides.
<!--PLAYER_ROCKET_SPLASH_SUICIDES-->	- Number of Rocket splash suicides.
<!--PLAYER_PLASMA_SUICIDES-->		- Number of direct plasma suicides.
<!--PLAYER_PLASMA_SPLASH_SUICIDES-->	- Number of Plasma splash suicides.
<!--PLAYER_BFG_SUICIDES-->		- Number of direct BFG suicides.
<!--PLAYER_BFG_SPLASH_SUICIDES-->	- Number of BFG splash suicides.
<!--PLAYER_DROWN_SUICIDES-->		- Number of drowning suicides.
<!--PLAYER_SLIME_SUICIDES-->		- Number of slime suicides.
<!--PLAYER_LAVA_SUICIDES-->		- Number of lava suicides.
<!--PLAYER_FALL_SUICIDES-->		- Number of craterings.
<!--PLAYER_TRIGGER_HURT_SUICIDES-->	- Number of fall (e.g. Q3DM17) suicides.
<!--PLAYER_CRUSH_SUICIDES-->		- Number of crushing suicides.
<!--PLAYER_CONSOLE_SUICIDES-->		- Number of "\cmd kill" suicides.

<!--PLAYER_SHOTGUN-->			- Shotguns picked up.
<!--PLAYER_GRENADE_LAUNCHER-->		- Grenade Launchers picked up.
<!--PLAYER_ROCKET_LAUNCHER-->		- Rocket Launchers picked up.
<!--PLAYER_LIGHTNING_GUN-->		- Lightning Guns picked up.
<!--PLAYER_RAILGUN-->			- Railugns picked up.
<!--PLAYER_PLASMA_GUN-->		- Plasma Guns picked up.
<!--PLAYER_BFG-->			- BFGs picked up.

<!--PLAYER_MACHINEGUN_AMMO-->		- Bullets picked up.
<!--PLAYER_SHOTGUN_AMMO-->		- Shells picked up.
<!--PLAYER_GRENADE_AMMO-->		- Grenades picked up.
<!--PLAYER_ROCKET_AMMO-->		- Rockets picked up.
<!--PLAYER_LIGHTNING_AMMO-->		- Lightning picked up.
<!--PLAYER_RAILGUN_AMMO-->		- Slugs picked up.
<!--PLAYER_PLASMA_AMMO-->		- Cells picked up.
<!--PLAYER_BFG_AMMO-->			- BFG ammo picked up.

<!--PLAYER_QUAD_DAMAGE-->		- Quads picked up.
<!--PLAYER_TELEPORTER-->		- Teleporters picked up.
<!--PLAYER_REGENERATION-->		- Regenerations picked up.
<!--PLAYER_BATTLE_SUIT-->		- Battle Suits picked up.
<!--PLAYER_MEDKIT-->			- Medkits picked up.
<!--PLAYER_INVISIBILITY-->		- Invisibilities picked up.
<!--PLAYER_FLIGHT-->			- Flights picked up.

<!--PLAYER_HEALTH_5-->			- Small healths picked up.
<!--PLAYER_HEALTH_25-->			- Medium healths picked up.
<!--PLAYER_HEALTH_50-->			- Large healths picked up.
<!--PLAYER_HEALTH_100-->		- Megahealths picked up.

<!--PLAYER_RED_ARMOUR-->		- Body armours picked up.
<!--PLAYER_YELLOW_ARMOUR-->		- Combat armours picked up.
<!--PLAYER_ARMOUR_SHARD-->		- Armour shards picked up.

Map Statistics
==============
<!--MAP_NAME-->				- Map name.
<!--MAP_TOTAL_FRAGS-->			- Total frags in map.
<!--MAP_TOTAL_SUICIDES-->		- Total suicides in map.
<!--MAP_TOTAL_GAMES-->			- Total games on map.
<!--MAP_TOTAL_TIME-->			- Total time played on map in the 
					  format:
					  HOURS:MINUTES:SECONDS
					  e.g. 24:12:02

<!--MAP_FRAGS_PER_MINUTE-->		- Mean frags per minute to 4 d.p.
<!--MAP_SUICIDES_PER_MINUTE-->		- Mean suicides per minute to 4 d.p.
<!--MAP_FRAGS_PER_GAME-->		- Mean frags per game to 4 d.p.
<!--MAP_SUICIDES_PER_GAME-->		- Mean suicides per game to 4 d.p.


/*********************/
/* KNOWN LIMITATIONS */
/*********************/
- Log file name and output file name must be less than 100 characters long.
- Maximum number of players supported in one log file is 1000.
- Maximum number of maps supported in one log file is 100.
- Maximum map file name length (e.g. q3dm11) is 50 characters.
- Maximum player name excluding special colour characters is 25 characters.
- Each player with a unique name will have his own stats. However if an
  existing player changes his name to one that ALREADY exists then the stats
  will continue to be recorded under his original name. This prevents someone
  changing their name to yours and messing up your stats. If an existing player
  changes his name to one that DOES NOT exist then his name will be changed and
  stats will be carried over from his old name.


/**************/
/* LEGAL SHIT */
/**************/
MKLOG is provided as is and the author holds no responsibility for any
consequences of running MKLOG. Use at your own risk.