From 42c07fb328b7d095e212b648d46793ff6c7f49a5 Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Sat, 21 Sep 2024 16:33:39 +0200
Subject: [PATCH 01/35] Add code legend via tringio

---
 .../gallery/embellishments/legend_stringio.py | 56 +++++++++++++++++++
 1 file changed, 56 insertions(+)
 create mode 100755 examples/gallery/embellishments/legend_stringio.py

diff --git a/examples/gallery/embellishments/legend_stringio.py b/examples/gallery/embellishments/legend_stringio.py
new file mode 100755
index 00000000000..93fac552a95
--- /dev/null
+++ b/examples/gallery/embellishments/legend_stringio.py
@@ -0,0 +1,56 @@
+"""
+Legend
+======
+
+The :meth:`pygmt.Figure.legend` method can automatically create a legend for
+symbols plotted using :meth:`pygmt.Figure.plot`. A legend entry is only added
+when the ``label`` parameter is used to state the desired text. Optionally,
+to adjust the legend, users can append different modifiers. A list of all
+available modifiers can be found at :gmt-docs:`gmt.html#l-full`. To create a
+multiple-column legend **+N** is used with the desired number of columns.
+For more complicated legends, users may want to write an ASCII file with
+instructions for the layout of the legend items and pass it to the ``spec``
+parameter of :meth:`pygmt.Figure.legend`. For details on how to set up such a
+file, please see the GMT documentation at :gmt-docs:`legend.html#legend-codes`.
+"""
+
+# %%
+import io
+import pygmt
+
+# -----------------------------------------------------------------------------
+spec = io.StringIO(
+"""
+G -0.1c
+H 24p,Times-Roman My Map Legend
+D 0.2c 1p
+N 2
+V 0 1p
+S 0.1c c 0.15c p300/12 0.25p 0.3c This circle is hachured
+S 0.1c e 0.15c yellow 0.25p 0.3c This ellipse is yellow
+S 0.1c w 0.15c green 0.25p 0.3c This wedge is green
+S 0.1c f 0.25c blue 0.25p 0.3c This is a fault
+S 0.1c - 0.15c - 0.25p,- 0.3c A contour
+S 0.1c v 0.25c magenta 0.5p 0.3c This is a vector
+S 0.1c i 0.15c cyan 0.25p 0.3c This triangle is boring
+D 0.2c 1p
+V 0 1p
+N 1
+M 5 5 600+u+f
+G 0.05c
+I @SOEST_block4.png 3i CT
+G 0.05c
+G 0.05c
+L 9p,Times-Roman R Smith et al., @%5%J. Geophys. Res., 99@%%, 2000
+G 0.1c
+T Let us just try some simple text that can go on a few lines.
+T There is no easy way to predetermine how many lines may be required
+T so we may have to adjust the height to get the right size box.
+""")
+
+# -----------------------------------------------------------------------------
+fig = pygmt.Figure()
+
+fig.legend(spec=spec, region=[0, 10] * 2, projection="M10c", position="jMC+jMC+w5c")
+
+fig.show()

From 79f6b3e3e0554a6f705c1d88fdb0c555d39ce21a Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Wed, 6 Nov 2024 10:59:43 +0100
Subject: [PATCH 02/35] Update docstring

---
 .../gallery/embellishments/legend_stringio.py | 124 ++++++++++--------
 1 file changed, 68 insertions(+), 56 deletions(-)

diff --git a/examples/gallery/embellishments/legend_stringio.py b/examples/gallery/embellishments/legend_stringio.py
index 93fac552a95..7aabb61789a 100755
--- a/examples/gallery/embellishments/legend_stringio.py
+++ b/examples/gallery/embellishments/legend_stringio.py
@@ -1,56 +1,68 @@
-"""
-Legend
-======
-
-The :meth:`pygmt.Figure.legend` method can automatically create a legend for
-symbols plotted using :meth:`pygmt.Figure.plot`. A legend entry is only added
-when the ``label`` parameter is used to state the desired text. Optionally,
-to adjust the legend, users can append different modifiers. A list of all
-available modifiers can be found at :gmt-docs:`gmt.html#l-full`. To create a
-multiple-column legend **+N** is used with the desired number of columns.
-For more complicated legends, users may want to write an ASCII file with
-instructions for the layout of the legend items and pass it to the ``spec``
-parameter of :meth:`pygmt.Figure.legend`. For details on how to set up such a
-file, please see the GMT documentation at :gmt-docs:`legend.html#legend-codes`.
-"""
-
-# %%
-import io
-import pygmt
-
-# -----------------------------------------------------------------------------
-spec = io.StringIO(
-"""
-G -0.1c
-H 24p,Times-Roman My Map Legend
-D 0.2c 1p
-N 2
-V 0 1p
-S 0.1c c 0.15c p300/12 0.25p 0.3c This circle is hachured
-S 0.1c e 0.15c yellow 0.25p 0.3c This ellipse is yellow
-S 0.1c w 0.15c green 0.25p 0.3c This wedge is green
-S 0.1c f 0.25c blue 0.25p 0.3c This is a fault
-S 0.1c - 0.15c - 0.25p,- 0.3c A contour
-S 0.1c v 0.25c magenta 0.5p 0.3c This is a vector
-S 0.1c i 0.15c cyan 0.25p 0.3c This triangle is boring
-D 0.2c 1p
-V 0 1p
-N 1
-M 5 5 600+u+f
-G 0.05c
-I @SOEST_block4.png 3i CT
-G 0.05c
-G 0.05c
-L 9p,Times-Roman R Smith et al., @%5%J. Geophys. Res., 99@%%, 2000
-G 0.1c
-T Let us just try some simple text that can go on a few lines.
-T There is no easy way to predetermine how many lines may be required
-T so we may have to adjust the height to get the right size box.
-""")
-
-# -----------------------------------------------------------------------------
-fig = pygmt.Figure()
-
-fig.legend(spec=spec, region=[0, 10] * 2, projection="M10c", position="jMC+jMC+w5c")
-
-fig.show()
+"""
+Legend
+======
+
+The :meth:`pygmt.Figure.legend` method creates legends, whereby auto-legends as
+well as manually created legends are allowed.
+For auto-legends the ``label`` parameter of :meth:`pygmt.Figure.plot` has to be
+specified to state the desired text.
+
+Optionally, to adjust the legend, users can append different modifiers. A list
+of all available modifiers can be found at :gmt-docs:`gmt.html#l-full`. To
+create a multiple-column legend **+N** is used with the desired number of columns.
+
+For more complicated legends, users may want to write an ASCII file with
+instructions for the layout of the legend items and pass it to the ``spec``
+parameter of :meth:`pygmt.Figure.legend`. For details on how to set up such a
+file, please see the GMT documentation at :gmt-docs:`legend.html#legend-codes`.
+Beides such an ASCII file PyGMT allows the provided a ``io.StringIO`` object.
+
+The example blow is orientated on the upstream GMT example at
+https://docs.generic-mapping-tools.org/dev/legend.html#examples.
+"""
+
+# %%
+import io
+
+import pygmt
+
+# -----------------------------------------------------------------------------
+# Set up io.StringIO object
+spec_io = io.StringIO(
+    """
+G -0.1c
+H 24p,Times-Roman My Map Legend
+D 0.2c 1p
+N 2
+V 0 1p
+S 0.1c c 0.15c p300/12 0.25p 0.3c This circle is hachured
+S 0.1c e 0.15c yellow 0.25p 0.3c This ellipse is yellow
+S 0.1c w 0.15c green 0.25p 0.3c This wedge is green
+S 0.1c f 0.25c blue 0.25p 0.3c This is a fault
+S 0.1c - 0.15c - 0.25p,- 0.3c A contour
+S 0.1c v 0.25c magenta 0.5p 0.3c This is a vector
+S 0.1c i 0.15c cyan 0.25p 0.3c This triangle is boring
+D 0.2c 1p
+V 0 1p
+N 1
+M 5 5 600+u+f
+G 0.05c
+I @SOEST_block4.png 3i CT
+G 0.05c
+G 0.05c
+L 9p,Times-Roman R Smith et al., @%5%J. Geophys. Res., 99@%%, 2000
+G 0.1c
+T Let us just try some simple text that can go on a few lines.
+T There is no easy way to predetermine how many lines may be required
+T so we may have to adjust the height to get the right size box.
+"""
+)
+
+# -----------------------------------------------------------------------------
+# Plot legend into a figure
+fig = pygmt.Figure()
+
+# Pass io.StringIO object to the spec parameter
+fig.legend(spec=spec_io, region=[0, 10] * 2, projection="M10c", position="jMC")
+
+fig.show()

From 497a275f34505023fb2d2013d820a98b2428b2b6 Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Wed, 6 Nov 2024 11:33:30 +0100
Subject: [PATCH 03/35] Addm more docs

---
 examples/gallery/embellishments/legend_stringio.py | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/examples/gallery/embellishments/legend_stringio.py b/examples/gallery/embellishments/legend_stringio.py
index 7aabb61789a..4a9de5a5d36 100755
--- a/examples/gallery/embellishments/legend_stringio.py
+++ b/examples/gallery/embellishments/legend_stringio.py
@@ -3,19 +3,19 @@
 ======
 
 The :meth:`pygmt.Figure.legend` method creates legends, whereby auto-legends as
