Rediseño del template LaTeX RELab_latex_template

Contexto

La carpeta PRIVATE/RELab_latex_template/ contiene el template LaTeX del Robust Ecologies Lab (autor original Mathias Legrand, refactorizado por Pablo Almaraz para el RELab). Hoy en día el template se usa en dos archivos .tex con propósitos solapados pero estilos distintos:

  • main.tex — manuscrito tipo preprint que carga cls/SelfArx.cls v3.1. Estética sobria, citas estilo nature, mathptmx/texgyrepagella para tipografía, header con logo del laboratorio, abstract destacado.
  • pseudocode.tex — documento técnico independiente que define localmente una serie de elementos visuales muy logrados (algorithmbox, definitionbox, badges de confianza \confhigh/\confmedhi/…, status box amarilla, listings R) y carga mathpazo directamente.

El usuario quiere unificar y enriquecer el ecosistema: que toda la funcionalidad estilística de pseudocode.tex viva dentro de cls/SelfArx.cls, que main.tex se reescriba como una galería didáctica que ejercite todas las opciones (1 y 2 columnas, ecuaciones de 1 y 2 columnas, figuras anchas/estrechas/de doble ancho, varios tipos de cajas, varias fuentes), que se incluya un main_void.tex esqueleto y un README.md que documente exhaustivamente todas las opciones — las preexistentes y las nuevas. La fuente por defecto debe ser mathpazo y debe ser conmutable a varias alternativas optimizadas.

El contenido textual de los .tex actuales es irrelevante: sirve solo como ejemplo y se sustituye por placeholder lorem-ipsum-de-divulgación-científica.

Decisiones arquitectónicas

1. La clase como única fuente de verdad

cls/SelfArx.cls pasa de v3.1 → v4.0. Todo lo que hoy vive en el preámbulo de los .tex (badges de confianza, paletas de color extra, environments visuales) baja a la clase y se expone vía un sistema de opciones de clase + toggles (vía etoolbox, ya cargado).

2. Sistema de opciones de clase con kvoptions

Se añade kvoptions para ofrecer opciones tipo key=value (más limpio que \DeclareOption*). Opciones expuestas:

Opción Valores Default Efecto
font mathpazo, newtx, mathptmx, libertinus, kpfonts, fourier, charter, lmodern, helvet, palatino mathpazo Carga del paquete tipográfico óptimo según el caso. mathpazo (Palatino + matemáticas Pazo) por defecto, fiel al pedido. newtx para Times-like moderno, libertinus para humanista con OpenType/lualatex, kpfonts para math-heavy, charter para alta legibilidad, etc.
colortheme relab (default), ocean, forest, ember, slate, royal, sand relab Cambia los tres color1, color2, color3 en bloque a paletas precalibradas.
cols one, two one Activa \twocolumn con ajustes de geometría compatibles.
lineno on, off off Activa numeración de líneas (paquete lineno ya cargado).
header logo, plain, none logo logo muestra el logo RELab; plain solo título; none cabecera vacía.
bibstyle nature, apa, authoryear-comp, numeric-comp, ieee, chicago-authordate nature Pasa el estilo a biblatex.
linkcolor subtle, vivid, mono subtle Tres estilos de coloreado de hyperref.
draft (booleano) off Activa lineno, todonotes visible, marcas de overfull.

Implementación:

\RequirePackage{kvoptions}
\SetupKeyvalOptions{family=SelfArx, prefix=SelfArx@}
\DeclareStringOption[mathpazo]{font}
\DeclareStringOption[relab]{colortheme}
\DeclareStringOption[one]{cols}
... (etc.)
\ProcessKeyvalOptions*

Después, ramificación con \ifdefstring{\SelfArx@font}{mathpazo}{...}{...} (etoolbox).

3. Catálogo de fuentes — qué carga cada font=

