--- main/pbx.c.orig	2010-01-05 14:30:44.000000000 -0500
+++ main/pbx.c	2010-04-15 17:05:01.000000000 -0400
@@ -12,7 +12,7 @@
  * channels for your use.
  *
  * This program is free software, distributed under the terms of
-* the GNU General Public License Version 2. See the LICENSE file
+ * the GNU General Public License Version 2. See the LICENSE file
  * at the top of the source tree.
  */
 
@@ -89,29 +89,49 @@
 /*** DOCUMENTATION
 	<application name="Answer" language="en_US">
 		<synopsis>
-			Answer a channel if ringing.
+			Answer an incoming call, if it has not been answered already.
 		</synopsis>
 		<syntax>
-			<parameter name="delay">
-				<para>Asterisk will wait this number of milliseconds before returning to
-				the dialplan after answering the call.</para>
+			<parameter name="timeout">
+				<para>Number of milliseconds to wait for the audio channel to be 
+				established before returning to the dialplan. The default is
+				500. Values less than 500 are ignored.</para>
 			</parameter>
 			<parameter name="nocdr">
-				<para>Asterisk will send an answer signal to the calling phone, but will not
-				set the disposition or answer time in the CDR for this call.</para>
+				<para>Asterisk will send an answer signal to the calling phone, but
+				will not set the disposition or answer time in the CDR for this
+				call.</para>
 			</parameter>
 		</syntax>
 		<description>
 			<para>If the call has not been answered, this application will
-			answer it. Otherwise, it has no effect on the call.</para>
+			answer it. Otherwise, it will have no effect on the call.</para>
+			<para>This application is generally used to answer the call before
+			entering an IVR menu. Answering a call stops the ringing sound produced by
+			<literal>Ringing</literal>, updates the CDR record, and starts the timer
+			while counts (potentially) billable time.</para>
+			<para>It is neither necessary nor desirable to call <literal>Answer</literal>
+			if the call will be routed onward using <literal>Dial</literal> since
+			<literal>Dial</literal> will pass back the answer signal when and if the call
+			is answered at its final destination. Calling <literal>Answer</literal>
+			before the call is actually answered would cause the caller to be billed
+			for the time the callee's phone is ringing, whether or not the call is
+			ever answered.</para>
+			<para>If you wish to play error messages (such as "all circuits busy") to the
+			caller, use <literal>Progress</literal>. This will open the audio channel
+			without indicating that the call has been answered.</para>
 		</description>
 		<see-also>
+			<ref type="application">Ringing</ref>
+			<ref type="application">Progress</ref>
+			<ref type="application">Busy</ref>
+			<ref type="application">Congestion</ref>
 			<ref type="application">Hangup</ref>
 		</see-also>
 	</application>
 	<application name="BackGround" language="en_US">
 		<synopsis>
-			Play an audio file while waiting for digits of an extension to go to.
+			Play an audio file while listening for DTMF digits.
 		</synopsis>
 		<syntax>
 			<parameter name="filenames" required="true" argsep="&amp;">
@@ -127,27 +147,29 @@
 						application will return immediately.</para>
 					</option>
 					<option name="n">
-						<para>Don't answer the channel before playing the files.</para>
+						<para>Do not answer the incoming call before playing the files.</para>
 					</option>
 					<option name="m">
-						<para>Only break if a digit hit matches a one digit
+						<para>Only break if a digit is received which matches a one digit
 						extension in the destination context.</para>
 					</option>
 				</optionlist>
 			</parameter>
 			<parameter name="langoverride">
-				<para>Explicitly specifies which language to attempt to use for the requested sound files.</para>
+				<para>Requests sound files in the specified language rather than the channel's language.</para>
 			</parameter>
 			<parameter name="context">
-				<para>This is the dialplan context that this application will use when exiting
-				to a dialed extension.</para>
+				<para>This is the dialplan context in which this application will seek an
+				extension cooresponding to the dialed digits.</para>
 			</parameter>
 		</syntax>
 		<description>
-			<para>This application will play the given list of files <emphasis>(do not put extension)</emphasis>
-			while waiting for an extension to be dialed by the calling channel. To continue waiting
-			for digits after this application has finished playing files, the <literal>WaitExten</literal>
-			application should be used.</para>
+			<para>Play the files listed <emphasis>(listed without filename
+			extension)</emphasis> while collecting dialed digits from the calling channel. When the first
+			digit is received, playback stops and digits are collected. If a complete extension is 
+			collected, execution will jump to that extension immediately. 
+			To continue waiting even if the last file plays to the end without interruption, call
+			<literal>WaitExten</literal> after <literal>BackGround</literal>.</para>
 			<para>If one of the requested sound files does not exist, call processing will be terminated.</para>
 			<para>This application sets the following channel variable upon completion:</para>
 			<variablelist>
@@ -159,6 +181,7 @@
 			</variablelist>
 		</description>
 		<see-also>
+			<ref type="application">Playback</ref>
 			<ref type="application">ControlPlayback</ref>
 			<ref type="application">WaitExten</ref>
 			<ref type="application">BackgroundDetect</ref>
@@ -167,16 +190,17 @@
 	</application>
 	<application name="Busy" language="en_US">
 		<synopsis>
-			Indicate the Busy condition.
+			Ask caller's equipment to play busy signal.
 		</synopsis>
 		<syntax>
 			<parameter name="timeout">
 				<para>If specified, the calling channel will be hung up after the specified number of seconds.
-				Otherwise, this application will wait until the calling channel hangs up.</para>
+				Otherwise, this application will wait until the caller hangs up.</para>
 			</parameter>
 		</syntax>
 		<description>
-			<para>This application will indicate the busy condition to the calling channel.</para>
+			<para>Send a signal to the caller's equipment to indicate that the callee's telephone
+			is already in use.</para>
 		</description>
 		<see-also>
 			<ref type="application">Congestion</ref>
@@ -187,7 +211,7 @@
 	</application>
 	<application name="Congestion" language="en_US">
 		<synopsis>
-			Indicate the Congestion condition.
+			Ask caller's equipment to play the circuit congestion tone.
 		</synopsis>
 		<syntax>
 			<parameter name="timeout">
@@ -196,7 +220,9 @@
 			</parameter>
 		</syntax>
 		<description>
-			<para>This application will indicate the congestion condition to the calling channel.</para>
+			<para>Send a signal to the caller's equipment to indicate that the call
+			did not go through.  Generally, the caller's equipment will play a fast busy signal
+			to the caller.</para>
 		</description>
 		<see-also>
 			<ref type="application">Busy</ref>
@@ -211,23 +237,56 @@
 		</synopsis>
 		<syntax argsep="?">
 			<parameter name="day_condition" required="true">
-				<argument name="times" required="true" />
-				<argument name="weekdays" required="true" />
-				<argument name="mdays" required="true" />
-				<argument name="months" required="true" />
-				<argument name="timezone" required="false" />
+				<argument name="hours" required="true">
+					<para>Ranges of times of day during which the condition should be true.
+					Times are specified in HH:MM format with the hour in 24 hour format.
+					Ranges will wrap through midnight, so <literal>17:00-09:00</literal>
+					means any time between five in the afternoon and nine the next morning.
+					Multiple ranges may be separated by <literal>&amp;</literal>, so
+					<literal>09:00-12:00&amp;13:00-17:00</literal> might mean "business
+					hours with a lunch break at noon".</para>
+				</argument>
+				<argument name="weekdays" required="true">
+					<para>Days of the week when the condition should be true. You may
+					use 0 for Sunday and so on or you may used the first three letters
+					of the English name of the day. Multiple acceptable ranges may be
+					specified, separated by <literal>&amp;</literal>.</para>
+				</argument>
+				<argument name="mdays" required="true">
+					<para>The days of the month during which the condition should be true.
+					Ranges such as <literal>25-5</literal> cover the end of one month
+					and the beginning of the next. Multiple acceptable ranges are
+					separated by <literal>&amp;</literal>.</para>
+				</argument>
+				<argument name="months" required="true">
+					<para>Months during which condition should be true.
+					You may use 0 for January and so on your you may use the first three
+					letters of the English name for the month. Ranges may span the of the
+					year. Multiple acceptable ranges may be separted by <literal>&amp;</literal>.</para>
+				</argument>
+				<argument name="timezone" required="false">
+					<para>Time zone in which rules are expressed</para>
+				</argument>
 			</parameter>
 			<parameter name="appname" required="true" hasparams="optional">
 				<argument name="appargs" required="true" />
 			</parameter>
 		</syntax>
 		<description>
-			<para>This application will execute the specified dialplan application, with optional
-			arguments, if the current time matches the given time specification.</para>
+			<para>If the current time of day meets all of the specified
+			conditions, then execute the specified application with the
+			specified arguments (if any).</para>
+
+			<para>The conditions are evaluated by obtaining the current time and date
+			from the system clock, converting them to the specified time zone (if
+			specified) and then verifying that the hour of the day, the day of the
+			week, the day of the month, and the month all fall within the acceptable
+			range or ranges. If you do not wish to specify a particular condition, 
+			such as the month, use <literal>*</literal>.</para>
+
 		</description>
 		<see-also>
-			<ref type="application">Exec</ref>
-			<ref type="application">TryExec</ref>
+			<ref type="application">GotoIfTime</ref>
 		</see-also>
 	</application>
 	<application name="Goto" language="en_US">
@@ -240,21 +299,26 @@
 			<parameter name="priority" required="true" />
 		</syntax>
 		<description>
-			<para>This application will set the current context, extension, and priority in the channel structure.
-			After it completes, the pbx engine will continue dialplan execution at the specified location.
-			If no specific <replaceable>extension</replaceable>, or <replaceable>extension</replaceable> and
-			<replaceable>context</replaceable>, are specified, then this application will
-			just set the specified <replaceable>priority</replaceable> of the current extension.</para>
-			<para>At least a <replaceable>priority</replaceable> is required as an argument, or the goto will
-			return a <literal>-1</literal>,	and the channel and call will be terminated.</para>
-			<para>If the location that is put into the channel information is bogus, and asterisk cannot
-			find that location in the dialplan, then the execution engine will try to find and execute the code in
-			the <literal>i</literal> (invalid) extension in the current context. If that does not exist, it will try to execute the
-			<literal>h</literal> extension. If either or neither the <literal>h</literal> or <literal>i</literal> extensions
-			have been defined, the channel is hung up, and the execution of instructions on the channel is terminated.
-			What this means is that, for example, you specify a context that does not exist, then
-			it will not be possible to find the <literal>h</literal> or <literal>i</literal> extensions,
-			and the call will terminate!</para>
+			<para>Jump unconditionally to a new location in the dialplan.
+			The parameters <replaceable>context</replaceable> and
+			<replaceable>extension</replaceable> are optional. If they
+			are omitted, the context or extension will remain unchanged.</para>
+
+			<para>If the require argument <replaceable>priority</replaceable>
+			is omitted, <literal>Goto</literal> will return <literal>-1</literal>,
+			which will terminate the call.</para>
+
+			<para>If Asterisk cannot find the target extension in the
+			dialplan, then the execution engine will try to find and
+			execute the code in the <literal>i</literal> (invalid)
+			extension in the new context. If that does not exist, it
+			will try to execute the <literal>h</literal> extension in the
+			new context. Neither the <literal>h</literal> nor the
+			<literal>i</literal> extension exists in the new context, the
+			channel is hung up, and the execution of dialplan instructions
+			ends. This means that if one jumps to a non-existent context,
+			the call will terminate immediately.</para>
+
 		</description>
 		<see-also>
 			<ref type="application">GotoIf</ref>
@@ -279,19 +343,12 @@
 			</parameter>
 		</syntax>
 		<description>
-			<para>This application will set the current context, extension, and priority in the channel structure
-			based on the evaluation of the given condition. After this application completes, the
-			pbx engine will continue dialplan execution at the specified location in the dialplan.
-			The labels are specified with the same syntax as used within the Goto application.
-			If the label chosen by the condition is omitted, no jump is performed, and the execution passes to the
-			next instruction. If the target location is bogus, and does not exist, the execution engine will try
-			to find and execute the code in the <literal>i</literal> (invalid) extension in the current context.
-			If that does not exist, it will try to execute the <literal>h</literal> extension.
-			If either or neither the <literal>h</literal> or <literal>i</literal> extensions have been defined,
-			the channel is hung up, and the execution of instructions on the channel is terminated.
-			Remember that this command can set the current context, and if the context specified
-			does not exist, then it will not be able to find any 'h' or 'i' extensions there, and
-			the channel and call will both be terminated!.</para>
+			<para>If the given condition is true, jump to the point in the dialplan 
+			specified after the <literal>?</literal>. If the condition is false and
+			an alternative location is specified after <literal>:</literal>, jump there.
+			The target locations are specified as for <literal>Goto</literal>.</para>
+			<para>This application handles a non-existent target extension in the same
+			way as <literal>Goto</literal> does.</para>
 		</description>
 		<see-also>
 			<ref type="application">Goto</ref>
@@ -306,7 +363,7 @@
 		</synopsis>
 		<syntax argsep="?">
 			<parameter name="condition" required="true">
-				<argument name="times" required="true" />
+				<argument name="hours" required="true" />
 				<argument name="weekdays" required="true" />
 				<argument name="mdays" required="true" />
 				<argument name="months" required="true" />
@@ -318,24 +375,23 @@
 			</parameter>
 		</syntax>
 		<description>
-			<para>This application will set the context, extension, and priority in the channel structure
-			based on the evaluation of the given time specification. After this application completes,
-			the pbx engine will continue dialplan execution at the specified location in the dialplan.
-			If the current time is within the given time specification, the channel will continue at
-			<replaceable>labeliftrue</replaceable>. Otherwise the channel will continue at <replaceable>labeliffalse</replaceable>.
-			If the label chosen by the condition is omitted, no jump is performed, and execution passes to the next
-			instruction. If the target jump location is bogus, the same actions would be taken as for <literal>Goto</literal>.
-			Further information on the time specification can be found in examples
-			illustrating how to do time-based context includes in the dialplan.</para>
+			<para>If the current time of day is within one of the specified ranges,
+			jump to the location specified after the <literal>?</literal>, otherwise
+			jump to the location specified after the <literal>:</literal> (if any).</para>
+			<para>See <literal>ExecIfTime</literal> to learn how to specify acceptable 
+			dates and times.</para>
+			<para>This application handles a non-existent target extension in the same way as
+			<literal>Goto</literal> does.</para>
 		</description>
 		<see-also>
+			<ref type="application">ExecIfTime</ref>
 			<ref type="application">GotoIf</ref>
 			<ref type="function">IFTIME</ref>
 		</see-also>
 	</application>
 	<application name="ImportVar" language="en_US">
 		<synopsis>
-			Import a variable from a channel into a new variable.
+			Read a variable from a different channel.
 		</synopsis>
 		<syntax argsep="=">
 			<parameter name="newvar" required="true" />
@@ -345,11 +401,11 @@
 			</parameter>
 		</syntax>
 		<description>
-			<para>This application imports a <replaceable>variable</replaceable> from the specified
-			<replaceable>channel</replaceable> (as opposed to the current one) and stores it as a variable
-			(<replaceable>newvar</replaceable>) in the current channel (the channel that is calling this
-			application). Variables created by this application have the same inheritance properties as those
-			created with the <literal>Set</literal> application.</para>
+			<para>Read the value of a channel variable from another channel.  Reads
+			<replaceable>variable</replaceable> from channel <replaceable>channel</replaceable>
+			and stores it in <replaceable>newvar</replaceable> (in the calling channel).
+			Variables created by this application have the same inheritance properties as those
+			created by the <literal>Set</literal> application.</para>
 		</description>
 		<see-also>
 			<ref type="application">Set</ref>
@@ -357,7 +413,7 @@
 	</application>
 	<application name="Hangup" language="en_US">
 		<synopsis>
-			Hang up the calling channel.
+			Terminate the call.
 		</synopsis>
 		<syntax>
 			<parameter name="causecode">
@@ -366,7 +422,14 @@
 			</parameter>
 		</syntax>
 		<description>
-			<para>This application will hang up the calling channel.</para>
+			<para>Hang up the channel from which it is executed.
+			This will end the call.  If there is an <literal>h</literal> extension in the
+			current context, execution will jump to it.</para>
+			<para>If the channel's communications technology supports it, the cause code is
+			passed to the other end. Cause codes can be used to indicate to the calling
+			switch whether the call went through and if not, why not.  The cause codes
+			are defined by the PRI standard. Channels of types other than PRI may translate
+			these codes to their own standards.</para>
 		</description>
 		<see-also>
 			<ref type="application">Answer</ref>
@@ -380,15 +443,14 @@
 		</synopsis>
 		<syntax>
 			<parameter name="n">
-				<para>If specified, then Incomplete will not attempt to answer the channel first.</para>
-				<note><para>Most channel types need to be in Answer state in order to receive DTMF.</para></note>
+				<para>Do not attempt to answer the channel first.</para>
+				<note><para>Channels of some types need to be in the Answer state in order to receive DTMF.</para></note>
 			</parameter>
 		</syntax>
 		<description>
-			<para>Signals the PBX routines that the previous matched extension is incomplete
-			and that further input should be allowed before matching can be considered
-			to be complete.  Can be used within a pattern match when certain criteria warrants
-			a longer match.</para>
+			<para>Informs the PBX routines that the matched extension is incomplete
+			and that further input should be collected in order to obtain a longer match.
+			</para>
 		</description>
 	</application>
 	<application name="NoOp" language="en_US">
@@ -397,12 +459,13 @@
 		</synopsis>
 		<syntax>
 			<parameter name="text">
-				<para>Any text provided can be viewed at the Asterisk CLI.</para>
+				<para>Parameter is unused, but variable and function interpolations will be expanded.</para>
 			</parameter>
 		</syntax>
 		<description>
-			<para>This application does nothing. However, it is useful for debugging purposes.</para>
-			<para>This method can be used to see the evaluations of variables or functions without having any effect.</para>
+			<para>This application does nothing. However, it is useful for debugging purposes since it can
+			be used to expand variables, functions, and expressions and display the result on the Asterisk
+			console (provided <literal>verbose</literal> is set high enough).</para>
 		</description>
 		<see-also>
 			<ref type="application">Verbose</ref>
@@ -411,20 +474,30 @@
 	</application>
 	<application name="Proceeding" language="en_US">
 		<synopsis>
-			Indicate proceeding.
+			Indicate that call routing is proceeding.
 		</synopsis>
 		<syntax />
 		<description>
-			<para>This application will request that a proceeding message be provided to the calling channel.</para>
+			<para>Inform the device at the remote end of the channel that the
+			call request has been received and Asterisk is attempting to route
+			the call. This may motivate the device at the remote end to give
+			Asterisk more time to finish routing the call.</para>
 		</description>
 	</application>
 	<application name="Progress" language="en_US">
 		<synopsis>
-			Indicate progress.
+			Indicate intention to play call-progress sounds.
 		</synopsis>
 		<syntax />
 		<description>
-			<para>This application will request that in-band progress information be provided to the calling channel.</para>
+			<para>Inform the channel driver that we intend to play sounds without
+			answering the call. This is generally done either before playing a message
+			indicating that the call did not go through or to ask the caller
+			to be patient.  The channel driver will attempt to bring up an audio
+			channel all the way back to the caller's telephone.</para>
+			<para>Remember that serveral of the applications which play sounds
+			will answer an unanswered channel if not prevented from doing so 
+			by the use of the <literal>n</literal> option.</para>
 		</description>
 		<see-also>
 			<ref type="application">Busy</ref>
@@ -435,14 +508,18 @@
 	</application>
 	<application name="RaiseException" language="en_US">
 		<synopsis>
-			Handle an exceptional condition.
+			Handle an exceptional (and likely unwelcome) condition.
 		</synopsis>
 		<syntax>
 			<parameter name="reason" required="true" />
 		</syntax>
 		<description>
-			<para>This application will jump to the <literal>e</literal> extension in the current context, setting the
-			dialplan function EXCEPTION(). If the <literal>e</literal> extension does not exist, the call will hangup.</para>
+			<para>Jump to the <literal>e</literal> extension in the current context.
+			The dialplan function EXCEPTION() can then be used to retrieve
+			<replaceable>reason</replaceable> and to learn the location in the
+			dialplan where the exception was raised.</para>
+			<para>If the <literal>e</literal> extension does not exist, the call
+			will be hung up.</para>
 		</description>
 		<see-also>
 			<ref type="function">Exception</ref>
@@ -471,7 +548,8 @@
 			</parameter>
 		</syntax>
 		<description>
-			<para>This application causes the Call Data Record to be reset.</para>
+			<para>This application causes the Call Data Record to be reset to the state
+			it was in at the start of the call.</para>
 		</description>
 		<see-also>
 			<ref type="application">ForkCDR</ref>
@@ -480,11 +558,18 @@
 	</application>
 	<application name="Ringing" language="en_US">
 		<synopsis>
-			Indicate ringing tone.
+			Ask caller's equipment to play ringback.
 		</synopsis>
 		<syntax />
 		<description>
-			<para>This application will request that the channel indicate a ringing tone to the user.</para>
+			<para>Send a signal to the caller's equipment to indicate that
+			the callee's telephone has begun to ring.  The caller's equipment will likely
+			begin to play a ringback tone in the caller's earpiece.</para>
+			<para>Indicating ringing in this manner has some advantages over opening the audio
+			channel with <literal>Progress</literal> and using <literal>Playtones</literal>.  For
+			one, the caller will hear the ringing signal used in his part of the world.  Secondly,
+			there is no need to consume resources to open an audio channel for a call that may never be
+			answered.</para>
 		</description>
 		<see-also>
 			<ref type="application">Busy</ref>
@@ -495,14 +580,14 @@
 	</application>
 	<application name="SayAlpha" language="en_US">
 		<synopsis>
-			Say Alpha.
+			Say the name of each letter in a string.
 		</synopsis>
 		<syntax>
 			<parameter name="string" required="true" />
 		</syntax>
 		<description>
-			<para>This application will play the sounds that correspond to the letters of the
-			given <replaceable>string</replaceable>.</para>
+			<para>Play the names of the letters in the given <replaceable>string</replaceable>.
+			For example, if <replaceable>string</replaceable> is "abc", it will say "aye bee see".</para>
 		</description>
 		<see-also>
 			<ref type="application">SayDigits</ref>
@@ -513,14 +598,16 @@
 	</application>
 	<application name="SayDigits" language="en_US">
 		<synopsis>
-			Say Digits.
+			Say the name of each digit in a string.
 		</synopsis>
 		<syntax>
 			<parameter name="digits" required="true" />
 		</syntax>
 		<description>
-			<para>This application will play the sounds that correspond to the digits of
-			the given number. This will use the language that is currently set for the channel.</para>
+			<para>Play the names of the digits in
+			the given number. This will use the language that is currently set for the channel.
+			For example, if <replaceable>digits</replaceable> is <literal>123</literal>, it will
+			say "one two three".</para>
 		</description>
 		<see-also>
 			<ref type="application">SayAlpha</ref>
@@ -531,16 +618,18 @@
 	</application>
 	<application name="SayNumber" language="en_US">
 		<synopsis>
-			Say Number.
+			Read digits as base-ten number.
 		</synopsis>
 		<syntax>
 			<parameter name="digits" required="true" />
 			<parameter name="gender" />
 		</syntax>
 		<description>
-			<para>This application will play the sounds that correspond to the given <replaceable>digits</replaceable>.
-			Optionally, a <replaceable>gender</replaceable> may be specified. This will use the language that is currently
-			set for the channel. See the LANGUAGE() function for more information on setting the language for the channel.</para>
+			<para>Say the number as if it had been written out in words.  For example,
+			if <replaceable>digits</replaceable> is "123", it will say "one hundred twenty three".</para>
+			<para>Optionally, a <replaceable>gender</replaceable> may be specified. This will use the
+			language that is currently set for the channel. See the LANGUAGE() function for more
+			information on setting the language for the channel.</para>
 		</description>
 		<see-also>
 			<ref type="application">SayAlpha</ref>
@@ -557,7 +646,7 @@
 			<parameter name="string" required="true" />
 		</syntax>
 		<description>
-			<para>This application will play the sounds from the phonetic alphabet that correspond to the
+			<para>Play the sounds from the phonetic alphabet that correspond to the
 			letters in the given <replaceable>string</replaceable>.</para>
 		</description>
 		<see-also>
@@ -568,27 +657,26 @@
 	</application>
 	<application name="Set" language="en_US">
 		<synopsis>
-			Set channel variable or function value.
+			Set the value of a single channel variable or function.
 		</synopsis>
 		<syntax argsep="=">
 			<parameter name="name" required="true" />
 			<parameter name="value" required="true" />
 		</syntax>
 		<description>
-			<para>This function can be used to set the value of channel variables or dialplan functions.
-			When setting variables, if the variable name is prefixed with <literal>_</literal>,
-			the variable will be inherited into channels created from the current channel.
+			<para>This function can be used to set the value of channel variables or dialplan functions.</para>
+			<para>If the variable name is prefixed with <literal>_</literal>,
+			the variable will be inherited into immediate child channels of the current channel.
 			If the variable name is prefixed with <literal>__</literal>, the variable will be
 			inherited into channels created from the current channel and all children channels.</para>
-			<note><para>If (and only if), in <filename>/etc/asterisk/asterisk.conf</filename>, you have
-			a <literal>[compat]</literal> category, and you have <literal>app_set = 1.6</literal> under that,then
-			the behavior of this app changes, and does not strip surrounding quotes from the right hand side as
-			it did previously in 1.4. The <literal>app_set = 1.6</literal> is only inserted if <literal>make samples</literal>
-			is executed, or if users insert this by hand into the <filename>asterisk.conf</filename> file.
-			The advantages of not stripping out quoting, and not caring about the separator characters (comma and vertical bar)
-			were sufficient to make these changes in 1.6. Confusion about how many backslashes would be needed to properly
-			protect separators and quotes in various database access strings has been greatly
-			reduced by these changes.</para></note>
+			<note><para>The behavior of <literal>Set</literal> potentially changes in Asterisk version
+			1.6. If this new behavior is enabled, the Set will no longer strip surrounding quotes from
+			the right hand side of the equals sign. The previous behavior was confusing because it
+			often required multiple levels of backslashes to protected quote marks and commas.</para>
+			<para>This new behavior will be enabled only if you add <literal>app_set = 1.6</literal> to
+			the <literal>[compat]</literal> section of <filename>asterisk.conf</filename> or if you 
+			use the sample <filename>asterisk.conf</filename> installed by <literal>make config</literal>.</para>
+			</note>
 		</description>
 		<see-also>
 			<ref type="application">MSet</ref>
@@ -599,7 +687,7 @@
 	</application>
 	<application name="MSet" language="en_US">
 		<synopsis>
-			Set channel variable(s) or function value(s).
+			Set the value of one or more channel variables or functions.
 		</synopsis>
 		<syntax>
 			<parameter name="set1" required="true" argsep="=">
@@ -612,16 +700,16 @@
 			</parameter>
 		</syntax>
 		<description>
-			<para>This function can be used to set the value of channel variables or dialplan functions.
-			When setting variables, if the variable name is prefixed with <literal>_</literal>,
-			the variable will be inherited into channels created from the current channel
-			If the variable name is prefixed with <literal>__</literal>, the variable will be
-			inherited into channels created from the current channel and all children channels.
-			MSet behaves in a similar fashion to the way Set worked in 1.2/1.4 and is thus
-			prone to doing things that you may not expect. For example, it strips surrounding
-			double-quotes from the right-hand side (value). If you need to put a separator
-			character (comma or vert-bar), you will need to escape them by inserting a backslash
-			before them. Avoid its use if possible.</para>
+			<para>This function can be used to set the value of channel one or more 
+			channel variables or dialplan functions. Channel variables may be made
+			inheritable by child and grandchild channels using the same conventions 
+			as for <literal>Set</literal>.</para>
+			<para>MSet behaves much as Set did in 1.2/1.4. It allows setting more than
+			one variable or function. It strips surrounding double-quotes from the value.
+			If you need to put a separator character (comma or vert-bar), you will need
+			to escape them by inserting a backslash before them. Since some of these
+			behaviours can catch one by surprise, the use of <literal>MSet</literal>
+			is not recommended.</para>
 		</description>
 		<see-also>
 			<ref type="application">Set</ref>
@@ -629,13 +717,22 @@
 	</application>
 	<application name="SetAMAFlags" language="en_US">
 		<synopsis>
-			Set the AMA Flags.
+			Set AMA flags in CDR record.
 		</synopsis>
 		<syntax>
-			<parameter name="flag" />
+			<parameter name="flag">
+				<para>Possible values are
+				<literal>default</literal>,
+				<literal>omit</literal>,
+				<literal>billing</literal>, and
+				<literal>documentation</literal>.
+				</para>
+			</parameter>
 		</syntax>
 		<description>
-			<para>This application will set the channel's AMA Flags for billing purposes.</para>
+			<para>Set the AMA (Automated Message Accounting) field in the CDR
+			record. This field indicates whether the billing system should
+			include the call in the customer's bill.</para>
 		</description>
 		<see-also>
 			<ref type="function">CDR</ref>
@@ -643,16 +740,17 @@
 	</application>
 	<application name="Wait" language="en_US">
 		<synopsis>
-			Waits for some time.
+			Pauses unconditionally for the indicated number of seconds.
 		</synopsis>
 		<syntax>
 			<parameter name="seconds" required="true">
-				<para>Can be passed with fractions of a second. For example, <literal>1.5</literal> will ask the
-				application to wait for 1.5 seconds.</para>
+				<para>Duration of pause in seconds.  May include a fractional part after a decimal point.</para>
 			</parameter>
 		</syntax>
 		<description>
-			<para>This application waits for a specified number of <replaceable>seconds</replaceable>.</para>
+			<para>This application pauses dialplan execution for the specified number of
+			<replaceable>seconds</replaceable>. It is often used to insert audible 
+			pauses when playing messages to the caller.</para>
 		</description>
 	</application>
 	<application name="WaitExten" language="en_US">
@@ -660,9 +758,11 @@
 			Waits for an extension to be entered.
 		</synopsis>
 		<syntax>
-			<parameter name="seconds">
-				<para>Can be passed with fractions of a second. For example, <literal>1.5</literal> will ask the
-				application to wait for 1.5 seconds.</para>
+			<parameter name="timeout">
+				<para>Maximum amount of time to wait for the caller start entering 
+				the desired extension.
+				May include a decimal point. For example, <literal>1.5</literal> will
+				give the caller up to 1.5 seconds to respond.</para>
 			</parameter>
 			<parameter name="options">
 				<optionlist>
@@ -676,8 +776,14 @@
 			</parameter>
 		</syntax>
 		<description>
-			<para>This application waits for the user to enter a new extension for a specified number
-			of <replaceable>seconds</replaceable>.</para>
+			<para>Give the caller a chance to enter a new extension. If a valid extension 
+			is entered, execution jumps to it immediately.</para>
+			<para>The caller will have up to <replaceable>timeout</replaceable> seconds
+			to enter the first digit. If no digit is entered, execution continues at
+			the next priority.</para>
+			<para>If an invalid extension is entered or the interdigit timeout expires
+			while only a partial extension has been entered, then execution jumps
+			to the <literal>i</literal> extension in the current context.</para>
 			<xi:include xpointer="xpointer(/docs/application[@name='Macro']/description/warning[2])" />
 		</description>
 		<see-also>
