initial docs for the map files because I never did quite understand the texture information. (still don't, but once I doc it, it won't matter if I forget it:)

doc/cliptest.map

@@ -0,0 +1,260 @@
+// --
+// -- Created with Quest
+// --
+// Quest Group Name: World
+// Quest Group Flags: 1
+// Quest Group Color: 0
+{
+"classname" "worldspawn"
+"wad" "quake101.wad"
+{
+:8
+-32 -96 8
+-32 32 8
+128 32 8
+128 -96 8
+-32 -96 0
+-32 32 0
+128 32 0
+128 -96 0
+4 ( 0 1 2 3 ) wmet4_4 0 0 0 1 1
+4 ( 4 0 3 7 ) wmet4_4 0 0 0 1 1
+4 ( 7 3 2 6 ) wmet4_4 0 0 0 1 1
+4 ( 6 2 1 5 ) wmet4_4 0 0 0 1 1
+4 ( 1 0 4 5 ) wmet4_4 0 0 0 1 1
+4 ( 4 7 6 5 ) wmet4_4 0 0 0 1 1
+}
+{
+:8
+-32 -104 104
+-32 -96 104
+128 -96 104
+128 -104 104
+-32 -104 8
+-32 -96 8
+128 -96 8
+128 -104 8
+4 ( 0 1 2 3 ) wmet4_4 0 0 0 1 1
+4 ( 4 0 3 7 ) wmet4_4 0 0 0 1 1
+4 ( 7 3 2 6 ) wmet4_4 0 0 0 1 1
+4 ( 6 2 1 5 ) wmet4_4 0 0 0 1 1
+4 ( 1 0 4 5 ) wmet4_4 0 0 0 1 1
+4 ( 4 7 6 5 ) wmet4_4 0 0 0 1 1
+}
+{
+:8
+136 -96 104
+128 -96 104
+128 96 104
+136 96 104
+136 -96 8
+128 -96 8
+128 96 8
+136 96 8
+4 ( 0 1 2 3 ) wmet4_4 0 0 0 1 1
+4 ( 4 0 3 7 ) wmet4_4 0 0 0 1 1
+4 ( 7 3 2 6 ) wmet4_4 0 0 0 1 1
+4 ( 6 2 1 5 ) wmet4_4 0 0 0 1 1
+4 ( 1 0 4 5 ) wmet4_4 0 0 0 1 1
+4 ( 4 7 6 5 ) wmet4_4 0 0 0 1 1
+}
+{
+:8
+-32 96 104
+-32 104 104
+128 104 104
+128 96 104
+-32 96 8
+-32 104 8
+128 104 8
+128 96 8
+4 ( 0 1 2 3 ) wmet4_4 0 0 0 1 1
+4 ( 4 0 3 7 ) wmet4_4 0 0 0 1 1
+4 ( 7 3 2 6 ) wmet4_4 0 0 0 1 1
+4 ( 6 2 1 5 ) wmet4_4 0 0 0 1 1
+4 ( 1 0 4 5 ) wmet4_4 0 0 0 1 1
+4 ( 4 7 6 5 ) wmet4_4 0 0 0 1 1
+}
+{
+:8
+-32 96 -24
+-32 32 -24
+-32 32 8
+-32 96 8
+-40 32 8
+-40 32 -24
+-40 96 -24
+-40 96 8
+4 ( 0 1 2 3 ) wmet4_4 0 0 0 1 1
+4 ( 4 5 6 7 ) wmet4_4 0 0 0 1 1
+4 ( 2 1 5 4 ) wmet4_4 0 0 0 1 1
+4 ( 6 5 1 0 ) wmet4_4 0 0 0 1 1
+4 ( 4 7 3 2 ) wmet4_4 0 0 0 1 1
+4 ( 7 6 0 3 ) wmet4_4 0 0 0 1 1
+}
+{
+:8
+-40 -96 104
+-40 96 104
+-32 96 104
+-32 -96 104
+-32 -96 8
+-32 96 8
+-40 96 8
+-40 -96 8
+4 ( 0 1 2 3 ) wmet4_4 0 0 0 1 1
+4 ( 4 3 2 5 ) wmet4_4 0 0 0 1 1
+4 ( 5 2 1 6 ) wmet4_4 0 0 0 1 1
+4 ( 6 1 0 7 ) wmet4_4 0 0 0 1 1
+4 ( 7 0 3 4 ) wmet4_4 0 0 0 1 1
+4 ( 4 5 6 7 ) wmet4_4 0 0 0 1 1
+}
+{
+:8
+-32 -96 112
+-32 96 112
+128 96 112
+128 -96 112
+-32 -96 104
+-32 96 104
+128 96 104
+128 -96 104
+4 ( 0 1 2 3 ) wmet4_4 0 0 0 1 1
+4 ( 4 0 3 7 ) wmet4_4 0 0 0 1 1
+4 ( 7 3 2 6 ) wmet4_4 0 0 0 1 1
+4 ( 6 2 1 5 ) wmet4_4 0 0 0 1 1
+4 ( 1 0 4 5 ) wmet4_4 0 0 0 1 1
+4 ( 4 7 6 5 ) wmet4_4 0 0 0 1 1
+}
+{
+:8
+136 96 -24
+136 32 -24
+136 32 8
+136 96 8
+128 32 8
+128 32 -24
+128 96 -24
+128 96 8
+4 ( 0 1 2 3 ) wmet4_4 0 0 0 1 1
+4 ( 4 5 6 7 ) wmet4_4 0 0 0 1 1
+4 ( 2 1 5 4 ) wmet4_4 0 0 0 1 1
+4 ( 6 5 1 0 ) wmet4_4 0 0 0 1 1
+4 ( 4 7 3 2 ) wmet4_4 0 0 0 1 1
+4 ( 7 6 0 3 ) wmet4_4 0 0 0 1 1
+}
+{
+:8
+-32 32 -24
+-32 96 -24
+128 96 -24
+128 32 -24
+-32 32 -32
+-32 96 -32
+128 96 -32
+128 32 -32
+4 ( 0 1 2 3 ) wmet4_4 0 0 0 1 1
+4 ( 4 0 3 7 ) wmet4_4 0 0 0 1 1
+4 ( 7 3 2 6 ) wmet4_4 0 0 0 1 1
+4 ( 6 2 1 5 ) wmet4_4 0 0 0 1 1
+4 ( 1 0 4 5 ) wmet4_4 0 0 0 1 1
+4 ( 4 7 6 5 ) wmet4_4 0 0 0 1 1
+}
+{
+:8
+-32 96 8
+-32 104 8
+128 104 8
+128 96 8
+-32 96 0
+-32 104 0
+128 104 0
+128 96 0
+4 ( 0 1 2 3 ) wmet4_4 0 0 0 1 1
+4 ( 4 0 3 7 ) wmet4_4 0 0 0 1 1
+4 ( 7 3 2 6 ) wmet4_4 0 0 0 1 1
+4 ( 6 2 1 5 ) wmet4_4 0 0 0 1 1
+4 ( 1 0 4 5 ) wmet4_4 0 0 0 1 1
+4 ( 4 7 6 5 ) wmet4_4 0 0 0 1 1
+}
+{
+:8
+-32 96 0
+-32 104 0
+128 104 0
+128 96 0
+-32 96 -24
+-32 104 -24
+128 104 -24
+128 96 -24
+4 ( 0 1 2 3 ) wmet4_4 0 0 0 1 1
+4 ( 4 0 3 7 ) wmet4_4 0 0 0 1 1
+4 ( 7 3 2 6 ) wmet4_4 0 0 0 1 1
+4 ( 6 2 1 5 ) wmet4_4 0 0 0 1 1
+4 ( 1 0 4 5 ) wmet4_4 0 0 0 1 1
+4 ( 4 7 6 5 ) wmet4_4 0 0 0 1 1
+}
+{
+:8
+-32 24 0
+-32 32 0
+128 32 0
+128 24 0
+-32 24 -24
+-32 32 -24
+128 32 -24
+128 24 -24
+4 ( 0 1 2 3 ) wmet4_4 0 0 0 1 1
+4 ( 4 0 3 7 ) wmet4_4 0 0 0 1 1
+4 ( 7 3 2 6 ) wmet4_4 0 0 0 1 1
+4 ( 6 2 1 5 ) wmet4_4 0 0 0 1 1
+4 ( 1 0 4 5 ) wmet4_4 0 0 0 1 1
+4 ( 4 7 6 5 ) wmet4_4 0 0 0 1 1
+}
+{
+:8
+64 -96 32
+64 -64 32
+128 -64 32
+128 -96 32
+64 -96 24
+64 -64 24
+128 -64 24
+128 -96 24
+4 ( 0 1 2 3 ) wmet4_4 0 0 0 1 1
+4 ( 4 0 3 7 ) wmet4_4 0 0 0 1 1
+4 ( 7 3 2 6 ) wmet4_4 0 0 0 1 1
+4 ( 6 2 1 5 ) wmet4_4 0 0 0 1 1
+4 ( 1 0 4 5 ) wmet4_4 0 0 0 1 1
+4 ( 4 7 6 5 ) wmet4_4 0 0 0 1 1
+}
+{
+:8
+64 -48 32
+64 -16 32
+128 -16 32
+128 -48 32
+64 -48 24
+64 -16 24
+128 -16 24
+128 -48 24
+4 ( 0 1 2 3 ) wmet4_4 0 0 0 1 1
+4 ( 4 0 3 7 ) wmet4_4 0 0 0 1 1
+4 ( 7 3 2 6 ) wmet4_4 0 0 0 1 1
+4 ( 6 2 1 5 ) wmet4_4 0 0 0 1 1
+4 ( 1 0 4 5 ) wmet4_4 0 0 0 1 1
+4 ( 4 7 6 5 ) wmet4_4 0 0 0 1 1
+}
+}
+{
+"classname" "info_player_start"
+"origin" "96 -80 64"
+}
+{
+"classname" "info_player_deathmatch"
+"origin" "96 -80 64"
+}
+{
+"classname" "light_globe"
+"origin" "48 0 96"
+}

