.\" Man page generated from reStructuredText.
.
.TH "BEGIN" "1gmt" "Sep 07, 2019" "6.0.0rc4" "GMT"
.SH NAME
begin \- Initiate a new GMT modern mode session
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
\fBgmt begin\fP [\fIprefix\fP] [\fIformats\fP] [\fIoptions\fP]
[  \fB\-V\fP[\fIlevel\fP] ]
.sp
\fBNote:\fP No space is allowed between the option flag and the associated arguments.
.SH DESCRIPTION
.sp
The \fBbegin\fP 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 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 \fIprefix\fP and \fIformats\fP, you can supply a comma\-separated series of
psconvert \fIoptions\fP that will override the default settings provided via
PS_CONVERT [\fBA\fP]. The only other available options control verbosity
and default parameter settings.
.SH OPTIONAL ARGUMENTS
.INDENT 0.0
.TP
.B \fIprefix\fP
Name\-stem used to construct the single final figure name.  The extension is appended
automatically from your \fIformats\fP 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 \fIprefix\fP has spaces in it then you must enclose your
prefix in single or double quotes.
.UNINDENT
.INDENT 0.0
.TP
.B \fIformats\fP
Give one or more comma\-separated graphics extensions from the list of allowable graphics formats
\fI\%formats\fP (default is configurable via setting GMT_GRAPHICS_FORMAT [pdf]).
.UNINDENT
.INDENT 0.0
.TP
.B \fIoptions\fP
Sets one or more comma\-separated options (and possibly arguments) that
can be passed to psconvert when preparing a session figure [\fBA\fP].
The valid subset of options are
\fBA\fP[\fIargs\fP],\fBC\fP\fIargs\fP,\fBD\fP\fIdir\fP,\fBE\fP\fIdpi\fP,\fBH\fP\fIfactor\fP,\fBM\fP\fIargs\fP,\fBQ\fP\fIargs\fP,\fBS\fP\&.
See the psconvert documentation for details on these options.
.UNINDENT
.INDENT 0.0
.TP
\fB\-V\fP[\fIlevel\fP] (more ...)
Select verbosity level [c].  
.UNINDENT
.INDENT 0.0
.TP
\fB\-^\fP or just \fB\-\fP
Print a short message about the syntax of the command, then exits (NOTE: on Windows just use \fB\-\fP).
.TP
\fB\-+\fP or just \fB+\fP
Print an extensive usage (help) message, including the explanation of
any module\-specific option (but not the GMT common options), then exits.
.TP
\fB\-?\fP or no arguments
Print a complete usage (help) message, including the explanation of all options, then exits.
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
Format
T}	T{
Explanation
T}
_
T{
bmp
T}	T{
Microsoft Bit Map
T}
_
T{
eps
T}	T{
Encapsulated PostScript
T}
_
T{
jpg
T}	T{
Joint Photographic Experts Group Format
T}
_
T{
pdf
T}	T{
Portable Document Format [Default]
T}
_
T{
png
T}	T{
Portable Network Graphics (opaque)
T}
_
T{
PNG
T}	T{
Portable Network Graphics (transparent)
T}
_
T{
ppm
T}	T{
Portable Pixel Map
T}
_
T{
ps
T}	T{
Plain PostScript
T}
_
T{
tif
T}	T{
Tagged Image Format File
T}
_
.TE
.UNINDENT
.UNINDENT
.SH EXAMPLES
.sp
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
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt begin Figure_2 pdf,png
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
If the modern session is only used for computations and no illustrations
are produced then we do not need to give any further arguments:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt begin
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
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).
.sp
To set up proceedings for a jpg figure with 0.5c white margin, we would run
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt begin \(aqMy Figure4\(aq pdf,png A+m1c
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SH NOTE ON POSTSCRIPT
.sp
If the user selects \fBps\fP as one of the formats, then please be aware that
it is recommended you first set the desired paper size.  With \fBps\fP, GMT needs to
work with a fixed paper size since, unlike the \fBeps\fP format, there will be
no cropping to BoundingBox.  If no paper size is specified via PS_MEDIA
then GMT will default to A4 and issue a warning; GMT is unable to determine if that
size is adequate for your plot but if the canvas width exceeds A4 paper width we will
switch page orientation to landscape. For all other formats the final dimension will
be determined automatically.
.SH NOTE ON UNIX SHELLS
.sp
Modern mode works by communicating across gmt modules via the shell script\(aqs (or terminal\(aqs)
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):
.INDENT 0.0
.INDENT 3.5
export GMT_SESSION_NAME=$$
.UNINDENT
.UNINDENT
.sp
or in cshell:
.INDENT 0.0
.INDENT 3.5
setenv GMT_SESSION_NAME $$
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
clear,
docs,
end,
figure,
inset,
subplot,
gmt
.SH COPYRIGHT
2019, The GMT Team
.\" Generated by docutils manpage writer.
.