plot/plot3d/clip: Simplify the -A syntax to -Ax|y

[seisman]

See #8645 for context.

Closes #8645.

[github-actions]

Summary of changed images

This is an auto-generated report of images that have changed on the DVC remote

Status	Path
modified	test/baseline/psxy/
modified	test/baseline/psxy/polarcurves.ps

Image diff(s)

Details

Added images

Modified images

Path	Old	New
test/baseline/psxy/polarcurves.ps

Report last updated at commit 31e79ca

[remkos]

I felt I should review this since I implemented -Am and -Ap in GMT4 in Sep 2007!
Since then it was extended with -A[x|y|r|t], without it actually requiring a change of code except for needing to parse the options and add to the documentation.

So it is OK to me to bring it back to -A[x|y] as long as the old options are still supported for backward compatibility.

How does this impact the long options?

[seisman]

I felt I should review this since I implemented -Am and -Ap in GMT4 in Sep 2007!

Good to know the history dating back to 2007!

When updating the documentation, we also found a bug that the meaning of -Am and -Ap are reversed. Please see #8645 (comment) for details. We already fixed it in #8648, but it would be great if you can verify it again.

So it is OK to me to bring it back to -A[x|y] as long as the old options are still supported for backward compatibility.

Yes, it's backward compatible.

How does this impact the long options?

That's a good question. Currently, long names exist for m/p/x/y/r/t (

gmt/src/longopt/psxy_inc.h

Line 29 in 605da46

"m,p,x,y,r,t", "mpfollow,pmfollow,xyalong,yxalong,rtalong,tralong",

). I guess we should also remove the long names for m/p/r/t, OK?

[remkos]

The original implementation from 2007 was, according to the e-mail I found about it:

-Am : first follow meridian, then parallel
-Ap : first follow parallel, then meridian.

As I said, -Ax and -Ay came later, but clearly x and p should be equivalent, just as y and m. The code also has that equivalence correct. Clearly sometime later the GMT_STAIRS_X and GMT_STAIRS_Y got confused (maybe already at the introduction of those defines), but you fixed that in #8667 and @Esteban82 in #8648.

So with this PR (#8674) we are good.

Regarding the long options, since they have not been thoroughly introduced, I would keep only xyalong,yxalong.

[joa-quim]

I must have missed that longoption choice that missed to match any of GMT.jl options. I propose to rename it to stairs, steps.
xyalong also looks awful to me. Why not just x, y or, in longer, xfirst, yfirst?

[seisman]

In PyGMT, the parameter name is straight_line and valid values are True, x and y.

[joa-quim]

GMT.jl accepts steps, stairs and straight_lines, but last one is not documented (probably it was before) and I'll drop it.
To solve this we can have in GMT these three aliases steps, stairs & straight_line ... or you change the PyGMT keyword or add an alias.

[joa-quim]

Also -E longoptions got it all wrong GMT.jl has error_bars, PyGMT error_bar but GMT picked errorbars. Add all three aliases in master.

[Esteban82]

Can this be merge?

[seisman]

Not yet. There are other modules (e.g., clip) that takes the same -A option.

[seisman]

I believe this PR is now ready for final review.

[joa-quim]

Looks good.