Listados de código

Cuando quieres presentar código fuente de forma cuidada, con números de línea y resaltado de sintaxis (palabras clave, comentarios y cadenas en colores distintos), los dos paquetes habituales son listings y minted. El primero no necesita herramientas externas y funciona en cualquier sitio; el segundo llama al motor externo Pygments para un resaltado mucho más preciso. Si solo necesitas reproducir el código exactamente como se escribió, basta la familia verbatim más simple.

Dos enfoques

Hay dos rutas para componer código fuente, basadas en ideas distintas. listings está implementado solo con macros LaTeX y no necesita software adicional: \usepackage{listings} basta tanto en Overleaf como en un entorno de laboratorio que no puedes configurar. minted, en cambio, delega el trabajo en Pygments, un lexer serio escrito en Python, y devuelve el resultado a LaTeX. Como Pygments analiza de verdad cientos de lenguajes, su resaltado es mucho más preciso que el de listings.

Esa diferencia es exactamente el criterio de elección: usa listings cuando quieras sencillez y portabilidad, y minted cuando priorices la calidad del resaltado. Como minted lanza un programa externo, necesita el permiso especial llamado shell escape (tratado abajo) y puede no funcionar en entornos restringidos. Si solo quieres reproducir el código verbatim, sin colores ni números de línea, verbatim o fancyvrb son más ligeros; consulta “Verbatim”.

Fundamentos de listings

Carga primero \usepackage{listings}. Encierra un bloque de código en el entorno lstlisting; incluye un archivo externo completo con \lstinputlisting; e inserta un fragmento corto en el texto con \lstinline. En lugar de repetir opciones en cada uso, lo normal es reunir una vez en el preámbulo la lengua y el aspecto con \lstset{...}.

\usepackage{listings}
\usepackage{xcolor}

\lstset{
  language=Python,                 % 言語 / language
  basicstyle=\ttfamily\small,       % 本文の書体 / base font
  keywordstyle=\color{blue}\bfseries,
  commentstyle=\color{teal}\itshape,
  stringstyle=\color{red!60!black},
  numbers=left,                    % 行番号を左に / line numbers on the left
  numberstyle=\tiny\color{gray},
  frame=single,                    % 枠線 / a single-line frame
  breaklines=true,                 % 長い行を折り返す / wrap long lines
  showstringspaces=false,          % 文字列中の空白を記号化しない
  tabsize=2,
}

\begin{lstlisting}[caption={階乗を計算する}, label=lst:fact]
def factorial(n):
    # 再帰で階乗を求める
    if n <= 1:
        return 1
    return n * factorial(n - 1)
\end{lstlisting}

Estas son las claves principales de \lstset. basicstyle fija la fuente general (\ttfamily\small es lo habitual); keywordstyle, commentstyle y stringstyle dan estilo a palabras clave, comentarios y cadenas. numbers=left coloca números de línea a la izquierda, y numberstyle los formatea. frame=single dibuja un borde, breaklines=true parte líneas largas, y caption= junto con label= convierten el bloque en un “listing” numerado, como una figura o tabla, que puedes referenciar con \ref.

Cada bloque puede sobrescribir opciones dentro de [ ], por ejemplo \begin{lstlisting}[language=C, numbers=none]. Con un archivo externo incluso puedes extraer un rango de líneas: \lstinputlisting[language=Python, firstline=37, lastline=45]{sample.py}. Para incrustar código en el texto, elige un delimitador como con \verb, por ejemplo \lstinline|while (i < n)|.

Límites de listings (UTF-8 y japonés)

El resaltado de listings es una aproximación basada en una lista de palabras clave por lenguaje y reglas simples; no es tan inteligente como un lexer real. La coloración dependiente del contexto, por ejemplo cuando la misma palabra puede ser un tipo o una variable según el lugar, se le da mal, y las asperezas se notan más en lenguajes complejos. Es una limitación del enfoque.

