From: Vladimír Vondruš Date: Mon, 18 Jun 2018 13:11:58 +0000 (+0200) Subject: doc: update math docs with new features and behavior. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=7e04f1b8e0596c2f57d839771f544b913a6f7e74;p=blog.git doc: update math docs with new features and behavior. --- diff --git a/doc/admire/math.rst b/doc/admire/math.rst index fbf9719e..2bfbc787 100644 --- a/doc/admire/math.rst +++ b/doc/admire/math.rst @@ -30,6 +30,8 @@ m.css math .. role:: text-primary :class: m-text m-primary +.. |o| replace:: · + :url: admire/math/ :cover: {filename}/static/cover-math.jpg :summary: The fastest possible math rendering for the modern web @@ -75,11 +77,11 @@ m.css math .. container:: m-col-m-12 - .. https://en.wikipedia.org/wiki/Rendering_equation + .. a copy of the following is below .. math:: - L_o(p,\omega_o) = \int\limits_{\Omega} f_r(p,\omega_i,\omega_o) L_i(p,\omega_i) n \cdot \omega_i d\omega_i + {\color{m-primary} L_o (\boldsymbol{x}, \omega_o)} = {\color{m-danger}\int\limits_{\Omega}} {\color{m-warning} f_r(\boldsymbol{x},\omega_i,\omega_o)} {\color{m-success} L_i(\boldsymbol{x},\omega_i)} {\color{m-info} ( \omega_i \cdot \boldsymbol{n})} {\color{m-danger} \operatorname d \omega_i} .. container:: m-row m-container-inflate @@ -132,12 +134,25 @@ performs and that there is no blank space or jumping until the math appears. View the page source to verify that there is nothing extra being loaded to make this happen. +Try to resize the window --- everything is possible, so why not have a +different layout of long equations optimized for smaller screens? + .. math:: + :class: m-show-m \pi = \cfrac{4} {1+\cfrac{1^2} {2+\cfrac{3^2} {2+\cfrac{5^2} {2+\ddots}}}} = \sum_{n=0}^\infty \frac{4(-1)^n}{2n+1} = \frac{4}{1} - \frac{4}{3} + \frac{4}{5} - \frac{4}{7} +- \cdots + .. math:: + :class: m-hide-m + + \begin{array}{rcl} + \pi &=& \cfrac{4} {1+\cfrac{1^2} {2+\cfrac{3^2} {2+\cfrac{5^2} {2+\ddots}}}} + = \sum_{n=0}^\infty \frac{4(-1)^n}{2n+1} \\ + &=& \frac{4}{1} - \frac{4}{3} + \frac{4}{5} - \frac{4}{7} +- \cdots + \end{array} + .. class:: m-text m-text-right m-dim m-em --- `Generalized continued fraction `_, @@ -158,20 +173,8 @@ Matrices render pretty well also: --- `QR decomposition `_, Wikipedia -And :text-primary:`everything can be colored` just by putting CSS classes -around: - - .. math:: - :class: m-primary - - X_{k+N} \ \stackrel{\mathrm{def}}{=} \ \sum_{n=0}^{N-1} x_n e^{-\frac{2\pi i}{N} (k+N) n} = \sum_{n=0}^{N-1} x_n e^{-\frac{2\pi i}{N} k n} \underbrace{e^{-2 \pi i n}}_{1} = \sum_{n=0}^{N-1} x_n e^{-\frac{2\pi i}{N} k n} = X_k. - - .. class:: m-text m-text-right m-dim m-em - - --- `Discrete Fourier transform § Periodicity `_, Wikipedia - -And now, finally, some inline math. Note the vertical alignment, consistent -line spacing and that nothing gets relayouted during page load: +Now, some inline math --- note the vertical alignment, consistent line spacing +and that nothing gets relayouted during page load: Multiplying :math:`x_n` by a *linear phase* :math:`e^{\frac{2\pi i}{N}n m}` for some integer :math:`m` corresponds to a *circular shift* of the output @@ -191,3 +194,58 @@ line spacing and that nothing gets relayouted during page load: .. class:: m-text m-text-right m-dim m-em --- `Discrete Fourier transform § Shift theorem `_, Wikipedia + +The inline SVG follows surrounding text size, so you can use it easily in more +places than just the main copy: + + .. button-default:: https://tauday.com/ + + The :math:`\tau` manifesto + + they say :math:`\pi` is wrong + +:text-primary:`Everything can be colored` just by putting CSS classes around: + + .. math:: + :class: m-primary m-show-m + + X_{k+N} \ \stackrel{\mathrm{def}}{=} \ \sum_{n=0}^{N-1} x_n e^{-\frac{2\pi i}{N} (k+N) n} = \sum_{n=0}^{N-1} x_n e^{-\frac{2\pi i}{N} k n} \underbrace{e^{-2 \pi i n}}_{1} = \sum_{n=0}^{N-1} x_n e^{-\frac{2\pi i}{N} k n} = X_k. + + .. math:: + :class: m-primary m-hide-m + + \begin{array}{rcl} + X_{k+N} & \ \stackrel{\mathrm{def}}{=} \ & \sum_{n=0}^{N-1} x_n e^{-\frac{2\pi i}{N} (k+N) n} \\ + & = & \sum_{n=0}^{N-1} x_n e^{-\frac{2\pi i}{N} k n} \underbrace{e^{-2 \pi i n}}_{1} \\ + & = & \sum_{n=0}^{N-1} x_n e^{-\frac{2\pi i}{N} k n} = X_k. + \end{array} + + .. class:: m-text m-text-right m-dim m-em + + --- `Discrete Fourier transform § Periodicity `_, Wikipedia + +But it's also possible to color only parts of the equation --- with a color +that matches page theme. + + .. math:: + :class: m-show-s + + {\color{m-primary} L_o (\boldsymbol{x}, \omega_o)} = {\color{m-danger}\int\limits_{\Omega}} {\color{m-warning} f_r(\boldsymbol{x},\omega_i,\omega_o)} {\color{m-success} L_i(\boldsymbol{x},\omega_i)} {\color{m-info} ( \omega_i \cdot \boldsymbol{n})} {\color{m-danger} \operatorname d \omega_i} + + .. math:: + :class: m-hide-s m-text m-small + + {\color{m-primary} L_o (\boldsymbol{x}, \omega_o)} = {\color{m-danger}\int\limits_{\Omega}} {\color{m-warning} f_r(\boldsymbol{x},\omega_i,\omega_o)} {\color{m-success} L_i(\boldsymbol{x},\omega_i)} {\color{m-info} ( \omega_i \cdot \boldsymbol{n})} {\color{m-danger} \operatorname d \omega_i} + + .. class:: m-text-center m-noindent + + :label-primary:`outgoing light` |o| :label-danger:`integral` + |o| :label-warning:`BRDF` |o| :label-success:`incoming light` + |o| :label-info:`normal attenuation` + + .. class:: m-text m-text-right m-dim m-em + + --- `Lighting: The Rendering Equation `_, rorydriscoll.com + +.. combined with https://en.wikipedia.org/wiki/Rendering_equation for the nice + Greek letters diff --git a/doc/css/components.rst b/doc/css/components.rst index 6d740668..8980414d 100644 --- a/doc/css/components.rst +++ b/doc/css/components.rst @@ -979,8 +979,7 @@ into your HTML code. The :html:`` element containing math can be wrapped in :html:`
` to make it centered. Similarly to code blocks, the math block shows a horizontal scrollbar if the content is too wide on narrow screens. `CSS color classes <#colors>`_ can be applied to the -:html:`
`. It's a good practice to include :html:`` and -:html:`<desc>` elements for accessibility reasons. +:html:`<div>`. It's a good practice to include the :html:`<title>` element for accessibility reasons. .. code-figure:: @@ -988,8 +987,7 @@ on narrow screens. `CSS color classes <#colors>`_ can be applied to the <div class="m-math m-success"> <svg> - <title>LaTeX Math - a^2 = b^2 + c^2 + a^2 = b^2 + c^2 ...
@@ -998,8 +996,7 @@ on narrow screens. `CSS color classes <#colors>`_ can be applied to the
- LaTeX Math - a^2 = b^2 + c^2 + a^2 = b^2 + c^2 @@ -1041,8 +1038,7 @@ the ``depth`` value returned on stderr can be taken as a base for the

