# HG changeset patch
# User Jordi Gutiérrez Hermoso <jordigh@octave.org>
# Date 1410192337 14400
# Node ID ec1e295402fa3e3b6eda5b99c13ca106043bdf48
# Parent  afc1a8965664c891630714c00e11bc705a842f12
doc: explain permute's PERM variable and give examples

* data.cc (Fpermute): Explain how the PERM variable is used. Give four
  quick examples.

diff -r afc1a8965664 -r ec1e295402fa libinterp/corefcn/data.cc
--- a/libinterp/corefcn/data.cc	Mon Sep 08 08:09:45 2014 +0200
+++ b/libinterp/corefcn/data.cc	Mon Sep 08 12:05:37 2014 -0400
@@ -2602,6 +2602,27 @@
 Return the generalized transpose for an N-D array object @var{A}.\n\
 The permutation vector @var{perm} must contain the elements\n\
 @code{1:ndims (A)} (in any order, but each element must appear only once).\n\
+\n\
+The @var{N}th dimension of @var{A} gets remapped to dimension \n\
+@code{@var{PERM}(@var{N})}.\n\ For example,\n\
+\n\
+@example\n\
+@group\n\
+@var{x} = zeros ([2, 3, 5, 7]);\n\
+size (@var{x})\n\
+   @result{}  2   3   5   7\n\
+\n\
+size (permute (@var{x}, [2, 1, 3, 4]))\n\
+   @result{}  3   2   5   7\n\
+\n\
+size (permute (@var{x}, [1, 3, 4, 2]))\n\
+   @result{}  2   5   7   3\n\
+\n\
+## The identity permutation\n\
+size (permute (@var{x}, [1, 2, 3, 4]))\n\
+   @result{}  2   3   5   7\n\
+@end group\n\
+@end example\n\
 @seealso{ipermute}\n\
 @end deftypefn")
 {