Bug #646

psxy -Sql documentation update

Added by Kristof almost 3 years ago. Updated almost 3 years ago.

Status:ClosedStart date:2014-11-19
Priority:NormalDue date:
Assignee:Remko% Done:

100%

Category:-
Target version:Candidate for next bugfix release
Affected version:all Platform:

Description

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 -Sql.

From the psxy documentation:

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,
Kristof

History

#1 Updated by Eduardo almost 3 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 almost 3 years ago

Hi Eduardo,

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,
Kristof

#3 Updated by Remko almost 3 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.

#4 Updated by Kristof almost 3 years ago

Hi Remko,

Yes, this is better understandable - at least for me. Thank you!

#5 Updated by Paul almost 3 years ago

  • Status changed from Feedback to Resolved

Hi Remko, yes much better, please update.

#6 Updated by Remko almost 3 years ago

  • Status changed from Resolved to Closed
  • % Done changed from 0 to 100

Closed as implemented by r13726 (GMT 5.1) and r13729 (GMT 5.2) and r10283 (GMT 4)

Also available in: Atom PDF