Enforce mode setting from GMT_Create_Session in API-driven programs

[PaulWessel]

Description of proposed changes

See #4518 for background, as reported by @sarzeaud.

The key problem was that when modules are not driven by gmt.c (i.e., command-line calls), the single GMT_Create_Session call must set the type of the session. Pass GMT_SESSION_NORMAL and you create a classic session, and pass GMT_SESSION_RUNMODE to select modern mode. Apart from the wrappers (MATLAB, Julia, Python), stand-alone C/C++ programs must follow that rule. Now, sessions started as classic cannot later call modern-mode only modules such as begin, figure, subplot, inset, and end.

I have added a new testapi_map.c program derived from the example in #4518. By default it creates a PostScript plot and the test for this passes, but if testapi_map is run manually on the command line with a valid graphics extension (e.g., testapi_map jpg) then it will now produce the cropped JPG missing from the original posting.

I suggest @joa-quim and @seisman test this branch in GMT.jl and PyGMT before approving.

[sarzeaud]

Hi Paul,
I have just tested your patch here with the GMT_SESSION_RUNMODE flag. It works BUT options that could follow after the file extension are not taken into account. I have tested with A+m0.2c to have a thin margin around the crop but it is not done.
Can you imagine a way to do that, or must I forget it?

[PaulWessel]

Will have a look. GMT modern mode was invented way after the API was designed.

[joa-quim]

It looks a bit scary but didn't affect GMT.jl

[PaulWessel]

It is a bit tricky with starting the modern mode at the GMT_Create_Session in this case, since that means the session is created before the args to gmt begin is processed. We need to rethink what role the mode has in the use of the API.

[sarzeaud]

Do you plan to merge this branch into master before 6.2?

[PaulWessel]

I am not sure as I am not happy with it overall. I think I want to revisit this but I am juggling several other branches with the team right now. Still want to fix this one before 6.2 though but only 24 hours per day, still.

[sarzeaud]

Thank you. Tell me if I can help.