Make the property-list documentation useful for users.

doc/Makefile.am

@@ -4,8 +4,8 @@ SUBDIRS= man
 
 DOX=\
 	bind.dox connect.dox cshifts.dox dirconf.dox faq.dox \
-	filesystem.dox mapformat.dox qtv.dox quakeforge.dox qw-cap-spec.dox \
+	filesystem.dox mapformat.dox property-lists.dox qtv.dox quakeforge.dox \
-	qw-download-spec.dox surround-sound.dox timestamps.dox
+	qw-cap-spec.dox qw-download-spec.dox surround-sound.dox timestamps.dox
 
 EXTRA_DIST= qf.ico \
 	\

doc/property-lists.dox

@@ -0,0 +1,90 @@
+//unfortunatly, have to wrap the docs in a C comment for doxygen
+/**
+\page property-lists Property Lists
+
+\QF's property lists are based on those used in OpenStep.
+
+\QF uses property lists for a wide variety of purposes. This includes saved
+game data, directory configuration and play-lists.
+
+Property lists are text files that describe a single value. However, that
+value can be one of the following types:
+<dl>
+	<dt>Dictionaries</dt>	<dd>Lists of values that are each accociated
+							with a key</dd>
+	<dt>Arrays</dt>			<dd>Lists of indexed values</dd>
+	<dt>Strings</dt>		<dd>Simple text strings.</dd>
+	<dt>Binary data</dt>	<dd>Random binary data</dd>
+</dl>
+Dictionary and Array values allow for arbitrarily complex data to be
+represented by a property list.
+
+In addition, property lists also support comments, both single-line and
+multi-line. Single-line comments start with \c // and continue to the end
+of the line. Multi-line comments begine with
+<!-- crazy formatting to get C comments--><code>/</code><code>*</code> and
+end with <code>*</code><code>/</code>, and may span multiple lines, or be
+contained entirely within a single line, possibly with non-comment text
+following the comment.
+
+\section pl-dictionaries Dictionaries.
+A dictionary is a list of values, each associated with a key. The order of
+key/value pairs in a dictionary is not preserved.
+
+\code
+{
+	key1 = value1;
+	key2 = value2;
+	// ...
+}
+\endcode
+
+A dictionary may be empty or have any number of
+<code>key&nbsp;=&nbsp;value</code> pairs separated by \c ;. The final \c ;
+before the closing \c } is optional.
+
+The key must be a string, but the value may be of any type, including
+dictionary or array.
+
+\section Arrays
+An array is an ordered list of values. The order of the values in an array
+is preserved.
+
+\code
+(
+	value1,
+	value2,
+	// ...
+)
+\endcode
+
+An array may be empty or have any number of values. Each value may be of
+any type, including dictionary or array.
+
+\section pl-strings Strings
+\QF's property lists support three types of strings: unquoted, quoted and
+"long".
+
+An unquoted string may contain most printable characters. This includes the
+digits \c 0 to \c 9, the letters \c a to \c z and \c A to \c Z, and the
+symbols \c !, \c #, \c $, \c %, \c &, \c *, \c +, \c -, \c ., \c /, \c :,
+\c ?, \c @, \c |, \c ~, \c _ and \c ^.
+\verbatim
+0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ
+abcdefghijklmnopqrstuvwxyz!#$%&*+-./:?@|~_^
+\endverbatim
+
+Quoted strings may contain whitespace, C escape sequences, and any
+printable character. The quote character is \c \".
+
+Long strings use tripple quotes (\c \"\"\") instead of \c \" as the quote
+character. This allows the use of unquoted \c \" characters in the string.
+And yes, these long strings were inspired by Python's long strings.
+
+\section pl-binary Binary Data
+<!-- in the following paragraph, the \< and \> are just < and >. the \ is
+	 for doxygen -->
+Binary data is hex-encoded and contained within angle brackets (\c \< \c
+\>). There must be an even number of hex-digits. That is, while \c \<FF00\>
+is value, \c \<F00\> is not.
+*/

include/QF/qfplist.h

@@ -36,46 +36,17 @@
 
 #include "QF/qtypes.h"
 
-/**
+/** The type of the property list item.
-	There are four types of data that can be stored in a property list:
 
-	<dl>
+	For further details, see \ref property-lists.
-		<dt>QFDictionary</dt>	<dd>A list of values, each associated with a
-								key (a C string).</dd>
-		<dt>QFArray</dt>		<dd>A list of indexed values</dd>
-		<dt>QFString</dt>		<dd>A string.</dd>
-		<dt>QFBinary</dt>		<dd>Random binary data.</dd>
-	</dl>
-
-	In textual form, a dictionary looks like:
-	\code
-	{
-		key = value;
-	}
-	\endcode
-	An array looks like:
-	\code
-	(
-		value1,
-		value2
-	)
-	\endcode
-	An unquoted string may contain only alphanumeric characters and/or the
-	underscore character, <code>_</code>. Quoted strings may contain
-	whitespace, C escape sequences, and so on. The quote character is
-	<code>\"</code>. Optionally, Python style long strings
-	(<code>\"\"\"...\"\"\"</code>) may be used, allowing for unquoted
-	<code>"</code> quotes in the string.
-
-	<!-- in the following paragraph, the \< and \> are just < and >. the \ is
-		 for doxygen -->
-	QFBinary data is hex-encoded and contained within angle brackets, \c \<
-	\c \>.  The length of the encoded data must be an even number, so while 
-	\c \<FF00\> is valid, \c \<F00\> isn't.
-
-	Property lists may contain C-style or BCPL-style comments.
 */
-typedef enum {QFDictionary, QFArray, QFBinary, QFString} pltype_t;
+typedef enum {
+	QFDictionary,	///< The property list item represents a dictionary.
+	QFArray,		///< The property list item represents an array.
+	QFBinary,		///< The property list item represents arbitrary binary
+					///< data.
+	QFString		///< The property list item represents a C string.
+} pltype_t;
 
 /**	Generic property list item.