Shapefile user guide typos (#5759)

* typos

* Apply suggestions from code review

still needs links to be added

Co-authored-by: Bill Little <[email protected]>

* added links to match review

* added space to warning

---------

Co-authored-by: Bill Little <[email protected]>

docs/src/common_links.inc

@@ -35,6 +35,7 @@
 .. _ruff: https://github.com/astral-sh/ruff
 .. _SciTools: https://github.com/SciTools
 .. _scitools-iris: https://pypi.org/project/scitools-iris/
+.. _Shapely: https://shapely.readthedocs.io/en/stable/index.html
 .. _sphinx: https://www.sphinx-doc.org/en/master/
 .. _sphinx-apidoc: https://github.com/sphinx-contrib/apidoc
 .. _test-iris-imagehash: https://github.com/SciTools/test-iris-imagehash

docs/src/userguide/subsetting_a_cube.rst

@@ -1,3 +1,5 @@
+.. include:: ../common_links.inc
+
 .. _subsetting_a_cube:
 
 =================
@@ -338,26 +340,32 @@ Cube Masking
 Masking from a shapefile
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-Often we want to perform so kind of analysis over a complex geographical feature - only over land points or sea points:
-or over a continent, a country, a river watershed or administrative region. These geographical features can often be described by shapefiles.
-Shapefiles are a file format first developed for GIS software in the 1990s, and now `Natural Earth`_ maintain a large freely usable database of shapefiles of many geographical and poltical divisions,
-accessible via cartopy. Users may also provide their own custom shapefiles.
+Often we want to perform some kind of analysis over a complex geographical feature e.g.,
+
+- over only land/sea points
+- over a continent, country, or list of countries
+- over a river watershed or lake basin
+- over states or administrative regions of a country
+
+These geographical features can often be described by `ESRI Shapefiles`_. Shapefiles are a file format first developed for GIS software in the 1990s, and `Natural Earth`_ maintain a large freely usable database of shapefiles of many geographical and political divisions,
+accessible via `cartopy`_. Users may also provide their own custom shapefiles for `cartopy`_ to load, or their own underlying geometry in the same format as a shapefile geometry.
 
 These shapefiles can be used to mask an iris cube, so that any data outside the bounds of the shapefile is hidden from further analysis or plotting.
 
-First, we load the correct shapefile from NaturalEarth via the `Cartopy`_ instructions. Here we get one for Brazil.
-The `.geometry` attribute of the records in the reader contain the shapely polygon we're interested in - once we have those we just need to provide them to
-the :class:`iris.util.mask_cube_from_shapefile` function. Once plotted, we can see that only our area of interest remains in the data.
+First, we load the correct shapefile from NaturalEarth via the `Cartopy_shapereader`_ instructions. Here we get one for Brazil.
+The `.geometry` attribute of the records in the reader contain the `Shapely`_ polygon we're interested in. They contain the coordinates that define the polygon (or set of lines) being masked
+and once we have those we just need to provide them to the :class:`iris.util.mask_cube_from_shapefile` function. 
+This returns a copy of the cube with a :class:`numpy.masked_array` as the data payload, where the data outside the shape is hidden by the masked array. We can see this in the following example.
 
 
 .. plot:: userguide/plotting_examples/masking_brazil_plot.py
    :include-source:
 
-We can see that the dimensions of the cube haven't changed - the plot is still global. But only the data over Brazil is plotted - the rest is masked.
+We can see that the dimensions of the cube haven't changed - the plot is still global. But only the data over Brazil is plotted - the rest has been masked out. 
 
 .. note::
     While Iris will try to dynamically adjust the shapefile to mask cubes of different projections, it can struggle with rotated pole projections and cubes with Meridians not at 0°
-    Converting your Cube's coordinate system may help if you get a fully masked cube from this function.
+    Converting your Cube's coordinate system may help if you get a fully masked cube as the output from this function unexpectedly.
 
 
 Cube Iteration
@@ -473,5 +481,8 @@ Similarly, Iris cubes have indexing capability::
 	print(cube[1, ::-2])
 
 
-.. _Cartopy: https://scitools.org.uk/cartopy/docs/latest/tutorials/using_the_shapereader.html#id1
+.. _Cartopy_shapereader: https://scitools.org.uk/cartopy/docs/latest/tutorials/using_the_shapereader.html#id1
 .. _Natural Earth: https://www.naturalearthdata.com/
+.. _ESRI Shapefiles: https://support.esri.com/en-us/technical-paper/esri-shapefile-technical-description-279
+
+