doc/mapformat.txt

@@ -0,0 +1,64 @@
+//unfortunatly, have to wrap the docs in a C comment for doxygen
+/**
+\page mapformat Map (.map) File Format
+
+"//" marks a comment which extends to the end of the current line
+
+Note that () and {} characters require white space around them.
+
+A map consists of a series of entities delineated by {}
+
+An entity consists of a series of either epairs or brushes, one per "line".
+
+An epair is a pair of quoted (via "quotes") strings. The first string of the
+pair is the key, the second string the value. epairs are used to populate the
+dictionary of the entity.
+
+A brush is a simple, convex polytope delinieated by {}. The format of a brush
+is as follows:
+\verbatim
+{
+[optional vertex list]
+<plane spec> <texture name> <texcoord spec> [optional flags]
+<plane spec> <texture name> <texcoord spec> [optional flags]
+<plane spec> <texture name> <texcoord spec> [optional flags]
+...
+}
+\endverbatim
+That is, an optional vertex list followed by a number of surface specs, one
+per line.
+
+The optional vertex list, found in map files produced by Quest3d, is denoted
+by a colon followed by a number indicating the number of vertices in the list.
+Following this, one per line, come the 3d coordinates of the vertices, one
+vertex per line. The vertex coordinates are listed in X Y Z order.
+
+There are two formats for the plane spec, selected via the presence (vertex
+mode) or absence (plane point mode) of the vertex list.
+
+In vertex mode, the plane spec directly describes the shape of the surface
+polygon. It is simply a number indicating the number of vertices, followed by a
+set of 0 based indices, enclosed in (). The indices indicate which of the
+vertices from the vertex list to use. When compiling the map, only the first 3
+vertices are significant: they are used as the 3 points for calculating the
+plane.
+
+In point plane mode, the plane spec consists of three point vectors, each
+enclosed in ().
+
+The three points (from either mode) are then used to calculate the plane
+normal and offset: n = (p0 - p1) x (p2 - p1), d = p1 . n
+
+The texture name is just a simple string (no spaces) that specifies the name
+of the texture within the wadfile.
+
+The texcoord spec is black magic.
+
+The optional flags indicate various options for the surface. So far, the only
+flag supported is "detail", indicating that the brush is a detail brush and not
+to be used for visibility calculations. If any surface has the detail flag set,
+the whole brush is affected.
+
+Example map file (vertex mode):
+\verbinclude cliptest.map
+*/

doc/quakeforge.dox.in

@@ -353,6 +353,7 @@ INPUT                 += @top_srcdir@/qw
 INPUT                 += @top_srcdir@/tools
 INPUT                 += @top_srcdir@/doc/quakeforge.txt
 INPUT                 += @top_srcdir@/doc/faq.txt
+INPUT                 += @top_srcdir@/doc/mapformat.txt
 
 # If the value of the INPUT tag contains directories, you can use the 
 # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp