GMT-Ghostscript incompatibility: Give recommendations and extend examples

.github/ISSUE_TEMPLATE/4-release_checklist.md

@@ -23,6 +23,7 @@ assignees: ''
   - [ ] All tests pass in the ["GMT Dev Tests" workflow](https://github.com/GenericMappingTools/pygmt/actions/workflows/ci_tests_dev.yaml)
   - [ ] All tests pass in the ["Doctests" workflow](https://github.com/GenericMappingTools/pygmt/actions/workflows/ci_doctests.yaml)
   - [ ] Deprecations and related tests are removed for this version by running `grep --include="*.py" -r 'remove_version="vX.Y.Z"' pygmt` from the base of the repository
+- [ ] Update warning in `pygmt.show_versions()` and note in [Common installation issues](https://www.pygmt.org/dev/install.html#common-installation-issues) regarding GMT-ghostscript incompatibility
 - [ ] Reserve a DOI on [Zenodo](https://zenodo.org) by clicking on "New Version"
 - [ ] Review the ["PyGMT Team" page](https://www.pygmt.org/dev/team.html)
 - [ ] Finish up 'Changelog entry for v0.x.x' Pull Request:

README.md

@@ -74,10 +74,12 @@ or a [Jupyter notebook](https://docs.jupyter.org/en/latest/running.html), and tr
 ``` python
 import pygmt
 fig = pygmt.Figure()
-fig.coast(projection="H10c", region="g", frame=True, land="gray")
+fig.coast(projection="N10c", region="g", frame=True, land="tan", water="lightblue")
+fig.text(position="MC", text="PyGMT", font="60p,Helvetica-Bold,red@75")
 fig.show()
 ```
 
+You should see a global map with land and water masses colored in tan and lightblue, respectively, with a semi-transparent text "PyGMT" on top. 
 For more examples, please have a look at the [Gallery](https://www.pygmt.org/latest/gallery/index.html) and
 [Tutorials](https://www.pygmt.org/latest/tutorials/index.html).
 

doc/install.md

@@ -238,11 +238,15 @@ import pygmt
 pygmt.show_versions()
 
 fig = pygmt.Figure()
-fig.coast(region="g", frame=True, shorelines=1)
+fig.coast(projection="N10c", region="g", frame=True, land="tan", water="lightblue")
+fig.text(position="MC", text="PyGMT", font="60p,Helvetica-Bold,red@75")
 fig.show()
 ```
 
-If you see a global map with shorelines, then you're all set.
+You should see a global map with land and water masses colored in tan and lightblue, respectively. On top, there
+should be the semi-transparent text "PyGMT". If the semi-transparency does not show up, there is  probably an
+incompatibility between your GMT and ghostscript versions. For details, please run `pygmt.show_versions()` and
+see [Not working transparency](#not-working-transparency).
 
 ## Common installation issues
 
@@ -284,3 +288,13 @@ jupyter kernelspec list --json
 
 After that, you need to restart Jupyter, open your notebook, select the `pygmt` kernel
 and then import pygmt.
+
+
+### Not working transparency
+
+It is known that some combinations of GMT and ghostscript versions cause issues, especially
+regarding transparency:
+
+- ghostscript 9.53-9.56: work
+- ghostscript 10.00-10.01: doesn't work
+- ghostscript 10.02-10.03: work, but requires GMT<=6.4