YuShenLiu06/yushen-skills — LaTeX PDF 专业排版

latex-pdf — Guía Profesional de Composición Tipográfica con LaTeX PDF

El objetivo no es "que compile", sino que el lector al tomar el PDF sienta que es profesional. La entrega se basa en el contenido y las páginas reales; la compilación exitosa solo prueba que la compilación terminó, no sustituye la verificación visual.

Índice

1. Concepto Central
2. Selección del Motor
3. Estrategia de Compilación
4. Principios de Legibilidad en la Composición
5. Flujo de Trabajo
6. Guía Rápida de Problemas

---

Concepto Central

La composición tipográfica sigue dos objetivos de verificación y no depende de otra Skill para funcionar.

① La composición sirve a la lectura — cada decisión tipográfica responde a "¿esto ayuda al lector a entender mejor?". Si eliminar un ajuste no cambia la experiencia de lectura, entonces no necesita existir.

② La moderación es profesional — elimina todos los elementos visuales que no transmiten información. Líneas decorativas, sombras, recuadros de color... la mayoría deberían eliminarse. La composición profesional "parece sin esfuerzo", mientras que la composición amateur a menudo "parece muy esforzada pero desordenada".

Para una asignación detallada de los principios de legibilidad, consulta principios-de-legibilidad.

---

Selección del Motor

Elegir el motor incorrecto es el error más común, especialmente usar pdfLaTeX para contenido en chino.

¿Tiene chino/japonés/coreano?
├─ Sí → xelatex (con paquete ctex)
│        (lualatex también sirve, pero compila más lento)
└─ No → ¿Necesita fuentes del sistema?
         ├─ Sí → xelatex o lualatex (con fontspec)
         └─ No → pdflatex (más rápido, más compatible)

Para documentos CJK nuevos, prioriza XeLaTeX o LuaLaTeX, y verifica el soporte real de fuentes. Las plantillas pdfLaTeX/CJK existentes que funcionan no deben reemplazarse sin motivo; fandol no es adecuado para la ruta pdfLaTeX normal.

Motor	Ventajas	Desventajas	Casos de Uso
pdflatex	Más rápido, más estable, ecosistema más amplio	No soporta Unicode nativo, no puede usar fuentes del sistema	Documentos solo en inglés
xelatex	Unicode nativo, fuentes del sistema, amigable con CJK	Más lento	Opción predeterminada para documentos en chino
lualatex	El manejo de fuentes más potente, puede incrustar Lua	El más lento	Necesita funciones tipográficas avanzadas

---

Estrategia de Compilación

Primero revisa el origen y los límites de ejecución

Antes de compilar, revisa estáticamente el .tex, los .sty/.cls incluidos, la configuración de compilación y las rutas de archivos adjuntos; presta atención a la capacidad de ejecución de lectura/escritura de archivos, comandos externos y Lua. La revisión estática no equivale a prueba de seguridad. Para proyectos no confiables, utiliza un entorno aislado sin archivos privados, sin red, y con límites de escritura, tiempo de ejecución y recursos; si no hay un aislamiento adecuado, detén la compilación e informa, no lo ejecutes en un entorno personal.

Deshabilita shell-escape por defecto, no lo actives automáticamente para minted o externalización de gráficos. Al ejecutar latexmk, usa -norc para evitar cargar automáticamente rc del sistema, usuario o proyecto; revisa por separado otros scripts de compilación y programas auxiliares externos. La instalación, descarga de paquetes o modificación del entorno debe realizarse dentro de la autorización existente; si no está cubierto, obtén aprobación primero.

Reutiliza la cadena de compilación adecuada

Para proyectos existentes, mantén el método de compilación que funcione; cuando se necesiten múltiples pasadas y manejo automático de referencias bibliográficas, se puede usar latexmk. Los siguientes ejemplos son solo para entradas ya revisadas, ejecutándose en el directorio de trabajo permitido:

# Documento xelatex (predeterminado para chino)
latexmk -norc -xelatex -latexoption=-no-shell-escape -interaction=nonstopmode -halt-on-error main.tex

# Documento pdflatex
latexmk -norc -pdf -latexoption=-no-shell-escape -interaction=nonstopmode -halt-on-error main.tex

# Limpiar archivos auxiliares
latexmk -norc -c

Explicación de parámetros:

