transfer from internal tree r5311 branches/1.4-gpl

git-svn-id: svn://svn.icculus.org/gtkradiant/GtkRadiant/branches/ZeroRadiant@177 8a3a26a2-13c4-0310-b231-cf6edde360e5

docs/developer/DRAFT

@@ -0,0 +1,130 @@
+usefull global variables in Radiant:
+g_strAppPath has the path to the binary
+
+-----------------------------------------------------------------------
+using prefs / ini settings:
+are stored in Radiant.ini and *.bin files
+win32:
+looks in the current directory for a Radiant.ini file
+if found, will use it and set the ini directory to the proper location
+if not found:
+the registry has a path to the default directory?
+under key HKEY_CURRENT_USER/Software/GtkRadiant/PrimaryEditorPath
+(DefaultEditorPath cause that gets used for 
+if the key doesn't exist create in current directory and set the key
+NOTE: need some registry version info, when we find in another dir than ours,
+  check version and prompt to use existing settings or our own?
+
+storing version information:
+each build publicly released should have a version string
+- use it in the about box
+- store it in the Radiant.ini file
+- use it in the registry GtkRadiant/
+do we need major and minor? minor could be used for versions that don't break .ini compatibility
+  (well I'm lazy .. won't do)
+
+linux:
+look in the current directory (check write permission!)
+if found, use it
+if not found:
+look in ~/.q3a/radiant
+
+-----------------------------------------------------------------------
+icons:
+look for bitmaps/ under g_strAppPath
+win32:
+if not found, use DefaultEditorPath registry key and try to locate there
+linux:
+we also need a DefaultEditorPath kind of thing?
+somewhere in ~/.q3a/radiant?
+
+-----------------------------------------------------------------------
+project file:
+Radiant.ini must have full path to the project file
+if no project file path:
+win32:
+we have to locate BASEPATH one way or the other. we have code that will look for the
+main directory and go down into baseq3/scripts. If that fails we prompt the user.
+it would be good to store BASEPATH in the .ini as well!
+linux:
+store path to Radiant installation somewhere in ~/.q3a/radiant
+if not found try some defaults and prompt the user
+
+NOTE: on linux radiant is in /usr/local/games/quake3/ instead of some
+quake3/tools directory. This makes looking for the basepath easier.
+
+g_PrefsDlg.m_strLastProject points to the project to be loaded
+if radiant cannot find it at startup it will try to guess and/or ask the user
+once the project file is loaded you can deduce a lot of things..
+but project file parsing has some prerequisites: __QERPATH / __QERHOMEPATH ??
+need to unify between win32 and linux!
+PrefsDlg has a bunch of defaults, but it must not try to guess 
+  __QERPATH and __QERHOMEPATH until there has been an ini load (or a lack of)
+the involved members are:
+m_strQuake2 <- points to the engine path, renamed to m_strBasePath m_strEngine
+m_strPAKFile <- built from m_strBasePath, removed (not used?)
+and: need to add more, like map compilers directory m_strToolsPath
+
+project file syntax:
+linux version is using __QERPATH / __QERHOMEPATH
+win32 has __Q2PATH __QERPATH
+and the overall syntax is different!
+
+big problem is user customization, it performs expansion and saves with static
+paths. but we'd like to keep the original one with generic naming. (cause if the
+config fucks up and user reinstalls he'll still get broken project settings)
+so: we try to load quake.qe4 project, expand it, and save as user.qe4
+(on linux, user.qe4 goes in ~/.q3a/baseq3/scripts)
+
+TODO: how is "New project" supposed to work? would copy the current project..
+TODO: get rid of m_bLoadLast .. we require having a project loaded for use?
+TODO: store path to the tools in prefs? (see usage for project file expansion?)
+  -> so you can use q3map in a given dir etc?
+
+unifying project file syntaxes:
+
+get rid of BuildShortPathName things!
+
+-----------------------------------------------------------------
+some common operations and portable code:
+document XP use of stat, checking for directory / file existence
+
+how to have code that reads well across XP:
+don't use TABS, have them emulated to 2 spaces
+
+-----------------------------------------------------------------
+project files:
+unless we rewrite a whole bunch of it from scratch there's no much
+hope for evolution of the project files. Nevertheless, introduced
+a new "version" key that describes the version of the project file.
+version 2 adds a # keyword for q3map global options
+NOTE: and it's a compatibility nightmare, we can't call this one
+quake.qe4 or default.qe4 cause it will break backward compatibility
+
+-----------------------------------------------------------------
+monitoring BSP process:
+we monitor through network connections
+we need to stop the process if an error occurs during one of the three steps
+and launch quake3 when all is done
+we don't want to CreateProcess and watch cause for rsh mode it will return immediately
+a BSP process is decomposed in several steps and we expect a connection at each step
+- later we can add custom steps that don't net connect and then we just spawn and
+watch them
+- we could add a name to the step to identify them, for now we'll just assume
+the first connection that we get is the one of the process we spawned
+when we loose the connection we wait one sec and spawn the next one...
+- we don't use batch file, just produce the command lines for each steps, the batch file
+will be produced only if we don't monitor the process (we can add an option to output
+the BAT file anyway)
+
+what stuff goes in prefs? "Monitor BSP process"
+
+detecting when the socket closes?
+using select() one can detect if a socket has closed or if there's some input
+NOTE: when launching a new BSP process we may still be connected. Need to ask the user
+about overridding and closing current connection.
+
+in prefs, boolean flag for process monitoring .. g_PrefsDlg.m_bWatchBSP
+
+when running in monitored mode, the BSP watcher is in charge of spawning and watching
+the processes (and more later when it will be parsing the output).