Use more Math markup in documentation

[PaulWessel]

Description of the desired feature

Given that our Restructured Text documentation fully support mathematics, it would be nice to try to use it when we do math. If I cd into the doc source directory and search for things like "raised to the second power" which we do for area units and simple math, I find lots of places that could be improved very simply:

cd doc/rst/source/
find . -type f -exec grep -H '\^2' {} \;

./supplements/gshhg/gshhg.rst:north* is the enclosing rectangle, *area* is the polygon area in km^2
./supplements/mgd77/mgd77list.rst:        7.5038 \* V \* cos(lat) \* sin(az) + 0.004154 \* V^2
./supplements/mgd77/mgd77list.rst:(1) g = 978052.0 \* [1 + 0.005285 \* sin^2(lat) - 7e-6 \* sin^2(2\*lat)
./supplements/mgd77/mgd77list.rst:+ 27e-6 \* cos^2(lat) \* cos^2(lon-18)]
./supplements/mgd77/mgd77list.rst:(2) g = 978049.0 \* [1 + 0.0052884 \* sin^2(lat) - 0.0000059 \*
./supplements/mgd77/mgd77list.rst:sin^2(2\*lat)]
./supplements/mgd77/mgd77list.rst:(3) g = 978031.846 \* [1 + 0.0053024 \* sin^2(lat) - 0.0000058 \*
./supplements/mgd77/mgd77list.rst:sin^2(2\*lat)]
./supplements/mgd77/mgd77list.rst:(4) g = 978032.67714 \* [(1 + 0.00193185138639 \* sin^2(lat)) / sqrt (1
./supplements/mgd77/mgd77list.rst:- 0.00669437999013 \* sin^2(lat))]
./supplements/mgd77/mgd77list.rst:99999999 mag 0.5\*cos(0.5\*(azim-19))^2 1.0\*exp(-1e-3(lat))^1.5
./supplements/potential/gmtflexure.rst:    or Young's modulus [7.0e10 N/m^2], respectively.
./supplements/potential/grdflexure.rst:    or Young's modulus [7.0e10 N/m^2], respectively.
./supplements/x2sys/x2sys_solve.rst:    **g** will fit f(**p**) = *a* + *b* sin(y)^2
./trend2d.rst:  z(x,y) = m_1 + m_{2}x + m_{3}y + m_{4}xy + m_{5}x^2 + m_{6}y^2 + m_{7}x^3 +
./trend2d.rst:  m_{8}x^{2}y + m_{9}xy^2 + m_{10}y^3.
./trend2d.rst:    and create weights as 1/*sigma*\ ^2, or use the weights as read (**+w**)
./tutorial/session-2_jl.rst:#. At *y = 5*, add the sentence :math:`z^2 = x^2 + y^2`.
./tutorial/session-1.rst:ranges from 10^20 to 10^24.  One possibility is
./tutorial/session-2.rst:#. At *y = 5*, add the sentence :math:`z^2 = x^2 + y^2`.
./tutorial/session-3_jl.rst:    (1-t)\nabla ^2 z -  t \nabla z = 0,
./tutorial/session-1_jl.rst:raw *x* data range from 3 to 9613 and that *y* ranges from 10^20 to 10^24. One possibility is
./grdfft.rst:curvature of the field. We can compute these as mGal/m^2 by::
./grd2xyz.rst:    For geographic grids we default to a length unit of **k** (hence area is in km^2). Change
./grd2xyz.rst:To write out *lon, lat, topo, area* from the @AFR.nc file, selecting meter^2 as the area unit,
./blockmean.rst:    then append **+s** and we compute weight = 1/sigma^2.  Otherwise (or
./explain_-A.rst_:    Features with an area smaller than *min\_area* in km^2 or of
./grdvolume.rst:To determine area (in km^2), volume (in km^3), and mean height (in km) of all land areas
./grdvolume.rst:   in unit^2 * z_unit quantities.
./gmtmath.rst:  **D2DT2**       1 1     d^2(A)/dt^2 2nd derivative                                                                  Calculus           
./gmtmath.rst:  **HYPOT**       2 1     Hypotenuse of a right triangle of sides A and B (= sqrt (A^2 + B^2))                        Calculus           
./gmtmath.rst:  **R2**          2 1     Hypotenuse squared (= A^2 + B^2)                                                            Calculus           
./grdtrend.rst:    m_1 + m_2x + m_3y + m_4xy + m_5x^2 + m_6y^2 + m_7x^3 + m_8x^2y + m_9xy^2 + m_{10}y^3.
./grdtrend.rst:    :math:`m_1 + m_2x + m_3x^2 + m_4x^3` or :math:`m_1 + m_2y + m_3y^2 + m_4y^3`.
./grdtrend.rst:    as 1/sigma^2.  If the robust option has been selected, the weights used
./grdfill.rst:    append a search *radius* in pixels [default radius is :math:`r = \sqrt{n^2 + m^2}`,
./grdmath.rst:| **AREA**      | 0 1   | Area of each gridnode cell (in km^2 if geographic)                                                     |
./grdmath.rst:| **D2DX2**     | 1 1   | d^2(A)/dx^2 2nd derivative                                                                             |
./grdmath.rst:| **D2DY2**     | 1 1   | d^2(A)/dy^2 2nd derivative                                                                             |
./grdmath.rst:| **D2DXY**     | 1 1   | d^2(A)/dxdy 2nd derivative                                                                             |
./grdmath.rst:| **R2**        | 2 1   | R2 = A^2 + B^2                                                                                         |
./grdmath.rst:| **SQR**       | 1 1   | A^2                                                                                                    |
./grdmath.rst:   2^24 or 16,777,216. Any higher result will be masked to fit in the lower
./trend1d.rst:    and create weights as 1/*sigma*\ ^2 [Default reads only the first 2 columns].
./trend1d.rst:To fit the model y(x) = a + bx^2 + c * cos(2*pi*3*(x/l) + d * sin(2*pi*3*(x/l), with l the fundamental period (here l = 15), try:
./grdfilter.rst:filter exp (-0.5\*r^2) whose distances r from the center is given by
./grdfilter.rst:(2x^2 + y^2 -2xy)/6, with major axis at an angle of 63 degrees with the

For the uninitiated you can just grep ':math:' * to see how it is done with math. I post this here since it is a very simple thing that new wannabe collaborators could try out for, say, one module at the time and offer a pull request for us to consider. We all have to full on the oars if we want to documentation to shine,

[anbj]

In the case of e.g. km^2; should it be :math:km^2 or km :math:^2?

[joa-quim]

Probably :math:^2 to not change the font of km as comparing to a linear km, but this is really a :math:^-100 issue.

[anbj]

My thought as well.

[anbj]

There is also some variation in examples; some are indented and some are not. What is the preferred way? Here an example from grdvolume.

[PaulWessel]

I think indentation is nice and the others are just leftover things from initial text to RST translation I imagine.

[anbj]

Alright. Indention it is!

[KristofKoch]

To keep track of the pages that are being worked on I would like to suggest a naming convention for the issues. Can we agree on naming the issues

DwM for Docs with Math followed by the file name of the file one intend to work on?

For example:

DwM gshhg.rst

would indicate that I work on gshhg.rst to use the :math: syntax and maybe fix minor layout things while at it?

[KristofKoch]

@PaulWessel while working on #7233 I found out that

:math:`^2`

breaks the docs if you use copy & paste.

using :math:

The visual representation in the html page is as intended but when you copy the text and paste it somewhere else things go wild. See the following example:

RestructuredText:

the polygon area in km\ :math:`^2` while *f\_area* is the actual area

Result after copy & paste:

the polygon area in km

2
while f_area is the actual area

using :sup:

With some reading around I found that :sup: would give proper html syntax that is "copy & paste safe" and gives the required visual representation in html:

RestructuredText:

the polygon area in km\ :sup:`2` while *f\_area* is the actual area

Result after copy & paste:

area is the polygon area in km2 while f_area is the actual area

While km2 is not as good as km^2 it preserves the meaning and layout better than whatever happens when using :math:.

While not exactly your initial proposal I would recommend using :sup: instead of :math: for all those inline "raised to the power" occasions.

Maybe there is an even better way to achieve this without breaking copy & paste?

[KristofKoch]

Do @joa-quim or @GenericMappingTools/gmt-docs have an opinion on :math: vs :sup:?

[joa-quim]

Not in particular, but if it does it better for some purpose, I'm fine with it.

[anbj]

Do @joa-quim or @GenericMappingTools/gmt-docs have an opinion on :math: vs :sup:?

Looks good to me (had to look it up).

[PaulWessel]

Just looked at gmtmath after @KristofKoch work and it looks great! However, I also noticed we have a bunch of sub-scripts as well and these look odd as chi2, nu1. In fact, they should be:math: treated I think since we might as well use the Greek chi^2 and nu_1 when explaining what A and B are since statistics books and tables use those terms. Then for operators like BCDF the p and n should be italicised as variables. BITTEST seems to have a dangling n, The CHI ops need Greek, COMB* need subscripts on C, E distros need greek lambda and so it goes down the list.