Vai al contenuto
Topos Uranos
Italiano

La struttura del documento: sintesi e sfide

Riepilogo

Questa lezione chiude la terza unità del corso, dedicata alla struttura del documento. Ricostruisce la catena di decisioni e di meccanismi che va dalla classe del documento al preambolo personale, indicando in ogni anello quale principio si usa e in quale lezione si stabilisce; colloca ciò che si è ottenuto rispetto al piano del corso e precisa quali questioni, appena anticipate, restano per le unità successive; ripete nella sua valutazione d’uscita le competenze della valutazione d’ingresso; e termina con sei sfide, di difficoltà superiore a quella dei problemi delle lezioni, che richiedono di combinarne diverse per progettare una tesi a partire dalle sue norme, prevedere la numerazione e i rinvii di un libro e diagnosticare documenti divisi che falliscono o che mentono.

Obiettivi di apprendimento

  1. Ricostruire l’ordine delle decisioni e dei meccanismi dell’unità, individuando il principio su cui ciascuno si fonda.
  2. Spiegare come la numerazione, l’indice, i rinvii e la compilazione parziale dipendano dai file ausiliari.
  3. Distinguere ciò che l’unità ha stabilito da ciò che ha soltanto anticipato e che le unità successive svilupperanno.
  4. Diagnosticare documenti divisi in più file che falliscono, o che si compilano con numeri falsi, ordinando le correzioni.
  5. Progettare la classe, la pagina, le parti, i rinvii e i file di una tesi a partire dalle norme che deve rispettare.

Ciò che l’unità ha ottenuto

L’unità si era proposta di dare al documento un’architettura i cui numeri, il cui indice e i cui rinvii restino veri attraverso tutte le sue modifiche. Lo scopo è stato raggiunto appoggiandosi su ciò che l’introduzione dava per noto dalle unità precedenti: le passate della compilazione, la divisione tra preambolo e corpo, e la marcatura logica. Con ciò, il cammino percorso si può leggere come un’unica catena in cinque tratti.

Classi di documento e pagina

La lezione sulle classi di documento e la pagina ha stabilito che la classe decide quali divisioni esistono, che cosa fa \maketitle, se c’è un sommario e se le pagine pari si distinguono dalle dispari; ne ha dedotto un criterio per scegliere tra article, report e book secondo la struttura e la stampa, e ha presentato le classi di KOMA-Script, con l’opzione es-noquoting che la loro combinazione con lo spagnolo richiede nella versione di TeX Live di questi esempi. Ha percorso le opzioni di classe, ha spiegato perché i margini dipendono dalla lunghezza della riga e come fissarli con geometry, e si è chiusa con gli stili di pagina, che alcuni comandi della classe impongono per conto proprio.

Sezioni, indice e appendici

La lezione sulle sezioni, l’indice e le appendici ha composto i dati del titolo e il sommario, ha ordinato i livelli di divisione e ha stabilito che due contatori indipendenti, secnumdepth e tocdepth, decidono che cosa si numera e che cosa entra nell’indice. Ha spiegato che l’indice si compone con ciò che la passata precedente ha annotato, senza avviso quando resta non aggiornato; che \appendix cambia la numerazione di ciò che la segue; e che un libro ha tre parti, con due numerazioni di pagina, il cui ordine non è indifferente.

Riferimenti incrociati

La lezione sui riferimenti incrociati ha stabilito il principio da cui dipende ogni rinvio: un’etichetta registra l’ultimo numero assegnato prima di essa, all’interno del suo ambiente. Ne ha dedotto dove va l’etichetta in ogni elemento, perché un’etichetta prima della didascalia di una figura rinvia alla sezione e perché una sezione senza numero non ha un numero proprio a cui rinviare. Ha mostrato che, dopo una modifica, una sola compilazione stampa i numeri precedenti con ogni apparenza di correttezza, e ha presentato hyperref, che va caricato alla fine dei pacchetti, e cleveref, che va dopo di esso, abbrevia «fig.» ed «eq.» e il cui nome «equazione», scritto per intero, chiede l’elisione dell’articolo.

Documenti lunghi

La lezione sui documenti lunghi ha ripartito un documento in un file principale e in parti senza preambolo. Ha distinto \input, una sostituzione letterale, da \include, che apre pagina, scrive un file ausiliario proprio e ammette \includeonly, la cui numerazione dipende dai file ausiliari di una compilazione completa precedente. Ha stabilito che i percorsi si scrivono a partire dalla cartella del file principale, che in Texmaker si dichiara il documento master, e ha passato in rassegna gli errori propri dei documenti divisi, tra cui due silenziosi: la parte che \include non trova e la parte con preambolo, il cui \end{document} termina la tesi.

Macro e preambolo personale

La lezione sulle macro e il preambolo personale ha fatto della marcatura logica un metodo: \newcommand con argomenti e con un argomento opzionale, la protezione che impedisce di ridefinire un nome già occupato, lo spazio che si perde dopo un comando senza argomenti, \NewDocumentCommand, gli ambienti propri, i cui argomenti esistono solo nell’apertura, e il preambolo portato in un file o in un pacchetto, che non deve imporre la classe, la lingua né la posizione di hyperref.

La figura seguente riunisce i cinque tratti in un’unica catena. Ogni nodo della colonna è una decisione o un meccanismo, numerato secondo l’ordine in cui si appoggiano gli uni sugli altri e unito da un arco agli anelli precedenti che usa; intorno fluttuano gli appoggi, cioè i principi a cui la catena ricorre di continuo, ciascuno unito con un tratto pieno agli anelli che si appoggiano su di esso e con uno punteggiato all’anello in cui si stabilisce, tranne quelli stabiliti in unità precedenti, che si disegnano come anelli vuoti. Facendo clic su un appoggio si evidenziano tutti gli anelli che lo usano, e ogni anello rinvia alla lezione in cui si studia.

Sostegni della catena

  • APassate. Il motore annota nei file ausiliari i numeri, i titoli e le pagine in una passata, e li usa nella successiva. Si stabilisce nella prima unità. Ammesso senza dimostrazione in questa unità.
  • BPreambolo e corpo. Il preambolo configura e carica i pacchetti, e il corpo compone; ciò che si limita a definire o a memorizzare può stare in entrambi. Si stabilisce nella prima unità. Ammesso senza dimostrazione in questa unità.
  • CContenuto e forma. L’autore dichiara che cosa è ogni cosa, e una decisione presa altrove fissa come appare. Si stabilisce nelle unità precedenti. Ammesso senza dimostrazione in questa unità.
  • DLa classe decide. La classe del documento decide quali divisioni esistono, che cosa compone il titolo, se c’è un sommario, come si ripartiscono le pagine e quale stile impongono i suoi comandi. Stabilito in: 1. Tre classi standard.
  • ECiò che registra un’etichetta. Un’etichetta registra l’ultimo numero assegnato prima di essa, all’interno del suo ambiente, senza sapere a che cosa è unita. Stabilito in: 11. Etichette e riferimenti.
  • FOrdine di caricamento. I pacchetti si caricano nell’ordine in cui vengono letti, e uno successivo può disfare ciò che ha fatto uno precedente: hyperref va alla fine, e cleveref dopo di esso. Stabilito in: 13. Collegamenti.
  • GIl file principale. Si compila sempre il file principale; le parti sono frammenti del suo corpo, senza preambolo, e i loro percorsi si scrivono a partire dalla cartella del principale. Stabilito in: 16. Il comando include.

  1. Tratto 1 Classi di documento e pagina

    • Scegliere la classe secondo la struttura e la stampa del documento.
    • Dichiarare le opzioni di classe e prevederne l’effetto.
    • Fissare i margini con geometry senza allungare troppo la riga.
    • Prevedere e cambiare gli stili di pagina, le testatine e i piedini.

    1. Tre classi standard. article non ha capitoli; report li ha, con titolo e sommario su pagine proprie; book stampa fronte e retro e non ha sommario.

      Si appoggia su: B (Preambolo e corpo). Dimostrato in: Classi di documento e pagina.

    2. KOMA-Script. scrartcl, scrreprt e scrbook corrispondono alle standard con scelte europee; con babel in spagnolo richiedono, in questa versione, l’opzione es-noquoting.

      Usa: 1. Tre classi standard. Si appoggia su: C (Contenuto e forma). Dimostrato in: Classi di documento e pagina.

    3. Opzioni di classe. Carta, corpo del carattere, una o due facciate, frontespizio, inizio dei capitoli e bozza si dichiarano nella prima riga.

      Usa: 1. Tre classi standard. Si appoggia su: D (La classe decide). Dimostrato in: Classi di documento e pagina.

    4. Margini. geometry calcola la pagina a partire da poche misure; la larghezza dello specchio di stampa fissa la lunghezza della riga, che è ciò che il lettore patisce.

      Usa: 3. Opzioni di classe. Si appoggia su: B (Preambolo e corpo). Dimostrato in: Classi di documento e pagina.

    5. Stili di pagina. Lo stile decide testatine e piedini; \maketitle e \chapter impongono alla loro pagina lo stile plain, e fancyhdr o scrlayer-scrpage compongono stili propri.

      Usa: 1. Tre classi standard, 4. Margini. Si appoggia su: D (La classe decide). Dimostrato in: Classi di documento e pagina.

  2. Tratto 2 Sezioni, indice e appendici

    • Comporre il titolo e il sommario secondo la classe.
    • Scegliere il livello di divisione e prevedere la numerazione e l’indice.
    • Produrre l’indice e gli elenchi, sapendo da quale passata dipendono.
    • Ordinare le appendici e le parti di un libro.

    1. Titolo e sommario. \title, \author e \date memorizzano, \maketitle compone; l’ambiente abstract esiste in article e report, non in book.

      Usa: 1. Tre classi standard. Si appoggia su: D (La classe decide), B (Preambolo e corpo). Dimostrato in: Sezioni, indice e appendici.

    2. Livelli di divisione. Sette livelli, dalla parte al sottoparagrafo; il capitolo esiste solo in report e book, e la gerarchia non si sceglie in base alla dimensione del titolo.

      Usa: 1. Tre classi standard. Si appoggia su: D (La classe decide). Dimostrato in: Sezioni, indice e appendici.

    3. Numerazione e indice. secnumdepth decide quali livelli si numerano e tocdepth quali entrano nell’indice; la forma con asterisco non numera né consuma numero.

      Usa: 7. Livelli di divisione. Si appoggia su: C (Contenuto e forma). Dimostrato in: Sezioni, indice e appendici.

    4. Indice ed elenchi. L’indice compone ciò che la passata precedente ha annotato nel file .toc, e non avvisa quando resta non aggiornato.

      Usa: 7. Livelli di divisione, 8. Numerazione e indice. Si appoggia su: A (Passate). Dimostrato in: Sezioni, indice e appendici.

    5. Appendici e parti del libro. \appendix cambia la numerazione di ciò che segue; in book, le pagine preliminari, il corpo del testo e le pagine finali hanno due numerazioni, e le appendici vengono prima di \backmatter.

      Usa: 7. Livelli di divisione, 5. Stili di pagina. Si appoggia su: D (La classe decide). Dimostrato in: Sezioni, indice e appendici.

  3. Tratto 3 Riferimenti incrociati

    • Collocare e nominare le etichette.
    • Prevedere che cosa stampa un riferimento dopo una o due passate.
    • Caricare hyperref e cleveref nel loro ordine.
    • Rinviare con il nome e il numero, o con il titolo.

    1. Etichette e riferimenti. \label segna un luogo, \ref e \pageref ne scrivono il numero e la pagina, con due passate.

      Usa: 7. Livelli di divisione. Si appoggia su: A (Passate). Dimostrato in: Riferimenti incrociati.

    2. Dove va l’etichetta. Dopo il comando che assegna il numero e dentro lo stesso ambiente: dopo \section, dopo \caption; con un prefisso che dica che cosa designa.

      Usa: 11. Etichette e riferimenti. Si appoggia su: E (Ciò che registra un’etichetta). Dimostrato in: Riferimenti incrociati.

    3. Collegamenti. hyperref trasforma i riferimenti, l’indice e le note in collegamenti e le sezioni in segnalibri, e si carica alla fine dei pacchetti.

      Usa: 11. Etichette e riferimenti, 9. Indice ed elenchi. Si appoggia su: B (Preambolo e corpo). Dimostrato in: Riferimenti incrociati.

    4. Riferimenti con il nome. cleveref scrive il nome e il numero, in italiano «sezione», «fig.», «eq.», regolabili con l’opzione noabbrev o con \crefname; nameref rinvia tramite il titolo.

      Usa: 13. Collegamenti, 12. Dove va l’etichetta. Si appoggia su: E (Ciò che registra un’etichetta), F (Ordine di caricamento). Dimostrato in: Riferimenti incrociati.

  4. Tratto 4 Documenti lunghi

    • Scegliere tra \input e \include per ogni parte.
    • Prevedere che cosa conserva \includeonly.
    • Organizzare le cartelle e dichiarare il documento master.
    • Riconoscere gli errori, rumorosi e silenziosi, dei documenti divisi.

    1. Il comando input. \input inserisce un file come se il suo testo fosse scritto al suo posto, senza interrompere la pagina né creare file ausiliari.

      Si appoggia su: B (Preambolo e corpo). Dimostrato in: Documenti lunghi.

    2. Il comando include. \include apre pagina prima e dopo, scrive un file ausiliario proprio per ogni parte e non si può annidare.

      Usa: 15. Il comando input, 7. Livelli di divisione. Si appoggia su: A (Passate). Dimostrato in: Documenti lunghi.

    3. Compilazione parziale. \includeonly compone solo le parti scelte e numera le altre con i loro file ausiliari, che devono provenire da una compilazione completa posteriore alla loro ultima modifica.

      Usa: 16. Il comando include, 11. Etichette e riferimenti. Si appoggia su: A (Passate). Dimostrato in: Documenti lunghi.

    4. Cartelle e documento master. Un file principale nella radice, parti in cartelle, percorsi a partire dal principale, nomi semplici, e in Texmaker il principale come documento master.

      Usa: 16. Il comando include. Si appoggia su: G (Il file principale). Dimostrato in: Documenti lunghi.

    5. Errori dei documenti divisi. Un \input senza file ferma la compilazione; un \include senza file annota soltanto «No file»; una parte con preambolo termina la tesi al suo \end{document}.

      Usa: 16. Il comando include, 18. Cartelle e documento master. Si appoggia su: G (Il file principale), B (Preambolo e corpo). Dimostrato in: Documenti lunghi.

  5. Tratto 5 Macro e preambolo personale

    • Definire comandi con argomenti e un argomento opzionale.
    • Distinguere definire, ridefinire e fornire, ed evitare lo spazio perduto.
    • Definire ambienti propri.
    • Riunire il preambolo in un file o in un pacchetto.

    1. Comandi propri. \newcommand definisce un comando con al massimo nove argomenti, il primo opzionale con il suo valore predefinito; nomina una funzione che si ripete.

      Si appoggia su: C (Contenuto e forma). Dimostrato in: Macro e preambolo personale.

    2. Nomi occupati e spazi. \newcommand rifiuta un nome esistente e \renewcommand uno inesistente; un comando senza argomenti consuma lo spazio che lo segue.

      Usa: 20. Comandi propri. Si appoggia su: B (Preambolo e corpo). Dimostrato in: Macro e preambolo personale.

    3. Ambienti propri. \newenvironment definisce apertura e chiusura; i suoi argomenti esistono solo nell’apertura, e \NewDocumentEnvironment li ammette anche nella chiusura.

      Usa: 20. Comandi propri. Si appoggia su: C (Contenuto e forma). Dimostrato in: Macro e preambolo personale.

    4. Preambolo personale. Il preambolo si porta in un file letto con \input o in un pacchetto .sty, che non impone la classe, la lingua né la posizione di hyperref.

      Usa: 20. Comandi propri, 21. Nomi occupati e spazi, 15. Il comando input, 13. Collegamenti. Si appoggia su: F (Ordine di caricamento), C (Contenuto e forma). Dimostrato in: Macro e preambolo personale.

Verso la matematica. La catena si ferma dove l’architettura è completa e resta da riempire: le equazioni e i teoremi numerati, a cui si rinvierà con le etichette di questa unità, sono l’oggetto della successiva.