# HG changeset patch
# User Rik <octave@nomad.inbox5.com>
# Date 1320170898 25200
# Node ID 990762e784fe8dbde23a04cd0d11d2310fdb8827
# Parent  7c0fcabd1a661bdc16cc391f60d611504de44515
Fix confusing interaction between @code macro and transpose operator (') in documentation (Bug #34661).

* octave.texi: Define new @xcode macro which expands to nothing in plain text
or Info output.  Expands to normal @code for all other formats.

* data.cc: Rephrase documentation for functions which have operator equivalents.
Use @xcode macro to mark the operator equivalent for these functions.

* expr.txi: Use @asis markup in table to prevent confusion between
transpose operator and @code expansion in Info format.

* mk_doc_cache.m, __makeinfo__.m: Add processing for new @xcode macro.

* krylov.m, etreeplot.m, lu.cc, schur.cc, symbfact.cc: Use new @xcode macro.

diff -r 7c0fcabd1a66 -r 990762e784fe doc/interpreter/expr.txi
--- a/doc/interpreter/expr.txi	Tue Nov 01 13:30:23 2011 -0400
+++ b/doc/interpreter/expr.txi	Tue Nov 01 11:08:18 2011 -0700
@@ -425,7 +425,7 @@
 The following arithmetic operators are available, and work on scalars
 and matrices.
 
-@table @code
+@table @asis
 @item @var{x} + @var{y}
 @opindex +
 Addition.  If both operands are matrices, the number of rows and columns
diff -r 7c0fcabd1a66 -r 990762e784fe doc/interpreter/mk_doc_cache.m
--- a/doc/interpreter/mk_doc_cache.m	Tue Nov 01 13:30:23 2011 -0400
+++ b/doc/interpreter/mk_doc_cache.m	Tue Nov 01 11:08:18 2011 -0700
@@ -48,6 +48,7 @@
 text = regexprep (text, "-\\*- texinfo -\\*-[ \t]*[\r\n]*", "");
 text = regexprep (text, '@seealso *\{([^}]*)\}', "See also: $1.");
 text = regexprep (text, '@nospell *\{([^}]*)\}', "$1");
+text = regexprep (text, '@xcode *\{([^}]*)\}', "$1");
 text = strrep (text, '@', "@@");
 
 ## Write data to temporary file for input to makeinfo
diff -r 7c0fcabd1a66 -r 990762e784fe doc/interpreter/octave.texi
--- a/doc/interpreter/octave.texi	Tue Nov 01 13:30:23 2011 -0400
+++ b/doc/interpreter/octave.texi	Tue Nov 01 11:08:18 2011 -0700
@@ -46,6 +46,20 @@
 \arg\
 @end macro
 
+@c The following macro works around a situation where the Info/plain text
+@c expansion of the @code{XXX} macro is `XXX'.  The use of the apostrophe
+@c can be confusing if the code segment itself ends with a transpose operator.
+@ifinfo
+@macro xcode{arg}
+\arg\
+@end macro
+@end ifinfo
+@ifnotinfo
+@macro xcode{arg}
+@code{\arg\}
+@end macro
+@end ifnotinfo
+
 @ifinfo
 @format
 START-INFO-DIR-ENTRY
diff -r 7c0fcabd1a66 -r 990762e784fe scripts/help/__makeinfo__.m
--- a/scripts/help/__makeinfo__.m	Tue Nov 01 13:30:23 2011 -0400
+++ b/scripts/help/__makeinfo__.m	Tue Nov 01 11:08:18 2011 -0700
@@ -101,6 +101,8 @@
 
   ## Handle @nospell macro
   text = regexprep (text, '@nospell *\{([^}]*)\}', "$1");
+  ## Handle @xcode macro
+  text = regexprep (text, '@xcode *\{([^}]*)\}', "$1");
 
   if (strcmpi (output_type, "texinfo"))
     status = 0;
diff -r 7c0fcabd1a66 -r 990762e784fe scripts/linear-algebra/krylov.m
--- a/scripts/linear-algebra/krylov.m	Tue Nov 01 13:30:23 2011 -0400
+++ b/scripts/linear-algebra/krylov.m	Tue Nov 01 11:08:18 2011 -0700
@@ -28,8 +28,8 @@
 ## Using Householder reflections to guard against loss of orthogonality.
 ##
 ## If @var{V} is a vector, then @var{h} contains the Hessenberg matrix
-## such that @code{a*u == u*h+rk*ek'}, in which @code{rk =
-## a*u(:,k)-u*h(:,k)}, and @code{ek'} is the vector
+## such that @xcode{a*u == u*h+rk*ek'}, in which @code{rk =
+## a*u(:,k)-u*h(:,k)}, and @xcode{ek'} is the vector
 ## @code{[0, 0, @dots{}, 1]} of length @code{k}.  Otherwise, @var{h} is
 ## meaningless.
 ##
diff -r 7c0fcabd1a66 -r 990762e784fe scripts/sparse/etreeplot.m
--- a/scripts/sparse/etreeplot.m	Tue Nov 01 13:30:23 2011 -0400
+++ b/scripts/sparse/etreeplot.m	Tue Nov 01 11:08:18 2011 -0700
@@ -20,7 +20,7 @@
 ## @deftypefn  {Function File} {} etreeplot (@var{A})
 ## @deftypefnx {Function File} {} etreeplot (@var{A}, @var{node_style}, @var{edge_style})
 ## Plot the elimination tree of the matrix @var{A} or
-## @code{@var{A}+@var{A}'} if @var{A} in not symmetric.  The optional
+## @xcode{@var{A}+@var{A}'} if @var{A} in not symmetric.  The optional
 ## parameters @var{node_style} and @var{edge_style} define the output
 ## style.
 ## @seealso{treeplot, gplot}
diff -r 7c0fcabd1a66 -r 990762e784fe src/DLD-FUNCTIONS/lu.cc
--- a/src/DLD-FUNCTIONS/lu.cc	Tue Nov 01 13:30:23 2011 -0400
+++ b/src/DLD-FUNCTIONS/lu.cc	Tue Nov 01 11:08:18 2011 -0700
@@ -616,7 +616,7 @@
 @end example\n\
 \n\
 @noindent\n\
-then a factorization of @code{@var{A}+@var{x}*@var{y}.'} can be obtained\n\
+then a factorization of @xcode{@var{A}+@var{x}*@var{y}.'} can be obtained\n\
 either as\n\
 \n\
 @example\n\
diff -r 7c0fcabd1a66 -r 990762e784fe src/DLD-FUNCTIONS/schur.cc
--- a/src/DLD-FUNCTIONS/schur.cc	Tue Nov 01 13:30:23 2011 -0400
+++ b/src/DLD-FUNCTIONS/schur.cc	Tue Nov 01 11:08:18 2011 -0700
@@ -307,7 +307,7 @@
 $U^{\\dagger} U$ is the identity matrix I.\n\
 @end tex\n\
 @ifnottex\n\
-@code{@var{UR} * @var{TR} * @var{UR}' = @var{U} * @var{T} * @var{U}'} and\n\
+@xcode{@var{UR} * @var{TR} * @var{UR}' = @var{U} * @var{T} * @var{U}'} and\n\
 @code{@var{U}' * @var{U}} is the identity matrix I.\n\
 @end ifnottex\n\
 \n\
diff -r 7c0fcabd1a66 -r 990762e784fe src/DLD-FUNCTIONS/symbfact.cc
--- a/src/DLD-FUNCTIONS/symbfact.cc	Tue Nov 01 13:30:23 2011 -0400
+++ b/src/DLD-FUNCTIONS/symbfact.cc	Tue Nov 01 11:08:18 2011 -0700
@@ -63,10 +63,10 @@
 Factorize @code{@var{S}' * @var{S}}.\n\
 \n\
 @item row\n\
-Factorize @code{@var{S} * @var{S}'}.\n\
+Factorize @xcode{@var{S} * @var{S}'}.\n\
 \n\
 @item lo\n\
-Factorize @code{@var{S}'}\n\
+Factorize @xcode{@var{S}'}\n\
 @end table\n\
 \n\
 @item mode\n\
diff -r 7c0fcabd1a66 -r 990762e784fe src/data.cc
--- a/src/data.cc	Tue Nov 01 13:30:23 2011 -0400
+++ b/src/data.cc	Tue Nov 01 11:08:18 2011 -0700
@@ -5288,7 +5288,7 @@
 DEFUN (uplus, args, ,
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} uplus (@var{x})\n\
-This function is equivalent to @w{@code{+ x}}.\n\
+This function and @w{@xcode{+ x}} are equivalent.\n\
 @end deftypefn")
 {
   return unary_op_defun_body (octave_value::op_uplus, args);
@@ -5297,7 +5297,7 @@
 DEFUN (uminus, args, ,
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} uminus (@var{x})\n\
-This function is equivalent to @w{@code{- x}}.\n\
+This function and @w{@xcode{- x}} are equivalent.\n\
 @end deftypefn")
 {
   return unary_op_defun_body (octave_value::op_uminus, args);
@@ -5306,13 +5306,8 @@
 DEFUN (transpose, args, ,
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} transpose (@var{x})\n\
-Return the transpose of @var{x}.  This function is equivalent to\n\
-@tex\n\
-@code{x.'}.\n\
-@end tex\n\
-@ifnottex\n\
-x.'.\n\
-@end ifnottex\n\
+Return the transpose of @var{x}.\n\
+This function and @xcode{x.'} are equivalent.\n\
 @seealso{ctranspose}\n\
 @end deftypefn")
 {
@@ -5344,14 +5339,8 @@
 DEFUN (ctranspose, args, ,
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} ctranspose (@var{x})\n\
-Return the complex conjugate transpose of @var{x}.  This function is\n\
-equivalent to\n\
-@tex\n\
-@code{x'}.\n\
-@end tex\n\
-@ifnottex\n\
-x'.\n\
-@end ifnottex\n\
+Return the complex conjugate transpose of @var{x}.\n\
+This function and @xcode{x'} are equivalent.\n\
 @seealso{transpose}\n\
 @end deftypefn")
 {
@@ -5427,7 +5416,7 @@
   "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {} plus (@var{x}, @var{y})\n\
 @deftypefnx {Built-in Function} {} plus (@var{x1}, @var{x2}, @dots{})\n\
-This function is equivalent to @w{@code{x + y}}.\n\
+This function and @w{@xcode{x + y}} are equivalent.\n\
 If more arguments are given, the summation is applied\n\
 cumulatively from left to right:\n\
 \n\
@@ -5446,7 +5435,7 @@
 DEFUN (minus, args, ,
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} minus (@var{x}, @var{y})\n\
-This function is equivalent to @w{@code{x - y}}.\n\
+This function and @w{@xcode{x - y}} are equivalent.\n\
 @seealso{plus}\n\
 @end deftypefn")
 {
@@ -5458,7 +5447,7 @@
 @deftypefn  {Built-in Function} {} mtimes (@var{x}, @var{y})\n\
 @deftypefnx {Built-in Function} {} mtimes (@var{x1}, @var{x2}, @dots{})\n\
 Return the matrix multiplication product of inputs.\n\
-This function is equivalent to @w{@code{x * y}}.\n\
+This function and @w{@xcode{x * y}} are equivalent.\n\
 If more arguments are given, the multiplication is applied\n\
 cumulatively from left to right:\n\
 \n\
@@ -5478,7 +5467,7 @@
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} mrdivide (@var{x}, @var{y})\n\
 Return the matrix right division of @var{x} and @var{y}.\n\
-This function is equivalent to @w{@code{x / y}}.\n\
+This function and @w{@xcode{x / y}} are equivalent.\n\
 @seealso{mldivide, rdivide}\n\
 @end deftypefn")
 {
@@ -5489,7 +5478,7 @@
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} mpower (@var{x}, @var{y})\n\
 Return the matrix power operation of @var{x} raised to the @var{y} power.\n\
-This function is equivalent to @w{@code{x ^ y}}.\n\
+This function and @w{@xcode{x ^ y}} are equivalent.\n\
 @seealso{power}\n\
 @end deftypefn")
 {
@@ -5500,7 +5489,7 @@
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} mldivide (@var{x}, @var{y})\n\
 Return the matrix left division of @var{x} and @var{y}.\n\
-This function is equivalent to @w{@code{x \\ y}}.\n\
+This function and @w{@xcode{x \\ y}} are equivalent.\n\
 @seealso{mrdivide, ldivide}\n\
 @end deftypefn")
 {
@@ -5570,7 +5559,7 @@
 @deftypefn  {Built-in Function} {} times (@var{x}, @var{y})\n\
 @deftypefnx {Built-in Function} {} times (@var{x1}, @var{x2}, @dots{})\n\
 Return the element-by-element multiplication product of inputs.\n\
-This function is equivalent to @w{@code{x .* y}}.\n\
+This function and @w{@xcode{x .* y}} are equivalent.\n\
 If more arguments are given, the multiplication is applied\n\
 cumulatively from left to right:\n\
 \n\
@@ -5590,7 +5579,7 @@
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} rdivide (@var{x}, @var{y})\n\
 Return the element-by-element right division of @var{x} and @var{y}.\n\
-This function is equivalent to @w{@code{x ./ y}}.\n\
+This function and @w{@xcode{x ./ y}} are equivalent.\n\
 @seealso{ldivide, mrdivide}\n\
 @end deftypefn")
 {
@@ -5602,7 +5591,7 @@
 @deftypefn {Built-in Function} {} power (@var{x}, @var{y})\n\
 Return the element-by-element operation of @var{x} raised to the\n\
 @var{y} power.\n\
-This function is equivalent to @w{@code{x .^ y}}.\n\
+This function and @w{@xcode{x .^ y}} are equivalent.\n\
 @seealso{mpower}\n\
 @end deftypefn")
 {
@@ -5613,7 +5602,7 @@
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} ldivide (@var{x}, @var{y})\n\
 Return the element-by-element left division of @var{x} and @var{y}.\n\
-This function is equivalent to @w{@code{x .\\ y}}.\n\
+This function and @w{@xcode{x .\\ y}} are equivalent.\n\
 @seealso{rdivide, mldivide}\n\
 @end deftypefn")
 {