Este documento vive en el repositorio
Es docs/AUTHORING.md,
la referencia que se usa a diario mientras se escribe. La web lo incluye
tal cual en lugar de copiarlo, para que no haya dos versiones y la de aquí
sea la vieja.
Escribir contenido en Didacta¶
Referencia de todo lo que se puede usar dentro de un fichero de contenido.
La regla que lo gobierna todo: el contenido no sabe a qué salida va. Se escribe una vez y los interruptores deciden qué aparece en cada PDF.
Un fichero de contenido¶
Sin preámbulo. Sin \documentclass. Sin \begin{document}. Solo el contenido:
\begin{frame}
\didactatitle{Definición y propiedades de los espacios normados}
La métrica usual en $\mathbb{R}$ es la distancia euclídea, dada por
\[ d(x,y) = |x-y|. \]
\onlynotes{%
La idea detrás del concepto de norma es generalizar las propiedades más
útiles de la distancia euclídea en $\mathbb{R}$.
}
\begin{definition}[Espacio normado]
Un \keyterm{espacio normado} es un par $(E, \|\cdot\|)$ tal que...
\end{definition}
\end{frame}
Ese fichero produce, sin cambiar una línea:
| Perfil | Qué sale |
|---|---|
slides |
una diapositiva con la definición en caja verde |
notes |
una subsección con el párrafo de \onlynotes incluido |
notes-teacher |
lo mismo, más las notas didácticas |
handout |
una hoja de referencia compacta |
\begin{frame} funciona en prosa porque los perfiles de documento cargan
beamerarticle. Es lo que permite un único origen.
Contenido condicional¶
Lo que no se envuelve aparece en todas las salidas.
| Comando | Aparece en |
|---|---|
\onlyslides{…} |
solo diapositivas |
\onlynotes{…} |
solo documentos |
\onlyteacher{…} |
solo copias del profesor |
\onlystudent{…} |
todo excepto copias del profesor |
\onlyfull{…} |
solo con detalle completo (no en un examen) |
\onlybrief{…} |
solo con detalle reducido |
Formas de entorno, para cuerpos con \par, listas o verbatim — que es donde
la forma de comando se rompe:
\begin{notesonly}
Un párrafo entero.
Y otro, con \begin{itemize}\item listas \end{itemize} dentro.
\end{notesonly}
slidesonly, teacheronly, studentonly, fullonly funcionan igual.
Combinaciones¶
| Comando | Aparece en |
|---|---|
\slidesandteacher{…} |
diapositivas o copia del profesor |
\notesandteacher{…} |
documentos o copia del profesor |
\bymedium{corto}{largo} |
la primera versión en diapositivas, la segunda en prosa |
\bymedium suele ser mejor que esconder una versión: casi siempre lo que se
quiere no es ocultar la frase larga, sino acortarla para la diapositiva.
Alias heredados¶
\onlybook{…} sigue funcionando: es el nombre antiguo de \onlynotes. Los
apuntes que se migran lo usan en 429 ficheros, así que se conserva.
Títulos¶
En diapositivas es el \frametitle. En prosa es una \subsection — que es lo
que un lector necesita para navegar y lo que alimenta el índice.
Escribir \frametitle directamente también funciona, pero en prosa desaparece:
el lector se queda sin encabezado. Usa \didactatitle.
Pausas¶
\dpause revela en slides. En slides-flat, en cualquier documento y en un
handout no hace nada — sin error, y sin generar una página extra.
\pause a secas también funciona (beamerarticle lo neutraliza en prosa),
pero \dpause es explícito sobre que la pausa es opcional.
Entornos de teorema¶
Un solo conjunto de nombres. El aspecto lo decide el medio: caja rellena con barra de título en diapositivas, filete al margen que parte entre páginas en prosa.
| Entorno | es | va | en |
|---|---|---|---|
theorem |
Teorema | Teorema | Theorem |
definition |
Definición | Definició | Definition |
proposition |
Proposición | Proposició | Proposition |
lemma |
Lema | Lema | Lemma |
corollary |
Corolario | Corol·lari | Corollary |
property |
Propiedad | Propietat | Property |
example |
Ejemplo | Exemple | Example |
question |
Cuestión | Questió | Question |
remark |
Nota | Nota | Remark |
axiom |
Axioma | Axioma | Axiom |
algorithm |
Algoritmo | Algoritme | Algorithm |
notation |
Notación | Notació | Notation |
\begin{theorem}[Teorema fundamental]
Enunciado.
\end{theorem}
\begin{definition*} % sin numerar
Para una redefinición o un aparte.
\end{definition*}
Un recuadro sin etiqueta¶
keypoint es un recuadro con el título en negrita si se le pone, sin número
y sin etiqueta:
\begin{keypoint}[Principio de inducción matemática (PIM)]
Si una propiedad $P$ sobre números naturales cumple ... entonces $P$ es cierta
para todo número natural $n$.
\end{keypoint}
Está para el material que destaca algo en un cuadro y no le pone nombre de
nada. El caso que lo motivó: el principio de inducción, que no es un teorema
--no es un resultado que se deduzca de nada, es de donde se parte-- y que la
práctica de la que viene enuncia en un \fbox.
El entorno lo decide lo que la cosa es, no cuánto se enseña de ella. Un
teorema enunciado sin demostrar sigue siendo un teorema: el apéndice de
trigonometría tiene tres, con su nombre y su número y sin una demostración a
la vista. keypoint no es «un teorema sin demostrar»; es el recuadro para lo
que no encaja en ninguno de los nombres de arriba.
Un solo contador compartido. Definición 1.1, Teorema 1.2, Ejemplo 1.3. Contadores independientes producen un Teorema 2.3 seguido de una Definición 2.1, que rompe cualquier referencia cruzada que el lector intente seguir.
El color agrupa por papel y no cambia entre salidas: azul lo que se demuestra o se asume, gris lo que se define, verde lo que se deduce, ámbar lo que se trabaja, violeta lo que conviene destacar.
Demostraciones¶
Una demostración casi nunca cabe en una diapositiva, así que envolverla en
\onlynotes es el caso normal. El nombre («Demostración», «Demostració»,
«Proof») viene del idioma.
Alias heredados¶
ndefn, nthrm, nprop, npro, nlem, ncor, nex, nques, nrem,
naxioma, recipe y las versiones sin n (defn, thrm, …) apuntan todos al
entorno correspondiente. En el sistema antiguo había dos juegos de nombres —
uno con caja y otro sin ella — porque el contenido tenía que saber a qué salida
iba. En Didacta no: migrar es renombrar, no reescribir.
Fórmulas destacadas¶
Para la ecuación de la diapositiva que importa. (nformula es el alias antiguo.)
Las funciones con nombre castellano¶
\sen, \tg, \arcsen, \arctg, \cotg, \cosec, \senh y \tgh se
pueden usar en cualquier idioma: una traducción que copia las fórmulas tal cual
compila. Cada idioma las escribe a su manera --en castellano sen y arc sen,
en valenciano sin y tg, en inglés sin y tan--, y el nombre lo decide su
latex/lang/didacta-lang-XX.def.
Problemas¶
Enunciado, indicación, respuesta, solución y corrección en un solo fichero. Cada nivel aparece únicamente en el perfil que le toca.
\begin{exercise}[Axiomas de norma]
Decide cuáles de las siguientes funciones son normas.
\begin{parts}
\item $f(x_1,x_2) = |x_1| + 2|x_2|$
\item $f(x_1,x_2) = |x_1| - |x_2|$
\end{parts}
\dmarks{4}
\begin{hint}
Para descartar una candidata basta un contraejemplo de un solo axioma.
\end{hint}
\begin{answer}
(i) sí; (ii) no, falla la positividad.
\end{answer}
\begin{solution}
(i) Es la norma 1 con pesos: los tres axiomas se comprueban término a término.
(ii) $f(1,1) = 0$ con $(1,1) \neq 0$.
\end{solution}
\begin{marking}
Un punto por apartado. Se exige nombrar el axioma que falla; decir solo «no es
norma» vale medio punto.
\end{marking}
\end{exercise}
Qué muestra cada perfil:
hint |
answer |
solution |
marking |
|
|---|---|---|---|---|
problems · alumnos, solo enunciados |
✓ | |||
problems-answers · alumnos, con resultados |
✓ | ✓ | ||
problems-teacher · profesor, todo |
✓ | ✓ | ✓ | ✓ |
exam |
||||
exam-marking |
✓ | ✓ | ✓ |
Tres versiones y no cuatro: la que lo enseña todo es la del profesor. Un
guion de prácticas tiene las mismas tres, con handout, handout-answers y
handout-teacher.
Los tres niveles son distintos a propósito:
answeres el resultado.f'(x) = 2x. Una línea. Para que el alumno compruebe si acertó.solutiones cómo se llega. El desarrollo.markinges qué buscar al corregir y cuánto vale cada parte.
En el sistema antiguo solo existía uno de los tres (shownto{solution}) y la
capa de respuesta corta nunca se llegó a escribir, aunque la infraestructura
estaba. Aquí los tres existen desde el principio.
Otros comandos de problemas¶
| Comando | Efecto |
|---|---|
\begin{exercise*} |
sin numerar |
\begin{parts} … \item |
apartados (i), (ii), (iii) |
\dmarks{4} |
puntuación, solo en perfiles de examen |
\answerspace{4cm} |
espacio para responder, solo en examen |
\dmarks, no \marks: \marks es una primitiva de TeX y sobreescribirla
rompe las rutinas de salida de una forma que aparece mucho después y cuesta
mucho rastrear.
Alias heredados¶
\begin{ej} es \begin{exercise}. \begin{shownto}{solution} es
\begin{solution}, y \begin{shownto}{profesor} es \begin{marking}.
El canal del profesor¶
Es un canal de verdad, no un sinónimo de «los apuntes»:
\begin{teaching}[Ritmo]
Quince minutos. Merece la pena detenerse en la homogeneidad: casi nadie ve por
qué hace falta el valor absoluto hasta que se les pide $\lambda = -1$.
\end{teaching}
\begin{commonmistake}
Escriben $\|\lambda x\| = \lambda\|x\|$ y pierden el valor absoluto. Sale
sistemáticamente en el primer parcial.
\end{commonmistake}
\timing{25 min}
Solo aparece en slides-teacher, notes-teacher, problems-teacher y
exam-marking. Con un filete rojo y el pie de página marcado, para que sea
imposible confundir la copia que tienes en la mano.
En el sistema antiguo \onlyteacher estaba definido igual que \onlybook,
así que no distinguía nada: no había forma de escribir una nota que llegara al
profesor y no al alumno.
Diseño de la unidad¶
\begin{objectives}
\begin{itemize}
\item Reconocer los tres axiomas de norma
\item Distinguir norma de métrica
\end{itemize}
\end{objectives}
\begin{prerequisites}
Espacios vectoriales; valor absoluto en $\mathbb{R}$.
\end{prerequisites}
\begin{summary}
Una norma mide longitud; toda norma induce una métrica; el recíproco es falso.
\end{summary}
No son decoración: son lo que hace que una unidad se pueda reutilizar con
seguridad, porque dicen qué asume y qué entrega. didacta check avisa cuando
un prerrequisito apunta a una unidad que no existe.
Figuras¶
Van en un directorio figures/ dentro de la unidad, y se referencian desde
ahí:
content/trigonometria/tales/teorema-tales/
├── es.tex
├── unit.yaml
└── figures/
├── Tales.png
└── corte1.png
\includegraphics[width=.85\textwidth,alt={Un triángulo cortado por dos
paralelas}]{figures/corte1.png}
alt={…} dice lo que se ve en la figura, para quien no la ve: lo lee un lector
de pantalla en el PDF accesible (didacta build --accessible) y en el HTML
(didacta html). Sin etiquetado no hace nada. En un dibujo va en sus
opciones, \begin{tikzpicture}[alt={…}]; Didacta acepta la clave aunque pgf no
la conozca. didacta check --with accessible dice qué figuras no lo tienen.
La figura viaja con la unidad: moverla, renombrarla o reutilizarla en otra
asignatura no rompe la referencia. Es lo contrario del sistema anterior, donde
un img/triangles.pdf apuntaba al directorio del fichero que hacía el
\import, así que la misma línea encontraba la figura o no según desde dónde
se compilara.
Bibliografía¶
Un análisis bibliográfico —el documento que dice dónde está demostrado cada resultado del tema, con capítulo y número— se escribe con los comandos de biblatex:
La irracionalidad de $\sqrt 2$ está en \cite[Theorem 1.1.1]{Abbott}.
Una introducción a los conjuntos, en
\cites[Section 1.2]{Abbott}[Chapter 3]{Tao}.
| Comando | Sale como |
|---|---|
\cite[Theorem 1.1.1]{Abbott} |
[Abb15, Theorem 1.1.1] |
\cites[Section 1.2]{Abbott}[Chapter 3]{Tao} |
[Abb15, Section 1.2; Tao14, Chapter 3] |
\textcite{Tao} |
Tao [Tao14], para citar dentro de la frase |
La clave —Abbott, Tao— es la del fichero de fuentes, que vive en la raíz
del repositorio de contenido:
Una sola lista para todo el repositorio, porque el mismo libro lo citan el
tema 1 y el tema 6, y tenerlo dos veces es tenerlo mal una de las dos. Si se
llama de otro modo, se dice una vez en didacta.yaml:
La lista de obras se imprime sola, al final del documento y solo si el
documento citó algo. Con \DidactaBibliography se puede pedir antes, en el
sitio que se quiera; entonces no se repite al final.
Un repositorio sin .bib no es un error: casi ningún tema cita, y ahí no
se carga biblatex ni se ejecuta biber. Lo que sí pasa es que una unidad que
cite en un repositorio sin fuentes imprime [?] —y didacta check lo dice
antes, con el nombre de la unidad:
warning content/.../numbers-bibliography/es.tex cita `Abbott`, `Spivak`, `Tao`,
y no hay bibliografía: falta shared/bibliography.bib
El mismo aviso sale cuando se cita una clave que el .bib no define, que es
el error de escribir {Abott} por {Abbott}.
Las citas llevan capítulo, sección y número de resultado, y esos números cambian de una edición a otra. El
.bibtiene que decir la edición que se usó al escribirlas.
Otros¶
| Comando | Para |
|---|---|
\keyterm{norma} |
el término que se está definiendo (negrita) |
\hl{esto} |
resaltado |
\didactaprofilebanner |
imprime los ejes activos — útil cuando una compilación ha salido raro |
Composiciones¶
Un documento es una lista de unidades:
\input{didacta-bootstrap}
\usepackage{didacta}
\DidactaDocument{Preliminars: espais normats}
\begin{document}
\DidactaTitlePage
\DidactaContents
\section{Espais normats}
\DidactaUnit{analysis/normed-spaces/definition}
\DidactaUnit{analysis/normed-spaces/induced-metric}
\end{document}
Los apartados van en year.yaml¶
El \section de arriba funciona, y para compilar a mano desde el editor es lo
más cómodo. Pero está en un idioma, y el mismo documento se compila en tres:
structure:
- section:
va: Espais normats
es: Espacios normados
en: Normed spaces
- unit: analysis/normed-spaces/definition
- unit: analysis/normed-spaces/induced-metric
Esa es también la razón por la que un apartado no va dentro de una unidad: el encabezado viajaría con ella a cada asignatura que la reutilice, en el idioma en que se escribió y en la posición en que se dejó.
Los idiomas que caben ahí son los que Didacta trae: es, va, ca, gl,
eu, en, fr, de, it y pt. No hace falta darlos todos --se dan los
que la asignatura use--, y el que falte se compila con el de otro y lo dice en
el log.
| Comando | Incluye |
|---|---|
\DidactaUnit{cat/tema/unidad} |
de content/ |
\DidactaProblem{cat/tema/unidad} |
de problems/ |
\DidactaUnit[en]{…} |
esa unidad en inglés, sea cual sea el idioma del documento |
\DidactaInclude{ruta/fichero} |
un .tex suelto, sin separar por idiomas |
Sin ../../../../. Las referencias se resuelven contra la raíz del
repositorio, que la herramienta inyecta. Mover una carpeta no rompe nada.
\DidactaUnit[en]{…} es lo que permite una hoja bilingüe sin duplicar la
composición.
Si falta una traducción¶
Didacta usa la de referencia y avisa:
Package didacta Warning: No `va' version of `analysis/normed-spaces/induced-metric';
using `es' instead on input line 34.
Una diapositiva sin traducir es mucho más útil que un hueco en la presentación. Si no existe en ningún idioma, sale un marcador visible en el PDF: mejor enterarse al revisar que delante de la clase.
A qué idiomas se traduce¶
settings.yaml dice a cuáles se traduce el repositorio entero y course.yaml
a cuáles cada asignatura:
Sin declararlo son es, va y en. Didacta sabe imprimir sus rótulos en
diez --los siete restantes son ca, gl, eu, fr, de, it y pt--,
pero imprimir en un idioma y traducir a él son cosas distintas: lo que se
declara aquí es lo que cada unidad tiene que tener, y por tanto lo que sale
como pendiente. Declararlos todos por si acaso convierte esa lista en ruido.
Desde la aplicación se marca en Ajustes, con un desplegable por asignatura.
Quitar uno no borra ningún .tex: deja de pedirse, y volver a marcarlo lo
recupera tal cual.
Añadir un idioma que Didacta no traiga es escribir su
latex/lang/didacta-lang-XX.def --treinta y seis palabras-- y anotarlo en el
registro de engine/didacta/profiles.py. Sin las dos mitades no sirve, y hay
un test que lo comprueba.
Metadatos¶
No los escribas en el .tex. Van en course.yaml y year.yaml, por idioma, y
Didacta los inyecta al compilar. Lo que declares en el fichero es solo un
respaldo para que compilar a mano desde el editor siga dando un documento con
título.
Es lo que evita que una cabecera en valenciano acabe en una hoja en castellano.
Temas de un curso¶
Para que la aplicación enseñe junto lo que se da junto. Se declaran al lado
del year.yaml, en themes.yaml:
y cada documento dice a cuáles pertenece:
Son dos ficheros a propósito, y pueden estar en repositorios distintos: el Tema 1 lleva su teoría, su práctica y su bibliografía, y eso puede estar repartido. Uno declara el tema; los demás lo nombran.
De ahí la regla que lo hace seguro: nombrar un tema que nadie declara no es un error. El documento sale suelto, como salía antes. Quien tenga solo uno de los repositorios ve todo su material; lo que no ve es la agrupación.
Un documento puede estar en varios temas, y sale en todos los que se conozcan.
Un tema nuevo¶
El id sale del título si no se da (tema-2-sucesiones). Se crea vacío: los
documentos se le van añadiendo con themes: [tema-2-sucesiones] en su entrada
de year.yaml, o desde la aplicación, con el botón que lleva cada tema
dentro.
Un curso académico nuevo¶
didacta new year am-i 2027-2028 --empty # en blanco
didacta new year am-i 2027-2028 # copiando el más reciente
didacta new year am-i 2027-2028 --from 2022-2023
Sin --empty y sin años de los que copiar --una asignatura recién creada--
sale vacío igualmente: pedir que se copie algo que no existe no es una
respuesta.
Copiar un año copia su composición y sus .tex, nunca las unidades.
Volver a dar un tema otro año¶
Sin ids se copia el curso entero. En la aplicación es el menú de un curso, en la lista de la asignatura: «Copiar a otro curso…», que además enseña los documentos para marcar cuáles.
Se copia la composición, nunca el contenido. El curso de destino referencia las mismas unidades: dar el Tema 1 otro año no reparte copias de su material, así que corregir una errata sigue siendo corregirla una vez. Es para lo que sirve que una unidad no sepa en qué asignatura entra.
Lo que viaja con el documento: su entrada de year.yaml con los comentarios
que lleve --los # TODO: va, las unidades comentadas que ese año no se
dieron--, su .tex, y la declaración de los temas que nombre, si el destino
no los tiene. Lo que ya esté en el destino con el mismo id no se toca: se dice
y no se copia nada.
Compilar¶
Desde el editor, directamente, con SyncTeX funcionando:
Un perfil concreto:
O con la herramienta, que se encarga de TEXINPUTS, del directorio de salida,
de los metadatos y de las pasadas:
didacta build tema-1 # todas las salidas del documento
didacta build tema-1 -p slides -l va
didacta build --all
Dependencias¶
Todo lo que Didacta usa está en CTAN: una TeX Live estándar basta.
Un repositorio con bibliografía necesita además biber, que TeX Live trae y
que ejecuta latexmk por su cuenta: no hay ningún paso que dar.
El sistema anterior necesitaba seis .sty no-CTAN (beamerthemeTorino,
beamercolorthemechameleon, beamerouterthemedecolines,
beamerinnerthemefancy, boiboites, multiaudience) y una fuente empaquetada
en el propio repositorio. Didacta no depende de ninguno: los teoremas con caja
los hace tcolorbox y las audiencias están implementadas directamente.