From fa7a6a8a6e9dc368a4e92d4149a4107e3a226c26 Mon Sep 17 00:00:00 2001
From: Wei Ji <weiji.leong@vuw.ac.nz>
Date: Mon, 8 Feb 2021 12:54:10 +1300
Subject: [PATCH 1/4] Add common alias ax (-c) to all plotting functions

Used to advance to the selected subplot panel.
See https://docs.generic-mapping-tools.org/6.1/gmt.html#c-full,
https://github.com/GenericMappingTools/gmt/blob/6.1.1/doc/rst/source/explain_-c_full.rst_,
and https://docs.generic-mapping-tools.org/6.1/cookbook/options.html#selecting-subplot-panels-the-c-option.
Needed for the `subplot` wrapper at #822.
Also added 'ax' to good-names list in pylintrc file.
---
 .pylintrc                   |  1 +
 pygmt/helpers/decorators.py | 11 +++++++++++
 pygmt/src/basemap.py        |  4 +++-
 pygmt/src/coast.py          |  4 +++-
 pygmt/src/colorbar.py       |  6 +++++-
 pygmt/src/contour.py        |  4 +++-
 pygmt/src/grdcontour.py     |  6 +++++-
 pygmt/src/grdimage.py       |  4 +++-
 pygmt/src/grdview.py        |  4 +++-
 pygmt/src/image.py          |  4 +++-
 pygmt/src/legend.py         |  4 +++-
 pygmt/src/logo.py           |  4 +++-
 pygmt/src/meca.py           |  4 +++-
 pygmt/src/plot.py           |  4 +++-
 pygmt/src/plot3d.py         |  4 +++-
 pygmt/src/text.py           |  3 +++
 16 files changed, 58 insertions(+), 13 deletions(-)

diff --git a/.pylintrc b/.pylintrc
index 766bdd46b8b..e42a50bf488 100644
--- a/.pylintrc
+++ b/.pylintrc
@@ -441,6 +441,7 @@ function-naming-style=snake_case
 good-names=i,
            j,
            k,
+           ax,
            ex,
            Run,
            _,
diff --git a/pygmt/helpers/decorators.py b/pygmt/helpers/decorators.py
index f40800d367a..b6350b62a2f 100644
--- a/pygmt/helpers/decorators.py
+++ b/pygmt/helpers/decorators.py
@@ -60,6 +60,17 @@
             Shift plot origin in y-direction. Full documentation is at
             :gmt-docs:`gmt.html#xy-full`.
          """,
+    "c": r"""ax : int or list
+            [*row*\ ,\ *col*\|\ *index*].
+            Used to advance to the selected subplot panel. Only allowed when in
+            subplot mode. Available to all plot modules. If no arguments are
+            given then we advance to the next panel in the selected order. If
+            no **ax** is given and we just entered subplot mode then the first
+            panel (top, left) is selected. Instead of *row, col* you may give
+            the one-dimensional *index* which depends on the order you set via
+            **autolabel** when the subplot was defined. **Note**: *row*, *col*,
+            and *index* all start at 0.
+         """,
     "j": """\
         distcalc : str
             ``e|f|g``.
diff --git a/pygmt/src/basemap.py b/pygmt/src/basemap.py
index 60fe1ddb217..97650cdc804 100644
--- a/pygmt/src/basemap.py
+++ b/pygmt/src/basemap.py
@@ -27,10 +27,11 @@
     V="verbose",
     X="xshift",
     Y="yshift",
+    c="ax",
     p="perspective",
     t="transparency",
 )
-@kwargs_to_strings(R="sequence", p="sequence")
+@kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
 def basemap(self, **kwargs):
     """
     Plot base maps and frames for the figure.
@@ -66,6 +67,7 @@ def basemap(self, **kwargs):
     {U}
     {V}
     {XY}
+    {c}
     {p}
     {t}
     """
