[manual] suggested addition to pcolor description

[Ben Abbott]

On Sep 20, 2008, at 5:40 AM, Francesco Potorti` wrote:

> In Two-Dimensional Plots I read:
>
> -- Function File:  pcolor (X, Y, C)
> -- Function File:  pcolor (C)
>     Density plot for given matrices X, and Y from `meshgrid' and a
>     matrix C corresponding to the X and Y coordinates of the mesh.  If
>     X and Y are vectors, then a typical vertex is (X(j), Y(i),
>     C(i,j)).  Thus, columns of C correspond to different X values and
>     rows of C correspond to different Y values.
>
>     *See also:* meshgrid, contour.
>
> To the end of the description I would add four sentences that explain
> how pcolor interprets its arguments and how it differs from imagesc.
>
> Of the four sentences below, the first and last are the most  
> important,
> while the second and third are optional:
>
> 1)
> Notice that values from C are taken as the values of the vertices of
> the mesh, meaning that the resulting plot contains rows(C)-1 rows and
> columns(C)-1 columns.
>
> 2)
> The colors used for plotting are computed by interpolating the  
> values at
> the four vertices of each rectangle of the grid.
>
> 3)
> Currently, gnuplot does no interpolation, but displays a color
> corresponding to the lower left vertex of the rectangle.
>

> 4)
> If you want your plot to show one color (rectangle?) for each of the
> values in C, you can use imagesc (see).

Regarding 3), I don't think we want to mention the specifics regarding  
special features or limitations of the graphics backend in the help  
text.

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

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.

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.

In any event, what of the change below?

  -- Function File:  pcolor (X, Y, C)
  -- Function File:  pcolor (C)
      Density plot for given matrices X, and Y from `meshgrid' and  a
      matrix C corresponding to the X and Y coordinates of  the mesh.
      If X and Y are vectors, then a typical vertex  is (X(j), Y(i),
      C(i,j)).  Thus, columns of C  correspond to different X values and
      rows of C correspond  to different Y values.

      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.

      See also: colormap, contour, meshgrid, shading.

Ben