There is a movement for replacing circle constant - LaTeX Math - 2 \pi + 2 \pi @@ -1052,8 +1048,7 @@ the ``depth`` value returned on stderr can be taken as a base for the with the - LaTeX Math - \tau + \tau @@ -1062,6 +1057,9 @@ the ``depth`` value returned on stderr can be taken as a base for the character.

+The CSS color classes work also on :html:`` and :html:`` elements +inside :html:`` for highlighting parts of formulas. + .. note-success:: Producing SVG manually using command-line tools is no fun. That's why the diff --git a/doc/plugins/math-and-code.rst b/doc/plugins/math-and-code.rst index 7828a3d9..d4c884e2 100644 --- a/doc/plugins/math-and-code.rst +++ b/doc/plugins/math-and-code.rst @@ -97,8 +97,12 @@ and: - Instead of relying on MathML or MathJax, converts input LaTeX math formula to a SVG file, which is then embedded directly to the page. All glyphs are converted to paths. -- Adds a :html:`` and :html:`` containing the original formula - to the generated :html:`` element for accessibility. +- Size is represented using CSS :css:`em` units so the formula follows + surrounding text size. +- Adds a possibility to color the whole formula or parts of it using colors + that follow the current theme. +- Adds a :html:`` containing the original formula to the generated + :html:`` element for accessibility. Put `math blocks <{filename}/css/components.rst#math>`_ into the :rst:`.. math::` directive; if you want to color the equations, add corresponding @@ -148,11 +152,55 @@ want to add additional CSS classes, derive a custom role from it. Quaternion-conjugated dual quaternion is :math-info:`\hat q^* = q_0^* + q_\epsilon^*`, while dual-conjugation gives :math:`\overline{\hat q} = q_0 - \epsilon q_\epsilon`. +The resulting SVG follows font size of surrounding text, so you can use math +even outside of main page copy: + +.. code-figure:: + + .. code:: rst + + .. button-success:: https://tauday.com/ + + The :math:`\tau` manifesto + + they say :math:`\pi` is wrong + + .. button-success:: https://tauday.com/ + + The :math:`\tau` manifesto + + they say :math:`\pi` is wrong + +The ``xcolor`` package is enabled by default together with names matching CSS +color classes. You can use it to highlight different parts of the formula: + +.. code-figure:: + + .. code:: rst + + .. math:: + + \boldsymbol{A} = \begin{pmatrix} + {\color{m-info} s_x} & 0 & 0 & {\color{m-success} t_x} \\ + 0 & {\color{m-info} s_y} & 0 & {\color{m-success} t_y} \\ + 0 & 0 & {\color{m-info} s_z} & {\color{m-success} t_z} \\ + 0 & 0 & 0 & 1 + \end{pmatrix} + + .. math:: + + \boldsymbol{A} = \begin{pmatrix} + {\color{m-info} s_x} & 0 & 0 & {\color{m-success} t_x} \\ + 0 & {\color{m-info} s_y} & 0 & {\color{m-success} t_y} \\ + 0 & 0 & {\color{m-info} s_z} & {\color{m-success} t_z} \\ + 0 & 0 & 0 & 1 + \end{pmatrix} + The :py:`M_MATH_CACHE_FILE` setting (defaulting to ``m.math.cache`` in the site root directory) describes a file used for caching rendered LaTeX math -formulas for speeding up subsequent runs. Old cached output is periodically -pruned and new formulas added to the file. Set it to :py:`None` to disable -caching. +formulas for speeding up subsequent runs. Cached output that's no longer needed +is periodically pruned and new formulas added to the file. Set it to :py:`None` +to disable caching. .. note-info::