clean up some application descriptions to use more gooder English

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

7 files changed, 74 insertions, 65 deletions

diff --git a/ChangeLog b/ChangeLog
index 4cf423db8..99041eaf1 100755
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2005-11-10  Russell Bryant <russell@digium.com>
+
+	* many files in apps/: Clean up some application descriptions. Make sure all descriptions in changed files are wrapped at 80 characters.
+
 2005-11-09  Russell Bryant <russell@digium.com>
 
 	* pbx.c: Clean up descriptions of built-in dialplan applications. Changes include clearer wording and not referring to return values.
diff --git a/apps/app_adsiprog.c b/apps/app_adsiprog.c
index 0d775877b..c5d7242ad 100755
--- a/apps/app_adsiprog.c
+++ b/apps/app_adsiprog.c
@@ -55,10 +55,8 @@ static char *synopsis = "Load Asterisk ADSI Scripts into phone";
 /* #define DUMP_MESSAGES */
 
 static char *descrip =
-"  ADSIProg(script): Programs an ADSI Phone with the given script.\n"
-"If none is specified, the default script is used.  The reprogramming\n"  
-"will complete successfully, except in cases where the device is  \n"
-"disconnected or hungup.\n";
+"  ADSIProg(script): This application programs an ADSI Phone with the given\n"
+"script. If nothing is specified, the default script (asterisk.adsi) is used.\n"
 
 STANDARD_LOCAL_USER;
 
diff --git a/apps/app_alarmreceiver.c b/apps/app_alarmreceiver.c
index 51419c806..7c36b60b8 100755
--- a/apps/app_alarmreceiver.c
+++ b/apps/app_alarmreceiver.c
@@ -73,13 +73,15 @@ static char *app = "AlarmReceiver";
 
 static char *synopsis = "Provide support for receving alarm reports from a burglar or fire alarm panel";
 static char *descrip =
-"Alarm receiver application for Asterisk. Only 1 signalling format is supported at this time:\n"
-"Ademco Contact ID. This application should be called whenever there is an alarm panel calling in\n"
-"to dump its events. The application will handshake with the alarm panel, and receive events,\n"
-"validate them, handshake them, and store them until the panel hangs up. Once the panel hangs up,\n"
-"the application will run the command line specified by the eventcmd setting in alarmreceiver.conf\n"
-"and pipe the events to the standard input of the application. Alarmreceiver.conf also contains settings\n"
-"for DTMF timing, and for the loudness of the acknowledgement tones.\n";
+"  AlarmReceiver(): Only 1 signalling format is supported at this time: Ademco\n"
+"Contact ID. This application should be called whenever there is an alarm\n"
+"panel calling in to dump its events. The application will handshake with the\n"
+"alarm panel, and receive events, validate them, handshake them, and store them\n"
+"until the panel hangs up. Once the panel hangs up, the application will run the\n"
+"system command specified by the eventcmd setting in alarmreceiver.conf and pipe\n"
+"the events to the standard input of the application. The configuration file also\n"
+"contains settings for DTMF timing, and for the loudness of the acknowledgement\n" 
+"tones.\n";
 
 /* Config Variables */
 
diff --git a/apps/app_authenticate.c b/apps/app_authenticate.c
index a3f5f91c9..583c5f4d3 100755
--- a/apps/app_authenticate.c
+++ b/apps/app_authenticate.c
@@ -49,26 +49,24 @@ static char *app = "Authenticate";
 static char *synopsis = "Authenticate a user";
 
 static char *descrip =