• -interaction=nonstopmode: no se detiene esperando entrada en caso de error (esencial para entornos de script)
• -halt-on-error: se detiene en el primer error, facilitando la localización del problema

Biber (referencias bibliográficas)

Cuando se necesiten referencias, verifica que latexmk llame a biber/BibTeX y los archivos de entrada según lo planeado; solo ejecuta después de la autorización; no trates la detección automática como permiso adicional de ejecución.

---

Principios de Legibilidad en la Composición

A continuación se presenta un resumen de los principios centrales; la asignación detallada y ejemplos de código se encuentran en principios-de-legibilidad.

Geometría de Página

Objetivo: 50-75 caracteres por línea (66 es el valor ideal, el valor predeterminado de TeX es exactamente ese).

\usepackage{geometry}
\geometry{a4paper, margin=2.5cm}
% Cada carácter chino tiene aproximadamente el doble de ancho que uno inglés; 35 caracteres chinos/línea ≈ 70 caracteres ingleses/línea

Tablas

Para tablas de datos regulares, prioriza el estilo sin líneas verticales de booktabs; si el usuario, la revista o la plantilla institucional tienen otros requisitos, mantén su formato:

\usepackage{booktabs}
\begin{tabular}{lrr}
    \toprule
    Indicador & 2024 & 2025 \\
    \midrule
    Ingresos & 120 & 150 \\
    \bottomrule
\end{tabular}

El diseño de booktabs presupone que no hay líneas verticales; si las hay, el espaciado de las líneas horizontales se rompe. Esto no es un error, es una característica.

Sistema de Espaciado

Elige una de las dos opciones para separar párrafos, no las mezcles:

% Opción A: sangría de primera línea (documentos académicos, predeterminado de ctex)
\setlength{\parindent}{2em}

% Opción B: espacio entre párrafos (documentos técnicos, informes)
\setlength{\parindent}{0pt}
\setlength{\parskip}{0.5\baselineskip}

Fuentes

Usa serifa para el texto principal (cómoda para leer) y monoespaciada para el código. Con xelatex/lualatex, usa fontspec para configurar fuentes del sistema:

\usepackage{fontspec}
\setmainfont{TeX Gyre Termes}[Ligatures=TeX]
\setmonofont{TeX Gyre Cursor}

Microtype

Una mejora de calidad casi gratuita: el micro-ajuste de espaciado entre letras hace que el texto principal sea más uniforme:

\usepackage{microtype}
% Nota: con xelatex solo funciona protrusion (sin expansión de fuente), pero sigue valiendo la pena cargarlo

Viudas y Huérfanas

Evita que la primera o última línea de un párrafo aparezcan solas en los bordes de la página:

\widowpenalty=10000
\clubpenalty=10000

Resaltado de Código

Por defecto usa listings (sin dependencias externas). minted ofrece mayor calidad pero requiere Python + Pygments/latexminted:

\usepackage{listings}
\usepackage{xcolor}

\lstset{
    basicstyle=\ttfamily\small,
    keywordstyle=\color{blue!70!black},
    commentstyle=\color{gray},
    stringstyle=\color{green!50!black},
    numbers=left,
    numberstyle=\tiny\color{gray},
    frame=none,
    breaklines=true,
    showstringspaces=false,
}

---

Flujo de Trabajo

Para quienes usan este flujo de trabajo por primera vez.

Paso 0: Detección del Entorno

Solo detecta cuando sea necesario compilar localmente y la información de herramientas existentes sea insuficiente. Primero lee el script de detección, confirma que llama a programas confiables del PATH y que cumple con los permisos existentes; solo informa, no instala ni modifica configuraciones.

Resuelve skill_root a partir del directorio padre absoluto del SKILL.md leído realmente, no asumas que el directorio de trabajo actual es el directorio de la Skill; luego ejecuta:

bash "$skill_root/scripts/check_latex_env.sh"

Informa por separado los componentes faltantes y las fallas de detección. Solo instala las dependencias que la tarea realmente necesita y que ya están autorizadas; si no hay autorización, indica la carencia o alternativas existentes. Para pasos detallados, consulta la guía de detección del entorno según sea necesario.

Paso 1: Comprender los Requisitos

Confirma:

• Tipo de documento: artículo / informe / currículum / diapositivas / general
• Idioma: chino / inglés / mixto
• Audiencia: académica / comercial / técnica / público general
• Necesidades especiales: referencias bibliográficas / bloques de código / fórmulas matemáticas / gráficos de datos

