Here are some annotations from the various PM files. I gathered them here,
to avoid cluttering the source codes:

###############################################################################
#
# Bunch.pm:
#
# * Brushes can be "deleted" by optimizing or one of the removeXXX, these 
#   brushes will remain in mem, but are not written out. No undelete exists 
#   yet, who really cares?
# * Textures are only numbers. Use Texture.pm for name/number mapping. DromEd
#   seems to ignore the names in the VBR and just uses the numbers, which will
#   greatly mess the textures up if you import a VBR from another level. 
#   A texture can be an hash reference, too. The hash should contain t,s,v,u 
#   and r respectively, undefined values will be replaced with defaults.
# * Bunches/Rooms/Groups are now associated with groupid/name. extractGroup seperates
#   them again.
# * Rooms are generated by the autoRoom function around the airbrushes. You 
#   can "help" this function by adding "mroom()" or mnoroom() to the type 
#   "air()" when creating a brush, this speeds autoRoom up. See benchmark. Most
#   of the bunches generated by f.i. Building.pm use this already.
# * Flows are generated by the autoFlow function around the waterbrushes.
# * Areas are generated by the autoArea function based on group ids/names.
# Time values from DromEd are no unqiue, it creates many things like particyleffects,
# flows/rooms with a value of 0, or 514 or whatnot. see genReport for more on this.
# Known bugs: dimensions does not know anything other then cubes/wedges :-/
#             see XXROOMXX
#   autoRoom sometimes generates the room around the wrong brush. If you have a small
#   air brush inside a larger air brush (for carpet or wall texturing), but the small
#   brush comes earlier, then autoRoom will generate a room around it, and later skip
#   the room around the larger because this would create nested rooms. It should prefer
#   the larger brush over the smaller one, tough. This is only important if brushes have
#   no mnoroom()/mroom() like when you suck in a mission file.
#
# This is the text I got from doug. not much, eh? ;) My comments are marked
# with "Tels"
#
##define EDITBR_MAX_FACES 12
#
#struct _editBrush
#{
#      // 8
#   short br_id;         // the unique runtime brush id, for CSG->brush   
#                        // mapping
#   short timestamp;     // timestamp, filled in at CSG/build time
#   int primal_id;       // what shape this is, 0==cube
#                         Tels: thats wrong, cube is actually 1..see brush2Number
#                               what does CSG stand for?
#                               magic number increased by 1 for align_by_sides
#      // 4
#   short tx_id;         // what texture to use by default
#                        // tels: for rooms: 0xffff unitialized, counting nr after
#                                 building room_db
#                                 for flows: group id
#   char  media;         // what the magic media code is
#                         Tels: 0 = solid, 1 = air, 2 = water, 
#                         0xFB = sound room, 0xFC - flow brush, 0xFD = object
#                         0xFE = area, FF - brush light (see use_flg)
#   char  flags;         // reserved for expansion
#
#      // 24
#   mxs_vector pos;      // center of the brush, for now 
#                        Tels: each is (float / 2)
#   mxs_vector sz;       // extents of brush
#                        Tels: float
#      // 8
#   mxs_angvec ang;      // angular locale of brush
#   short cur_face;      // after the above for alignment
#
#      // 24
#   Grid grid;
#   uchar num_faces;     // number of elements in the following data
#                        Tels: Room/Flow/Area brushes have a 6 here, but
#                              actually no face data
#      // 8
#   char edge;           // used to be "int pad0, pad1" in version <= 1.0
#   char point;
#   char use_flg;        // Tels: 0 = align by sides, 04 = align by vertices
#                                 0 = spotlight, 1 = omnilight
#   char group_id;       // Tels: what is this for? marking different multibrushes?
#   int pad0;            // should we set edge and point count here? or imply?
#
#      // ???
#   TexInfo txs[EDITBR_MAX_FACES]; // textures for each face of the brush
#                                  // this is actually only as long as it needs
#                                  // to be (according to num_faces),
#};
#
#
# Tels: Notes [08/28/99] & [09/10/99]
# * There are 11+2 faces in a cylinder, which gives 13, not 12, anyway...
# * an int in Perl is _at least_ 32 bits, but in dromed ints are exactly 32 bit,
#   so we use S for short and L for int in the pack below
# * What does grid stand for?
#
# when reading out B,H,P (7,6,5) from something dromed generated you get:
#rx => 6.998291015625
#ry => 5.99853515625
#rz => 4.998779296875
# this may account for some rouding errors in dimensions. !?
###############################################################################