Cada opción aplica el conjunto idiomático correcto (paquete texto + paquete matemáticas + microajustes), respetando que una mala mezcla rompe el matemático. Tabla canónica:

font= Texto Matemáticas Caso de uso
mathpazo (default) mathpazo (Palatino) mathpazo Manuscritos largos, lectura prolongada, default RELab
newtx newtxtext newtxmath Times moderno, journals tipo PRSA, Nature
mathptmx times + mathptmx mathptmx Times clásico (compatible con LaTeX viejo)
libertinus libertinus libertinust1math Humanista pdfLaTeX/lualatex, gran cobertura UTF-8
kpfonts kpfonts kpfonts Documentos saturados de matemáticas
fourier fourier (Utopia) fourier Estilo francés, contraste alto
charter charter + mathdesign mathdesign con Charter Pantalla y proyección
lmodern lmodern (ams) LaTeX clásico moderno
helvet helvet (sans) + sansmath sansmath Posters, slides
palatino palatino (sin mathpazo math) (default) Solo texto Palatino

Bajo lualatex/xelatex (detectado vía iftutex), se prefiere la rama OpenType paralela: texgyrepagella para mathpazo/palatino, STIX Two para newtx, Libertinus Serif para libertinus, etc., con unicode-math.

4. Paleta de colores extendida

Se mantienen color1, color2, color3 y se añaden las colores que pseudocode.tex definía localmente, ahora globales en la clase:

  • Confidence: confhighbg/fg, confmedhibg/fg, confmedbg/fg, conflowbg/fg, newtagbg/fg, fixtagbg/fg (idénticos a los de pseudocode.tex).
  • Box-themes: boxgray, boxblue, boxgreen, boxyellow, boxred, boxpurple, boxteal (cada uno con triplete bg/frame/title-bg coherente).
  • themePrimary, themeAccent, themeMuted redirigidos según colortheme=.

5. Catálogo de environments tipo caja

Todas como tcolorbox con la misma firma ([label]{title}), todas registradas en el \listofboxes (contador único boxcounter):

Environment Color base Uso típico
algorithmbox gris (existe) Pseudocódigo, igual de elegante que en pseudocode.tex
definitionbox azul/gris (existe) Definiciones formales
theorembox índigo Teoremas destacados
lemmabox violeta Lemas
examplebox verde Ejemplos resueltos
notebox azul claro Notas al margen del flujo
tipbox verde-amarillo Consejos, buenas prácticas
warningbox rojo Avisos, supuestos críticos
cautionbox naranja Advertencias suaves
statusbox amarillo (la actual de pseudocode.tex) Estado del documento, versionado
quotebox gris claro Citas largas destacadas
codebox gris ttfamily Bloque de código no listings
proofbox sin color, marco fino Demostraciones largas que no caben en proof

Fix técnico: la algorithmbox actual mezcla breakable + float — mutuamente excluyentes en tcolorbox. Se separa en dos environments:

  • algorithmbox — flotante, no breakable (rinde como float [t!], va al \listofboxes).
  • algorithmbox* — breakable, no flotante (para algoritmos largos que no caben en una página, idéntico al de pseudocode.tex).

Mismo patrón para definitionbox/definitionbox* y theorembox/theorembox*.

6. Listings de código mejorados

\lstset se enriquece y se añaden estilos nombrados conmutables:

  • \lstdefinestyle{Rstyle}{...} — el actual de pseudocode.tex (R, comentarios gris cursiva, strings púrpura).
  • \lstdefinestyle{Pythonstyle}{...} — Python con keywords azul-bold.
  • \lstdefinestyle{Cppstyle}{...} — C++.
  • \lstdefinestyle{Bashstyle}{...} — shell.
  • \lstdefinestyle{Latexstyle}{...} — LaTeX para meta-doc.

Comando \setcodelang{R} (default R) que aplica \lstset{style=Rstyle}.

7. Badges de confianza y tags