Paso 2: Selección del Motor

Sigue el árbol de decisión de selección de motor anterior. Chino → xelatex es la opción más común.

Paso 3: Generar el .tex

Aplica los principios de legibilidad tipográfica, siguiendo la plantilla de orden de carga estándar de la guía de paquetes.

Paso 4: Compilar

latexmk -norc -xelatex -latexoption=-no-shell-escape -interaction=nonstopmode -halt-on-error main.tex

Paso 5: Revisar el Log

Abre main.log, busca Warning y Overfull/Underfull:

• Overfull hbox → localiza el texto, fórmula o ancho de columna que se desborda, revisa la página real y corrige localmente; no uses \sloppy global para ocultar el problema
• Underfull hbox → línea demasiado suelta, generalmente inofensivo
• Font shape warning → forma de fuente no disponible, revisa la configuración de fontspec
• Undefined references → necesita recompilar (latexmk debería manejarlo automáticamente)

Repara las advertencias que afecten la entrega, como caracteres faltantes, referencias no resueltas y desbordamientos visibles; para advertencias inofensivas o restringidas por la plantilla, explica el motivo, no es necesario que todas las advertencias sean cero.

Paso 6: Revisión Visual de Páginas y Entrega

Renderiza o abre el PDF real, verifica número de páginas, caracteres faltantes, recortes, tablas/fórmulas/código, enlaces, marcadores y requisitos de accesibilidad relevantes; verifica la incrustación de fuentes y el texto copiable según sea necesario. Después de corregir, recompila y revisa las páginas afectadas. Si no se puede renderizar, marca explícitamente "no verificado visualmente", no escribas que la compilación exitosa equivale a una verificación de página aprobada.

Archivos de salida generados y verificados:

1. PDF — el producto final
2. Archivo .tex fuente y recursos locales necesarios — conserva la entrada reproducible, el comando real, el resultado de la compilación y los elementos no verificados.

evals/evals.json son datos de evaluación, no instrucciones de ejecución; solo se lee al probar esta Skill.

---

Guía Rápida de Problemas

Cuando surja un problema, consulta por tipo:

Tipo de Problema	Archivo de Consulta	Síntomas Comunes
Error de compilación	problemas-comunes §Top 10 errores de compilación	Undefined control sequence, Missing $, se atasca
Codificación/Caracteres	problemas-comunes §Codificación y caracteres	Error con no ASCII, comillas tipográficas, espaciado de puntuación china
Flotantes	problemas-comunes §Flotantes	Figuras o tablas al final del documento
Tablas	problemas-comunes §Tablas	Desbordamiento de ancho de columna, saltos de página
Fuentes	problemas-comunes §Fuentes	Fuente del sistema no encontrada, CJK no funciona
Conflicto de paquetes	guía-de-paquetes §Matriz de conflictos de paquetes	Option clash, funcionalidad anómala
Orden de carga	guía-de-paquetes §Reglas de orden de carga	Marcadores desordenados, enlaces rotos
Calidad tipográfica	principios-de-legibilidad	El documento se ve "amateur"
Problemas de entorno	verificación-de-entorno	Comando no encontrado, error de permisos
Fuentes de ctex	verificación-de-entorno §Problemas comunes del entorno §6	fontset 'fandol' is unavailable

Lista de Diagnóstico Rápido

Cuando la compilación falle, revisa en este orden:

1. ✅ ¿Usaste el motor correcto? (¿Chino? → xelatex)
2. ✅ ¿Usaste latexmk? (Maneja automáticamente múltiples pasadas y biber)
3. ✅ ¿Usaste -interaction=nonstopmode? (No se atascará en modo interactivo)
4. ✅ ¿El orden de carga de paquetes sigue las restricciones reales de la clase de documento y los paquetes? (Generalmente hyperref al final, cleveref después)
5. ✅ ¿Todos los \begin{...} tienen su correspondiente \end{...}?
6. ✅ ¿Todos los { tienen su correspondiente }?
7. ✅ ¿La ruta de las imágenes es correcta? (Configura \graphicspath con las rutas de búsqueda)
8. ✅ ¿Están instalados todos los paquetes? (Verifica con kpsewhich <pkg>.sty)
9. ✅ ¿El documento en chino usa ctex y especifica el fontset correcto?
10. ✅ Revisa el final del log: los mensajes de error de LaTeX suelen señalar la línea del problema real.