feature: Inline Rendering for Single-Line LaTeX Equations

[LexeyKhom]

Hello!

I'd like to propose an enhancement: rendering single-line LaTeX equations
directly inline, rather than using virtual lines above the text. While the
current virtual line approach is functional, it often consumes significant
vertical space and can be distracting, especially for short equations.

My suggestion is to integrate these equations directly into the text flow,
which would significantly improve readability and document compactness.

Here are visual examples demonstrating the difference:

Before:

After:

I've implemented a prototype to demonstrate this idea and serve as a starting
point:

---@param root TSNode
---@return render.md.Mark[]
function Handler:run(root)
    if self.context:skip(self.config) then
        return {}
    end
    if vim.fn.executable(self.config.converter) ~= 1 then
        log.add('debug', 'ConverterNotFound', self.config.converter)
        return {}
    end

    local node = Node.new(self.context.buf, root)
    log.node('latex', node)

    local indent = self:indent(node.start_row, node.start_col)
    local lines = iter.list.map(self:expressions(node), function(expression)
        local line = vim.list_extend({}, indent) ---@type render.md.mark.Line
        line[#line + 1] = { expression, self.config.highlight }
        return line
    end)

    local marks = Marks.new(self.context, true)

    if #lines == 1 then
        marks:add(true, node.start_row, node.start_col, {
            end_row = node.end_row,
            end_col = node.end_col,
            virt_text = lines[1],
            virt_text_pos = 'inline',
            conceal = '',
        })
        return marks:get()
    end

    local above = self.config.position == 'above'
    local row = above and node.start_row or node.end_row

    marks:add('virtual_lines', row, 0, {
        virt_lines = lines,
        virt_lines_above = above,
    })
    return marks:get()
end

---@private
---@param node render.md.Node
---@return string[]
function Handler:expressions(node)
    local lines = str.split(self:convert(node.text), '\n', true)

    if #lines == 1 then
        return lines
    end

    local col = node.start_col
    local _, first = node:line('first', 0)
    local prefix = str.pad(first and str.width(first:sub(1, col)) or col)
    local width = vim.fn.max(iter.list.map(lines, str.width))
    local result = {} ---@type string[]

    for _ = 1, self.config.top_pad do
        result[#result + 1] = ''
    end

    for _, line in ipairs(lines) do
        local suffix = str.pad(width - str.width(line))
        result[#result + 1] = prefix .. line .. suffix
    end

    for _ = 1, self.config.bottom_pad do
        result[#result + 1] = ''
    end

    return result
end

Further Observations and Challenges (regarding multi-line equations):

I also explored applying a similar inline approach to multi-line LaTeX
equations but encountered several challenges:

• Challenge: Detecting End of File/Last Formula: While the line break logic
  (if cur_start_row ~= node.start_row) worked, I couldn't find a reliable
  mechanism to detect the very last formula in a file. The absence of a clear
  end-of-file indicator (e.g., nil) or a subscribable event prevented me from
  correctly rendering the final group of equations.
• Usability for Multi-line Equations: Furthermore, for multi-line
  equations, strict inline rendering isn't always ideal. Ideally, it would be
  great to have full rendering visible during editing (e.g., displaying the
  equation as a virtual line when the cursor hovers over it). However, I
  haven't found a simple and performant solution for such interactive
  rendering.

I'd appreciate your thoughts on this proposal and any insights or suggestions
regarding the multi-line challenges, especially detecting the end of a formula
block or file.

P.S. I used AI to help formulate this issue, aiming for maximum clarity and
precision, as my English proficiency sometimes hinders expressing nuanced
ideas. I hope this is acceptable.

[LexeyKhom]

To better illustrate what I meant regarding multi-line equations in the main Issue description, here's a visualization of the ideal, yet challenging to implement, scenario:

Ideal Multi-line Equation Presentation (what I aimed for):

As you can see, such a presentation would be highly convenient for reading. However, as I mentioned in the "Further Observations and Challenges" section (specifically, the "Usability for Multi-line Equations" point), this very approach presents the difficulties I couldn't resolve simply and efficiently.

The LaTeX text used for this test:

# Latex test

1. Looks perfect $A = \begin{pmatrix} a & b \\ & \\c&d \end{pmatrix}$.

2. $\begin{pmatrix}a\\c\end{pmatrix} and \begin{pmatrix}b\\d\end{pmatrix}$
   same.

3. $\begin{pmatrix}a\\c\end{pmatrix}$ and $\begin{pmatrix}b\\d\end{pmatrix}$ If
   two or more multi-line formulas in one line, then this comes out. Need to
   combine.

4. Long formulas for two or more lines give the following problem:
   $Δₓ=\begin{vmatrix}c₁&b₁\\& \\c₂& b₂\end{vmatrix}=c₁b₂-c₂b₁,
\ Δy=\begin{vmatrix}a₁&c₁\\& \\a₂& c₂\end{vmatrix}=a₁c₂-a₂c₁
\ - auxiliary determinants of the system\\$

5. But if we use `$$`, then everything is fine (well, or almost):
   $$
    Δₓ=\begin{vmatrix}c₁&b₁\\& \\c₂& b₂\end{vmatrix}=c₁b₂-c₂b₁,
   \ Δy=\begin{vmatrix}a₁&c₁\\& \\a₂& c₂\end{vmatrix}=a₁c₂-a₂c₁
   \- auxiliary determinants of the system\\
   $$

The rough prototype code used for this experiment:

---@param root TSNode
---@return render.md.Mark[]
function Handler:run(root)
    if self.context:skip(self.config) then
        return {}
    end
    if vim.fn.executable(self.config.converter) ~= 1 then
        log.add('debug', 'ConverterNotFound', self.config.converter)
        return {}
    end

    local node = Node.new(self.context.buf, root)
    log.node('latex', node)

    local indent = self:indent(node.start_row, node.start_col)
    local lines = iter.list.map(self:expressions(node), function(expression)
        local line = vim.list_extend({}, indent) ---@type render.md.mark.Line
        line[#line + 1] = { expression, self.config.highlight }
        return line
    end)

    local marks = Marks.new(self.context, true)

    if #lines == 1 then
        marks:add(true, node.start_row, node.start_col, {
            end_row = node.end_row,
            end_col = node.end_col,
            virt_text = lines[1],
            virt_text_pos = 'inline',
            conceal = '',
        })
        return marks:get()
    end

    local above = self.config.position == 'above'
    local row = above and node.start_row or node.end_row

    local top_lines = vim.fn.slice(lines, 0, math.floor(#lines / 2))
    local center_line =
        vim.fn.slice(lines, math.floor(#lines / 2), math.floor(#lines / 2 + 1))
    local bottom_lines = vim.fn.slice(lines, math.floor(#lines / 2 + 1), #lines)

    marks:add(true, node.start_row, node.start_col, {
        end_row = node.end_row,
        end_col = node.end_col,
        virt_text = center_line[1],
        virt_text_pos = 'inline',
        conceal = '',
    })

    marks:add('virtual_lines', row, 0, {
        virt_lines = top_lines,
        virt_lines_above = true,
    })

    marks:add('virtual_lines', row, 0, {
        virt_lines = bottom_lines,
        virt_lines_above = false,
    })
    return marks:get()
end

---@private
---@param node render.md.Node
---@return string[]
function Handler:expressions(node)
    local lines = str.split(self:convert(node.text), '\n', true)

    if #lines == 1 then
        return lines
    end

    local col = node.start_col
    local _, first = node:line('first', 0)
    local prefix = str.pad(first and str.width(first:sub(1, col)) or col)
    local width = vim.fn.max(iter.list.map(lines, str.width))
    local result = {} ---@type string[]
    -- for _ = 1, self.config.top_pad do
    --     result[#result + 1] = ''
    -- end

    for i, line in ipairs(lines) do
        if i == math.floor(#lines / 2 + 1) then
            result[#result + 1] = line
        else
            local suffix = str.pad(width - str.width(line))
            result[#result + 1] = prefix .. line .. suffix
        end
    end

    -- for _ = 1, self.config.bottom_pad do
    --     result[#result + 1] = ''
    -- end

    return result
end

[LexeyKhom]

Minimal config (top_pad and bottom_pad must be 0 for this prototype):

latex = {
      converter = "utftex",
      top_pad = 0,
      bottom_pad = 0,
    }

[LexeyKhom]

I worked with this configuration for a couple of hours and found another bug: incorrect offset (suffix) of the formula if there are hidden special characters before the formula, for example:

Otherwise it looks great. The readability of latex documents improves several times. And all the above disadvantages can be bypassed by merging several inline formulas into one or moving them to a new line (which is a crutch, but still better than before, when I avoided $$ for all simple formulas and got by with ``)

[MeanderingProgrammer]

Thanks for all the hard work!

P.S. I used AI to help formulate this issue, aiming for maximum clarity and
precision, as my English proficiency sometimes hinders expressing nuanced
ideas. I hope this is acceptable.

That makes sense, and is not a problem at all! Thanks for letting me know.

As you can see, such a presentation would be highly convenient for reading. However, as I mentioned in the "Further Observations and Challenges" section (specifically, the "Usability for Multi-line Equations" point), this very approach presents the difficulties I couldn't resolve simply and efficiently.

Unfortunately this is just a complicated problem, which is why inline rendering doesn't exist. I initially implemented latex rendering by doing an overlay but ran into far too many edge cases and had to change it to something simpler.

I think one thing I could do fairly easily is inline render single line results (which I saw in part of your code), if that would be helpful. But it seems like most things people actually use end up being multiple lines anyway, so unsure if that's useful enough. It seems like utftex really likes using a lot of lines, but the simple approach works fairly well with the output of latex2text, though definitely less stylish.

The problem of trying to get virtual lines to align with physical lines perfectly accounting for concealing and inlining is really difficult to solve. You need to account for all the concealed text that exists as part of systems like treesitter, as well as any text shifts caused by this plugin as well. For instance, if you have 2 formulas on the same line you would need the corresponding virtual line above the text to account for any changes in width caused by the inline / conceal center line of the first formula.

Making everything virtual means we don't have to worry about alignment, but at the cost of a worse output.

If you find a decent solution that you like I'm more than happy to take a look, or provide some option to let you render it however you want on your end. Or if you have any other approaches that you'd like me to think about. As is getting things to align just ends up being too problematic.

any insights or suggestions
regarding the multi-line challenges

There are actually some existing plugins that you might like to combine with this one to improve the overall rendering. I list a few options in this doc: https://github.com/MeanderingProgrammer/render-markdown.nvim/blob/main/doc/limitations.md#latex-formula-positioning

Essentially you'd disable latex support in this plugin, and use nabla.nvim or latex.nvim to handle inlining things nicely for you.

[MeanderingProgrammer]

Added support for inlining single line outputs here: b7dad79

Thanks for looking into this! Even though this solution doesn't cover all the cases, I think it's a noticeable improvement.