Cleanup some *.rst_ files

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 <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 <tbl-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_
+:doc:`clear`,
+:doc:`docs`,
+:doc:`end`,
+:doc:`figure`,
+:doc:`inset`,
+:doc:`subplot`,
+:doc:`gmt`

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_
+:doc:`begin`,
+:doc:`docs`,
+:doc:`end`,
+:doc:`figure`,
+:doc:`inset`,
+:doc:`subplot`,
+:doc:`gmt`