Add Developer Documentation link to the sidebar

[PaulWessel]

Description of proposed changes

This PR adds a link to the developer documentation which is a new directory with detailed explanations only relevant to the developers. Currently, it only contains the rationale and design for how to introduce long-options in GMT, but over time the "gurudocs" materials from the sandbox repo will be reformatted and added as new sections in this document. In doing this I broke up the ugly ifdef-ed splitting of the long options for the three blockm*.c programs and I directly show the lines in the codes as part of the docs. Hopefully, this is useful information to the developers as well as wanna-bee developers who may have better ideas on how things should be implemented.

[joa-quim]

Long options like read-columns are not a good idea. They cannot be followed by the wrappers where the - means subtraction and read-columns will not be seen as a single name but as an algebraic operation.

[PaulWessel]

OK. I was thinking the keywords are strings but you are saying in Julia they are variables (so obviously cannot use hyphens)?

[joa-quim]

Nope,

julia> D = mbgetdata(raw"C:\j\OT\PatchSurvezEM122PHINS\0000_20111219_154640_METEOR_EM122.mb59", Vd-aa=1);
ERROR: syntax: invalid keyword argument name "(Vd - aa)" around REPL[5]:1

and I'm sure Matlab & Python will scream the same.

[maxrjones]

Matlab generally uses CamelCase, I think standard in python is underscores (my preference).

[PaulWessel]

I understand that variables cannot have hyphens. I am just asking if keywords are in fact variables in Julia. In MATLAB, your example would be 'Vd-aa', 1, and since a string no screaming would ensue. So looks like the same is the case in PyGMT, i.e.,

fig.coast(shorelines="1/0.5p", region=[-180, 180, -60, 60], projection="M10i")

and I assume

fig.coast(shorelines="1/0.5p", region=[-180, 180, -60, 60], read-columns=3)

would scream as well. true, @seisman ? If so then read-columns will be changed to readcolumns or incolumns.

[joa-quim]

Right, Matlab doesn't have kwargs but I would be very surprised if Python accepted read-columns=3. Keywords are not strings in Julia and almost for sure not in Python either.

[PaulWessel]

Just so I understand and that we are on the same page. If GMT has a common standard option -Rw/e/s/n which on the command-line would be --region=w/e/s/n, this keyword/value combination will be treated differently in the wrappers:

MATLAB: gmt ('coast', 'region', [-10 20 -5 44], ...); Just a string/value thing
PyGMT: gmt.coast (region, [-10 20 -5 44], ...); Keyword/value pair
Julia: coast (region, [-10 20 -5 44], ...); Keyword/value pair

Thus, all keywords must satisfy the usual restrictions on variable names, i.e., cannot start with number, no special symbols, but use underscores or CamelCase to indicate word separations.

With that I can revise the common option translation structure.

[PaulWessel]

To improve correlation between short and long options I think we should do this:

-i becomes --incols=
-o becomes --outcols=

This avoids the read/write-columns. Anyone have feelings about incols versus incolumns?

[joa-quim]

This avoids the read/write-columns. Anyone have feelings about incols versus incolumns?

It's incol in Julia (but trivial to add incols as well). incolumns seem a bit too long.

[PaulWessel]

I am OK with the idea that the wrappers can add any number of aliases for the "official" GMT long-option. I have no strong opinion on cols vs columns, but I think it should be plural (so incols, outcols).

[joa-quim]

Julia: coast (region, [-10 20 -5 44], ...);

As I told you before I don't intend to use the GMT long-options parsing mechanism. I don't even would know how to implement region, [-10 20 -5 44], which is not a kwarg pair, as a equivalent to region=[-10 20 -5 44]. But I think the wrappers should follow the closest as possible the same variable naming as the mother/father GMT, so the rules for variables naming should apply.

[PaulWessel]

Sorry, the Julia example was meant to be coast(region=[0 360 -90 90], ... straight from your example.