Snodi

Snodi è un libro digitale di matematica per la scuola Secondaria di Secondo grado, pensato principalmente per il secondo biennio e quinto anno di corso.

Il codice sorgente è basato su PreTeXt: il file principale del libro è source/main.ptx e da questo, per mezzo di xi:include, si includono gli altri capitoli del libro.
Il libro è stato compilato e verificato con la versione 2.42.0 di PreTeXt. La versione web del libro è disponibile su GitHub Pages.

Per compilare la versione web localmente, dopo aver clonato il progetto da GitHub, eseguire pretext build html e per vederlo eseguire pretext view html.
Per generare un pdf statico (perdendo gli esercizi interattivi), eseguire pretext build pdf.

Licenza

Questo progetto è rilasciato sotto la licenza Creative Commons Attribuzione - Non commerciale - Condividi allo stesso modo 4.0 Internazionale (CC BY-NC-SA 4.0).

Guida per gli autori

Il libro è scritto con PreTeXt, un linguaggio di markup basato su XML. Questo significa che ogni blocco di testo, formula o struttura deve essere racchiuso tra un tag di apertura (es. ) e uno di chiusura (es. ).
A seguire vengono presentati i principali tag XML di PreTeXt: all’inizio di ogni sezione c’è il riferimento dettagliato al manuale di PreTeXt. Sono disponibili anche gli esempi qui e qui.

Struttura del codice

Riferimenti al manuale di PreTeXt: struttura, riferimenti incrociati

La struttura gerarchica (del libro e del codice) si sviluppa dal contenitore più grande (capitolo) a quello più piccolo (sezione, sottosezione). Ogni blocco deve sempre avere un titolo (<title>).

Ecco lo scheletro di base da seguire nel file del capitolo:

<?xml version='1.0' encoding='utf-8'?>

<chapter xml:id="ch-mio-capitolo" xmlns:xi="http://www.w3.org/2001/XInclude">
  <title>Titolo del capitolo</title>

  <introduction>
    <p>Introduzione opzionale</p>
  </introduction>

  <xi:include href="./sec-prima-sezione.ptx" />
  <xi:include href="./sec-seconda-sezione.ptx" />
  ...
</chapter>

Per un file di sezione:

<?xml version='1.0' encoding='utf-8'?>

<section xml:id="sec-mia-sezione" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>Titolo della sezione</title>

<author><xref ref="ref-autore"/></author>

<introduction>
  <p>Introduzione opzionale</p>
</introduction>

<subsection>
  <title>Titolo della prima sotto-sezione</title>
  <p>Qui va il testo...</p>
  </definition>
</subsection>

<subsection>
  <title>Titolo della seconda sotto-sezione</title>
  <p>Qui va il testo...</p>
  </definition>
</subsection>

...

</section>

Il tag author (uno per ogni autore) deve essere coerente con contributors.ptx.

Paragrafi

Riferimenti al manuale di PreTeXt: paragrafi, affiancare più oggetti

In PreTeXt, il testo normale non può fluttuare libero: deve sempre essere dentro un paragrafo .
Esempio: Questo è un paragrafo.

Esistono dei particolari tag per certi scopi:

<term> per l’uso di un termine per la prima volta, per esempio nelle definizioni
<alert> per far risaltare un possibile punto critico, come una condizione di esistenza o un errore comune
 (da usare raramente) per enfatizzare del testo in maniera leggera
