Merged revisions 58931 via svnmerge from

https://origsvn.digium.com/svn/asterisk/branches/1.4

........
r58931 | russell | 2007-03-15 17:25:12 -0500 (Thu, 15 Mar 2007) | 13 lines

Merge changes from svn/asterisk/team/russell/LaTeX_docs.

* Convert most of the doc directory into a single LaTeX formatted document
  so that we can generate a PDF, HTML, or other formats from this
  information.
* Add a CLI command to dump the application documentation into LaTeX format
  which will only be include if the configure script is run with 
  --enable-dev-mode.
* The PDF turned out to be close to 1 MB, so it is not included.  However, you
  can simply run "make asterisk.pdf" to generate it yourself.  We may include
  it in release tarballs or have automatically generated ones on the web site,
  but that has yet to be decided.

........


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@58932 65c4cc65-6c06-0410-ace0-fbb531ad65f3

1 files changed, 198 insertions, 0 deletions

diff --git a/doc/configuration.tex b/doc/configuration.tex
new file mode 100644
index 000000000..a501928bb
--- /dev/null
+++ b/doc/configuration.tex
@@ -0,0 +1,198 @@
+\subsubsection{Introduction}
+
+The Asterisk configuration parser in the 1.2 version
+and beyond series has been improved in a number of ways. In
+addition to the realtime architecture, we now have the ability to create
+templates in configuration files, and use these as templates when we
+configure phones, voicemail accounts and queues.
+
+These changes are general to the configuration parser, and works in
+all configuration files. 
+
+\subsubsection{General syntax}
+Asterisk configuration files are defined as follows:
+
+\begin{verbatim}
+	[section]
+	label = value
+	label2 = value
+\end{verbatim}
+
+In some files, (e.g. mgcp.conf, zapata.conf and agents.conf), the syntax
+is a bit different. In these files the syntax is as follows:
+	
+\begin{verbatim}
+	[section]
+	label1 = value1
+	label2 = value2
+	object => name
+
+	label3 = value3
+	label2 = value4
+	object2 => name2
+\end{verbatim}
+
+In this syntax, we create objects with the settings defined above the object
+creation. Note that settings are inherited from the top, so in the example 
+above object2 has inherited the setting for "label1" from the first object.
+
+For template configurations, the syntax for defining a section is changed
+to:
+\begin{verbatim}
+	[section](options)
+	label = value
+\end{verbatim}
+
+The options field is used to define templates, refer to templates and hide
+templates. Any object can be used as a template.
+
+No whitespace is allowed between the closing "]" and the parenthesis "(".
+
+\subsubsection{Comments}
+
+All lines that starts with semi-colon ";" is treated as comments
+and is not parsed.
+
+The ";--" is a marker for a multi-line comment. Everything after
+that marker will be treated as a comment until the end-marker "--;"
+is found. Parsing begins directly after the end-marker.
+
+\begin{verbatim}
+	;This is a comment
+	label = value
+	;-- This is 
+	a comment --;
+	
+	;-- Comment --; exten=> 1000,1,dial(SIP/lisa)	
+\end{verbatim}
+
+\subsubsection{Including other files}
+In all of the configuration files, you may include the content of another
+file with the \#include statement. The content of the other file will be
+included at the row that the \#include statement occurred.
+	
+\begin{verbatim}
+	#include myusers.conf
+\end{verbatim}
+
+You may also include the output of a program with the \#exec directive,
+if you enable it in asterisk.conf
+	
+In asterisk.conf, add the execincludes = yes statement in the options
+section:
+\begin{verbatim}
+	[options]
+	execincludes=yes
+\end{verbatim}
+
+The exec directive is used like this:
+	
+\begin{verbatim}
+	#exec /usr/local/bin/myasteriskconfigurator.sh
+\end{verbatim}
+
+\subsubsection{Adding to an existing section}
+\begin{verbatim}
+	[section] 
+	label = value
+	
+	[section](+)
+	label2 = value2	
+\end{verbatim}	
+
+In this case, the plus sign indicates that the second section (with the
+same name) is an addition to the first section. The second section can
+be in another file (by using the \#include statement). If the section
+name referred to before the plus is missing, the configuration will fail
+to load.
+
+\subsubsection{Defining a template-only section}
+\begin{verbatim}
+	[section](!)
+	label = value
+\end{verbatim}
+
+The exclamation mark indicates to the config parser that this is a only
+a template and should not itself be used by the Asterisk module for
+configuration. The section can be inherited by other sections (see 
+section "Using templates" below) but is not used by itself.
+
+\subsubsection{Using templates (or other configuration sections)}
+\begin{verbatim}
+	[section](name[,name])
+	label = value
+\end{verbatim}
+
+The name within the parenthesis refers to other sections, either
+templates or standard sections. The referred sections are included
+before the configuration engine parses the local settings within the
+section as though their entire contents (and anything they were 
+previously based upon) were included in the new section.  For example 
+consider the following:
+
+\begin{verbatim}
+[foo]
+permit=192.168.0.2
+host=asdf
+deny=192.168.0.1
+
+[bar]
+permit=192.168.1.2
+host=jkl
+deny=192.168.1.1
+
+[baz](foo,bar)
+permit=192.168.3.1
+host=bnm
+\end{verbatim}
+
+The [baz] section will be processed as though it had been written in the 
+following way:
+
+\begin{verbatim}
+[baz]
+permit=192.168.0.2
+host=asdf
+deny=192.168.0.1
+permit=192.168.1.2
+host=jkl
+deny=192.168.1.1
+permit=192.168.3.1
+host=bnm
+\end{verbatim}
+
+\subsubsection{Additional Examples}
+
+(in top-level sip.conf)
+
+\begin{verbatim}
+[defaults](!)
+type=friend
+nat=yes
+qualify=on
+dtmfmode=rfc2833
+disallow=all
+allow=alaw
+
+#include accounts/*/sip.conf
+\end{verbatim}
+
+(in accounts/customer1/sip.conf)
+
+\begin{verbatim}
+[def-customer1](!,defaults)
+secret=this_is_not_secret
+context=from-customer1
+callerid=Customer 1 <300>
+accountcode=0001
+
+[phone1](def-customer1)
+mailbox=phone1@customer1
+
+[phone2](def-customer1)
+mailbox=phone2@customer1
+\end{verbatim}
+
+This example defines two phones - phone1 and phone2 with settings
+inherited from "def-customer1".  The "def-customer1" is a template that
+inherits from "defaults", which also is a template.