szcharlesji/tikz-explorer-book

Libro de exploración TikZ

Estás creando un libro que alguien explorará: una sola página web cuya portada es un mapa conceptual de todo el campo, y cuyos capítulos hacen visible una idea con figuras TikZ cuidadosamente calculadas. El lector quiere ver primero el panorama general, conectar los puntos y luego profundizar donde elija.

La visualización es la prioridad. Un capítulo son sus figuras. El texto conduce a una figura y extrae la conclusión de ella; nunca sustituye a una figura que podría mostrar lo mismo. Cuando tengas que priorizar, mantén la calidad de las figuras y reduce la prosa.

Este skill orquesta; el arte de las figuras reside en dos skills hermanos que comparten un lenguaje visual (dlviz.sty, color = rol). Se distribuyen juntos y se encuentran al lado de la carpeta de este skill; a continuación, <skills> indica la carpeta que contiene los tres (la carpeta padre de este skill, donde sea que esté instalado):

• tikz-dl-visualizer (<skills>/tikz-dl-visualizer/): figuras estáticas. Su archivo de estilo, arquetipos y script de renderizado definen qué es una buena figura. La mayoría de las figuras en un libro son estáticas.
• tikz-live (<skills>/tikz-live/): figuras interactivas. Un esqueleto TikZ compilado por pdflatex más una pequeña especificación JS que dibuja la parte móvil, para que el lector pueda arrastrar un punto de inicio, deslizar una temperatura o pasar el ratón sobre un token mientras cada etiqueta sigue siendo TeX real. El libro las incrusta y siguen su tema claro/oscuro.

Lee ambos archivos SKILL.md una vez antes de planificar, para saber qué es una buena figura y cuándo la interacción merece su lugar.

Qué entregas

<book>/
├── book.json            título, partes, ids de capítulos, roles de color, configuración del mapa
├── SPEC.md              el contrato que sigue cada autor de capítulo
├── chapters/00-front.html   portada, espacio para el mapa, cómo leer, convenciones, leyenda
├── chapters/<cid>.html  una <section class="chapter"> por capítulo
├── figs/<cid>-<slug>.tex/.png/-light.png/.pdf
├── figs/<cid>-<slug>.js     solo figuras interactivas: la especificación; fig.sh también escribe
│                            .live.html (incrustado por la compilación), .html (independiente)
│                            y <slug>.<snapshot>.png (para revisión)
├── scripts/<cid>-<slug>.py  el Python detrás de cada número en una figura
├── map/data.json        mapa conceptual: familias, conceptos, obras clave, enlaces, visita guiada
├── tools/               build.py, shell.html (diseño de página), fig.sh, dllive.js (entorno interactivo)
└── index.html, preview.html   página compilada (publica index.html)

Requisitos: una instalación de TeX con TikZ/pgfplots (pdflatex), Ghostscript o poppler para PNGs, ImageMagick para hojas de contacto, uv (o Python con numpy/scipy) para los números de las figuras, y para figuras interactivas node más PyMuPDF (uv run --with pymupdf, que fig.sh hace por ti). La página carga MathJax (jsDelivr) y d3 (cdnjs). Verifica which pdflatex gs magick uv node al principio; si faltan paquetes de TeX, indica al usuario el comando tlmgr install en lugar de instalarlos.

Flujo de trabajo

1. Comprende la fuente y el lector

Lee la fuente (obtén el calendario del curso o el programa de estudios, enumera las lecturas). Luego determina quién es el lector: qué sabe ya (omite lo básico que ya conoce, pero sigue dibujando bien los fundamentos) y a qué apunta (un trabajo, un examen, una dirección de investigación). El objetivo determina la forma del libro:

• La Parte I sigue la fuente, un capítulo por sesión o unidad. Cada uno profundiza en una idea en lugar de resumirlo todo.
• La Parte II es un conjunto de herramientas para el objetivo del lector, por ejemplo, "lo que un investigador de generación de video debe saber": los fundamentos transversales que la fuente asume o pasa por alto, prácticos y actuales, con números reales. Omite la Parte II si el lector no tiene ningún objetivo más allá de la fuente.
• La página de inicio es un mapa conceptual: la visión general antes de cualquier profundidad.

Pregunta al usuario solo cuando el objetivo no esté realmente claro; de lo contrario, indica tu interpretación en una línea y continúa.

2. Planifica capítulos en torno a figuras