Se trasladan tal cual desde pseudocode.tex y se añaden variantes:

  • \confhigh, \confmedhi, \confmed, \conflow — niveles de confianza.
  • \confnew, \conffix — tags ortogonales.
  • \todo{...}, \fixme{...}, \note{...} — marcas inline (sobre todonotes).
  • \confidence{LEVEL} — el helper que hoy vive en main.tex, ahora en cls.
  • \fixflag{...} — el helper rojo de main.tex, ahora en cls.

8. Soporte de figuras

\graphicspath{{imgs/}{figs/}{./}} (se añade imgs/).

Se introducen comandos macro para los tres patrones de figura que pide el usuario:

  • \onefig{path}{caption}{label} — figura de una columna (figure* si onecolumn, figure con width=\columnwidth si twocolumn).
  • \widefig{path}{caption}{label} — figura de doble ancho cubriendo todo el \textwidth aun en modo twocolumn (envuelve en figure*).
  • \twofig{pathA}{pathB}{captionA}{captionB}{labelA}{labelB} — dos figuras lado a lado con subcaption.
  • \fullpagefig{path}{caption}{label} — figura a página completa con \includegraphics[width=\textwidth, height=0.9\textheight, keepaspectratio].

9. Soporte de ecuaciones en doble columna

En modo cols=two, las ecuaciones largas no caben en \columnwidth. Soluciones:

  • equation y align normales — confinadas a la columna.
  • Comando \widetop{...} que vuelca contenido al ancho completo en la parte superior de la página (basado en \twocolumn[...] o dblfloatfix).
  • Environment widealign (envoltorio sobre figure*+minipage) para ecuaciones que crucen ambas columnas.

10. Theorems numerados con sección

Se añaden los theorems que faltan en la cls actual: openproblem, definition (ya existe), y se permite numeración por sección vía \numberwithin{theorem}{section} opcional. La cls expone una toggle \toggletrue{theoremsbysection} por si el usuario lo prefiere.

11. Limpieza de bugs en la clase actual

  • Línea 108: \RequirePackage{graphicx} está duplicada (también en línea 104). Eliminar.
  • algorithmbox mezcla breakable + float (incompatibles en tcolorbox). Separar como se describe arriba.
  • \graphicspath{{figs/}{./}} no incluye imgs/. Añadir.
  • tolerance=1000, \hyphenpenalty=50, \exhyphenpenalty=50 son agresivos y pueden producir líneas con river-spaces; se documentará y se permitirá ajustar vía opción linebreak={loose,normal,tight}.
  • \flushbottom global — documentado, pero conflictúa con figuras flotantes; se permite override.
  • \set...spacing se ofrece como opción de clase en lugar de comentar/descomentar manualmente.
  • \@maketitle muestra el header logo solo si el archivo existe, pero si no existe imprime una \PackageWarning sin fallback visual: añadir título de respaldo.

Estructura final de archivos

PRIVATE/RELab_latex_template/
├── cls/
│   ├── SelfArx.cls              ← reescrita, v4.0
│   └── RELab_tex_logo.pdf       ← intacto
├── imgs/
│   └── ... (intacto)
├── main.tex                     ← reescrito como GALERÍA exhaustiva
├── main_void.tex                ← NUEVO — esqueleto mínimo idéntico al main pero sin contenido
├── pseudocode.tex               ← intacto (ya no necesario, pero el usuario quiere conservarlo como ejemplo histórico)
├── refs.bib                     ← intacto
└── README.md                    ← NUEVO — documentación exhaustiva

Diseño de main.tex (la galería)