diff --git a/pygmt/src/coast.py b/pygmt/src/coast.py
index 21dccb52599..daccdf91f6e 100644
--- a/pygmt/src/coast.py
+++ b/pygmt/src/coast.py
@@ -32,10 +32,11 @@
     V="verbose",
     X="xshift",
     Y="yshift",
+    c="ax",
     p="perspective",
     t="transparency",
 )
-@kwargs_to_strings(R="sequence", p="sequence")
+@kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
 def coast(self, **kwargs):
     r"""
     Plot continents, shorelines, rivers, and borders on maps
@@ -182,6 +183,7 @@ def coast(self, **kwargs):
         the segment headers via **-Z**\ *code* settings.To apply different
         settings to different countries, pass a list of string arguments.
     {XY}
+    {c}
     {p}
     {t}
     {V}
diff --git a/pygmt/src/colorbar.py b/pygmt/src/colorbar.py
index 571dc8e760e..bc32f4dbf92 100644
--- a/pygmt/src/colorbar.py
+++ b/pygmt/src/colorbar.py
@@ -20,10 +20,13 @@
     V="verbose",
     X="xshift",
     Y="yshift",
+    c="ax",
     p="perspective",
     t="transparency",
 )
-@kwargs_to_strings(R="sequence", G="sequence", I="sequence", p="sequence")
+@kwargs_to_strings(
+    R="sequence", G="sequence", I="sequence", c="sequence_comma", p="sequence"
+)
 def colorbar(self, **kwargs):
     """
     Plot a gray or color scale-bar on maps.
@@ -94,6 +97,7 @@ def colorbar(self, **kwargs):
         illumination.
     {V}
     {XY}
+    {c}
     {p}
     {t}
     """
diff --git a/pygmt/src/contour.py b/pygmt/src/contour.py
index 2ad34a366e0..471f147b3e1 100644
--- a/pygmt/src/contour.py
+++ b/pygmt/src/contour.py
@@ -30,10 +30,11 @@
     V="verbose",
     X="xshift",
     Y="yshift",
+    c="ax",
     p="perspective",
     t="transparency",
 )
-@kwargs_to_strings(R="sequence", i="sequence_comma", p="sequence")
+@kwargs_to_strings(R="sequence", c="sequence_comma", i="sequence_comma", p="sequence")
 def contour(self, x=None, y=None, z=None, data=None, **kwargs):
     """
     Contour table data by direct triangulation.
@@ -92,6 +93,7 @@ def contour(self, x=None, y=None, z=None, data=None, **kwargs):
         separator for the two labels instead.
     {V}
     {XY}
+    {c}
     {p}
     {t}
     """
diff --git a/pygmt/src/grdcontour.py b/pygmt/src/grdcontour.py
index 9b839f931a8..bd04f0c9f06 100644
--- a/pygmt/src/grdcontour.py
+++ b/pygmt/src/grdcontour.py
@@ -30,10 +30,13 @@
     l="label",
     X="xshift",
     Y="yshift",
+    c="ax",
     p="perspective",
     t="transparency",
 )
-@kwargs_to_strings(R="sequence", L="sequence", A="sequence_plus", p="sequence")
+@kwargs_to_strings(
+    R="sequence", L="sequence", A="sequence_plus", c="sequence_comma", p="sequence"
+)
 def grdcontour(self, grid, **kwargs):
     """
     Convert grids or images to contours and plot them on maps.
@@ -87,6 +90,7 @@ def grdcontour(self, grid, **kwargs):
     {V}
     {W}
     {XY}
+    {c}
     label : str
         Add a legend entry for the contour being plotted. Normally, the
         annotated contour is selected for the legend. You can select the
diff --git a/pygmt/src/grdimage.py b/pygmt/src/grdimage.py
index f0cb2bd5a6a..643c64dfa21 100644
--- a/pygmt/src/grdimage.py
+++ b/pygmt/src/grdimage.py
@@ -32,11 +32,12 @@
     X="xshift",
     Y="yshift",
     n="interpolation",
