diff --git a/doc/rst/source/begin.rst b/doc/rst/source/begin.rst index 92341a279ac8..a1b0df510fd8 100644 --- a/doc/rst/source/begin.rst +++ b/doc/rst/source/begin.rst @@ -1,5 +1,154 @@ -##### +.. index:: ! begin + +***** begin -##### +***** + +.. only:: not man + + Initiate a new GMT modern mode session + +Synopsis +-------- + +.. include:: common_SYN_OPTs.rst_ + +**gmt begin** [*prefix*] [*formats*] [*options*] +[ |SYN_OPT-V| ] + +|No-spaces| + +Description +----------- + +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 you want to create multiple illustrations within this +session or need more control over the conversion from the internal PostScript to the output format, +you will instead use :doc:`figure` for the figure(s) 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. +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 ` [**A**]. The only other available options control verbosity +and default parameter settings. + +Optional Arguments +------------------ + +.. _begin-prefix: + +*prefix* + Name-stem used to construct the single final figure name. The extension is appended + 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. + While not recommended, if your *prefix* has spaces in it then you must enclose your + prefix in single quotes. + +.. _begin-formats: + +*formats* + Give one or more comma-separated graphics extensions from the list of allowable graphics formats + :ref:`formats ` [pdf]. + +.. _begin-options: + +*options* + Sets one or more comma-separated options (and possibly arguments) that + can be passed to :doc:`psconvert` when preparing a session 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. + +.. _begin-V: + +.. |Add_-V| unicode:: 0x20 .. just an invisible code +.. include:: explain_-V.rst_ + +.. include:: explain_help_nopar.rst_ + +.. _tbl-formats: + + +--------+-----------------------------------------+ + | Format | Explanation | + +========+=========================================+ + | bmp | Microsoft Bit Map | + +--------+-----------------------------------------+ + | eps | Encapsulated PostScript | + +--------+-----------------------------------------+ + | jpg | Joint Photographic Experts Group Format | + +--------+-----------------------------------------+ + | pdf | Portable Document Format [Default] | + +--------+-----------------------------------------+ + | png | Portable Network Graphics (opaque) | + +--------+-----------------------------------------+ + | PNG | Portable Network Graphics (transparent) | + +--------+-----------------------------------------+ + | ppm | Portable Pixel Map | + +--------+-----------------------------------------+ + | ps | Plain PostScript | + +--------+-----------------------------------------+ + | tif | Tagged Image Format File | + +--------+-----------------------------------------+ + +Examples +-------- + +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 illustrations +are produced then we do not need to give any further arguments: + + :: + + gmt begin + +Should we give such a command and still produce a plot then it will automatically +be called gmtsession.pdf. + +To set up proceedings for a jpg figure with 0.5c white margin, we would run + + :: + + gmt begin 'My Figure4' pdf,png A+m1c + +.. include:: explain_postscript.rst_ + +Note on UNIX shells +------------------- + +Modern mode works by communicating across gmt modules via the shell script's (or terminal's) +process ID, which is the common parent process ID (PPID) for each module. This number is used to +create the unique session directories where gmt keeps its book-keeping records. However, inconsistencies +across various UNIX shells and other differences in their implementations may occasionally lead +to problems for gmt to properly determine the unique PPID. The most common situation is +related to a shell spawning sub-shells when you are linking two or more processes via UNIX pipes. +Each sub-shell will then have its own process ID and gmt modules started by the sub-shell will then +have that ID as PPID and it will differ from the one determined by gmt begin. +If you are using pipes in your modern mode script and you get strange errors about not finding gmt6.##### +then you can add this command to the top of your script to make the issue go away (in Bourne shell): + +export GMT_SESSION_NAME=$$ + +or in cshell: + +setenv GMT_SESSION_NAME $$ + +See Also +-------- -.. include:: begin.rst_ \ No newline at end of file +:doc:`clear`, +:doc:`docs`, +:doc:`end`, +:doc:`figure`, +:doc:`inset`, +:doc:`subplot`, +:doc:`gmt` diff --git a/doc/rst/source/begin.rst_ b/doc/rst/source/begin.rst_ deleted file mode 100644 index 509a574d887d..000000000000 --- a/doc/rst/source/begin.rst_ +++ /dev/null @@ -1,149 +0,0 @@ -.. index:: ! begin - -.. only:: not man - - Initiate a new GMT modern mode session - -Synopsis --------- - -.. include:: common_SYN_OPTs.rst_ - -**gmt begin** [*prefix*] [*formats*] [*options*] -[ |SYN_OPT-V| ] - -|No-spaces| - -Description ------------ - -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 you want to create multiple illustrations within this session, -you will instead use :doc:`figure` for the figure(s) 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. -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 ` [**A**]. The only other available options control verbosity -and default parameter settings. - -Optional Arguments ------------------- - -.. _begin-prefix: - -*prefix* - Name-stem used to construct the single final figure name. The extension is appended - 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. - While not recommended, if your *prefix* has spaces in it then you must enclose your - prefix in single or double quotes. - -.. _begin-formats: - -*formats* - Give one or more comma-separated graphics extensions from the list of allowable graphics formats - :ref:`formats ` (default is configurable via setting GMT_GRAPHICS_FORMAT [pdf]). - -.. _begin-options: - -*options* - Sets one or more comma-separated options (and possibly arguments) that - can be passed to :doc:`psconvert` when preparing a session 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. - -.. _begin-V: - -.. |Add_-V| unicode:: 0x20 .. just an invisible code -.. include:: explain_-V.rst_ - -.. include:: explain_help_nopar.rst_ - -.. _tbl-formats: - - +--------+-----------------------------------------+ - | Format | Explanation | - +========+=========================================+ - | bmp | Microsoft Bit Map | - +--------+-----------------------------------------+ - | eps | Encapsulated PostScript | - +--------+-----------------------------------------+ - | jpg | Joint Photographic Experts Group Format | - +--------+-----------------------------------------+ - | pdf | Portable Document Format [Default] | - +--------+-----------------------------------------+ - | png | Portable Network Graphics (opaque) | - +--------+-----------------------------------------+ - | PNG | Portable Network Graphics (transparent) | - +--------+-----------------------------------------+ - | ppm | Portable Pixel Map | - +--------+-----------------------------------------+ - | ps | Plain PostScript | - +--------+-----------------------------------------+ - | tif | Tagged Image Format File | - +--------+-----------------------------------------+ - -Examples --------- - -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 illustrations -are produced then we do not need to give any further arguments: - - :: - - gmt begin - -Should we give such a command and still produce a plot then it will automatically -be called gmtsession.pdf (assuming GMT_GRAPHICS_FORMAT is pdf). - -To set up proceedings for a jpg figure with 0.5c white margin, we would run - - :: - - gmt begin 'My Figure4' pdf,png A+m1c - -.. include:: explain_postscript.rst_ - -Note on UNIX shells -------------------- - -Modern mode works by communicating across gmt modules via the shell script's (or terminal's) -process ID, which is the common parent process ID (PPID) for each module. This number is used to -create the unique session directories where gmt keeps its book-keeping records. However, inconsistencies -across various UNIX shells and other differences in their implementations may occasionally lead -to problems for gmt to properly determine the unique PPID. The most common situation is -related to a shell spawning sub-shells when you are linking two or more processes via UNIX pipes. -Each sub-shell will then have its own process ID and gmt modules started by the sub-shell will then -have that ID as PPID and it will differ from the one determined by gmt begin. -If you are using pipes in your modern mode script and you get strange errors about not finding gmt6.##### -then you can add this command to the top of your script to make the issue go away (in Bourne shell): - - export GMT_SESSION_NAME=$$ - -or in cshell: - - setenv GMT_SESSION_NAME $$ - -See Also --------- - -:doc:`clear`, -:doc:`docs`, -:doc:`end`, -:doc:`figure`, -:doc:`inset`, -:doc:`subplot`, -:doc:`gmt` diff --git a/doc/rst/source/clear.rst b/doc/rst/source/clear.rst index 65917a51259a..b68da656bc21 100644 --- a/doc/rst/source/clear.rst +++ b/doc/rst/source/clear.rst @@ -1,5 +1,86 @@ -##### +.. index:: ! clear + +***** clear -##### +***** + +.. only:: not man + + Delete current defaults, or the cache, data or sessions directories + +Synopsis +-------- + +.. include:: common_SYN_OPTs.rst_ + +**gmt clear** [ **all** \| **cache** \| **defaults** \| **data** \| **sessions** ] +[ |SYN_OPT-V| ] + +|No-spaces| + +Description +----------- + +The clear command allows users to delete their entire user cache, data, or sessions +directories, and in modern mode their defaults settings (i.e., gmt.conf), or all of the above. + +Optional Arguments +------------------ + +.. _clear-all: + +**all** + Deletes all the items under the control of the individual targets. + +.. _clear-conf: + +**conf** + Delete the current defaults (gmt.conf) file used for the current modern session. + +.. _clear-cache: + +**cache** + Delete the user's cache directory and all of its contents. + +.. _clear-data: + +**data** + Delete the user's data download directory and all of its contents. + +.. _clear-sessions: + +**sessions** + Delete the user's sessions directory. + +.. _clear-V: + +.. |Add_-V| unicode:: 0x20 .. just an invisible code +.. include:: explain_-V.rst_ + +.. include:: explain_help_nopar.rst_ + +Examples +-------- + +To remove the current default settings in a modern mode session, use + + :: + + gmt clear defaults + +To completely wipe your GMT cache directory, try + + :: + + gmt clear cache + +See Also +-------- -.. include:: clear.rst_ \ No newline at end of file +:doc:`begin`, +:doc:`docs`, +:doc:`end`, +:doc:`figure`, +:doc:`inset`, +:doc:`subplot`, +:doc:`gmt` diff --git a/doc/rst/source/clear.rst_ b/doc/rst/source/clear.rst_ deleted file mode 100644 index cbbf4ea14250..000000000000 --- a/doc/rst/source/clear.rst_ +++ /dev/null @@ -1,82 +0,0 @@ -.. index:: ! clear - -.. only:: not man - - Delete current defaults, or the cache, data or sessions directories - -Synopsis --------- - -.. include:: common_SYN_OPTs.rst_ - -**gmt clear** [ **all** \| **cache** \| **defaults** \| **data** \| **sessions** ] -[ |SYN_OPT-V| ] - -|No-spaces| - -Description ------------ - -The clear command allows users to delete their entire user cache, data, or sessions -directories, and in modern mode their defaults settings (i.e., gmt.conf), or all of the above. - -Optional Arguments ------------------- - -.. _clear-all: - -**all** - Deletes all the items under the control of the individual targets. - -.. _clear-defaults: - -**defaults** - Delete the current defaults (gmt.conf) file used for the current modern session. - -.. _clear-cache: - -**cache** - Delete the user's cache directory and all of its contents. - -.. _clear-data: - -**data** - Delete the user's data download directory and all of its contents. - -.. _clear-sessions: - -**sessions** - Delete the user's sessions directory. - -.. _clear-V: - -.. |Add_-V| unicode:: 0x20 .. just an invisible code -.. include:: explain_-V.rst_ - -.. include:: explain_help_nopar.rst_ - -Examples --------- - -To remove the current default settings in a modern mode session, use - - :: - - gmt clear defaults - -To completely wipe your GMT cache directory, try - - :: - - gmt clear cache - -See Also --------- - -:doc:`begin`, -:doc:`docs`, -:doc:`end`, -:doc:`figure`, -:doc:`inset`, -:doc:`subplot`, -:doc:`gmt` diff --git a/doc/rst/source/docs.rst b/doc/rst/source/docs.rst index 8a171a41a7d3..6e04cb30a73a 100644 --- a/doc/rst/source/docs.rst +++ b/doc/rst/source/docs.rst @@ -1,5 +1,99 @@ -#### +.. index:: ! docs + +**** docs -#### +**** + +.. only:: not man + + Show the HTML documentation for selected module + +Synopsis +-------- + +.. include:: common_SYN_OPTs.rst_ + +**gmt docs** [ **-Q** ] [ |SYN_OPT-V| ] [ *module-name* [*-option*] ] + +|No-spaces| + +Description +----------- + +**docs** tells GMT to display the HTML version of a module's documentation using the default browser. +Besides the modules names, the special targets *cookbook*, *gallery*, *defaults*, *api* and *tutorial* +are also accepted. + +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 file open command will take place. This is useful + if you are working remotely on a server and do not wish to launch a GUI browser. + If used, **-Q** must be the first option to **docs**. + +.. _-V: + +.. |Add_-V| unicode:: 0x20 .. just an invisible code +.. include:: explain_-V.rst_ + +Optional Module Arguments +------------------------- + +*-option* + Where *-option* is the one-letter option of the module in question (e.g, **-R**). + We then display the *module* documentation positioned at that specific option. + +Examples +-------- + +To see the documentation of *grdimage* + + :: + + gmt docs grdimage + +To see the link to the documentation of *grdimage* + + :: + + gmt docs -Q grdimage + +To see the documentation of the **-B** option in *pscoast* + + :: + + gmt docs pscoast -B + +And do not be surprised to see that it says *coast* instead of *pscoast*. + +To examine the list of GMT defaults, try + + :: + + gmt docs defaults + +To see the Gallery + + :: + + gmt docs gallery + +To display the URL to the surface man page,.run + + :: + + gmt docs -Q surface + + +See Also +-------- -.. include:: docs.rst_ \ No newline at end of file +:doc:`begin`, +:doc:`clear`, +:doc:`end`, +:doc:`figure`, +:doc:`inset`, +:doc:`subplot`, +:doc:`gmt` diff --git a/doc/rst/source/docs.rst_ b/doc/rst/source/docs.rst_ deleted file mode 100644 index b7002b4bca11..000000000000 --- a/doc/rst/source/docs.rst_ +++ /dev/null @@ -1,89 +0,0 @@ -.. index:: ! docs - -.. only:: not man - - Show the HTML documentation for selected module - -Synopsis --------- - -.. include:: common_SYN_OPTs.rst_ - -**gmt docs** [ **-Q** ] [ |SYN_OPT-V| ] *module-name* [*-option*] - -|No-spaces| - -Description ------------ - -**docs** tells GMT to display the HTML version of a module's documentation using the default browser. -Besides the modules names, the special targets *cookbook*, *gallery*, *defaults*, *api* and *tutorial* -are also accepted. - -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 file open command will take place. This is useful - if you are working remotely on a server and do not wish to launch a GUI browser. - If used, **-Q** must be the first option to **docs**. - -.. _-V: - -.. |Add_-V| unicode:: 0x20 .. just an invisible code -.. include:: explain_-V.rst_ - -.. include:: explain_help_nopar.rst_ - -Optional Module Arguments -------------------------- - -*-option* - Where *-option* is the one-letter option of the module in question (e.g, **-R**). - We then display the *module* documentation positioned at that specific option. - -Examples --------- - -To see the documentation of *grdimage* - - :: - - gmt docs grdimage - -To see the link to the documentation of *grdimage* - - :: - - gmt docs -Q grdimage - -To see the documentation of the **-B** option in *pscoast* - - :: - - gmt docs pscoast -B - -To examine the list of GMT defaults, try - - :: - - gmt docs defaults - -To see the Gallery - - :: - - gmt docs gallery - - -See Also --------- - -:doc:`begin`, -:doc:`clear`, -:doc:`end`, -:doc:`figure`, -:doc:`inset`, -:doc:`subplot`, -:doc:`gmt` diff --git a/doc/rst/source/end.rst b/doc/rst/source/end.rst index a3677552e164..bb0264e22088 100644 --- a/doc/rst/source/end.rst +++ b/doc/rst/source/end.rst @@ -1,5 +1,60 @@ -### +.. index:: ! end + +*** end -### +*** + +.. only:: not man + + Terminate GMT modern mode session and produce optional graphics + +Synopsis +-------- + +.. include:: common_SYN_OPTs.rst_ + +**gmt end** +[ **show** ] +[ |SYN_OPT-V| ] + +|No-spaces| + +Description +----------- + +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 +------------------ + +**show** + Open all graphics produced by the session in the default viewer via call(s) to gmt :doc:`docs`. + +.. _end-V: + +.. |Add_-V| unicode:: 0x20 .. just an invisible code +.. include:: explain_-V.rst_ + +.. include:: explain_help_nopar.rst_ + +Examples +-------- + +To close the current modern session and finalize any plots requested, we use + + :: + + gmt end + +See Also +-------- -.. include:: end.rst_ \ No newline at end of file +:doc:`begin`, +:doc:`clear`, +:doc:`docs`, +:doc:`figure`, +:doc:`inset`, +:doc:`subplot`, +:doc:`gmt` diff --git a/doc/rst/source/end.rst_ b/doc/rst/source/end.rst_ deleted file mode 100644 index ad31dda314db..000000000000 --- a/doc/rst/source/end.rst_ +++ /dev/null @@ -1,56 +0,0 @@ -.. index:: ! end - -.. only:: not man - - Terminate GMT modern mode session and produce optional graphics - -Synopsis --------- - -.. include:: common_SYN_OPTs.rst_ - -**gmt end** -[ **show** ] -[ |SYN_OPT-V| ] - -|No-spaces| - -Description ------------ - -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 ------------------- - -**show** - Open all graphics produced by the session in the default viewer. - -.. _end-V: - -.. |Add_-V| unicode:: 0x20 .. just an invisible code -.. include:: explain_-V.rst_ - -.. include:: explain_help_nopar.rst_ - -Examples --------- - -To close the current modern session and finalize any plots requested, we use - - :: - - gmt end - -See Also --------- - -:doc:`begin`, -:doc:`clear`, -:doc:`docs`, -:doc:`figure`, -:doc:`inset`, -:doc:`subplot`, -:doc:`gmt` diff --git a/doc/rst/source/figure.rst b/doc/rst/source/figure.rst index bb5404035d57..524834a8161a 100644 --- a/doc/rst/source/figure.rst +++ b/doc/rst/source/figure.rst @@ -1,5 +1,105 @@ -###### +.. index:: ! figure + +****** figure -###### +****** + +.. only:: not man + + Set attributes for the current modern mode session figure + +Synopsis +-------- + +.. include:: common_SYN_OPTs.rst_ + +**gmt figure** *prefix* [*formats*] [*options*] +[ |SYN_OPT-V| ] + +|No-spaces| + +Description +----------- + +A GMT modern session can make any number of illustrations (including none). +In situations when multiple illustrations will be made during a single session or when you need +specific control over the conversion from PostScript to the output format, +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 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 ` [**A**]. The only other available options control verbosity +and default parameter settings. Each figure maintains its own history and settings, so +memory of region and projection settings only apply on a per figure basis. + +Required Arguments +------------------ + +*prefix* + Name stem used to construct the figure name. The extension(s) are appended + automatically from your *formats* selection(s). + While not recommended, if your *prefix* has spaces in it then you must enclose your + prefix in single quotes. + +Optional Arguments +------------------ + +.. _figure-formats: + +*formats* + Give one or more comma-separated graphics extensions from the list of allowable graphics + :ref:`formats ` [pdf]. + +.. _figure-options: + +*options* + 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. + +.. _figure-V: + +.. |Add_-V| unicode:: 0x20 .. just an invisible code +.. include:: explain_-V.rst_ + +.. include:: explain_help_nopar.rst_ + +.. include:: explain_postscript.rst_ + +Examples +-------- + +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 + + :: + + gmt figure Regional pdf,eps + +To start a new figure GlobalMap that should be returned as a JPEG file with a 1 cm padding +around the image, try + + :: + + gmt figure GlobalMap jpg A1c + +If the same figure were to be called Global Map.jpg you would need quotes: + + :: + + gmt figure 'Global Map' jpg A1c + +See Also +-------- -.. include:: figure.rst_ \ No newline at end of file +:doc:`begin`, +:doc:`clear`, +:doc:`docs`, +:doc:`end`, +:doc:`subplot`, +:doc:`gmt` diff --git a/doc/rst/source/figure.rst_ b/doc/rst/source/figure.rst_ deleted file mode 100644 index 831b249e171b..000000000000 --- a/doc/rst/source/figure.rst_ +++ /dev/null @@ -1,126 +0,0 @@ -.. index:: ! figure - -.. only:: not man - - Set attributes for the current modern mode session figure - -Synopsis --------- - -.. include:: common_SYN_OPTs.rst_ - -**gmt figure** *prefix* [*formats*] [*options*] -[ |SYN_OPT-V| ] - -|No-spaces| - -Description ------------ - -A GMT modern session can make any number of illustrations (including none). -In situations when multiple 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 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 ` [**A**]. The only other available options control verbosity -and default parameter settings. Each figure maintains its own history and settings, so -memory of region and projection settings only apply on a per figure basis. - -Required Arguments ------------------- - -*prefix* - Name stem used to construct the figure name. The extension(s) are appended - automatically from your *formats* selection(s). - While not recommended, if your *prefix* has spaces in it then you must enclose your - prefix in single quotes. - -Optional Arguments ------------------- - -.. _figure-formats: - -*formats* - Give one or more comma-separated graphics extensions from the list of allowable graphics - :ref:`formats ` (default is configurable via setting GMT_GRAPHICS_FORMAT [pdf]). - -.. _figure-options: - -*options* - 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. - -.. _-V: - -.. |Add_-V| unicode:: 0x20 .. just an invisible code -.. include:: explain_-V.rst_ - -.. include:: explain_help_nopar.rst_ - -.. include:: explain_postscript.rst_ - -Examples --------- - -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: - - gmt begin - gmt figure Regional pdf,eps - gmt ... - gmt end show - -To start a new figure GlobalMap that should be returned as a JPEG file with a 1 cm padding -around the image, try: - - gmt begin - gmt figure GlobalMap jpg A1c - gmt ... - gmt end show - -If the same figure were to be called Global Map.jpg you would need quotes:: - - gmt begin - gmt figure 'Global Map' jpg A1c - gmt ... - gmt end show - -To make two figures in one session and go back and forth between different figures:: - - gmt begin - - # Activate figure Fig1 - gmt figure Fig1 pdf - gmt ... - - # Activate figure Fig1 - gmt figure Fig2 pdf - gmt ... - - # Go back to figure Fig1 - gmt figure Fig1 - gmt ... - - # Go back to figure Fig2 - gmt figure Fig2 - gmt ... - - gmt end show - - -See Also --------- - -:doc:`begin`, -:doc:`clear`, -:doc:`docs`, -:doc:`end`, -:doc:`subplot`, -:doc:`gmt` diff --git a/doc/rst/source/inset.rst b/doc/rst/source/inset.rst index 99fcc7a4488d..506cb5f40571 100644 --- a/doc/rst/source/inset.rst +++ b/doc/rst/source/inset.rst @@ -1,5 +1,148 @@ -##### +.. index:: ! inset + +***** inset -##### +***** + +.. only:: not man + + Manage figure inset setup and completion + +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) +--------------------- + +.. include:: common_SYN_OPTs.rst_ + +**gmt inset begin** +|-D|\ *inset-box* +[ |-F|\ *box* ] +[ |-M|\ *margins* ] +[ |SYN_OPT-V| ] +[ |SYN_OPT--| ] + +|No-spaces| + +Description +----------- + +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. The user may select any plot region +and projection once plotting in the inset, but if the first command uses +? as scale or width then we adjust the scale or width to fill the inset as best +as possible, given the inset size and margins. + + +Required Arguments +------------------ + +.. _-D: + +**-D**\ [*unit*]\ *xmin/xmax/ymin/ymax*\ [**r**] \| **-D**\ [**g**\ \|\ **j**\ \|\ **J**\ \|\ **n**\ \|\ **x**]\ *refpoint*\ **+w**\ *width*\ [/*height*][**+j**\ *justify*][**+o**\ *dx*\ [/*dy*]] + Define the map inset box on the map. Specify the box in one of three ways: + (a) Give *west/east/south/north* of geographic rectangle bounded by parallels + and meridians; append **r** if the coordinates instead are the lower left and + upper right corners of the desired rectangle. (b) Give **u**\ *xmin/xmax/ymin/ymax* + of bounding rectangle in projected coordinates (here, **u** is the coordinate unit). + (c) Give the reference point on the map for the inset using one of four coordinate systems: + (1) Use **-Dg** for map (user) coordinates, (2) use **-Dj** or **-DJ** for setting *refpoint* via + a 2-char justification code that refers to the (invisible) map domain rectangle, + (3) use **-Dn** for normalized (0-1) coordinates, or (4) use **-Dx** for plot coordinates + (inches, cm, etc.). + Append **+w**\ *width*\ [/*height*] of bounding rectangle or box in plot coordinates (inches, cm, etc.). + By default, the anchor point on the scale is assumed to be the bottom left corner (BL), but this + can be changed by appending **+j** followed by a 2-char justification code *justify* (see :doc:`text`). + Note: If **-Dj** is used then *justify* defaults to the same as *refpoint*, + if **-DJ** is used then *justify* defaults to the mirror opposite of *refpoint*. + Add **+o** to offset the inset fig by *dx*/*dy* away from the *refpoint* point in + the direction implied by *justify* (or the direction implied by **-Dj** or **-DJ**). + Specify inset box attributes via the **-F** option [outline only]. + +Optional Arguments +------------------ + +.. _inset_begin-F: + +**-F**\ [\ **+c**\ *clearances*][\ **+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]][\ **+p**\ [*pen*]][\ **+r**\ [*radius*\ ]][\ **+s**\ [[*dx*/*dy*/][*shade*\ ]]] + Without further options, draws a rectangular border around the map inset using + :ref:`MAP_FRAME_PEN `; specify a different pen with **+p**\ *pen*. + Add **+g**\ *fill* to fill the logo box [no fill]. + Append **+c**\ *clearance* where *clearance* is either *gap*, *xgap*\ /\ *ygap*, + or *lgap*\ /\ *rgap*\ /\ *bgap*\ /\ *tgap* where these items are uniform, separate in + x- and y-direction, or individual side spacings between logo and border. + Append **+i** to draw a secondary, inner border as well. We use a uniform + *gap* between borders of 2\ **p** and the :ref:`MAP_DEFAULT_PEN ` + unless other values are specified. Append **+r** to draw rounded + rectangular borders instead, with a 6\ **p** corner radius. You can + override this radius by appending another value. Finally, append + **+s** to draw an offset background shaded region. Here, *dx*/*dy* + indicates the shift relative to the foreground frame + [4\ **p**/-4\ **p**] and *shade* sets the fill style to use for shading [gray50]. + +.. _inset_begin-M: + +**-M**\ *margins* + This is clearance that is added around the inside of the inset. Plotting will take place + within the inner region only. + 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]. + +.. _inset_begin-V: + +.. |Add_-V| unicode:: 0x20 .. just an invisible code +.. include:: explain_-V.rst_ + +.. include:: explain_help_nopar.rst_ + +Synopsis (end mode) +------------------- + +**gmt inset end** [ |SYN_OPT-V| ] + +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 +------------------ + +.. _inset_end-V: + +.. include:: explain_-V.rst_ +.. include:: explain_help_nopar.rst_ + + +Examples +-------- + +To make a simple basemap plot called inset.pdf that demonstrates the inset module, try + + :: + + gmt begin inset pdf + gmt basemap -R0/40/20/60 -JM6.5i -Bafg -B+glightgreen + gmt inset begin -DjTR+w2.5i+o0.2i -F+gpink+p0.5p -M0.25i + gmt basemap -Rg -JA20/20/2i -Bafg + echo INSET | gmt text -F+f18p+cTR -Dj-0.15i + gmt inset end + echo MAP | gmt text -F+f18p+cBL -Dj0.2i + gmt end + + +See Also +-------- -.. include:: inset.rst_ \ No newline at end of file +:doc:`begin`, +:doc:`clear`, +:doc:`docs`, +:doc:`end`, +:doc:`figure`, +:doc:`gmt`, +:doc:`inset` diff --git a/doc/rst/source/inset.rst_ b/doc/rst/source/inset.rst_ deleted file mode 100644 index 740030b09579..000000000000 --- a/doc/rst/source/inset.rst_ +++ /dev/null @@ -1,142 +0,0 @@ -.. index:: ! inset - -.. only:: not man - - Manage figure inset setup and completion - -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) ---------------------- - -.. include:: common_SYN_OPTs.rst_ - -**gmt inset begin** -|-D|\ *inset-box* -[ |-F|\ *box* ] -[ |-M|\ *margins* ] -[ |SYN_OPT-V| ] -[ |SYN_OPT--| ] - -|No-spaces| - -Description ------------ - -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. The user may select any plot region -and projection once plotting in the inset, but if the first command uses -? as scale or width then we adjust the scale or width to fill the inset as best -as possible, given the inset size and margins (if selected). - - -Required Arguments ------------------- - -.. _-D: - -**-D**\ *xmin/xmax/ymin/ymax*\ [**+r**][**+u**\ *unit*]] \| **-D**\ [**g**\ \|\ **j**\ \|\ **J**\ \|\ **n**\ \|\ **x**]\ *refpoint*\ **+w**\ *width*\ [/*height*][**+j**\ *justify*][**+o**\ *dx*\ [/*dy*]] - Define the map inset rectangle on the map. Specify the rectangle in one of three ways: - (a) Give *west/east/south/north* of geographic rectangle bounded by parallels - and meridians; append **+r** if the coordinates instead are the lower left and - upper right corners of the desired rectangle. (b) Give *xmin/xmax/ymin/ymax* - of bounding rectangle in projected coordinates and optionally append **+u**\ *unit* [Default coordinate unit is meter (e)]. - (c) Give the reference point on the map for the inset using one of four coordinate systems: - (1) Use **-Dg** for map (user) coordinates, (2) use **-Dj** or **-DJ** for setting *refpoint* via - a 2-char justification code that refers to the (invisible) map domain rectangle, - (3) use **-Dn** for normalized (0-1) coordinates, or (4) use **-Dx** for plot coordinates - (inches, cm, etc.). - Append **+w**\ *width*\ [/*height*] of bounding rectangle or box in plot coordinates (inches, cm, etc.). - By default, the anchor point on the scale is assumed to be the bottom left corner (BL), but this - can be changed by appending **+j** followed by a 2-char justification code *justify* (see :doc:`text`). - Note: If **-Dj** is used then *justify* defaults to the same as *refpoint*, - if **-DJ** is used then *justify* defaults to the mirror opposite of *refpoint*. - Add **+o** to offset the inset fig by *dx*/*dy* away from the *refpoint* point in - the direction implied by *justify* (or the direction implied by **-Dj** or **-DJ**). - Specify inset box attributes via the **-F** option [outline only]. - -Optional Arguments ------------------- - -.. _inset_begin-F: - -**-F**\ [\ **+c**\ *clearances*][\ **+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]][\ **+p**\ [*pen*]][\ **+r**\ [*radius*\ ]][\ **+s**\ [[*dx*/*dy*/][*shade*\ ]]] - Without further options, draws a rectangular border around the map inset using - :ref:`MAP_FRAME_PEN `; specify a different pen with **+p**\ *pen*. - Add **+g**\ *fill* to fill the logo box [no fill]. - Append **+c**\ *clearance* where *clearance* is either *gap*, *xgap*\ /\ *ygap*, - or *lgap*\ /\ *rgap*\ /\ *bgap*\ /\ *tgap* where these items are uniform, separate in - x- and y-direction, or individual side spacings between logo and border. - Append **+i** to draw a secondary, inner border as well. We use a uniform - *gap* between borders of 2\ **p** and the :ref:`MAP_DEFAULT_PEN ` - unless other values are specified. Append **+r** to draw rounded - rectangular borders instead, with a 6\ **p** corner radius. You can - override this radius by appending another value. Finally, append - **+s** to draw an offset background shaded region. Here, *dx*/*dy* - indicates the shift relative to the foreground frame - [4\ **p**/-4\ **p**] and *shade* sets the fill style to use for shading [gray50]. - -.. _inset_begin-M: - -**-M**\ *margins* - This is clearance that is added around the inside of the inset. Plotting will take place - within the inner region only. 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) [no margins]. - -.. _inset_begin-V: - -.. |Add_-V| unicode:: 0x20 .. just an invisible code -.. include:: explain_-V.rst_ - -.. include:: explain_help_nopar.rst_ - -Synopsis (end mode) -------------------- - -**gmt inset end** [ |SYN_OPT-V| ] - -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 ------------------- - -.. _inset_end-V: - -.. include:: explain_-V.rst_ -.. include:: explain_help_nopar.rst_ - - -Examples --------- - -To make a simple basemap plot called inset.pdf that demonstrates the inset module, try - - :: - - gmt begin inset pdf - gmt basemap -R0/40/20/60 -JM6.5i -Bafg -B+glightgreen - gmt inset begin -DjTR+w2.5i+o0.2i -F+gpink+p0.5p -M0.25i - gmt basemap -Rg -JA20/20/2i -Bafg - gmt text -F+f18p+cTR+tINSET -Dj-0.15i -N - gmt inset end - gmt text -F+f18p+cBL+tMAP -Dj0.2i - gmt end - -See Also --------- - -:doc:`begin`, -:doc:`clear`, -:doc:`docs`, -:doc:`end`, -:doc:`figure`, -:doc:`gmt`, -:doc:`inset` diff --git a/doc/rst/source/subplot.rst b/doc/rst/source/subplot.rst index 35039d8079bb..69152232f3c3 100644 --- a/doc/rst/source/subplot.rst +++ b/doc/rst/source/subplot.rst @@ -1,5 +1,261 @@ -####### +.. index:: ! subplot + +******* subplot -####### +******* + +.. only:: not man + + Manage modern mode figure subplot configuration and selection + +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** +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) +--------------------- + +.. include:: common_SYN_OPTs.rst_ + +**gmt subplot begin** *nrows*\ **x**\ *ncols* +**-F**\ [**f**\ \|\ **s**\ ]\ *width*\ /*height*\ [**+f**\ *wfracs*\ /*hfracs*\ ] +[ **-A**\ *autolabel* ] +[ **-C**\ *side*\ /*clearance*\ [**u**] +[ |SYN_OPT-B| ] +[ |-J|\ *parameters* ] +[ **-M**\ *margins* ] +[ |SYN_OPT-R| ] +[ **-S**\ *layout* ] +[ **-T**\ *title* ] +[ |SYN_OPT-V| ] +[ |SYN_OPT--| ] + +|No-spaces| + +Description +----------- + +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 +------------------ + +*nrows*\ **x**\ *ncols* + Specifies the number of rows and columns of subplots. Each row will have + the same number of subplots. To construct figures with different number of + subplots per row you will need to stack separate subplots. Note: You are not + required to place a plot in each panel. + +.. _subplot_begin-F: + +**-F**\ [**f**\ \|\ **s**\ ]\ *width(s)*\ /*height(s)*\ \ [**+f**\ *wfracs*\ /*hfracs*\ ] + Specify the dimensions of the figure. There are two different ways to do this: + (**f**) Specify overall figure dimensions or (**s**) specify the dimensions of + a single panel. + +**-Ff** + 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 + fractions, a slash, and then the list of height fractions. For example **-Ff**\ 10c/10c\ **+f**\ 3,1/1,2 will make the first column + three times as wide as the second, while the second row will be twice as tall as the first row. + A single number means constant widths (or heights) [Default]. + +**-Fs** + 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 comma-separated list of widths, + a slash, and then the comma-separated list of heights. A single number means constant widths (or heights) [Default]. + For example **-Fs**\ 5c,8c/8c will make the first column 5 cm wide and the second column 8 cm wide, with + all having a constant height of 8 cm. The number of values must either be one (constant across the rows or columns) + or exactly match the number of rows (or columns). For geographic maps, the height of each panel depends on + your map region and projection. There are two options: (1) Specify both **-R** and **-J** and we use these + to compute the height of each subplot. All subplot must share the same region and projection and you specify + a zero *height*, or (2) you can select *height* based on trial and error to suit your plot layout. + +Optional Arguments +------------------ + +.. _subplot_begin-A: + +**-A**\ *autolabel* + Specify automatic tagging of each subplot. Append either a number or letter [a]. + This sets the tag of the first, top-left subplot and others follow sequentially. + Surround the number or letter by parentheses on any side if these should be typeset + as part of the tag (Note: In UNIX shells you may need to escape these parentheses.) + Use **+j**\ \|\ **J**\ *refpoint* to specify where the tag should be placed in the subplot [TL]. + 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 ` 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 `]. + Append **+p**\ *pen* to draw the outline of the tag's text box using selected *pen* [no outline]. + Append **+r** to typeset your tag numbers using lowercase Roman numerals; + use **+R** for uppercase Roman numerals [Arabic numerals]. + Append **+v** to increase tag numbers vertically down columns [horizontally across rows]. + +.. include:: explain_-B.rst_ + +.. _subplot_set-C1: + +**-C**\ *side*\ /*clearance*\ [**u**\ ] + 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** directive apply + to all panels, while settings under **set** only apply to the selected panel. Note: Common options **-X** + and **-Y** are not available during subplots; use **-C** instead. + +.. _-J: + +.. |Add_-J| unicode:: 0x20 .. just an invisible code +.. include:: explain_-J.rst_ + +.. _subplot_begin-M: + +**-M**\ *margins* + 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]. + +.. _-R: + +.. |Add_-R| replace:: This is useful when all subplots share a common plot domain. +.. include:: explain_-R.rst_ + +.. _subplot_begin-S: + +**-S**\ *layout* + Set subplot layout for shared axes. May be set separately for rows (**-SR**) and columns (**-SC**). + 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. + 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. + 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 not used you may have to set **-C** to secure + extra space for long horizontal annotations. + +.. _subplot_begin-T: + +**-T**\ *heading* + While individual subplots can have titles (see **-S** or **-B**), the entire figure may also have a + overarching *heading* [no heading]. Font is determined by setting :ref:`FONT_HEADING `. + +.. _subplot_begin-V: + +.. |Add_-V| unicode:: 0x20 .. just an invisible code +.. include:: explain_-V.rst_ + +.. include:: explain_help.rst_ + +Synopsis (set mode) +------------------- + +**gmt subplot set** [ *row,col*\ \|\ *index* ] [ **-A**\ *fixedlabel*] [ **-C**\ *side*\ /*clearance*\ [**u**\ ] ] [ |SYN_OPT-V| ] + +Before you start plotting you must first select the active subplot panel. +Note: Any **-J** option passed when plotting subplots must give ? as scale or width +since the dimensions of the map are completely determined by the subplot size and your region. +Specifying map width will result in an error. For Cartesian plots: If you want the scale +to apply *equally* to both dimensions then you must specify **-Jx** [The default **-JX** will +fill the subplot by using unequal scales]. + +Optional Arguments +------------------ + +*row,col* + Sets the current subplot until further notice. Note: First *row* or *col is 0, not 1. If not given we go to the next panel by order + specified via **-A**. As an alternative, you may bypass the **set** mode and + instead supply the common option **-c**\ [*row,col*] to the first plot command you issue in that subplot. + GMT maintains information about the current figure and subplot. Also, you may give the one-dimensional + *index* instead which starts at 0 and follows the row or column order set via **-A**. + +.. _subplot_set-A: + +**-A**\ *fixedlabel* + Overrides the automatic labeling with the given string. No modifiers are allowed. + Placement, justification, etc. are all inherited from how **-A** was specified by the + initial **subplot begin** command. + +.. _subplot_set-C2: + +**-C**\ *side*\ /*clearance*\ [**u**\ ] + 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. This setting overrides the common + clearances set by **-C** during **subplot begin**. + +.. _subplot_set-V: + +.. include:: explain_-V.rst_ + +.. include:: explain_help.rst_ + +Any number of plotting command can now take place and all output will be directed to the +selected subplot panel. There are a few other rules that need to be followed: +(1) The subplot machinery expects the first plotting command in a new subplot window +to take care of plotting the base frame. The particulars of this frame may have been +specified by the **-S** option in **subplot begin**. In either case, should you need to set or override +frame and axis parameters then you must specify these **-B** options with this first plot +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 +dimensions of the last plot to that of the entire subplot. This allows **-X** and **-Y** to +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 +------------------ + +.. _subplot_end-V: + +.. include:: explain_-V.rst_ +.. include:: explain_help.rst_ + + +Examples +-------- + +To make a minimalistic 2x2 basemap layout called panels.pdf, try + + :: + + gmt begin panels pdf + gmt subplot begin 2x2 -Fs8c -M5p -A -SCb -SRl -Bwstr + gmt basemap -R0/80/0/10 + gmt basemap -c + gmt basemap -c + gmt basemap -c + gmt subplot end + gmt end + + +See Also +-------- -.. include:: subplot.rst_ \ No newline at end of file +:doc:`begin`, +:doc:`clear`, +:doc:`docs`, +:doc:`end`, +:doc:`figure`, +:doc:`inset`, +:doc:`gmt` diff --git a/doc/rst/source/subplot.rst_ b/doc/rst/source/subplot.rst_ deleted file mode 100644 index 82fedca40ac8..000000000000 --- a/doc/rst/source/subplot.rst_ +++ /dev/null @@ -1,266 +0,0 @@ -.. index:: ! subplot - -.. only:: not man - - Manage modern mode figure subplot configuration and selection - -The **subplot** module is used to split the current figure into a rectangular layout of subplots -that each may contain a single self-contained figure. A subplot setup is started with the **begin** -directive that defines the layout of the subplots, while positioning to a particular subplot for -plotting is done via the **set** directive. The subplot process is completed via the **end** directive. - -Synopsis (begin mode) ---------------------- - -.. include:: common_SYN_OPTs.rst_ - -**gmt subplot begin** *nrows*\ **x**\ *ncols* -**-F**\ [**f**\ \|\ **s**\ ]\ *width*\ /*height*\ [**+f**\ *wfracs*\ /*hfracs*\ ][**+c**\ *dx/dy*\ ][**+g**\ *fill*\ ][**+p**\ *pen*\ ][**+w**\ *pen*\ ] -[ **-A**\ *autolabel* ] -[ **-C**\ [*side*]\ /*clearance*\ [**u**]] -[ |SYN_OPT-B| ] -[ |-J|\ *parameters* ] -[ **-M**\ *margins* ] -[ |SYN_OPT-R| ] -[ **-S**\ *layout* ] -[ **-T**\ *title* ] -[ |SYN_OPT-V| ] -[ |SYN_OPT--| ] - -|No-spaces| - -Description ------------ - -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 subplots. - -Required Arguments ------------------- - -*nrows*\ **x**\ *ncols* - Specifies the number of rows and columns of subplots. Each row will have - the same number of subplots. - Note: You are not required to place a plot in each subplot. - -.. _subplot_begin-F: - -**-F**\ [**f**\ \|\ **s**\ ]\ *width(s)*\ /*height(s)*\ \ [**+f**\ *wfracs*\ /*hfracs*\ ][**+c**\ *dx/dy*\ ][**+g**\ *fill*\ ][**+p**\ *pen*\ ] - Specify the dimensions of the figure. There are two different ways to do this: - (**f**) Specify overall figure dimensions or (**s**) specify the dimensions of - a single subplot. - -**-Ff** - 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 subplots. - As for other figures, 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 - fractions, a slash, and then the list of height fractions. For example **-Ff**\ 10c/10c\ **+f**\ 3,1/1,2 will make the first column - three times as wide as the second, while the second row will be twice as tall as the first row. - A single number means constant widths (or heights) [Default]. - -**-Fs** - 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 subplots. - As for other figures, 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 comma-separated list of widths, - a slash, and then the comma-separated list of heights. A single number means constant widths (or heights) [Default]. - For example **-Fs**\ 5c,8c/8c will make the first column 5 cm wide and the second column 8 cm wide, with - all having a constant height of 8 cm. The number of values must either be one (constant across the rows or columns) - or exactly match the number of rows (or columns). For geographic maps, the height of each subplot depends on - your map region and projection. There are two options: (1) Specify both **-R** and **-J** and we use these - to compute the height of each subplot. All subplots must share the same region and projection and you specify - a zero *height*, or (2) you can select *height* based on trial and error to suit your plot layout. - - Optionally, you may draw or paint the figure rectangle behind the subplots, and even expand it via **+c**. This - is most useful if you supply **-B+n** to subplot begin, meaning no ticks or annotations will take place in the - subplots. - -Optional Arguments ------------------- - -.. _subplot_begin-A: - -**-A**\ *autolabel* - Specify automatic tagging of each subplot. Append either a number or letter [a]. - This sets the tag of the first, top-left subplot and others follow sequentially. - Surround the number or letter by parentheses on any side if these should be typeset - as part of the tag (Note: In UNIX shells you may need to escape these parentheses.) - Use **+j**\ \|\ **J**\ *refpoint* to specify where the tag should be placed in the subplot [TL]. - 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** [3p/3p, i.e., 15% of the :ref:`FONT_TAG size ` 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 [4p/4p, i.e., 20% of the :ref:`FONT_TAG size `]. - Append **+p**\ *pen* to draw the outline of the tag's text box using selected *pen* [no outline]. - Append **+r** to typeset your tag numbers using lowercase Roman numerals; - use **+R** for uppercase Roman numerals [Arabic numerals]. - Append **+v** to increase tag numbers vertically down columns [horizontally across rows]. - -.. include:: explain_-B.rst_ - -.. _subplot_set-C1: - -**-C**\ [*side*]\ /*clearance*\ [**u**\ ] - 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**, or **x** for both **w** and **e** - or **y** for both **s** and **n**. No *side* means all sides. 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** directive apply - to all subplots, while settings under **set** only apply to the selected (active) subplot. Note: Common options **-X** - and **-Y** are not available during subplots; use **-C** instead. - -.. _-J: - -.. |Add_-J| unicode:: 0x20 .. just an invisible code -.. include:: explain_-J.rst_ - -.. _subplot_begin-M: - -**-M**\ *margins* - This is margin space that is added *between* neighboring subplots (i.e., the interior margins) *in addition* - to the automatic space added for tick marks, annotations, and labels. The margins can be specified as - a single value (for same margin on all sides), a pair of values separated by slashes - (for setting separate horizontal and vertical margins), or the full set of four slash-separated margins - (for setting separate left, right, bottom, and top margins). The actual gap created is always a sum of - the margins for the two opposing sides (e.g., east plus west or south plus north margins) [Default is - half the primary annotation font size, giving the full annotation font size as the default gap]. - -.. _-R: - -.. |Add_-R| replace:: This is useful when all subplots share a common plot domain. -.. include:: explain_-R.rst_ - -.. _subplot_begin-S: - -**-S**\ *layout* - Set subplot layout for shared axes. May be set separately for rows (**-SR**) and columns (**-SC**). - 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. - 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 subplot's own **-B** setting. - 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 not used you may have to set **-C** to secure - extra space for long horizontal annotations. - Append **+w** to draw horizontal and vertical lines between interior panels using selected pen [no lines]. - - -.. _subplot_begin-T: - -**-T**\ *heading* - While individual subplots can have titles (see **-S** or **-B**), the entire figure may also have a - overarching *heading* [no heading]. Font is determined by setting :ref:`FONT_HEADING `. - -.. _subplot_begin-V: - -.. |Add_-V| unicode:: 0x20 .. just an invisible code -.. include:: explain_-V.rst_ - -.. include:: explain_help.rst_ - -Synopsis (set mode) -------------------- - -**gmt subplot set** [ *row,col*\ \|\ *index* ] [ **-A**\ *fixedlabel*] [ **-C**\ *side*\ /*clearance*\ [**u**\ ] ] [ |SYN_OPT-V| ] - -Before you start plotting you must first select the active subplot. -Note: If any **-J** option is passed with **?** as scale or width when plotting subplots, -then the dimensions of the map are automatically determined by the subplot size and your region. -For Cartesian plots: If you want the scale to apply *equally* to both dimensions -then you must specify **-Jx** [The default **-JX** will fill the subplot by using unequal scales]. - -Optional Arguments ------------------- - -*row,col* - Sets the current subplot until further notice. Note: First *row* or *col is 0, not 1. If not given we go to the next subplot by order - specified via **-A**. As an alternative, you may bypass the **set** mode and - instead supply the common option **-c**\ [*row,col*] to the first plot command you issue in that subplot. - GMT maintains information about the current figure and subplot. Also, you may give the one-dimensional - *index* instead which starts at 0 and follows the row or column order set via **-A**. - -.. _subplot_set-A: - -**-A**\ *fixedlabel* - Overrides the automatic labeling with the given string. No modifiers are allowed. - Placement, justification, etc. are all inherited from how **-A** was specified by the - initial **subplot begin** command. - -.. _subplot_set-C2: - -**-C**\ *side*\ /*clearance*\ [**u**\ ] - 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. This setting overrides the common - clearances set by **-C** during **subplot begin**. - -.. _subplot_set-V: - -.. include:: explain_-V.rst_ - -Any number of plotting command can now take place and all output will be directed to the -selected subplot. There are a few other rules that need to be followed: -(1) The subplot machinery expects the first plotting command in a new subplot window -to take care of plotting the base frame. The particulars of this frame may have been -specified by the **-S** option in **subplot begin**. In either case, should you need to set or override -frame and axis parameters then you must specify these **-B** options with this first plot -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 -gmt.history to reflect the dimensions and linear projection required to draw the entire figure -outline. This allows subsequent commands, such as colorbar, to use **-DJ** to place bars with -reference to the complete figure dimensions. We also reset -the current plot location to where it was prior to the subplot. - -Optional Arguments ------------------- - -.. _subplot_end-V: - -.. include:: explain_-V.rst_ - -Examples --------- - -To make a minimalistic 2x2 basemap layout called panels.pdf, try - - :: - - gmt begin panels pdf - gmt subplot begin 2x2 -Fs8c -M5p -A -SCb -SRl -Bwstr - gmt subplot set - gmt basemap -R0/80/0/10 - gmt subplot set - gmt basemap - gmt subplot set - gmt basemap - gmt subplot set - gmt basemap - gmt subplot end - gmt end show - - -See Also --------- - -:doc:`begin`, -:doc:`clear`, -:doc:`docs`, -:doc:`end`, -:doc:`figure`, -:doc:`inset`, -:doc:`gmt`