Problem with inline math for Literate-generated notebook

Tooling Package Management
,
1

I’m using Literate and Documenter to develop documentation for a new package. Everything is going smoothly as far as the generated HTML docs go. The problem is that the inline math isn’t displayed as math in the generated Jupyter notebook. Displayed math is fine, but inline math isn’t processed properly.

Here is a fragment of the tutorial.jl file that is input to Literate:

# ### Steering Choice: Specify Phasing
# Plane wave illumination induces a progressive phase shift from cell to cell of the structure:
# ```math
#  V(\vec{r} + m\vec{s}_1 + n\vec{s}_2) = e^{-j(m\psi_1 + n\psi_2)} V(\vec{r})
# ```
# for all integers ``m`` and ``n``, where ``\vec{s}_1`` and ``\vec{s}_2`` 
# are the *lattice vectors* of the 2D periodic structure, and

The corresponding portion of the generated notebook looks like this:

image

The contents of the markdown notebook cell containing the math is

### Steering Choice: Specify Phasing
Plane wave illumination induces a progressive phase shift from cell to cell of the structure:
$$
 V(\vec{r} + m\vec{s}_1 + n\vec{s}_2) = e^{-j(m\psi_1 + n\psi_2)} V(\vec{r})
$$
for all integers ``m`` and ``n``, where ``\vec{s}_1`` and ``\vec{s}_2``
are the *lattice vectors* of the 2D periodic structure, and
``\psi_1`` and ``\psi_2``
are the incremental phase shifts (a pair of real numbers).  Specify
the phasings in degrees as a named tuple as in either of the following two examples:

so it appears that Literate correctly translated the math fence to double dollar signs but not the double back-quotes to single dollar signs. Looking at the Literate documentation, it appears that I may be able to create a custom post processing filter to do the conversion, but I would expect that capability to be built into Literate.
My call to convert the Literate input to a notebook is the simplest possible:

Literate.notebook("tutorial.jl")

Am I doing something wrong? Any suggestions are very appreciated.

2

My current workaround is to use the following preprocessor:

function notebook_filter(str)
  re = r"(?<!`)``(?!`)"  # Two backquotes not preceded by nor followed by another
  replace(str, re => "\$")
end

Literate.notebook(file, preprocess=notebook_filter)

This does the trick, but I suspect there’s a way using Literate without this kind of hack.

3

I use a similar regex preprocessor. I don’t think there is any other way to do this at the moment. There is an open issue for this: https://github.com/fredrikekre/Literate.jl/issues/116

3 Likes
4

This has been fixed in Literate.jl#190 which is included in Literate version 2.13.0.

3 Likes