more cleanups to application descriptions

git-svn-id: http://svn.digium.com/svn/asterisk/trunk@7072 f38db490-d61c-443f-a65b-d21fe96a405b

6 files changed, 168 insertions, 125 deletions

diff --git a/apps/app_controlplayback.c b/apps/app_controlplayback.c
index 6cd577d7f..dab0c156c 100755
--- a/apps/app_controlplayback.c
+++ b/apps/app_controlplayback.c
@@ -48,18 +48,22 @@ static const char *app = "ControlPlayback";
 static const char *synopsis = "Play a file with fast forward and rewind";
 
 static const char *descrip = 
-"ControlPlayback(filename[|skipms[|ffchar[|rewchar[|stopchar[|pausechar[|restartchar[|option]]]]]]]):\n"
-"  Plays back a given filename (do not put extension). Options may also\n"
-"  be included following a pipe symbol.  You can use * and # to rewind and\n"
-"  fast forward the playback specified. If 'stopchar' is added the file will\n"
-"  terminate playback when 'stopchar' is pressed. If 'restartchar' is added, the file\n"
-"  will restart when 'restartchar' is pressed.\n"
-"  The option string may contain the following character:\n"
-"       'j' -- jump to +101 priority if the file requested isn't found.\n"
-"  This application sets the following channel variable upon completion:\n"
-"     CPLAYBACKSTATUS       The status of the attempt as a text string, one of\n"
-"             SUCCESS | USERSTOPPED | ERROR\n"
-"  Example:  exten => 1234,1,ControlPlayback(file|4000|*|#|1|0|5)\n\n";
+"  ControlPlayback(file[|skipms[|ff[|rew[|stop[|pause[|restart|options]]]]]]]):\n"
+"This application will play back the given filename. By default, the '*' key\n"
+"can be used to rewind, and the '#' key can be used to fast-forward.\n"
+"Parameters:\n"
+"  skipms  - This is number of milliseconds to skip when rewinding or\n"
+"            fast-forwarding.\n"
+"  ff      - Fast-forward when this DTMF digit is received.\n"
+"  rew     - Rewind when this DTMF digit is received.\n"
+"  stop    - Stop playback when this DTMF digit is received.\n"
+"  pause   - Pause playback when this DTMF digit is received.\n"
+"  restart - Restart playback when this DTMF digit is received.\n"
+"Options:\n"
+"  j - Jump to priority n+101 if the requested file is not found.\n"
+"This application sets the following channel variable upon completion:\n"
+"  CPLAYBACKSTATUS -  This variable contains the status of the attempt as a text\n"
+"                     string, one of: SUCCESS | USERSTOPPED | ERROR\n";
 
 STANDARD_LOCAL_USER;
 
diff --git a/apps/app_curl.c b/apps/app_curl.c
index ebe664e6e..5cf4b167d 100755
--- a/apps/app_curl.c
+++ b/apps/app_curl.c
@@ -48,10 +48,14 @@ static char *app = "Curl";
 static char *synopsis = "Load an external URL";
 
 static char *descrip = 
-"  Curl(URL[|postdata]): Requests the URL.  Mainly used for signalling\n"
-"external applications of an event.  Curl will fail on fatal errors. \n"
-"Argument specified treated as POST data.  Also sets CURL variable with the\n"
-"resulting page.\n";
+"  Curl(URL[|postdata]): This application will request the specified URL.\n"
+"It is mainly used for signalling external applications of an event.\n"
+"Parameters:\n"
+"  URL      - This is the external URL to request.\n"
+"  postdata - This information will be treated as POST data.\n"
+"This application will set the following variable:\n"
+"  CURL - This variable will contain the resulting page.\n"
+"This application has been deprecated in favor of the CURL function.\n";
 
 STANDARD_LOCAL_USER;
 
diff --git a/apps/app_cut.c b/apps/app_cut.c
index 718583ec7..4eb6e552e 100755
--- a/apps/app_cut.c
+++ b/apps/app_cut.c
@@ -42,29 +42,32 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 /* Maximum length of any variable */
 #define MAXRESULT	1024
 
