[manual] suggested addition to pcolor description

[Francesco Potorti`]

>Regarding the interpolation of the color values across the mesh, this  
>is controlled by the "shading" command.

By the way, I do not understand what shading() does.  As far as I
understood by experimenting, "flat" removes the black lines between mesh
elements, and "faceted" does the opposite.  I did not understand what
"interp" does.  These are purely aesthetic effects, and have nothing to
do with the choice of the color to use.

So either I did not manage to guess what shading() does, or it has
nothing to do with the choice of color, or some mix in between :)

>Perhaps what should be mentioned is that "C" is interpreted by the  
>current color map and that "shading" controls whether the mesh is  
>flat, faceted, or interpolated.

Yes, but what is essential, and is not mentioned, is that if C is 3x3,
pcolor draws a picture with 4 (2x2) rectangles, because the 3x3 values
of C are intended to be at the mesh vertices.  This is not documented
anywhere.  On the other hand, imagesc, which does a very similar job,
draws instead a picture with 9 (3x3) rectangles, because the values of
its argument are intended to be in the middle of the mesh rectangles
(not at the vertices).  In my opinion, it is well worth noting the
similarities and differences between the two in the manual; I only
discovered them after quite some time doing experiments.

>On another note, I am pleased to see the interest of you and others  
>are taking to improve Octave's documentation. I'd encourage you to  
>install mercurial and pull the sources from jwe's repository. Even if  
>you aren't interested in building Octave from its sources, having the  
>repository local permits you to create and submit changesets directly.

The fact is, I have just switched to 3.0 and at the same time have just
started to fiddle with multidim arrays and 2d plotting, so I am doing a
lot of experimenting and manual reading just now, but the rate of my bug
reports is going to reduce soon, I suspect, because I have read most of
the new topics by now.  Anyway, I'll consider mercurial if I manage to
find the time, thanks for your suggestion.

>In any event, what of the change below?
...
>      The values of C are linearly mapped to the mesh using the current
>      colormap. The method of  interpolation of the colors across the
>      mesh is determined by the state of shading.

This language is obscure to me.  Does "linearly mapped" refer to how the
values are geometrically arranged in the plot or how they are mapped to
colors?  In any case, the type of mapping is not explained.  Same for
the "method of interpolation", because the doc for shading does not
explain what is the meaning of its argument.

More generally speaking, none of the issues that I mentioned above are
addressed by this change.