-well as manually created legends are allowed.
+well as manually created legends are supported
 For auto-legends the ``label`` parameter of :meth:`pygmt.Figure.plot` has to be
-specified to state the desired text.
+specified to state the desired text in the legend entery.
 
 Optionally, to adjust the legend, users can append different modifiers. A list
-of all available modifiers can be found at :gmt-docs:`gmt.html#l-full`. To
-create a multiple-column legend **+N** is used with the desired number of columns.
+of all available modifiers can be found at :gmt-docs:`gmt.html#l-full`.
+To create a multiple-column legend **+N** is used with the desired number of columns;
+see also gallery example xyz.
 
 For more complicated legends, users may want to write an ASCII file with
 instructions for the layout of the legend items and pass it to the ``spec``
-parameter of :meth:`pygmt.Figure.legend`. For details on how to set up such a
-file, please see the GMT documentation at :gmt-docs:`legend.html#legend-codes`.
-Beides such an ASCII file PyGMT allows the provided a ``io.StringIO`` object.
+parameter of :meth:`pygmt.Figure.legend`. Beides such an ASCII file PyGMT
+allows the provided this information as ``io.StringIO`` object.
 
 The example blow is orientated on the upstream GMT example at
 https://docs.generic-mapping-tools.org/dev/legend.html#examples.

From 3012359ebd3477b0be1a894bfd4d6263ad74c94d Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Wed, 6 Nov 2024 12:11:32 +0100
Subject: [PATCH 04/35] Add remaining section | Move file to tutorials

---
 .../gallery/embellishments/legend_stringio.py |  68 ----------
 .../tutorials/advanced/legend_stringio.py     | 123 ++++++++++++++++++
 2 files changed, 123 insertions(+), 68 deletions(-)
 delete mode 100755 examples/gallery/embellishments/legend_stringio.py
 create mode 100755 examples/tutorials/advanced/legend_stringio.py

diff --git a/examples/gallery/embellishments/legend_stringio.py b/examples/gallery/embellishments/legend_stringio.py
deleted file mode 100755
index 4a9de5a5d36..00000000000
--- a/examples/gallery/embellishments/legend_stringio.py
+++ /dev/null
@@ -1,68 +0,0 @@
-"""
-Legend
-======
-
-The :meth:`pygmt.Figure.legend` method creates legends, whereby auto-legends as
-well as manually created legends are supported
-For auto-legends the ``label`` parameter of :meth:`pygmt.Figure.plot` has to be
-specified to state the desired text in the legend entery.
-
-Optionally, to adjust the legend, users can append different modifiers. A list
-of all available modifiers can be found at :gmt-docs:`gmt.html#l-full`.
-To create a multiple-column legend **+N** is used with the desired number of columns;
-see also gallery example xyz.
-
-For more complicated legends, users may want to write an ASCII file with
-instructions for the layout of the legend items and pass it to the ``spec``
-parameter of :meth:`pygmt.Figure.legend`. Beides such an ASCII file PyGMT
-allows the provided this information as ``io.StringIO`` object.
-
-The example blow is orientated on the upstream GMT example at
-https://docs.generic-mapping-tools.org/dev/legend.html#examples.
-"""
-
-# %%
-import io
-
-import pygmt
-
-# -----------------------------------------------------------------------------
-# Set up io.StringIO object
-spec_io = io.StringIO(
-    """
-G -0.1c
-H 24p,Times-Roman My Map Legend
-D 0.2c 1p
-N 2
-V 0 1p
-S 0.1c c 0.15c p300/12 0.25p 0.3c This circle is hachured
-S 0.1c e 0.15c yellow 0.25p 0.3c This ellipse is yellow
-S 0.1c w 0.15c green 0.25p 0.3c This wedge is green
-S 0.1c f 0.25c blue 0.25p 0.3c This is a fault
-S 0.1c - 0.15c - 0.25p,- 0.3c A contour
-S 0.1c v 0.25c magenta 0.5p 0.3c This is a vector
-S 0.1c i 0.15c cyan 0.25p 0.3c This triangle is boring
-D 0.2c 1p
-V 0 1p
-N 1
-M 5 5 600+u+f
-G 0.05c
-I @SOEST_block4.png 3i CT
-G 0.05c
-G 0.05c
-L 9p,Times-Roman R Smith et al., @%5%J. Geophys. Res., 99@%%, 2000
-G 0.1c
-T Let us just try some simple text that can go on a few lines.
-T There is no easy way to predetermine how many lines may be required
-T so we may have to adjust the height to get the right size box.
-"""
-)
-
-# -----------------------------------------------------------------------------
-# Plot legend into a figure
-fig = pygmt.Figure()
-
-# Pass io.StringIO object to the spec parameter
-fig.legend(spec=spec_io, region=[0, 10] * 2, projection="M10c", position="jMC")
-
-fig.show()
diff --git a/examples/tutorials/advanced/legend_stringio.py b/examples/tutorials/advanced/legend_stringio.py
new file mode 100755
index 00000000000..e45a93ea9f8
--- /dev/null
+++ b/examples/tutorials/advanced/legend_stringio.py
@@ -0,0 +1,123 @@
+"""
+Legend
+======
+
+The :meth:`pygmt.Figure.legend` method creates legends, whereby auto-legends as
+well as manually created legends are supported.
+
+Users can adjust the position of the legend and add box around it.
+"""
+
+# %%
+import io
+
+import pygmt
+
+# Add an auto-legend
+# ------------------
+
+# For auto-legends, the ``label`` parameter of :meth:`pygmt.Figure.plot` has to
+# be specified to state the desired text in the legend entry.
+# Optionally, to adjust the legend, users can append different modifiers.
+# A list of all available modifiers can be found at :gmt-docs:`gmt.html#l-full`.
+# To create a multiple-column legend **+N** is used with the desired number of
+# columns; see also gallery example xyz.
+
+fig = pygmt.Figure()
+
+fig.basemap(region=[0, 10] * 2, projection="M5c", frame=True)
+fig.plot(x=0, y=0, style="c0.25c", fill="orange", label="orange circle")
+fig.legend()
+
+fig.show()
+
+
+# Adjust the position
+# -------------------
+# ``position`` parameter, resets also the Defaults for box -> no box added anymore
+
+fig = pygmt.Figure()
+
+fig.basemap(region=[0, 10] * 2, projection="M5c", frame=True)
+fig.plot(x=0, y=0, style="c0.25c", fill="orange", label="orange circle")
+fig.legend(position="jMC")
+
+fig.show()
+
+
+# Add a box
+# ---------
+# ``box`` parameter, Default: p,black,thick outline with white/no fill
+# Default auf position is preserved
+
+fig = pygmt.Figure()
+
+fig.basemap(region=[0, 10] * 2, projection="M5c", frame=True)
+fig.plot(x=0, y=0, style="c0.25c", fill="orange", label="orange circle")
+fig.legend(position="jMC", box=True)
+
+fig.shift_origin(xshift="w+1c")
+
+fig.basemap(region=[0, 10] * 2, projection="M5c", frame=True)
+fig.plot(x=0, y=0, style="c0.25c", fill="orange", label="orange circle")
+fig.legend(position="jMC", box="+p2p,cyan+gblue@70")
+
+fig.show()
+
+
+# Add an manual legend
+# ---------------------
+#
+# For more complicated legends, users need to write an ASCII file with
+# instructions for the layout of the legend items and pass it to the ``spec``
+# parameter of :meth:`pygmt.Figure.legend`. Besides providing this information
+# as in the form of an ASCII file PyGMT allows to use an ``io.StringIO`` object.
+#
+# The example below is orientated on the upstream GMT example at
+# https://docs.generic-mapping-tools.org/dev/legend.html#examples.
+
+
+# %%
+# First, we set up an io.StringIO object
+
+spec_io = io.StringIO(
+    """
+G -0.1c
+H 24p,Times-Roman My Map Legend
+D 0.2c 1p
+N 2
+V 0 1p
+S 0.1c c 0.15c p300/12 0.25p 0.3c This circle is hachured
+S 0.1c e 0.15c yellow 0.25p 0.3c This ellipse is yellow
+S 0.1c w 0.15c green 0.25p 0.3c This wedge is green
+S 0.1c f 0.25c blue 0.25p 0.3c This is a fault
+S 0.1c - 0.15c - 0.25p,- 0.3c A contour
+S 0.1c v 0.25c magenta 0.5p 0.3c This is a vector
+S 0.1c i 0.15c cyan 0.25p 0.3c This triangle is boring
+D 0.2c 1p
+V 0 1p
+N 1
+M 5 5 600+u+f
+G 0.05c
+I @SOEST_block4.png 3i CT
+G 0.05c
+G 0.05c
+L 9p,Times-Roman R Smith et al., @%5%J. Geophys. Res., 99@%%, 2000
+G 0.1c
+T Let us just try some simple text that can go on a few lines.
+T There is no easy way to predetermine how many lines may be required
+T so we may have to adjust the height to get the right size box.
+"""
+)
+
+# %%
+# Now, we can add a legend based on this `io.StringIO` object.
+
+fig = pygmt.Figure()
+
+# Pass the io.StringIO object to the spec parameter
+fig.legend(spec=spec_io, region=[0, 10] * 2, projection="M10c", position="jMC")
+
+fig.show()
+
+# sphinx_gallery_thumbnail_number = 4

