Showing LaTeX docstrings at the REPL

General Usage
,
1

LaTeX in docstrings can look very nice in HTML in rendered documentation or IJulia. However, at the REPL, the raw LaTeX is displayed.

Since rendering LaTeX in most terminals is problematic, I’m wondering if anyone has suggestions on how to deal with LaTeX in docstrings? Are there examples of packages which use a lot of LaTeX documentation? Do these package owners assume most users use HTML interfaces? Or for function docs, do people avoid LaTeX?

This came up in the context of https://github.com/JuliaImages/ImageFiltering.jl/pull/54, which adds some nice examples as LaTeX tables, and which look nice when rendered, but really clutter up the REPL docstring display:

help?> padarray
search: padarray

      padarray([T], img, border) --> imgpadded

  Generate a padded image from an array img and a specification border of the boundary conditions and amount of padding to add.

...

     Examples
    ≡≡≡≡≡≡≡≡≡≡

  Each example is based on the input array

\mathbf{A} =
\boxed{
\begin{matrix}
 1  & 2  &  3  &  4 & 5  & 6 \\
 2  & 4  &  6  &  8 & 10 & 12 \\
 3  & 6  &  9  & 12 & 15 & 18 \\
 4  & 8  & 12  & 16 & 20 & 24 \\
 5  & 10 & 15  & 20 & 25 & 30 \\
 6  & 12 & 18  & 24 & 30 & 36
 \end{matrix}}.

...

(Note that this isn’t too bad yet, but the tables that follow are unreadable.)

Cheers,
Kevin

1 Like
2

In the specific case, I wonder if one could just use Julia syntax, eg

[1 2 ... ;
 2 4 ... ;
...]

in a jldoctest.

More generally though, I have run into the same problem a few times: LaTeX is very useful, but it cannot render well in plain text. My current approach is the following: for short equations that can be done using Unicode, I use ``-delimited inline math, more complicated stuff goes into the documentation files and renders well in Documenter.jl; the docstrings just mention it.