-static char *tdesc = "String manipulation";
+static char *tdesc = "Cut out information from a string";
 
 static char *app_cut = "Cut";
 
-static char *cut_synopsis = "Splits a variable's content using the specified delimiter";
+static char *cut_synopsis = "Splits a variable's contents using the specified delimiter";
 
 static char *cut_descrip =
-"Usage: Cut(newvar=varname,delimiter,fieldspec)\n"
+"  Cut(newvar=varname,delimiter,fieldspec): This applicaiton will split the\n"
+"contents of a variable based on the given delimeter and store the result in\n"
+"a new variable.\n"
+"Parameters:\n"
 "  newvar    - new variable created from result string\n"
 "  varname   - variable you want cut\n"
 "  delimiter - defaults to '-'\n"
 "  fieldspec - number of the field you want (1-based offset)\n"
-"            may also be specified as a range (with -)\n"
-"            or group of ranges and fields (with &)\n" 
-"  The process with complete on success or fail on hangup or error\n";
+"              may also be specified as a range (with -)\n"
+"              or group of ranges and fields (with &)\n"
+"This application has been deprecated in favor of the CUT function.\n";
 
 static char *app_sort = "Sort";
 static char *app_sort_synopsis = "Sorts a list of keywords and values";
 static char *app_sort_descrip =
-"   Sort(<newvar>=<key1>:<val1>[,<key2>:<val2>[[...],<keyN>:<valN>]])\n"
-"Sorts the list provided by using the value as a float to order the list of\n"
-"keywords in ascending order.  Sets the variable provided to the list of\n"
-"sorted keywords. \n";
+"  Sort(newvar=key1:val1[,key2:val2[[...],keyN:valN]]): This application will\n"
+"sort the list provided in ascending order. The result will be stored in the\n"
+"specified variable name.\n"
+"  This applicaiton has been deprecated in favor of the SORT function.\n";
 
 STANDARD_LOCAL_USER;
 
diff --git a/apps/app_datetime.c b/apps/app_datetime.c
index 4adb646ff..b10ad97e6 100755
--- a/apps/app_datetime.c
+++ b/apps/app_datetime.c
@@ -46,8 +46,7 @@ static char *app = "DateTime";
 static char *synopsis = "Say the date and time";
 
 static char *descrip = 
-"  DateTime():  Says the current date and time.  Terminates on hangup or\n"
-"completion.\n";
+"  DateTime(): This application will say the current date and time.\n";
 
 STANDARD_LOCAL_USER;
 
diff --git a/apps/app_db.c b/apps/app_db.c
index 659f9686e..245c8d3ca 100755
--- a/apps/app_db.c
+++ b/apps/app_db.c
@@ -45,27 +45,30 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 #include "asterisk/lock.h"
 #include "asterisk/options.h"
 
-static char *tdesc = "Database access functions for Asterisk extension logic";
+static char *tdesc = "Database Access Functions";
 
 static char *g_descrip =
-	"  DBget(varname=family/key[|options]): Retrieves a value from the Asterisk\n"
-	"database and stores it in the given variable.\n"
-	"  The option string may contain the following character:\n"
-	"       'j' -- jump to +101 priority if the requested family/key isn't found.\n"
-	"  This application sets the following channel variable upon completion:\n"
-	"     DBGETSTATUS       The status of the attempt as a text string, one of\n"
-	"             FOUND | NOTFOUND \n";
+"  DBget(varname=family/key[|options]): This application will retrieve a value\n"
+"from the Asterisk database and store it in the given variable.\n"
+"  Options:\n"
+"    j - Jump to priority n+101 if the requested family/key isn't found.\n"
+"  This application sets the following channel variable upon completion:\n"
+"    DBGETSTATUS - This variable will contain the status of the attempt\n"
+"                  FOUND | NOTFOUND \n"
+"  This application has been deprecated in favor of the DB function.\n";
 
 static char *p_descrip =