From 3cfefeab6038127c05a062978a06937941403e87 Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Wed, 6 Nov 2024 12:40:23 +0100
Subject: [PATCH 05/35] Add width

---
 examples/tutorials/advanced/legend_stringio.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/tutorials/advanced/legend_stringio.py b/examples/tutorials/advanced/legend_stringio.py
index e45a93ea9f8..74dc54739c7 100755
--- a/examples/tutorials/advanced/legend_stringio.py
+++ b/examples/tutorials/advanced/legend_stringio.py
@@ -116,7 +116,7 @@
 fig = pygmt.Figure()
 
 # Pass the io.StringIO object to the spec parameter
-fig.legend(spec=spec_io, region=[0, 10] * 2, projection="M10c", position="jMC")
+fig.legend(spec=spec_io, region=[0, 10] * 2, projection="M10c", position="jMC+w5c")
 
 fig.show()
 

From b81a42a9e3cfcbc782cf4f0e3ae5b0d6af295fed Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Wed, 6 Nov 2024 12:59:57 +0100
Subject: [PATCH 06/35] Fix shinx gallery layout

---
 examples/tutorials/advanced/legend_stringio.py | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/examples/tutorials/advanced/legend_stringio.py b/examples/tutorials/advanced/legend_stringio.py
index 74dc54739c7..9a675d934a3 100755
--- a/examples/tutorials/advanced/legend_stringio.py
+++ b/examples/tutorials/advanced/legend_stringio.py
@@ -13,6 +13,7 @@
 
 import pygmt
 
+# %%
 # Add an auto-legend
 # ------------------
 
@@ -32,6 +33,7 @@
 fig.show()
 
 
+# %%
 # Adjust the position
 # -------------------
 # ``position`` parameter, resets also the Defaults for box -> no box added anymore
@@ -45,6 +47,7 @@
 fig.show()
 
 
+# %%
 # Add a box
 # ---------
 # ``box`` parameter, Default: p,black,thick outline with white/no fill
@@ -65,6 +68,7 @@
 fig.show()
 
 
+# %%
 # Add an manual legend
 # ---------------------
 #

From 8ec43885a7dbb46b8709155a76a0535aba0307f7 Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Wed, 6 Nov 2024 13:03:18 +0100
Subject: [PATCH 07/35] Fix forma | Remove execution permission

---
 examples/tutorials/advanced/legend_stringio.py | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 mode change 100755 => 100644 examples/tutorials/advanced/legend_stringio.py

diff --git a/examples/tutorials/advanced/legend_stringio.py b/examples/tutorials/advanced/legend_stringio.py
old mode 100755
new mode 100644

From 17d5f1535d3abc25b0cac053773697865cbb71ea Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Wed, 6 Nov 2024 13:22:14 +0100
Subject: [PATCH 08/35] Add more documentation

---
 .../tutorials/advanced/legend_stringio.py     | 37 ++++++++++++-------
 1 file changed, 23 insertions(+), 14 deletions(-)

diff --git a/examples/tutorials/advanced/legend_stringio.py b/examples/tutorials/advanced/legend_stringio.py
index 9a675d934a3..887362407fc 100644
--- a/examples/tutorials/advanced/legend_stringio.py
+++ b/examples/tutorials/advanced/legend_stringio.py
@@ -5,7 +5,7 @@
 The :meth:`pygmt.Figure.legend` method creates legends, whereby auto-legends as
 well as manually created legends are supported.
 
-Users can adjust the position of the legend and add box around it.
+Users can adjust the position of the legend and add a box around the legend.
 """
 
 # %%
@@ -14,15 +14,16 @@
 import pygmt
 
 # %%
-# Add an auto-legend
-# ------------------
-
+# Create an auto-legend
+# ---------------------
+#
 # For auto-legends, the ``label`` parameter of :meth:`pygmt.Figure.plot` has to
 # be specified to state the desired text in the legend entry.
-# Optionally, to adjust the legend, users can append different modifiers.
-# A list of all available modifiers can be found at :gmt-docs:`gmt.html#l-full`.
-# To create a multiple-column legend **+N** is used with the desired number of
-# columns; see also gallery example xyz.
+# Optionally, to adjust the legend, users can append different modifiers to the
+# string passed to ``label`. A list of all available modifiers can be found at
+# :gmt-docs:`gmt.html#l-full`. To create a multiple-column legend **+N** is used
+# with the desired number of columns; see also gallery example
+# https://www.pygmt.org/dev/gallery/embellishments/legend.html.
 
 fig = pygmt.Figure()
 
@@ -36,7 +37,10 @@
 # %%
 # Adjust the position
 # -------------------
-# ``position`` parameter, resets also the Defaults for box -> no box added anymore
+# Use the ``position`` parameter to adjust the position of the legend.
+# j within, J outside of bounding box
+# also adjust ``width`` via **+w** modifier
+# The default of ``box`` is changed, i.e. no box plotted anymore.
 
 fig = pygmt.Figure()
 
@@ -50,8 +54,10 @@
 # %%
 # Add a box
 # ---------
-# ``box`` parameter, Default: p,black,thick outline with white/no fill
-# Default auf position is preserved
+# ``box`` parameter, Default: 1-point thick, black, solid outline with white fill.
+# The default of ``position`` is preserved.
+# **+p** for outline
+# **+g** for fill
 
 fig = pygmt.Figure()
 
@@ -69,8 +75,8 @@
 
 
 # %%
-# Add an manual legend
-# ---------------------
+# Create a manual legend
+# ----------------------
 #
 # For more complicated legends, users need to write an ASCII file with
 # instructions for the layout of the legend items and pass it to the ``spec``
@@ -116,11 +122,14 @@
 
 # %%
 # Now, we can add a legend based on this `io.StringIO` object.
+#
+# width (``position`` parameter) required for multi-columns legends!
 
 fig = pygmt.Figure()
 
 # Pass the io.StringIO object to the spec parameter
-fig.legend(spec=spec_io, region=[0, 10] * 2, projection="M10c", position="jMC+w5c")
+fig.basemap(region=[0, 10] * 2, projection="M10c", frame=0)
+fig.legend(spec=spec_io, position="jMC+w5c", box="+p1p,gray50+ggray90")
 
 fig.show()
 

From f4293426db5a3309a61a930714f5c081be04e65e Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Wed, 6 Nov 2024 13:28:43 +0100
Subject: [PATCH 09/35] Use Cartesian projection

---
 .../tutorials/advanced/legend_stringio.py     | 20 +++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/examples/tutorials/advanced/legend_stringio.py b/examples/tutorials/advanced/legend_stringio.py
index 887362407fc..c2e15a5687b 100644
--- a/examples/tutorials/advanced/legend_stringio.py
+++ b/examples/tutorials/advanced/legend_stringio.py
@@ -18,16 +18,16 @@
 # ---------------------
 #
 # For auto-legends, the ``label`` parameter of :meth:`pygmt.Figure.plot` has to
-# be specified to state the desired text in the legend entry.
-# Optionally, to adjust the legend, users can append different modifiers to the
-# string passed to ``label`. A list of all available modifiers can be found at
-# :gmt-docs:`gmt.html#l-full`. To create a multiple-column legend **+N** is used
-# with the desired number of columns; see also gallery example
+# be specified to state the desired text in the legend entry (white spaces are
+# allowed) Optionally, to adjust the legend, users can append different modifiers
+# to the string passed to ``label`. A list of all available modifiers can be
+# found at :gmt-docs:`gmt.html#l-full`. To create a multiple-column legend **+N**
+# is used with the desired number of columns; see also gallery example
 # https://www.pygmt.org/dev/gallery/embellishments/legend.html.
 
 fig = pygmt.Figure()
+fig.basemap(region=[-5, 5] * 2, projection="X5c", frame=True)
 
-fig.basemap(region=[0, 10] * 2, projection="M5c", frame=True)
 fig.plot(x=0, y=0, style="c0.25c", fill="orange", label="orange circle")
 fig.legend()
 
@@ -43,8 +43,8 @@
 # The default of ``box`` is changed, i.e. no box plotted anymore.
 
 fig = pygmt.Figure()
+fig.basemap(region=[-5, 5] * 2, projection="X5c", frame=True)
 
-fig.basemap(region=[0, 10] * 2, projection="M5c", frame=True)
 fig.plot(x=0, y=0, style="c0.25c", fill="orange", label="orange circle")
 fig.legend(position="jMC")
 
@@ -60,14 +60,14 @@
 # **+g** for fill
 
 fig = pygmt.Figure()
+fig.basemap(region=[-5, 5] * 2, projection="X5c", frame=True)
 
-fig.basemap(region=[0, 10] * 2, projection="M5c", frame=True)
 fig.plot(x=0, y=0, style="c0.25c", fill="orange", label="orange circle")
 fig.legend(position="jMC", box=True)
 
 fig.shift_origin(xshift="w+1c")
+fig.basemap(region=[-5, 5] * 2, projection="X5c", frame=True)
 
-fig.basemap(region=[0, 10] * 2, projection="M5c", frame=True)
 fig.plot(x=0, y=0, style="c0.25c", fill="orange", label="orange circle")
 fig.legend(position="jMC", box="+p2p,cyan+gblue@70")
 
@@ -126,9 +126,9 @@
 # width (``position`` parameter) required for multi-columns legends!
 
 fig = pygmt.Figure()
+fig.basemap(region=[-5, 5] * 2, projection="X10c", frame=True)
 
 # Pass the io.StringIO object to the spec parameter
-fig.basemap(region=[0, 10] * 2, projection="M10c", frame=0)
 fig.legend(spec=spec_io, position="jMC+w5c", box="+p1p,gray50+ggray90")
 
 fig.show()

From 9633aadb8d50a94a6a6785f849ed3786ed40475d Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Wed, 6 Nov 2024 13:30:04 +0100
Subject: [PATCH 10/35] Update title

---
 examples/tutorials/advanced/legend_stringio.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/tutorials/advanced/legend_stringio.py b/examples/tutorials/advanced/legend_stringio.py
index c2e15a5687b..88f10218906 100644
--- a/examples/tutorials/advanced/legend_stringio.py
+++ b/examples/tutorials/advanced/legend_stringio.py
@@ -1,6 +1,6 @@
 """
