[Docutils-users] implementing a ``mathmacro`` substitution directive?

[Pierre]

Hello,

I am struggling to write a documentation with a lot of math. It would be
very convenient to implement a ``mathmacro`` substitution directive which
should work like this:

- Definition::

.. |bnabla| mathmacro:: \boldsymbol{\nabla}
.. |vv| mathmacro:: \textbf{v}

- These math macros could be included directly in text as in::

|bnabla| is the nabla operator,

which should produce an inline equation like this
":math:`\boldsymbol{\nabla}` is the nabla operator".

- These macros could also be included in inline equations like this::

This is an inline equation :math:`|vv| = |bnabla|f`,

which should give :math:`\textbf{v} = \boldsymbol{\nabla}f`.

- They could also be included in block equation::

.. math:: |vv| = |bnabla|f

which should gives

.. math:: \textbf{v} = \boldsymbol{\nabla}f.

Would it be possible to do that?

I think it would be a lot nicer to use such mathmacro directive rather that
latex macros since (i) it would leads to nicer code and (ii) the MathJax
sphinx extension does not really supports macro definition.

I'm trying to define a new directive by copying on the replace directive but
I don't know how to redefine the substitution rules (which have to vary
depending on the context, in text, in inline math and in block math). I
don't know neither if rST can work this way, with a directive preprocessing
text that will be used after by math directives.

[Guenter Milde]

Hi Pierre,

Post by Pierre
I am struggling to write a documentation with a lot of math. It would be
very convenient to implement a ``mathmacro`` substitution directive which
.. |bnabla| mathmacro:: \boldsymbol{\nabla}
.. |vv| mathmacro:: \textbf{v}
|bnabla| is the nabla operator,
which should produce an inline equation like this
":math:`\boldsymbol{\nabla}` is the nabla operator".
This is an inline equation :math:`|vv| = |bnabla|f`,
which should give :math:`\textbf{v} = \boldsymbol{\nabla}f`.
.. math:: |vv| = |bnabla|f
which should give
.. math:: \textbf{v} = \boldsymbol{\nabla}f.
Would it be possible to do that?

This would be a very big change, because the markup-language of the
math-directive/role content is LaTeX, the rst-parser sees it as raw text.

Parsing LaTeX for non-latex syntax is tricky,
generally, I don't think it is a good idea to mix two markup languages in one
source-part.

How would you write :math:`|-x| = x` with your planned extension?

Post by Pierre
I think it would be a lot nicer to use such mathmacro directive rather that
latex macros since (i) it would leads to nicer code and (ii) the MathJax
sphinx extension does not really supports macro definition.

Do you know, that you can use literal Unicode characters in your source?
These will be translated to LaTeX macros for LaTeX output. Mathjax also
understands Unicode. May be this suffices for your examples and some other
cases.


Günter