WIP: DOC: Add Technical Reference page for reference and anchor points

doc/techref/index.md

@@ -15,5 +15,6 @@ text_formatting.md
 patterns.md
 encodings.md
 justification_codes.md
+reference_anchor_points.md
 environment_variables.md
 ```

doc/techref/justification_codes.md

@@ -5,10 +5,11 @@ file_format: mystnb
 # Justification codes
 
 To place plot embellishments, such as scalebars, directional roses, colorbars, legends,
-text, or images on a figure, two points have to be specified: a point somewhere on the
-figure (**reference point**) and a point on the feature (**anchor point**). For both,
-users can use a two-character code, a combination of a vertical code and a horizontal
-code (order-independent):
+text, or images on a figure, two points have to be specified a point somewhere on the
+figure (**reference point**) and a point on the feature (**anchor point**); for details
+please see [Reference and anchor points](/techref/reference_anchor_points.md). For both,
+users can use a two-character code, a combination of a vertical code and a horizontal code
+(order-independent):
 
 - Vertical: **T**(op), **M**(iddle), **B**(ottom)
 - Horizontal: **L**(eft), **C**(entre), **R**(ight)

doc/techref/reference_anchor_points.md

@@ -0,0 +1,55 @@
+---
+file_format: mystnb
+---
+
+# Reference and anchor points
+
+For placing plot embellishments, we distinguish between reference and anchor points. To set
+these points users have to use the [justification codes](/techref/justification_codes.md).
+The `offset` parameter allows to offset the anchor point from the reference point.
+
+```{code-cell}
+---
+tags: [remove-input]
+---
+"""
+Script explaining reference and anchor points.
+"""
+import pygmt
+
+size = 5
+x1 = [-size, 0, size, size, size, 0, -size, -size, 0]
+y1 = [-size, -size, -size, 0, size, size, size, 0, 0]
+x2 = [-3, -2, -1, -1, -1, -2, -3, -3, -2]
+y2 = [-1, -1, -1, 0, 1, 1, 1, 0, 0]
+codes = ["BL", "BC", "BR", "MR", "TR", "TC", "TL", "ML", "MC"]
+
+fig = pygmt.Figure()
+fig.basemap(projection="X10c/6c", region=[-size, size, -size, size], frame=0)
+
+fig.text(
+    text=codes,
+    x=x1,
+    y=y1,
+    justify=codes,
+    offset="j0.5c/0.2c+v1p,gray30",
+    font="10p,1,black",
+)
+
+fig.plot(x=x2[0:-1], y=y2[0:-1], fill="bisque")
+
+fig.plot(x=-size, y=size, style="s0.6c", fill="lightred", no_clip=True)
+fig.plot(x=x1, y=y1, style="c0.25c", fill="steelblue", no_clip=True)
+
+fig.plot(x=-3, y=1, style="s0.6c", fill="orange")
+fig.plot(x=x2, y=y2, style="c0.15c", fill="darkblue")
+
+fig.plot(x=[-5, -3], y=[5, 1], pen="0.5p,black")
+fig.plot(x=[-5, -3], y=[1, 1], pen="0.5p,black,2_2")
+fig.plot(x=[-3, -3], y=[1, 5], pen="0.5p,black,2_2")
+
+fig.text(x=-4, y=1, text="dx", offset="0c/0.2c")
+fig.text(x=-3, y=3, text="dy", offset="-0.2c/0c")
+
+fig.show(width=600)
+```