-	"  DBput(family/key=value): Stores the given value in the Asterisk\n"
-	"database.\n";
+"  DBput(family/key=value): This application will store the given value in the\n"
+"specified location in the Asterisk database.\n"
+"  This application has been deprecated in favor of the DB function.\n";
 
 static char *d_descrip =
-	"  DBdel(family/key): Deletes a key from the Asterisk database.\n";
+"  DBdel(family/key): This applicaiton will delete a key from the Asterisk\n"
+"database.\n";
 
 static char *dt_descrip =
-	"  DBdeltree(family[/keytree]): Deletes a family or keytree from the Asterisk\n"
-	"database.\n";
+"  DBdeltree(family[/keytree]): This application will delete a family or keytree\n"
+"from the Asterisk database\n";
 
 static char *g_app = "DBget";
 static char *p_app = "DBput";
diff --git a/apps/app_dial.c b/apps/app_dial.c
index 4851e98ab..97196bc8c 100755
--- a/apps/app_dial.c
+++ b/apps/app_dial.c
@@ -63,97 +63,127 @@ static char *app = "Dial";
 static char *synopsis = "Place a call and connect to the current channel";
 
 static char *descrip =
-"  Dial(Technology/resource[&Technology2/resource2...][|timeout][|options][|URL]):\n"
-"Requests one or more channels and places specified outgoing calls on them.\n"
-"As soon as a channel answers, the Dial app will answer the originating\n"
-"channel (if it needs to be answered) and will bridge a call with the channel\n"
-"which first answered. All other calls placed by the Dial app will be hung up.\n"
-"If a timeout is not specified, the Dial application will wait indefinitely\n"
-"until either one of the called channels answers, the user hangs up, or all\n"
-"channels return busy or error. The dialplan will continue execution if the\n"
-"the calls cannot be placed, or if the timeout expires.\n"
-"  For the Privacy and Screening Modes, the DIALSTATUS variable will be set to DONTCALL, \n"
-"if the called party chooses to send the calling party to the 'Go Away' script, and \n"
-"the DIALSTATUS variable will be set to TORTURE, if the called party wants to send the caller to \n"
-"the TORTURE scripts\n"
-"  This application will report normal termination if the originating channel hangs up, or if the\n"
-"call is bridged and either of the parties in the bridge ends the call.\n"
-"The option string may contain zero or more of the following characters:\n"
-"	'A(x)' -- play an announcement to the called party, using x as file\n"
-"	'C' -- reset call detail record for this call.\n"
-"	'd' -- allow the calling user to dial a 1 digit extension while waiting for a call to\n"
-"		be answered exiting to that extension if it exists in the context defined by\n"
-"		${EXITCONTEXT} or the current context.\n"
-"	'D([called][:calling])'  -- Send DTMF strings *after* called party has answered, but before the\n"
-"		call gets bridged. The 'called' DTMF string is sent to the called party, and the\n"
-"		'calling' DTMF string is sent to the calling party. Both parameters can be used alone.\n"  	
-"	'f' -- Forces callerid to be set as the extension of the line \n"
-"             making/redirecting the outgoing call. For example, some PSTNs\n"
-"             don't allow callerid set to numbers that are not assigned to you.\n"
-"	'g' -- goes on in context if the destination channel hangs up\n"
-"	'G(context^exten^pri)' -- If the call is answered transfer both parties to the specified exten.\n"
-"	'h' -- allow callee to hang up by hitting *.\n"
-"	'H' -- allow caller to hang up by hitting *.\n"
-"	'j' -- Jump to n+101 if all of the channels were busy.\n"
-"	'L(x[:y][:z])' -- Limit the call to 'x' ms warning when 'y' ms are left\n"
-"		repeated every 'z' ms) Only 'x' is required, 'y' and 'z' are optional.\n"
-"             The following special variables are optional:\n"
-"             * LIMIT_PLAYAUDIO_CALLER    yes|no (default yes)\n"
-"                                         Play sounds to the caller.\n"
-"             * LIMIT_PLAYAUDIO_CALLEE    yes|no\n"
-"                                         Play sounds to the callee.\n"
-"             * LIMIT_TIMEOUT_FILE        File to play when time is up.\n"
-"             * LIMIT_CONNECT_FILE        File to play when call begins.\n"
-"             * LIMIT_WARNING_FILE        File to play as warning if 'y' is defined.\n"
-"                        'timeleft' is a special sound macro to auto-say the time \n"
-"                        left and is the default.\n"
-"	'm[(class)]' -- provide hold music to the calling party until answered (optionally\n"
-"                      with the specified class.\n"
-"	'M(x[^arg])' -- Executes the macro (x with ^ delim arg list) upon connect of the call.\n"
-"                      Also, the macro can set the MACRO_RESULT variable to do the following:\n"
-"                     -- ABORT - Hangup both legs of the call.\n"
-"                     -- CONGESTION - Behave as if line congestion was encountered.\n"
-"                     -- BUSY - Behave as if a busy signal was encountered. (n+101 only if those options are set)\n"
-"                     -- CONTINUE - Hangup the called party and continue on in the dialplan.\n"
-"                     -- GOTO:<context>^<exten>^<priority> - Transfer the call.\n"
-"	'n' -- modifier for screen/privacy mode. No intros are to be saved in the priv-callerintros dir.\n"
-"	'N' -- modifier for screen/privacy mode. if callerID is present, do not screen the call.\n"
-"	'o' -- Original (inbound) Caller*ID should be placed on the outbound leg of the call\n" 
-"             instead of using the destination extension (old style asterisk behavior)\n"
-"	'p' -- screening mode.  Basically Privacy mode without memory.\n"
-"	'P[(x)]' -- privacy mode, using 'x' as database if provided, or the extension is used if not provided.\n"
-"	'r' -- indicate ringing to the calling party, pass no audio until answered.\n"
-"	'S(x)' -- hangup the call after x seconds AFTER called party picked up\n"  	
-"	't' -- allow the called user to transfer the calling user by hitting the key sequence defiend in features.conf.\n"
-"	'T' -- allow the calling user to transfer the call by hitting the key sequence defined in features.conf.\n"
-"	'w' -- allow the called user to write the conversation to disk via Monitor\n"
-"	'W' -- allow the calling user to write the conversation to disk via Monitor\n\n"
-"  In addition to transferring the call, a call may be parked and then picked\n"
-"up by another user.\n"
+"  Dial(Technology/resource[&Tech2/resource2...][|timeout][|options][|URL]):\n"
+"This applicaiton will place calls to one or more specified channels. As soon\n"
+"as one of the requested channels answers, the originating channel will be\n"
+"answered, if it has not already been answered. These two channels will then\n"
+"be active in a bridged call. All other channels that were requested will then\n"
+"be hung up.\n"
+"  Unless there is a timeout specified, the Dial application will wait\n"
+"indefinitely until one of the called channels answers, the user hangs up, or\n"
+"if all of the called channels are busy or unavailable. Dialplan executing will\n"
+"continue if no requested channels can be called, or if the timeout expires.\n"
+"  This application sets the following channel variables upon completion:\n"
+"    DIALEDTIME   - This is the time from dialing a channel until when it\n"
+"                   answers.\n" 
+"    ANSWEREDTIME - This is the amount of time for actual call.\n"
+"    DIALSTATUS   - This is the status of the call:\n"
+"                   CHANUNAVAIL | CONGESTION | NOANSWER | BUSY | ANSWER | CANCEL\n" 
+"                   DONTCALL | TORTURE\n"
+"  For the Privacy and Screening Modes, the DIALSTATUS variable will be set to\n"
+"DONTCALL if the called party chooses to send the calling party to the 'Go Away'\n"
+"script. The DIALSTATUS variable will be set to TORTURE if the called party\n"
+"wants to send the caller to the 'torture' script.\n"
+"  This application will report normal termination if the originating channel\n"
+"hangs up, or if the call is bridged and either of the parties in the bridge\n"
+"ends the call.\n"
 "  The optional URL will be sent to the called party if the channel supports it.\n"
 "  If the OUTBOUND_GROUP variable is set, all peer channels created by this\n"
