.. index:: ! begin

.. only:: not man

    Initiate a new GMT modern mode session

Synopsis
--------

.. include:: common_SYN_OPTs.rst_

**gmt begin** [*prefix*] [*formats*]
[ |SYN_OPT-V| ]
[ |SYN_OPT--| ]

|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.

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.

.. _begin-formats:

*formats*
    Give one or more comma-separated graphics extensions from the list of allowable graphics formats
    :ref:`formats <tbl-formats>` [pdf].

.. _begin-V:

.. |Add_-V| unicode:: 0x20 .. just an invisible code
.. include:: explain_-V.rst_

.. include:: explain_help.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.

.. include:: explain_postscript.rst_

See Also
--------

:doc:`clear`,
:doc:`docs`,
:doc:`end`,
:doc:`figure`,
:doc:`inset`,
:doc:`subplot`,
:doc:`gmt`
