

Greetings !!

This HOWTO was written as a small description of some advanced
features of Q3 LogGen.
English is not my native language, so please forgive me any mistakes.


Contents
********

1. Source-Code
2. Calculation of the effectiveness
3. Templates


********************************************************
1. Source-Code
I started this program in late december 1999 using a free compiler for
Windows (lcc-win32). Later I changed my mind, and now I am working
completely using Linux, my favorite developer-OS.
Nevertheless I still generate executables for Windows, but this
happens also with the help of GNU-GCC.
Code is a kind of a mess .... I know ... if you really try to read it
- simply forget it :-) - code is just given away for OS-independant
compilation.




********************************************************
2. Effectiveness
As an additional command-line parameter you can use the "-c <xy>"
string, which defines a mathematical construct to be used for the
calculation of the effectiveness of the players.
Please note, that most of the shells or the DOS-BOX handle "*","(" or
")" as special chars, you have to use esc-sequences, like "\*", "\("
or "\)".
DO NOT USE SPACES OR ADDITIONAL CHARACTERS !!!!
You can use :
    Operators  : +-*/ ()
    consts like: 10.0 0.5 5 2.3
    vars       : F (frags),T (Tkills),t (secs), S (suic.), D (deaths),
	         K (kills)

    WARNING! Bugs !! Use "(" and ")".
    These module is far from being finished, I wrote it on one evening,
    very fast. Its not tested and if you get a warning about a
    "ERROR in calculation" the program did not understand your input.

Examples:
	F-((D/2)+S) - Depends on Frags, Deaths and Suicides
	F/(t/120)   - average frags per 2 mins (useless, FPH sorts the
		      same way !)



********************************************************
3. Templates (very long and "strange")
Q3 LogGen reads templates from the input-directory (by default
"Templates"), parses the HTML-templates and writes them to an
output-directory (by default "Html_log"). During writing the files
back to the file-system <Q3L_xx>-tags will be replaced with the
information.
The whole thing was programed very fast, so its not very easy to
understand, try first rewriting the given HTML-templates.

I hope, this graphics helps you to understand the structure of the
information (no frame-set, like "noframe"-Template) - please use a
fixed-width-font:

index.html -> help.html
           -> ag_allgame.html
	   -> ap_allplayer.html  -> all_player0.html
                                 -> all_player1.html
                                      ....
                                 -> all_playerXX.html
           -> game_000.html -> 00_player0.html
                            -> 00_player1.html
                                 ....
                            -> 00_player2.html
           -> game_001.html -> 01_player0.html
                                 ....
                               01_playerXX.html
              ....
           -> game_YYY.html -> YYY_player0.html
                                 ....
                            -> YYY_playerXX.html


Rules:
1. Tags for Q3_LogGen will be replaced in the target-file.
2. Q3L - Tags must always be uppercase.
3. Q3_LogGen just parses and copies html-files, pictures you have to
   transfer separately !


Name-conventions:
Q3L_SG_  - Single Game
Q3L_SP_  - Single Game, single Player (player-stats within a single game)
Q3L_AG_  - All Games
Q3L_AP_  - All Games, single Player (player-stats over all games)
It makes no sense to access a SP while you are in an AG or AP, since
the current game is not set (Q3LogGen ignores this tags).
But from SP you can access SG (e.g. for mapname, hostname).
And from everwhere you can use AP and AG.


Files:
3 files *must* exist in the Template-directory:
sg_game.html   - Single Game
sp_player.html - Single Game, single Player
ap_player.html - Single Player stats over all games

The files are automatically parsed when finding the following tags:
<Q3L_GAMETABLE>   - sg_game.html will be readed and written for each game
<Q3L_SG_RANKS>	  - sp_player.html for each player who took part in the
		    single game (this tag is located in sg_game.html)
<Q3L_AP_ALLSTATS> - ap_player.html for each player ever logged


Vars:
I have added some special tags for a more detailed template-use, but
this is very time-consuming, so most of the people will simply let the
tables generate by Q3_LogGen.
Using this tags gives you the chance to get some simple numbers in HTML
(you can change the appearance by HTML-tags), or a graphical output
with image-numbers <... PRE=num_ POST=jpg> -> "num_0.jpg"
.. "num_9.jpg" - all the little images have to be in the
"pix"-directory. By default Q3_LogGen automatically adds ".jpg" as extension.

Example : if you want to access the number of fired weapons directly
you can do so by using this tag:
<Q3L_xxy_VW_yyyy [ALL] [GFX [PRE=] [POST=]]>
Q3L  - standard-tag-identifier
xx   - SG, SP, AG, AP
z    - S, T -> suicide, teamkill, if not set normal weapon-use
VW   - Var Weapon
yyyy - one of the following "weapons" :
       SHOTGUN, GAUNTLET, MACHINEGUN, GRENADE, GRENADESPLASH,
       ROCKET, ROCKETSPLASH, PLASMA,  PLASMASPLASH, RAILGUN,
       LIGHTNING, BFG, BFGSPLASH, LAVA, CRUSH, TELEFRAG,
       FALLING, SUICIDE, TRIGGERHURT, SPLASH
ALL  - counts also splashes (just for GRENADE, ROCKET, PLASMA, BFG)


