Clean up modern docs

doc_modern/rst/source/begin.rst_

@@ -2,7 +2,7 @@
 
 .. only:: not man
 
- Initiate a new GMT session using modern mode
+ Initiate a new GMT modern mode session
 
 Synopsis
 --------
@@ -18,9 +18,9 @@ Synopsis
 Description
 -----------
 
-The **begin** tells GMT to begin a new modern session. If your script only makes
+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
-and format(s) of your plots. However, if multiple illustrations will be made
+and format(s) of your plot. However, if multiple illustrations will be made
 then you will need to use :doc:`figure` as well.
 
 Optional Arguments
@@ -29,13 +29,13 @@ Optional Arguments
 .. _begin-prefix:
 
 *prefix*
- Name-stem used to construct the single final figure name. Extensions are appended
- automatically from your *formats* selection [gmtsession].
+ Name-stem used to construct the single final figure name. The extension is appended
+ automatically from your *formats* selection(s) [gmtsession].
 
 .. _begin-formats:
 
 *formats*
- Give one or more comma-separated graphics extensions from the allowable graphics
+ Give one or more comma-separated graphics extensions from the list of allowable graphics
  :ref:`formats <tbl-formats>` [pdf].
 
 .. _begin-V:
@@ -72,16 +72,16 @@ Optional Arguments
 Examples
 --------
 
-To initiate a new modern session that should produce a single
-map called Figure_2 represented by both a PDF and a PNG
-raster image, we would run
+To initiate a new modern session that will produce a single
+map called Figure_2 saved as both a PDF vector graphics file
+and an opaque PNG raster image, we would run
 
  ::
 
  gmt begin Figure_2 pdf,png
 
-If the modern session is only used for computations and no illustration
-is made then we do not need to give any further arguments
+If the modern session is only used for computations and no illustrations
+are produced then we do not need to give any further arguments:
 
  ::
 

doc_modern/rst/source/docs.rst_

@@ -21,14 +21,14 @@ For the time being, only modern mode module names are displayed. That is, if use
 *gmt docs psxy* she will see the *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 formats or
+However, **docs** can also be used to open local files such as PDF or image files or
 web link addresses.
 
 Optional Arguments
 ------------------
 
 *-option*
- Where *-option* is the one-letter option of the module in question (e.g, **-R**)
+ 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.
 
 Examples

doc_modern/rst/source/end.rst_

@@ -18,7 +18,7 @@ Synopsis
 Description
 -----------
 
-This command terminates the modern mode and finalizes the processing of all registered
+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.
 
 Optional Arguments
@@ -34,7 +34,7 @@ Optional Arguments
 Examples
 --------
 
-To close the session and finalize any plots requested, use
+To close the current modern session and finalize any plots requested, we use
 
  ::
 

doc_modern/rst/source/figure.rst_

@@ -2,7 +2,7 @@
 
 .. only:: not man
 
- Set attributes for the current figure
+ Set attributes for the current modern mode session figure
 
 Synopsis
 --------
@@ -18,40 +18,40 @@ Synopsis
 Description
 -----------
 
-A GMT modern session can make any number of illustrations. In this situation,
-the figure command tells GMT the name and format(s) to use for the current plot.
+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
-new call changes focus to the next figure. You may go back and forth between
+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
-be given the first time to specify a new figure.
+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 should override the default settings provided via
+:doc:`psconvert` options that will override the default settings provided via
 :ref:`PS_CONVERT <PS_CONVERT>`. The only other available option controls verbosity.
 
 Required Arguments
 ------------------
 
 *prefix*
- Name-stem used to construct final figure names, Extensions are appended
- automatically from your *formats* selection.
+ Name stem used to construct final figure names, The extension is appended
+ automatically from your *formats* selection(s).
 
 Optional Arguments
 ------------------
 
 .. _figure-formats:
 
 *formats*
- Give one or more comma-separated graphics extensions from the allowable graphics
+ Give one or more comma-separated graphics extensions from the list of allowable graphics
  :ref:`formats <tbl-formats>` [pdf].
 
 .. _figure-options:
 
 *options*
  Sets one or more comma-separated options arguments that
- will be passed to :doc:`psconvert` when preparing this figure [A].
+ 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**.
+ **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.
 
 .. _figure-V:
@@ -64,8 +64,8 @@ Optional Arguments
 Examples
 --------
 
