Clase de documento y preámbulo

El 1 de junio de 1994, LaTeX partió un comando en dos, y desde entonces todo documento LaTeX empieza igual: una línea \documentclass y después un preámbulo de declaraciones \usepackage. Antes se escribía \documentstyle[12pt,twoside]{article}, metiendo opciones y estilos añadidos entre los mismos corchetes. Separar la clase de documento de los paquetes no fue una cuestión de orden. La clase decide qué es el documento —artículo, informe, libro o juego de diapositivas— y el preámbulo decide qué sabe hacer. Con esa frontera bien trazada, una revista recompone el manuscrito entero cambiando una sola línea; mal trazada, la tarde que ibas a dedicar a escribir se va en perseguir Option clash for package geometry.

Qué decide realmente \documentclass

\documentclass[options]{class} es el único comando que debe ir primero en un documento; lo único que puede precederlo es un comentario que empiece por %. Entre llaves va el nombre de la clase y entre corchetes las opciones, y ese nombre entre llaves apunta a un archivo real. Escribir article carga article.cls, unos cientos de líneas de definiciones que no contienen más que reglas. Un encabezado \section, por ejemplo, se compone en \Large\bfseries con 3.5ex de espacio arriba y 2.3ex abajo; esos tres valores están escritos literalmente en article.cls. De tu texto no hay ahí ni un solo carácter.

Ese reparto de tareas no es casual. A principios de los años ochenta, Leslie Lamport empezaba a escribir un libro, encontró insuficiente el paquete de macros que circulaba entonces y pensó que, con algo más de esfuerzo, las macros que necesitaba podrían servir también a otras personas. En una entrevista de enero de 2000 para los DMV-Mitteilungen describe eso como el origen de LaTeX. Una clase es, por tanto, la separación entre estructura y apariencia convertida en un archivo. En el cuerpo escribes \section{Introduction} —el significado y nada más— y componerlo grande y en negrita, numerarlo y dejar espacio encima es tarea de la clase. Por eso mismo las sociedades científicas y las editoriales distribuyen las suyas: amsart, IEEEtran, elsarticle, revtex4-2 y acmart existen de verdad y algunas normas de envío las exigen. El propio Lamport defendió la idea a finales de los ochenta, proponiendo a la ACM que crease estilos de documento estándar para TeX/LaTeX, troff y Scribe para agilizar los envíos electrónicos; un editor de la ACM lo rechazó.

% Only the first line changes; the body stays as it is.
\documentclass[11pt,a4paper]{article}  % top level heading is \section
% \documentclass[11pt,a4paper]{book}   % \chapter becomes available

\begin{document}
\section{Introduction}
The source carries the structure; the class supplies the appearance.
\end{document}

article, report y book: qué cambia de verdad

En la práctica la diferencia se reduce a dos cosas: si hay capítulos y si se presupone impresión a doble cara. article.cls no define ningún \chapter, de modo que \section es su nivel superior; report.cls y book.cls sí lo definen. Los valores predeterminados están escritos en la línea \ExecuteOptions de cada archivo de clase: article usa letterpaper,10pt,oneside,onecolumn,final, report añade openany y solo book cambia a twoside y openright. La trampa es el papel: las tres presuponen letterpaper, así que si quieres A4 tienes que pedir a4paper tú mismo. El título también cambia: en article continúa en lo alto de la primera página, mientras que report y book le dan una página propia.

book incorpora un mecanismo más que conviene conocer: \frontmatter / \mainmatter / \backmatter, que implementan las convenciones del libro impreso en poco más de una línea cada uno. \frontmatter llama a \pagenumbering{roman}, de modo que el prefacio y el índice llevan números romanos en minúscula (i, ii, iii…) y los capítulos quedan sin numerar. \mainmatter llama a \pagenumbering{arabic}, reinicia la cuenta en 1 y vuelve a activar la numeración de capítulos. \backmatter mantiene la paginación arábiga pero elimina de nuevo los números de capítulo, para que el índice analítico no salga como «Capítulo 12 Índice». Todo libro cuyo prefacio va en i, ii, iii y cuyo texto empieza otra vez en 1 es consecuencia de esas tres líneas.

