I've been thinking about the differences between learning mark-up languages like LaTeX and learning scripting or programming languages like PHP. I started learning LaTeX by doing four or five hours of reading and working through a bunch of examples in Packt's LaTeX Beginner's Guide (2011), at which point I dived right into creating the document I wanted to work on rather than reading the rest of the book. From there, I just used search engine results to solve my problems. With a mark-up language, this works great. The worst thing that can happen is that you produce an ugly or unreadable document (and you'll know it when it happens). Do this with a scripting language (and people seem particularly inclined to do it with PHP) and you're likely to create a security disaster, a broken website leaking data all over the internet. Chances are you won't know it either, because the code does what you want it to ... it just happens to also leaks data because you never read that chapter on security ...

I'm working on a LaTeX document including some GRUB code (intro a few days ago). I'd still argue that LaTeX is fairly straight-forward, but with its age and popularity it's developed a huge number of packages. And that's mostly a good thing. But there are some non-obvious catches.

UPDATE 2018-08-06: [As shown here, "listings can also do remarkably good colour.]

The package "listings" is old, but standard and works reasonably well for inclusion of computer code into documents. It does basic highlighting, with language keywords bolded. On the other hand, the newer package "minted" does colour syntax highlighting, and better wrapping of text. I'd started with "listings," but decided to switch to "minted." This led to a very entertaining discovery: Tex Live (the standard distribution for TeX and LaTeX) has its own package manager, tlmgr. I'm actually relieved to say that it isn't installed on my system (I already have package managers for the OS, Python, and NeoVim, and quite possibly other things I don't know about - and that's quite enough) because I installed through the OS (Fedora) rather than using the Tex Live installer. So I installed the Fedora package texlive-minted.noarch. Apparently Fedora's package management isn't too good around Tex Live, because when I tried to run pdflatex --shell-escape codetest.tex it replied ! LaTeX Error: File `framed.sty' not found. So I had to install texlive-framed.noarch by hand (something I definitely shouldn't have had to do, it should have been installed as a dependency of texlive-minted).

The --shell-escape parameter to the command is needed because "minted" calls the Python-based Pygments to do the colour syntax highlighting - and calls to external programs require special permission.

Here's a comparison of the two (on a piece of GRUB code, although I admit that both lexers are treating it as "sh" code):

photo: "listings" output first, then "minted"

The "minted" output is definitely more garish, but overall more readable even if it is a bit ugly (partly because it's ugly). And the "listings" output needed some configuration to look even that good, whereas that's "minted" straight up, no configuration at all.

But Tex Live and "minted" had another surprise for me: if you run latex2html codetest.tex, the "listings" source code works fine, and the "minted" source code ... vanishes. I had assumed that the HTML conversion would go okay, as this blog uses Pygments to create code listings in HTML and it's always worked well.

So it would appear I'm switching back to "listings" because I want to be able to generate both PDF and HTML output.

The source code for this exercise is included at the very bottom of this page.

LaTeX Resources:

• ShareLaTeX - they're definitely selling a product, but their examples are the best, most straight-forward and readable on the internet
• https://tex.stackexchange.com/ - yup, StackExchange has a TeX division

The source of codetest.tex (colourized by Pygments! although somewhat botched as the lexer is having trouble with the dollar signs it should ignore because they're inside code blocks):

\documentclass[11pt]{article}
\usepackage[letterpaper, inner=2.5cm, outer=2.5cm, top=2.5cm, bottom=2.5cm]{geometry}
\usepackage{minted}

\usepackage{listings}
\lstset{
    basicstyle=\small,
}

\begin{document}
\title{Code Test - Minted vs Listing}
\author{Giles Orr}
% First created: 2018-07-28 10:20

\maketitle

\begin{lstlisting}[language=bash]
    function cpuinfo {
        # only able to determine: 32/64 bit, and is it PAE
        echo "GRUB's ability to analyse processors is limited, we can only tell you:"
        if cpuid -p; then
            pae_assessment="PAE"
        else
            pae_assessment="NO PAE"
        fi
        if cpuid -l; then
            echo "64-bit processor, $pae_assessment"
        else
            echo "32-bit processor, $pae_assessment"
        fi
    }
\end{lstlisting}

\begin{minted}{sh}
    function cpuinfo {
        # only able to determine: 32/64 bit, and is it PAE
        echo "GRUB's ability to analyse processors is limited, we can only tell you:"
        if cpuid -p; then
            pae_assessment="PAE"
        else
            pae_assessment="NO PAE"
        fi
        if cpuid -l; then
            echo "64-bit processor, $pae_assessment"
        else
            echo "32-bit processor, $pae_assessment"
        fi
    }
\end{minted}

\end{document}