--- a/src/DLD-FUNCTIONS/schur.cc	Sun Nov 21 17:31:10 1999 +0000
+++ b/src/DLD-FUNCTIONS/schur.cc	Tue Nov 23 19:07:18 1999 +0000
@@ -36,17 +36,212 @@
 #include "utils.h"
 
 DEFUN_DLD (schur, args, nargout,
-  "[U, S] = schur (A) or S = schur (A)\n\
-\n\
-or, for ordered Schur:\n\
+  "-*- texinfo -*-
+@deftypefn {Loadable Function} {@var{s} =} schur (@var{a})\n\
+@deftypefnx {Loadable Function} {[@var{u}, @var{s}] =} schur (@var{a}, @var{opt})\n\
+@cindex Schur decomposition\n\
+The Schur decomposition is used to compute eigenvalues of a\n\
+square matrix, and has applications in the solution of algebraic\n\
+Riccati equations in control (see @code{are} and @code{dare}).\n\
+@code{schur} always returns\n\
+@iftex\n\
+@tex\n\
+$S = U^T A U$\n\
+@end tex\n\
+@end iftex\n\
+@ifinfo\n\
+@code{s = u' * a * u}\n\
+@end ifinfo\n\
+where\n\
+@iftex\n\
+@tex\n\
+$U$\n\
+@end tex\n\
+@end iftex\n\
+@ifinfo\n\
+@code{u}\n\
+@end ifinfo\n\
+ is a unitary matrix\n\
+@iftex\n\
+@tex\n\
+($U^T U$ is identity)\n\
+@end tex\n\
+@end iftex\n\
+@ifinfo\n\
+(@code{u'* u} is identity)\n\
+@end ifinfo\n\
+and\n\
+@iftex\n\
+@tex\n\
+$S$\n\
+@end tex\n\
+@end iftex\n\
+@ifinfo\n\
+@code{s}\n\
+@end ifinfo\n\
+is upper triangular.  The eigenvalues of\n\
+@iftex\n\
+@tex\n\
+$A$ (and $S$)\n\
+@end tex\n\
+@end iftex\n\
+@ifinfo\n\
+@code{a} (and @code{s})\n\
+@end ifinfo\n\
+are the diagonal elements of\n\
+@iftex\n\
+@tex\n\
+$S$\n\
+@end tex\n\
+@end iftex\n\
+@ifinfo\n\
+@code{s}\n\
+@end ifinfo\n\
+If the matrix\n\
+@iftex\n\
+@tex\n\
+$A$\n\
+@end tex\n\
+@end iftex\n\
+@ifinfo\n\
+@code{a}\n\
+@end ifinfo\n\
+is real, then the real Schur decomposition is computed, in which the\n\
+matrix\n\
+@iftex\n\
+@tex\n\
+$U$\n\
+@end tex\n\
+@end iftex\n\
+@ifinfo\n\
+@code{u}\n\
+@end ifinfo\n\
+is orthogonal and\n\
+@iftex\n\
+@tex\n\
+$S$\n\
+@end tex\n\
+@end iftex\n\
+@ifinfo\n\
+@code{s}\n\
+@end ifinfo\n\
+is block upper triangular\n\
+with blocks of size at most\n\
+@iftex\n\
+@tex\n\
+$2\\times 2$\n\
+@end tex\n\
+@end iftex\n\
+@ifinfo\n\
+@code{2 x 2}\n\
+@end ifinfo\n\
+blocks along the diagonal.  The diagonal elements of\n\
+@iftex\n\
+@tex\n\
+$S$\n\
+@end tex\n\
+@end iftex\n\
+@ifinfo\n\
+@code{s}\n\
+@end ifinfo\n\
+(or the eigenvalues of the\n\
+@iftex\n\
+@tex\n\
+$2\\times 2$\n\
+@end tex\n\
+@end iftex\n\
+@ifinfo\n\
+@code{2 x 2}\n\
+@end ifinfo\n\
+blocks, when\n\
+appropriate) are the eigenvalues of\n\
+@iftex\n\
+@tex\n\
+$A$\n\
+@end tex\n\
+@end iftex\n\
+@ifinfo\n\
+@code{a}\n\
+@end ifinfo\n\
+and\n\
+@iftex\n\
+@tex\n\
+$S$.\n\
+@end tex\n\
+@end iftex\n\
+@ifinfo\n\
+@code{s}.\n\
+@end ifinfo\n\
 \n\
-  [U, S] = schur (A, TYPE) or S = schur (A, TYPE)\n\
-where TYPE is a string that begins with one of the following\n\
-characters:\n\
-\n\
-  A = continuous time poles\n\
-  D = discrete time poles\n\
-  U = unordered schur (default)")
+The eigenvalues are optionally ordered along the diagonal according to\n\
+the value of @code{opt}.  @code{opt = \"a\"} indicates that all\n\
+eigenvalues with negative real parts should be moved to the leading\n\
+block of\n\
+@iftex\n\
+@tex\n\
+$S$\n\
+@end tex\n\
+@end iftex\n\
+@ifinfo\n\
+@code{s}\n\
+@end ifinfo\n\
+(used in @code{are}), @code{opt = \"d\"} indicates that all eigenvalues\n\
+with magnitude less than one should be moved to the leading block of\n\
+@iftex\n\
+@tex\n\
+$S$\n\
+@end tex\n\
+@end iftex\n\
+@ifinfo\n\
+@code{s}\n\
+@end ifinfo\n\
+(used in @code{dare}), and @code{opt = \"u\"}, the default, indicates that\n\
+no ordering of eigenvalues should occur.  The leading\n\
+@iftex\n\
+@tex\n\
+$k$\n\
+@end tex\n\
+@end iftex\n\
+@ifinfo\n\
+@code{k}\n\
+@end ifinfo\n\
+columns of\n\
+@iftex\n\
+@tex\n\
+$U$\n\
+@end tex\n\
+@end iftex\n\
+@ifinfo\n\
+@code{u}\n\
+@end ifinfo\n\
+always span the\n\
+@iftex\n\
+@tex\n\
+$A$-invariant\n\
+@end tex\n\
+@end iftex\n\
+@ifinfo\n\
+@code{a}-invariant\n\
+@end ifinfo\n\
+subspace corresponding to the\n\
+@iftex\n\
+@tex\n\
+$k$\n\
+@end tex\n\
+@end iftex\n\
+@ifinfo\n\
+@code{k}\n\
+@end ifinfo\n\
+leading eigenvalues of\n\
+@iftex\n\
+@tex\n\
+$S$.\n\
+@end tex\n\
+@end iftex\n\
+@ifinfo\n\
+@code{s}.\n\
+@end ifinfo\n\
+@end deftypefn")
 {
   octave_value_list retval;