Improve the first figure tutorial

examples/tutorials/first-figure.py

@@ -7,7 +7,8 @@
 
 .. note::
 
-    This tutorial assumes the use of a Python notebook, such as IPython or Jupyter Notebook.
+    This tutorial assumes the use of a Python notebook, such as `IPython <https://ipython.org/>`__
+    or `JupyterLab <https://jupyter.org/>`__.
     To see the figures while using a Python script instead, use
     ``fig.show(method="external")`` to display the figure in the default PDF viewer.
 
@@ -34,11 +35,13 @@
 fig = pygmt.Figure()
 
 ########################################################################################
-# Add elements to the figure using its methods. For example, let's start a map with an
-# automatic frame and ticks around a given longitude and latitude bound, set the
-# projection to Mercator (``M``), and the map width to 8 inches:
+# Add elements to the figure using its methods. For example, let's use
+# :meth:`pygmt.Figure.basemap` to start the creation of a map. We'll use the ``region`` parameter
+# to provide the longitude and latitude bounds, the ``projection`` parameter to set
+# the projection to Mercator (**M**) and the map width to 15 cm, and the ``frame``
+# parameter to generate a frame with automatic tick and annotation spacings.
 
-fig.basemap(region=[-90, -70, 0, 20], projection="M8i", frame=True)
+fig.basemap(region=[-90, -70, 0, 20], projection="M15c", frame=True)
 
 ########################################################################################
 # Now we can add coastlines using :meth:`pygmt.Figure.coast` to this map using the
@@ -56,7 +59,7 @@
 # without calling :meth:`gmt.Figure.basemap`:
 
 fig = pygmt.Figure()
-fig.coast(shorelines=True, region=[-90, -70, 0, 20], projection="M8i", frame=True)
+fig.coast(shorelines=True, region=[-90, -70, 0, 20], projection="M15c", frame=True)
 fig.show()
 
 ########################################################################################
@@ -73,21 +76,29 @@
 # Note for experienced GMT users
 # ------------------------------
 #
-# You’ll probably have noticed several things that are different from classic
-# command-line GMT. Many of these changes reflect the new GMT modern execution mode that
-# are part of GMT 6. A few are PyGMT exclusive (like the ``savefig`` method).
+# You have probably noticed several things that are different from classic
+# command-line GMT. Many of these changes reflect the new GMT modern execution
+# mode that is part of GMT 6.
 #
-# 1. The name of method is ``coast`` instead of ``pscoast``. As a general rule, all
-#    ``ps*`` modules had their ``ps`` prefix removed. The exceptions are:
-#    ``psxy`` which is now ``plot``, ``psxyz`` which is now ``plot3d``, and ``psscale``
-#    which is now ``colorbar``.
-# 2. The parameters don't use the GMT 1-letter syntax (**R**, **J**, **B**, etc). We use longer
+# 1. As a general rule, the ``ps`` prefix has been removed from all ``ps*``
+#    modules (PyGMT methods). For example, the name of the GMT 5 module ``pscoast``
+#    is ``coast`` in GMT 6 and PyGMT. The exceptions are:  ``psxy`` which is now
+#    ``plot``, ``psxyz`` which is now ``plot3d``, and ``psscale`` which is now
+#    ``colorbar``.
+#
+# 2. More details can be found in the :gmt-docs:`GMT cookbook introduction to
+#    modern mode </cookbook/introduction.html#modern-and-classic-mode>`.
+#
+# A few are PyGMT exclusive (like the ``savefig`` method).
+#
+# 1. The PyGMT parameters (called options or arguments in GMT) don't use the GMT
+#    1-letter syntax (**R**, **J**, **B**, etc). We use longer
 #    aliases for these parameters and have some Python exclusive names. The mapping
-#    between the GMT parameters and their Python counterparts should be straight
-#    forward.
-# 3. Parameters like ``region`` can take lists as well as strings like ``1/2/3/4``.
-# 4. If a GMT parameter has no options (like ``-B`` instead of ``-Baf``), use a ``True``
+#    between the GMT parameters and their PyGMT aliases should be straightforward.
+#    For some modules, these aliases are still being developed.
+# 2. Parameters like ``region`` can take :class:`lists <list>` as well as strings like ``1/2/3/4``.
+# 3. If a GMT option has no arguments (like ``-B`` instead of ``-Baf``), use a ``True``
 #    in Python. An empty string would also be acceptable. For repeated parameters, such
-#    as ``-B+Loleron -Bxaf -By+lm``, provide a list: ``frame=["+Loleron", "xaf", "y+lm"]``.
-# 5. There is no output redirecting to a PostScript file. The figure is generated in the
+#    as ``-B+Loleron -Bxaf -By+lm``, provide a :class:`list`: ``frame=["+Loleron", "xaf", "y+lm"]``.
+# 4. There is no output redirecting to a PostScript file. The figure is generated in the
 #    background and will only be shown or saved when you ask for it.