Cuando las cuatro clases estándar no bastan, CTAN tiene una para casi cualquier propósito. Para una charla, beamer es la opción por defecto: un entorno frame equivale a una diapositiva, con revelados por pasos (overlays) y temas incluidos. Si la tipografía predeterminada de las clases estándar parece anticuada, scrartcl / scrreprt / scrbook de KOMA-Script se corresponden con article / report / book y ofrecen una interfaz mucho más rica para afinar detalles. En composición japonesa las opciones son jsarticle / jsbook (las jsclasses, mantenidas por Haruhiko Okumura y el equipo texjporg) sobre pLaTeX / upLaTeX, sus equivalentes de LuaTeX-ja ltjsarticle / ltjsbook sobre LuaLaTeX, y jlreq, basada en los Requirements for Japanese Text Layout (JLReq), que detecta el motor automáticamente y cambia a un comportamiento tipo report o book con las opciones report y book. En todos los casos la primera pregunta es la misma: ¿encaja la clase con el motor que compila?

Qué significan las opciones de \documentclass

Las opciones son interruptores separados por comas dentro de los corchetes que se aplican a todo el documento, como en \documentclass[11pt,a4paper,twoside]{article}. El orden es indiferente y, si se dan dos opciones de la misma familia (oneside y twoside, por ejemplo), gana la última. La tabla siguiente recoge las que se usan de verdad, pero lo que conviene memorizar son los valores por defecto: texto a 10pt, papel letterpaper, composición onecolumn. Si piensas imprimir en A4, a4paper hay que escribirlo cada vez.

Hay aquí un mecanismo con el que todo el mundo tropieza al menos una vez. Las opciones escritas en \documentclass no pertenecen solo a la clase: se entregan a cada paquete cargado después como opciones globales. En la terminología de clsguide, lo que se da directamente a \usepackage[...] es una opción local y lo que se da a \documentclass[...] es una opción global, y cada paquete toma de ambas fuentes los nombres que reconoce. Así, \documentclass[twocolumn]{article} pone en silencio a dos columnas todos los paquetes que entienden esa opción. Ese mismo mecanismo es además el remedio para ! LaTeX Error: Option clash for package geometry., que aparece cuando un paquete se carga dos veces con opciones distintas, casi siempre porque una clase o plantilla ya lo había cargado. El propio LaTeX aconseja en el registro subir esa opción a la declaración \documentclass, porque una opción global no puede chocar con una segunda carga.

Qué va en el preámbulo y qué va en el cuerpo

El preámbulo va desde la línea siguiente a \documentclass hasta justo antes de \begin{document}, y solo puede contener declaraciones: ni un carácter de texto corriente. Una frase normal ahí detiene la compilación con ! LaTeX Error: Missing \begin{document}. El nombre despista; lo que significa es «llegó algo imprimible antes de que empezara el cuerpo». La misma línea aparece cuando un comentario % del preámbulo queda sin cerrar o cuando se cuela un espacio duro o de ancho completo. El caso simétrico es llamar a \usepackage dentro del cuerpo, que da ! LaTeX Error: Can be used only in preamble.: todos los paquetes deben estar presentes antes de componer la primera página.

• Carga de paquetes — \usepackage[options]{package}. Se pueden agrupar como \usepackage{amsmath,amssymb}, pero esa forma no admite opciones.
• Metadatos de título — \title{...}, \author{...}, \date{...}. Quien realmente los compone es \maketitle en el cuerpo; por convención las tres declaraciones viven en el preámbulo.
• Comandos y entornos propios — \newcommand, \renewcommand, \newenvironment, para construcciones usadas en todo el documento.
• Longitudes y contadores — \setlength{\parindent}{0pt}, \setcounter{tocdepth}{2} y otros valores de alcance global.
• Estilo de página y configuración de paquetes — \pagestyle{headings}, \hypersetup{...}, \graphicspath{{figures/}}: los ajustes posteriores a la carga.
• Lo que no debe ir ahí — encabezados, párrafos, figuras, tablas; todo lo que aparece en la salida va después de \begin{document}.