###############################################################################
#
# Texture.pm: 
#
# * It is not possible yet to write the texture mapping back to an VBR. I do think
#   thats just not supported by DromEd, since it would then need somehow to "merge"
#   the two texture palettes.
#   So that means you are stuck to use the default mapping or create your
#   own from a mission file. It IS possible to write back the texture map,
#   to a mission file, however. Comming very soon to a computer near you...
# * textures for Bunch can either be numbers (like -1, 5 etc) or an hash ref,
#   containing the parameters s,v,u,r,t. Texture::createTexture() aids you
#   in this, although it is perfectly possible to create a texture hash by 
#   yourself by using $t = { t => 5, u => 16, s=>24 }; :-)
# usage:
# use Texture;
# $txt = Texture->create(); $txt->loadMapping("name");
# #or: $txt = Texture->create("name");
# print "Number of texture \"Grey Brick\" is ",$txt->texture("Grey Brick),"\n";
# print "Number of texture \"GrBr01\" is ",$txt->texture("grbr01),"\n";
# print "Random texture floortile: ",$txt->randtexture(floortile()),"\n";
# the next two will create a ref to an hash containing texture name as key and weight as
# value. with $txt = randTxt($list) you get a random texture back. 
# $list = $txt = txtlist("name",1,"name2",1,"name3",1); # name, weitght, name, weight
# #or: $list = $txt = txtlist( {"name" => 1, "name2" => 1 } ); # name, weitght, name, weight
###############################################################################

###############################################################################
#
# VRoom.pm: see http://bloodgate.com/thief/cow/vworld.htm
#
###############################################################################


###############################################################################
#
# GamFile.pm
#
# A chunk of version 0200000 (2), 11000000 (17) is a chunk containing normal
# texts, it contains always: obid (l), length_of_name+5 (L, maybe recordlength), 
# length_of_name+1 (L), name (ASCIIZ)
# examples: symname, designnot, book, bookart, etc. 
# note: 17 is NOT the maximum string length allowed. 
#
# schemata list: 
# format is: number (4 byte long, probably record length), Count (4 byte long)
# then Count times nr (4 byte, probably str len), asciiname (arbitrary long), 
# followed by \x01..\0x07 (relative priority of wav to use ??)
#
# brhead: (BRHEAD,7c,0)
# creator (16 bytes ASCIIZ), lastsavedby (16 bytes ASCIIZ), 68 zeros,
# gridsize (L), showgrid (L: 0,1), ?? (L), ?? (L), usegrid (L:0,1),
# working time in 1/1000 seconds (L)
#
# links ids: yyy1xxxx yyy  = flavour or -flavour (f.i. 2 or FFE)
#                     xxxx = counting number
#            0x2 = contains, 0xb = playerfactory etc
#
# L$contains:  linkID fromid toid flavournumber
# LD$contains: 0x00000004 (L) followed by:
#              linkID x (L)        (x: 0 = GenericContents, -1 Belt, -2 Hand)
# LD$ParticA:  0x00000004 followed by:
#              type (L), vhotnr (L), joint (L), submodelnr (L)
# L$MetaProp:  0011xxxx (L, counting from 1) objectid (L), baseobjectid (L),
#              0x001 (S, 0x001 since Metaprop is #1 of relations)
# LD$MetaProp: 0x00000004 followed by:
#              id (0011xxxx) from L$MetaProp (L), 0x000000 (L)
# P$FromBrief  id (L), 4 (L), 1 (L)
#              Even when adding EngineFeatures->Frombriefcase, and choosing False
#              or True, no different VBR is generated by DromEd. Also, after the
#              save, the FromBrief property has vanished. (???) 
# P$Position   Seems pos/angle is saved twice (in brushlist and in this chunk)
#              for each object. *sight*
#              (tels 2000-04-28: has to be since brlist can be stripped)                     
#              header: 0x00010016,0 
#              objectid (l), 0x16 (L), X (f), Y (f), Z (f), 0xffffffff (L), 
#              rz (S), ry (S), rx (S)
# All the other property chunk stuff formats can be found in Darkprop.pm  
###############################################################################
