Initial version of conf.doxygen

2 files changed, 222 insertions, 1 deletions

diff --git a/doc/conf.doxygen b/doc/conf.doxygen
new file mode 100644
index 00000000..866f341d
--- /dev/null
+++ b/doc/conf.doxygen
@@ -0,0 +1,221 @@
+/*! \page conf Configuration files
+
+<P>Configuration files are using a simple format allowing the modern
+data description like nesting and array assignments.</P>
+
+\section conf_whitespace Whitespace
+
+Whitespace is the collective name given to spaces (blanks), horizontal and
+vertical tabs, newline characters, and comments. Whitespace can serve to
+indicate where configuration tokens start and end, but beyond this function,
+any surplus whitespace is discarded. For example, the two sequences
+
+\code
+  a 1 b 2
+\endcode
+
+and
+
+\code
+  a 1 
+     b 2
+\endcode
+
+are lexically equivalent and parse identically to give the four tokens:
+
+\code
+a
+1
+b
+2
+\endcode
+
+The ASCII characters representing whitespace can occur within literal
+strings, int which case they are protected from the normal parsing process
+(tey remain as part of the string). For example:
+
+\code
+  name "John Smith"
+\endcode
+
+parses to two tokens, including the single literal-string token "John
+Smith".
+
+\section conf_linesplicing Line splicing with \\
+
+A special case occurs, if the final newline character encountered is
+preceded by a backslash (\) in the string value definition. The backslash
+and new line are both discarded, allowing two physical lines of text to be
+treated as one unit.
+
+\code
+"John \\
+Smith"
+\endcode
+
+is parsed as "John Smith".
+
+\section conf_comments Comments
+
+A single-line comments are defined using character #. The comment can start
+in any position, and extends until the next new line.
+
+\code
+  a 1  # this is a comment
+\endcode
+
+\section conf_include Include another configuration file
+
+A new configuration file can be included using <filename> syntax. The global
+configuration directory can be referenced using <confdir:filename> syntax.
+
+\code
+</etc/alsa1.conf>
+<confdir:pcm/surround.conf>
+\endcode
+
+\section conf_punctuators Punctuators
+
+The configuration punctuators (also known as separators) are:
+
+\code
+  {} [] , ; = . ' " new-line form-feed carriage-return whitespace
+\endcode
+
+\subsection conf_braces Braces
+
+Open and close braces { } indicate the start and end of a compound
+statement:
+
+\code
+a {
+  b 1
+}
+\endcode
+
+\subsection conf_brackets Brackets
+
+Open and close brackets indicate single array definition. The identificators
+are automatically generated starting with zero.
+
+\code
+a [
+  "first"
+  "second"
+]
+\endcode
+
+Above code is equal to
+
+\code
+a.0 "first"
+a.1 "second"
+\endcode
+
+\subsection conf_comma_semicolon Comma and semicolon
+
+The comma (,) or semicolon (;) can separate the value assignments. It is not
+strictly required to use these separators, because any whitespace supplies
+them.
+
+\code
+a 1;
+b 1,
+\endcode
+
+\subsection conf_equal Equal sign
+
+The equal sign (=) separates can separate variable declarations from
+initialization lists:
+
+\code
+a=1
+b=2
+\endcode
+
+Using the equal signs is not required, because any whitespace supplies
+them.
+
+\section conf_assigns Assigns
+
+The configuration file defines id (key) and value pairs. The id (key) can be
+composed from any ASCII digits or chars from a to z or A to Z, including
+char _. The value can be either a string, integer or real number.
+
+\subsection conf_single Single assign
+
+\code
+a 1	# is equal to
+a=1	# is equal to
+a=1;	# is equal to
+a 1,
+\endcode
+
+\subsection conf_compound Compound assign (definition using braces)
+
+\code
+a {
+  b = 1
+}
+a={
+  b 1,
+}
+\endcode
+
+\section conf_compound1 Compound assign (one key definition)
+
+\code
+a.b 1
+a.b=1
+\endcode
+
+\subsection conf_array Array assign (definition using brackets)
+
+\code
+a [
+  "first"
+  "second"
+]
+\endcode
+
+\subsection conf_array1 Array assign (one key definition)
+
+\code
+a.0 "first"
+a.1 "second"
+\endcode
+
+\section conf_summary Summary
+
+\code
+# Configuration file syntax
+
+# Include a new configuration file
+<filename>
+
+# Simple assign
+name [=] value [,|;]
+
+# Compound assign (first style)
+name [=] {
+        name1 [=] value [,|;]
+        ...
+}
+
+# Compound assign (second style)
+name.name1 [=] value [,|;]
+
+# Array assign (first style)
+name [
+        value0 [,|;]
+        value1 [,|;]
+        ...
+]
+
+# Array assign (second style)
+name.0 [=] value0 [,|;]
+name.1 [=] value1 [,|;]
+\endcode
+
+
+*/
diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg
index ba518b84..096274cf 100644
--- a/doc/doxygen.cfg
+++ b/doc/doxygen.cfg
@@ -5,7 +5,7 @@ GENERATE_MAN     = NO
 GENERATE_RTF	 = NO
 
 CASE_SENSE_NAMES = NO
-INPUT            = index.doxygen pcm.doxygen ../include ../src
+INPUT            = index.doxygen conf.doxygen pcm.doxygen ../include ../src
 EXCLUDE		 = ../src/control/control_local.h \
 		   ../src/pcm/atomic.h \
 		   ../src/pcm/interval.h \