# HG changeset patch
# User Rik <rik@octave.org>
# Date 1344982659 25200
# Node ID 8593bed236f119816da3136dc8710d22905ff00d
# Parent  c7d466a02065fc54aa4c62dc58bd44a3d314652b
doc: Document escape character processing within single quotes for regexp, warning, error.

regexp.cc (regexp, regexprep): Add implementation note about doing
escape character processing within single quotes of pattern and
replacement string.

error.cc (warning, error): Add implementation note about doing
escape character processing when the number of input arguments
is greater than two.

diff -r c7d466a02065 -r 8593bed236f1 src/corefcn/regexp.cc
--- a/src/corefcn/regexp.cc	Tue Aug 14 13:57:44 2012 -0700
+++ b/src/corefcn/regexp.cc	Tue Aug 14 15:17:39 2012 -0700
@@ -596,10 +596,7 @@
 end (@code{$}) of the string.\n\
 @end table\n\
 \n\
-In addition, the following escaped characters have special meaning.  Note,\n\
-it is recommended to quote @var{pat} in single quotes, rather than double\n\
-quotes, to avoid the escape sequences being interpreted by Octave before\n\
-being passed to @code{regexp}.\n\
+In addition, the following escaped characters have special meaning.\n\
 \n\
 @table @code\n\
 @item \\b\n\
@@ -633,6 +630,12 @@
 Match any non-digit\n\
 @end table\n\
 \n\
+Implementation Note: For compatibility with @sc{matlab}, ordinary escape\n\
+sequences (e.g., \"\\n\" => newline) are processed in @var{pat}\n\
+regardless of whether @var{pat} has been defined within single quotes.  Use\n\
+a second backslash to stop interpolation of the escape sequence (e.g.,\n\
+\"\\\\n\") or use the @code{regexptranslate} function.\n\
+\n\
 The outputs of @code{regexp} default to the order given below\n\
 \n\
 @table @var\n\
@@ -1258,6 +1261,11 @@
 This option is present for compatibility but is ignored.\n\
 \n\
 @end table\n\
+\n\
+Implementation Note: For compatibility with @sc{matlab}, ordinary escape\n\
+sequences (e.g., \"\\n\" => newline) are processed in both @var{pat}\n\
+and @var{repstr} regardless of whether they were defined within single quotes.  Use a second backslash to stop interpolation of the escape sequence (e.g.,\n\
+\"\\\\n\") or use the @code{regexptranslate} function.\n\
 @seealso{regexp, regexpi, strrep}\n\
 @end deftypefn")
 {
diff -r c7d466a02065 -r 8593bed236f1 src/interpfcn/error.cc
--- a/src/interpfcn/error.cc	Tue Aug 14 13:57:44 2012 -0700
+++ b/src/interpfcn/error.cc	Tue Aug 14 15:17:39 2012 -0700
@@ -1068,6 +1068,14 @@
 error: nargin != 1\n\
 @end group\n\
 @end example\n\
+\n\
+Implementation Note: For compatibility with @sc{matlab}, escape\n\
+sequences (e.g., \"\\n\" => newline) are processed in @var{template}\n\
+regardless of whether @var{template} has been defined within single quotes\n\
+as long as there are two or more input arguments.\n\
+Use a second backslash to stop interpolation of the escape sequence (e.g.,\n\
+\"\\\\n\") or use the @code{regexptranslate} function.\n\
+@seealso{warning, lasterror}\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -1167,7 +1175,14 @@
 warning (\"error\");\n\
 @end group\n\
 @end example\n\
-@seealso{warning_ids}\n\
+\n\
+Implementation Note: For compatibility with @sc{matlab}, escape\n\
+sequences (e.g., \"\\n\" => newline) are processed in @var{template}\n\
+regardless of whether @var{template} has been defined within single quotes\n\
+as long as there are two or more input arguments.\n\
+Use a second backslash to stop interpolation of the escape sequence (e.g.,\n\
+\"\\\\n\") or use the @code{regexptranslate} function.\n\
+@seealso{warning_ids, lastwarn, error}\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -1553,7 +1568,7 @@
 \n\
 If @code{lasterror} is called with the argument \"reset\", all fields are\n\
 set to their default values.\n\
-@seealso{lasterr}\n\
+@seealso{lasterr, error, lastwarn}\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -1678,7 +1693,7 @@
 return the last error message and message identifier.  With one\n\
 argument, set the last error message to @var{msg}.  With two arguments,\n\
 also set the last message identifier.\n\
-@seealso{lasterror}\n\
+@seealso{lasterror, error, lastwarn}\n\
 @end deftypefn")
 {
   octave_value_list retval;
@@ -1722,10 +1737,14 @@
 
 DEFUN (lastwarn, args, nargout,
   "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {[@var{msg}, @var{msgid}] =} lastwarn (@var{msg}, @var{msgid})\n\
-Without any arguments, return the last warning message.  With one\n\
+@deftypefn  {Built-in Function} {[@var{msg}, @var{msgid}] =} lastwarn ()\n\
+@deftypefnx {Built-in Function} {} lastwarn (@var{msg})\n\
+@deftypefnx {Built-in Function} {} lastwarn (@var{msg}, @var{msgid})\n\
+Query or set the last warning message.  When called without input arguments,\n\
+return the last warning message and message identifier.  With one\n\
 argument, set the last warning message to @var{msg}.  With two arguments,\n\
 also set the last message identifier.\n\
+@seealso{warning, lasterror, lasterr}\n\
 @end deftypefn")
 {
   octave_value_list retval;