-"  Authenticate(password[|options]): Requires a user to enter a"
-"given password in order to continue execution.  If the\n"
-"password begins with the '/' character, it is interpreted as\n"
-"a file which contains a list of valid passwords (1 per line).\n"
-"an optional set of opions may be provided by concatenating any\n"
-"of the following letters:\n"
-"     a - Set account code to the password that is entered\n"
-"     d - Interpret path as database key, not literal file\n"
-"     j - Support jumping to n+101\n"
-"     m - Interpret path as a file which contains a list of\n"
-"         account codes and password hashes delimited with ':'\n"
-"         one per line. When password matched, corresponding\n"
-"         account code will be set\n"
-"     r - Remove database key upon successful entry (valid with 'd' only)\n"
-"\n"
-"When using a database key, the value associated with the key can be\n"
-"anything.  Users have three attempts to authenticate before the line is \n"
-"hungup.  If the passsword is invalid, and the 'j' flag is specified, \n"
-"and priority n+101 exists, the call would be sent to the n+101 priority \n"
-"and executed \n";
+"  Authenticate(password[|options]): This application asks the caller to enter a\n"
+"given password in order to continue dialplan execution. If the password begins\n"
+"with the '/' character, it is interpreted as a file which contains a list of\n"
+"valid passwords, listed 1 password per line in the file.\n"
+"  When using a database key, the value associated with the key can be anything.\n"
+"Users have three attempts to authenticate before the channel is hung up. If the\n"
+"passsword is invalid, the 'j' option is specified, and priority n+101 exists,\n"
+"dialplan execution will continnue at this location.\n"
+"  Options:\n"
+"     a - Set the channels' account code to the password that is entered\n"
+"     d - Interpret the given path as database key, not a literal file\n"
+"     j - Support jumping to n+101 if authentication fails\n"
+"     m - Interpret the given path as a file which contains a list of account\n"
+"         codes and password hashes delimited with ':', listed one per line in\n"
+"         the file. When one of the passwords is matched, the channel will have\n"
+"         its account code set to the corresponding account code in the file.\n"
+"     r - Remove the database key upon successful entry (valid with 'd' only)\n"
+;
 
 STANDARD_LOCAL_USER;
 
diff --git a/apps/app_cdr.c b/apps/app_cdr.c
index 4f87898d1..501bfc79b 100755
--- a/apps/app_cdr.c
+++ b/apps/app_cdr.c
@@ -34,11 +34,14 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 #include "asterisk/pbx.h"
 
 
-static char *tdesc = "Make sure asterisk doesn't save CDR for a certain call";
+static char *tdesc = "Tell Asterisk to not maintain a CDR for the current call";
+
+static char *nocdr_descrip = 
+"  NoCDR(): This application will tell Asterisk not to maintain a CDR for the\n"
+"current call.\n";
 
-static char *nocdr_descrip = "NoCDR(): makes sure there won't be any CDR written for a certain call";
 static char *nocdr_app = "NoCDR";
-static char *nocdr_synopsis = "Make sure asterisk doesn't save CDR for a certain call";
+static char *nocdr_synopsis = "Tell Asterisk to not maintain a CDR for the current call";
 
 STANDARD_LOCAL_USER;
 
diff --git a/apps/app_chanisavail.c b/apps/app_chanisavail.c
index acdc4d9f8..a2b1dbe0b 100755
--- a/apps/app_chanisavail.c
+++ b/apps/app_chanisavail.c
@@ -44,26 +44,22 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 #include "asterisk/devicestate.h"
 #include "asterisk/options.h"
 
-static char *tdesc = "Check if channel is available";
+static char *tdesc = "Check channel availability";
 
 static char *app = "ChanIsAvail";
 
-static char *synopsis = "Check if channel is available";
+static char *synopsis = "Check channel availability;
 
 static char *descrip = 