Para cada capítulo, escribe un resumen breve: el hilo profundo (una frase), 2–3 figuras con lo que cada una debe hacer visible, qué arquetipo y qué calcular. Este es el paso más importante. Los resúmenes que nombran el mecanismo dan figuras excelentes; los que nombran un tema dan diagramas de cajas.

• Débil: "figura sobre guía libre de clasificador".
• Fuerte: "Mezcla de dos clases en 1D; integra la EDO guiada con velocidades exactas para w = 0, 1, 2, 4; múltiples pequeños de las densidades resultantes frente a p(x|c) y la densidad inclinada, mostrando que la guía sobrepasa la inclinación."

Buenos temas para figuras: un mecanismo en acción (caminos, flujos, actualizaciones), un antes/después, una comparación de dos métodos en entradas idénticas, formas y conteos (formas de tensores, conteos de tokens, FLOPs), un experimento numérico cuyo resultado es el punto. Cada uno debe ser computable: el autor producirá cada número en Python.

Decide qué figuras serán interactivas. Una figura merece interacción cuando el lector aprende cambiando algo y observando cómo responde el mecanismo, de una manera que una imagen estática o múltiples pequeños no pueden mostrar tan bien. Escribe su frase de interacción en el resumen: "el lector arrastra X / desliza Y / pasa el ratón sobre Z y ve W". Presupuesto: aproximadamente una figura interactiva por capítulo, para el mecanismo principal del capítulo; todo lo demás, estático. Buenos candidatos: caminos de optimizadores (arrastra el inicio, desliza β), atención o convolución (pasa el ratón sobre una fila o celda), un peso de guía o barrido de temperatura, un mapa lineal (arrastra los vectores base), pasos de muestreo (reproducir). Malos: tuberías, diagramas de arquitectura, cualquier cosa donde múltiples pequeños ya muestren la tendencia.

• Resumen interactivo: "Mezcla de dos clases en 1D; el lector desliza el peso de guía w de 0 a 6 y ve cómo la densidad guiada sobrepasa el objetivo inclinado; un botón de reproducción integra la EDO paso a paso; números: KL respecto al objetivo, en vivo."

También decide, de una vez, para todo el libro: los roles de color (qué color significa qué; ponlos en book.json para que las figuras, las matemáticas de la prosa y la leyenda coincidan), las convenciones sobre las que el campo no se pone de acuerdo (dirección del tiempo, signos, notación y símbolos que significan cosas diferentes en distintos capítulos, como (v) para la velocidad del momento y el segundo momento de Adam), y los ids de los capítulos (w01…, v01…; la letra se convierte en el prefijo de la etiqueta de la figura, W3.2, V5.1).

3. Andamiaje

python3 <skill>/scripts/init_book.py <book> --title "Título del libro" --sub "Fuente · Trimestre"

Edita book.json (partes, ids de capítulos, roles) y chapters/00-front.html; lee cada uno primero, ya que las herramientas del archivo se niegan a sobrescribir un archivo que no has leído. Los roles de la plantilla son genéricos de aprendizaje profundo (entrada, oculto, latente...): reemplázalos por los del propio campo (para optimizadores: iterar, gradiente, velocidad, pérdida...). Escribe <book>/SPEC.md a partir de references/author-spec.md, completando cada bloque «…»: lector, partes, tabla de roles, convenciones, mapa de capítulos. Los autores solo ven SPEC.md y su resumen, por lo que SPEC.md debe ser autónomo. Escríbelo incluso cuando seas tú mismo el autor del libro: es donde residen las convenciones para capítulos posteriores y sesiones posteriores.

Antes de lanzar a nadie, renderiza una figura de prueba a través de bash <book>/tools/fig.sh para demostrar que la tubería de TeX funciona, y, si el plan tiene figuras interactivas, también una figura interactiva: copia <skills>/tikz-live/assets/examples/momentum/momentum.{tex,js} en figs/_test/, ejecuta bash <book>/tools/fig.sh figs/_test/momentum.tex, luego rm -rf <book>/figs/_test (sus archivos intermedios viven en figs/_test/.dllive/, así que no queda nada). Eso demuestra que node y PyMuPDF funcionan y coloca tools/dllive.js en su lugar. Una tubería rota descubierta por nueve autores paralelos cuesta nueve veces más.

4. Delega los capítulos

