mgubi/texmacs

Documentos TeXmacs

Una guía práctica para agentes que trabajan con GNU TeXmacs, recopilada mientras se convertían apuntes de clase y charlas, se escribían paquetes de estilo y se auditaban manuscritos matemáticos extensos. Mantenlo vivo: añade lo que se aprenda nuevo a "Trampas" y mantén los scripts en scripts/ funcionando. Las adiciones específicas de un proyecto pertenecen a un skill local separado que apunte aquí; la sección "Convenciones (obligatorio)" se aplica en todas partes. Fuente: https://github.com/mgubi/texmacs-skill. Última actualización: 2026-11-04.

Mantener este skill actualizado

Este skill está pensado para instalarse como un clon de git (normalmente ~/.claude/skills/texmacs). Antes de trabajar en documentos TeXmacs:

• Actualízalo: ejecuta git -C <directorio del skill> pull --ff-only (si SSH a GitHub falla, haz pull desde https://github.com/mgubi/texmacs-skill.git main). Si el clon tiene cambios locales o commits que no están enviados, informa al usuario en lugar de hacer pull sobre ellos.
• Contribuye de vuelta: cuando se aprenda algo nuevo sobre TeXmacs, añádelo aquí (normalmente en "Trampas", o corrige un script), haz commit en el clon y súbelo a GitHub (o abre un pull request si no puedes subirlo), para que cada instalación lo reciba. El material específico del proyecto se queda en el proyecto.

El formato del archivo

• Un archivo .tm es un árbol serializado: <etiqueta|arg1|arg2> en línea, <\etiqueta>…</etiqueta> (con <|etiqueta> entre argumentos) para argumentos de bloque, los párrafos se separan con líneas en blanco, la sangría es solo de diseño. Dentro de las cadenas \<alfa\> es un símbolo, <less>/<gtr> son </>, \| es una barra literal, <#89AB…> son datos hexadecimales sin procesar (imágenes incrustadas).

• Codificación: las cadenas están codificadas en Cork (T1), no en UTF‑8. Las letras latinas acentuadas coinciden en su mayoría con los bytes Latin‑1 (é = 0xE9, à = 0xE0, ö = 0xF6), pero p. ej. la raya en = 0x15, la raya em = 0x16, § = 0x9F; cualquier otro carácter Unicode se escribe <#XXXX> (punto de código hexadecimal). No escribas <#XX> tú mismo como un token independiente: se lee como datos sin procesar (consulta "Escribir paquetes de estilo"). Consecuencias: nunca edites un .tm con herramientas UTF‑8 (las herramientas Editar/Escribir lo rechazan o lo corrompen). Lee/escribe con Python encoding='latin-1', newline='', o mejor usa la ruta stree a continuación y deja que TeXmacs escriba el archivo.

• Escribir un archivo .tm a mano: copia este esqueleto exactamente. Los elementos de nivel superior se separan con líneas en blanco; sin ellas TeXmacs conserva solo el encabezado <TeXmacs|…> y descarta silenciosamente todo lo demás (el volcado stree es (document (TeXmacs "2.1.5")), el PDF está vacío y no hay ningún error):

  <TeXmacs|2.1.5>
  
  <style|<tuple|article|british>>
  
  <\body>
    Primer párrafo con <math|x<rsup|2>>.
  
    Segundo párrafo.
  </body>
  
  <\initial>
    <\collection>
      <associate|font|TeX Gyre Pagella>
    </collection>
  </initial>
  

  Dentro de <\body> los párrafos (y los bloques de cualquier <\etiqueta>…</etiqueta>) también se separan con líneas en blanco; una sola nueva línea continúa el mismo párrafo. Cierra cada etiqueta de bloque en su propia línea, escapa los símbolos como \<alfa\> y los <, >, | literales en el texto como <less>, <gtr>, \|, y mantén el archivo en Cork/Latin-1 (escríbelo con Python, no con printf o la herramienta Escribir, en cuanto contenga un carácter no ASCII).

• Prefiere generar a escribir a mano. Para cualquier cosa de más de unas pocas líneas, construye el stree en Python (scripts/latex2tm/stree.py) y deja que TeXmacs lo serialice (tm-undump en dump.scm); o escribe el fragmento, haz tm-dump y empalma el árbol. Al escribir a mano, verifica el resultado antes de usarlo: haz tm-dump y confirma que el cuerpo tiene el número esperado de párrafos, o compónlo tipográficamente y confirma que el texto del PDF no está vacío y es completo (mutool draw -F txt). Un PDF vacío o corto, o un volcado con un nodo enorme, significa un error de formato, no un error de TeXmacs.

• Archivos grandes: las charlas incrustan imágenes como datos sin procesar (10+ MB). Elimina las secuencias <#…> antes de leer: re.sub(r'<#[0-9A-F]{200,}>', '<#HEX>', s).

Ejecutar TeXmacs sin interfaz gráfica

Binario (macOS): /Applications/TeXmacs.app/Contents/MacOS/TeXmacs; en Linux texmacs. Probado con 2.1.4 y 2.1.5. scripts/latex2tm/run.sh contiene la ruta; ajústala allí.

• Convertir: TeXmacs -headless -c entrada.tex salida.tm -q (importación LaTeX), -c entrada.tm salida.pdf -q (PDF del búfer actual).
• Scheme: TeXmacs -headless -x "(begin (load \"/abs/dump.scm\") … (quit-TeXmacs))". Envuelve siempre el cuerpo en (catch #t (lambda () …) (lambda args (display args))) y termina con (quit-TeXmacs): un error deja el proceso colgado para siempre. Ejecútalo en segundo plano y espera su PID (consulta scripts/latex2tm/run.sh); mata solo ese PID, nunca pkill TeXmacs (el usuario puede tener TeXmacs abierto).
• Las ejecuciones sin interfaz gráfica escriben el estado propio de TeXmacs en ~/.TeXmacs/system; eso es normal.

API de Scheme que funciona sin interfaz gráfica (scripts/latex2tm/dump.scm)

• (tree-import (string->url f) "texmacs") / "latex", y (tree-export t (string->url f) "texmacs"): archivo ↔ árbol sin un búfer.
• (tree->stree t) / (stree->tree s): expresiones s. Escríbelas con (call-with-output-file f (lambda (p) (write s p))) — with-output-to-file no redirige en el Guile de TeXmacs. Guile escribe los caracteres de control como escapes \xHH (manejados por scripts/latex2tm/stree.py).
• Composición tipográfica: (load-buffer u) (switch-to-buffer u) (export-buffer-main u (string->url pdf) "pdf" (list)) — la exportación PDF es lo que compone tipográficamente. (update-document "all") no hace nada sin interfaz gráfica (es un comando inactivo retrasado); llama a (generate-all-aux) (update-current-buffer) directamente para llenar la tabla de contenidos / bibliografía, exporta de nuevo, luego (buffer-pretend-modified u) (buffer-save u) para almacenar <\references>. Un archivo nuevo necesita dos pasadas de composición tipográfica, en procesos separados, cada una con una exportación PDF real antes de que todas las referencias se resuelvan (scripts/latex2tm/typeset.sh). Exporta siempre con (list :overwrite) como opciones: sin interfaz gráfica, export-buffer-main de lo contrario pide confirmación para reemplazar un archivo existente, nadie responde y la exportación se omite silenciosamente (mgubi/texmacs#807). tm-typeset y tm-html en dump.scm hacen esto.
• Las presentaciones (screens) exportan solo la pantalla actual. Para una verificación visual construye una copia de vista previa con las pantallas aplanadas en páginas separadas por new-page* (scripts/latex2tm/preview_slides.py); entrega la versión de pantallas.
• Verifica la salida con mutool draw -r 60 -o p%d.png archivo.pdf y magick montage … -tile 4x1 -geometry +4+4; el texto con mutool draw -F txt -o - archivo.pdf (cuenta ? para referencias no resueltas).

Exportación HTML

Haz la personalización HTML dentro de TeXmacs: los paquetes de estilo (o un plugin) configuran las variables del exportador y proporcionan representaciones tmhtml- de macros; un sitio web se construye exportando un directorio (tmweb-convert-dir) con TEXMACS_HOME_PATH apuntando a la carpeta de plugins del sitio y (style-clear-cache). No proceses posteriormente el HTML generado con scripts.

Reúne las correcciones genéricas en un plugin (abajo llamado max-html, vinculado como ~/.TeXmacs/plugins/max-html), y mantén la configuración específica del documento en el paquete del documento. Dicho plugin contiene:

• progs/max-html/fixes.scm, cargado al inicio, corrige la exportación MathJax. Las etiquetas dentro de fórmulas obtienen anclajes (#617), \ring se escribe \mathring (#607) y equations-base se escribe aligned (#611). Reemplaza el enlace de tmhtml-mathjax-formula* dentro de (convert html tmhtml) (module-variable + variable-set!; ayudantes internos como cork->html mediante module-ref) y extiende latex-mathjax con tm-define … (former x).

• El paquete max-html (artículos) proporciona teoremas enmarcados, etiquetas de lista y el panel lateral de contenido div.max-toc. El paquete max-html-slides proporciona el visor de diapositivas y tmhtml-mytitle/myframed/myframed-2.

• resources/ contiene max-html.css/js y max-html-slides.css/js, para copiar junto a las páginas. Los paquetes de documento <use-package|max-html> y asignan la tupla completa html-extra-css de nuevo (primero el archivo del plugin): merge no funciona, porque el exportador lee la variable sin evaluar. Las fuentes son variables CSS (--max-text-font, --max-slide-font).

• Las correcciones genéricas para la exportación HTML van en el plugin. Las cosas específicas del documento (fuentes, favicon, macros de charla) van en el paquete del documento.

• Exportar: (tm-html entrada salida mathjax?) en scripts/latex2tm/dump.scm (preferencias texmacs->html:mathjax|css|images, luego (export-buffer-main u (string->url "x.html") "html" (list))). Exporta el .tm compuesto tipográficamente (los <\references> almacenados dan los números). Los enlaces doc.tm#etiqueta se convierten en doc.html#etiqueta; las imágenes se convierten en <base>-N.png junto a la página; MathJax 3 proviene de jsdelivr.

• Variables de estilo leídas por el exportador (configúralas en un paquete de estilo): html-css (reemplaza el css en línea predeterminado), html-extra-css (tupla de hojas de estilo adicionales, se mantiene el css predeterminado), html-extra-javascript-src (tupla, diferido), html-extra-javascript, html-head-javascript(-src), html-head-favicon, html-title, html-doc-title, html-site-version.

• Representaciones HTML de macros: define tmhtml-NOMBRE junto a NOMBRE. El exportador lo usa en lugar de NOMBRE. Ayudantes de marcado para ello: html-div-class|clase|cuerpo (bloque), html-class|clase|cuerpo (span en línea), html-style, html-div-style, html-attr, html-tag, html-javascript. Esto solo funciona para macros definidas en un paquete de estilo: las macros asignadas en el hide-preamble del documento se expanden antes de la exportación y sus variantes tmhtml- se ignoran. Así que pon las macros de presentación en un paquete.

• Un paquete foo.ts junto al documento se encuentra cuando la tupla de estilo lista foo. Después de editar un paquete, llama a (style-clear-cache) (TeXmacs almacena en caché los entornos de estilo en ~/.TeXmacs/system/cache), de lo contrario se usan definiciones antiguas.

• Tabla de contenidos (y otras listas generadas): las entradas se escriben en los datos auxiliares ya expandidas (write evalúa su argumento), así que los envoltorios alrededor de toc-main-*/toc-1…5 desaparecen y sus variantes tmhtml- nunca se ven. Solo la macro externa table-of-contents puede tener una representación tmhtml-. Los marcadores que sobreviven a la expansión y exportación: <b> (secciones en negrita), <with|font-size|…> → <font style=…>, font-shape → <i>/versalitas, color → <font color>; la sangría par-left se pierde. Cada entrada termina con <a href="#auto-N">página</a>. Receta para el panel lateral (paquete del plugin max-html): tmhtml-table-of-contents → div.max-toc fijo a la izquierda; oculta y estira el enlace de página con .max-toc p a[href^="#auto-"] {position:absolute; inset:0; font-size:0} (selecciona por href: un eqref en un título también es un enlace); marca las entradas a nivel de párrafo redefiniendo toc-3…5 con un <with|font-size|0.92|…> anidado y selecciona p:has(> font). Regenera la TOC (dos pasadas de composición tipográfica) después de cambiar las macros toc-*.

• Resaltar la sección actual en el panel necesita JavaScript: max-html.js (plugin), adjunto con html-extra-javascript-src en el paquete; mapea el enlace #auto-N de cada entrada al encabezado con ese id, marca el último encabezado por encima del 25% del viewport (p.toc-current, y su padre en negrita p.toc-current-section) y desplaza el panel para mantenerlo visible.

• Teoremas enmarcados (artículos web de Joris van der Hoeven, p. ej. texmacs.org/joris/fftcomp; el modelo es styles/article/texmacs/tmarticle.ts en TeXmacs): define tmhtml-render-theorem → <html-div-class|theorem|<render-enunciation|…>> y tmhtml-render-enunciation con <html-class|enunciation-name|cuál>; teorema, proposición, lema, corolario y definición usan render-theorem, mientras que observaciones y demostraciones usan render-remark. El css de Joris (texmacs.org/css/theme-dark-colored.css) es .theorem {border: 1px solid; border-left: 1em solid; padding: 0 1em}; un color apagado y una barra de .5em también funcionan bien (max-html.css). Esto es solo HTML; el PDF no cambia. Colores (también como en el tema de Joris): h1…h6, strong, b, dt, .enunciation-name en un rojo oscuro apagado, la salida MathJax mediante mjx-container {color: …}; restablece b dentro del panel TOC.

• La exportación HTML convierte cada enumerate-alpha|Alpha|roman en una simple <ol> (etiquetas decimales). Corrección: tmhtml-enumerate-alpha → <html-div-class|enum-alpha|<enumerate|…>> más .enum-alpha > ol > li::marker {content: "(" counter(list-item, lower-alpha) ") "}.

• MathJax: el convertidor escribe el acento de anillo <abovering> como \ring{…} (paquete LaTeX accents), del cual MathJax carece (mgubi/texmacs#607). Corregido por el plugin. Una alternativa a nivel de página es una configuración MathJax en línea en html-extra-javascript (se ejecuta antes de la <script> de MathJax): `window.MathJax = {tex: {macros: {ring: [String.fromCharCode(92)

  • 'mathring{#1}', 1]}}}`.

• MathJax: aligned dentro de una equation es preexpandido por el exportador HTML a equations-base y llega a MathJax como \begin{equationsbase} (mgubi/texmacs#611). Corregido por el plugin; la alternativa a nivel de página es environments: {equationsbase: […aligned…]} en esa configuración.

• Verifica todas las fórmulas de una exportación con scripts/mathjax-check/: npm install [email protected] en una carpeta deps/ temporal, luego python3 extract.py DIRECTORIOHTML formulas.json (usa un analizador HTML: < sin procesar en \(t < \infty\) es texto, como en los navegadores) y node check.js deps/node_modules formulas.json. Renderiza cada fórmula sin el paquete noundefined (que en el navegador muestra silenciosamente macros no definidas en rojo) y agrupa los errores. No ve fórmulas vacías (cuenta \(\displaystyle \) por separado) o enlaces rotos: también verifica que cada href="...#x" interno tenga un id="x" coincidente.

• Diapositivas: una imagen con width=100% estrechada por un max-height css se queda a la izquierda de su párrafo; céntrala con div.toggle img.image {display: block; margin: 0 auto}.

• Firefox sin interfaz gráfica: la preferencia content-override del modo oscuro en user.js no surtió efecto; para cambiar a una paleta clara establece TEXMACS_THEME="light" en el entorno (export TEXMACS_THEME="light").

• Renderizado de documentos TeXmacs con el plugin TikZ: tmhtml-tikz es un renderizador de imagen alternativo que guarda el resultado como un archivo PNG y lo referencia en el HTML. Asegúrate de que el paquete TikZ esté instalado en el sistema (sudo apt-get install texlive-pictures en Linux) y de que max-html cargue tikz.ts como dependencia.

• Comprobación final: ejecuta scripts/check_html_links.py DIRECTORIOHTML para detectar enlaces internos rotos y scripts/check_math.py DIRECTORIOHTML para asegurarte de que no haya ecuaciones sin renderizar (etiquetas <span class="MathJax_Preview"> vacías).

Trampas

• No usar UTF-8: un archivo .tm escrito con codificación UTF-8 se corrompe. Si recibes uno, conviértelo con iconv -f utf-8 -t latin-1 y corrige los caracteres que fallen.
• No mezclar estilos de párrafo: no pongas dos párrafos separados por solo un salto de línea dentro de un bloque; usa líneas en blanco.
• No olvidar la línea en blanco inicial: el esqueleto requiere una línea en blanco después de <TeXmacs|...> antes de <style|...>; de lo contrario, el documento se interpreta incorrectamente.
• No usar la herramienta Escribir de TeXmacs para archivos grandes (>1 MB): el editor se ralentiza y puede fallar. Usa scripts para generar o modificar.
• No confiar en la exportación HTML por defecto: personaliza siempre mediante un plugin y verifica con los scripts de comprobación.
• No ejecutar pkill TeXmacs: mata el proceso hijo específico para no cerrar accidentalmente la sesión del usuario.
• No editar .tm con sed o awk: la estructura de etiquetas anidadas es frágil; usa stree.py para transformaciones.
• No olvidar que eqref en un título crea un enlace: ajusta el selector CSS en consecuencia.
• No usar merge para html-extra-css: el exportador no lo evalúa; asigna la tupla completa.
• No definir tmhtml- macros en el preámbulo oculto: se expanden antes de la exportación y se ignoran.

Convenciones (obligatorio)

1. Nunca modifiques un .tm con herramientas UTF-8.
2. Siempre que generes un .tm, verifícalo con tm-dump o composición tipográfica.
3. Siempre que exportes a HTML, usa un plugin para las correcciones genéricas.
4. Siempre que ejecutes TeXmacs sin interfaz gráfica, envuelve el código Scheme en catch y termina con quit-TeXmacs.
5. Siempre que actualices este skill, haz pull primero y contribuye de vuelta si aprendes algo nuevo.
6. Mantén los scripts en scripts/ funcionando y actualiza la documentación en consecuencia.