Tutorial "Plotting text": Rewrite to improve structure, explain more parameters, show list input

[yvonnefroehlich]

Description of proposed changes

This PR aims to expand and update the tutorial "Plotting text":

• Mention the position parameter along with justify
• Mention the pen parameter along with fill
• Grouping and showing the configurations justify, font, angle, fill + pen via simple Cartesian plots
• Showing the possiblity of providing lists for justify, font, and angle (possible after PR Figure.text: Support passing in a list of angle/font/justify values #2720) beside providing an external input file

Please state, whether these changes are improvements, or that we should keep the current version.

Changes suggested by @seisman to improve the structure of the tutorial (see comment #2760 (comment)):

• 1. The first map should have only one text (e.g., text="SOUTH CHINA SEA", x=112, y=6)
• 2. Introduce the angle/font/justify/pen/fill parameters to adjust the texts (maybe one map for angle/font/justify and another map for pen/fill
• 3. Show how to add several texts in one Figure.text call (e.g., pass 1-D arrays to x/y/text)
• 4. Show that angle/font/justify can also accept 1-D arrays (maybe combine 3 and 4 into one map)
• 5. Explain that it's also possible to pass a file or a 2-D matrix to data textfiles
• 6. Introduce the position parameter. A useful use case for this parameter is to add a tag (e.g., (a)) at the top left corner of the map for multiple subplots, but we should also mention that the Figure.subplot method can do this automatically.

Preview: https://pygmt-dev--2760.org.readthedocs.build/en/2760/tutorials/basics/text.html

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If wrapping a new module, open a 'Wrap new GMT module' issue and submit reasonably-sized PRs.
• If adding new functionality, add an example to docstrings or tutorials.
• Use underscores (not hyphens) in names of Python files and directories.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash commands are:

• /format: automatically format and lint the code
• /test-gmt-dev: run full tests on the latest GMT development version

[seisman]

Sorry to be mean here, but I think the "Plotting text" tutorial (both the old version and the current new version) is not as good as other tutorials. In other tutorials, we usually start with a simple plot with a few required parameters and then improve the plot by adding more parameters step by step in the following sections, but in this tutorial, we start with a nice map and then start to explain the position/text, font, angle, fill/pen parameters, which has nothing to do with the first map. The tutorial reads more like a manual for Figure.text's parameters, rather than a tutorial for adding texts.

Here are my thoughts about the tutorial:

1. The first map should have only one text (e.g., text="SOUTH CHINA SEA", x=112, y=6)
2. Introduce the angle/font/justify/pen/fill parameters to adjust the texts (maybe one map for angle/font/justify and another map for pen/fill
3. Show how to add several texts in one Figure.text call (e.g., pass 1-D arrays to x/y/text)
4. Show that angle/font/justify can also accept 1-D arrays (maybe combine 3 and 4 into one map)
5. Explain that it's also possible to pass a file or a 2-D matrix to data
6. Introduce the position parameter. A useful use case for this parameter is to add a tag (e.g., (a)) at the top left corner of the map for multiple subplots, but we should also mention that the Figure.subplot method can do this automatically.

[yvonnefroehlich]

Sorry to be mean here, but I think the "Plotting text" tutorial (both the old version and the current new version) is not as good as other tutorials. In other tutorials, we usually start with a simple plot with a few required parameters and then improve the plot by adding more parameters step by step in the following sections, but in this tutorial, we start with a nice map and then start to explain the position/text, font, angle, fill/pen parameters, which has nothing to do with the first map. The tutorial reads more like a manual for Figure.text's parameters, rather than a tutorial for adding texts.

Here are my thoughts about the tutorial:

1. The first map should have only one text (e.g., text="SOUTH CHINA SEA", x=112, y=6)
2. Introduce the angle/font/justify/pen/fill parameters to adjust the texts (maybe one map for angle/font/justify and another map for pen/fill
3. Show how to add several texts in one Figure.text call (e.g., pass 1-D arrays to x/y/text)
4. Show that angle/font/justify can also accept 1-D arrays (maybe combine 3 and 4 into one map)
5. Explain that it's also possible to pass a file or a 2-D matrix to data
6. Introduce the position parameter. A useful use case for this parameter is to add a tag (e.g., (a)) at the top left corner of the map for multiple subplots, but we should also mention that the Figure.subplot method can do this automatically.

No worries @seisman. My initial intent for this PR was only to add a code example regarding list input for font, angle, and justify. But this turned out to be more difficult than expected because of the current structure of the tutorial. Thus, I made some additional changes to the tutorial and then tried to include the list-input-aspect. But as you mentioned, the tutorial is still not optimal in terms of its structure from an educational perspective. However, I was unsure about making more significant changes, as I am not the original author of this tutorial. But I am open to consider your suggested points above to restructure and rewrite this tutorial. Maybe it makes sense to see what the other @GenericMappingTools/pygmt-maintainers think about these changes🙂 before I start working on this.

[yvonnefroehlich]

I tried to address the issues mentioned by @seisman in #2760 (comment). @GenericMappingTools/pygmt-maintainers do you think the current changes are improving this tutorial?

[seisman]

Looks good.