From 6f4d918c661699c17b89d8af35dcba6a99479523 Mon Sep 17 00:00:00 2001
From: Bill Currie <bill@taniwha.org>
Date: Thu, 8 Sep 2011 14:38:57 +0900
Subject: [PATCH] Begin documenting sound and tidy up specifications.

---
 doc/Makefile.am        |  3 +-
 doc/config.dox         |  3 +-
 doc/quakeforge.dox     |  1 +
 doc/sound.dox          | 85 ++++++++++++++++++++++++++++++++++++++++++
 doc/specifications.dox | 13 +++++++
 5 files changed, 103 insertions(+), 2 deletions(-)
 create mode 100644 doc/sound.dox
 create mode 100644 doc/specifications.dox

diff --git a/doc/Makefile.am b/doc/Makefile.am
index ec55eb35f..09ef0c2c0 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -5,7 +5,8 @@ SUBDIRS= man
 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
+	qw-cap-spec.dox qw-download-spec.dox sound.dox specifications.dox \
+	surround-sound.dox timestamps.dox
 
 EXTRA_DIST= qf.ico \
 	\
diff --git a/doc/config.dox b/doc/config.dox
index 9a4a2eef5..ead8940f6 100644
--- a/doc/config.dox
+++ b/doc/config.dox
@@ -7,6 +7,7 @@
 \li \subpage cvars
 \li \subpage filesystem
 \li \subpage dirconf
+\li \subpage sound
 \li \subpage tracklist
 \li \subpage key_binding
 \li \subpage cshift_cvars
@@ -117,7 +118,7 @@ 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.
+\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 cvars: using the \c set
diff --git a/doc/quakeforge.dox b/doc/quakeforge.dox
index e21a7fd27..bf3da2584 100644
--- a/doc/quakeforge.dox
+++ b/doc/quakeforge.dox
@@ -12,4 +12,5 @@ of players we can.
 \li \subpage build-install
 \li \subpage faq
 \li \subpage run_config
+\li \subpage specs
 */
diff --git a/doc/sound.dox b/doc/sound.dox
new file mode 100644
index 000000000..30dc44d0c
--- /dev/null
+++ b/doc/sound.dox
@@ -0,0 +1,85 @@
+//unfortunately, have to wrap the docs in a C comment for doxygen
+// vim:tw=74:formatoptions-=l
+/**
+\page sound \QF Sound System
+The \QF sound system is designed to work with many sound systems. The
+sound systems \QF supports are:
+<dl>
+	<dt>Linux</dt>				<dd>ALSA, OSS, SDL</dd>
+	<dt>Other UNIX-like</dt>	<dd>OSS, SDL</dd>
+	<dt>Windows</dt>			<dd>DirectX, Win32, SDL</dd>
+</dl>
+There are others (SUN, SGI, MME), but their status is unkown. SUN sound
+support will build (on OpenBSD), but whether it works is unknown.
+
+In the above list, the first sound system listed for each OS is the
+default. To use one of the other supported drivers, set the \c snd_output
+cvar to the appropriate name as shown below (all systems are shown).
+
+<table>
+<tr>
+	<td>System</td><td>ALSA</td><td>OSS</td><td>DirectX</td>
+	<td>Win32</td><td>SUN</td><td>SGI</td><td>MME</td><td>SDL</td>
+</tr>
+<tr>
+	<td>Driver</td><td>alsa</td><td>oss</td><td>dx</td>
+	<td>win</td><td>sun</td><td>sgi</td><td>mme</td><td>sdl</td>
+</tr>
+</table>
+
+As \c snd_output is read-only, see \ref cvar_rom for how to set it.
+
+In addition to the above, \QF also supports JACK audio. \QF's JACK support
+should work on any system that supports JACK. However, as JACK support
+uses a different architecture (JACK audio is "pull", \QF default audio is
+"push"), selecting JACK support uses a different cvar; Set \c snd_render
+to \c jack (the following table shows the name for both render systems).
+
+<table>
+<tr>
+	<td>System</td><td>Default</td><td>JACK</td>
+</tr>
+<tr>
+	<td>Render</td><td>default</td><td>jack</td>
+</tr>
+</table>
+
+\section snd_comcc Common Cvars and Commands
+\c ambient_level<br>
+\c ambient_fade<br>
+\c precache<br>
+\c snd_swapchannelside<br>
+\c snd_volumesep<br>
+\c snd_phasesep<br>
+\c volume<br>
+
+\c play<br>
+\c playcenter<br>
+\c playvol<br>
+\c snd_force_unblock<br>
+\c soundlist<br>
+
+When \QF is built with MIDI support (using WildMidi):<br>
+\c wildmidi_config<br>
+\c wildmidi_volume<br>
+
+\section snd_defcc QF Default Cvars and Commands
+\c snd_noextraupdate<br>
+\c snd_mixahead<br>
+\c nosound<br>
+
+\c stopsound<br>
+\c soundinfo<br>
+
+\c snd_stereo<br>
+\c snd_rate<br>
+\c snd_bits<br>
+
+\c snd_device<br>
+
+\c snd_oss_mmaped<br>
+
+\section snd_jackcc JACK Cvars and Commands
+\c snd_jack_server<br>
+
+*/
diff --git a/doc/specifications.dox b/doc/specifications.dox
new file mode 100644
index 000000000..423febed0
--- /dev/null
+++ b/doc/specifications.dox
@@ -0,0 +1,13 @@
+//unfortunately, have to wrap the docs in a C comment for doxygen
+// vim:tw=74:formatoptions-=l
+/**
+\page specs Various Specifications
+
+
+\li \subpage surround_sound_spec
+\li \subpage connection_sequence
+\li \subpage mapformat
+\li \subpage property-list
+\li \subpage qw_cap_spec
+\li \subpage qw_download_spec
+*/