A variety of rst fixes plus a few code standardizations (#574)

Most of this PR is just improving the RST docs but also fixing mistakes as I find them (typos, formatting error etc).  I ran across a few issues that warranted a code update:
psmeca and pscoupe had optino syntax that ended in optional f and u.  I changed this to +f and +u (backwards compatible)
mgd77list had -C for distance calculations, changed to -j
talwani3d did not allow user to set latitude for geoid calculations

Author: PaulWessel

doc/rst/source/begin.rst_

@@ -18,10 +18,14 @@ Synopsis
 Description
 -----------
 
-The **begin** module tells GMT to begin a new modern session.  If your script only makes
-a single plot then this is the most straightforward way to specify the name
+The **begin** module instructs GMT to begin a new modern session.  If your script only makes
+a single plot then this is the most opportune time to specify the name
 and format(s) of your plot.  However, if multiple illustrations will be made
-then you will need to use :doc:`figure` as well.
+then you will instead use :doc:`figure` for each figure you wish to make.  The session
+keeps track of all default and history settings and isolates them from any other session
+that may run concurrently.  Thus unlike in classic mode you can run multiple modern sessions
+simultaneously without having destructive interference in updating the history of common
+options.
 
 Optional Arguments
 ------------------
@@ -30,12 +34,13 @@ Optional Arguments
 
 *prefix*
     Name-stem used to construct the single final figure name.  The extension is appended
-    automatically from your *formats* selection(s) [gmtsession].
+    automatically from your *formats* selection(s) [gmtsession].  If your script only
+    performs calculations or needs to make several figures then you will not use this argument.
 
 .. _begin-formats:
 
 *formats*
-    Give one or more comma-separated graphics extensions from the list of allowable graphics
+    Give one or more comma-separated graphics extensions from the list of allowable graphics formats
     :ref:`formats <tbl-formats>` [pdf].
 
 .. _begin-V:
@@ -90,16 +95,7 @@ are produced then we do not need to give any further arguments:
 Should we give such a command and still produce a plot then it will automatically
 be called gmtsession.pdf.
 
-Note on PostScript
-------------------
-
-If the user selects **ps** as one of the formats, then please be aware that
-it is recommended you first set the desired paper size.  GMT needs to
-work with a fixed paper size since, unlike the **eps** format, there will be
-no cropping to BoundingBox.  If no paper size is specified via :ref:`PS_MEDIA <PS_MEDIA>`
-then GMT will default to A4 and issue a warning; GMT is unable to determine if that
-size is adequate for your plot but if the plot width exceeds A4 paper width we will
-switch page orientation to landscape.
+.. include:: explain_postscript.rst_
 
 See Also
 --------

doc/rst/source/clear.rst_

@@ -19,7 +19,7 @@ Description
 -----------
 
 The clear command allows users to delete their current history, conf,
-or cpt file, remove the entire user cache, data, or sessions directory, or all of the above.
+or cpt files, remove the entire user cache, data, or sessions directory, or all of the above.
 
 Optional Arguments
 ------------------
@@ -32,7 +32,7 @@ Optional Arguments
 .. _clear-conf:
 
 *conf*
-    Delete the current gmt.conf file used for the modern session.
+    Delete the current gmt.conf file used for the current modern session.
 
 .. _clear-cpt:
 
@@ -42,12 +42,12 @@ Optional Arguments
 .. _clear-cache:
 
 *cache*
-    Delete the user's cache directory and its contents.
+    Delete the user's cache directory and all of its contents.
 
 .. _clear-data:
 
 *data*
-    Delete the user's data download directory and its contents.
+    Delete the user's data download directory and all of its contents.
 
 .. _clear-history:
 

doc/rst/source/docs.rst_

@@ -9,7 +9,7 @@ Synopsis
 
 .. include:: common_SYN_OPTs.rst_
 
-**gmt docs** [ **-Q** ] *<module-name>* [*-option*]
+**gmt docs** [ **-Q** ] *module-name* [*-option*]
 
 |No-spaces|
 
@@ -18,26 +18,27 @@ Description
 
 **docs** tells GMT to display the HTML version of a module's documentation using the default browser.
 For the time being, only modern mode module names are displayed. That is, if user asks for
-*gmt docs psxy* she will see the *plot* documentation. Besides the modules names, the special
+*gmt docs psxy* she will see the (near-equivalent) *plot* documentation. Besides the modules names, the special
 forms *cookbook*, *gallery*, *gmt.conf*, *api* and *tutorial* are also accepted.
 
-However, **docs** can also be used to open local files such as PDF or image files or
+However, **docs** can also be used to open local files such as PDF or image files or even
 web link addresses.
 
 Optional Arguments
 ------------------
 
 **-Q**
     This option means we are doing a "dry-run" and simply want the final URL to be
-    printed to standard output.  No browser command will take place.
+    printed to standard output.  No browser command will take place. This is useful
+    if you are working remotely on a server and do not wish to launch a GUI browser.
 
 
 Optional Module Arguments
 -------------------------
 
 *-option*
     Where *-option* is the one-letter option of the module in question (e.g, **-R**).
-    It then displays the documentation positioned at that specific option.
+    We then display the *module* documentation positioned at that specific option.
 
 Examples
 --------
@@ -74,6 +75,12 @@ To see the beautiful figure that I just created with GMT.
 
     gmt docs my_beautiful_figure.pdf
 
+To display the URL to the surface man page,.run
+
+   ::
+
+    gmt docs -Q surface
+
 See Also
 --------
 

doc/rst/source/end.rst_

@@ -18,8 +18,9 @@ Synopsis
 Description
 -----------
 
-This **end** module terminates the modern mode and finalizes the processing of all registered
-figures.  The final graphics will be placed in the current directory.
+This **end** module terminates the modern mode session created with **begin** and finalizes the processing of all registered
+figures.  The final graphics will be placed in the current directory and the hidden sessions directory
+will be removed.
 
 Optional Arguments
 ------------------

doc/rst/source/explain_distcalc.rst_

@@ -1,2 +1,2 @@
-**-je**\ \|\ **f**\ \|\ **g** :ref:`(more ...) <-j_full>`
-    Determine how spherical distances are calculated. |Add_-j|
+**-je**\ \|\ **f**\ \|\ **g** :ref:`(more ...) <distcalc_full>`
+    Determine how spherical distances are calculated.

doc/rst/source/explain_distcalc_full.rst_

@@ -1,4 +1,4 @@
-.. _-j_full:
+.. _distcalc_full:
 
 **-je**\ \|\ **f**\ \|\ **g**
     Determine how spherical distances are calculated in modules that support this.

doc/rst/source/explain_postscript.rst_

@@ -0,0 +1,11 @@
+Note on PostScript
+------------------
+
+If the user selects **ps** as one of the formats, then please be aware that
+it is recommended you first set the desired paper size.  With *ps, GMT needs to
+work with a fixed paper size since, unlike the **eps** format, there will be
+no cropping to BoundingBox.  If no paper size is specified via :ref:`PS_MEDIA <PS_MEDIA>`
+then GMT will default to A4 and issue a warning; GMT is unable to determine if that
+size is adequate for your plot but if the canvas width exceeds A4 paper width we will
+switch page orientation to landscape. For all other formats the final dimension will
+be determined automatically.

doc/rst/source/figure.rst_

@@ -19,21 +19,22 @@ Description
 -----------
 
 A GMT modern session can make any number of illustrations (including none).
-In situations when many illustrations will be made during the session,
-the **figure** module specifies the name and format(s) to use for the current plot.
-It must be issued before you start plotting to the current figure, and each
+In situations when many illustrations will be made during a single session,
+the **figure** module is used to specify the name and format(s) to use for the next plot.
+It must be issued before you start plotting to the intended figure, and each
 new **figure** call changes plotting focus to the next figure.  You may go back and forth between
-different figure but the optional arguments (*formats* and *options*) can only
+different figures but the optional arguments (*formats* and *options*) can only
 be given the first time you specify a new figure.
 In addition to *prefix* and *formats*, you can supply a comma-separated series of
 :doc:`psconvert` options that will override the default settings provided via
-:ref:`PS_CONVERT <PS_CONVERT>`. The only other available option controls verbosity.
+:ref:`PS_CONVERT <PS_CONVERT>` [**A**]. The only other available options control verbosity
+and default parameter settings.
 
 Required Arguments
 ------------------
 
 *prefix*
-    Name stem used to construct final figure names,  The extension is appended
+    Name stem used to construct the figure name.  The extension(s) are appended
     automatically from your *formats* selection(s).
 
 Optional Arguments
@@ -48,8 +49,8 @@ Optional Arguments
 .. _figure-options:
 
 *options*
-    Sets one or more comma-separated options arguments that
-    can be passed to :doc:`psconvert` when preparing this figure [A].
+    Sets one or more comma-separated options (and possibly arguments) that
+    can be passed to :doc:`psconvert` when preparing this figure [**A**].
     The valid subset of options are
     **A**\ [*args*],\ **C**\ *args*,\ **D**\ *dir*,\ **E**\ *dpi*,\ **H**\ *factor*,\ **M**\ *args*,\ **Q**\ *args*,\ **S**.
     See the :doc:`psconvert` documentation for details on these options.
@@ -61,6 +62,8 @@ Optional Arguments
 
 .. include:: explain_help.rst_
 
+.. include:: explain_postscript.rst_
+
 Examples
 --------
 

doc/rst/source/inset.rst_

@@ -4,11 +4,11 @@
 
     Manage figure inset setup and completion
 
-The **inset** module is used to carve out a sub-region of the current plot and
-limit further plotting to that section of the canvas.  The inset setup is started with the **begin**
-mode that defines the placement and size of the inset.  Subsequent plot commands will be directed
-to that window.  The inset is completed via the **end** mode, which reverts operations to the full
-canvas and restores the plot region and projection that was in effect prior to the setup of the inset.
+The **inset** module is used to carve out a sub-region of the current plot canvas and
+restrict further plotting to that section of the canvas.  The inset setup is started with the **begin**
+directive that defines the placement and size of the inset.  Subsequent plot commands will be directed
+to that window.  The inset is completed via the **end** directive, which reverts operations to the full
+canvas and restores the plot region and map projection that was in effect prior to the setup of the inset.
 
 Synopsis (begin mode)
 ---------------------
@@ -27,8 +27,8 @@ Synopsis (begin mode)
 Description
 -----------
 
-The **begin** mode of inset defines the dimension and placement of the inset canvas.  It
-makes a note of the current region and projection so that we may return to the initial
+The **begin** directive of **inset** defines the dimension and placement of the inset canvas.  It
+records the current region and projection so that we may return to the initial
 plot environment when  the inset is completed.
 
 Required Arguments
@@ -98,8 +98,8 @@ Synopsis (end mode)
 
 **gmt inset end** [ |SYN_OPT-V| ]
 
-This command finalizes the current inset, which returns the plotting environment to
-the state prior to the start of the inset.  The previous region and projection will be
+The **end** directive finalizes the current inset, which returns the plotting environment to
+the state prior to the start of the inset.  The previous region and map projection will be
 in effect going forward.
 
 Optional Arguments
@@ -114,7 +114,7 @@ Optional Arguments
 Examples
 --------
 
-To make a simple basemap layout with an inset called inset.pdf, try
+To make a simple basemap plot called inset.pdf that demonstrates the inset module, try
 
    ::
 

doc/rst/source/subplot.rst_

@@ -4,10 +4,10 @@
 
     Manage modern mode figure subplot configuration and selection
 
-The **subplot** module is used to split the current figure into a matrix of subplots
+The **subplot** module is used to split the current figure into a rectangular layout of subplots
 that each may contain a single panel figure.  A subplot setup is started with the **begin**
-mode that defines the layout of the subplots, while positioning to a particular panel for
-plotting is done via the **set** mode.  The subplot is completed via the **end** mode.
+directive that defines the layout of the subplots, while positioning to a particular panel for
+plotting is done via the **set** directive.  The subplot is completed via the **end** directive.
 
 Synopsis (begin mode)
 ---------------------
@@ -32,8 +32,8 @@ Synopsis (begin mode)
 Description
 -----------
 
-The **begin** mode of subplot defines the layout of the entire multi-panel illustration.  Several
-options are available to specify the systematic layout, labeling, dimensions, and more.
+The **begin** directive of subplot defines the layout of the entire multi-panel illustration.  Several
+options are available to specify the systematic layout, labeling, dimensions, and more for the panels.
 
 Required Arguments
 ------------------
@@ -52,7 +52,7 @@ Required Arguments
     a single panel.
 
 **-Ff**
-    Specify the final figure dimensions.  The subplot dimensions are then calculated from the figure
+    Specify the final **f**igure dimensions.  The subplot dimensions are then calculated from the figure
     dimensions after accounting for the space that optional tick marks, annotations, labels, and margins occupy between panels.
     The annotations, ticks, and labels along the outside perimeter are not counted as part of the figure dimensions.
     To specify different subplot dimensions for each row (or column), append **+f** followed by a comma-separated list of width
@@ -61,7 +61,7 @@ Required Arguments
     A single number means constant widths (or heights) [Default].
 
 **-Fs**
-    Specify the dimensions of each subplot directly.  Then, the figure dimensions are computed from the
+    Specify the dimensions of each **s**ubplot directly.  Then, the figure dimensions are computed from the
     subplot dimensions after adding the space that optional tick marks, annotations, labels, and margins occupy between panels.
     The annotations, ticks, and labels along the outside perimeter are not counted as part of the figure dimensions.
     To specify different subplot dimensions for each row (or column),  append a colon followed by a comma-separated list of widths,
@@ -87,7 +87,7 @@ Optional Arguments
     Note: **+j** sets the justification of the tag to *refpoint* (suitable for interior tags)
     while **+J** instead selects the mirror opposite (suitable for exterior tags).
     Append **+c**\ *dx*\ [/*dy*] to set the clearance between the tag and a surrounding text box
-    requested via **+g** or **p** [3pt/3pt, i.e., 15% of the :ref:`FONT_TAG size <FONT_TAG>` size].
+    requested via **+g** or **+p** [3pt/3pt, i.e., 15% of the :ref:`FONT_TAG size <FONT_TAG>` dimension].
     Append **+g**\ *fill* to paint the tag's text box with *fill* [no painting].
     Append **+o**\ *dx*\ [/*dy*] to offset the tag's reference point in the direction implied
     by the justification [4pt/4pt, i.e., 20% of the :ref:`FONT_TAG size <FONT_TAG>`].
@@ -104,7 +104,7 @@ Optional Arguments
     Reserve a space of dimension *clearance* between the margin and the subplot on the specified
     side, using *side* values from **w**, **e**, **s**, or **n**.  The option is repeatable to set aside space
     on more than one side.  Such space will be left untouched by the main map plotting but can
-    be accessed by modules that plot scales, bars, text, etc.  Settings specified under **begin** mode apply to all panels.
+    be accessed by modules that plot scales, bars, text, etc.  Settings specified under **begin** directive apply to all panels.
 
 .. _-J:
 
@@ -114,7 +114,7 @@ Optional Arguments
 .. _subplot_begin-M:
 
 **-M**\ *margins*
-    This is clearance that is added around each subplot beyond the automatic space allocated for tick marks,
+    This is margin space that is added around each subplot beyond the automatic space allocated for tick marks,
     annotations, and labels.  The margins can be a single value, a pair of values separated by slashes
     (for setting separate horizontal and vertical margins), or the full set of four margins (for setting
     separate left, right, bottom, and top margins) [0.5c].
@@ -123,20 +123,21 @@ Optional Arguments
 
 .. |Add_-R| unicode:: 0x20 .. just an invisible code
 .. include:: explain_-R.rst_
+    This is useful when all subplots share a common plot domain.
 
 .. _subplot_begin-S:
 
 **-S**\ *layout*
     Set subplot layout for shared axes. May be set separately for rows (**-SR**) and columns (**-SC**).
-    **-SC**: Use when all subplots in a **C**\ olumn share a common *x*-range. The first (i.e., **t**\ op) and the last
+    Considerations for **-SC**: Use when all subplots in a **C**\ olumn share a common *x*-range. The first (i.e., **t**\ op) and the last
     (i.e., **b**\ ottom) rows will have *x* annotations; append **t** or **b** to select only one of those two rows [both].
     Append **+l** if annotated *x*-axes should have a label [none]; optionally append the label if it is the same
     for the entire subplot.
-    **-SR**: Use when all subplots in a **R**\ ow share a common *y*-range. The first (i.e., **l**\ eft) and the last
+    Considerations for **-SR**: Use when all subplots in a **R**\ ow share a common *y*-range. The first (i.e., **l**\ eft) and the last
     (i.e., **r**\ ight) columns will have *y*-annotations; append **l** or **r** to select only one of those two columns [both].
     Append **+l** if annotated *y*-axes will have a label [none]; optionally, append the label if it is the same
     for the entire subplot.
-    Append **+p** to make all annotations axis-parallel [horizontal]; if used you may have to set **-C** to secure
+    Append **+p** to make all annotations axis-parallel [horizontal]; if not used you may have to set **-C** to secure
     extra space for long horizontal annotations.
     Append **+t** to make space for subplot titles for each row; use **+tc** for top row titles only [no subplot titles].
     Labels and titles that depends on which row or column are specified as usual via a panel's **-B** setting.
@@ -213,7 +214,7 @@ Synopsis (end mode)
 
 This command finalizes the current subplot, including any placement of tags, and updates the
 dimensions of the last plot to that of the entire subplot. This allows **-X** and **-Y** to
-use *w* and *h* in setting the current point relative to the entire subplot.  We also reset
+use the codes *w* and *h* in setting the current point relative to the entire subplot.  We also reset
 the current plot location to where it was prior to the subplot.
 
 Optional Arguments

doc/rst/source/supplements/img/img2grd.rst

@@ -15,10 +15,10 @@ Synopsis
 
 **gmt img2grd** *imgfile* |-G|\ *grdfile*
 |SYN_OPT-R|
-|-T|\ *type*
 [ |-C| ]
 [ |-D|\ [*minlat/maxlat*] ] [ |-E| ] [ |-I|\ *inc* ]
 [ |-M| ] [ |-N|\ *navg* ] [ |-S|\ [*scale*] ]
+[ |-T|\ *type* ]
 [ |SYN_OPT-V| ]
 [ |-W|\ *maxlon* ]
 [ |SYN_OPT-n| ]