+    c="ax",
     p="perspective",
     t="transparency",
     x="cores",
 )
-@kwargs_to_strings(R="sequence", p="sequence")
+@kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
 def grdimage(self, grid, **kwargs):
     """
     Project and plot grids or images.
@@ -151,6 +152,7 @@ def grdimage(self, grid, **kwargs):
     {R}
     {V}
     {XY}
+    {c}
     {n}
     {p}
     {t}
diff --git a/pygmt/src/grdview.py b/pygmt/src/grdview.py
index 63ca411be34..7ea2869dea3 100644
--- a/pygmt/src/grdview.py
+++ b/pygmt/src/grdview.py
@@ -33,10 +33,11 @@
     V="verbose",
     X="xshift",
     Y="yshift",
+    c="ax",
     p="perspective",
     t="transparency",
 )
-@kwargs_to_strings(R="sequence", p="sequence")
+@kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
 def grdview(self, grid, **kwargs):
     """
     Create 3-D perspective image or surface mesh from a grid.
@@ -111,6 +112,7 @@ def grdview(self, grid, **kwargs):
 
     {V}
     {XY}
+    {c}
     {p}
     {t}
     """
diff --git a/pygmt/src/image.py b/pygmt/src/image.py
index 72c5f7949d5..75137de58dc 100644
--- a/pygmt/src/image.py
+++ b/pygmt/src/image.py
@@ -15,10 +15,11 @@
     V="verbose",
     X="xshift",
     Y="yshift",
+    c="ax",
     p="perspective",
     t="transparency",
 )
-@kwargs_to_strings(R="sequence", p="sequence")
+@kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
 def image(self, imagefile, **kwargs):
     """
     Place images or EPS files on maps.
@@ -53,6 +54,7 @@ def image(self, imagefile, **kwargs):
         YIQ-transformation.
     {V}
     {XY}
+    {c}
     {p}
     {t}
     """
diff --git a/pygmt/src/legend.py b/pygmt/src/legend.py
index c8d3fcef8e3..addb75eb4b0 100644
--- a/pygmt/src/legend.py
+++ b/pygmt/src/legend.py
@@ -22,10 +22,11 @@
     V="verbose",
     X="xshift",
     Y="yshift",
+    c="ax",
     p="perspective",
     t="transparency",
 )
-@kwargs_to_strings(R="sequence", p="sequence")
+@kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
 def legend(self, spec=None, position="JTR+jTR+o0.2c", box="+gwhite+p1p", **kwargs):
     """
     Plot legends on maps.
@@ -61,6 +62,7 @@ def legend(self, spec=None, position="JTR+jTR+o0.2c", box="+gwhite+p1p", **kwarg
         using a 1 point black pen and adds a white background.
     {V}
     {XY}
+    {c}
     {p}
     {t}
     """
diff --git a/pygmt/src/logo.py b/pygmt/src/logo.py
index c2f29fae2d1..19c1402eb26 100644
--- a/pygmt/src/logo.py
+++ b/pygmt/src/logo.py
@@ -17,9 +17,10 @@
     V="verbose",
     X="xshift",
     Y="yshift",
+    c="ax",
     t="transparency",
 )
-@kwargs_to_strings(R="sequence", p="sequence")
+@kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
 def logo(self, **kwargs):
     """
     Plot the GMT logo.
@@ -54,6 +55,7 @@ def logo(self, **kwargs):
     {U}
     {V}
     {XY}
+    {c}
     {t}
     """
     kwargs = self._preprocess(**kwargs)  # pylint: disable=protected-access
diff --git a/pygmt/src/meca.py b/pygmt/src/meca.py
index f50933facf1..c5555a121f0 100644
--- a/pygmt/src/meca.py
+++ b/pygmt/src/meca.py
@@ -26,10 +26,11 @@
     V="verbose",
     X="xshift",
     Y="yshift",
+    c="ax",
     p="perspective",
     t="transparency",
 )
-@kwargs_to_strings(R="sequence", p="sequence")
+@kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
 def meca(
     self,  # pylint: disable=unused-argument
     spec,
@@ -124,6 +125,7 @@ def meca(
     {B}
     {V}
     {XY}
+    {c}
     {p}
     {t}
     """
diff --git a/pygmt/src/plot.py b/pygmt/src/plot.py
index 0324e1c25d0..5e522a49a4f 100644
--- a/pygmt/src/plot.py
+++ b/pygmt/src/plot.py
@@ -38,10 +38,11 @@
     Z="zvalue",
     i="columns",
     l="label",
+    c="ax",
     p="perspective",
     t="transparency",
 )