-"  application will be put into that group (as in SetGroup).\n"
-"  This application sets the following channel variables upon completion:\n"
-"      DIALEDTIME    Time from dial to answer\n" 
-"      ANSWEREDTIME  Time for actual call\n"
-"      DIALSTATUS    The status of the call as a text string, one of\n"
-"             CHANUNAVAIL | CONGESTION | NOANSWER | BUSY | ANSWER | CANCEL | DONTCALL | TORTURE\n"
-"";
+"application will be put into that group (as in Set(GROUP()=...).\n"
+"  Options:\n"
+"    A(x) - Play an announcement to the called party, using 'x' as the file.\n"
+"    C    - Reset the CDR for this call.\n"
+"    d    - Allow the calling user to dial a 1 digit extension while waiting for\n"
+"           a call to be answered. Exit to that extension if it exists in the\n"
+"           current context, or the context defined in the EXITCONTEXT variable,\n"
+"           if it exists.\n"
+"    D([called][:calling]) - Send the specified DTMF strings *after* the called\n"
+"           party has answered, but before the call gets bridged. The 'called'\n"
+"           DTMF string is sent to the called party, and the 'calling' DTMF\n"
+"           string is sent to the calling party. Both parameters can be used\n"
+"           alone.\n"  	
+"    f    - Force the callerid of the *calling* channel to be set as the\n"
+"           extension associated with the channel using a dialplan 'hint'.\n"
+"           For example, some PSTNs do not allow CallerID to be set to anything\n"
+"           other than the number assigned to the caller.\n"
+"    g    - Proceed with dialplan execution at the current extension if the\n"
+"           destination channel hangs up.\n"
+"    G(context^exten^pri) - If the call is answered, transfer both parties to\n"
+"           the specified priority. Optionally, an extension, or extension and\n"
+"           context may be specified. Otherwise, the current extension is used.\n"
+"    h    - Allow the called party to hang up by sending the '*' DTMF digit.\n"
+"    H    - Allow the calling party to hang up by hitting the '*' DTMF digit.\n"
+"    j    - Jump to priority n+101 if all of the requested channels were busy.\n"
+"    L(x[:y][:z]) - Limit the call to 'x' ms. Play a warning when 'y' ms are\n"
+"           left. Repeat the warning every 'z' ms. The following special\n"
+"           variables can be used with this option:\n"
+"           * LIMIT_PLAYAUDIO_CALLER   yes|no (default yes)\n"
+"                                      Play sounds to the caller.\n"
+"           * LIMIT_PLAYAUDIO_CALLEE   yes|no\n"
+"                                      Play sounds to the callee.\n"
+"           * LIMIT_TIMEOUT_FILE       File to play when time is up.\n"
+"           * LIMIT_CONNECT_FILE       File to play when call begins.\n"
+"           * LIMIT_WARNING_FILE       File to play as warning if 'y' is defined.\n"
+"                                      The default is to say the time remaining.\n"
+"    m([class]) - Provide hold music to the calling party until a requested\n"
+"           channel answers. A specific MusicOnHold class can be\n"
+"           specified.\n"
+"    M(x[^arg]) - Execute the Macro for the *called* channel before connecting\n"
+"           to the calling channel. Arguments can be specified to the Macro\n"
+"           using '^' as a delimeter. The Macro can set the variable\n"
+"           MACRO_RESULT to specify the following actions after the Macro is\n" 
+"           finished executing.\n"
+"           * ABORT        Hangup both legs of the call.\n"
+"           * CONGESTION   Behave as if line congestion was encountered.\n"
+"           * BUSY         Behave as if a busy signal was encountered. This will also\n"
+"                          have the application jump to priority n+101 if the\n"
+"                          'j' option is set.\n"
+"           * CONTINUE     Hangup the called party and allow the calling party\n"
+"                          to continue dialplan execution at the next priority.\n"
+"           * GOTO:<context>^<exten>^<priority> - Transfer the call to the\n"
+"                          specified priority. Optionally, an extension, or\n"
+"                          extension and priority can be specified.\n"
+"    n    - This option is a modifier for the screen/privacy mode. It specifies\n"
+"           that no introductions are to be saved in the priv-callerintros\n"
+"           directory.\n"
+"    N    - This option is a modifier for the screen/privacy mode. It specifies\n"
+"           that if callerID is present, do not screen the call.\n"
+"    o    - Specify that the CallerID that was present on the *calling* channel\n"
+"           be set as the CallerID on the *called* channel. This was the\n"
+"           behavior of Asterisk 1.0 and earlier.\n"
+"    p    - This option enables screening mode. This is basically Privacy mode\n"
+"           without memory.\n"
+"    P([x]) - Enable privacy mode. Use 'x' as the family/key in the database if\n"
+"           it is provided. The current extension is used if a database\n"
+"           family/key is not specified.\n"
+"    r    - Indicate ringing to the calling party. Pass no audio to the calling\n"
+"           party until the called channel has answered.\n"
+"    S(x) - Hang up the call after 'x' seconds *after* the called party has\n"
+"           answered the call.\n"  	
+"    t    - Allow the called party to transfer the calling party by sending the\n"
+"           DTMF sequence defiend in features.conf.\n"
+"    T    - Allow the calling party to transfer the called party by sending the\n"
+"           DTMF sequence defined in features.conf.\n"
+"    w    - Allow the called party to enable recording of the call by sending\n"
+"           the DTMF sequence defined for one-touch recording in features.conf.\n"
+"    W    - Allow the calling party to enable recording of the call by sending\n"
+"           the DTMF sequence defined for one-touch recording in features.conf.\n";
 
 /* RetryDial App by Anthony Minessale II <anthmct@yahoo.com> Jan/2005 */
 static char *rapp = "RetryDial";
 static char *rsynopsis = "Place a call, retrying on failure allowing optional exit extension.";
 static char *rdescrip =