Estructura propuesta — una sección por funcionalidad, todo con texto placeholder de divulgación científica de sistemas dinámicos / ecología (no requiere significado real):

  1. Title page + abstract + keywords — usa \PaperTitle, \Authors, \affiliation, ORCID, \Abstract, \Keywords, header con logo. Demuestra header=logo, colortheme=relab.
  2. §1 Introduction — \lettrine drop cap, citas a refs.bib, ecuación inline + display, \confidence{HIGH}.
  3. §2 Mathematical preamble — varios theorem, definition, lemma, proposition, \fixflag y \confnew inline.
  4. §3 One-column equations — equation, align, gather, cases, aligned, ecuación numerada con \label cruzado.
  5. §4 Two-column section (usando \twocolumn[...] localmente) — texto a 2 columnas con ecuaciones de 1 columna, wide-equation que cruza ambas columnas vía \widetop{...}.
  6. §5 Figures gallery — usando solo los 4 archivos ligeros de imgs/ (se excluye el JPG IMG_20251009_220439.jpg para mantener el PDF compacto):
    • Figura simple (\onefig) con koloro_bathymetry.png.
    • Dos figuras lado a lado (\twofig) con los dos fig_*.pdf.
    • Figura ancha (\widefig) con koloro_chlorophyll.png.
    • El comando \fullpagefig se documenta en el README pero no se ejercita en main.tex; un comentario % \fullpagefig{...} muestra dónde iría.
  7. §6 Tables — booktabs simple, tabularx con ancho variable, tabla con multirow+makecell.
  8. §7 Boxes gallery — un ejemplar de cada caja:
    • \begin{algorithmbox}{Title} con código R via lstlisting.
    • \begin{algorithmbox*}{Long algorithm} rompible cubriendo dos páginas.
    • \begin{definitionbox} formal.
    • \begin{theorembox} con teorema destacado.
    • \begin{examplebox}, \begin{notebox}, \begin{tipbox}, \begin{warningbox}, \begin{cautionbox}, \begin{statusbox}, \begin{quotebox}.
  9. §8 Code listings — bloques R, Python, C++, bash usando los styles de listings.
  10. §9 Confidence badges + tags — texto de muestra mostrando \confhigh, \confmedhi, \confmed, \conflow, \confnew, \conffix en contexto.
  11. §10 Pseudocode — un algorithmbox largo con algorithm2e (\SetAlgoLined, \KwIn, \KwOut, \Repeat, \For, \If) reproduciendo el estilo de pseudocode.tex.
  12. §11 Cross-referencing showcase — \autoref, \eqref, \cref (si se añade cleveref), referencias a tablas, figuras, cajas y secciones.
  13. §Acknowledgements, ***, *** con \listofboxes, \listoffigures, \listoftables.

main.tex debe compilar sin warnings, mostrar absolutamente cada feature al menos una vez y no superar 12-15 páginas de salida.

Diseño de main_void.tex

Idéntico al main.tex en preámbulo, metadatos vacíos (\PaperTitle{Title}, \Authors{Author}, abstract de una línea), y un \section{Introduction} con un \lipsum[1] y nada más. Es el punto de arranque para un manuscrito nuevo. Todos los comentarios % TODO: señalan dónde rellenar.

Diseño del README.md

