--- a/doc/ChangeLog	Fri Mar 06 12:00:11 2009 +0100
+++ b/doc/ChangeLog	Fri Mar 06 13:42:24 2009 +0100
@@ -1,3 +1,7 @@
+2009-03-06  Jaroslav Hajek  <highegg@gmail.com>
+
+	* interpreter/diagperm.txi: Various improvements.
+
 2009-02-27  John W. Eaton  <jwe@octave.org>
 
 	* interpreter/set.txi (Sets): Don't document create_set.

--- a/doc/interpreter/diagperm.txi	Fri Mar 06 12:00:11 2009 +0100
+++ b/doc/interpreter/diagperm.txi	Fri Mar 06 13:42:24 2009 +0100
@@ -28,12 +28,14 @@
 @end menu
 
 @node Basic Usage
-@section The Creation and Manipulation of Diagonal and Permutation Matrices
+@section Creating and Manipulating Diagonal and Permutation Matrices
 
 A diagonal matrix is defined as a matrix that has zero entries outside the main diagonal;
 that is, 
 @iftex
+@tex
 $D_{ij} = 0$ if $i \neq j$
+@end tex
 @end iftex
 @ifnottex
 @code{D(i,j) == 0} if @code{i != j}.
@@ -46,8 +48,10 @@
 in each row and each column; all other elements are zero. That is, there exists a 
 permutation (vector) 
 @iftex
+@tex
 $p$ such that $P_{ij}=1$ if $j = p_i$ and
 $P_{ij}=0$ otherwise.  
+@end tex
 @end iftex
 @ifnottex
 @code{p} such that @code{P(i,j) == 1} if @code{j == p(i)} and 
@@ -69,16 +73,40 @@
 @subsection Creating Diagonal Matrices
 
 The most common and easiest way to create a diagonal matrix is using the built-in
-function @dfn{diag}. The expression @code{diag (@var{v})}, with @var{v} a vector,
+function @dfn{diag}. The expression @code{diag (v)}, with @var{v} a vector,
 will create a square diagonal matrix with elements on the main diagonal given
 by the elements of @var{v}, and size equal to the length of @var{v}.
-@code{diag (@var{v}, m, n)} can be used to construct a rectangular diagonal matrix.
+@code{diag (v, m, n)} can be used to construct a rectangular diagonal matrix.
 The result of these expressions will be a special diagonal matrix object, rather
 than a general matrix object.
 
+Diagonal matrix with unit elements can be created using @dfn{eye}.
 Some other built-in functions can also return diagonal matrices. Examples include
 @dfn{balance} or @dfn{inv}.
 
+Example:
+@example
+  diag (1:4)
+@result{}
+Diagonal Matrix
+
+   1   0   0   0
+   0   2   0   0
+   0   0   3   0
+   0   0   0   4
+
+  diag(1:3,5,3)
+
+@result{}
+Diagonal Matrix
+
+   1   0   0
+   0   2   0
+   0   0   3
+   0   0   0
+   0   0   0
+@end example  
+
 @node Creating Permutation Matrices
 @subsection Creating Permutation Matrices
 
@@ -87,23 +115,62 @@
 created by indexing an identity matrix by permutation vectors.
 That is, if @var{q} is a permutation vector of length @var{n}, the expression
 @example
-  @var{P} = eye (@var{n}) (:, @var{q});
+  P = eye (n) (:, q);
 @end example
 will create a permutation matrix - a special matrix object.
 @example
-eye (@var{n}) (@var{q}, :) 
+eye (n) (q, :) 
 @end example
 will also work (and create a row permutation matrix), as well as 
 @example
-eye (@var{n}) (@var{q1}, @var{q2}).
+eye (n) (q1, q2).
+@end example
+
+For example:
+@example
+  eye (4) ([1,3,2,4],:)
+@result{}
+Permutation Matrix
+
+   1   0   0   0
+   0   0   1   0
+   0   1   0   0
+   0   0   0   1
+
+  eye (4) (:,[1,3,2,4])
+@result{}
+Permutation Matrix
+
+   1   0   0   0
+   0   0   1   0
+   0   1   0   0
+   0   0   0   1
 @end example
 
 Mathematically, an identity matrix is both diagonal and permutation matrix.
-In Octave, @code{eye (@var{n})} returns a diagonal matrix, because a matrix
+In Octave, @code{eye (n)} returns a diagonal matrix, because a matrix
 can only have one class. You can convert this diagonal matrix to a permutation
-matrix by indexing it by an identity permutation, as shown above.
+matrix by indexing it by an identity permutation, as shown below.
 This is a special property of the identity matrix; indexing other diagonal
-matrices generall produces a full matrix.
+matrices generally produces a full matrix.
+
+@example
+  eye (3)
+@result{}
+Diagonal Matrix
+
+   1   0   0
+   0   1   0
+   0   0   1
+
+  eye(3)(1:3,:)
+@result{}
+Permutation Matrix
+
+   1   0   0
+   0   1   0
+   0   0   1
+@end example
 
 Some other built-in functions can also return permutation matrices. Examples include
 @dfn{inv} or @dfn{lu}.
@@ -112,17 +179,18 @@
 @subsection Explicit and Implicit Conversions
 
 The diagonal and permutation matrices are special objects in their own right. A number
-of operations and built-in functions, are defined for these matrices to use special,
+of operations and built-in functions are defined for these matrices to use special,
 more efficient code than would be used for a full matrix in the same place. Examples
 are given in further sections.
 
 To facilitate smooth mixing with full matrices, backward compatibility, and
 compatibility with Matlab, the diagonal and permutation matrices should allow
