Do some work on the user documentation.

Also document part of the cvar api.

doc/Makefile.am

@@ -3,7 +3,7 @@ AUTOMAKE_OPTIONS= foreign
 SUBDIRS= man
 
 DOX=\
-	bind.dox connect.dox cshifts.dox dirconf.dox faq.dox \
+	bind.dox config.dox connect.dox cshifts.dox dirconf.dox faq.dox \
 	filesystem.dox mapformat.dox property-list.dox qtv.dox quakeforge.dox \
 	qw-cap-spec.dox qw-download-spec.dox surround-sound.dox timestamps.dox
 

doc/config.dox

@@ -0,0 +1,122 @@
+//unfortunately, have to wrap the docs in a C comment for doxygen
+/**
+\page run_config Runtime Configuration.
+
+\li \subpage cvars
+\li \subpage filesystem
+\li \subpage dirconf
+\li \subpage tracklist
+\li \subpage key_binding
+\li \subpage cshift_cvars
+\li \subpage server_timestamps
+
+*/
+
+/**
+\page cvars Configuration variables
+
+The core of \QF's configurabitly is the cvar.
+
+\section cvar_value Cvar values.
+Depending how the engine's use of the cvar, the value will be treated as a
+string, a floating point value, an integer value or even a vector value.
+
+If a space is needed in the value, the value must be "quoted".
+
+\section cvar_type Cvar types.
+From the user's perspective, there are three types of cvar:
+\li plain cvar: the value can be displayed or set, but will not be
+automatically saved.
+\li archive cvar: like a plain cvar, the value can be displayed or set, but
+the cvar will be automatically saved to \c config.cfg by the engine on
+shutdown or gamedir change (quakeworld).
+\li read-only cvar: the value can be displayed but not changed in any way
+(value or flags). If the cvar also happens to be an archive cvar (the
+archive flag was set before the read-only flag), then the cvar will be
+saved to \c config.cfg.
+
+\section cvar_cmds Cvar related commands.
+<code>\<cvar\> [value]</code><br>
+Display the current value of the specified cvar. If \c value is given, set
+the cvar to \c value. Does not create a new cvar.
+
+<code>set \<cvar\> \<value\></code><br>
+Set the specified cvar to the specified value. If the cvar does not already
+exist, a new cvar will be created.
+
+<code>seta \<cvar\> \<value\></code><br>
+Set the specified cvar to the specified value. If the cvar does not already
+exist, a new cvar will be created. Sets the cvar's archive flag so it will
+be automatically saved to \c config.cfg by the clients.
+
+<code>setrom \<cvar\> \<value\></code><br>
+Set the specified cvar to the specified value. If the cvar does not already
+exist, a new cvar will be created. Sets the cvar's read-only flag so it can
+no longer be modified in any way (not even by \c reset or \c resetall).
+
+<code>toggle \<cvar\></code><br>
+Treat the cvar as a boolean value, changing it from off to on, or on to
+off. Any non-zero integer value is considered to be on, while zero and
+any string that parses as zero (does not start with a non-zero number) will
+be treated as off. The new value will always be either one (1) or zero (0).
+\note values smaller than 1 will be treated as off.
+
+<code>cvarlist [foo]</code><br>
+Print a list of all cvars known to the engine (engine created or user
+created). If the foo parameter is given (any value), then extra
+information (cvar description, flags) will also be printed.
+
+<code>cycle \<cvar\> \<value list\></code><br>
+Cause the cvar to cycle through the list of values. Each time this command
+is executed, the cvar will change to the value immediately after the cvar's
+current value in the list, cycling back to the beginning when the current
+value is the last value in the list. If the current value is not in the
+list, the cvar will be set to the first value in the list.
+
+<code>inc \<cvar\> [amount]</code><br>
+Add one (1) to the cvar's current numeric value. If the optional amount is
+given, add that value to the cvar's current numeric value. Using -1
+(<code>inc \<cvar\> -1</code>), this can be used as a \c dec command.
+
+<code>reset \<cvar\></code><br>
+Reset the specified cvar to its default (engine specified) value.
+
+<code>resetall</code><br>
+Reset all cvars to their default (engine specified values).
+
+\section cvar_rom Read-only cvars.
+Many cvars in \QF are read-only because changing them at runtime would
+either have little meaning or be difficult to implement. However, there
+<em>is</em> a way to change even a read-only cvarsing the \c set command,
+the cvar can be created with the desired value before the engine creates
+the cvar (and sets its read-only flag). There are exactly three places
+where the cvar can be created before the engine does:
+\li the command line (eg <code>nq-glx +set snd_rate 48000</code>)
+\li the global configuration file specified by the \c fs_globalcfg cvar.
+\li the user configuration file specified by the \c fs_usercfg cvar.
+
+The global and user configuration files are normal quake scripts, but only
+\c set, \c seta, and \c setrom commands are executed.
+
+It might seem strange to have the global and user configuration files
+specified by cvars, but \QF's startup sequence is quite intense:
+\li execute any \c set commands given on the command line. This way, \c
+fs_globalcfg can be set.
+\li execute any \c set commands in the global configuration file. This way,
+\c fs_usercfg can be set.
+\li re-execute any \c set commands given on the command line. Thus it is
+possible to override \c fs_usercfg if it is set by the global configuration
+file (unless \c setrom is used: BOFH).
+\li execute any \c set commands in the user configuration file. Any cvars
+set in the user configuration file override those set in the global
+configuration file.
+\li once again, re-execute any \c set commands given on the command line.
+Thus cvars set on the command line override those set in either the user
+configuration file or the global configuration file (or both).
+
+During the above process, the only cvars created by the engine are \c
+fs_globalcfg (just before reading the global configuration file) and \c
+fs_usercfg (just before reading the user configuration file). Thus, it is
+possible to set <em>any</em> cvar in \QF.
+
+*/