-Legend
-======
+Creating legends
+================
 
 The :meth:`pygmt.Figure.legend` method creates legends, whereby auto-legends as
 well as manually created legends are supported.

From 4fe847348abf99e669daf81875d238fe6649a13a Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Wed, 6 Nov 2024 13:30:56 +0100
Subject: [PATCH 11/35] Adjust file name

---
 examples/tutorials/advanced/{legend_stringio.py => legends.py} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename examples/tutorials/advanced/{legend_stringio.py => legends.py} (100%)

diff --git a/examples/tutorials/advanced/legend_stringio.py b/examples/tutorials/advanced/legends.py
similarity index 100%
rename from examples/tutorials/advanced/legend_stringio.py
rename to examples/tutorials/advanced/legends.py

From b6f60456ac744988e9595f7cb4ef8dc60b40aa58 Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Wed, 6 Nov 2024 13:33:53 +0100
Subject: [PATCH 12/35] Use Mercator projection

---
 examples/tutorials/advanced/legends.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
index 88f10218906..fcf6da9bddf 100644
--- a/examples/tutorials/advanced/legends.py
+++ b/examples/tutorials/advanced/legends.py
@@ -126,7 +126,7 @@
 # width (``position`` parameter) required for multi-columns legends!
 
 fig = pygmt.Figure()
-fig.basemap(region=[-5, 5] * 2, projection="X10c", frame=True)
+fig.basemap(region=[-5, 5] * 2, projection="M10c", frame=True)
 
 # Pass the io.StringIO object to the spec parameter
 fig.legend(spec=spec_io, position="jMC+w5c", box="+p1p,gray50+ggray90")

From bf84f6a8912275bb873a59ad02a2a6cacb4a0793 Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Wed, 6 Nov 2024 13:34:45 +0100
Subject: [PATCH 13/35] Adjust position of example data point

---
 examples/tutorials/advanced/legends.py | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
index fcf6da9bddf..e4ed0592892 100644
--- a/examples/tutorials/advanced/legends.py
+++ b/examples/tutorials/advanced/legends.py
@@ -28,7 +28,7 @@
 fig = pygmt.Figure()
 fig.basemap(region=[-5, 5] * 2, projection="X5c", frame=True)
 
-fig.plot(x=0, y=0, style="c0.25c", fill="orange", label="orange circle")
+fig.plot(x=0, y=-3, style="c0.25c", fill="orange", label="orange circle")
 fig.legend()
 
 fig.show()
@@ -45,7 +45,7 @@
 fig = pygmt.Figure()
 fig.basemap(region=[-5, 5] * 2, projection="X5c", frame=True)
 
-fig.plot(x=0, y=0, style="c0.25c", fill="orange", label="orange circle")
+fig.plot(x=0, y=-3, style="c0.25c", fill="orange", label="orange circle")
 fig.legend(position="jMC")
 
 fig.show()
@@ -62,13 +62,13 @@
 fig = pygmt.Figure()
 fig.basemap(region=[-5, 5] * 2, projection="X5c", frame=True)
 
-fig.plot(x=0, y=0, style="c0.25c", fill="orange", label="orange circle")
+fig.plot(x=0, y=-3, style="c0.25c", fill="orange", label="orange circle")
 fig.legend(position="jMC", box=True)
 
 fig.shift_origin(xshift="w+1c")
 fig.basemap(region=[-5, 5] * 2, projection="X5c", frame=True)
 
-fig.plot(x=0, y=0, style="c0.25c", fill="orange", label="orange circle")
+fig.plot(x=0, y=-3, style="c0.25c", fill="orange", label="orange circle")
 fig.legend(position="jMC", box="+p2p,cyan+gblue@70")
 
 fig.show()

From ac0b46904aaf207849fee9d63030df55d551827a Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Wed, 6 Nov 2024 13:40:14 +0100
Subject: [PATCH 14/35] Adjust width of legend

---
 examples/tutorials/advanced/legends.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
index e4ed0592892..ddf6e2d4d3d 100644
--- a/examples/tutorials/advanced/legends.py
+++ b/examples/tutorials/advanced/legends.py
@@ -129,7 +129,7 @@
 fig.basemap(region=[-5, 5] * 2, projection="M10c", frame=True)
 
 # Pass the io.StringIO object to the spec parameter
-fig.legend(spec=spec_io, position="jMC+w5c", box="+p1p,gray50+ggray90")
+fig.legend(spec=spec_io, position="jMC+w9c", box="+p1p,gray50+ggray95")
 
 fig.show()
 

From e4a966bec523ff822112b9f35931c84e2db1bb5e Mon Sep 17 00:00:00 2001
From: Yvonne <yvonne.froehlich@kite.edu>
Date: Sun, 10 Nov 2024 11:48:19 +0000
Subject: [PATCH 15/35] Improve docs

---
 examples/tutorials/advanced/legends.py | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
index ddf6e2d4d3d..e24625af94e 100644
--- a/examples/tutorials/advanced/legends.py
+++ b/examples/tutorials/advanced/legends.py
@@ -78,17 +78,18 @@
 # Create a manual legend
 # ----------------------
 #
-# For more complicated legends, users need to write an ASCII file with
-# instructions for the layout of the legend items and pass it to the ``spec``
-# parameter of :meth:`pygmt.Figure.legend`. Besides providing this information
-# as in the form of an ASCII file PyGMT allows to use an ``io.StringIO`` object.
+# For more complicated legends in GMT, users need to write an ASCII file with
+# instructions for the layout of the legend items. In PyGMT it is addionaly
+# possible to provide this information as an ``io.StringIO`` object. Both, the
+# ASCII file or the ``io.StringIO`` object are passed to the ``spec`` parameter
+# of :meth:`pygmt.Figure.legend`.
 #
 # The example below is orientated on the upstream GMT example at
 # https://docs.generic-mapping-tools.org/dev/legend.html#examples.
 
 
 # %%