-"  ChanIsAvail(Technology/resource[&Technology2/resource2...][|option]): \n"
-"Checks if any of the requested channels are available.  \n"
-"If any of the requested channels are available, the dialplan will continue and:\n"
-"  ${AVAILCHAN} will be set to the name of the available channel\n"
-"  ${AVAILORIGCHAN} is the canonical channel name that was used to create the channel\n"
-"  ${AVAILSTATUS} is the status code for the channel\n"
-"If the option 's' is specified (state), will consider channel unavailable\n"
-"when the channel is in use at all, even if it can take another call.\n"
-"If none of the requested channels are available, then:\n"
-"  if the option 'j' is specified (jump), the application will jump to n+101\n"
-"    if it exists, otherwise the call will terminate\n"
-"  if the option 'j' is not specified the dialplan will continue and\n"
-"    ${AVAILCHAN} will be empty\n";
+"  ChanIsAvail(Technology/resource[&Technology2/resource2...][|options]): \n"
+"This application will check to see if any of the specified channels are\n"
+"available. The following variables will be set by this application:\n"
+"  ${AVAILCHAN}     - the name of the available channel, if one exists\n"
+"  ${AVAILORIGCHAN} - the canonical channel name that was used to create the channel\n"
+"  ${AVAILSTATUS}   - the status code for the available channel\n"
+"  Options:\n"
+"    s - Consider the channel unavailable if the channel is in use at all\n"
+"    j - Support jumping to priority n+101 if no channel is available\n";
 
 STANDARD_LOCAL_USER;
 
diff --git a/apps/app_chanspy.c b/apps/app_chanspy.c
index 4e96d8f6d..375f49eff 100755
--- a/apps/app_chanspy.c
+++ b/apps/app_chanspy.c
@@ -51,23 +51,31 @@ AST_MUTEX_DEFINE_STATIC(modlock);
 #define ALL_DONE(u, ret) LOCAL_USER_REMOVE(u); return ret;
 #define get_volfactor(x) x ? ((x > 0) ? (1 << x) : ((1 << abs(x)) * -1)) : 0
 
-static const char *synopsis = "Tap into any type of asterisk channel and listen to audio";
+static const char *synopsis = "Listen to the audio of an active channel\n";
 static const char *app = "ChanSpy";
-static const char *desc = "   Chanspy([<scanspec>][|<options>])\n\n"
-"Valid Options:\n"
-" - b: bridged, only spy on channels involved in a bridged call.\n"
-" - g(grp): enforce group.  Match only calls where their ${SPYGROUP} is 'grp'.\n"
-" - q: quiet, don't announce channels beep, etc.\n"
-" - r[(basename)]: Record session to monitor spool dir (with optional basename, default is 'chanspy')\n\n"
-" - v([-4..4]): adjust the initial volume. (negative is quieter)\n"
-"If <scanspec> is specified, only channel names *beginning* with that string will be scanned.\n"
-"('all' or an empty string are also both valid <scanspec>)\n\n"
-"While Spying:\n\n"
-"Dialing # cycles the volume level.\n"
-"Dialing * will stop spying and look for another channel to spy on.\n"
-"Dialing a series of digits followed by # builds a channel name to append to <scanspec>\n"
-"(e.g. run Chanspy(Agent) and dial 1234# while spying to jump to channel Agent/1234)\n\n"
-"";
+static const char *desc = 
+"  ChanSpy([chanprefix][|options]): This application is used to listen to the\n"
+"audio from an active Asterisk channel. This includes the audio coming in and\n"
+"out of the channel being spied on. If the 'chanprefix' parameter is specified,\n"
+"only channels beginning with this string will be spied upon.\n"
+"  While Spying, the following actions may be performed:\n"
+"    - Dialing # cycles the volume level.\n"
+"    - Dialing * will stop spying and look for another channel to spy on.\n"
+"    - Dialing a series of digits followed by # builds a channel name to append\n"
+"      to 'chanprefix'. For example, executing ChanSpy(Agent) and then dialing\n"
+"      the digits '1234#' while spying will begin spying on the channel,\n"
+"      'Agent/1234'.
+"  Options:\n"
+"    b - Only spy on channels involved in a bridged call.\n"
+"    g(grp) - Match only channels where their ${SPYGROUP} variable is set to\n"
+"             'grp'.\n"
+"    q - Don't play a beep when beginning to spy on a channel.\n"
+"    r[(basename)] - Record the session to the monitor spool directory. An\n"
+"                    optional base for the filename may be specified. The\n"
+"                    default is 'chanspy'.\n"
+"    v([value]) - Adjust the initial volume in the range from -4 to 4. A\n"
+"                 negative value refers to a quieter setting.\n"
+;
 
 static const char *chanspy_spy_type = "ChanSpy";