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 warnings in `pygmt.show_versions()` and notes in [Common installation issues](https://www.pygmt.org/dev/install.html#not-working-transparency) 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,12 +74,14 @@ 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()
 ```
 
-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).
+You should see a global map with land and water masses colored in tan and lightblue, respectively, with the 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).
 
 ## Contacting us
 

doc/install.md

@@ -105,7 +105,7 @@ If you have [PyArrow](https://arrow.apache.org/docs/python/index.html) installed
 does have some initial support for `pandas.Series` and `pandas.DataFrame` objects with
 Apache Arrow-backed arrays. Specifically, only uint/int/float and date32/date64 dtypes
 are supported for now. Support for string Arrow dtypes is still a work in progress.
-For  more details, see [issue #2800](https://github.com/GenericMappingTools/pygmt/issues/2800).
+For more details, see [issue #2800](https://github.com/GenericMappingTools/pygmt/issues/2800).
 :::
 
 ## Installing GMT and other dependencies
@@ -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,12 @@ 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:
+
+- Use Ghostscript 9.53-9.56 for GMT 6.3/6.4
+- Use Ghostscript 10.03 or later for GMT 6.5