-any operation that works on full matrices, and will either treat is specially,
+any operation that works on full matrices, and will either treat it specially,
 or implicitly convert themselves to full matrices.
 
-Instances include matrix indexing (except for extracting a single element),
-indexed assignment, or applying most mapper functions, such as @dfn{exp}.
+Instances include matrix indexing, except for extracting a single element or
+a leading submatrix, indexed assignment, or applying most mapper functions,
+such as @dfn{exp}.
 
 An explicit conversion to a full matrix can be requested using the built-in
 function @dfn{full}. It should also be noted that the diagonal and permutation
@@ -147,11 +215,13 @@
 @subsection Expressions Involving Diagonal Matrices
 
 Assume @var{D} is a diagonal matrix. If @var{M} is a full matrix,
-then @code{@var{D}*@var{M}} will scale the rows of @var{M}. That means,
-if @code{@var{S} = @var{D}*@var{M}}, then for each pair of indices
+then @code{D*M} will scale the rows of @var{M}. That means,
+if @code{S = D*M}, then for each pair of indices
 i,j it holds 
 @iftex
+@tex
 $$S_{ij} = D_{ii} M_{ij}$$
+@end tex
 @end iftex
 @ifnottex
 @example
@@ -178,7 +248,7 @@
 in a least-squares minimum-norm sense. In exact arithmetics, this is
 equivalent to multiplying by a pseudoinverse. The pseudoinverse of
 a rectangular diagonal matrix is again a rectangular diagonal matrix
-of the same dimensions, where each nonzero diagonal element is replaced
+with swapped dimensions, where each nonzero diagonal element is replaced
 by its reciprocal.
 The matrix division algorithms do, in fact, use division rather than 
 multiplication by reciprocals for better numerical accuracy; otherwise, they
@@ -190,11 +260,11 @@
 
 If @var{D1} and @var{D2} are both diagonal matrices, then the expressions
 @example
-@var{D1} + @var{D2}
-@var{D1} - @var{D2} 
-@var{D1} * @var{D2} 
-@var{D1} / @var{D2} 
-@var{D1} \ @var{D2}
+D1 + D2
+D1 - D2 
+D1 * D2 
+D1 / D2 
+D1 \ D2
 @end example
 again produce diagonal matrices, provided that normal
 dimension matching rules are obeyed. The relations used are same as described above.
@@ -203,13 +273,20 @@
 to a scalar power if it is square, producing diagonal matrix result in all cases. 
 
 A diagonal matrix can also be transposed or conjugate-transposed, giving the expected
-result. Extracting a leading submatrix of a diagonal matrix, i.e. @code{@var{D}(1:m,1:n)},
+result. Extracting a leading submatrix of a diagonal matrix, i.e. @code{D(1:m,1:n)},
 will produce a diagonal matrix, other indexing expressions will implicitly convert to
 full matrix.
 
-When involved in expressions with the element-by-element operators @code{.*},
+Adding a diagonal matrix to a full matrix only operates on the diagonal elements. Thus,
+@example
+A = A + eps * eye (n)
+@end example
+is an efficient method of augmenting the diagonal of a matrix. Subtraction works
+analogically.
+
+When involved in expressions with other element-by-element operators, @code{.*},
 @code{./}, @code{.\} or @code{.^}, an implicit conversion to full matrix will
-also take place. This is not always strictly necessary but chosen to facilitate
+take place. This is not always strictly necessary but chosen to facilitate
 better consistency with Matlab.
 
 @node Expressions Involving Permutation Matrices
@@ -295,12 +372,14 @@
   x = U \ L \ P*b;
 @end example
 
+@noindent
 This is how you normalize columns of a matrix @var{X} to unit norm:
 @example
   s = norm (X, "columns");
   X = diag (s) \ X;
 @end example
 
+@noindent
 The following expression is a way to efficiently calculate the sign of a
 permutation, given by a permutation vector @var{p}. It will also work
 in earlier versions of Octave, but slowly.
@@ -308,6 +387,7 @@
   det (eye (length (p))(p, :))
 @end example
 
+@noindent
 Finally, here's how you solve a linear system @code{A*x = b} 
 with Tikhonov regularization (ridge regression) using SVD (a skeleton only):
 @example
@@ -316,14 +396,15 @@
   ## determine the regularization factor alpha
   ## alpha = ...
   ## transform to orthogonal basis
-  x = U'*b;
-  ## Use the standard formula, replacing A with S. We work with 
-  ## diagonal matrices, so this will be plausibly efficient.
-  x = (S'*S + alpha^2 * eye (n)) \ (S' * x);
+  b = U'*b;
+  ## Use the standard formula, replacing A with S.
+  ## S is diagonal, so the following will be very fast and accurate.
+  x = (S'*S + alpha^2 * eye (n)) \ (S' * b);
   ## transform to solution basis
   x = V*x;
 @end example
 
+
 @node Zeros Treatment
 @section The Differences in Treatment of Zero Elements
 
@@ -347,8 +428,9 @@
 usually not stored explicitly anywhere, but is implied by the underlying
 data structure.
 
-The primary distinction is that an assumed zero, when multiplied or divided
-by any number, yields *always* a zero, even when, e.g., multiplied by @code{Inf}
+The primary distinction is that an assumed zero, when multiplied 
+by any number, or divided by any nonzero number,
+yields *always* a zero, even when, e.g., multiplied by @code{Inf}
 or divided by @code{NaN}.
 The reason for this behavior is that the numerical multiplication is not
 actually performed anywhere by the underlying algorithm; the result is