What’s the recommended way to include a multi-character function or argument name in the LaTeX/math part of a docstring? \text, \mathrm, or something else?
MWE:
@doc """
Test if ``x \\le \\text{abstol}``.
"""
is_done(x, abstol) = abs(x) ≤ abstol
The LaTeX Companion states that \mathit is appropriate for such “full-word variable names” and the like, whereas \mathrm is good for operators and \text for “normal text” inside mathematical constructs. If you generate a PDF with Documenter you can see whether this advice fits your taste.
1 Like
I am not sure what the recommended way is, but I read your string as: The first part is math, the second (the abstol) is code, so I would write it like exactly that mix, e.g.
@doc """
Test if ``x ≤ `` `abstol`.
"""
(I think it should even work without the space between math and code)
If you feel that this is too much of a mix, one could also maybe write
@doc """
Test if ``x ≤ ε_{\\mathrm{abs}} ``, where ``ε_{\\mathrm{abs}}`` is the `abstol` keyword.
"""
though that is a bit longer, it makes the split between math and code names a bit clearer.
What I find a bit hard is to find a good balance between “renders nice in docs” and “is readable on REPL”, so I use UTF8 characters for example.
It would be great if REPL printing could just elide \text etc, eg within the entry point Markdown.plain(::IO, ::LaTeX), but I guess that would require parsing LaTeX, at least to a certain extent. Cf
1 Like
That would indeed be great and resolve most of balancing I currently try. Thanks for linking that Issue!
1 Like