legend: clearances between legend items and the box border

[seisman]

Description of the problem

In the legend module, it seems the -F+c and -C options set the clearance between legend terms and the frame. Is it right? If yes, perhaps we should remove the -C option from the documentation (still keep it for backward compatibility).

Here is an example:

gmt begin GMT_autolegend
	gmt plot -R0/7.2/3/7.2 -Jx2c @Table_5_11.txt -Sc0.35c -Glightgreen -Wfaint -lApples+H"LEGEND"+f16p+D
	gmt plot @Table_5_11.txt -St0.35c -Gorange -B -BWStr -lOranges
	gmt legend -DjTR+w3c+o0.25c -F+p1p+ggray95+s+c10p/10p
gmt end show

Removing +c10p/10p and adding -C10p/10p gives similar plots.

For large clearances, +c50p/50p still works well, but -C50p/50p doesn't. Here is the result for -C50p/50p.

[PaulWessel]

Currently, the default clearance is controlled by -C so if -F+c is not given then the -C defaults apply. Since we have to be backwards compatible here we will still need to honor -C and its defaults. Perhaps we simply undocument -C and transfer the default to -F+c but leave the code as is?

[seisman]

I think it's a good solution.

[PaulWessel]

Reading more carefully, there seems to be a difference:

1. The -C clearance assumes the given dimensions of the box and starts plotting items this far inside the box.
2. The -F+c clearance adds extra space by expanding the dimensions of the box.

So they achieve the same relative result but in two different ways. That may be overkill but also not a duplication we can easily fix by removing -C. At best, we could add -F+Cclearance which would do the inwards shift like -C while -F+c would do the outward shift.

Thoughts on this?

[PaulWessel]

Wait, perhaps I am wrong about this (or specifically the comments in the code). I see the computation of the box height starts with

`height = 2.0 * Ctrl->C.off[GMT_Y];`

so that suggests outward moving of the boundaries, just like -F+c says it does.

[PaulWessel]

No, not wrong. Here I run with -C:

echo "H 16p HELLO" | gmt legend -R0/10/0/10 -Jx1c -Bafg1 -F+p0.25+glightgray -C1c -DjBL+w5c -png map

Here I use -F+c:

echo "H 16p HELLO" | gmt legend -R0/10/0/10 -Jx1c -Bafg1 -F+p0.25+glightgray+c1c -DjBL+w5c -png map2

Clearly two different effects, so perhaps the real solution here is better documentation?

[seisman]

OK, now I understand the differences between these two.

To me, the behavior of -C (inwards shift) seems more useful. When I use -DjBL+o0.2c/0.2+w5c, I expect to put the legend (the legend box) to the bottom left corner, with 0.2c and 0.2c offsets, but

-DjBL+o0.2c/0.2c+w5c -F+p0.25+glightgray+c1c

do the outward shifts (like the figure above), then I have to change the offsets (+o modifier) based on the values of +c.

[PaulWessel]

I agree that it seems very awkward to add space with +c and then having to adjust via +o. So there are two paths:

1. We declare a bug and fix +c to work like -C and then deprecate -C
2. We leave it as a feature and are stuck with both.

I think option 1 is more appealing, but possibly we will ahve to deal with some test failures and PS updates. Voting on this, @seisman and @joa-quim ?

[joa-quim]

Also prefer 1.

[seisman]

Yes for option 1.

[PaulWessel]

Before we do this, let's be clear on the scope. Another difference with -C is that -F+c clearance is either gap, xgap/ygap, or lgap/rgap/bgap/tgap while -C is only gap or xgap/ygap. So allowing the 4-sided clearances requires some recoding in pslegend. Furthermore, -F also applies to many other map embellishments and it is not clear (I have not looked in detail) if what makes sense for a legend also makes sense for map scales, compasses, etc. I think we need to know that before changing -F+c due to side-effects. Checking for scripts that contain a -F option with a +c modifier and not pstext gave me these:

doc/examples/ex28/ex28.sh
doc/examples/ex43/ex43.sh
doc/examples/ex44/ex44.sh
doc/scripts/GMT_agefig.sh
doc/scripts/GMT_mapscale.sh
doc/scripts/GMT_panel.sh
doc/scripts/GMT_seislegend.sh

For instance, the agefig.sh has this:

-F+gwhite+c0p/1p/2p/8p+pfaint

as we try to do a good job fitting a rectangle behind a colorbar with labels. The reason for this really is that the only way to do this exactly is to do the sizing in PostScript based on things that are plotted. But it is pretty hard to keep track of min/max extents of annotations and labels. In this case, enlarging the rectangle was needed. So if we declare a but, we sould have to change the signs of those to +c0p/-1p/-2p/-8p and now it looks less appealing.

Chew on this and see what you think.

[PaulWessel]

Regardless of the above, I think +oxoff/yoff should be such that the corner of the rectangle touches that point. With -F+c now it is the zero-clearance imaginary rectangle that touch that point. That could be fixed without affecting the -C discussion if we declare that a bug. Again, this then shifts the center of the rectangle so there is some other considerations as well.

[seisman]

The new behavior (+c means inward offsets) may not make sense for -Dglon/lat, especially for map scale bars.

[PaulWessel]

Yes, so I think the only good solution here is to decide that -F+c will presumably extend the rectangle, and then the -F+o offset should be measured to the side/corner of that extended box, not the original one (with zero extensions). I cannot see that any user would want to get the result above (2nd hello) but would expect it to have its lower-left corner at the same spot as the first Hello, since no offset was specified. Do we all agree on that interpretation? So I think legend -C is a separate module-specific option that will stay, and the interplay between -F+o+c needs work.

[PaulWessel]

Pinging you guys again as we should wrap this up. So +c should extend the rectangle and then +o works relative to the extended rectangle. OK as a plan?