-"  RetryDial(announce|sleep|loops|Technology/resource[&Technology2/resource2...][|timeout][|options][|URL]):\n"
-"Attempt to place a call.  If no channel can be reached, play the file defined by 'announce'\n"
-"waiting 'sleep' seconds to retry the call.  If the specified number of attempts matches \n"
-"'loops' the call will continue in the dialplan.  If 'loops' is set to 0, the call will retry endlessly.\n\n"
-"While waiting, a 1 digit extension may be dialed.  If that extension exists in either\n"
-"the context defined in ${EXITCONTEXT} or the current one, The call will transfer\n"
-"to that extension immmediately.\n\n"
-"All arguments after 'loops' are passed directly to the Dial() application.\n"
-"";
-
+"  RetryDial(announce|sleep|retries|dialargs): This application will attempt to\n"
+"place a call using the normal Dial application. If no channel can be reached,\n"
+"the 'annonce' file will be played. Then, it will wait 'sleep' number of\n"
+"seconds before retying the call. After 'retires' number of attempts, the\n"
+"calling channel will continue at the next priority in the dialplan. If the\n"
+"'retries' setting is set to 0, this application will retry endlessly.\n"
+"  While waiting to retry a call, a 1 digit extension may be dialed. If that\n"
+"extension exists in either the context defined in ${EXITCONTEXT} or the current\n"
+"one, The call will jump to that extension immediately.\n"
+"  The 'dialargs' are specified in the same format that arguments are provided\n"
+"to the Dial application.\n";
 
 enum {
 	OPT_ANNOUNCE = (1 << 0),