朱莉娅:docstrings和LaTeX [英] Julia: docstrings and LaTeX

问题描述

Julia具有docstrings功能，在此处记录 https://docs .julialang.org/en/stable/manual/documentation/.我的印象是它支持LaTeX代码，但是我不确定其意图是让LaTeX代码看起来像代码还是解释.在下文中，LaTeX代码有些乱码(例如，参见rho)，并且没有解释(rho看起来不像ρ).难道我做错了什么?

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?

是否有一种方法可以解释LaTeX代码的外观?

Is there a way to get LaTeX code look interpreted?

我的解释是类似于他们在 https://math.stackexchange.com/上所做的事情.

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

文档说，LaTeX代码应该用双反引号引起来，并且希腊字母应键入为ρ而不是\rho.但是，这违反了能够包含LaTeX代码的观点，不是吗?

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

注意:0.5.2版在Juno/Atom控制台中运行.

Note: Version 0.5.2 run in Juno/Atom console.

"""

Module blabla

The objective function is:
``\max \mathbb{E}_0 \int_0^{\infty} e^{-\rho 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:

编辑，是David P. Sanders关于使用Documenter.jl软件包的建议的后续措施.

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^{-\rho t} F(x_t) dt$
    """
    module blabla
    end

提供以下信息:LaTeX代码似乎可以正确打印，但是无法解释(ρ显示为\rho.我遵循以下建议:

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

推荐答案

无论哪种软件呈现您的文档字符串，都必须将LaTeX代码呈现为实际方程式.因此，为什么您在Juno中看不到任何渲染方程式的简短答案是Juno当前不支持LaTeX渲染(正如Matt B.指出的那样，有一个

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).

doc""字符串文字/字符串宏可以解决另一个问题.反斜杠和美元符号通常在字符串文字中具有特殊含义-

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. \n 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}$

不这样做会产生错误:

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

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

or invalid characters in the resulting strings:

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

编写文档字符串时，必须始终逃避所有麻烦.因此，要解决此问题，正如David指出的那样，可以使用doc字符串宏/非标准字符串文字.在doc文字中，所有标准转义序列都将被忽略，因此未转义的LaTeX字符串不会引起任何问题:

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}
$$

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

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.

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

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.

双引号与美元符号.在Julia文档字符串或文档中标记LaTeX的首选方法是使用

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.

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

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

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