Documentación de referencia — no tutorial, no marketing, formato manual. Secciones obligatorias:

  1. Quickstart — 3 líneas: latexmk -lualatex main.tex (o pdflatex+biber+pdflatex+pdflatex), dependencias mínimas (TeX Live ≥ 2023, biber, paquetes incluidos en texlive-science y texlive-fonts-extra).
  2. Estructura de archivos — qué hace cada .tex/.cls/.bib/.pdf.
  3. Opciones de clase (la tabla del §2 más arriba, ampliada con ejemplos \documentclass[...]{cls/SelfArx}).
  4. Catálogo tipográfico — la tabla del §3 con muestras de cuándo usar cada font=.
  5. Paletas de color — los siete colortheme= listados con triplete RGB de cada uno.
  6. Macros de metadatos — \PaperTitle, \Authors, \affiliation, \JournalInfo, \Archive, \Abstract, \Keywords, \HeaderLogoFile, \HeaderWebAddress.
  7. Environments de caja — los 13 environments con un ejemplo mínimo de cada uno + screenshot del PDF.
  8. Comandos de figuras — \onefig, \widefig, \twofig, \fullpagefig con firma y ejemplo.
  9. Comandos de ecuaciones — \widetop, widealign, convenciones de numeración.
  10. Listings — \setcodelang{R|Python|Cpp|Bash|Latex}, customización de cada estilo.
  11. Badges y tags — \confhigh/\confmedhi/\confmed/\conflow/\confnew/\conffix, \confidence{LEVEL}, \fixflag{...}.
  12. Theorems — lista de \newtheorem predefinidos heredados (theorem, lemma, definition, proposition, openproblem, etc.).
  13. Hooks de personalización — qué \renewcommand/\definecolor puedes hacer en el preámbulo del .tex para sobreescribir defaults sin tocar la clase.
  14. Compatibilidad y advertencias — engines (pdflatex/lualatex/xelatex), errores frecuentes (font missing, biber not found, etc.).
  15. Changelog — v3.1 → v4.0 (qué se añadió, qué bugs se arreglaron).

Ficheros críticos a modificar

Archivo Líneas afectadas Tipo de cambio
cls/SelfArx.cls ~15-200 (preamble) reescritura del bloque de opciones (kvoptions) y carga de fuentes
cls/SelfArx.cls ~280-330 (boxes) extensión del catálogo de tcolorboxes
cls/SelfArx.cls ~104, 108 eliminar \RequirePackage{graphicx} duplicado
cls/SelfArx.cls nuevo bloque ~330-380 añadir paleta de confianza + macros \conf*
cls/SelfArx.cls nuevo bloque ~380-420 comandos de figuras \onefig/\widefig/\twofig/\fullpagefig
cls/SelfArx.cls nuevo bloque ~420-460 listings styles y \setcodelang
cls/SelfArx.cls bump version a v4.0 (línea 75) header de la clase
main.tex reescritura completa la galería
main_void.tex nuevo esqueleto
README.md nuevo documentación

Funciones/macros existentes que se reutilizan tal cual:

  • \PaperTitle, \Archive, \Authors, \JournalInfo, \Abstract, \Keywords, \affiliation (líneas 582-587 de la cls actual) — perfectos.
  • \listofboxes, \addboxtolist, contador boxcounter (líneas 261-273) — perfectos.
  • Toggle HeaderWithLogo (línea 95) — se mantiene; la opción header= solo lo programa antes.
  • \@maketitle (líneas 593-640) — se mantiene casi intacto, solo se le añade fallback cuando no hay logo.
  • Definiciones de theorem (líneas 379-401) — se mantienen.
  • Mathops \R, \E, \Z, \eps, etc. (líneas 404-460) — se mantienen.

Verificación end-to-end

Compilación esperada (en orden):

cd PRIVATE/RELab_latex_template
latexmk -lualatex -bibtex main.tex            # debe compilar sin errores
latexmk -pdf main.tex                          # ruta pdflatex+biber, también debe funcionar
latexmk -lualatex -bibtex main_void.tex        # esqueleto compila, da 1-2 páginas

Checklist de aceptación:

Notas finales

  • Biblatex style=nature sigue siendo el default por mínima fricción con el flujo actual; el usuario lo cambia con bibstyle=apa si publica en otra parte.
  • No se toca pseudocode.tex: queda como está, su contenido sigue siendo válido aunque las definiciones locales ahora dupliquen las de la clase. (Si en una iteración futura se decide que ya es innecesario, se puede convertir su preámbulo en un simple \documentclass{cls/SelfArx}.)
  • El sistema de opciones de clase con valores por defecto garantiza que un autor que no toque nada obtiene exactamente el aspecto del template actual; los cambios son aditivos, no destructivos.
  • La cls v4.0 es retrocompatible con main.tex v3.1 si se conservan los toggles antiguos: si el usuario tiene un .tex viejo, sigue compilando.