doc/faq.dox

@@ -7,6 +7,7 @@
 \li \ref git_compile_error
 \li \ref no_music
 \li \ref no_mp3
+\li \ref faq_cvar_rom
 
 \section gfx_wad What does "W_LoadWadFile: unable to load gfx.wad" mean?
 The most common cause of this error is QuakeForge is unable to find
@@ -17,6 +18,8 @@ Linux (and other UNIX like operating systems), fs_userpath defaults to
 ~/.quakeforge and fs_sharepath defaults to $prefix/share/games/quakeforge
 (distribution packages might alter the exact path).
 
+See \ref filesystem for more details.
+
 \section pak0_pak Where can I get pak0.pak?
 See \ref game_data
 
@@ -60,4 +63,8 @@ the value appropriate for your system:
 Because they are not free. MP3 support is a patent minefield, and we really
 don't want to wind up with lawyers at ten paces, especially since we'd be
 unarmed with no armor, and they have rocket launchers and quad-damage.
+
+\section faq_cvar_rom How do I set a read-only cvar (eg, snd_rate)?
+Read-only cvars can be set by creating them before the engine does. See
+\ref cvar_rom for details.
 */

doc/quakeforge.dox

@@ -10,12 +10,5 @@ of players we can.
 
 \li \subpage build-install
 \li \subpage faq
-\li \subpage key_binding
+\li \subpage run_config
-\li \subpage cshift_cvars
-\li \subpage filesystem
-\li \subpage dirconf
-\li \subpage qw_cap_spec
-\li \subpage qw_download_spec
-\li \subpage server_timestamps
-\li \subpage qtv_overview
 */

include/QF/cvar.h

@@ -38,42 +38,55 @@
 #include "QF/quakeio.h"
 
 typedef struct cvar_s {
-	const char *name;
+	const char *name;			///< The name of the cvar.
-	const char *string;
+	const char *string;			///< The current cvar value as a string.
-	const char *default_string;
+	const char *default_string;	///< The default value of the cvar.
-	int	        flags;
+	int	        flags;			///< Cvar flags
+	/** Callback for when the cvar value changes.
+	
+		This allows for more flexibility in what happens when a cvar is
+		nodifed than can be achieved with flags alone. While a similar could
+		be done using commands, a cvar with a callback and CVAR_ARCHIVE set
+		allows the setting to be saved automatically.
+
+		\param var	This cvar.
+	*/
 	void      (*callback)(struct cvar_s *var);
-	const char *description;	// for "help" command
+	const char *description;	///< for "help" command
-	float       value;
+	float       value;			///< The current cvar value as a float
-	int         int_val;
+	int         int_val;		///< The current cvar value as an integer
-	vec3_t      vec;
+	vec3_t      vec;			///< The current cvar value as a vector
-	struct cvar_s *next;
+	struct cvar_s *next;		///< \internal Linked list of cvars.
 } cvar_t;
 
 typedef struct cvar_alias_s {
-	char       *name;
+	char       *name;			///< The name of the alias.
-	cvar_t     *cvar;
+	cvar_t     *cvar;			///< The cvar to which this alias refers
-	struct cvar_alias_s	*next;
+	struct cvar_alias_s	*next;	///< \internal LInked list of aliases.
 } cvar_alias_t;
 
-#define CVAR_NONE			0
+/** \name cvar_flags
-#define	CVAR_ARCHIVE		1		// set to cause it to be saved to vars.rc
+	Zoid| A good CVAR_ROM example is userpath.  The code should read "cvar_t
-									// used for system variables, not for player
+	*fs_userpath = CvarGet("fs_userpath", ".", CVAR_ROM);  The user can
-									// specific configurations
+	override that with +set fs_userpath \<blah\> since the command line +set
-#define	CVAR_USERINFO		2		// sent to server on connect or change
+	gets created _before_ the C code for fs_basepath setup is called.  The
-#define	CVAR_SERVERINFO		4		// sent in response to front end requests
+	code goes "look, the user made fs_basepath already", uses the users value,
-#define	CVAR_NOTIFY			32		// Will notify players when changed.
+	but sets CVAR_ROM as per the call.
-#define	CVAR_ROM			64		// display only, cannot be set by user at all
+*/
-#define	CVAR_USER_CREATED	128		// created by a set command
+//@{
-#define CVAR_LATCH			2048	// will change only when C code next does
+#define CVAR_NONE			0		///< normal cvar
-									// a Cvar_Get(), so it can't be changed
+#define	CVAR_ARCHIVE		1		///< set to cause it to be saved to
-
+									///< config.cfg
-// Zoid| A good CVAR_ROM example is userpath.  The code should read "cvar_t
+#define	CVAR_USERINFO		2		///< sent to server on connect or change
-// *fs_userpath = CvarGet("fs_userpath", ".", CVAR_ROM);  The user can
+#define	CVAR_SERVERINFO		4		///< sent in response to front end requests
-// override that with +set fs_userpath <blah> since the command line +set gets
+#define	CVAR_NOTIFY			32		///< Will notify players when changed.
-// created _before_ the C code for fs_basepath setup is called.  The code goes
+									///< (not implemented)
-// "look, the user made fs_basepath already", uses the users value, but sets
+#define	CVAR_ROM			64		///< display only, cannot be set
-// CVAR_ROM as per the call.
+#define	CVAR_USER_CREATED	128		///< created by a set command
+#define CVAR_LATCH			2048	///< will change only when C code next does
+									///< a Cvar_Get(), so it can't be changed
+									///< (not implemented)
+//@}
 
 
 // Returns the Cvar if found, creates it with value if not.  Description and