-@kwargs_to_strings(R="sequence", i="sequence_comma", p="sequence")
+@kwargs_to_strings(R="sequence", c="sequence_comma", i="sequence_comma", p="sequence")
 def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
     """
     Plot lines, polygons, and symbols in 2-D.
@@ -178,6 +179,7 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
         polygon in the input data. To apply it to the fill color, use
         ``color='+z'``. To apply it to the pen color, append **+z** to
         **pen**.
+    {c}
     columns : str or 1d array
         Choose which columns are x, y, color, and size, respectively if
         input is provided via *data*. E.g. ``columns = [0, 1]`` or
diff --git a/pygmt/src/plot3d.py b/pygmt/src/plot3d.py
index d828d85c6c3..e5d4cce17f0 100644
--- a/pygmt/src/plot3d.py
+++ b/pygmt/src/plot3d.py
@@ -38,10 +38,11 @@
     Z="zvalue",
     i="columns",
     l="label",
+    c="ax",
     p="perspective",
     t="transparency",
 )
-@kwargs_to_strings(R="sequence", i="sequence_comma", p="sequence")
+@kwargs_to_strings(R="sequence", c="sequence_comma", i="sequence_comma", p="sequence")
 def plot3d(
     self, x=None, y=None, z=None, data=None, sizes=None, direction=None, **kwargs
 ):
@@ -150,6 +151,7 @@ def plot3d(
         polygon in the input data. To apply it to the fill color, use
         ``color='+z'``. To apply it to the pen color, append **+z** to
         **pen**.
+    {c}
     label : str
         Add a legend entry for the symbol or line being plotted.
     {p}
diff --git a/pygmt/src/text.py b/pygmt/src/text.py
index 6bcf7e0989e..c21ea060401 100644
--- a/pygmt/src/text.py
+++ b/pygmt/src/text.py
@@ -28,6 +28,7 @@
     W="pen",
     X="xshift",
     Y="yshift",
+    c="ax",
     p="perspective",
     t="transparency",
 )
@@ -37,6 +38,7 @@
     angle="sequence_comma",
     font="sequence_comma",
     justify="sequence_comma",
+    c="sequence_comma",
     p="sequence",
 )
 def text_(
@@ -140,6 +142,7 @@ def text_(
         clip].
     {V}
     {XY}
+    {c}
     {p}
     {t}
     """

From b8b454ace5a03b2ae3728ea76b176e3799dd3b62 Mon Sep 17 00:00:00 2001
From: Wei Ji <weiji.leong@vuw.ac.nz>
Date: Mon, 8 Feb 2021 12:55:26 +1300
Subject: [PATCH 2/4] Add ax (c) to list of necessary arguments in basemap

---
 pygmt/src/basemap.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/pygmt/src/basemap.py b/pygmt/src/basemap.py