-# First, we set up an io.StringIO object
+# First, we set up an ``io.StringIO`` object.
 
 spec_io = io.StringIO(
     """
@@ -121,9 +122,9 @@
 )
 
 # %%
-# Now, we can add a legend based on this `io.StringIO` object.
-#
-# width (``position`` parameter) required for multi-columns legends!
+# Now, we can add a legend based on this `io.StringIO` object. For
+# multi-columns legends, width (**+w**) has to be specified via a the
+# ``position`` parameter.
 
 fig = pygmt.Figure()
 fig.basemap(region=[-5, 5] * 2, projection="M10c", frame=True)

From e0ef881cca180a9a456055be9e90fdf2de4cced2 Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Sun, 10 Nov 2024 18:11:21 +0100
Subject: [PATCH 16/35] Use long list for 'region' | Fix typo | Improve
 comments

---
 examples/tutorials/advanced/legends.py | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
index e24625af94e..2745467632c 100644
--- a/examples/tutorials/advanced/legends.py
+++ b/examples/tutorials/advanced/legends.py
@@ -19,14 +19,14 @@
 #
 # For auto-legends, the ``label`` parameter of :meth:`pygmt.Figure.plot` has to
 # be specified to state the desired text in the legend entry (white spaces are
-# allowed) Optionally, to adjust the legend, users can append different modifiers
+# allowed). Optionally, to adjust the legend, users can append different modifiers
 # to the string passed to ``label`. A list of all available modifiers can be
 # found at :gmt-docs:`gmt.html#l-full`. To create a multiple-column legend **+N**
 # is used with the desired number of columns; see also gallery example
 # https://www.pygmt.org/dev/gallery/embellishments/legend.html.
 
 fig = pygmt.Figure()
-fig.basemap(region=[-5, 5] * 2, projection="X5c", frame=True)
+fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
 
 fig.plot(x=0, y=-3, style="c0.25c", fill="orange", label="orange circle")
 fig.legend()
@@ -43,7 +43,7 @@
 # The default of ``box`` is changed, i.e. no box plotted anymore.
 
 fig = pygmt.Figure()
-fig.basemap(region=[-5, 5] * 2, projection="X5c", frame=True)
+fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
 
 fig.plot(x=0, y=-3, style="c0.25c", fill="orange", label="orange circle")
 fig.legend(position="jMC")
@@ -60,13 +60,13 @@
 # **+g** for fill
 
 fig = pygmt.Figure()
-fig.basemap(region=[-5, 5] * 2, projection="X5c", frame=True)
+fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
 
 fig.plot(x=0, y=-3, style="c0.25c", fill="orange", label="orange circle")
 fig.legend(position="jMC", box=True)
 
 fig.shift_origin(xshift="w+1c")
-fig.basemap(region=[-5, 5] * 2, projection="X5c", frame=True)
+fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
 
 fig.plot(x=0, y=-3, style="c0.25c", fill="orange", label="orange circle")
 fig.legend(position="jMC", box="+p2p,cyan+gblue@70")
@@ -127,7 +127,8 @@
 # ``position`` parameter.
 
 fig = pygmt.Figure()
-fig.basemap(region=[-5, 5] * 2, projection="M10c", frame=True)
+# Note, that we are now using a Mercator projection
+fig.basemap(region=[-5, 5, -5, 5], projection="M10c", frame=True)
 
 # Pass the io.StringIO object to the spec parameter
 fig.legend(spec=spec_io, position="jMC+w9c", box="+p1p,gray50+ggray95")

From 46e8340baed882e30b5fcc8ded40666ac6987d57 Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Mon, 11 Nov 2024 09:05:45 +0100
Subject: [PATCH 17/35] Adjust position of legend instead of datapoint

---
 examples/tutorials/advanced/legends.py | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
index 2745467632c..57448136313 100644
--- a/examples/tutorials/advanced/legends.py
+++ b/examples/tutorials/advanced/legends.py
@@ -28,7 +28,7 @@
 fig = pygmt.Figure()
 fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
 
-fig.plot(x=0, y=-3, style="c0.25c", fill="orange", label="orange circle")
+fig.plot(x=0, y=0, style="c0.25c", fill="orange", label="orange circle")
 fig.legend()
 
 fig.show()
@@ -39,14 +39,15 @@
 # -------------------
 # Use the ``position`` parameter to adjust the position of the legend.
 # j within, J outside of bounding box
+# offset via **+o**
 # also adjust ``width`` via **+w** modifier
 # The default of ``box`` is changed, i.e. no box plotted anymore.
 
 fig = pygmt.Figure()
 fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
 
-fig.plot(x=0, y=-3, style="c0.25c", fill="orange", label="orange circle")
-fig.legend(position="jMC")
+fig.plot(x=0, y=0, style="c0.25c", fill="orange", label="orange circle")
+fig.legend(position="jLT+o0.3c/0.2c")
 
 fig.show()
 
@@ -62,14 +63,14 @@
 fig = pygmt.Figure()
 fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
 
-fig.plot(x=0, y=-3, style="c0.25c", fill="orange", label="orange circle")
-fig.legend(position="jMC", box=True)
+fig.plot(x=0, y=0, style="c0.25c", fill="orange", label="orange circle")
+fig.legend(position="jTL+o0.3c/0.2c", box=True)
 
 fig.shift_origin(xshift="w+1c")
 fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
 
-fig.plot(x=0, y=-3, style="c0.25c", fill="orange", label="orange circle")
-fig.legend(position="jMC", box="+p2p,cyan+gblue@70")
+fig.plot(x=0, y=0, style="c0.25c", fill="orange", label="orange circle")
+fig.legend(position="jTL+o0.3c/0.2c", box="+p2p,cyan+gblue@70")
 
 fig.show()
 

From 907c2196bb35f7dcfb8d3a2365f9099f45af4f56 Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Mon, 11 Nov 2024 13:16:07 +0100
Subject: [PATCH 18/35] Add docs

---
 examples/tutorials/advanced/legends.py | 23 ++++++++++++++---------
 1 file changed, 14 insertions(+), 9 deletions(-)

diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
index 57448136313..ba5e730ec7a 100644
--- a/examples/tutorials/advanced/legends.py
+++ b/examples/tutorials/advanced/legends.py
@@ -24,6 +24,9 @@
 # found at :gmt-docs:`gmt.html#l-full`. To create a multiple-column legend **+N**
 # is used with the desired number of columns; see also gallery example
 # https://www.pygmt.org/dev/gallery/embellishments/legend.html.
+# By default, the legend is placed in the Upper Right corner with an offset of 0.1
+# centimeters in x and y directions and a box with white fill and a 1-point thick,
+# black, solid outline is drawn around the legend.
 
 fig = pygmt.Figure()
 fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
@@ -37,11 +40,12 @@
 # %%
 # Adjust the position
 # -------------------
-# Use the ``position`` parameter to adjust the position of the legend.
-# j within, J outside of bounding box
-# offset via **+o**
-# also adjust ``width`` via **+w** modifier
-# The default of ``box`` is changed, i.e. no box plotted anymore.
+# Use the ``position`` parameter to adjust the position of the legend. For the
+# different ways to specifiy the placement of an plotting element (e.g., legends,
+# colorbars) on a plot in GMT, please refer to the Technical Reference TODO (: .
+# Add an offset via **+o** for the x and y directions. Addionally append **+w**
+# to adjust the ``width of the legenth. Note, no box is drawn by default if
+# ``position`` is used.
 
 fig = pygmt.Figure()
 fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
@@ -55,10 +59,11 @@
 # %%
 # Add a box
 # ---------
-# ``box`` parameter, Default: 1-point thick, black, solid outline with white fill.
-# The default of ``position`` is preserved.
-# **+p** for outline
-# **+g** for fill
+# Use the ``box`` parameter for adjusting the box around the legend. Append
+# **g+** to fill the legend with a color or pattern [Default is a white fill].
+# The outline of the box an be adjusted by appending **p**. The default of
+# ``position`` is preserved.
+
 
 fig = pygmt.Figure()
 fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)

From 92f76bc09a190e4362f654bc90cc32c9fce80f29 Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Mon, 11 Nov 2024 13:39:12 +0100
Subject: [PATCH 19/35] Fix highlighting | Remove sentence

---
 examples/tutorials/advanced/legends.py | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
index ba5e730ec7a..7ce2301b167 100644
--- a/examples/tutorials/advanced/legends.py
+++ b/examples/tutorials/advanced/legends.py
@@ -4,8 +4,6 @@
 
 The :meth:`pygmt.Figure.legend` method creates legends, whereby auto-legends as
 well as manually created legends are supported.
-
-Users can adjust the position of the legend and add a box around the legend.
 """
 
 # %%
@@ -128,7 +126,7 @@
 )
 
 # %%
-# Now, we can add a legend based on this `io.StringIO` object. For
+# Now, we can add a legend based on this ``io.StringIO`` object. For
 # multi-columns legends, width (**+w**) has to be specified via a the
 # ``position`` parameter.
 

From f806a06e5ed0f57d743bdaa12781104a137eacf6 Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Tue, 12 Nov 2024 00:33:42 +0100
Subject: [PATCH 20/35] Fix typos

---
 examples/tutorials/advanced/legends.py | 42 +++++++++++++-------------
 1 file changed, 21 insertions(+), 21 deletions(-)

diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
index 7ce2301b167..e69f8b8e747 100644
--- a/examples/tutorials/advanced/legends.py
+++ b/examples/tutorials/advanced/legends.py
@@ -2,8 +2,8 @@
 Creating legends
 ================
 
