baip/skills

Apuntes de clase accesibles desde originales escritos a mano y mecanografiados

El entregable es un archivo Markdown por documento más un script de dibujo de figuras por documento. Un PDF etiquetado y un sitio web se generan a partir de ellos mediante el kit de herramientas incluido aquí. El Markdown es la única fuente: las correcciones van en el .md, nunca en el .tex o HTML generado.

                     ┌─ mkweb.py   → Sphinx + MyST + MathJax → site/
Markdown (*.md) ─────┤
                     └─ md2tex.py  → <class>.cls → lualatex  → PDF junto al .md

Un proyecto tiene este aspecto:

md2tex.py buildtex.py mkweb.py checkweb.py package.py contents.py   scripts de compilación, se ejecutan desde la raíz
<class>.cls  contents.yaml  CONVENTIONS.md  BUILD.md
src/                 lectures: NN_Name.md, con NN_Name.tex y .pdf al lado de cada uno
2026/                tareas y exámenes de una edición, misma disposición
figures/             fig_<doc>_<NN>_<name>.svg, y los PDF hechos a partir de ellas
scripts/figures_audit.py
scripts/figures/     figlib.py, make_figures_<doc>.py, ayudantes de datos
originals/  work/    los originales e imágenes de página, sin seguimiento

Lo que incluye

Ruta	Uso
scripts/init_project.py	Crear un nuevo proyecto, o --update-toolkit en uno existente
scripts/render_pages.py	Renderizar las páginas de un original (y recortes ampliados) para leerlas
scripts/contact_sheet.py	Renderizar las figuras SVG modificadas en un solo PNG para inspeccionar y enviar
scripts/notation_lint.py	Señalar compromisos de notación: límites en palabras, anotaciones descritas, subíndices aplanados, letras fuera de las matemáticas, bloques alt incorrectos, glifos que faltan en la fuente del PDF
assets/toolkit/	Los scripts de compilación y notes.cls, colocados en un proyecto por init_project.py
assets/templates/	contents.yaml, un ejemplo de clase y script de dibujo, .gitignore, package.json
references/transcribing.md	Lectura de originales, peculiaridades de OneNote, clases y tareas, comprobaciones previas a la entrega
references/figures.md	Cómo dibujar figuras que superen la revisión
references/notation-pass.md	Revisar documentos existentes para usar notación real, solo o con ayudantes paralelos
references/review-and-delivery.md	Rondas de revisión, git, trabajo a través de un puente de archivos, publicación
references/conventions.md, references/building.md	Se convierten en los CONVENTIONS.md y BUILD.md del proyecto

0. Configurar o encontrar el proyecto

1. Buscar un proyecto existente: contents.yaml, md2tex.py, un *.cls, CONVENTIONS.md, BUILD.md. Si existe, lea primero su CONVENTIONS.md y BUILD.md y sígalos donde difieran de esta habilidad, ya que registran decisiones del autor. Revise también las confirmaciones recientes del proyecto: el autor a menudo revisa documentos a mano, y esas revisiones son el estilo actual de la casa (redacción del frontmatter, qué conservan las notas finales).

2. De lo contrario, cree uno nuevo:

   python3 <skill>/scripts/init_project.py <carpeta> \
       --title "CHEM 101 — Química General" --short "CHEM 101" \
       --class chem101 --author "…" --copyright "…"
   

   Compile el ejemplo de clase una vez para confirmar que la máquina está configurada (BUILD.md enumera las instalaciones), luego elimínelo de contents.yaml, src/, scripts/figures/ y figures/.

3. Pregunte lo que no pueda inferir, en una sola ronda: nombre del curso y código corto, qué documentos vienen primero, dónde están los originales y el proyecto (cargas, una carpeta en el ordenador del autor, un repositorio git), si compilar el PDF y el sitio web en cada ronda, y quién envía los cambios. A menos que se indique lo contrario, confirme localmente y nunca envíe.

