I fear.
I fear that the CookBook gets too filled and stuff and users don't find the things there. My preferred example are the detailed info about reading complex netCDF and HDF grids via GDAL that we have in Reading more complex multi-band IMAGES or GRIDS and that people often have troubles in finding it.

I like the idea of having more explanation for the many ways to use options like -B and agree that the man pages are not the best place for that explanation. I also agree that it would be helpful to see the code that produces figures in the cookbook. For example, I think it would be helpful to see this code:

gmt basemap -R-2/1/0/0.35 -JM4i -Bpa15mf5mg5m -BwSe -Bs1f30mg15m --MAP_FRAME_TYPE=fancy-rounded \
		--MAP_GRID_PEN_PRIMARY=thinnest,black,. --MAP_GRID_CROSS_SIZE_SECONDARY=0.1i \
		--MAP_FRAME_WIDTH=0.075i --MAP_TICK_LENGTH_PRIMARY=0.1i

above this figure in the cookbook.

I disagree that the examples should be taken out of the man pages entirely, because those examples likely do help users quickly find information that they need. In addition, most software include some small number of examples in the reference documentation and I think it is good to include expected components in the man pages.

For completeness, other changes that I think are necessary are adding how-to guides, revising the tutorial, and adding more cross-referencing between the man pages, how-to guides, tutorial, and cookbook. I see the amount of explanation included as the main difference between the cookbook and the how-to guides/tutorial. The cookbook can include ample information about why things might be a certain way, but the how-to guides and tutorials should be more goal oriented.

Any more comments on this? Maybe @PaulWessel has some thoughts as well?

Hi @joa-quim, I see your point in the forum currently. Maybe the user seeking help did search the docs for "read netcdf" and had no luck? From personal experience I can say that the search function of the documentation is good if you know what you are looking for but is hard when you don't know exactly what your solution might look like. Additionally the current documentation system has a learning curve for how to find stuff.

If you are interested in what that -B does in a snippet of code you found somewhere? Unfortunately, the search function is no help here as a quick search for -B shows.

You must

• know that the information you are looking for hides behind the "Common Options" on the index page and
• then find it in the table
• realize you have to click on the small "(...)" at the end of the line to finally get to the info you are looking for.

Or, plan B, find a module that uses -B

• On the index page you should now be interested in "Modules".
• Have no clue which module uses -B, luckily the first entry basemap is a hit
• click on -B
• click on "(more ...)" and get yourself to the finish line this way.

Maybe this is a more fundamental problem with organizing the documentation. It just culminates in "users don't find the things there", as you wrote?

Hi @meghanrjones, ok, maybe it is just me and my use cases that the man page examples are seldomly useful for me. But I see your point. And yes, I agree with you that the command displayed above the plot would be helpful.

I would extend it and say every plot in the docs should have its command next to it. Maybe a separate page for each plot with a heavily commented command would be helpful as well? My reasoning is that the example you took is great not only for primary and secondary plot borders but also for offsets and the arrows and labels beneath it.

I totally agree with your last paragraph. Especially with the cross-linking and the different orientations between different types of documentation.

@leouieda once posted the link to the restructuring effort of the NumPy docs which is similar to what we are discussing here. It references "The Grand Unified Theory of Documentation" which somewhat sounds like a blueprint for our problem on hand.

The Grand Unified Theory of Documentation

@meghanrjones and @joa-quim what do you think - might this be a solution for the different problems with the current docs?

I think that, first of all, we could reordered the information in the man-page in order to be more user-friendly.

For example, instead of this (-F from basemap):

-F[d|l|t][+cclearances][+gfill][+i[[gap/]pen]][+p[pen]][+r[radius]][+s[[dx/dy/][shade]]]

Without further options, draws a rectangular border around any map inset (-D; classic mode only), map scale (-L) or map rose (-T) using MAP_FRAME_PEN; specify a different pen with +ppen. Add +gfill to fill the box [no fill]. Append +cclearance where clearance is either gap, xgap/ygap, or lgap/rgap/bgap/tgap where these items are uniform, separate in x- and y-direction, or individual side spacings between map inset/scale/rose and border. Append +i to draw a secondary, inner border as well. We use a uniform gap between borders of 2p and the MAP_DEFAULT_PEN unless other values are specified. Append +r to draw rounded rectangular borders instead, with a 6p corner radius. You can override this radius by appending another value. Finally, append +s to draw an offset background shaded region. Here, dx/dy indicates the shift relative to the foreground frame [4p/-4p] and shade sets the fill style to use for shading [gray50]. Used in combination with -D, -L or -T. To specify separate parameters for the various map features, append d|l|t to -F to specify panel parameters for just that panel [Default uses the same panel parameters for all selected map features].

We could write something like this:

-F[d|l|t][+cclearances][+gfill][+i[[gap/]pen]][+p[pen]][+r[radius]][+s[[dx/dy/][shade]]]

Without further options, draws a rectangular border around any map inset (-D; classic mode only), map scale (-L) or map rose (-T) using MAP_FRAME_PEN. Used in combination with -D, -L or -T. To specify separate parameters for the various map features, append d|l|t to -F to specify panel parameters for just that panel [Default uses the same panel parameters for all selected map features].
The following modifiers can be used:

• +ppen to specify a different pen with
• +gfill to fill the box [no fill]
• +cclearance where clearance is either gap, xgap/ygap, or lgap/rgap/bgap/tgap where these items are uniform, separate in x- and y-direction, or individual side spacings between map inset/scale/rose and border.
• +i to draw a secondary, inner border as well. We use a uniform gap between borders of 2p and the MAP_DEFAULT_PEN unless other values are specified.
• +r to draw rounded rectangular borders instead, with a 6p corner radius. You can override this radius by appending another value.
• +s to draw an offset background shaded region. Here, dx/dy indicates the shift relative to the foreground frame [4p/-4p] and shade sets the fill style to use for shading [gray50].

There are some arguments like -i in coast that are written this way.

Just another idea. I think it would be good to create a section with 2D surfaces (like the 1D array). It would be theoretical surfaces that could be helpful to test scripts for example. It should be add in grdmath manpage. If you think that it is good idea I can do it (or at least start).

There was a time that Paul wanted to create grdmath macros. That could be useful for use when synthetic data is handy.

Macros are fully operational but not supplied nor discussed in great details. I think they are looked for in current dir or .gmt etc.

Nice @Esteban82, I have made a lot of those things in my day. To make this more accessible to mere mortals, perhaps it is best to have a section on how to make 2-D surfaces and why one would want to.

gmt/grd math operators:

I have another suggestion. I was seeing the last column (return) of the table of operators of gmt/grd math. There are many operators that I don't understand what they do (like ACSC, BEI, BER, DILOG). I think that in some a more detailed description could be add. Also maybe we could add a link (to wikipedia?) for more complex operators. What do you think? I offer to help.

I notice that in the synopsis of the docs of some modules (e.g. movie, grdsample, grdimage) there is no link for the -x (lowercase) argument.
Is this on purpose? I saw the rst file but it was more complex that I expected and I am not sure how to fix it (if this is the case). So I decided to ask here.