DOC/projections: Simplify links in the projection table to use directly the titles of the examples

[yvonnefroehlich]

Description of proposed changes

See #3405 (comment) for context.

• Correct link in projection table to projection code A (the first row)
• Simply link in projection table and use titles of examples
• Make projection names consistent - identical case: lower-case
• Make projection names consistent - keep or remove term "projection" -> separate PR
• Make projection names consistent - identical term: following the GMT table -> separate PR

Related upstream GMT PR: GenericMappingTools/gmt#8567

Preview

• projection table: https://pygmt-dev--3407.org.readthedocs.build/en/3407/techref/projections.html
• projection examples: https://pygmt-dev--3407.org.readthedocs.build/en/3407/projections/index.html

Fixes #3405

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 command is:

• /format: automatically format and lint the code

[seisman]

I'm unsure about changes like this. According to https://en.wikipedia.org/wiki/List_of_map_projections, the official name for this projection should be "Mollweide" rather than "Mollweide equal-area". "equal-area" is just a property of this projection, not its name.

[yvonnefroehlich]

Yes, I was unsure about this change. I used the upstream GMT table as an orientation. I fell it would be good, if both tables use the identical name for the projections. Maybe it is better to remove the "equal-area" and update the GMT table?

[seisman]

Let's wait for the upstream change first.

[yvonnefroehlich]

So the GMT-related PR is merged. Let's continue here.
Do we want to make the projection names consistent with GMT or consistent between the overview table and the examples? For the later one, do we want to use the name from the GMT projection table or form the headings of the GMTdocumentation page?

[seisman]

I think we should make the projection names consistent with headings of the GMT documentation.

[seisman]

Not sure if we can finish the upstream PR GenericMappingTools/gmt#8567 and this PR in time. If not, at least we can fix the link to the projection code A in PR #3370, and then work on the projection table after v0.13.0. @yvonnefroehlich What do you think?

[yvonnefroehlich]

Not sure if we can finish the upstream PR GenericMappingTools/gmt#8567 and this PR in time. If not, at least we can fix the link to the projection code A in PR #3370, and then work on the projection table after v0.13.0. @yvonnefroehlich What do you think?

Yes, unfortunately it looks like I am running a bit out of time with these PRs (just back to work since this Monday). For now, I fixed the like to the projection code A in the common typo fixes PR #3370.

[yvonnefroehlich]

Not sure if we can finish the upstream PR GenericMappingTools/gmt#8567 and this PR in time. If not, at least we can fix the link to the projection code A in PR #3370, and then work on the projection table after v0.13.0. @yvonnefroehlich What do you think?

Yes, unfortunately it looks like I am running a bit out of time with these PRs (just back to work since this Monday). For now, I fixed the like to the projection code A in the common typo fixes PR #3370.

Maybe we can split the PR into two parts: (i) simplifying the links (this PR, and completed for v0.13.0) and (ii) making the projection names consistent (new PR, and moved to v0.14.0).

I have reverted the changes of the projection names (see fb2e904). For now, the names are only changed regarding using consistently lower-case letters and removing the term "projection" (commit 46b37b7).

[seisman]

Maybe we can split the PR into two parts: (i) simplifying the links (this PR, and completed for v0.13.0) and (ii) making the projection names consistent (new PR, and moved to v0.14.0).

Sounds good to me.

I have reverted the changes of the projection names (see fb2e904). For now, the names are only changed regarding using consistently lower-case letters and removing the term "projection" (commit 46b37b7).
I'm debating if we should keep the "projection" term instead. For some projections like Mercator or Hammer, the term "projection" makes no difference, but for some projections like "Polyconic", "Polyconic" is an adjective, and "Polyconic projection" may make more sense in the example title.

[yvonnefroehlich]

I have reverted the changes of the projection names (see fb2e904). For now, the names are only changed regarding using consistently lower-case letters and removing the term "projection" (commit 46b37b7).

I'm debating if we should keep the "projection" term instead. For some projections like Mercator or Hammer, the term "projection" makes no difference, but for some projections like "Polyconic", "Polyconic" is an adjective, and "Polyconic projection" may make more sense in the example title.

Yes, I was actually wondering about this. But as we currently have "Azimuthal equistant", "General stereographic", "Gnomonic", "Orthographic", "Equidistant conic", and "Sinusoidal" without the term "projection" and these are also adjectives and sound (at least for me) better with "projection", I removed it for "Polyconic" and "Lambert conic conformal" to make it consistent. Maybe we can include this in the projection names discussion and decide on the GMT docs first (see also comment GenericMappingTools/gmt#8567 (comment)) and do the same for the PyGMT docs?

[yvonnefroehlich]

I have reverted the changes of the projection names (see fb2e904). For now, the names are only changed regarding using consistently lower-case letters and removing the term "projection" (commit 46b37b7).

I'm debating if we should keep the "projection" term instead. For some projections like Mercator or Hammer, the term "projection" makes no difference, but for some projections like "Polyconic", "Polyconic" is an adjective, and "Polyconic projection" may make more sense in the example title.

Yes, I was actually wondering about this. But as we currently have "Azimuthal equistant", "General stereographic", "Gnomonic", "Orthographic", "Equidistant conic", and "Sinusoidal" without the term "projection" and these are also adjectives and sound (at least for me) better with "projection", I removed it for "Polyconic" and "Lambert conic conformal" to make it consistent. Maybe we can include this in the projection names discussion and decide on the GMT docs first (see also comment GenericMappingTools/gmt#8567 (comment)) and do the same for the PyGMT docs?

Hm. I now reverted all projection name changes in this PR.

I have reverted the changes of the projection names (see fb2e904). For now, the names are only changed regarding using consistently lower-case letters and removing the term "projection" (commit 46b37b7).

I'm debating if we should keep the "projection" term instead. For some projections like Mercator or Hammer, the term "projection" makes no difference, but for some projections like "Polyconic", "Polyconic" is an adjective, and "Polyconic projection" may make more sense in the example title.

Yes, I was actually wondering about this. But as we currently have "Azimuthal equistant", "General stereographic", "Gnomonic", "Orthographic", "Equidistant conic", and "Sinusoidal" without the term "projection" and these are also adjectives and sound (at least for me) better with "projection", I removed it for "Polyconic" and "Lambert conic conformal" to make it consistent. Maybe we can include this in the projection names discussion and decide on the GMT docs first (see also comment GenericMappingTools/gmt#8567 (comment)) and do the same for the PyGMT docs?

Hm. I am currently unsure what still has to be done in this PR. Should I revert all changes of the projection names, including the change to lower-case? Or should I only add the term "projection" back for for "Polyconic" and "Lambert conic conformal"?

[seisman]

I prefer to leave this PR to v0.14.0 so that we can have more comments/thoughts from others before we make more changes.

[yvonnefroehlich]

I prefer to leave this PR to v0.14.0 so that we can have more comments/thoughts from others before we make more changes.

That's fine with me. Just thought we split this PR and want to get to link simplication in v0.13.0.

[yvonnefroehlich]

\format

[seisman]

Is this PR finished? I haven't checked all changes carefully, but generally they look good.

One off-topic question: Do you think we should combine the three gallery examples for the Oblique Mercator projections (https://www.pygmt.org/dev/projections/cyl/cyl_oblique_mercator_1.html, https://www.pygmt.org/dev/projections/cyl/cyl_oblique_mercator_2.html, https://www.pygmt.org/dev/projections/cyl/cyl_oblique_mercator_3.html) into the same page, since they are just one projection with different ways to specify the projection parameters.