index 97650cdc804..097d8478bbe 100644
--- a/pygmt/src/basemap.py
+++ b/pygmt/src/basemap.py
@@ -72,9 +72,9 @@ def basemap(self, **kwargs):
     {t}
     """
     kwargs = self._preprocess(**kwargs)  # pylint: disable=protected-access
-    if not args_in_kwargs(args=["B", "L", "Td", "Tm"], kwargs=kwargs):
+    if not args_in_kwargs(args=["B", "L", "Td", "Tm", "c"], kwargs=kwargs):
         raise GMTInvalidInput(
-            "At least one of frame, map_scale, compass, or rose must be specified."
+            "At least one of frame, map_scale, compass, rose, or ax must be specified."
         )
     with Session() as lib:
         lib.call_module("basemap", build_arg_string(kwargs))

From ffb3b48bfa3bb057fc9071679a192e0172d64e31 Mon Sep 17 00:00:00 2001
From: Wei Ji <weiji.leong@vuw.ac.nz>
Date: Thu, 11 Feb 2021 09:02:58 +1300
Subject: [PATCH 3/4] Rename alias ax to panel to follow upstream GMT

---
 .pylintrc                   |  1 -
 pygmt/helpers/decorators.py | 12 ++++++------
 pygmt/src/basemap.py        |  4 ++--
 pygmt/src/coast.py          |  2 +-
 pygmt/src/colorbar.py       |  2 +-
 pygmt/src/contour.py        |  2 +-
 pygmt/src/grdcontour.py     |  2 +-
 pygmt/src/grdimage.py       |  2 +-
 pygmt/src/grdview.py        |  2 +-
 pygmt/src/image.py          |  2 +-
 pygmt/src/legend.py         |  2 +-
 pygmt/src/logo.py           |  2 +-
 pygmt/src/meca.py           |  2 +-
 pygmt/src/plot.py           |  2 +-
 pygmt/src/plot3d.py         |  2 +-
 pygmt/src/text.py           |  2 +-
 16 files changed, 21 insertions(+), 22 deletions(-)

diff --git a/.pylintrc b/.pylintrc
index e42a50bf488..766bdd46b8b 100644
--- a/.pylintrc
+++ b/.pylintrc
@@ -441,7 +441,6 @@ function-naming-style=snake_case
 good-names=i,
            j,
            k,
-           ax,
            ex,
            Run,
            _,
diff --git a/pygmt/helpers/decorators.py b/pygmt/helpers/decorators.py
index b6350b62a2f..9682d205046 100644
--- a/pygmt/helpers/decorators.py
+++ b/pygmt/helpers/decorators.py
@@ -60,16 +60,16 @@
             Shift plot origin in y-direction. Full documentation is at
             :gmt-docs:`gmt.html#xy-full`.
          """,
-    "c": r"""ax : int or list
+    "c": r"""panel : int or list
             [*row*\ ,\ *col*\|\ *index*].
             Used to advance to the selected subplot panel. Only allowed when in
             subplot mode. Available to all plot modules. If no arguments are
             given then we advance to the next panel in the selected order. If
-            no **ax** is given and we just entered subplot mode then the first
-            panel (top, left) is selected. Instead of *row, col* you may give
-            the one-dimensional *index* which depends on the order you set via
-            **autolabel** when the subplot was defined. **Note**: *row*, *col*,
-            and *index* all start at 0.
+            no **panel** is given and we just entered subplot mode then the
+            first panel (top, left) is selected. Instead of *row, col* you may
+            give the one-dimensional *index* which depends on the order you set
+            via **autolabel** when the subplot was defined. **Note**: *row*,
+            *col*, and *index* all start at 0.
          """,
     "j": """\
         distcalc : str
diff --git a/pygmt/src/basemap.py b/pygmt/src/basemap.py
index 097d8478bbe..678540c48f7 100644
--- a/pygmt/src/basemap.py
+++ b/pygmt/src/basemap.py
@@ -27,7 +27,7 @@
     V="verbose",
     X="xshift",
     Y="yshift",
-    c="ax",
+    c="panel",
     p="perspective",
     t="transparency",
 )
