psxy -Sql documentation update
|Target version:||Candidate for next bugfix release|
I'd like to suggest a slight clarification of the current documentation: While the documentation is logically correct I had problems figuring out how to use
The format of each line specification is start/stop, where start and stop are either a specified point lon/lat or […].
My suggestion would be to add an example in the form of start_lon/start_lat/stop_lon/stop_lat to put some emphasis on the correct formatting of the coordinate pairs. It wasn't obvious to me that the separation between lon & lat as well as between the start and stop pairs has to be made with a forward slash.
Maybe English not being my native tongue contributed to this misunderstanding. Or my logic thinking ability. Or both.
All the best,
#1 Updated by Eduardo over 4 years ago
Hi Kristof, now you point this, I read it a thousand times and never understood it.
Reading n+1 times it looks something recursive. You have "start/stop" which are points in the form "lon/lat" so you ends with your awful discovery: "start_lon/start_lat/stop_lon/stop_lat"
#2 Updated by Kristof over 4 years ago
my apologies for not making my point clear. I simply had problems understanding that the forward slash between lon/lat is required for proper parsing. I read it as some stylistic element to aid readability of the documentation. For example, you might write "x/y-plane" instead of "xy-plane" for better readability. I finally figured it out after reading the (very) old Technical Reference and Cookbook (Version 5.0.0b, August 2011) where it says on page 193 under O.1 Label Placement:
For example, […] Z-/135W/15S is a line from the grid minimum to the point (135°W, 15°S).
This made the proper formatting clear to me. Unfortunately this sentence is no longer present in newer iterations of the psxy documentation. Therefore I'd like to suggest to reintroduce something similar to the current psxy documentation.
Hopefully I was able to express my point better this time.
All the best,
#3 Updated by Remko over 4 years ago
- Status changed from New to Feedback
- Assignee set to Remko
- Target version set to Candidate for next bugfix release
I suggest to change the documentation to the following:
Give the coordinates of the end points for one or more comma-separated straight line segments. Labels will be placed where these lines intersect the quoted lines. The format of each line specification is start_lon/*start_lat*/*stop_lon*/*stop_lat*. Both start_lon/*start_lat* and stop_lon/*stop_lat* can be replaced by a 2-character key that uses the justification format employed in pstext to indicate a point on the frame or center of the map, given as [LCR][BMT].
Please advice if this is better understandable.