--- a/src/ChangeLog	Fri Apr 01 18:53:14 2011 -0700
+++ b/src/ChangeLog	Fri Apr 01 20:19:18 2011 -0700
@@ -1,3 +1,8 @@
+2011-04-01  Rik  <octave@nomad.inbox5.com>
+
+	* data.cc (diag): Remove archaic 3-input argument form of function.
+	Add all calling forms of function to docstring.
+
 2011-04-01  Rik  <octave@nomad.inbox5.com>
 
 	* DLD-FUNCTIONS/filter.cc: Fix orientation of initial conditions vector

--- a/src/data.cc	Fri Apr 01 18:53:14 2011 -0700
+++ b/src/data.cc	Fri Apr 01 20:19:18 2011 -0700
@@ -1224,7 +1224,10 @@
 
 DEFUN (diag, args, ,
   "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {} diag (@var{v}, @var{k})\n\
+@deftypefn  {Built-in Function} {@var{M} =} diag (@var{v})\n\
+@deftypefnx {Built-in Function} {@var{M} =} diag (@var{v}, @var{k})\n\
+@deftypefnx {Built-in Function} {@var{v} =} diag (@var{M})\n\
+@deftypefnx {Built-in Function} {@var{v} =} diag (@var{M}, @var{k})\n\
 Return a diagonal matrix with vector @var{v} on diagonal @var{k}.  The\n\
 second argument is optional.  If it is positive, the vector is placed on\n\
 the @var{k}-th super-diagonal.  If it is negative, it is placed on the\n\
@@ -1261,20 +1264,6 @@
       else
         retval = args(0).diag(k);
     }
-  else if (nargin == 3)
-    {
-      octave_value arg0 = args(0);
-      if (arg0.ndims () == 2 && (args(0).rows () == 1 || args(0).columns () == 1))
-        {
-          octave_idx_type m = args(1).int_value (), n = args(2).int_value ();
-          if (! error_state)
-            retval = arg0.diag ().resize (dim_vector (m, n));
-          else
-            error ("diag: invalid dimensions");
-        }
-      else
-        error ("diag: V must be a vector");
-    }
   else
     print_usage ();
 
@@ -1292,6 +1281,7 @@
 %!assert(diag ([1, 0, 0; 0, 2, 0; 0, 0, 3]), [1; 2; 3]);
 %!assert(diag ([0, 1, 0, 0; 0, 0, 2, 0; 0, 0, 0, 3; 0, 0, 0, 0], 1), [1; 2; 3]);
 %!assert(diag ([0, 0, 0, 0; 1, 0, 0, 0; 0, 2, 0, 0; 0, 0, 3, 0], -1), [1; 2; 3]);
+%!assert(diag (ones(1, 0), 2), zeros (2));
 
 %!assert(full (diag (single([1; 2; 3]))), single([1, 0, 0; 0, 2, 0; 0, 0, 3]));
 %!assert(diag (single([1; 2; 3]), 1), single([0, 1, 0, 0; 0, 0, 2, 0; 0, 0, 0, 3; 0, 0, 0, 0]));
@@ -1314,6 +1304,7 @@
 %!assert(diag (int8([0, 0, 0, 0; 1, 0, 0, 0; 0, 2, 0, 0; 0, 0, 3, 0]), -1), int8([1; 2; 3]));
 
 %!error <Invalid call to diag.*> diag ();
+%!error <Invalid call to diag.*> diag (ones(3, 1),0,1);
 
  */
 

--- a/test/ChangeLog	Fri Apr 01 18:53:14 2011 -0700
+++ b/test/ChangeLog	Fri Apr 01 20:19:18 2011 -0700
@@ -1,3 +1,8 @@
+2011-04-01  Rik  <octave@nomad.inbox5.com>
+
+	* test_diag_perm.m: Update diag tests to reflect removal of archaic
+	3-input form of diag().
+
 2011-03-18  Rik  <octave@nomad.inbox5.com>
 
 	* test_parser.m: Add operatore precedence tests.

--- a/test/test_diag_perm.m	Fri Apr 01 18:53:14 2011 -0700
+++ b/test/test_diag_perm.m	Fri Apr 01 20:19:18 2011 -0700
@@ -160,9 +160,9 @@
 %! n = 7;
 %! mn = min (m, n);
 %! d1 = rand (mn, 1) + I () * rand (mn, 1);
-%! D1 = diag (d1, m, n);
+%! D1 = resize (diag (d1), m, n);
 %! d2 = rand (mn, 1);
-%! D2 = diag (d2, m, n);
+%! D2 = resize (diag (d2), m, n);
 %! D1D2 = D1 + D2;
 %! assert (typeinfo (D1D2), "complex diagonal matrix");
 %! assert (diag (D1D2), d1 + d2);
@@ -176,7 +176,7 @@
 %! n = 6;
 %! mn = min (m, n);
 %! d = rand (mn, 1);
-%! D = diag (d, m, n);
+%! D = resize (diag (d), m, n);
 %! Dslice = D (1:(m-3), 1:(n-2));
 %! assert (typeinfo (Dslice), "diagonal matrix");
 
@@ -218,7 +218,7 @@
 %! n = 8;
 %! A = sprand (n, n, .5);
 %! scalefact = rand (n-2, 1);
-%! Dr = diag (scalefact, n, n-2);
+%! Dr = resize (diag (scalefact), n, n-2);
 %! assert (full (Dr \ A), Dr \ full(A))
 
 ## sparse inverse column scaling with a zero factor
@@ -236,7 +236,7 @@
 %! n = 7;
 %! A = sprand (n, n, .5);
 %! scalefact = rand (1, n-2) + I () * rand(1, n-2);
-%! Dc = diag (scalefact, n-2, n);
+%! Dc = resize (diag (scalefact), n-2, n);
 %! assert (full (A / Dc), full(A) / Dc)
 
 ## adding sparse and diagonal stays sparse