@@ -74,7 +74,7 @@ def basemap(self, **kwargs):
     kwargs = self._preprocess(**kwargs)  # pylint: disable=protected-access
     if not args_in_kwargs(args=["B", "L", "Td", "Tm", "c"], kwargs=kwargs):
         raise GMTInvalidInput(
-            "At least one of frame, map_scale, compass, rose, or ax must be specified."
+            "At least one of frame, map_scale, compass, rose, or panel must be specified."
         )
     with Session() as lib:
         lib.call_module("basemap", build_arg_string(kwargs))
diff --git a/pygmt/src/coast.py b/pygmt/src/coast.py
index daccdf91f6e..38f3719d47a 100644
--- a/pygmt/src/coast.py
+++ b/pygmt/src/coast.py
@@ -32,7 +32,7 @@
     V="verbose",
     X="xshift",
     Y="yshift",
-    c="ax",
+    c="panel",
     p="perspective",
     t="transparency",
 )
diff --git a/pygmt/src/colorbar.py b/pygmt/src/colorbar.py
index bc32f4dbf92..f523ab63609 100644
--- a/pygmt/src/colorbar.py
+++ b/pygmt/src/colorbar.py
@@ -20,7 +20,7 @@
     V="verbose",
     X="xshift",
     Y="yshift",
-    c="ax",
+    c="panel",
     p="perspective",
     t="transparency",
 )
diff --git a/pygmt/src/contour.py b/pygmt/src/contour.py
index 471f147b3e1..a782d8d814b 100644
--- a/pygmt/src/contour.py
+++ b/pygmt/src/contour.py
@@ -30,7 +30,7 @@
     V="verbose",
     X="xshift",
     Y="yshift",
-    c="ax",
+    c="panel",
     p="perspective",
     t="transparency",
 )
diff --git a/pygmt/src/grdcontour.py b/pygmt/src/grdcontour.py
index bd04f0c9f06..932e5b7a89e 100644
--- a/pygmt/src/grdcontour.py
+++ b/pygmt/src/grdcontour.py
@@ -30,7 +30,7 @@
     l="label",
     X="xshift",
     Y="yshift",
-    c="ax",
+    c="panel",
     p="perspective",
     t="transparency",
 )
diff --git a/pygmt/src/grdimage.py b/pygmt/src/grdimage.py
index 643c64dfa21..9658164677b 100644
--- a/pygmt/src/grdimage.py
+++ b/pygmt/src/grdimage.py
@@ -32,7 +32,7 @@
     X="xshift",
     Y="yshift",
     n="interpolation",
-    c="ax",
+    c="panel",
     p="perspective",
     t="transparency",
     x="cores",
diff --git a/pygmt/src/grdview.py b/pygmt/src/grdview.py
index 7ea2869dea3..77127e343d9 100644
--- a/pygmt/src/grdview.py
+++ b/pygmt/src/grdview.py
@@ -33,7 +33,7 @@
     V="verbose",
     X="xshift",
     Y="yshift",
-    c="ax",
+    c="panel",
     p="perspective",
     t="transparency",
 )
diff --git a/pygmt/src/image.py b/pygmt/src/image.py
index 75137de58dc..9864422a120 100644
--- a/pygmt/src/image.py
+++ b/pygmt/src/image.py
@@ -15,7 +15,7 @@
     V="verbose",
     X="xshift",
     Y="yshift",
-    c="ax",
+    c="panel",
     p="perspective",
     t="transparency",
 )
diff --git a/pygmt/src/legend.py b/pygmt/src/legend.py
index addb75eb4b0..cd3e9362f12 100644
--- a/pygmt/src/legend.py
+++ b/pygmt/src/legend.py
@@ -22,7 +22,7 @@
     V="verbose",
     X="xshift",
     Y="yshift",
-    c="ax",
+    c="panel",
     p="perspective",
     t="transparency",
 )
