Julia:文档字符串和 LaTeX [英] Julia: docstrings and LaTeX

问题描述

Julia 具有 docstrings 功能，此处记录了

使用三重引号，美元符号消失，但公式打印在深色背景上:

EDIT 跟进 David P. Sanders 使用 Documenter.jl 包的建议.

 使用 Documenter医生"""模块 blabla目标函数为:$max mathbb{E}_0 int_0^{infty} e^{-
ho t} F(x_t) dt$"""模块blabla结尾

提供以下内容:LaTeX 代码似乎可以正确打印，但它没有被解释(ρ 显示为 ho.我遵循了以下建议:

解决方案

将 LaTeX 代码渲染为实际方程式必须由渲染文档字符串的任何软件支持.因此，为什么您在 Juno 中看不到任何渲染方程的简短答案是 Juno 目前不支持 LaTeX 渲染(正如 Matt B. 指出的那样，有一个 未解决的问题).

doc"" 字符串文字/字符串宏可以解决另一个问题. 反斜杠和美元符号通常在字符串文字中具有特殊含义 -- 转义序列和变量插值，分别(例如 被换行符替换, $(variable) 将 variable 的值插入到字符串中).当然，这与普通的 LaTeX 命令和分隔符(例如 frac、$...$)有冲突.因此，要在字符串中实际包含反斜杠和美元符号，您需要使用反斜杠将它们全部转义，例如:

朱莉娅>"$\frac{x}{y}$" |>打印$frac{x}{y}$

不这样做会报错:

朱莉娅>"$frac{x}{y}$" |>打印错误:语法:无效的插值语法:$"

或结果字符串中的无效字符:

朱莉娅>"``e^x``" |>打印``^x``

在编写文档字符串时，必须一直逃避一切当然会很烦人.因此，正如大卫指出的那样，为了解决这个问题，您可以使用 doc 字符串宏/非标准字符串文字.在 doc 文字中，所有标准转义序列都被忽略，因此未转义的 LaTeX 字符串不会导致任何问题:

朱莉娅>文档$frac{x}{y}$"|>打印$$frac{x}{y}$$

注意:doc 也会解析字符串中的 Markdown 并实际返回一个 Base.Markdown.MD 对象，而不是字符串，这就是为什么打印字符串与输入有点不同.

最后，您可以将这些 doc-literals 用作普通的文档字符串，但是您可以自由地使用 LaTeX 语法，而不必担心转义所有内容:

doc"""$frac{x}{y}$"""函数 foo 结束

这也记录在 Documenter 的手册，虽然它实际上并不特定于 Documenter.

双反引号 vs 美元符号. 在 Julia 文档字符串或文档中标记 LaTeX 的首选方法是使用 双反引号 或 ```math 块，如手册​​中所述.支持美元符号以实现向后兼容性.

注意:Documenter 手册和 Julia 中 Markdown 对象的 show 方法应该更新以反映这一点.

Julia has docstrings capabilities, which are documented here https://docs.julialang.org/en/stable/manual/documentation/. I'm under the impression that it has support for LaTeX code, but I'm not sure if the intention is that the LaTeX code should look like code or like an interpretation. In the following, the LaTeX code is garbled somewhat (see rho, for instance) and not interpreted (rho does not look like ρ). Am I doing something wrong?

Is there a way to get LaTeX code look interpreted?

What I mean by interpreted is something like what they do at https://math.stackexchange.com/.

The documentation says that LaTeX code should be wrapped around double back-quotes and that Greek letters should be typed as ρ rather than ho. But that rather defeats the point of being able to include LaTeX code, doesn't it?

Note: Version 0.5.2 run in Juno/Atom console.

"""

Module blabla

The objective function is:
``max mathbb{E}_0 int_0^{infty} e^{-
ho t} F(x_t) dt``

"""
module blabla
end

If I then execute the module and query I get this:

With triple quotes, the dollar signs disappear, but the formula is printed on a dark background:

EDIT Follow-up to David P. Sanders' suggestion to use the Documenter.jl package.

    using Documenter
    doc"""
    Module blabla

    The objective function is:
    $max mathbb{E}_0 int_0^{infty} e^{-
ho t} F(x_t) dt$
    """
    module blabla
    end

Gives the following: the LaTeX code appears to print correctly, but it's not interpreted (ρ is displayed as ho. I followed suggestions in: https://juliadocs.github.io/Documenter.jl/stable/man/latex.html to

解决方案

Rendering LaTeX code as actual equations has to be supported by whichever software renders your docstrings. So, the short answer to why you're not seeing any rendered equations in Juno is that LaTeX rendering is currently not supported in Juno (as Matt B. pointed out, there's an open issue for that).

The doc"" string literal / string macro is there to get around another issue. Backslashes and dollar signs normally have a special meaning in string literals -- escape sequences and variable interpolation, respectively (e.g. gets replaced by a newline character, $(variable) inserts the value of variable into the string). This, of course, clashes with the ordinary LaTeX commands and delimiters (e.g. frac, $...$). So, to actually have backslashes and dollar signs in a string you need to escape them all with backslashes, e.g.:

julia> "$\frac{x}{y}$" |> print
$frac{x}{y}$

Not doing that will either give an error:

julia> "$frac{x}{y}$" |> print
ERROR: syntax: invalid interpolation syntax: "$"

or invalid characters in the resulting strings:

julia> "``e^x``" |> print
``^x``

Having to escape everything all the time would, of course, be annoying when writing docstrings. So, to get around this, as David pointed out out, you can use the doc string macro / non-standard string literal. In a doc literal all standard escape sequences are ignored, so an unescaped LaTeX string doesn't cause any issues:

julia> doc"$frac{x}{y}$" |> print
$$
frac{x}{y}
$$

Note: doc also parses the Markdown in the string and actually returns a Base.Markdown.MD object, not a string, which is why the printed string is a bit different from the input.

Finally, you can then use these doc-literals as normal docstrings, but you can then freely use LaTeX syntax without having to worry about escaping everything:

doc"""
$frac{x}{y}$
"""
function foo end

This is also documented in Documenter's manual, although it is not actually specific to Documenter.

Double backticks vs dollar signs. The preferred way to mark LaTeX in Julia docstrings or documentation is by using double backticks or ```math blocks, as documented in the manual. Dollar signs are supported for backwards compatibility.

Note: Documenter's manual and the show methods for Markdown objects in Julia should be updated to reflect this.

这篇关于Julia:文档字符串和 LaTeX的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！