¿En qué orden hay que cargar los paquetes?

A la mayoría de los paquetes el orden les da igual, pero las excepciones merecen memorizarse. La más conocida es hyperref, cuyo manual dice sin rodeos que debe ir el último de los paquetes que cargues. La razón es descarnada: el trabajo de hyperref consiste en redefinir un gran número de comandos de LaTeX, así que cargarlo pronto permite que un paquete posterior sobrescriba esas redefiniciones y rompa en silencio los enlaces y los marcadores del PDF. El manual acompaña ese consejo con una nota al pie: se ha empezado a reducir el número de redefiniciones y con ello la dependencia del orden de carga. Es, por tanto, una solución provisional y no una ley permanente.

Y ese «último» tiene una excepción célebre: cleveref debe cargarse después de hyperref. cleveref construye sus comandos de referencia detectando lo que hyperref ha definido, así que el orden inverso sencillamente no funciona. Si además usas varioref, el orden que prescribe su manual es varioref → hyperref → cleveref. Lo pérfido de esta trampa es que falla en silencio: el manual de cleveref advierte de que, con el orden equivocado, las referencias cruzadas apuntarán a algo completamente distinto sin ningún aviso en la salida ni en el registro. Si alguna vez los números de referencia salieron misteriosamente desplazados en uno, empieza por revisar el orden de esas tres líneas del preámbulo.

\documentclass[11pt,a4paper]{article}

% 1. encoding and fonts
\usepackage[T1]{fontenc}
% 2. language
\usepackage[english]{babel}
% 3. page geometry
\usepackage[margin=25mm]{geometry}
% 4. mathematics
\usepackage{amsmath,amssymb}
% 5. graphics and colour
\usepackage{graphicx}
\usepackage{xcolor}
% 6. hyperref near the end: it redefines many commands
\usepackage{hyperref}
% 7. cleveref is the exception, it must come after hyperref
\usepackage{cleveref}

% document-wide settings and definitions
\newcommand{\R}{\mathbb{R}}
\setlength{\parindent}{0pt}
\title{A Short Note}
\author{Ada Lovelace}
\date{\today}

\begin{document}
\maketitle

\section{Setup}\label{sec:setup}
For all $x \in \R$ we have $x^2 \ge 0$.

\section{Result}
The argument of \cref{sec:setup} applies unchanged.
\end{document}

Mantener el preámbulo más pequeño que el documento

En esa misma entrevista se pidió a Lamport que nombrara tres errores de LaTeX que la gente debería dejar de cometer. Sus tres respuestas fueron la misma: preocuparse demasiado por el formato y demasiado poco por el contenido. La repetición era el chiste. El preámbulo es justo donde está puesta esa trampa: retoques visuales de un solo uso, paquetes probados una vez y nunca retirados, abreviaturas empleadas dos veces, todo acumulándose. El coste no es la fealdad, sino que el día en que aparezca un error el culpable estará escondido en alguna de esas decenas de líneas. Conserva solo lo que vale para todo el documento: clase, idioma y fuentes, matemáticas, figuras y tablas, enlaces. Reserva \newcommand para construcciones que de verdad se repitieron mientras escribías. Y cuando haya una plantilla de envío de por medio, respeta primero su preámbulo: sustituir un paquete que la clase da por supuesto suele volver en forma de Option clash, o en una forma bastante menos legible.

• Un informe nuevo — empieza con article. Tocar el diseño de página puede esperar a que el texto esté más o menos escrito.
• Una tesis — usa tal cual la clase que distribuye la universidad y deja los ajustes de márgenes o encabezados para el final; no tocar el preámbulo de la plantilla es el camino más corto.
• Un envío a revista — pon primero la clase de la editorial (elsarticle, IEEEtran, revtex4-2…) y añade encima solo lo mínimo de preámbulo propio.
• Imprimir en A4 — las clases estándar presuponen letterpaper, así que indica explícitamente \documentclass[a4paper]{...}; con geometry cargado también puede fijarse ahí.
• Cuando aparece un error — sospecha primero del \usepackage o \newcommand añadido en último lugar; si no basta, corta el preámbulo por la mitad y busca por bisección.