Add illustration to complicated module options

[PaulWessel]

Hi @GenericMappingTools/gmt-contributors-

The documentation for plot got much better after adding the illustrations of the many type of symbol groups. However, there are many other modules that could benefit from either

A representative figure just below the Description section
An illustrative figure at the end of the stuff for some option -X

Some may need both. This requires familiarity with GMT and ability and willingness to write a short script that makes the figure, or search through test/module to see if we already have one among the tests. If you have suggestions for such and willing to do it, open a PR with a title like "WIP supporting figure for module xxxxxx" where your branch off master simply adds the script with a useful name like the others in doc/script, e.g. GMT_segmentations.sh. Select the core collaborator team for the review. The team can then try it out. Just post the figure on GItHub for now (do not add PS file to DVC etc since we need to review first).

Ideally, the illustration is made at 15cm by 5 cm unless by nature it needs to be taller or square.

[seisman]

Just one thought here, adding more images is definitely a good idea, but it will also significantly increase the number of tests, which will slow down the testing process.

For example, the image for the 35 PostScript fonts (https://docs.generic-mapping-tools.org/dev/_images/GMT_App_G.png) never changes and should always pass. Sometimes it fails because tiny differences caused by different gs versions but we really don't care about it. So it's not necessary to test it.

In other words, we should have a mechanism to skip a test, e.g., adding # SKIP_TEST to skip it.

[gd-a]

Well, I'm willing to write some. Can you make a somewhat prioritized list? Do you want them to be one-liners or within begin environment ?

[PaulWessel]

Thanks. I dont have a list. I think it words best if there is a particular option that is too nebulous to you and could benefit from a sketch or plot. I am sensitive to @seisman's point but unlike most of the tests these scripts actually produce a figure in the documentation and even allows users to see the script that made it. To the extent possible, show around for something in the test/module directory. If it does not have exactly what you need then you can add to it or it is a new script (which goes in doc/scripts). Don't worry about the PostScript plots - we can update those via DVC when the PR is accepted.

[PaulWessel]

I found a test that is also used separately in doc/scripts. I will remove that test and its baseline PS file. Do I run dvc add test/baseline/psxy to "remove" one file or is there a dvc remove command I should use instead. First time I remove a test...

[seisman]

You can try:

rm doc/scripts/images/xxx.ps
dvc status
dvc add doc/scripts/images