For the number of items the people picked up you can use this tags:
<Q3L_xx_VI_yyyy [ALL] [GFX [PRE=] [POST=]]>
Q3L  - standard
xx   - SG, SP, AG, AP
VI   - Var Items (picked up)
yyyy - one of the following items (picked up):
       BULLETS, SHELLS, ROCKETS, CELLS, SLUGS, GRENADES,
       LIGHT_AMMO, BGF_AMMO, RAILGUN, ROCKETLAUNCHER,
       GRENADELAUNCHER, SHOTGUN, PLASMAGUN, LIGHTNING_GUN,
       BFG2K, HEALTH_SMALL, HEALTH, HEALTH_LARGE, HEALTH_MEGA,
       ARMOR_SHARD, ARMOR_BODY, ARMOR_COMBAT,
       HASTE, REGENERATION, QUAD_DAMAGE, INVISIBILITY,
       HOLDABLE_MEDIKIT, HOLDABLE_TELEPORTER,
       ALL_HEALTH, ALL_ARMOR, ALL_WEAPONS, ALL_ARMOR, ALL_POWERUPS

<Q3L_xx_VG_yyyy [GFX [PRE=] [POST=]]>
Q3L  - standard
xx   - SG, SP, AG, AP
VI   - Vars General
yyyy - one of the general vars:
       FRAGCOUNTER, FRAGMASTERCOUNT, FOOLCOUNT, EASYPREYCOUNT,
       LONGTIMECOUNT, EFFECTIVENESSCOUNT, ROBUSTNESSCOUNT



Tags:
Most of the tags generate more complex tables. Simple outputs are just
generated by VARS (see above). The table must be created in the
HTML-file, Q3L assumes the exitance of <table> and </table> within the
templates.
For tables like weapon and item-stats you can define the number of cols
with <Q3L_.... COLS=xx> (where xx is the number of cols). By default
Q3L will generate 3 cols.
For tables with team-colors (Q3L_SG_CTFSTATS, Q3L_SG_TEAMSTATS,
Q3L_SG_RANKS) the color for the teams can be defined by
<Q3L... REDC=#xxxxxx BLUEC=#yyyyyy> (where colors are in #RRGGBB
format).
For tables with a header you can define the table-head-color by using
<Q3L... HEADC=#RRGGBB>.



Special-Tags (can be used everywhere):
<Q3L_HTML LINK=xx> - adds the HTML-file to the TODO-stack
<Q3L_DATE>         - date of the output
<Q3L_TIME>         - time of the output
<Q3L_FRAGCOUNTER>  - all frags logged till today
<Q3L_CALCULATIONSTRING> - prints the used string for calculations
<Q3L_AP_FRAGMASTERNAME>
<Q3L_AP_EFFECTIVENESSNAME>
<Q3L_AP_EASYPREYNAME>
<Q3L_AP_FOOLNAME>
<Q3L_AP_LONGTIMENAME>
<Q3L_AP_ROBUSTNESSNAME>
<Q3L_AP_ALLSTATS>     - table with all players ever playing, generates
		        automatically some detailed
			player-descriptions (all_playerX.html)

			Additional tag:
			for humans:  HUMANONLY
			for sorting (default: frags):
			SORTDEATHS, SORTNAMES,
			SORTSUICIDES, SORTFRAGS, SORTKILLS, SORTTIME,
			SORTFPH, SORTEFFICENCY, SORTTTL
			for sortcolor (bg): SORTC=#RRGGBB


SG-Tags (sg_game.html):
<Q3L_SG_MAPNAME>      - name of the map
<Q3L_SG_STATS>        - simple table with servername, mapname,
		        gametype..
<Q3L_SG_STATS ALL>    - table with stats for all players in the game
<Q3L_SG_CTFTIMELINE>  - not implemented yet
<Q3L_SG_CTFSTATS>     - CTF-results (table)
<Q3L_SG_TEAMTIMELINE> - not implemented yet
<Q3L_SG_TEAMSTATS>    - Team-results (table)
<Q3L_SG_TIMELINE>     - writes a PNG-file for each game
			Tags: WIDTH, HEIGHT, OFFSETX, OFFSETY
<Q3L_SG_RANKS>        - Ranks for all players (individual) ->
		        generates detailed player-stats (from
			"sp_player.html") + table-generation
			Additional Tags:
			NOCOLORS, suppress the timeline-colors for
						player-names
			REDC, BLUEC, NEUTRALC, HEADC
<Q3L_SG_KILLTABLE>    - detailed table (who was killed by whom ?)
<Q3L_SG_WEAPS>        - all weapons causing someones dead
<Q3L_SG_SUICIDEWEAPONS> - weapons causing suicides
<Q3L_SG_TEAMKILLWEAPONS>- weapons accidently team-members were killed
			  with
<Q3L_SG_ITEMS>        - table with items picked up
<Q3L_SG_FRAGMASTERNAME> - name of the player with most frags
<Q3L_SG_EASYPREYNAME> - name of the player who was killed most
<Q3L_SG_FOOLNAME>     - name of the player with most suicides
<Q3L_SG_EFFECTIVENESS>- name of the most effective player
<Q3L_SG_ROBUSTNESS>   - name of the most effective player


<Q3L_SP_PLAYERNAME>
<Q3L_SP_MAPNAME>
<Q3L_SP_KILLTABLE>    - shows who was killed by which weapon (by the
			current player)


All-Player-Tags (ap_player.html):
<Q3L_AP_PLAYERNAME>   - current player in detailed player-description
<Q3L_AP_WEAPONS>
<Q3L_AP_TEAMKILLWEAPONS>
<Q3L_AP_SUICIDEWEAPONS>
<Q3L_AP_ITEMS>


All-Game-Tags:
<Q3L_AG_STATS>        - small table with all the kills, frags, suicides...
<Q3L_AG_WEAPS>
<Q3L_AG_SUICIDEWEAPONS>
<Q3L_AG_TEAMKILLWEAPONS>
<Q3L_AG_ITEMS>