-To start a new figure in your session by the name Regional, and request we make both
-a PDF and and EPS file, try
+To start a new figure in your current modern mode session by the name Regional and
+request we make both a PDF and an EPS file, try
 
  ::
 

doc_modern/rst/source/subplot.rst_

@@ -2,15 +2,15 @@
 
 .. only:: not man
 
- Manage figure subplot configuration and selection
+ Manage modern mode figure subplot configuration and selection
 
-The subplot command is used to split the current figure into a matrix of subplots
+The **subplot** module is used to split the current figure into a matrix 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:
+plotting is done via the **set** mode. The subplot is completed via the **end** mode.
 
-Synopsis
---------
+Synopsis (begin mode)
+---------------------
 
 .. include:: common_SYN_OPTs.rst_
 
@@ -153,6 +153,9 @@ Optional Arguments
 
 .. include:: explain_help.rst_
 
+Synopsis (set mode)
+-------------------
+
 **gmt subplot set** *row,col* [ **-A**\ *fixedlabel*] [ **-C**\ *side*\ /*clearance*\ [**u**\ ] ] [ |SYN_OPT-V| ]
 
 Before you start plotting you must first select the active subplot panel.
@@ -204,6 +207,9 @@ frame and axis parameters then you must specify these **-B** options with this f
 command. (2) The subplot machinery automatically uses the **-X** and **-Y** options under
 the hood so these options are not available while a subplot is active.
 
+Synopsis (end mode)
+-------------------
+
 **gmt subplot end** [ |SYN_OPT-V| ]
 
 This command finalizes the current subplot, including any placement of tags, and updates the
@@ -223,11 +229,18 @@ Optional Arguments
 Examples
 --------
 
-To conclude the current subplot, simply use
+To make a minimalistic 2x2 basemap layout called panels.pdf, try
 
  ::
 
- gmt subplot end
+ gmt begin panels pdf
+ gmt subplot begin 2x2 -Fs3i -M5p -A -SCb -SRl -Bwstr
+ gmt psbasemap -R0/80/0/10 -c1,1
+ gmt psbasemap -c1,2
+ gmt psbasemap -c2,1
+ gmt psbasemap -c2,2
+ gmt subplot end
+ gmt end
 
 
 See Also

src/begin.c

@@ -26,7 +26,7 @@
 
 #define THIS_MODULE_NAME "begin"
 #define THIS_MODULE_LIB "core"
-#define THIS_MODULE_PURPOSE "Initiate a new GMT session using modern mode [classic]"
+#define THIS_MODULE_PURPOSE "Initiate a new GMT modern mode session"
 #define THIS_MODULE_KEYS ""
 #define THIS_MODULE_NEEDS ""
 #define THIS_MODULE_OPTIONS "V"
@@ -36,7 +36,7 @@
 GMT_LOCAL int usage (struct GMTAPI_CTRL *API, int level) {
  const char *name = gmt_show_name_and_purpose (API, THIS_MODULE_LIB, THIS_MODULE_NAME, THIS_MODULE_PURPOSE);
  if (level == GMT_MODULE_PURPOSE) return (GMT_NOERROR);
- GMT_Message (API, GMT_TIME_NONE, "usage: %s [<prefix>] [<format(s)>] [%s] [%s]\n\n", name, GMT_V_OPT, GMT_PAR_OPT);
+ GMT_Message (API, GMT_TIME_NONE, "usage: gmt %s [<prefix>] [<format(s)>] [%s] [%s]\n\n", name, GMT_V_OPT, GMT_PAR_OPT);
 
  if (level == GMT_SYNOPSIS) return (GMT_MODULE_SYNOPSIS);
 

src/blockmean.c

@@ -53,7 +53,7 @@ enum Block_Modes {
 GMT_LOCAL int usage (struct GMTAPI_CTRL *API, int level) {
  const char *name = gmt_show_name_and_purpose (API, THIS_MODULE_LIB, THIS_MODULE_NAME, THIS_MODULE_PURPOSE);
  if (level == GMT_MODULE_PURPOSE) return (GMT_NOERROR);
- GMT_Message (API, GMT_TIME_NONE, "usage: %s [<table>] %s %s\n", name, GMT_I_OPT, GMT_Rgeo_OPT);
+ GMT_Message (API, GMT_TIME_NONE, "usage: gmt %s [<table>] %s %s\n", name, GMT_I_OPT, GMT_Rgeo_OPT);
  if (API->external)
  GMT_Message (API, GMT_TIME_NONE, "\t[-A<fields>] [-C] [-E[+p|P]] [-S[m|n|s|w]] [%s] [-W[i][o][+s]]\n", GMT_V_OPT);
  else

src/blockmedian.c

@@ -46,7 +46,7 @@
 GMT_LOCAL int usage (struct GMTAPI_CTRL *API, int level) {
  const char *name = gmt_show_name_and_purpose (API, THIS_MODULE_LIB, THIS_MODULE_NAME, THIS_MODULE_PURPOSE);
  if (level == GMT_MODULE_PURPOSE) return (GMT_NOERROR);
- GMT_Message (API, GMT_TIME_NONE, "usage: %s [<table>] %s\n", name, GMT_I_OPT, GMT_Rgeo_OPT);
+ GMT_Message (API, GMT_TIME_NONE, "usage: gmt %s [<table>] %s\n", name, GMT_I_OPT, GMT_Rgeo_OPT);
  if (API->external)
  GMT_Message (API, GMT_TIME_NONE, "\t[-A<fields>] [-C] [-E[b]] [-Er|s[-]] [-Q] [-T<q>] [%s]\n", GMT_V_OPT);
  else

src/blockmode.c

@@ -57,7 +57,7 @@ struct BIN_MODE_INFO { /* Used for histogram binning */
 GMT_LOCAL int usage (struct GMTAPI_CTRL *API, int level) {
  const char *name = gmt_show_name_and_purpose (API, THIS_MODULE_LIB, THIS_MODULE_NAME, THIS_MODULE_PURPOSE);
  if (level == GMT_MODULE_PURPOSE) return (GMT_NOERROR);
- GMT_Message (API, GMT_TIME_NONE, "usage: %s [<table>] %s\n", name, GMT_I_OPT, GMT_Rgeo_OPT);
+ GMT_Message (API, GMT_TIME_NONE, "usage: gmt %s [<table>] %s\n", name, GMT_I_OPT, GMT_Rgeo_OPT);
  if (API->external)
  GMT_Message (API, GMT_TIME_NONE, "\t[-A<fields>] [-C] [-D<width>[+c][+l|h]] [-E] [-Er|s[-]] [-Q]\n", GMT_V_OPT);
  else

src/clear.c

@@ -38,7 +38,7 @@ EXTERN_MSC void gmtlib_free_list (struct GMT_CTRL *GMT, char **list, uint64_t n)
 GMT_LOCAL int usage (struct GMTAPI_CTRL *API, int level) {
  const char *name = gmt_show_name_and_purpose (API, THIS_MODULE_LIB, THIS_MODULE_NAME, THIS_MODULE_PURPOSE);
  if (level == GMT_MODULE_PURPOSE) return (GMT_NOERROR);
- GMT_Message (API, GMT_TIME_NONE, "usage: %s all|cache|cpt|conf|data|history|sessions [%s] [%s]\n\n", name, GMT_V_OPT, GMT_PAR_OPT);
+ GMT_Message (API, GMT_TIME_NONE, "usage: gmt %s all|cache|cpt|conf|data|history|sessions [%s] [%s]\n\n", name, GMT_V_OPT, GMT_PAR_OPT);
 
  if (level == GMT_SYNOPSIS) return (GMT_MODULE_SYNOPSIS);
 

src/docs.c

@@ -35,7 +35,7 @@
 GMT_LOCAL int usage (struct GMTAPI_CTRL *API, int level) {
  const char *name = gmt_show_name_and_purpose (API, THIS_MODULE_LIB, THIS_MODULE_NAME, THIS_MODULE_PURPOSE);
  if (level == GMT_MODULE_PURPOSE) return (GMT_NOERROR);
- GMT_Message (API, GMT_TIME_NONE, "usage: %s <module-name> [<-option>]\n\n", name);
+ GMT_Message (API, GMT_TIME_NONE, "usage: gmt %s <module-name> [<-option>]\n\n", name);
  GMT_Message (API, GMT_TIME_NONE, "\t<module-name> is one of the core or supplemental modules\n");
 
  if (level == GMT_SYNOPSIS) return (GMT_MODULE_SYNOPSIS);

src/end.c

@@ -35,7 +35,7 @@
 GMT_LOCAL int usage (struct GMTAPI_CTRL *API, int level) {
  const char *name = gmt_show_name_and_purpose (API, THIS_MODULE_LIB, THIS_MODULE_NAME, THIS_MODULE_PURPOSE);
  if (level == GMT_MODULE_PURPOSE) return (GMT_NOERROR);
- GMT_Message (API, GMT_TIME_NONE, "usage: %s [%s] [%s]\n\n", name, GMT_V_OPT, GMT_PAR_OPT);
+ GMT_Message (API, GMT_TIME_NONE, "usage: gmt %s [%s] [%s]\n\n", name, GMT_V_OPT, GMT_PAR_OPT);
 
  if (level == GMT_SYNOPSIS) return (GMT_MODULE_SYNOPSIS);
 

src/figure.c

@@ -27,7 +27,7 @@
 
 #define THIS_MODULE_NAME "figure"
 #define THIS_MODULE_LIB "core"
-#define THIS_MODULE_PURPOSE "Set attributes for the current figure"
+#define THIS_MODULE_PURPOSE "Set attributes for the current modern mode session figure"
 #define THIS_MODULE_KEYS ""
 #define THIS_MODULE_NEEDS ""
 #define THIS_MODULE_OPTIONS "V"
@@ -37,7 +37,7 @@
 GMT_LOCAL int usage (struct GMTAPI_CTRL *API, int level) {
  const char *name = gmt_show_name_and_purpose (API, THIS_MODULE_LIB, THIS_MODULE_NAME, THIS_MODULE_PURPOSE);
  if (level == GMT_MODULE_PURPOSE) return (GMT_NOERROR);
- GMT_Message (API, GMT_TIME_NONE, "usage: %s <prefix> [<formats>] [<psconvertoptions] [%s] [%s]\n\n", name, GMT_V_OPT, GMT_PAR_OPT);
+ GMT_Message (API, GMT_TIME_NONE, "usage: gmt %s <prefix> [<formats>] [<psconvertoptions] [%s] [%s]\n\n", name, GMT_V_OPT, GMT_PAR_OPT);
 
  if (level == GMT_SYNOPSIS) return (GMT_MODULE_SYNOPSIS);
 

src/filter1d.c

@@ -180,7 +180,7 @@ GMT_LOCAL void Free_Ctrl (struct GMT_CTRL *GMT,struct FILTER1D_CTRL *C) { /* Dea
 GMT_LOCAL int usage (struct GMTAPI_CTRL *API, int level) {
  const char *name = gmt_show_name_and_purpose (API, THIS_MODULE_LIB, THIS_MODULE_NAME, THIS_MODULE_PURPOSE);
  if (level == GMT_MODULE_PURPOSE) return (GMT_NOERROR);
- GMT_Message (API, GMT_TIME_NONE, "usage: %s [<table>] -F<type><width>[<modifiers>] [-D<increment>] [-E] [-I<ignore_val>]\n", name);
+ GMT_Message (API, GMT_TIME_NONE, "usage: gmt %s [<table>] -F<type><width>[<modifiers>] [-D<increment>] [-E] [-I<ignore_val>]\n", name);
  GMT_Message (API, GMT_TIME_NONE, "\t[-L<lack_width>] [-N<t_col>] [-Q<q_factor>] [-S<symmetry>] [-T[<min>/<max>/][-|+]<inc>[<unit>][+n|a]]\n");
  GMT_Message (API, GMT_TIME_NONE, "\t[%s] [%s] [%s] [%s] [%s]\n\t[%s] [%s]\n\t[%s] [%s] [%s] [%s]\n\n",
  GMT_V_OPT, GMT_b_OPT, GMT_d_OPT, GMT_e_OPT, GMT_f_OPT, GMT_g_OPT, GMT_h_OPT, GMT_i_OPT, GMT_o_OPT, GMT_colon_OPT, GMT_PAR_OPT);

src/fitcircle.c

@@ -119,7 +119,7 @@ GMT_LOCAL void Free_Ctrl (struct GMT_CTRL *GMT, struct FITCIRCLE_CTRL *C) { /* D
 GMT_LOCAL int usage (struct GMTAPI_CTRL *API, int level) {
  const char *name = gmt_show_name_and_purpose (API, THIS_MODULE_LIB, THIS_MODULE_NAME, THIS_MODULE_PURPOSE);
  if (level == GMT_MODULE_PURPOSE) return (GMT_NOERROR);
- GMT_Message (API, GMT_TIME_NONE, "usage: %s [<table>] -L[<norm>] [-F[<flags>]] [-S[<lat>]] [%s] [%s]\n", name, GMT_V_OPT, GMT_a_OPT);
+ GMT_Message (API, GMT_TIME_NONE, "usage: gmt %s [<table>] -L[<norm>] [-F[<flags>]] [-S[<lat>]] [%s] [%s]\n", name, GMT_V_OPT, GMT_a_OPT);
  GMT_Message (API, GMT_TIME_NONE, "\t[%s] [%s] [%s] [%s] [%s]\n\t[%s] [%s]\n\t[%s] [%s] [%s]\n\n",
  GMT_bi_OPT, GMT_di_OPT, GMT_e_OPT, GMT_f_OPT, GMT_g_OPT, GMT_h_OPT, GMT_i_OPT, GMT_o_OPT, GMT_colon_OPT, GMT_PAR_OPT);
 

src/gmt.c

@@ -229,7 +229,7 @@ int main (int argc, char *argv[]) {
  fprintf (stderr, "You may redistribute copies of this program under the terms of the\n");
  fprintf (stderr, "GNU Lesser General Public License (https://www.gnu.org/licenses/lgpl.html).\n");
  fprintf (stderr, "For more information about legal matters, see the file named LICENSE.TXT.\n\n");
- fprintf (stderr, "usage: %s [options]\n", PROGRAM_NAME);
+ fprintf (stderr, "usage: gmt %s [options]\n", PROGRAM_NAME);
  fprintf (stderr, " %s <module name> [<module-options>]\n\n", PROGRAM_NAME);
  fprintf (stderr, "session management:\n");
  fprintf (stderr, " gmt begin Initiate a new GMT session using modern mode [classic].\n");
@@ -238,8 +238,8 @@ int main (int argc, char *argv[]) {
  fprintf (stderr, " gmt figure Set figure format specifics under a GMT modern mode session.\n");
  fprintf (stderr, " gmt subplot Initiate a multi-panel figure.\n");
  //fprintf (stderr, " gmt revert Undo last <n> layers from current figure.\n");
- fprintf (stderr, " gmt clear history | conf | cache | all\n");
- fprintf (stderr, " Delete gmt.history, gmt.conf, the user cache dir, or all of them.\n\n");
+ fprintf (stderr, " gmt clear all | cache | cpt | conf | data | history | sessions\n");
+ fprintf (stderr, " Delete gmt.history, gmt.conf, session CPT, the user cache or data dir, or all of them.\n\n");
  fprintf (stderr, "options:\n");
  fprintf (stderr, " --help List descriptions of available GMT modules.\n");
  fprintf (stderr, " --show-bindir Show directory with GMT executables.\n");

src/gmt2kml.c

@@ -199,7 +199,7 @@ GMT_LOCAL int usage (struct GMTAPI_CTRL *API, int level) {
 
  const char *name = gmt_show_name_and_purpose (API, THIS_MODULE_LIB, THIS_MODULE_NAME, THIS_MODULE_PURPOSE);
  if (level == GMT_MODULE_PURPOSE) return (GMT_NOERROR);
- GMT_Message (API, GMT_TIME_NONE, "usage: %s [<table>] [-Aa|g|s[<altitude>|x<scale>]] [-C<cpt>] [-D<descriptfile>] [-E]\n", name);
+ GMT_Message (API, GMT_TIME_NONE, "usage: gmt %s [<table>] [-Aa|g|s[<altitude>|x<scale>]] [-C<cpt>] [-D<descriptfile>] [-E]\n", name);
  GMT_Message (API, GMT_TIME_NONE, "\t[-Fe|s|t|l|p|w] [-Gf|n[-|<fill>] [-I<icon>] [-K] [-L<name1>,<name2>,...]\n");
  GMT_Message (API, GMT_TIME_NONE, "\t[-N<col>|t|<template>|<name>] [-O] [-Q[a|i]<az>] [-Qs<scale>[unit]] [-Re|<w>/<e>/<s>/n>] [-Sc|n<scale>]\n");
  GMT_Message (API, GMT_TIME_NONE, "\t[-T<title>[/<foldername>] [%s] [-W[<pen>][<attr>]] [-Z<opts>] [%s]\n", GMT_V_OPT, GMT_a_OPT);