Documentation of character escape sequences in text module and Cookbook not ideal

[KristofKoch]

Description of the problem

The documentation for the character escape sequences exists in both the text module and in the Cookbook. Neither one is really good and I would like to improve the documentation.

Identified areas for improvement:
(in no particular order)

1. The wording in the tables is different (toggle vs turn on/off, I prefer turn on/off as it is easier to understand for people with basic English skills)
2. LaTex option is missing completely in the Cookbook and is not in the table in text, just some paragraphs down as text. Easy to overlook that powerful option this way.
3. The various accented European characters are presented in a nice table in the Cookbook but for some reason in text only the shorthands are given instead of the resulting characters. Would be better to have the supported characters on hand and then link to the table for the shorthand?
4. Maybe move the details completely into the Cookbook and just link to it in text? Only one place to maintain them.

The issue was brought to my attention by user Andreas in the forum.

What do @GenericMappingTools/core and @GenericMappingTools/gmt-maintainers think about this? Do you consider it worthwhile? If yes, I'm happy to work on the improvement of the documentation.

[PaulWessel]

It is always true that the documentation can be improved. We try to follow this model for new changes:

If some chunks of explanation (say Latex or accented characters) really is useful in more than one place, then we make a single file with extension.rst_ and we include that file in the places the content should go. This means we only have one place to maintain and fix for typos or extensions even though it appears in more than one place in the docs.

Over the years we have made changes to fit this model but there are tons of places that could benefit from this treatment. Last week I added this to both grdmath and gmtmath documentation just after the description:

.. include:: RPN_info.rst_

and that file shows some relevant images and captions that discusses Reverse Polish Notation, for instance.

[KristofKoch]

That include model is better than my idea. Would you mind me giving it a shot for the escape characters and consolidate that info into a single file?

@PaulWessel - After re-reading my initial post it sounds a bit harsh/aggressive – that wasn't my intention. I know how hard it can be to document things properly and then maintaining it. If you felt this way, please accept my apologies. I just saw a possible area for improvement where I don't have to rely on your work and time to improve it but could do it myself.

[PaulWessel]

No worries Kristof, I have thick skin and did not even notice anything negative.

[KristofKoch]

Phew. Glad to hear! Do you think it is worthwhile me going ahead with this?

[PaulWessel]

Sure, I think any improvement is good.