4. Las instrucciones permanentes se aplican para cada ronda posterior hasta que se levanten ("no compilar", "yo mismo enviaré los cambios").

1. Leer los originales

La extracción de texto solo devuelve texto mecanografiado. La escritura a mano y los bocetos son tinta, así que renderice las páginas y léalas como imágenes, ampliando cualquier cosa pequeña:

python3 <skill>/scripts/render_pages.py originals/03.pdf work/03
python3 <skill>/scripts/render_pages.py originals/03.pdf work/03 --zoom 5 0.1 0.2 0.9 0.5

Lea references/transcribing.md antes del primer documento.

2. Transcripción

Siga el CONVENTIONS.md del proyecto. Las reglas más importantes:

• Dónde va. Una clase es src/NN_Name.md; las tareas y exámenes van en la carpeta del año (2026/homework03_solution.md). Añada cada uno a contents.yaml con checked: false. Solo el autor lo establece como true, lo que lo publica en el sitio web.
• Frontmatter. title, docheading (el único h1), lang, runningfoot, description (" Apuntes de : ."), subtitle ("<título del curso>."). Los encabezados del cuerpo comienzan en ## y nunca saltan un nivel. No hay nota "Acerca de esta transcripción" ni marcadores de límite de página: el autor los elimina, así que no los añada.
• Soluciones de tareas. Transcriba solo las soluciones, bajo ## Problema N y ### Parte (a): <lo que encuentra>. Cuando el autor proporciona el conjunto de problemas (como .tex o .pdf), úselo para entender las soluciones y para la notación, no como texto para convertir.
• Matemáticas: la notación del original, correctamente compuesta. LaTeX en $…$, y $$…$$ dentro de ::: eq. Sumas, productos e integrales llevan sus límites; las matrices y determinantes se componen; las letras script son \mathcal{}; los índices en cursiva, las etiquetas rectas; subíndices anidados reales (x_{j}, nunca x\, j); palabras en \text{}; no use \left(\right) alrededor de una fracción simple a menos que se dibuje; \, solo después de una coma en una lista de subíndices, entre fracciones adyacentes y antes de un diferencial; {} después de un \underbrace seguido de un operador; \exp(…) para un exponente que lleva una fracción.
• Las anotaciones a mano se convierten en notación (\cancel, \underbrace{…}_{0}, llaves etiquetadas, \overset{…}{=}, \boxed, barras de evaluación), y dicha ecuación obtiene una forma hablada: ::: {.eq alt="…"} que contiene exactamente una ecuación en pantalla, con una oración simple que nombra las marcas (sin LaTeX, sin comillas dobles). Las ecuaciones ordinarias no tienen alt: MathML de MathJax permite que un lector las recorra.
• La fuente de texto del PDF carece de algunos símbolos (⋮, ①, π, ′, ≪, ≫). Escríbalos como matemáticas ($\vdots$), y "estado 1" para números encerrados en círculos. La compilación falla si falta algún carácter.
• Tablas: solo tablas de tuberías, con una fila de encabezado, sin reglas. Coloque una figura antes de una tabla larga, nunca justo después. Mantenga las tablas lo suficientemente estrechas para la página (la compilación advierte cuando una es demasiado ancha).
• Bloques: ::: eq, ::: problem, ::: keep, ::: flush, ::: quote, ::: note. No existe [H].
• Errores en el original se transcriben tal como están escritos y se marcan en las notas finales con la evidencia, nunca se corrigen en silencio. Cuando el autor dice que corrija uno, corríjalo.
• Notas finales (## Notas sobre los cambios realizados para la accesibilidad) contienen solo lo que el autor necesita verificar o decidir: posibles errores, lecturas inciertas, adiciones. Sin texto estándar.

Ejecute python3 <skill>/scripts/notation_lint.py <doc>.md antes de compilar: sus errores deben corregirse, sus advertencias deben comprobarse con el original.

3. Redibujar cada figura

Cada boceto se convierte en un SVG dibujado por scripts/figures/make_figures_<doc>.py basado en figlib.py, con el nombre fig_<doc>_<NN>_<name>.svg, referenciado desde el Markdown de forma relativa a sí mismo como ![**Título.** Descripción larga.](../figures/fig_….svg){#fig-<doc>-<NN> width=NNN alt="…"} y citado como [](#fig-<doc>-<NN>). Nunca escriba un número de figura a mano. Lea references/figures.md antes de dibujar. En resumen: calcule curvas a partir de ecuaciones, céntrelas en el gráfico, comience y termine las flechas en los objetos, mantenga las etiquetas cerca y claras de las líneas (place_label en gráficos densos), dibuje acentos y números encerrados en círculos en lugar de escribirlos, ajuste el tamaño del viewBox al dibujo y actualice el pie de foto cada vez que el dibujo cambie.

4. Compilar y verificar

python3 scripts/figures/make_figures_<NN>.py
python3 md2tex.py <nombre>                  # p. ej. 09_Mezclas o homework03_solution
python3 buildtex.py <nombre>                # 12 comprobaciones, más una advertencia de demasiado ancho
python3 mkweb.py && python3 checkweb.py   # 9 comprobaciones por página, incluidos errores de MathJax
python3 scripts/figures_audit.py
python3 <skill>/scripts/contact_sheet.py work/sheet.png figures/fig_<doc>_*.svg

• Mire la salida. Vea la hoja de contactos de cada figura modificada y renderice las páginas PDF que contengan ecuaciones, tablas y figuras modificadas. Envíe la hoja al autor.
• Un documento retenido con checked: false no está en el sitio web. Para probar su página, compile el sitio en una copia temporal con él establecido como true.
• La comprobación 11 ("el texto alternativo de la fórmula no es LaTeX sin procesar") falla en TeX Live anterior a tagpdf 1.0. Si falla en la máquina que crea los PDF publicados, dígalo en lugar de ocultarlo.
• Si el autor dijo que no compilara, no escriba la salida de la compilación en su carpeta. Una copia temporal en otro lugar está bien para verificar un cambio arriesgado.
• Las comprobaciones son necesarias, no suficientes. Recomiende PAC 2024 en los PDF y una auditoría WCAG del sitio antes de publicar.

5. Rondas de revisión y revisiones por lotes

Lea references/review-and-delivery.md. En resumen: sincronice primero con los archivos actuales del autor, haga una tarea por viñeta más una tarea de verificación, verifique cada punto con el original, responda preguntas por separado de las ediciones (no cambie nada para una pregunta hasta que el autor decida), corrija las convenciones de todo el proyecto en el kit de herramientas y en CONVENTIONS.md, e informe en una línea por elemento.

Cuando el autor solicite la misma revisión en muchos documentos (por ejemplo "haz que 05–10 coincida con lo que hice en 01–04"), lea references/notation-pass.md: estudie la propia revisión del autor como modelo, haga las partes mecánicas con un script y entregue el trabajo por ecuación a ayudantes paralelos, dos o tres documentos cada uno, con un resumen escrito.

6. Entrega

• Edite en la máquina del autor cuando el proyecto resida allí. Vuelva a generar los SVGs ejecutando el script de dibujo allí en lugar de copiarlos, ya que los puentes de archivos pueden reescribir imágenes en tránsito. Confirme mediante suma de verificación cuando copie.
• Confirme con la identidad del propio autor y un mensaje que enumere los elementos. Nunca envíe cambios a menos que se le pida, y rechace los ganchos que se lo soliciten.
• Si se pierde el enlace con el ordenador del autor, confirme en su propio clon y entregue un paquete git (git bundle create x.bundle <su-cabeza>..main) que puedan extraer, o aplíquelo cuando el enlace regrese.
• python3 package.py crea un archivo de todo el proyecto a partir de contents.yaml, y se niega mientras scripts/figures_audit.py falle.
• Para dar a un proyecto un kit de herramientas más nuevo: python3 <skill>/scripts/init_project.py <carpeta> --update-toolkit.