From: Tilghman Lesher <tilghman@meg.abyt.es>
Date: Tue, 7 Apr 2009 22:16:50 +0000 (+0000)
Subject: Fix Macro documentation to match current (and intended) behavior.
X-Git-Tag: 1.4.25-rc1~77
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=56e7ca00c1f56aef35b8d961d5ff1475168932aa;p=thirdparty%2Fasterisk.git

Fix Macro documentation to match current (and intended) behavior.
(See -dev mailing list)


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

diff --git a/apps/app_macro.c b/apps/app_macro.c
index eac1cc1573..af042913a8 100644
--- a/apps/app_macro.c
+++ b/apps/app_macro.c
@@ -61,17 +61,23 @@ static char *descrip =
 "will be returned at the location of the Goto.\n"
 "If ${MACRO_OFFSET} is set at termination, Macro will attempt to continue\n"
 "at priority MACRO_OFFSET + N + 1 if such a step exists, and N + 1 otherwise.\n"
-"Extensions: While a macro is being executed, it becomes the current context.\n"
-"            This means that if a hangup occurs, for instance, that the macro\n"
-"            will be searched for an 'h' extension, NOT the context from which\n"
-"            the macro was called. So, make sure to define all appropriate\n"
-"            extensions in your macro! (you can use 'catch' in AEL) \n"
 "WARNING: Because of the way Macro is implemented (it executes the priorities\n"
 "         contained within it via sub-engine), and a fixed per-thread\n"
 "         memory stack allowance, macros are limited to 7 levels\n"
 "         of nesting (macro calling macro calling macro, etc.); It\n"
-"         may be possible that stack-intensive applications in deeply nested macros\n"
-"         could cause asterisk to crash earlier than this limit.\n";
+"         may be possible that stack-intensive applications in deeply nested\n"
+"         macros could cause asterisk to crash earlier than this limit.\n"
+"NOTE: a bug existed in earlier versions of Asterisk that caused Macro not\n"
+"to reset its context and extension correctly upon exit.  This meant that\n"
+"the 'h' extension within a Macro sometimes would execute, when the dialplan\n"
+"exited while that Macro was running.  However, since this bug has been in\n"
+"Asterisk for so long, users started to depend upon this behavior.  Therefore,\n"
+"when a channel hangs up when in the midst of executing a Macro, the macro\n"
+"context will first be checked for an 'h' extension, followed by the main\n"
+"context from which the Macro was originally called.  This behavior in 1.4\n"
+"exists only for compatibility with earlier versions.  You are strongly\n"
+"encouraged to make use of the 'h' extension only in the context from which\n"
+"Macro was originally called.\n";
 
 static char *if_descrip =
 "  MacroIf(<expr>?macroname_a[|arg1][:macroname_b[|arg1]])\n"