text: Honor vector heads on the -D+v leader line pen

[Esteban82]

text -D...+v<pen> accepted the pen's +v modifiers but silently ignored them. This PR makes +vb<specs> draw a vector head at the data point, as plot -W does. psxy's end-vector helper moves to gmt_plot.c as gmt_plot_end_vectors so both modules share it (no change to plot output).

Vector head at the data point

The leader is shortened by the head length so the tip lands on the point. It works with a text box (-W/-G), rotated text and paragraph mode (-M); a head longer than the leader is skipped.

Tested with:

gmt begin leader png
	gmt basemap -R0/10/-1/1 -JX12c/6c -B
	printf "5 0\n2 -0.5\n8 0.5\n8 -0.5\n" | gmt plot -Sc0.15c -Gblack
	echo "5 0 Label" | gmt text -D2c/1c+v1p,red+vb0.4c+gred -F+f12p
	echo "2 -0.5 Box" | gmt text -D1.5c/-1.2c+v0.5p+vb0.3c+a50+gblue -F+f12p -W0.5p -Gyellow -C0.2c
	echo "8 0.5 Rotated" | gmt text -DJ1c+v1p,darkgreen+vb0.3c+gdarkgreen -F+f12p+a30+jML
	echo "8 -0.5 No head" | gmt text -D-1.5c/-0.6c+v1p -F+f12p
gmt end

Head at the text end: not supported (error)

A head at the text end (+ve, or plain +v for both ends) is rejected with an error:

echo "5 0 X" | gmt text -R0/10/-1/1 -JX10c -D1c+v1p+ve0.3c -ps err
text [ERROR]: Option -D: A vector head can only be placed at the data point end of the line; use pen modifier +vb<specs>

The leader is clipped against the text box in PostScript (PSL_plotline_clipped_by_textbox), so C does not know where the line meets the box. Supporting it would need that intersection computed in C (e.g. a PSL function returning the text dimensions) or the head drawn in PostScript. Happy to follow up if wanted.

Written with Claude Opus 5.5 (implementation and local review); draft by Claude Sonnet 5.5.

[joa-quim]

Didn't we have nothing that does this already? And I think the arrow head should stop at circle's edge, not its center.

[Esteban82]

Didn't we have nothing that does this already?

On whether something already does this: plot -W...+vb draws a line with a head, and text -D...+v<pen> already drew the leader line but dropped the head modifiers silently. This PR only makes text honor what its pen already accepted, so one command gives the label, the leader (clipped at the text box) and the head. I'm not aware of another option that combines them; if you had a specific one in mind, point me to it.

And I think the arrow head should stop at circle's edge, not its center.

On the head stopping at the circle's edge: the black dots in the figure are drawn separately (with printf "5 0\n2 -0.5\n8 0.5\n8 -0.5\n" | gmt plot -Sc0.15c -Gblack) with plot -Sc, so text does not know a symbol is there or how big it is, and today the tip lands exactly on the data point. Here is the same figure without the circles:

If you want, I could add a suppor for +o<offset> at the data end (as plot -W does), so the user sets the gap for their symbol, e.g. -D2c/1c+v1p,red+o0.1c+vb0.4c+gred. Default stays 0.

[joa-quim]

Yes, I think a +o<offset> is important too.

I have this implemented in GMT.jl (https://www.generic-mapping-tools.org/GMTjl_doc/documentation/utilities/annotate.html#vector-lines) but likely I implemented the arrow part separately.

[joa-quim]

In these type of changes we must strictly insist with Claude that it is not allowed to reinvent solutions that GMT already has. I am thinking for example in +o<offset>. It will insist it won't do it but that thing is a big liar.

[Esteban82]

Thanks @joa-quim. Added +o<offset>, handled by the same gmt_trim_line that plot -W uses, so it takes the same offsets and rules (c|i|p or map distances; put it before +vb). Only the data-point end is trimmed, and the default stays 0.

Tested with:

gmt begin leader_offset png
	gmt basemap -R0/10/-1/1 -JX12c/6c -B
	printf "5 0\n2 -0.5\n8 0.5\n8 -0.5\n" | gmt plot -Sc0.15c -Gblack
	echo "5 0 Label" | gmt text -D2c/1c+v1p,red+o0.15c+vb0.4c+gred -F+f12p
	echo "2 -0.5 Box" | gmt text -D1.5c/-1.2c+v0.5p+o0.25c+vb0.3c+a50+gblue -F+f12p -W0.5p -Gyellow -C0.2c
	echo "8 0.5 Rotated" | gmt text -DJ1c+v1p,darkgreen+o0.25c+vb0.3c+gdarkgreen -F+f12p+a30+jML
	echo "8 -0.5 Offset only" | gmt text -D-1.5c/-0.6c+v1p,orange+o0.2c -F+f12p
gmt end

[seisman]

In these type of changes we must strictly insist with Claude that it is not allowed to reinvent solutions that GMT already has. I am thinking for example in +o<offset>. It will insist it won't do it but that thing is a big liar.

I feel we need an AGENTS.md file (https://agents.md/) to give AI agents clear instructions what to do and not to do.

[Esteban82]

In these type of changes we must strictly insist with Claude that it is not allowed to reinvent solutions that GMT already has. I am thinking for example in +o<offset>. It will insist it won't do it but that thing is a big liar.

I feel we need an AGENTS.md file (https://agents.md/) to give AI agents clear instructions what to do and not to do.

I'm about to make a PR about that.

[joa-quim]

OK, seems not very intrusive with regard to what we already have.