Added document for program overview and reflex map format

docs/doc-overview.txt

@@ -0,0 +1,118 @@
+reflex2q3
+A tool to convert Reflex Arena maps to idTech .maps for use in map editors.
+Forked from chronokun's ReflexToQ3.
+
+Features, and Responsibilities of the Program: For Mappers
+    The converter is equipped with the following features:
+        - Converts map geometry from Reflex
+        - Converts entities such as, but not limited to
+            - player spawn points
+            - item pickups
+            - teleporters and respective targets
+            - race checkpoints
+
+    During the conversion process, face related data (texture & color) are 
+    preserved. This is both because of the differences between engines and the
+    numerous games built in idTech engines. Meaning the map converter does not
+    attempt to retexture the map with generic idTech engine equivalents or 
+    per-game equivalents. It is the individual mappers' responsibility to 
+    appropriately adapt the map for the target game. Some of the following 
+    tasks for mappers remain:
+
+        - Redesigning specific map geometry so meta/gameplay tricks work.
+        - Sealing leaks allowed by Reflex Arena, but illegal in idTech.
+        - Texturing the map.
+            * Extends to applying lava and slime effects to brushes.
+        - Providing light to the map.
+            * The converter handles Point Lights; however some entities and 
+            textures in Reflex emit light while target game equivalents
+            do not.
+
+Program Design: For Programmers
+    The program can be summarized as two distinct phases:
+        1. Converting worldspawn (map geometry).
+        2. Converting entities.
+
+    These are split into two distinct phases because of the difference between
+    engines. While it is acceptable for worldspawn brushes and game entites to
+    be in which ever order in Reflex, worldspawn in IdTech engines must not have
+    entities with in it. Entities must be handled separately after worldspawn.
+
+    Both phases will write to the output file, the format determined by a 
+    function pointer to the outputting function- the function to call being a
+    "variable" determined in main. Both phases convert and write to file single 
+    instance of a game object (brush or entity) at a time.
+
+    Converting Worldspawn
+        This is the phase that passes through the input file, parses Reflex's 
+        .map format, and converts brushes for the idTech format.
+
+        Functions pertaining to this phase are written to be easily changed to
+        deal with either from-memory or from-file operations. For example, 
+        functions for parsing brushes for the first phase will deal with input 
+        and output file streams, but later in the next phase they are used to 
+        deal with stringstream. If for any reason, the entire contents of the 
+        input file should be stored in memory, no major rewrites are needed.
+
+        The parsing functions for each game object (brush, faces, vertices) 
+        expect and operate on the contents underneath the respective keywords.
+
+        As the two engines are very different, entities must be converted and
+        written to file at a different phase. The converter will store the 
+        strings of an entity to a vector of vector of strings (STL). A vector
+        was chosen because the entity converter needs to prescan the container
+        for teleporters and targets. The vector permitting multiple passes FIFO
+        and pass by reference; where instead STL queue is either destructive or
+        requires copying the queue. 
+
+    Converting Entities
+        This is the phase that operates on the container of entity strings, 
+        converts, and writes them to file. Entity names for pick up items will
+        vary per target game; to easily adapt to multiple games, a plain text 
+        file is used, containing Reflex map entity id's corresponding to the 
+        target game entity names.
+
+        In order to determine the teleporters and the corresponding target 
+        locations, the entity container is prescanned.
+
+Major Code Changes in Forking
+    - Can be compiled for g++ and by extension mingw, and Linux systems.
+        The original project was for Microsoft Visual Studio; however even
+        manually compiling the source resulted in errors from syntax acceptable
+        by Visual Studio, but rejected by g++.
+
+    - Removal of ckmath, original author's custom C++ library for linear 
+    algebra
+        This was because the attempt to compile ckmath results in several 
+        warnings and errors. Addressing the compilation errors would have 
+        warranted its own tests to see if the output is unchanged. 
+        This was scrapped for Eigen.
+
+    - Addition of Reflex version 8 map parsing
+        The original code had a reported Issue where it did not parse V8, the
+        current format of map files for the game.
+
+    - Addition of output to Net Radiant's brush definition
+        The original code's output was the legacy brush definition used by GTK
+        Radiant or older map editors.
+
+    - Addition of converting map entities.
+
+    - Addition of translating texture definitions.
+        Previously these were kept as placeholder values.
+
+    - Severe bug fixes
+        The old converter crashed on converting Pocket Infinity, and had 
+        distorted geometry for certain maps e.g Sky Temples. The main cause
+        for such issues have been addressed and will not occur on maps 
+        featuring similar cases.
+
+Minor Code Changes
+    - Improved memory usage
+
+    - Added new command line arguments and robust handling of.
+        -h, --help, displays help
+        -gtk        switch to output to GTK's map format
+        -e <FILE>   entity conversion
+
+    - Added test cases to verify correctness of operations pre-commit.