Merge branch 'main' into refactor/virtualfile-to-data

.github/workflows/ci_docs.yml

@@ -113,7 +113,7 @@ jobs:
             sphinx-autodoc-typehints
             sphinx-copybutton
             sphinx-design
-            sphinx-gallery
+            sphinx-gallery<0.17.0
             sphinx_rtd_theme
 
       # Download cached remote files (artifacts) from GitHub

ci/requirements/docs.yml

@@ -28,5 +28,5 @@ dependencies:
     - sphinx-autodoc-typehints
     - sphinx-copybutton
     - sphinx-design
-    - sphinx-gallery
+    - sphinx-gallery<0.17.0
     - sphinx_rtd_theme

doc/external_resources.md

@@ -97,7 +97,7 @@ Andre Belem
 :text-align: center
 :margin: 0 3 0 0
 
-![](https://github.com/tktmyd/pygmt-howto-jp/raw/main/docs/_images/inf_on_map_12_0.png)
+![](https://github.com/tktmyd/pygmt-howto-jp/raw/main/docs/_images/01aed847a81445c7a002cce113d95886793f6236fbcccb233862486589f17ed1.png)
 +++
 Takuto Maeda
 ::::

doc/overview.md

@@ -22,7 +22,7 @@ The project was started in 2017 by [Leonardo Uieda](http://www.leouieda.com) and
 [Paul Wessel](http://www.soest.hawaii.edu/wessel) (the co-creator and main developer of
 GMT) at the University of Hawaiʻi at Mānoa. The development of PyGMT has been supported
 by NSF grants [OCE-1558403](https://www.nsf.gov/awardsearch/showAward?AWD_ID=1558403)
-and [EAR-1948603](https://www.nsf.gov/awardsearch/showAward?AWD_ID=1948602).
+and [EAR-1948602](https://www.nsf.gov/awardsearch/showAward?AWD_ID=1948602).
 
 We welcome any feedback and ideas! Let us know by submitting
 [issues on GitHub](https://github.com/GenericMappingTools/pygmt/issues) or by posting on

doc/techref/encodings.md

@@ -1,14 +1,12 @@
 # Supported Encodings and Non-ASCII Characters
 
-GMT supports a number of encodings and each encoding contains a set of ASCII and non-ASCII
-characters. Below are some of the most common encodings and characters that are supported.
+GMT supports a number of encodings and each encoding contains a set of ASCII and
+non-ASCII characters. In PyGMT, you can use any of these ASCII and non-ASCII characters
+in arguments and text strings. When using non-ASCII characters in PyGMT, the easiest way
+is to copy and paste the character from the encoding tables below.
 
-In PyGMT, you can use any of these ASCII and non-ASCII characters in arguments and text
-strings. When using non-ASCII characters in PyGMT, the easiest way is to copy and paste
-the character from the tables below.
-
-**Note**: The special character � (REPLACEMENT CHARACTER) is used to indicate that
-the character is not defined in the encoding.
+**Note**: The special character � (REPLACEMENT CHARACTER) is used to indicate
+that the character is not defined in the encoding.
 
 ## Adobe ISOLatin1+ Encoding
 
@@ -106,3 +104,27 @@ the Unicode character set.
 | **\35x** | ➨ | ➩ | ➪ | ➫ | ➬ | ➭ | ➮ | ➯ |
 | **\36x** | � | ➱ | ➲ | ➳ | ➴ | ➵ | ➶ | ➷ |
 | **\37x** | ➸ | ➹ | ➺ | ➻ | ➼ | ➽ | ➾ | � |
+
+## ISO/IEC 8859
+
+GMT also supports the ISO/IEC 8859 standard for 8-bit character encodings. Refer to
+<https://en.wikipedia.org/wiki/ISO/IEC_8859> for descriptions of the different parts of
+the standard.
+
+For a list of the characters in each part of the standard, refer to the following links:
+
+- <https://en.wikipedia.org/wiki/ISO/IEC_8859-1>
+- <https://en.wikipedia.org/wiki/ISO/IEC_8859-2>
+- <https://en.wikipedia.org/wiki/ISO/IEC_8859-3>
+- <https://en.wikipedia.org/wiki/ISO/IEC_8859-4>
+- <https://en.wikipedia.org/wiki/ISO/IEC_8859-5>
+- <https://en.wikipedia.org/wiki/ISO/IEC_8859-6>
+- <https://en.wikipedia.org/wiki/ISO/IEC_8859-7>
+- <https://en.wikipedia.org/wiki/ISO/IEC_8859-8>
+- <https://en.wikipedia.org/wiki/ISO/IEC_8859-9>
+- <https://en.wikipedia.org/wiki/ISO/IEC_8859-10>
+- <https://en.wikipedia.org/wiki/ISO/IEC_8859-11>
+- <https://en.wikipedia.org/wiki/ISO/IEC_8859-13>
+- <https://en.wikipedia.org/wiki/ISO/IEC_8859-14>
+- <https://en.wikipedia.org/wiki/ISO/IEC_8859-15>
+- <https://en.wikipedia.org/wiki/ISO/IEC_8859-16>

environment.yml

@@ -40,7 +40,7 @@ dependencies:
     - sphinx-autodoc-typehints
     - sphinx-copybutton
     - sphinx-design
-    - sphinx-gallery
+    - sphinx-gallery<0.17.0
     - sphinx_rtd_theme
     # Dev dependencies (type hints)
     - mypy

examples/gallery/3d_plots/grdview_surface.py

@@ -60,7 +60,7 @@ def ackley(x, y):
 # Add colorbar for gridded data
 fig.colorbar(
     frame="a2f1",  # Set annotations in steps of two, tick marks in steps of one
-    position="JRM",  # Place colorbar at position Right Middle
+    position="JMR",  # Place colorbar in the Middle Right (MR) corner
 )
 
 fig.show()

examples/gallery/basemaps/double_y_axes.py

@@ -63,7 +63,8 @@ class can control which axes should be plotted and optionally show annotations,
 # Plot points for y2 data
 fig.plot(x=x, y=y2, style="s0.28c", fill="red", label="y2")
 
-# Create a legend in the top-left corner of the plot
+# Create a legend in the Top Left (TL) corner of the plot with an
+# offset of 0.1 centimeters
 fig.legend(position="jTL+o0.1c", box=True)
 
 fig.show()

examples/gallery/embellishments/colorbar.py

@@ -16,14 +16,13 @@
   horizontal (**L**\ eft, **C**\ enter, **R**\ ight) alignment codes, e.g.
   ``position="jTR"`` for Top Right.
 - **g**: using map coordinates, e.g. ``position="g170/-45"`` for longitude
-  170E, latitude 45S.
+  170° East, latitude 45° South.
 - **x**: using paper coordinates, e.g. ``position="x5c/7c"`` for 5 cm, 7 cm
   from anchor point.
 - **n**: using normalized (0-1) coordinates, e.g. ``position="n0.4/0.8"``.
 
 Note that the anchor point defaults to the bottom left (**BL**). Append ``+h``
-to ``position`` to get a horizontal colorbar instead of a vertical one
-(``+v``).
+to ``position`` to get a horizontal colorbar instead of a vertical one (``+v``).
 """
 
 # %%
@@ -34,7 +33,7 @@
 
 # ============
 # Create a colorbar designed for seismic tomography - roma
-# Colorbar is placed at bottom center (BC) by default if no position is given
+# Colorbar is placed at Bottom Center (BC) by default if no position is given
 # Add quantity and unit as labels ("+l") to the x and y axes
 # Add annotations ("+a") in steps of 0.5 and ticks ("+f") in steps of 0.1
 fig.colorbar(cmap="roma", frame=["xa0.5f0.1+lVelocity", "y+lm/s"])
@@ -78,8 +77,8 @@
 # Plot the colorbar
 fig.colorbar(
     cmap=True,  # Use colormap set up above
-    # Colorbar placed inside the plot bounding box (j) at Bottom Left (BL),
-    # offset (+o) by 0.5 cm horizontally and 0.8 cm vertically from anchor
+    # Colorbar placed inside the plot bounding box (j) in the Bottom Left (BL) corner,
+    # with an offset (+o) by 0.5 cm horizontally and 0.8 cm vertically from the anchor
     # point, and plotted horizontally (+h)
     position="jBL+o0.5c/0.8c+h",
     box=True,

examples/gallery/embellishments/inset.py

@@ -16,9 +16,9 @@
 # to "brown", the water to "lightblue", the shorelines width to "thin", and
 # adding a frame
 fig.coast(region="MG+r2", land="brown", water="lightblue", shorelines="thin", frame="a")
-# Create an inset, setting the position to top left, the width to 3.5 cm, and
-# the x- and y-offsets to 0.2 cm. The margin is set to 0, and the border is
-# "gold" with a pen size of 1.5 points.
+# Create an inset, placing it in the Top Left (TL) corner with a width of 3.5 cm and
+# x- and y-offsets of 0.2 cm. The margin is set to 0, and the border is "gold" with a
+# pen size of 1.5 points.
 with fig.inset(position="jTL+w3.5c+o0.2c", margin=0, box="+p1.5p,gold"):
     # Create a figure in the inset using coast. This example uses the azimuthal
     # orthogonal projection centered at 47E, 20S. The land color is set to

examples/gallery/embellishments/inset_rectangle_region.py

@@ -25,8 +25,8 @@
 # figure
 fig.coast(land="lightbrown", water="azure1", shorelines="2p", area_thresh=1000)
 
-# Create an inset map, setting the position to bottom right, and the x- and
-# y-offsets to 0.1 cm, respectively.
+# Create an inset map, placing it in the Bottom Right (BR) corner with x- and
+# y-offsets of 0.1 cm, respectively.
 # The inset map contains the Japan main land. "U54S/3c" means UTM projection
 # with a map width of 3 cm. The inset width and height are automatically
 # calculated from the specified ``region`` and ``projection`` parameters.

examples/gallery/embellishments/legend.py

@@ -43,8 +43,8 @@
 fig.plot(x=x, y=y2, style="c0.07c", fill="dodgerblue", label="cos(x)+1.1")
 
 # Add a legend to the plot; place it within the plot bounding box with both
-# reference ("J") and anchor ("+j") points being TopRight and with an offset
-# of 0.2 centimeters in x and y directions; surround the legend with a box
+# reference ("J") and anchor ("+j") points being the Top Right (TR) corner and an
+# offset of 0.2 centimeters in x and y directions; surround the legend with a box
 fig.legend(position="JTR+jTR+o0.2c", box=True)
 
 # -----------------------------------------------------------------------------
@@ -55,8 +55,8 @@
 
 fig.plot(x=x, y=y4, style="s0.07c", fill="orange", label="cos(x/2)-1.1")
 
-# For a multi-column legend, users have to provide the width via "+w", here it
-# is set to 6 centimeters; reference and anchor points are set to BottomRight
+# For a multi-column legend, users have to provide the width via "+w", here it is
+# set to 6 centimeters; reference and anchor points are the Bottom Right (BR) corner
 fig.legend(position="JBR+jBR+o0.2c+w6c", box=True)
 
 fig.show()

examples/gallery/embellishments/logo.py

@@ -11,7 +11,7 @@
 fig = pygmt.Figure()
 fig.basemap(region=[0, 10, 0, 2], projection="X6c", frame=True)
 
-# add the GMT logo in the Top Right corner of the current map,
+# Add the GMT logo in the Top Right (TR) corner of the current map,
 # scaled up to be 3 cm wide and offset by 0.3 cm in x direction
 # and 0.6 cm in y direction.
 fig.logo(position="jTR+o0.3c/0.6c+w3c")

examples/gallery/embellishments/timestamp.py

@@ -3,9 +3,9 @@
 =========
 
 The :meth:`pygmt.Figure.timestamp` method can draw the GMT timestamp logo on the plot.
-The timestamp will always be shown relative to the bottom-left corner of the plot. By
-default, the ``offset`` and ``justify`` parameters are set to ``("-54p", "-54p")``
-(x, y directions) and ``"BL"`` (bottom-left), respectively.
+The timestamp will always be shown relative to the Bottom Left (BL) corner of the plot.
+By default, the ``offset`` and ``justify`` parameters are set to ``("-54p", "-54p")``
+(x, y directions) and ``"BL"`` (Bottom Left), respectively.
 """
 
 # %%

examples/gallery/images/cross_section.py

@@ -46,8 +46,8 @@
 
 # Add a colorbar for the elevation
 fig.colorbar(
-    # Place the colorbar inside the plot (lower-case "j") with justification
-    # Bottom Right and an offset ("+o") of 0.7 centimeters and
+    # Place the colorbar inside the plot (lower-case "j") in the Bottom
+    # Right (BR) corner with an offset ("+o") of 0.7 centimeters and
     # 0.3 centimeters in x or y directions, respectively
     # Move the x label above the horizontal colorbar ("+ml")
     position="jBR+o0.7c/0.8c+h+w5c/0.3c+ml",

examples/gallery/images/grdlandmask.py

@@ -2,9 +2,8 @@
 Create 'wet-dry' mask grid
 ==========================
 
-The :func:`pygmt.grdlandmask` function allows setting
-all nodes on land or water to a specified value using
-the ``maskvalues`` parameter.
+The :func:`pygmt.grdlandmask` function allows setting all nodes on land
+or water to a specified value using the ``maskvalues`` parameter.
 """
 
 # %%

examples/gallery/lines/wiggle.py

@@ -35,8 +35,8 @@
     pen="1.0p",
     # Draw a blue track with a width of 0.5 points
     track="0.5p,blue",
-    # Plot a vertical scale bar at the right middle. The bar length is 100 in
-    # data (z) units. Set the z unit label to "nT".
-    position="jRM+w100+lnT",
+    # Plot a vertical scale bar at Middle Right (MR). The bar length (+w)
+    # is 100 in data (z) units. Set the z unit label (+l) to "nT".
+    position="jMR+w100+lnT",
 )
 fig.show()

examples/gallery/maps/borders.py

@@ -11,9 +11,9 @@
 * **3** = Marine boundaries
 * **a** = All boundaries (1-3)
 
-For example, to draw national boundaries with a line thickness of 1p and black
-line color use ``borders="1/1p,black"``. You can draw multiple boundaries by
-passing in a list to ``borders``.
+For example, to draw national boundaries with a line thickness of 1 point and
+black line color use ``borders="1/1p,black"``. You can draw multiple boundaries
+by passing in a list to ``borders``.
 """
 
 # %%

examples/gallery/maps/country_polygons.py

@@ -22,7 +22,7 @@
     water="white",
     frame="afg",
     dcw=[
-        # Great Britain (country code) with seagrean land
+        # Great Britain (country code) with seagreen land
         "GB+gseagreen",
         # Italy with a red border
         "IT+p0.5p,red3",

examples/gallery/symbols/points.py

@@ -2,8 +2,8 @@
 Points
 ======
 
-The :meth:`pygmt.Figure.plot` method can plot points. The plot symbol and size
-is set with the ``style`` parameter.
+The :meth:`pygmt.Figure.plot` method can plot data points. The symbol and
+size are set with the ``style`` parameter.
 """
 
 # %%

examples/tutorials/advanced/insets.py

@@ -31,12 +31,12 @@
 # %%
 # The :meth:`pygmt.Figure.inset` method uses a context manager, and is called
 # using a ``with`` statement. The ``position`` parameter, including the inset
-# width, is required to plot the inset. Using the **j** argument, the location
-# of the inset is set to one of the 9 anchors (bottom-middle-top and
-# left-center-right). In the example below, ``BL`` sets the inset to the bottom
-# left. The ``box`` parameter can set the fill and border of the inset. In the
-# example below, ``+pblack`` sets the border color to black and ``+glightred``
-# sets the fill to light red.
+# width, is required to plot the inset. Using the **j** modifier, the location
+# of the inset is set to one of the 9 anchors (Top - Middle - Bottom and Left -
+# Center - Right). In the example below, ``BL`` places the inset at the Bottom
+# Left corner. The ``box`` parameter can set the fill and border of the inset.
+# In the example below, ``+pblack`` sets the border color to black and
+# ``+glightred`` sets the fill to light red.
 
 fig = pygmt.Figure()
 fig.coast(

pygmt/encodings.py

@@ -1,13 +1,13 @@
 """
-Adobe character encodings supported by GMT.
+Character encodings supported by GMT.
 
-Currently, only Adobe Symbol, Adobe ZapfDingbats, and Adobe ISOLatin1+ encodings are
-supported.
+Currently, Adobe Symbol, Adobe ZapfDingbats, Adobe ISOLatin1+ and ISO-8859-x (x can be
+1-11, 13-16) encodings are supported. Adobe Standard encoding is not supported.
 
-The corresponding Unicode characters in each Adobe character encoding are generated
-from the mapping table and conversion script in the GMT-octal-codes
-(https://github.com/seisman/GMT-octal-codes) repository. Refer to that repository for
-details.
+The corresponding Unicode characters in each Adobe character encoding are generated from
+the mapping tables and conversion scripts in the
+`GMT-octal-codes repository <https://github.com/seisman/GMT-octal-codes>`__. Refer to
+that repository for details.
 
 Some code points are undefined and are assigned with the replacement character
 (``\ufffd``).
@@ -16,14 +16,17 @@
 ----------
 
 - GMT-octal-codes: https://github.com/seisman/GMT-octal-codes
-- GMT official documentation: https://docs.generic-mapping-tools.org/dev/reference/octal-codes.html
+- GMT documentation: https://docs.generic-mapping-tools.org/dev/reference/octal-codes.html
 - Adobe Postscript Language Reference: https://www.adobe.com/jp/print/postscript/pdfs/PLRM.pdf
-- ISOLatin1+: https://en.wikipedia.org/wiki/PostScript_Latin_1_Encoding
+- Adobe ISOLatin1+: https://en.wikipedia.org/wiki/PostScript_Latin_1_Encoding
 - Adobe Symbol: https://en.wikipedia.org/wiki/Symbol_(typeface)
-- Zapf Dingbats: https://en.wikipedia.org/wiki/Zapf_Dingbats
+- Adobe ZapfDingbats: https://en.wikipedia.org/wiki/Zapf_Dingbats
 - Adobe Glyph List: https://github.com/adobe-type-tools/agl-aglfn
+- ISO-8859: https://en.wikipedia.org/wiki/ISO/IEC_8859
 """
 
+import codecs
+
 # Dictionary of character mappings for different encodings.
 charset: dict = {}
 
@@ -129,3 +132,12 @@
         strict=False,
     )
 )
+
+# ISO-8859-x charsets and x can be 1-11, 13-16.
+for i in range(1, 17):
+    if i == 12:  # ISO-8859-12 was abandoned.
+        continue
+    charset[f"ISO-8859-{i}"] = {
+        code: codecs.decode(bytes([code]), f"iso8859_{i}", errors="replace")
+        for code in [*range(0o040, 0o200), *range(0o240, 0o400)]
+    }

pygmt/helpers/__init__.py

@@ -15,6 +15,7 @@
     unique_name,
 )
 from pygmt.helpers.utils import (
+    _check_encoding,
     _validate_data_input,
     args_in_kwargs,
     build_arg_list,