Links to lower case options in documentation are odd

[remkos]

Description of the problem

The modules are all described in the on-line documentation (e.g. https://docs.generic-mapping-tools.org/dev/plot.html) with the syntax at the top. There, the uppercase options (e.g. -J) are clickable and are linked to the descriptions below.

For the lowercase options, however, the option is not clickable, but the argument is. E.g. "flags" is clickable in -fflags, instead of -f. This is inconsistent.

In addition, the option -: is not linked at all. Neither is --PAR=value.

This is so across all the documentation of the modules.

[PaulWessel]

I think those are called |SYN_OPT-j| etc. See doc/source/common_SYN_OPTs.rst_

.. |SYN_OPT-j| replace:: **-j**\ :ref:flags <-distcalc_full>``

but it does not mean we have updated the documentation where -j etc are found.

[PaulWessel]

Maybe someone clever (looking at you @seisman) could write a script that finds all occurrences of **-?**, where ? is lower case and substitute them for|SYN_OPT-?|in all man pages?

[PaulWessel]

I can do this unless @seisman has started.

[seisman]

I haven't done it yet.

[remkos]

But then why do we have in doc/rst/source/common_SYN_OPTs.rst_ the following form for uppercase options:

.. |SYN_OPT-R| replace:: |-R|\ *region*

while for lowercase options we use:

`.. |SYN_OPT-j| replace:: **-j**\ :ref:flags <-distcalc_full>`

?

Why not

.. |SYN_OPT-j| replace:: |-j|\ *flags*

?

[PaulWessel]

Not sure Remko. My knowledge of RST is limited. For -R etc the explain* files starts with

.. _-R:

but the one for -j does not. I think (?) the:: _R is what creates |R| but not sure. Need comments from @maxrjones and @seisman here.

[joa-quim]

If you consult the history of the common_SYN_OPTs.rst_ file you'll see that they all started in 2013 as |SYN_OPT-?| replace:: **-?**\ ... but than in 10/25/2015 the upper cases changed to use the |?| macro. Why only the upper cases? Don't remember and didn't leave enough comments on the commit messages. Maybe there were not macros for the lower case options at the time. Remember that all this evolved from me converting the entire docs in HTML to RST and I had to learn RST while was doing the translation and the macros thing was something that I invented at the time from also limited knowledge at time (which was much better than my current one).

[joa-quim]

There is even this commit

SHA-1: d3e93f43764cdd40326733dfe35a3c055694134e

* Bring -A to -Z back to man pages

By a certain Remko that only modified (what existed at the time) the upper case macros.

[joa-quim]

.. _-R: Not the macro definition (that is in the common_SYN_OPTs.rst_ file) . This is what makes the page jump to the -R option when we click on it in synopsis (or any other occurrence of the -R link)

[seisman]

But then why do we have in doc/rst/source/common_SYN_OPTs.rst_ the following form for uppercase options:

.. |SYN_OPT-R| replace:: |-R|\ *region*

while for lowercase options we use:

`.. |SYN_OPT-j| replace:: **-j**\ :ref:flags <-distcalc_full>`

?

Why not

.. |SYN_OPT-j| replace:: |-j|\ *flags*

?

I'll work on this later.

[remkos]

Thanks @seisman . Unfortunately, I'm not much of a help, since I never managed to download the images, so I'm not able to build the documentation for testing. I'll try that once again.