Switch or at least support code listings in LaTeX using the listings package instead of minted

[BambOoxX]

Hi, I'm currently trying to build a PDF version of the documentation of one of my packages, and unfortunately, this has been really painful due to minted and pygments. I'm pretty sure there is a very good reason for using this package, but unfortunately, because of the external dependency, I simply cannot use the PDF output.

I was wondering if using listings instead of minted was ever considered ? I know that listings does not officially support julia as a language, but this repo contains a language specification for julia: https://github.com/wg030/jlcode

[mortenpi]

I'm not opposed to using listings instead of minted, but what issues are you actually running into with minted/Pygments?

[BambOoxX]

I've had a lot of trouble with minted finding pygmentize because of PATH conflicts. I know it is related to my specific company setup, nevertheless it's quite cumbersome to debug. And now that it works I get an error in a pygtex file saying.

! Undefined control sequence.
\PYG #1#2->\FV@PYG

My idea is more generally that people that will run minted will require a python install, which is still not everybody (at least on windows), and that this could be solved by purely relying on LaTeX, thus avoiding an additional dependency compared to julia.

[mortenpi]

I guess Docker is also out of the question for you? You could also try Tectonic though, but I am not sure if it handles the Python / pygments installation for you or not.

[BambOoxX]

Yes, unfortunately, both Docker and Tectonic are out of my scope.
Auditing the code, there does not seem to be so many references to minted, so I could try and propose a PR for lsitings, whenever I have some time.
I figuring this would result in an additional opt-in kwarg for LaTexWriter.

[mortenpi]

Yeah, let's make this an opt-in option via a kwarg.

[odow]

I haven't benchmarked, but I think the minted package is one cause of the excessively large compilation times for the JuMP documentation, so I would be in favor of this. At the very least, I should check.

[BambOoxX]

@mortenpi I'm wondering what would be the correct way to configure

Documenter.jl/src/latex/LaTeXWriter.jl

Lines 490 to 519 in 77f0bdd

	function latex(io::Context, node::Node, code::MarkdownAST.CodeBlock)
	language = Documenter.codelang(code.info)
	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.
	language = "text"
	end
	text = IOBuffer(code.code)
	code_code = repr(MIME"text/plain"(), ANSIColoredPrinters.PlainTextPrinter(text))
	escape = '⊻' ∈ code_code
	_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
	_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

with an opt-in option to LaTeX(...).

I've added an option with

struct LaTeX <: Documenter.Writer
    platform::String
    version::String
    tectonic::Union{Cmd,String,Nothing}
    code_listings::String
    function LaTeX(;
            platform = "native",
            version  = get(ENV, "TRAVIS_TAG", ""),
            tectonic = nothing,
            code_listings = "minted")
        code_listings ∈ ("minted", "listings") || throw(ArgumentError("unknown code formatting package: $platform"))
        platform ∈ ("native", "tectonic", "docker", "none") || throw(ArgumentError("unknown platform: $platform"))
        return new(platform, string(version), tectonic, code_listings)
    end
end

but since the latex(...) calls are nested, I do not want to touch the signature too much. Would you have a suggestion ?
Some latex(...) use setting as an option, but I preferred to have you opinion on this first.

Side note, tex is currently detected with

Documenter.jl/src/latex/LaTeXWriter.jl

Line 90 in 77f0bdd

hastex() = (try; success(`latexmk -version`); catch; false; end)

While latexmk may be used by a lot of people, I think detecting a tex distro with that is a bit restrictive, though I guess you impose this due to the platform setting. If you are insterested, I think I can propose an arara-based equivalent compilation chain.

[BambOoxX]

@mortenpi I've started really working on this, and I was wondering what the pdf output should look like. Would you mind sharing it (I can't generate it).