-The :meth:`pygmt.Figure.legend` method creates legends, whereby auto-legends as
-well as manually created legends are supported.
+The :meth:`pygmt.Figure.legend` method creates legends, whereby auto-legends as well
+as manually created legends are supported.
 """
 
 # %%
@@ -15,16 +15,16 @@
 # Create an auto-legend
 # ---------------------
 #
-# For auto-legends, the ``label`` parameter of :meth:`pygmt.Figure.plot` has to
-# be specified to state the desired text in the legend entry (white spaces are
-# allowed). Optionally, to adjust the legend, users can append different modifiers
-# to the string passed to ``label`. A list of all available modifiers can be
-# found at :gmt-docs:`gmt.html#l-full`. To create a multiple-column legend **+N**
-# is used with the desired number of columns; see also gallery example
+# For auto-legends, the ``label`` parameter of :meth:`pygmt.Figure.plot` has to be
+# specified to state the desired text in the legend entry (white spaces are allowed).
+# Optionally, to adjust the legend, users can append different modifiers to the string
+# passed to ``label``. A list of all available modifiers can be found at
+# :gmt-docs:`gmt.html#l-full`. To create a multiple-column legend **+N** is used with
+# the desired number of columns; for details see the gallery example
 # https://www.pygmt.org/dev/gallery/embellishments/legend.html.
 # By default, the legend is placed in the Upper Right corner with an offset of 0.1
-# centimeters in x and y directions and a box with white fill and a 1-point thick,
-# black, solid outline is drawn around the legend.
+# centimeters in both x and y directions and a box with a white fill and a 1-point
+# thick, black, solid outline is drawn around the legend.
 
 fig = pygmt.Figure()
 fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
@@ -39,10 +39,10 @@
 # Adjust the position
 # -------------------
 # Use the ``position`` parameter to adjust the position of the legend. For the
-# different ways to specifiy the placement of an plotting element (e.g., legends,
+# different ways to specify the placement of a plotting element (e.g., legends,
 # colorbars) on a plot in GMT, please refer to the Technical Reference TODO (: .
-# Add an offset via **+o** for the x and y directions. Addionally append **+w**
-# to adjust the ``width of the legenth. Note, no box is drawn by default if
+# Add an offset via **+o** for the x and y directions. Additionally append **+w**
+# to adjust the ``width`` of the length. Note, no box is drawn by default if
 # ``position`` is used.
 
 fig = pygmt.Figure()
@@ -57,9 +57,9 @@
 # %%
 # Add a box
 # ---------
-# Use the ``box`` parameter for adjusting the box around the legend. Append
-# **g+** to fill the legend with a color or pattern [Default is a white fill].
-# The outline of the box an be adjusted by appending **p**. The default of
+# Use the ``box`` parameter for adjusting the box around the legend. Append **+g**
+# to fill the legend with a color (or pattern) [Default is a white fill]. The
+# outline of the box can be adjusted by appending **+p**. The default of
 # ``position`` is preserved.
 
 
@@ -83,7 +83,7 @@
 # ----------------------
 #
 # For more complicated legends in GMT, users need to write an ASCII file with
-# instructions for the layout of the legend items. In PyGMT it is addionaly
+# instructions for the layout of the legend items. In PyGMT it is additionally
 # possible to provide this information as an ``io.StringIO`` object. Both, the
 # ASCII file or the ``io.StringIO`` object are passed to the ``spec`` parameter
 # of :meth:`pygmt.Figure.legend`.
@@ -126,15 +126,15 @@
 )
 
 # %%
-# Now, we can add a legend based on this ``io.StringIO`` object. For
-# multi-columns legends, width (**+w**) has to be specified via a the
-# ``position`` parameter.
+# Now, we can add a legend based on this ``io.StringIO`` object. For multi-
+# columns legends, width (**+w**) has to be specified via a the ``position``
+# parameter.
 
 fig = pygmt.Figure()
 # Note, that we are now using a Mercator projection
 fig.basemap(region=[-5, 5, -5, 5], projection="M10c", frame=True)
 
-# Pass the io.StringIO object to the spec parameter
+# Pass the io.StringIO object to the "spec" parameter
 fig.legend(spec=spec_io, position="jMC+w9c", box="+p1p,gray50+ggray95")
 
 fig.show()

From de182e8ad40e3002b0d316bef0c449ec06a11ef8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?=
 <94163266+yvonnefroehlich@users.noreply.github.com>
Date: Tue, 12 Nov 2024 00:37:50 +0100
Subject: [PATCH 21/35] Add highighting

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>
---
 examples/tutorials/advanced/legends.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
index e69f8b8e747..5b42b48558a 100644
--- a/examples/tutorials/advanced/legends.py
+++ b/examples/tutorials/advanced/legends.py
@@ -84,8 +84,8 @@
 #
 # For more complicated legends in GMT, users need to write an ASCII file with
 # instructions for the layout of the legend items. In PyGMT it is additionally
-# possible to provide this information as an ``io.StringIO`` object. Both, the
-# ASCII file or the ``io.StringIO`` object are passed to the ``spec`` parameter
+# possible to provide this information as an :class:`io.StringIO` object. Both, the
+# ASCII file or the :class:`io.StringIO` object are passed to the ``spec`` parameter
 # of :meth:`pygmt.Figure.legend`.
 #
 # The example below is orientated on the upstream GMT example at
@@ -93,7 +93,7 @@
 
 
 # %%
-# First, we set up an ``io.StringIO`` object.
+# First, we set up an :class:`io.StringIO` object.
 
 spec_io = io.StringIO(
     """

From 70774970fbbd89a1a4fd0e503aa976aeca4c3e94 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?=
 <94163266+yvonnefroehlich@users.noreply.github.com>
Date: Tue, 12 Nov 2024 00:38:35 +0100
Subject: [PATCH 22/35] Use link syntax

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>
---
 examples/tutorials/advanced/legends.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
index 5b42b48558a..5917107611e 100644
--- a/examples/tutorials/advanced/legends.py
+++ b/examples/tutorials/advanced/legends.py
@@ -21,7 +21,7 @@
 # passed to ``label``. A list of all available modifiers can be found at
 # :gmt-docs:`gmt.html#l-full`. To create a multiple-column legend **+N** is used with
 # the desired number of columns; for details see the gallery example
-# https://www.pygmt.org/dev/gallery/embellishments/legend.html.
+# :doc:`</gallery/embellishments/legend>`.
 # By default, the legend is placed in the Upper Right corner with an offset of 0.1
 # centimeters in both x and y directions and a box with a white fill and a 1-point
 # thick, black, solid outline is drawn around the legend.

From 991d56f955e564fb02daafa828680c13f62be234 Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Tue, 12 Nov 2024 00:43:56 +0100
Subject: [PATCH 23/35] Add hilighting

---
 examples/tutorials/advanced/legends.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
index 5917107611e..9dd3157c24c 100644
--- a/examples/tutorials/advanced/legends.py
+++ b/examples/tutorials/advanced/legends.py
@@ -126,9 +126,9 @@
 )
 
 # %%
-# Now, we can add a legend based on this ``io.StringIO`` object. For multi-
-# columns legends, width (**+w**) has to be specified via a the ``position``
-# parameter.
+# Now, we can add a legend based on this :class:`io.StringIO` object. For
+# multi- columns legends, width (**+w**) has to be specified via a the
+# ``position`` parameter.
 
 fig = pygmt.Figure()
 # Note, that we are now using a Mercator projection

From 4e9d842dedc3062dd27c26c385756a7e62bed85a Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Tue, 12 Nov 2024 00:57:42 +0100
Subject: [PATCH 24/35] Fix link

---
 examples/tutorials/advanced/legends.py | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
index 9dd3157c24c..a419dcc40ca 100644
--- a/examples/tutorials/advanced/legends.py
+++ b/examples/tutorials/advanced/legends.py
@@ -19,12 +19,11 @@
 # specified to state the desired text in the legend entry (white spaces are allowed).
 # Optionally, to adjust the legend, users can append different modifiers to the string
 # passed to ``label``. A list of all available modifiers can be found at
-# :gmt-docs:`gmt.html#l-full`. To create a multiple-column legend **+N** is used with
-# the desired number of columns; for details see the gallery example
-# :doc:`</gallery/embellishments/legend>`.
-# By default, the legend is placed in the Upper Right corner with an offset of 0.1
-# centimeters in both x and y directions and a box with a white fill and a 1-point
-# thick, black, solid outline is drawn around the legend.
+# :gmt-docs:`gmt.html#l-full`. To create a
+# :doc:`multiple-column legend </gallery/embellishments/legend>` **+N** is used with
+# the desired number of columns. By default, the legend is placed in the Upper Right
+# corner with an offset of 0.1 centimeters in both x and y directions and a box with
+# a white fill and a 1-point thick, black, solid outline is drawn around the legend.
 
 fig = pygmt.Figure()
 fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)

From 49773b491774e44ca43e45ca8be89837c7d1dc0d Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Tue, 12 Nov 2024 18:15:20 +0100
Subject: [PATCH 25/35] Mention other plotting method with have the 'label'
 parameter for legend

---
 examples/tutorials/advanced/legends.py | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
index a419dcc40ca..b55e067c7ef 100644
--- a/examples/tutorials/advanced/legends.py
+++ b/examples/tutorials/advanced/legends.py
@@ -15,15 +15,17 @@
 # Create an auto-legend
 # ---------------------
 #
-# For auto-legends, the ``label`` parameter of :meth:`pygmt.Figure.plot` has to be
-# specified to state the desired text in the legend entry (white spaces are allowed).
-# Optionally, to adjust the legend, users can append different modifiers to the string
-# passed to ``label``. A list of all available modifiers can be found at
-# :gmt-docs:`gmt.html#l-full`. To create a
-# :doc:`multiple-column legend </gallery/embellishments/legend>` **+N** is used with
-# the desired number of columns. By default, the legend is placed in the Upper Right
-# corner with an offset of 0.1 centimeters in both x and y directions and a box with
-# a white fill and a 1-point thick, black, solid outline is drawn around the legend.
+# An auto-legend can be created for the methods :meth:`pygmt.Figure.plot`,
+# :meth:`pygmt.Figure.plot3d`, and :meth:`pygmt.Figure.histogram`. Therefore the
+# ``label`` parameter has to be specified to state the desired text for the legend
+# entry (white spaces are supported). Here, we focus on :meth:`pygmt.Figure.plot`,
+# examplarly. By default, the legend is placed in the Upper Right corner with an
+# offset of 0.1 centimeters in both x and y directions and a box with a white fill
+# and a 1-point thick, black, solid outline is drawn around the legend. Optionally,
+# to adjust the legend, users can append different modifiers to the string passed
+# to ``label``. For a list of available modifiers see :gmt-docs:`gmt.html#l-full`.
+# To create a :doc:`multiple-column legend </gallery/embellishments/legend>` **+N**
+# is used with the desired number of columns.
 
 fig = pygmt.Figure()
 fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)

From a47babf5343f3bb1f32d1f4831d06d77ff4e66e0 Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Tue, 12 Nov 2024 18:34:49 +0100
Subject: [PATCH 26/35] Use multiple symbols to show legend layout

---
 examples/tutorials/advanced/legends.py | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
index b55e067c7ef..1506f959a96 100644
--- a/examples/tutorials/advanced/legends.py
+++ b/examples/tutorials/advanced/legends.py
@@ -18,11 +18,12 @@
 # An auto-legend can be created for the methods :meth:`pygmt.Figure.plot`,
 # :meth:`pygmt.Figure.plot3d`, and :meth:`pygmt.Figure.histogram`. Therefore the
 # ``label`` parameter has to be specified to state the desired text for the legend
-# entry (white spaces are supported). Here, we focus on :meth:`pygmt.Figure.plot`,
+# entry (white spaces are supported). Here, we use :meth:`pygmt.Figure.plot`,
 # examplarly. By default, the legend is placed in the Upper Right corner with an
 # offset of 0.1 centimeters in both x and y directions and a box with a white fill
-# and a 1-point thick, black, solid outline is drawn around the legend. Optionally,
-# to adjust the legend, users can append different modifiers to the string passed
+# and a 1-point thick, black, solid outline is drawn around the legend. The order
+# of the legend entries (top to bottom) is determine by the plotting order.
+# Optionally, to adjust the legend, append different modifiers to the string passed
 # to ``label``. For a list of available modifiers see :gmt-docs:`gmt.html#l-full`.
 # To create a :doc:`multiple-column legend </gallery/embellishments/legend>` **+N**
 # is used with the desired number of columns.
@@ -30,7 +31,12 @@
 fig = pygmt.Figure()
 fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
 
+# Plot three data points with different symbols and sizes
 fig.plot(x=0, y=0, style="c0.25c", fill="orange", label="orange circle")
+fig.plot(x=1, y=0, style="t0.3c", fill="pink", label="pink triangle")
+fig.plot(x=-1, y=0, style="s0.3c", fill="darkred", label="darkred square")
+
+# Add a legend based on the explanation text given via the "label" parameter
 fig.legend()
 
 fig.show()
@@ -50,6 +56,10 @@
 fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
 
 fig.plot(x=0, y=0, style="c0.25c", fill="orange", label="orange circle")
+fig.plot(x=1, y=0, style="t0.3c", fill="pink", label="pink triangle")
+fig.plot(x=-1, y=0, style="s0.3c", fill="darkred", label="darkred square")
+
+# Left Top
 fig.legend(position="jLT+o0.3c/0.2c")
 
 fig.show()
@@ -68,12 +78,16 @@
 fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
 
 fig.plot(x=0, y=0, style="c0.25c", fill="orange", label="orange circle")
+fig.plot(x=1, y=0, style="t0.3c", fill="pink", label="pink triangle")
+fig.plot(x=-1, y=0, style="s0.3c", fill="darkred", label="darkred square")
 fig.legend(position="jTL+o0.3c/0.2c", box=True)
 
 fig.shift_origin(xshift="w+1c")
 fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
 
 fig.plot(x=0, y=0, style="c0.25c", fill="orange", label="orange circle")
+fig.plot(x=1, y=0, style="t0.3c", fill="pink", label="pink triangle")
+fig.plot(x=-1, y=0, style="s0.3c", fill="darkred", label="darkred square")
 fig.legend(position="jTL+o0.3c/0.2c", box="+p2p,cyan+gblue@70")
 
 fig.show()

From a36710181729b1bdb563a3b8d7ea6a8f9d19081d Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Tue, 12 Nov 2024 18:42:50 +0100
Subject: [PATCH 27/35] Improve docs

---
 examples/tutorials/advanced/legends.py | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
index 1506f959a96..aa53aa6ae8d 100644
--- a/examples/tutorials/advanced/legends.py
+++ b/examples/tutorials/advanced/legends.py
@@ -68,11 +68,10 @@
 # %%
 # Add a box
 # ---------
-# Use the ``box`` parameter for adjusting the box around the legend. Append **+g**
-# to fill the legend with a color (or pattern) [Default is a white fill]. The
-# outline of the box can be adjusted by appending **+p**. The default of
-# ``position`` is preserved.
-
+# Use the ``box`` parameter for adjusting the box around the legend. The outline
+# of the box can be adjusted by appending **+p**. Append **+g** to fill the legend
+# with a color (or pattern) [Default is a white fill]. The default of ``position``
+# is preserved.
 
 fig = pygmt.Figure()
 fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
@@ -80,6 +79,7 @@
 fig.plot(x=0, y=0, style="c0.25c", fill="orange", label="orange circle")
 fig.plot(x=1, y=0, style="t0.3c", fill="pink", label="pink triangle")
 fig.plot(x=-1, y=0, style="s0.3c", fill="darkred", label="darkred square")
+
 fig.legend(position="jTL+o0.3c/0.2c", box=True)
 
 fig.shift_origin(xshift="w+1c")
@@ -88,6 +88,7 @@
 fig.plot(x=0, y=0, style="c0.25c", fill="orange", label="orange circle")
 fig.plot(x=1, y=0, style="t0.3c", fill="pink", label="pink triangle")
 fig.plot(x=-1, y=0, style="s0.3c", fill="darkred", label="darkred square")
+
 fig.legend(position="jTL+o0.3c/0.2c", box="+p2p,cyan+gblue@70")
 
 fig.show()

From db75fee08367f177cf730e56ed690ad427885e35 Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Tue, 12 Nov 2024 18:45:00 +0100
Subject: [PATCH 28/35] Add blank line

---
 examples/tutorials/advanced/legends.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
index aa53aa6ae8d..085108a2827 100644
--- a/examples/tutorials/advanced/legends.py
+++ b/examples/tutorials/advanced/legends.py
@@ -45,6 +45,7 @@
 # %%
 # Adjust the position
 # -------------------
+#
 # Use the ``position`` parameter to adjust the position of the legend. For the
 # different ways to specify the placement of a plotting element (e.g., legends,
 # colorbars) on a plot in GMT, please refer to the Technical Reference TODO (: .

From eb721313819f8b43f8f5d8ac05b03e75483f5dd9 Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Tue, 12 Nov 2024 18:50:17 +0100
Subject: [PATCH 29/35] Add comments

---
 examples/tutorials/advanced/legends.py | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
index 085108a2827..8ddfa44b32d 100644
--- a/examples/tutorials/advanced/legends.py
+++ b/examples/tutorials/advanced/legends.py
@@ -60,7 +60,8 @@
 fig.plot(x=1, y=0, style="t0.3c", fill="pink", label="pink triangle")
 fig.plot(x=-1, y=0, style="s0.3c", fill="darkred", label="darkred square")
 
-# Left Top
+# Set the reference point to Left Top and use an offset of 0.3 and 0.2 centimeters
+# in the x and y directions, respectively
 fig.legend(position="jLT+o0.3c/0.2c")
 
 fig.show()
@@ -69,9 +70,9 @@
 # %%
 # Add a box
 # ---------
-# Use the ``box`` parameter for adjusting the box around the legend. The outline
-# of the box can be adjusted by appending **+p**. Append **+g** to fill the legend
-# with a color (or pattern) [Default is a white fill]. The default of ``position``
+# Use the ``box`` parameter for adjusting the box around the legend. The outline of
+# the box can be adjusted by appending **+p**. Append **+g** to fill the legend with
+# a color (or pattern) [Default is a white fill]. The default of ``position`` is
 # is preserved.
 
 fig = pygmt.Figure()
@@ -90,6 +91,8 @@
 fig.plot(x=1, y=0, style="t0.3c", fill="pink", label="pink triangle")
 fig.plot(x=-1, y=0, style="s0.3c", fill="darkred", label="darkred square")
 
+# Add a box with a 2-points thick cyan, solid outline and a blue fill with a
+# transparency of 70 percentage ("@70")
 fig.legend(position="jTL+o0.3c/0.2c", box="+p2p,cyan+gblue@70")
 
 fig.show()
@@ -144,7 +147,7 @@
 
 # %%
 # Now, we can add a legend based on this :class:`io.StringIO` object. For
-# multi- columns legends, width (**+w**) has to be specified via a the
+# multi-columns legends, width (**+w**) has to be specified via a the
 # ``position`` parameter.
 
 fig = pygmt.Figure()

From 02da95a63a61f410bccb57a17cf7345bb815866b Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Tue, 12 Nov 2024 18:53:13 +0100
Subject: [PATCH 30/35] Combine subsections

---
 examples/tutorials/advanced/legends.py | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
index 8ddfa44b32d..c5dabb918ab 100644
--- a/examples/tutorials/advanced/legends.py
+++ b/examples/tutorials/advanced/legends.py
@@ -110,9 +110,7 @@
 #
 # The example below is orientated on the upstream GMT example at
 # https://docs.generic-mapping-tools.org/dev/legend.html#examples.