diff --git a/pygmt/src/logo.py b/pygmt/src/logo.py
index 19c1402eb26..af0d60c0754 100644
--- a/pygmt/src/logo.py
+++ b/pygmt/src/logo.py
@@ -17,7 +17,7 @@
     V="verbose",
     X="xshift",
     Y="yshift",
-    c="ax",
+    c="panel",
     t="transparency",
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
diff --git a/pygmt/src/meca.py b/pygmt/src/meca.py
index c5555a121f0..0fe68b8c8b9 100644
--- a/pygmt/src/meca.py
+++ b/pygmt/src/meca.py
@@ -26,7 +26,7 @@
     V="verbose",
     X="xshift",
     Y="yshift",
-    c="ax",
+    c="panel",
     p="perspective",
     t="transparency",
 )
diff --git a/pygmt/src/plot.py b/pygmt/src/plot.py
index 5e522a49a4f..0ec3d0bc89a 100644
--- a/pygmt/src/plot.py
+++ b/pygmt/src/plot.py
@@ -38,7 +38,7 @@
     Z="zvalue",
     i="columns",
     l="label",
-    c="ax",
+    c="panel",
     p="perspective",
     t="transparency",
 )
diff --git a/pygmt/src/plot3d.py b/pygmt/src/plot3d.py
index e5d4cce17f0..682cd7494a4 100644
--- a/pygmt/src/plot3d.py
+++ b/pygmt/src/plot3d.py
@@ -38,7 +38,7 @@
     Z="zvalue",
     i="columns",
     l="label",
-    c="ax",
+    c="panel",
     p="perspective",
     t="transparency",
 )
diff --git a/pygmt/src/text.py b/pygmt/src/text.py
index c21ea060401..0fa0a9698a8 100644
--- a/pygmt/src/text.py
+++ b/pygmt/src/text.py
@@ -28,7 +28,7 @@
     W="pen",
     X="xshift",
     Y="yshift",
-    c="ax",
+    c="panel",
     p="perspective",
     t="transparency",
 )

From 65fe92f0bc2ba13a3270b2bb800e4a1cc584856f Mon Sep 17 00:00:00 2001
From: Wei Ji <weiji.leong@vuw.ac.nz>
Date: Thu, 11 Feb 2021 10:03:47 +1300
Subject: [PATCH 4/4] Update description of common alias c to be more Pythonic

Co-Authored-By: Dongdong Tian <seisman.info@gmail.com>
---
 pygmt/helpers/decorators.py | 16 +++++++---------
 1 file changed, 7 insertions(+), 9 deletions(-)

diff --git a/pygmt/helpers/decorators.py b/pygmt/helpers/decorators.py
index 9682d205046..37d7797ce01 100644
--- a/pygmt/helpers/decorators.py
+++ b/pygmt/helpers/decorators.py
@@ -60,16 +60,14 @@
             Shift plot origin in y-direction. Full documentation is at
             :gmt-docs:`gmt.html#xy-full`.
          """,
-    "c": r"""panel : int or list
+    "c": r"""panel : int or list or bool
             [*row*\ ,\ *col*\|\ *index*].
-            Used to advance to the selected subplot panel. Only allowed when in
-            subplot mode. Available to all plot modules. If no arguments are
-            given then we advance to the next panel in the selected order. If
-            no **panel** is given and we just entered subplot mode then the
-            first panel (top, left) is selected. Instead of *row, col* you may
-            give the one-dimensional *index* which depends on the order you set
-            via **autolabel** when the subplot was defined. **Note**: *row*,
-            *col*, and *index* all start at 0.
+            Selects a specific subplot panel. Only allowed when in subplot
+            mode. Use ``panel=True`` to advance to the next panel in the
+            selected order. Instead of *row,col* you may also give a scalar
+            value *index* which depends on the order you set via ``autolabel``
+            when the subplot was defined. **Note**: *row*, *col*, and *index*
+            all start at 0.
          """,
     "j": """\
         distcalc : str