title: Map reading

Reading of maps in the innumberable variants of the .map format is achieved by
the ReadEntityList procedure in QkMap.pas.  Why EntityList? because that's what
a map file is, first the worldspawn entity, then the others.  This procedure
is driven by the sub-procedure ReadSymbol, which basically pulls a 'token'
off the input string (SourceFile), and stores various kinds information
about it for later access by the real parsing routines.  A slight complexity
in the formulation of the procedure is that it is also used for reading
entity lists in BSP's, so there is a certain amount of code involved only
in that.

A slightly peculiar feature of ReadSymbol is that it takes as argument an
member of the local type TSymbols, which is what the type of the previously
token should have been.  This provides a certain amount of automatic syntax
error detection.  ReadSymbol deposits significant info about the token it
has just read in a number of places:
<UL>
<LI>S: a String variable containing the string form of the token
<LI>SymbolType: a TSymbol value indicating the type of the just-read
token.
<LI>NumericValue: a Double variable containing the number designated
by the token, if it has one.
</UL>
So what the parser does is basically loop around reading tokens, starting
with ReadSymbol(sEOF) (a clever usage of this type, given that it can't have
actually been encountered until a read attempt has been made), storing things
building the map structure as it goes along.

Tning are made a bit muddy by the fact that there is a great range of variation
in the map format, which I think falls into two major types:
<UL>
<LI>Variations caused by the capacity of the engine.  E.g. the Q1 engine can't
make sense of the Content, Surface, Value fields
<LI>Variations caused by the propoerties of the standard compile tools, such
as that the new HL tools understand the Valve 220 map format but not
Brush Primtives, while the reverse is true for the GtkRadiant tools for Q3A
and RtCW.
</UL>
The overall strategy is to try to use the first kind of information, but not
the second, to determine identity of the game, to the extent that this
can be done.

This is attempted to be achieved by returning as Result a gamecode, the Result
value is initially set to mjQuake (original Quake, 'mj' stands for French
modejeu='gamemode', maybe someday it will be replaced by 'gm'), and reset
as things are encountered, and finally fixed up at the end.  The latter step
is somewhat messy; the idea is that if something inconsistent with the present
game-mode is encountered, it switches to the presumedly most popular game
consistent with what is seen, but this is getting rather messy and the whole
thing needs to be rethought.

The innards of the map-reading procedure bristle with special-purpose code
blocks for reading and interpreting the various kinds of texture positioning
info, etc.  Some of this involves significant 3d math, there are commentaries
and references to sources in the code, see also <ref>src/math</ref> and
<ref>src/topics/face</ref>in the infobase.

