From 86cf1e2a8a660a009584ee21ea6b5b8d7646c3be Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?=
 <94163266+yvonnefroehlich@users.noreply.github.com>
Date: Sun, 21 Apr 2024 16:04:42 +0200
Subject: [PATCH] Gallery example "Custom symbols": Mention own coustom symbols
 (#3186)

Co-authored-by: Michael Grund <23025878+michaelgrund@users.noreply.github.com>
---
 examples/gallery/symbols/custom_symbols.py | 38 ++++++++++++----------
 1 file changed, 21 insertions(+), 17 deletions(-)

diff --git a/examples/gallery/symbols/custom_symbols.py b/examples/gallery/symbols/custom_symbols.py
index 3949903f8e2..5e2b5a001b2 100644
--- a/examples/gallery/symbols/custom_symbols.py
+++ b/examples/gallery/symbols/custom_symbols.py
@@ -2,12 +2,21 @@
 Custom symbols
 ==============
 
-The :meth:`pygmt.Figure.plot` method can plot individual custom symbols
-by passing the corresponding symbol name together with the **k** shortcut to
-the ``style`` parameter. In total 41 custom symbols are already included of
-which the following plot shows five exemplary ones. The symbols are shown
-underneath their corresponding names. For the remaining symbols see the GMT
-Technical Reference :gmt-docs:`reference/custom-symbols.html`.
+The :meth:`pygmt.Figure.plot` method can plot individual custom symbols by
+passing the corresponding symbol name together with the **k** shortcut to the
+``style`` parameter.
+
+In total 41 custom symbols are already included of which the following plot shows
+five exemplary ones. The symbols are shown underneath their corresponding names.
+For the remaining symbols see the GMT Technical Reference
+:gmt-docs:`reference/custom-symbols.html`.
+
+Beside these built-in custom symbols GMT allows users to define their own custom
+symbols. For this, a specific macro language is used. A detailed introduction can
+be found at :gmt-docs:`reference/custom-symbols.html#the-macro-language`. After
+defining such a symbol it can be used in the same way as a built-in custom symbol.
+
+*Please note*: Custom symbols can not be used in auto-legends yet.
 """
 
 # %%
@@ -16,32 +25,27 @@
 fig = pygmt.Figure()
 fig.basemap(region=[0, 8, 0, 3], projection="X12c/4c", frame=True)
 
-# define pen and fontstyle for annotations
+# Define pen and fontstyle for annotations
 pen = "1p,black"
 font = "15p,Helvetica-Bold"
 
-# use the volcano symbol with a size of 1.5c,
-# fill color is set to "seagreen"
+# Use the volcano symbol with a size of 1.5c, fill color is set to "seagreen"
 fig.plot(x=1, y=1.25, style="kvolcano/1.5c", pen=pen, fill="seagreen")
 fig.text(x=1, y=2.5, text="volcano", font=font)
 
-# use the astroid symbol with a size of 1.5c,
-# fill color is set to "red3"
+# Use the astroid symbol with a size of 1.5c, fill color is set to "red3"
 fig.plot(x=2.5, y=1.25, style="kastroid/1.5c", pen=pen, fill="red3")
 fig.text(x=2.5, y=2.5, text="astroid", font=font)
 
-# use the flash symbol with a size of 1.5c,
-# fill color is set to "darkorange"
+# Use the flash symbol with a size of 1.5c, fill color is set to "darkorange"
 fig.plot(x=4, y=1.25, style="kflash/1.5c", pen=pen, fill="darkorange")
 fig.text(x=4, y=2.5, text="flash", font=font)
 
-# use the star4 symbol with a size of 1.5c,
-# fill color is set to "dodgerblue4"
+# Use the star4 symbol with a size of 1.5c, fill color is set to "dodgerblue4"
 fig.plot(x=5.5, y=1.25, style="kstar4/1.5c", pen=pen, fill="dodgerblue4")
 fig.text(x=5.5, y=2.5, text="star4", font=font)
 
-# use the hurricane symbol with a size of 1.5c,
-# fill color is set to "magenta4"
+# Use the hurricane symbol with a size of 1.5c, fill color is set to "magenta4"
 fig.plot(x=7, y=1.25, style="khurricane/1.5c", pen=pen, fill="magenta4")
 fig.text(x=7, y=2.5, text="hurricane", font=font)