Para un curso completo (10+ capítulos), genera subagentes de propósito general en paralelo, cada uno a cargo de 2–4 capítulos relacionados (aproximadamente 5–7 figuras). Cada indicación dice: lee primero <book>/SPEC.md y síguelo; los ids de los capítulos de los que se encarga; por capítulo, los metadatos de la sesión, los artículos, el hilo profundo y los resúmenes de las figuras; renderiza, mira, arregla, luego informa según la sección 5 de SPEC. Agrupa los capítulos relacionados bajo un mismo autor para que las figuras compartidas sean coherentes (por ejemplo, OT dinámico con acoplamientos OT).

Los límites de uso son reales: nueve autores a la vez pueden agotar el límite de una sesión a mitad de la ejecución. Si los agentes se detienen con un error de límite de velocidad, sus archivos se conservan. Reanuda cada uno con SendMessage ("continúa desde donde te detuviste; verifica lo que ya has hecho") una vez que el límite se restablezca, en lugar de iniciar nuevos agentes. Para libros grandes, considera lanzarlos en dos oleadas.

Para un libro pequeño (un tema, 3–5 capítulos) omite los subagentes y escríbelo tú mismo, siguiendo aún SPEC.md.

5. Mientras los autores dibujan: material preliminar y el mapa

Escribe chapters/00-front.html (portada, cómo leer, las convenciones, la leyenda <!--ROLES-->, opcionalmente una tabla que refleje la fuente, por ejemplo el calendario del curso con enlaces a capítulos) y map/data.json. Lee references/concept-map.md para el esquema y cómo elegir familias, nodos, relaciones y la visita guiada. El mapa es una visión general: qué es cada idea, dónde se sitúa, cómo se relaciona y qué capítulo profundiza. No expliques mecanismos allí.

6. Revisa a medida que llegan los informes

Cada informe enumera las frases de una idea de sus figuras y sus afirmaciones no verificadas. Abre tú mismo las figuras más importantes (la comparación principal, cualquier cosa que el usuario haya solicitado por su nombre) y verifícalas con los hechos que conoces. Envía correcciones concretas al autor que la dibujó.

7. Ensambla, verifica, lee

python3 <book>/tools/build.py
python3 <skill>/scripts/check_book.py <book> --sheet

Luego sigue references/qa-and-publish.md: vistazo a la hoja de contacto, verificaciones en el navegador (errores matemáticos, desbordamiento en ancho de teléfono, mapa, modo claro, figuras interactivas: todas montadas, arrastrar y pasar el ratón funcionan, el cambio de tema las recolorea), y lee el texto de cada capítulo antes de publicar. Corrige los deslices de metadatos (números de sesión, fechas) que los autores hereden de tus resúmenes.

No omitas la verificación en el navegador. Las verificaciones estáticas no pueden ejecutar el JavaScript de la página, y los fallos más importantes son silenciosos: un mapa que nunca se renderiza, matemáticas que dejan de tipografiar. Si realmente no puedes abrir un navegador, dilo en la entrega y enumera las verificaciones del navegador como no realizadas.

8. Publica

Publica <book>/index.html como un Artefacto con cada PNG de figura como archivo de soporte (check_book.py --files-json imprime la lista; las figuras interactivas están incrustadas en la página, por lo que sus PNGs se excluyen), o entrega la carpeta si no existe ninguna herramienta de Artefactos. Informa al usuario de qué contiene cada parte, qué no está verificado, qué figuras son ilustraciones en lugar de resultados calculados, y cómo reconstruir (python3 tools/build.py) o volver a renderizar una figura.

Solicitudes posteriores

Edita la misma carpeta y vuelve a publicar la misma ruta de archivo, para que el enlace permanezca igual: añade un capítulo (añade su id en book.json), amplía el mapa (edita map/data.json) o cambia el estilo (edita tools/shell.html). Mantén las correcciones enumeradas en references/qa-and-publish.md §3 cuando toques el shell o map.js.

Archivos de referencia

• references/author-spec.md — la plantilla para SPEC.md, el contrato de los autores de capítulo (reglas de figuras, formato de fragmento HTML, reglas de citación).
• references/concept-map.md — esquema de map/data.json y cómo escribir un mapa que conecte los puntos.
• references/qa-and-publish.md — verificaciones, fragmentos de navegador, trampas conocidas ya corregidas en la plantilla, publicación.
• assets/template/ — el esqueleto del libro que copia init_book.py.