Otra trampa práctica son los caracteres multibyte. listings no asume UTF-8 por defecto, de modo que comentarios japoneses y similares dentro del código pueden salir corruptos o desalineados. Hay dos remedios. Si escribes el código directamente en el cuerpo, le enseñas los caracteres uno por uno con literate=, como en \lstset{... literate={あ}{{あ}}1 ...}; no es práctico si hay muchos. Si incluyes un archivo externo, la solución sencilla es cargar listingsutf8 en lugar de listings (solo funciona con \lstinputlisting).

Fundamentos de minted (Pygments)

Al cargar \usepackage{minted}, los bloques de código se escriben en el entorno minted. La gran diferencia frente a listings es que pasas el nombre del lenguaje como primer argumento: \begin{minted}{python}. También existen el atajo de una línea \mint, el comando en línea \mintinline y \inputminted para archivos externos.

\usepackage{minted}

% ドキュメント全体の配色テーマ / a color theme for the whole document
\usemintedstyle{monokai}

\begin{minted}[linenos, bgcolor=black!90, fontsize=\small]{python}
def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)
\end{minted}

% 単一行 / a single line
\mint{python}|print("Hello!")|

% 本文中に埋め込む / inline in running text
\mintinline{python}{print("Hello!")}

% 外部ファイルを取り込む / include an external file
\inputminted[linenos]{python}{sample.py}

Las opciones van justo después del nombre del entorno, en [ ], con forma key=value. Las comunes son linenos para números de línea; style= para elegir un tema de color de Pygments (monokai, etc.; la galería está en pygments.org/styles); bgcolor= para color de fondo; y fontsize=. Para aplicar un tema a todo el documento usa \usemintedstyle{monokai}; para fijar valores por defecto más amplios usa \setminted{style=monokai, linenos}. Para un lenguaje no soportado por Pygments, o para desactivar el resaltado a propósito, usa text como lenguaje.

El código de \mint y \mintinline se delimita como con \verb: con un par de delimitadores coincidentes (cualquier signo, por ejemplo |...|) o con llaves {...}. Ten en cuenta que \mint no es para uso en línea; solo evita escribir el entorno cuando el código tiene una sola línea. Para integrar código en el texto, usa siempre \mintinline.

Shell escape (la condición de minted)

Como minted lanza un programa externo de Python, debes compilar con shell escape activado, el permiso que permite a LaTeX ejecutar comandos externos. Con pdfLaTeX, pasa la opción -shell-escape.

pdflatex -shell-escape document.tex

También requiere Python 3.8+ y Pygments por debajo. Dicho esto, la situación mejoró con minted versión 3, una reescritura completa publicada desde 2025. Cuando se instala mediante un gestor de paquetes TeX (tlmgr install minted, etc.), toda la parte Python, incluido Pygments, se distribuye dentro del árbol TeX como un ejecutable dedicado latexminted, de modo que no hace falta instalar Pygments aparte. Además, latexminted está diseñado para shell escape restringido: en TeX Live 2024 y posteriores está registrado como ejecutable de confianza, así que puedes compilar sin -shell-escape en absoluto.

Aun así, en TeX Live anterior a 2024 y en MiKTeX sigues necesitando -shell-escape (-enable-write18 en MiKTeX). Como shell escape puede ejecutar comandos externos arbitrarios, no lo uses con documentos de fuentes no confiables. En cambio, en un entorno preconfigurado como Overleaf, o localmente con tu propio código, no hay problema (Overleaf soporta minted de serie). Esta “dependencia externa más shell escape” es el principal compromiso frente al más portable listings.

Cuál elegir

• Quieres cero configuración y seguridad de que funciona en cualquier lugar → listings. En Overleaf o en una máquina bloqueada, \usepackage basta.
• La precisión del resaltado y la cobertura de lenguajes son lo primero → minted. La coloración de Pygments está en otra liga.
• No puedes instalar herramientas externas / no puedes usar shell escape → listings, sin discusión.
• Solo necesitas reproducir código verbatim, sin color → verbatim o fancyvrb bastan (ver “Verbatim”).
• Quieres escribir un algoritmo como pseudocódigo → los paquetes dedicados algorithm2e / algpseudocode (ver “Algorithms”).