Switch to use {minted} for code output in LaTeXWriter (#1957)

CHANGELOG.md

@@ -12,7 +12,7 @@
   **For upgrading:** The cases where an `@eval` results in a object that is not `nothing` or `::Markdown.MD`, the returned object should be reviewed. In case the resulting object is of some `Markdown` node type (e.g. `Markdown.Paragraph` or `Markdown.Table`), it can simply be wrapped in `Markdown.MD([...])` for block nodes, or `Markdown.MD([Markdown.Paragraph([...])])` for inline nodes. In other cases Documenter was likely not handling the returned object in a correct way, but please open an issue if this change has broken a previously working use case.
 
 * ![Enhancement][badge-enhancement] Admonitions are now styled with color in the LaTeX output. ([#1931][github-1931], [#1932][github-1932], [#1946][github-1946], [#1955][github-1955])
-* ![Enhancement][badge-enhancement] Improved the styling of code blocks in the LaTeXWriter. ([#1933][github-1933], [#1935][github-1935], [#1944][github-1944], [#1956][github-1956])
+* ![Enhancement][badge-enhancement] Improved the styling of code blocks in the LaTeXWriter. ([#1933][github-1933], [#1935][github-1935], [#1936][github-1936], [#1944][github-1944], [#1956][github-1956], [#1957][github-1957])
 * ![Enhancement][badge-enhancement] Automatically resize oversize `tabular` environments from `@example` blocks in LaTeXWriter. ([#1930][github-1930], [#1937][github-1937])
 * ![Enhancement][badge-enhancement] The `ansicolor` keyword to `HTML()` now defaults to true, meaning that executed outputs from `@example`- and `@repl`-blocks are now by default colored (if they emit colored output). ([#1828][github-1828])
 * ![Enhancement][badge-enhancement] Documenter now shows a link to the root of the repository in the top navigation bar. The link is determined automatically from the remote repository, unless overridden or disabled via the `repolink` argument of `HTML`. ([#1254][github-1254])
@@ -1153,12 +1153,14 @@
 [github-1932]: https://github.com/JuliaDocs/Documenter.jl/pull/1932
 [github-1933]: https://github.com/JuliaDocs/Documenter.jl/issues/1933
 [github-1935]: https://github.com/JuliaDocs/Documenter.jl/pull/1935
+[github-1936]: https://github.com/JuliaDocs/Documenter.jl/issues/1936
 [github-1937]: https://github.com/JuliaDocs/Documenter.jl/pull/1937
 [github-1944]: https://github.com/JuliaDocs/Documenter.jl/issues/1944
 [github-1946]: https://github.com/JuliaDocs/Documenter.jl/issues/1946
 [github-1948]: https://github.com/JuliaDocs/Documenter.jl/pull/1948
 [github-1955]: https://github.com/JuliaDocs/Documenter.jl/pull/1955
 [github-1956]: https://github.com/JuliaDocs/Documenter.jl/pull/1956
+[github-1957]: https://github.com/JuliaDocs/Documenter.jl/pull/1957
 <!-- end of issue link definitions -->
 
 [julia-29344]: https://github.com/JuliaLang/julia/issues/29344

assets/latex/documenter.sty

@@ -31,25 +31,13 @@
 %
 
 % listings
-\usepackage{listings, minted}
-
-\lstset{
-    basicstyle = \small\ttfamily,
-    breaklines = true,
-    columns = fullflexible,
-    rulecolor = \color{codeblock-border},
-    frame = single,
-    keepspaces = true,
-    showstringspaces = false,
-    xleftmargin = 3.25pt,
-    xrightmargin = 3.25pt,
-}
-
+\usepackage{minted}
 \setminted{
     breaklines = true,
     fontsize = \small,
     frame = none,
     bgcolor = codeblock-background,
+    rulecolor=codeblock-border,
 }
 %
 

src/Writers/LaTeXWriter.jl

@@ -496,9 +496,7 @@ const LEXER = Set([
 
 function latex(io::Context, node::Node, code::MarkdownAST.CodeBlock)
     language = Utilities.codelang(code.info)
-    if isempty(language)
-        language = "text"
-    elseif language == "julia-repl"
+    if language == "julia-repl"
         language = "jlcon"  # the julia-repl is called "jlcon" in Pygments
     elseif !(language in LEXER) && language != "text/plain"
         # For all others, like ```python or ```markdown, render as text.
@@ -507,32 +505,24 @@ function latex(io::Context, node::Node, code::MarkdownAST.CodeBlock)
     text = IOBuffer(code.code)
     code_code = repr(MIME"text/plain"(), ANSIColoredPrinters.PlainTextPrinter(text))
     escape = '⊻' ∈ code_code
-    if language in LEXER
-        _print(io, "\n\\begin{minted}")
-        if escape
-            _print(io, "[escapeinside=\\#\\%]")
-        end
-        _println(io, "{", language, "}")
-        if escape
-            _print_code_escapes_minted(io, code_code)
-        else
-            _print(io, code_code)
-        end
-        _println(io, "\n\\end{minted}\n")
+    _print(io, "\n\\begin{minted}")
+    if escape
+        _print(io, "[escapeinside=\\#\\%")
+    end
+    if language == "text/plain"
+        _print(io, escape ? "," : "[")
+        # Special-case the formatting of code outputs from Julia.
+        _println(io, "xleftmargin=-\\fboxsep,xrightmargin=-\\fboxsep,bgcolor=white,frame=single]{text}")
     else
-        # The only blocks that use {lstlisting} are `text/plain` renders of
-        # Julia output.
-        @assert language == "text/plain"
-        _print(io, "\n\\begin{lstlisting}")
-        if escape
-            _println(io, "[escapeinside=\\%\\%]")
-            _print_code_escapes_lstlisting(io, code_code)
-        else
-            _println(io)
-            _print(io, code_code)
-        end
-        _println(io, "\n\\end{lstlisting}\n")
+        _println(io, escape ? "]{" : "{", language, "}")
     end
+    if escape
+        _print_code_escapes_minted(io, code_code)
+    else
+        _print(io, code_code)
+    end
+    _println(io, "\n\\end{minted}\n")
+    return
 end
 
 latex(io::Context, node::Node, mcb::Documents.MultiCodeBlock) = latex(io, node, join_multiblock(node))
@@ -560,13 +550,6 @@ function _print_code_escapes_minted(io, s::AbstractString)
                      _print(io, ch)
     end
 end
-function _print_code_escapes_lstlisting(io, s::AbstractString)
-    for ch in s
-        ch === '%' ? _print(io, "%\\%%") :
-        ch === '⊻' ? _print(io, "%\\unicodeveebar%") :
-                     _print(io, ch)
-    end
-end
 
 function latex(io::Context, node::Node, code::MarkdownAST.Code)
     _print(io, "\\texttt{")

test/examples/references/latex_showcase.tex

@@ -761,7 +761,7 @@ \section{Running interactive code}
 
 \begin{minted}{text}
 ```@example
-2 + 3
+typeof(π)
 ```
 \end{minted}
 
@@ -773,13 +773,13 @@ \section{Running interactive code}
 
 
 \begin{minted}{julia}
-2 + 3
+typeof(π)
 \end{minted}
 
 
-\begin{lstlisting}
-5
-\end{lstlisting}
+\begin{minted}[xleftmargin=-\fboxsep,xrightmargin=-\fboxsep,bgcolor=white,frame=single]{text}
+Irrational{:π}
+\end{minted}
 
 
 
@@ -819,9 +819,9 @@ \section{Running interactive code}
 \end{minted}
 
 
-\begin{lstlisting}
+\begin{minted}[xleftmargin=-\fboxsep,xrightmargin=-\fboxsep,bgcolor=white,frame=single]{text}
 Hello World
-\end{lstlisting}
+\end{minted}
 
 
 
@@ -836,9 +836,9 @@ \section{Running interactive code}
 \end{minted}
 
 
-\begin{lstlisting}
+\begin{minted}[xleftmargin=-\fboxsep,xrightmargin=-\fboxsep,bgcolor=white,frame=single]{text}
 42
-\end{lstlisting}
+\end{minted}
 
 
 
@@ -894,9 +894,9 @@ \section{Setup blocks}
 \end{minted}
 
 
-\begin{lstlisting}
+\begin{minted}[xleftmargin=-\fboxsep,xrightmargin=-\fboxsep,bgcolor=white,frame=single]{text}
 6
-\end{lstlisting}
+\end{minted}
 
 
 
@@ -986,11 +986,11 @@ \subsubsection{Raw ANSI code output}
 \end{minted}
 
 
-\begin{lstlisting}
+\begin{minted}[xleftmargin=-\fboxsep,xrightmargin=-\fboxsep,bgcolor=white,frame=single]{text}
     0     1     2     3     4     5     6     7
     8     9    10    11    12    13    14    15
 
-\end{lstlisting}
+\end{minted}
 
 
 

test/examples/src.latex_showcase/showcase.md

@@ -322,14 +322,14 @@ E.g. the following Markdown
 
 ````markdown
 ```@example
-2 + 3
+typeof(π)
 ```
 ````
 
 becomes the following code-output block pair
 
 ```@example
-2 + 3
+typeof(π)
 ```
 
 If the last element can be rendered as `text/latex`: