La estructura del documento: síntesis y desafíos

Resumen

Esta clase cierra la tercera unidad del curso, dedicada a la estructura del documento. Reconstruye la cadena de decisiones y mecanismos que va de la clase del documento al preámbulo propio, señalando en cada eslabón qué principio se usa y en qué clase se establece; sitúa lo logrado respecto del plan del curso y precisa qué cuestiones, apenas anticipadas, quedan para las unidades siguientes; repite en su evaluación de salida las destrezas de la evaluación de entrada; y termina con seis desafíos, de dificultad superior a la de los problemas de las clases, que exigen combinar varias de ellas para planificar una tesis a partir de sus normas, predecir la numeración y las remisiones de un libro y diagnosticar documentos divididos que fallan o que mienten.

Objetivos de aprendizaje

Reconstruir el orden de las decisiones y los mecanismos de la unidad, identificando el principio en que se apoya cada uno.
Explicar cómo dependen la numeración, el índice, las remisiones y la compilación parcial de los archivos auxiliares.
Distinguir lo que la unidad estableció de lo que solo anticipó y que las unidades siguientes desarrollarán.
Diagnosticar documentos divididos en varios archivos que fallan, o que compilan con números falsos, ordenando las correcciones.
Planificar la clase, la página, las partes, las remisiones y los archivos de una tesis a partir de las normas que debe cumplir.

Lo logrado en la unidad

La unidad se propuso dar al documento una arquitectura cuyos números, índice y remisiones sigan siendo verdaderos a través de todos sus cambios. El propósito se ha cumplido apoyándose en lo que la introducción declaró por sabido de las unidades anteriores: las pasadas de la compilación, la división entre el preámbulo y el cuerpo, y el marcado lógico. Con ello, el camino recorrido puede leerse como una sola cadena en cinco tramos.

Clases de documento y página

La clase sobre las clases de documento y la página estableció que la clase decide qué divisiones existen, qué hace \maketitle, si hay resumen y si las páginas pares se distinguen de las impares; de ello dedujo un criterio para elegir entre article, report y book según la estructura y la impresión, y presentó las clases de KOMA-Script, con la opción es-noquoting que su combinación con el español exige en la versión de TeX Live de estos ejemplos. Recorrió las opciones de la clase, explicó por qué los márgenes dependen de la longitud de la línea y cómo fijarlos con geometry, y terminó con los estilos de página, que algunas instrucciones de la clase imponen por su cuenta.

Secciones, índice y apéndices

La clase sobre las secciones, el índice y los apéndices compuso los datos del título y el resumen, ordenó los niveles de división y estableció que dos contadores independientes, secnumdepth y tocdepth, deciden qué se numera y qué entra en el índice. Explicó que el índice se compone con lo que la pasada anterior anotó, sin advertencia cuando queda desactualizado; que \appendix cambia la numeración de lo que la sigue; y que un libro tiene tres partes, con dos numeraciones de página, cuyo orden no es indiferente.

Referencias cruzadas

La clase sobre las referencias cruzadas estableció el principio del que depende toda remisión: una etiqueta registra el último número asignado antes de ella, dentro de su entorno. De él dedujo dónde va la etiqueta en cada elemento, por qué una etiqueta antes del pie de una figura remite a la sección y por qué una sección sin número no tiene número propio al que remitir. Mostró que, tras un cambio, una sola compilación imprime los números anteriores con toda apariencia de corrección, y presentó hyperref, que debe cargarse al final de los paquetes, y cleveref, que va después de él y que en español llama «apartado» a las secciones.

Documentos largos

La clase sobre los documentos largos repartió un documento en un archivo principal y piezas sin preámbulo. Distinguió \input, una sustitución literal, de \include, que abre página, escribe un auxiliar propio y admite \includeonly, cuya numeración depende de los auxiliares de una compilación completa anterior. Estableció que las rutas se escriben desde la carpeta del archivo principal, que en Texmaker se declara el documento maestro, y recorrió los errores propios de los documentos divididos, entre ellos dos silenciosos: la pieza que no se encuentra con \include y la pieza con preámbulo, cuyo \end{document} termina la tesis.

Macros y preámbulo propio

La clase sobre las macros y el preámbulo propio convirtió en método el marcado lógico: \newcommand con argumentos y con un opcional, la protección que impide redefinir un nombre ocupado, el espacio que se pierde tras una instrucción sin argumentos, \NewDocumentCommand, los entornos propios, cuyos argumentos solo existen en la apertura, y el preámbulo llevado a un archivo o a un paquete, que no debe imponer la clase, el idioma ni la posición de hyperref.

La figura siguiente reúne los cinco tramos en una sola cadena. Cada nudo de la columna es una decisión o un mecanismo, numerado según el orden en que se apoyan unos en otros y unido por un arco a los eslabones anteriores que usa; alrededor flotan los apoyos, es decir, los principios a los que la cadena recurre una y otra vez, cada uno unido con un trazo firme a los eslabones que se apoyan en él y con uno punteado al eslabón donde se establece, salvo los que se establecieron en unidades anteriores, que se dibujan como anillos. Al pulsar un apoyo se destacan todos los eslabones que lo usan, y cada eslabón remite a la clase en que se estudia.

Apoyos de la cadena

APasadas. El motor anota en los archivos auxiliares los números, los títulos y las páginas en una pasada, y los usa en la siguiente. Se establece en la primera unidad. Se admite sin demostración en esta unidad.
BPreámbulo y cuerpo. El preámbulo configura y carga los paquetes, y el cuerpo compone; lo que solo define o guarda puede ir en ambos. Se establece en la primera unidad. Se admite sin demostración en esta unidad.
CContenido y forma. El autor declara qué es cada cosa, y una decisión tomada en otro lugar fija cómo se ve. Se establece en las unidades anteriores. Se admite sin demostración en esta unidad.
DLa clase decide. La clase del documento decide qué divisiones existen, qué compone el título, si hay resumen, cómo se reparten las páginas y qué estilo imponen sus instrucciones. Se establece en: 1. Tres clases estándar.
ELo que registra una etiqueta. Una etiqueta registra el último número asignado antes de ella, dentro de su entorno, sin saber a qué está unida. Se establece en: 11. Etiquetas y referencias.
FOrden de carga. Los paquetes se cargan en el orden en que se leen, y uno posterior puede deshacer lo que hizo uno anterior: hyperref va al final, y cleveref después de él. Se establece en: 13. Enlaces.
GEl archivo principal. Se compila siempre el archivo principal; las piezas son fragmentos de su cuerpo, sin preámbulo, y sus rutas se escriben desde la carpeta del principal. Se establece en: 16. La instrucción include.

Tramo 1 Clases de documento y página
- Elegir la clase por la estructura y la impresión del documento.
- Declarar las opciones de la clase y predecir su efecto.
- Fijar los márgenes con geometry sin alargar la línea en exceso.
- Predecir y cambiar los estilos de página, los encabezados y los pies.
1. Tres clases estándar. article no tiene capítulos; report los tiene, con título y resumen en páginas propias; book imprime a dos caras y no tiene resumen.
  Se apoya en: B (Preámbulo y cuerpo). Se demuestra en: Clases de documento y página.
2. KOMA-Script. scrartcl, scrreprt y scrbook corresponden a las estándar con decisiones europeas; con babel en español requieren, en esta versión, la opción es-noquoting.
  Usa: 1. Tres clases estándar. Se apoya en: C (Contenido y forma). Se demuestra en: Clases de documento y página.
3. Opciones de la clase. Papel, cuerpo de letra, una o dos caras, página de título, comienzo de los capítulos y borrador se declaran en la primera línea.
  Usa: 1. Tres clases estándar. Se apoya en: D (La clase decide). Se demuestra en: Clases de documento y página.
4. Márgenes. geometry calcula la página a partir de unas pocas medidas; el ancho de la caja fija la longitud de la línea, que es lo que el lector padece.
  Usa: 3. Opciones de la clase. Se apoya en: B (Preámbulo y cuerpo). Se demuestra en: Clases de documento y página.
5. Estilos de página. El estilo decide encabezados y pies; \maketitle y \chapter imponen el estilo plain a su página, y fancyhdr o scrlayer-scrpage componen estilos propios.
  Usa: 1. Tres clases estándar, 4. Márgenes. Se apoya en: D (La clase decide). Se demuestra en: Clases de documento y página.
Tramo 2 Secciones, índice y apéndices
- Componer el título y el resumen según la clase.
- Elegir el nivel de división y predecir la numeración y el índice.
- Producir el índice y las listas, sabiendo de qué pasada dependen.
- Ordenar los apéndices y las partes de un libro.
1. Título y resumen. \title, \author y \date guardan, \maketitle compone; el entorno abstract existe en article y report, no en book.
  Usa: 1. Tres clases estándar. Se apoya en: D (La clase decide), B (Preámbulo y cuerpo). Se demuestra en: Secciones, índice y apéndices.
2. Niveles de división. Siete niveles, de la parte al subpárrafo; el capítulo solo existe en report y book, y la jerarquía no se elige por el tamaño del título.
  Usa: 1. Tres clases estándar. Se apoya en: D (La clase decide). Se demuestra en: Secciones, índice y apéndices.
3. Numeración e índice. secnumdepth decide qué niveles se numeran y tocdepth cuáles entran en el índice; la forma con asterisco no numera ni consume número.
  Usa: 7. Niveles de división. Se apoya en: C (Contenido y forma). Se demuestra en: Secciones, índice y apéndices.
4. Índice y listas. El índice compone lo que la pasada anterior anotó en el archivo .toc, y no advierte cuando queda desactualizado.
  Usa: 7. Niveles de división, 8. Numeración e índice. Se apoya en: A (Pasadas). Se demuestra en: Secciones, índice y apéndices.
5. Apéndices y partes del libro. \appendix cambia la numeración de lo que sigue; en book, las páginas preliminares, el cuerpo y las finales tienen dos numeraciones, y los apéndices van antes de \backmatter.
  Usa: 7. Niveles de división, 5. Estilos de página. Se apoya en: D (La clase decide). Se demuestra en: Secciones, índice y apéndices.
Tramo 3 Referencias cruzadas
- Ubicar y nombrar las etiquetas.
- Prever lo que imprime una referencia tras una o dos pasadas.
- Cargar hyperref y cleveref en su orden.
- Remitir con el nombre y el número, o con el título.
1. Etiquetas y referencias. \label marca un lugar, \ref y \pageref escriben su número y su página, con dos pasadas.
  Usa: 7. Niveles de división. Se apoya en: A (Pasadas). Se demuestra en: Referencias cruzadas.
2. Dónde va la etiqueta. Después de la instrucción que asigna el número y dentro del mismo entorno: tras \section, tras \caption; con un prefijo que diga qué designa.
  Usa: 11. Etiquetas y referencias. Se apoya en: E (Lo que registra una etiqueta). Se demuestra en: Referencias cruzadas.
3. Enlaces. hyperref convierte las referencias, el índice y las notas en enlaces y las secciones en marcadores, y se carga al final de los paquetes.
  Usa: 11. Etiquetas y referencias, 9. Índice y listas. Se apoya en: B (Preámbulo y cuerpo). Se demuestra en: Referencias cruzadas.
4. Referencias con nombre. cleveref escribe el nombre y el número, en español «apartado» para las secciones, ajustable con \crefname; nameref remite por el título.
  Usa: 13. Enlaces, 12. Dónde va la etiqueta. Se apoya en: E (Lo que registra una etiqueta), F (Orden de carga). Se demuestra en: Referencias cruzadas.
Tramo 4 Documentos largos
- Elegir entre \input e \include para cada pieza.
- Predecir lo que conserva \includeonly.
- Organizar las carpetas y declarar el documento maestro.
- Reconocer los errores, ruidosos y silenciosos, de los documentos divididos.
1. La instrucción input. \input inserta un archivo como si su texto estuviera escrito en su lugar, sin cortar la página ni crear auxiliares.
  Se apoya en: B (Preámbulo y cuerpo). Se demuestra en: Documentos largos.
2. La instrucción include. \include abre página antes y después, escribe un auxiliar propio por pieza y no puede anidarse.
  Usa: 15. La instrucción input, 7. Niveles de división. Se apoya en: A (Pasadas). Se demuestra en: Documentos largos.
3. Compilación parcial. \includeonly compone solo las piezas elegidas y numera las demás con sus auxiliares, que deben venir de una compilación completa posterior a su último cambio.
  Usa: 16. La instrucción include, 11. Etiquetas y referencias. Se apoya en: A (Pasadas). Se demuestra en: Documentos largos.
4. Carpetas y documento maestro. Un archivo principal en la raíz, piezas en carpetas, rutas desde el principal, nombres sencillos, y en Texmaker el principal como documento maestro.
  Usa: 16. La instrucción include. Se apoya en: G (El archivo principal). Se demuestra en: Documentos largos.
5. Errores de los documentos divididos. Un \input sin archivo detiene la compilación; un \include sin archivo solo anota «No file»; una pieza con preámbulo termina la tesis en su \end{document}.
  Usa: 16. La instrucción include, 18. Carpetas y documento maestro. Se apoya en: G (El archivo principal), B (Preámbulo y cuerpo). Se demuestra en: Documentos largos.
Tramo 5 Macros y preámbulo propio
- Definir instrucciones con argumentos y un opcional.
- Distinguir definir, redefinir y proveer, y evitar el espacio perdido.
- Definir entornos propios.
- Reunir el preámbulo en un archivo o en un paquete.
1. Instrucciones propias. \newcommand define una instrucción con hasta nueve argumentos, el primero opcional con su valor predeterminado; nombra una función que se repite.
  Se apoya en: C (Contenido y forma). Se demuestra en: Macros y preámbulo propio.
2. Nombres ocupados y espacios. \newcommand rechaza un nombre existente y \renewcommand uno inexistente; una instrucción sin argumentos consume el espacio que la sigue.
  Usa: 20. Instrucciones propias. Se apoya en: B (Preámbulo y cuerpo). Se demuestra en: Macros y preámbulo propio.
3. Entornos propios. \newenvironment define apertura y cierre; sus argumentos solo existen en la apertura, y \NewDocumentEnvironment los admite también en el cierre.
  Usa: 20. Instrucciones propias. Se apoya en: C (Contenido y forma). Se demuestra en: Macros y preámbulo propio.
4. Preámbulo propio. El preámbulo se lleva a un archivo leído con \input o a un paquete .sty, que no impone la clase, el idioma ni la posición de hyperref.
  Usa: 20. Instrucciones propias, 21. Nombres ocupados y espacios, 15. La instrucción input, 13. Enlaces. Se apoya en: F (Orden de carga), C (Contenido y forma). Se demuestra en: Macros y preámbulo propio.

Hacia la matemática. La cadena se detiene donde la arquitectura está completa y falta llenarla: las ecuaciones y los teoremas numerados, que se remitirán con las etiquetas de esta unidad, son el objeto de la siguiente.