-
-
-# %%
+#
 # First, we set up an :class:`io.StringIO` object.
 
 spec_io = io.StringIO(

From 3afe1fd51575e7281930ada1b526177fa24532ac Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Tue, 12 Nov 2024 18:58:54 +0100
Subject: [PATCH 31/35] Fix typo

---
 examples/tutorials/advanced/legends.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
index c5dabb918ab..e1ff8d6c2f5 100644
--- a/examples/tutorials/advanced/legends.py
+++ b/examples/tutorials/advanced/legends.py
@@ -19,7 +19,7 @@
 # :meth:`pygmt.Figure.plot3d`, and :meth:`pygmt.Figure.histogram`. Therefore the
 # ``label`` parameter has to be specified to state the desired text for the legend
 # entry (white spaces are supported). Here, we use :meth:`pygmt.Figure.plot`,
-# examplarly. By default, the legend is placed in the Upper Right corner with an
+# exemplary. By default, the legend is placed in the Upper Right corner with an
 # offset of 0.1 centimeters in both x and y directions and a box with a white fill
 # and a 1-point thick, black, solid outline is drawn around the legend. The order
 # of the legend entries (top to bottom) is determine by the plotting order.

From 038f9c4b489771a798fa0c381d69f8837f342e66 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?=
 <94163266+yvonnefroehlich@users.noreply.github.com>
Date: Tue, 12 Nov 2024 19:04:19 +0100
Subject: [PATCH 32/35] Improve formulation

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>
---
 examples/tutorials/advanced/legends.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
index e1ff8d6c2f5..d3f43ed532b 100644
--- a/examples/tutorials/advanced/legends.py
+++ b/examples/tutorials/advanced/legends.py
@@ -102,9 +102,9 @@
 # Create a manual legend
 # ----------------------
 #
-# For more complicated legends in GMT, users need to write an ASCII file with
-# instructions for the layout of the legend items. In PyGMT it is additionally
-# possible to provide this information as an :class:`io.StringIO` object. Both, the
+# For more complicated legends, users need to prepare a legend specification with 
+# instructions for the layout of the legend items. The legend specification can be 
+# either an ASCII file or an :class:`io.StringIO` object. Both, the
 # ASCII file or the :class:`io.StringIO` object are passed to the ``spec`` parameter
 # of :meth:`pygmt.Figure.legend`.
 #

From 5eeff8b3569fef1d006e0a80ca258815fb335d60 Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Tue, 12 Nov 2024 19:24:03 +0100
Subject: [PATCH 33/35] Fix coding style

---
 examples/tutorials/advanced/legends.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
index d3f43ed532b..69a357fdd70 100644
--- a/examples/tutorials/advanced/legends.py
+++ b/examples/tutorials/advanced/legends.py
@@ -102,8 +102,8 @@
 # Create a manual legend
 # ----------------------
 #
-# For more complicated legends, users need to prepare a legend specification with 
-# instructions for the layout of the legend items. The legend specification can be 
+# For more complicated legends, users need to prepare a legend specification with
+# instructions for the layout of the legend items. The legend specification can be
 # either an ASCII file or an :class:`io.StringIO` object. Both, the
 # ASCII file or the :class:`io.StringIO` object are passed to the ``spec`` parameter
 # of :meth:`pygmt.Figure.legend`.

From 380a58f5ca7e489e5740f9ca2d4dc2aae668c20d Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Wed, 13 Nov 2024 10:46:09 +0100
Subject: [PATCH 34/35] Add docs for legend codes

---
 examples/tutorials/advanced/legends.py | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
index 69a357fdd70..ba96b8d568e 100644
--- a/examples/tutorials/advanced/legends.py
+++ b/examples/tutorials/advanced/legends.py
@@ -104,9 +104,13 @@
 #
 # For more complicated legends, users need to prepare a legend specification with
 # instructions for the layout of the legend items. The legend specification can be
-# either an ASCII file or an :class:`io.StringIO` object. Both, the
-# ASCII file or the :class:`io.StringIO` object are passed to the ``spec`` parameter
-# of :meth:`pygmt.Figure.legend`.
+# either an ASCII file or an :class:`io.StringIO` object. Both, the ASCII file or
+# the :class:`io.StringIO` object are passed to the ``spec`` parameter of
+# :meth:`pygmt.Figure.legend`. There are multiple legend codes available to create
+# complicated legends; an full overview can be found at
+# https://docs.generic-mapping-tools.org/dev/legend.html#legend-codes. It's
+# supported to include length scales, faults, and images as well as to add specific
+# lines.
 #
 # The example below is orientated on the upstream GMT example at
 # https://docs.generic-mapping-tools.org/dev/legend.html#examples.

From 55c8215165739d7b97595fb42eb489625226ecbe Mon Sep 17 00:00:00 2001
From: yvonnefroelich <yvonne.froehlich@kit.edu>
Date: Mon, 18 Nov 2024 08:07:10 +0100
Subject: [PATCH 35/35] Rewrap to 88 chars

---
 examples/tutorials/advanced/legends.py | 51 ++++++++++++--------------
 1 file changed, 24 insertions(+), 27 deletions(-)

diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
index ba96b8d568e..705af64124e 100644
--- a/examples/tutorials/advanced/legends.py
+++ b/examples/tutorials/advanced/legends.py
@@ -2,8 +2,8 @@
 Creating legends
 ================
 
-The :meth:`pygmt.Figure.legend` method creates legends, whereby auto-legends as well
-as manually created legends are supported.
+The :meth:`pygmt.Figure.legend` method creates legends, whereby auto-legends as well as
+manually created legends are supported.
 """
 
 # %%
@@ -17,16 +17,16 @@
 #
 # An auto-legend can be created for the methods :meth:`pygmt.Figure.plot`,
 # :meth:`pygmt.Figure.plot3d`, and :meth:`pygmt.Figure.histogram`. Therefore the
-# ``label`` parameter has to be specified to state the desired text for the legend
-# entry (white spaces are supported). Here, we use :meth:`pygmt.Figure.plot`,
-# exemplary. By default, the legend is placed in the Upper Right corner with an
-# offset of 0.1 centimeters in both x and y directions and a box with a white fill
-# and a 1-point thick, black, solid outline is drawn around the legend. The order
-# of the legend entries (top to bottom) is determine by the plotting order.
-# Optionally, to adjust the legend, append different modifiers to the string passed
-# to ``label``. For a list of available modifiers see :gmt-docs:`gmt.html#l-full`.
-# To create a :doc:`multiple-column legend </gallery/embellishments/legend>` **+N**
-# is used with the desired number of columns.
+# ``label`` parameter has to be specified to state the desired text for the legend entry
+# (white spaces are supported). Here, we use :meth:`pygmt.Figure.plot`, exemplary. By
+# default, the legend is placed in the Upper Right corner with an offset of 0.1
+# centimeters in both x and y directions and a box with a white fill and a 1-point
+# thick, black, solid outline is drawn around the legend. The order of the legend
+# entries (top to bottom) is determine by the plotting order. Optionally, to adjust the
+# legend, append different modifiers to the string passed to ``label``. For a list of
+# available modifiers see :gmt-docs:`gmt.html#l-full`. To create a
+# :doc:`multiple-column legend </gallery/embellishments/legend>` **+N** is used with the
+# desired number of columns.
 
 fig = pygmt.Figure()
 fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
@@ -48,10 +48,9 @@
 #
 # Use the ``position`` parameter to adjust the position of the legend. For the
 # different ways to specify the placement of a plotting element (e.g., legends,
-# colorbars) on a plot in GMT, please refer to the Technical Reference TODO (: .
-# Add an offset via **+o** for the x and y directions. Additionally append **+w**
-# to adjust the ``width`` of the length. Note, no box is drawn by default if
-# ``position`` is used.
+# colorbars) on a plot in GMT, please refer to the Technical Reference TODO (: . Add
+# an offset via **+o** for the x and y directions. Additionally append **+w** to adjust
+# the ``width`` of the length. Note, no box is drawn by default if ``position`` is used.
 
 fig = pygmt.Figure()
 fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
@@ -60,8 +59,8 @@
 fig.plot(x=1, y=0, style="t0.3c", fill="pink", label="pink triangle")
 fig.plot(x=-1, y=0, style="s0.3c", fill="darkred", label="darkred square")
 
-# Set the reference point to Left Top and use an offset of 0.3 and 0.2 centimeters
-# in the x and y directions, respectively
+# Set the reference point to Left Top and use an offset of 0.3 and 0.2 centimeters in
+# the x and y directions, respectively
 fig.legend(position="jLT+o0.3c/0.2c")
 
 fig.show()
@@ -70,10 +69,9 @@
 # %%
 # Add a box
 # ---------
-# Use the ``box`` parameter for adjusting the box around the legend. The outline of
-# the box can be adjusted by appending **+p**. Append **+g** to fill the legend with
-# a color (or pattern) [Default is a white fill]. The default of ``position`` is
-# is preserved.
+# Use the ``box`` parameter for adjusting the box around the legend. The outline of the
+# box can be adjusted by appending **+p**. Append **+g** to fill the legend with a color
+# (or pattern) [Default is a white fill]. The default of ``position`` is preserved.
 
 fig = pygmt.Figure()
 fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
@@ -104,13 +102,12 @@
 #
 # For more complicated legends, users need to prepare a legend specification with
 # instructions for the layout of the legend items. The legend specification can be
-# either an ASCII file or an :class:`io.StringIO` object. Both, the ASCII file or
-# the :class:`io.StringIO` object are passed to the ``spec`` parameter of
+# either an ASCII file or an :class:`io.StringIO` object. Both, the ASCII file or the
+# :class:`io.StringIO` object are passed to the ``spec`` parameter of
 # :meth:`pygmt.Figure.legend`. There are multiple legend codes available to create
 # complicated legends; an full overview can be found at
-# https://docs.generic-mapping-tools.org/dev/legend.html#legend-codes. It's
-# supported to include length scales, faults, and images as well as to add specific
-# lines.
+# https://docs.generic-mapping-tools.org/dev/legend.html#legend-codes. It's supported
+# to include length scales, faults, and images as well as to add specific lines.
 #
 # The example below is orientated on the upstream GMT example at
 # https://docs.generic-mapping-tools.org/dev/legend.html#examples.