<foreign> per indicare delle parole non in italiano (deve essere corredato dal parametro xml:lang per indicare in che lingua è scritto, assegnando il valore “en” per l’inglese, “la” per il latino, eccetera)
<q> per fare il virgolettato (non si usa il simbolo " o ')

Per parti rilevanti del libro (come definizioni, assiomi, teoremi, procedure, ecc.) è opportuno includere l’indicizzazione dell’elemento. Ci sono due indici: quello della notazione (i simboli) e quello analitico (termini, teoremi, definizioni). Il primo si fa con il tag <notation> con all’interno ulteriori tag <usage> e <description>; il secondo si fa con il tag <idx> al cui interno si usano ulteriori tag <h> per strutturare l’indice analitico.

Matematica

PreTeXt usa la sintassi LaTeX per la matematica.

Formule

Riferimenti al manuale di PreTeXt: matematica, buone pratiche

Formula in linea (nel testo): si usa il tag <m>
Formula centrata (a blocco): si usa il tag <md>

Esempi:

PreTeXt	Risultato
`<p>La nota equazione <m>E = mc^2</m> di Einstein.</p>`	La nota equazione $E=mc^2$ di Einstein.
`<md> \frac{x^2+2x-2}{x-1} </md>`	$$\frac{x^2+2x-2}{x-1}$$
`<md> \left( x^2-1 \right)^3 \cdot \sqrt{x+1} </md>`	$$\left( x^2-1 \right)^3 \cdot \sqrt{x+1}$$
`<md> f(x) = a_0 + \sum_{i=1}^N a_i x^i </md>`	$$f(x) = a_0 + \sum_{i=1}^N a_i x^i$$
`<md> \int_0^{+\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2} </md>`	$$\int_0^{+\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}$$

Per scrivere queste formule ci vuole tempo! Le opzioni sono due: imparare la formattazione LaTeX oppure scrivere la formula su MS Word e convertirla (cosa che non sempre funziona benissimo). Nel secondo caso, dopo aver scritto la formula con il tool Equazione, seleziona la formula, nella scheda Equazione clicca su LaTeX nella parte delle conversioni e poi Converti > Lineare.

Teoremi, definizioni e assiomi

Riferimenti al manuale di PreTeXt: assiomi, teoremi e definizioni

I teoremi hanno una struttura base che include un titolo <title>, l'enunciato del teorema <statement> e una dimostrazione <proof> se necessaria.

<theorem xml:id="thm-nome-teorema">
  <title>Teorema di ...</title>

  <statement>
    <p>Enunciato del teorema ...</p>
  </statement>

  <proof>
    <p>Dimostrazione ...</p>
  </proof>
</theorem>

Per le definizioni e gli assiomi, basta sostituire il tag <theorem> con <definition> o <axiom>. Ovviamente definizioni e assiomi non hanno una dimostrazione. La definizione può anche essere fatta anche con <term> in linea senza bisogno di un titolo.

Esempi

Riferimenti al manuale di PreTeXt: esempi

Gli esempi vanno inseriti nella sezione usando il tag <example>, che accetta un titolo <title>, una consegna <statement> e una soluzione dettagliata <solution>.

<example xml:id="ex-nome-esempio">
  <title>Titolo dell'esempio</title>

  <statement>
    <p>Consegna ...</p>
  </statement>

  <solution>
    <p>Soluzione dettagliata ...</p>
  </solution>
</example>

Esercizi

Riferimenti al manuale di PreTeXt: esercizi, esercizi interattivi

Gli esercizi possono essere inseriti direttamente nella sezione pertinente (senza dover fare una sezione a parte) usando il tag <exercise> e possono essere dotati di una soluzione dettagliata <solution> oltre che dalla risposta secca <answer>.

<exercise xml:id="exe-nome-esercizio">
  <title>Titolo opzionale ...</title>

  <statement>
    <p>Consegna ...</p>
  </statement>

  <answer>
    <p>Risultato</p>
  </answer>

  <solution>
    <p>Svolgimento dettagliato ...</p>
  </solution>
</exercise>

Gli esercizi interattivi (che esistono in varie forme secondo il manuale di PreTeXt) permettono al lettore di inserire e controllare i risultati in maniera più dinamica, ma richiedono una programmazione più dettagliata.

<exercise xml:id="exint-nome-esercizio">
  <title>&#9889; Titolo esercizio interattivo</title>
  <statement>
    <p>Consegna</p>
  </statement>

  <tag specifici del tipo di esercizio ...>
</exercise>

I generatori di esercizi sono probabilmente l'elemento più complesso del libro (dal punto di vista della programmazione) e vanno codificati seguendo le indicazioni del manuale di PreTeXt usando un apposito file PGML (WebWork) inserito in assets/pgml.

<exercise xml:id="exmkr-nome-esercizio">
  <title>&#x2728; Titolo generatore di esercizi</title>

  <webwork>
    <xi:include href="../../assets/pgml/exmkr-nome-file.pg" parse="text" />
  </webwork>
</exercise>

Comandi speciali

Sono stati creati appositamente per questo libro dei comandi per velocizzare la rappresentazione di certi elementi: il disegno della piccola parabola per le disequazioni di secondo grado (parabolina), il grafico dei segni (GraficoSegni) e il grafico delle linee (GraficoLinee). Questi tre comandi sono formalmente comandi TikZ/LaTeX, quindi vanno inseriti dentro un tag <latex-image>, a sua volta dentro un <image>.

Il comando parabolina[]{}{} richiede due argomenti obbligatori e ha un parametro opzionale:

[opzionale] concavità della parabola: 1 verso l’alto, -1 verso il basso (default: 1)
le soluzioni dell'equazione associata: se nessuna va lasciato vuoto, se 1 si indica il numero, se due si indica la lista ordinata dei due valori {x1,x2}
il verso della disuguaglianza da risolvere: g per maggiore e l per minore

Il comando GraficoSegni[]{}{} richiede due argomenti obbligatori e ha un parametro opzionale:

[opzionale] il simbolo della variabile sull'asse (default: x)
la lista dei numeri da mettere sull'asse orientato, per esempio {-1,\frac{1}{2},2}
la lista di liste con le righe da inserire (l'ultima verrà separata dalle altre con una riga), per esempio {{N/-,0,+,,+}, {D/+,,+,0,-}, {\frac{N}{D}/-,0,+,\nexists,-}}

Il comando GraficoLinee[]{}{} richiede due argomenti obbligatori e ha un parametro opzionale:

[opzionale] il simbolo della variabile sull'asse (default: x)
la lista dei numeri da mettere sull'asse orientato, per esempio {-1,2,3,5}
la lista di liste con l’indicazione degli intervalli: la riga su cui indicare l’intervallo (0 si usa per il risultato) e le parentesi a per un aperto e c per un chiuso, per esempio {{1/,a,,a,,}, {1/,,c,,c,}, {2/a,c,,,,}

Attributi `xml:id`

L'attributo xml:id nelle varie parti del libro serve per creare dei tag unici. Permette di fare riferimenti incrociati (es. si veda la Sezione 3 senza dover scrivere a mano i numeri, che nel tempo potrebbero cambiare). Per i tag xml:id vanno usati dei nomi unici, in minuscolo e separati da trattini.

Per scelta di ordine, l’attributo xml:id deve sempre iniziare con delle lettere per indicare certi tipi di elementi ed è obbligatorio in certe situazioni:

Elemento	Inizio `xml:id`	Obbligatorio
Capitolo	`ch-`	x
Sezioni	`sec-`	x
Sotto-sezioni	`subsec-`
Assiomi	`ax-`	x
Definizioni	`def-`	x
Teoremi	`thm-`	x
Esempi	`ex-`
Esercizi statici	`exe-`
Esercizi interattivi	`exint-`
Generatori di esercizi	`exmkr-`

Figure

Riferimenti al manuale di PreTeXt: immagini

Per scelta, le figure vanno scritte in codice LaTeX (con TikZ) e importate in un tag apposito oppure, se si usano immagini già pronte, bisogna verificarne i diritti di utilizzo prima di importarle. Tutte le immagini (già fatte o i loro codici LaTeX) vanno inserite nella cartella assets e da lì vengono incluse nel testo.

Per un’immagine già pronta si usa il tag <image> con attributi source per il percorso (che ha di default il root sulla cartella assets) e width per la larghezza.

Per un’immagine codificata in LaTeX si deve usare il tag <xi:include> con attributi href per il percorso (relativo al file .ptx in uso) verso il file .tex e parse=”text”. Questo va inserito in un tag <latex-image>, che a sua volta va inserito in un tag <image>.

I colori nelle figure non vanno scelti tra i seguenti colori nominali:

Nome	HTML	Colore
`col1`	#054FF0
`col2`	#DC0462
`col3`	#440E42
`col4`	#FA971F
`col5`	#FECB3E
`col6`	#21782E
`black`	#000000
`white`	#FFFFFF

come definiti in docinfo.ptx coerentemente con publication.ptx. Questo serve perché se si volesse/dovesse cambiare la palette di colori del libro in futuro, tutti i colori cambierebbero in automatico modificando solo poche righe di codice, senza dover modificare una a una tutte le immagini.

Per provare a creare delle immagini senza compilare tutto il libro ogni volta si può usare Overleaf con il seguente codice:

\documentclass[12pt]{article}
\usepackage[english]{babel}
\usepackage[utf8]{inputenc}
\usepackage[OT1,T1]{fontenc}

\usepackage{tikz, pgfplots, graphicx, amsmath, amssymb}
\pgfplotsset{compat=newest}

\newcommand{\N}{\mathbb N}
\newcommand{\Z}{\mathbb Z}
\newcommand{\Q}{\mathbb Q}
\newcommand{\R}{\mathbb R}
\newcommand{\C}{\mathbb C}

\definecolor{col1}{HTML}{054FF0} %blu
\definecolor{col2}{HTML}{DC0462} %rosso
\definecolor{col3}{HTML}{440E42} %viola scuro
\definecolor{col4}{HTML}{FA971F} %arancione
\definecolor{col5}{HTML}{FECB3E} %giallo
\definecolor{col6}{HTML}{21782E} %verde

\begin{document}
  \begin{tikzpicture}
    Codice da testare ...
  \end{tikzpicture}
\end{document}

Se vengono usate all'interno delle figure delle macro definite in source/docinfo.ptx, queste andranno copiate nel preambolo (prima di \begin{document}) su Overleaf.

Name		Name	Last commit message	Last commit date
Latest commit History 50 Commits
.github		.github
assets		assets
publication		publication
source		source
.error_schema.log		.error_schema.log
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
project.ptx		project.ptx
requirements.txt		requirements.txt

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Snodi

Licenza

Guida per gli autori

Struttura del codice

Paragrafi

Matematica

Formule

Teoremi, definizioni e assiomi

Esempi

Esercizi

Comandi speciali

Attributi `xml:id`

Figure

About

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Snodi

Licenza

Guida per gli autori

Struttura del codice

Paragrafi

Matematica

Formule

Teoremi, definizioni e assiomi

Esempi

Esercizi

Comandi speciali

Attributi xml:id

Figure

About

Resources

Stars

Watchers

Forks

Contributors

Languages

Attributi `xml:id`