Apéndice A — Cómo está hecho el libro (y cómo extenderlo)

Este libro es reproducible de principio a fin. Aquí se explica su maquinaria por si quieres corregir algo, añadir un capítulo o construir un widget nuevo.

A.1 La pila de herramientas

  • Quarto — el motor del libro. Cada capítulo es un archivo .qmd (Markdown + código + LaTeX) y Quarto lo compila a un sitio web estático (_site/).
  • Python (numpy, scipy, matplotlib) — genera las figuras. El código va dentro del propio .qmd y se ejecuta al compilar, así que las figuras nunca quedan desactualizadas.
  • Web Audio API (JavaScript) — los widgets interactivos. Cada uno es un .html autocontenido en widgets/, sin dependencias externas: el sonido se sintetiza en el navegador del lector.
  • MathJax — renderiza la matemática LaTeX.
  • Bibliografía en BibTeX (referencias.bib) con estilo IEEE (ieee.csl).

A.2 Ponerlo en marcha

# una sola vez
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# ver el libro con recarga en vivo
./preview.sh          # o: quarto preview

quarto render genera el sitio completo en _site/.

A.3 Estructura

libro-audio/
├─ _quarto.yml          configuración (capítulos, partes, tema, formato)
├─ theme.scss           estilos (dos niveles, widgets)
├─ index.qmd            prefacio
├─ capitulos/NN-*.qmd   un archivo por capítulo
├─ apendices/*.qmd      estos apéndices
├─ widgets/*.html       widgets Web Audio autocontenidos
├─ referencias.bib      bibliografía · ieee.csl (estilo)
└─ iframe-resize.html   ajuste automático de altura de los iframes

A.4 El patrón de dos niveles

El nivel amigable es prosa normal. El nivel riguroso es un callout colapsable:

Explicación técnica en prosa…

::: {.callout-important .a-fondo collapse="true"}
## ¿Quieres ir más a fondo? — <tema>
Aquí toda la matemática: $H(j\omega)$, ecuaciones $$…$$
:::

A.5 Añadir un capítulo

  1. Crea capitulos/NN-nombre.qmd con un title: en la cabecera YAML.
  2. Regístralo en _quarto.yml, bajo la parte que corresponda.
  3. Cita con [@clave] (las claves están en referencias.bib).

A.6 Añadir una figura en Python

Un bloque de código etiquetado se ejecuta y su salida se incrusta:

A.7 Añadir un widget interactivo

Cada widget es un .html completo y autocontenido en widgets/ (HTML + CSS + JS en el mismo archivo, sin recursos externos). Se embebe con un iframe:

<iframe class="widget-frame" src="../widgets/mi-widget.html" title="…" loading="lazy"></iframe>

Convenciones útiles aprendidas construyendo los del libro:

  • No uses {{< include >}} para HTML con JavaScript: Pandoc lo interpreta como código. Va siempre en un archivo aparte y se embebe con <iframe>; eso además aísla el JS y evita choques de identificadores si repites un widget.
  • El widget informa su altura al libro con postMessage({type:"widget-height", …}); el script iframe-resize.html (incluido en todas las páginas) ajusta el iframe. Copia ese bloque de cualquier widget existente.
  • No te fíes de aproximaciones en la física: calcula el modelo exacto y verifícalo contra un caso conocido (una alineación Butterworth debe salir plana, un cardioide debe cancelar hacia atrás, la coherencia debe ser \(s/(s+n)\)…). Varios widgets de este libro se reescribieron al descubrir que un atajo daba un resultado físicamente incorrecto.
  • Para dibujar respuestas de biquad, calcula los coeficientes RBJ y evalúa \(H(e^{j\omega})\) analíticamente en vez de fiarte de getFrequencyResponse, que en algunos motores no da un Butterworth limpio.

A.8 Publicar

El repositorio incluye un flujo de GitHub Actions (.github/workflows/publish.yml) que renderiza y publica en GitHub Pages en cada push. Para un dominio propio, ver el README y descomentar site-url/repo-url en _quarto.yml.