grdinterpolate -T documentation

[tomeracles]

Sorry, not exactly sure how to label this. I have been using grdinterpolate to get 2-d depth slices from 3-d netCDF cubes of seismic tomography models (i.e., with longitude, latitude, depth co-ordinates).

The way to do this, as far as I can tell, is to use grdinterpolate -T[level]. To be fair, there are some clues on the manual page for grdinterpolate that this is the way to do it (e.g., the first example is reasonably clear, and there are some hints in the description of -G), but I don't think it's easy to see from the description of -T that this is the way. It starts to talk about "time-steps" and "times", but then in the second half refers to "layers" — at first reading, I did not understand that this would be the way to choose a z-coordinate (or "level" as this manual page refers to z-coordinates). There is also no mention of choosing a single z-value.

I would like to suggest that the -T description could be improved, but please let me know if I have misunderstood something.

Current text:

**-T**\ [*min/max*\ /]\ *inc*\ [**+i**\|\ **n**] \|\ |-T|\ *file*\|\ *list*
    Make evenly spaced time-steps from *min* to *max* by *inc* [Default uses input times].
    For details on array creation, see `Generate 1-D Array`_.  **Note**: If |-Z| is set
    and no output times are set with |-T| we simply rewrite the grid-produced cube as
    a 3-D data cube file and exit. Also, for |-E| and |-S| you may also just give
    a range via |-T|\ *min/max* to limit the layers considered, with no interpolation
    between the selected layers.  If |-T| is not given and neither |-E| nor |-S| are
    set, then we simply extract all layers within the bounds set by |-R|.

My idea for possible replacement text:

**-T**\ [*min/max*\ /]\ *inc*\ [**+i**\|\ **n**] \|\ |-T|\ *file*\|\ *list*
    Create evenly-spaced levels from *min* to *max* by *inc* [Default uses input levels]. 
    Alternatively, provide a comma-separated *list* of levels or a *file* containing levels 
    to output. A single value specified will result in a single layer being output.
    For details on array creation, see `Generate 1-D Array`_.  **Note**: If |-Z| is set
    and no output levels are set with |-T| we simply rewrite the grid-produced cube as
    a 3-D data cube file and exit. Also, for |-E| and |-S| you may also just give
    a range via |-T|\ *min/max* to limit the layers considered, with no interpolation
    between the selected layers.  If |-T| is not given and neither |-E| nor |-S| are
    set, then we simply extract all layers within the bounds set by |-R|.

I am not certain about some things:

1. I am inferring from the presence of the options "file|list" that you could specify either a comma-separated list of levels or a file containing levels but I have not checked this.

2. I think the current formatting implies you could select -T<inc>, whereas instead of an increment it will understand that as a level.

3. I assume all the mentions about times/time-steps are legacy from what the option was previously intended for, presumably it is not needed?

Let me know what you think.

Thanks,
Tom