Documentation of complicated options

[PaulWessel]

The plot module is very powerful and very complicated to fully understand. There is an ocean of complexity between specifying how to plot a circle and how to plot a quoted line. The circle only has size, color, and pen to worry about, while for the quoted line we have six directives that determine where the text will be placed, then up to 20 modifiers to control various aspects of the result, from fonts to alignments to text being placed. Decorated lines are simpler in that there are only 8 modifiers to worry about. The segmentation option (-F) is another plot option that I think is extremely difficult to penetrate without more explanations in the form of examples. The error bar option -E, which includes box-and-whisker specifications, could also need a simple plot to explain the moving parts. There are probably others.

We actually have many examples of these options spread across our tests and gallery. However, I do not think we want to add page-size plots needed to fully cover quoted lines directly in the plot documentation. My proposal is therefore this:

Have more of a teaser figure as a heading for quoted lines and similar complicated options. This has been implemented. Then, there should be a link to a separate page for more details, similar to how we punt off the full explanation for all the modifiers related to vectors. I think the same applies to decorated lines, segmentation, and probably fronts. And custom symbols. We have an appendix on the custom symbol macro but very few pictures. The simpler stuff like error bars can fit in a small figure beneath that option.

The new pages should also form the backbone of another entry to the documentation that does not go through the modules. We have talked about this before as well. E.g., maybe a HOW-TO page that lists various how-tos:

• How to plot symbols?
• How to draw lines?
• How to plot polygons?
• How to plot text?
• How to plot grids?

etc. These would cross-link to the detailed pages and back to the corresponding modules. The modules would also link to the same pages. So whether you know you need to use plot of whether you just know you want to plot lines, in either case you will find eventually yourself on the same page discussing the details, with examples. I note the vector attribute page that explains all the modifiers is completely free of illustrations. I think with GMT, a picture really is worth a 1000 words, so there is much to do here. A competent GMT scripter could make many of these illustrations.

[Esteban82]

I would be glad to help with the HOW-TO guide. I think I qualified as a competent GMT scripter.

[PaulWessel]

Yes you certainly are! Let me try to develop an over-arching plan for how this would work so we all know what to do and what is required before we split up tasks. Next week, hopefully.

[stale]

This issue has been automatically marked as stale because it has not had activity in the last 90 days. It will be closed if no further activity occurs within 7 days. Thank you for your contributions.

[Esteban82]

I write some ideas for the HOW-TO guide:

The explanations must be in plain english (clear and concise and without complex vocabulary). It is easier to understand for users with a lower english level and also to translate correctly. Include multiple images showing how the figure was made.

The script must be bash files written with modern syntax. Should be friendly to the eye. That is to say, neat. Leave blank lines if necessary. Align the commands if possible. Include remarks.

I think it is better that each command should do one thing so the user can see it and reuse it. For example, use basemap many times with only one argument and not in only one line with multiple arguments.

Use keywords to easily find the subject of each example.

[maxrjones]

I would be glad to work with @Esteban82 on this. The documentation framework that Leo shared regarding the distinction between how-to guides and other components of documentation seems really fitting for this task and aligns well with Federico's ideas. Also relevant are the first how-to guides that Numpy added to their documentation. I like their idea of starting with a how-to guide for creating how-to guides, which could be more-or-less be an expansion of @Esteban82's last comment.

Perhaps after the AGU/end-of-semester rush, @PaulWessel can set the over-arching plan for this? It would be nice to have the standards for how-to-guides set for 6.2 and then we could add the guides for a 6.3 release.

[stale]

This issue has been automatically marked as stale because it has not had activity in the last 90 days. It will be closed if no further activity occurs within 7 days. Thank you for your contributions.

[maxrjones]

I moved this issue over to the gmt-examples repository as a place to host the simple how-to guides in the gallery section.