move on a new branch

.gitea/workflows/build-pdf.yml

@@ -8,6 +8,9 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
+    env:
+      GIT_SSL_NO_VERIFY: "true"
+      NODE_EXTRA_CA_CERTS: /usr/local/share/ca-certificates/Egregge.crt
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -33,20 +36,18 @@ jobs:
 
       - name: Compile changed root files
         if: steps.changed.outputs.roots != ''
-        uses: docker://texlive/texlive:latest
+        uses: docker://texlive/texlive:latest-full
-        run: |
+        with:
-          mkdir -p pdf aux
+          entrypoint: sh
-          for f in ${{ steps.changed.outputs.roots }}; do
+          args: >-
-            echo "== Building $f =="
+            -c "mkdir -p pdf aux && for f in ${{ steps.changed.outputs.roots }}; do
-            latexmk -pdf -interaction=nonstopmode -halt-on-error \
+            echo Building $f;
-              -outdir=pdf -auxdir=aux "$f"
+            latexmk -pdf -interaction=nonstopmode -halt-on-error -outdir=pdf -auxdir=aux \"$f\" || exit 1;
-          done
+            done && find pdf -type f ! -name '*.pdf' -delete"
-          # keep pdf/ containing only pdfs
-          find pdf -type f ! -name '*.pdf' -delete
 
       - name: Upload built PDFs
         if: steps.changed.outputs.roots != ''
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v3
         with:
           name: pdf-output
           path: pdf/*.pdf

.gitignore

@@ -0,0 +1,3 @@
+./aux/*
+./*/aux/*
+*.gz

00_SetupLaTeX.tex

@@ -1,44 +1,286 @@
 \PassOptionsToPackage{pdftex}{graphics}
 \PassOptionsToPackage{pdftex}{color}
 \PassOptionsToPackage{pdftex}{xcolor}
-\documentclass{beamer}\usetheme{Metropolis}
+\documentclass[aspectratio=169]{beamer}
+\usepackage[utf8]{inputenc}
+\usepackage[T1]{fontenc}
+\usepackage{tabularx}
+\usepackage{booktabs}
+\usepackage{colortbl}
+\usepackage{tcolorbox}
+\usepackage{tikz}
+\tcbuselibrary{skins,breakable}
+
+% ---------- Tema ----------
+\usetheme{metropolis}
+\metroset{
+  block=fill,
+  progressbar=frametitle,
+  numbering=fraction,
+  sectionpage=progressbar,
+}
 \renewcommand{\footnotesize}{\scriptsize}
+
+% ---------- Palette ----------
+\definecolor{ForestPrimary}{HTML}{2E5339}
+\definecolor{ForestAccent}{HTML}{6BAA75}
+\definecolor{ForestLight}{HTML}{EAF2EB}
+\definecolor{ForestDark}{HTML}{1B2E22}
+\definecolor{WarnColor}{HTML}{B5651D}
+\definecolor{WarnLight}{HTML}{FBEBDD}
+\definecolor{TipColor}{HTML}{1F6F78}
+\definecolor{TipLight}{HTML}{E3F2F3}
+
+\setbeamercolor{palette primary}{bg=ForestPrimary, fg=white}
+\setbeamercolor{background canvas}{bg=white}
+\setbeamercolor{frametitle}{bg=ForestPrimary, fg=white}
+\setbeamercolor{progress bar}{fg=ForestAccent, bg=ForestLight}
+\setbeamercolor{title separator}{fg=ForestAccent}
+\setbeamercolor{progress bar in section page}{fg=ForestAccent, bg=ForestLight}
+\setbeamercolor{alerted text}{fg=ForestAccent}
+\setbeamercolor{normal text}{fg=ForestDark}
+\setbeamercolor{itemize item}{fg=ForestAccent}
+\setbeamercolor{itemize subitem}{fg=ForestPrimary}
+\setbeamercolor{section in toc}{fg=ForestPrimary}
+\setbeamercolor{footnote}{fg=ForestPrimary}
+\setbeamercolor{footnote mark}{fg=ForestAccent}
+
+\setbeamerfont{footnote}{size=\tiny}
+\setbeamertemplate{footline}[frame number]
+\setbeamertemplate{itemize item}{\textbullet}
+\setbeamertemplate{itemize subitem}{\textendash}
+
+% ---------- Icone leggere disegnate a TikZ (nessuna dipendenza esterna) ----------
+\newcommand{\iconcircle}[3]{%
+  % #1 = colore riempimento, #2 = colore testo, #3 = simbolo
+  \tikz[baseline=-0.65ex]{\node[circle, fill=#1, inner sep=1.6pt, minimum size=1.6em] {\textcolor{#2}{\footnotesize\textbf{#3}}};}%
+}
+\newcommand{\iconinfo}{\iconcircle{ForestAccent}{white}{?}}
+\newcommand{\icontip}{\iconcircle{TipColor}{white}{\checkmark}}
+\newcommand{\iconwarn}{\iconcircle{WarnColor}{white}{!}}
+\newcommand{\icongit}{\iconcircle{ForestPrimary}{white}{G}}
+\newcommand{\iconstar}{\iconcircle{ForestPrimary}{ForestAccent}{$\star$}}
+
+% ---------- Box tematici ----------
+\newtcolorbox{tipbox}[1][Consiglio]{
+  colback=TipLight, colframe=TipColor, boxrule=0.6pt, arc=2pt,
+  left=6pt, right=6pt, top=4pt, bottom=4pt, breakable,
+  fonttitle=\bfseries, title={\icontip\ #1}
+}
+\newtcolorbox{warnbox}[1][Attenzione]{
+  colback=WarnLight, colframe=WarnColor, boxrule=0.6pt, arc=2pt,
+  left=6pt, right=6pt, top=4pt, bottom=4pt, breakable,
+  fonttitle=\bfseries, title={\iconwarn\ #1}
+}
+\newtcolorbox{infobox}[1][Info]{
+  colback=ForestLight, colframe=ForestPrimary, boxrule=0.6pt, arc=2pt,
+  left=6pt, right=6pt, top=4pt, bottom=4pt, breakable,
+  fonttitle=\bfseries, title={\iconinfo\ #1}
+}
+
 \title{Setup LaTeX}
 \author{Domipoke}
 \date{\today}
 
 \begin{document}
 
-\frame{\titlepage}
+\begin{frame}[plain]
+  \titlepage
+\end{frame}
 
-\begin{frame}
+\begin{frame}{Outline}
-\frametitle{Outline}
 \tableofcontents
 \end{frame}
 
-\section{Introduction}
+\section{Introduzione}
 
-\begin{frame}{LaTeX 1/2}
+\begin{frame}{Cos'è LaTeX}
-  LaTeX è un linguaggio di \textbf{marcatura} (non di programmazione), ovvero un linguaggio che delinea delle regole per la formattazione di testo.\\
+  \begin{itemize}
-  Generalmente trova la sua applicazione nella scrittura di libri e paper di ricerca. \\
+    \item È un linguaggio di \textbf{marcatura} (non di programmazione): definisce delle regole per la formattazione del testo.
-  LaTeX divenne negli anni successivi un po' "complesso" dato l'evolversi delle interfacce grafiche e soluzioni come word furono all'inizio solo wrap\footnote{Per wrap si fa riferimento a un programma che nasconde la complessità di un qualcosa sotto istruzioni più semplici. Nell'esempio di word è nascosto da un'interfaccia grafica. Il cliccare un pulsante all'atto pratico scrive il testo nel formato "codice LaTeX" corrispondente a quell'azione. Ad oggi word è un linguaggio assestante chiamato docx} di LaTeX o simili.  
+    \item Trova applicazione soprattutto nella scrittura di \textbf{libri} e \textbf{paper di ricerca}.
+    \item LaTeX divenne negli anni successivi un po' "complesso" dato l'evolversi delle interfacce grafiche e soluzioni come word furono all'inizio solo wrap\footnote{Per wrap si fa riferimento a un programma che nasconde la complessità di un qualcosa sotto istruzioni più semplici. Nell'esempio di word è nascosto da un'interfaccia grafica. Il cliccare un pulsante all'atto pratico scrive il testo nel formato "codice LaTeX" corrispondente a quell'azione. Ad oggi word è un linguaggio assestante chiamato docx} di LaTeX o simili.  
+ \end{itemize}
 \end{frame}
 
-\begin{frame}{LaTeX 2/2}
+\begin{frame}{LaTeX: pro e limiti}
-  LaTeX è abbastanza intuitivo una volta capite le basi del linguaggio ed è anche ricchissimo di funzionalità. \\ 
+  \begin{itemize}
-  LaTeX puro permette un insieme molto limitato di azioni e queste forse non giustificano nemmeno la sua "complessità" nell'uso; pertanto useremo anche molte librerie distribuite da CTAN. 
+    \item È abbastanza intuitivo una volta capite le basi del linguaggio.
+    \item È ricchissimo di funzionalità grazie a un enorme ecosistema di librerie.
+    \item LaTeX "puro'' permette un insieme piuttosto limitato di azioni, che difficilmente giustificano da sole la sua complessità d'uso.
+  \end{itemize}
+  \begin{tipbox}
+    Per questo useremo anche molte librerie distribuite da \textbf{CTAN}, l'archivio ufficiale dei pacchetti LaTeX.
+  \end{tipbox}
 \end{frame}
 
-\begin{frame}{Requisiti 1/2}
+\section{Editor e distribuzioni}
-  Prima di iniziare ci serve fare delle scelte:\\
+
-  \begin{table}[htbp]
+\begin{frame}{Le scelte da fare}
+  Prima di iniziare ci servono alcune decisioni su \textbf{dove} e \textbf{come} scrivere in LaTeX:
+  \begin{table}[h]
     \centering
-    \begin{tabular}{|X|X|X|X}
+    \renewcommand{\arraystretch}{1.3}
-      & Overleaf & Overleaf-toolkit & VS Code \\
+    \rowcolors{2}{ForestLight}{white}
-      {LaTeX$\rightarrow$Pdf} & Media & Media & Veloce* \\
+    \begin{tabularx}{\textwidth}{X X X X}
-      Peso & 0 & 0** & 200MB - 2GB \\ 
+      \toprule
-      Limite & Imposto dal sito & Nessuno** & Nessuno*    
+      \rowcolor{ForestPrimary}
-    \end{tabular}
+      \textcolor{white}{} & \textcolor{white}{Overleaf} & \textcolor{white}{Overleaf-toolkit} & \textcolor{white}{VS Code} \\
+      \midrule
+      LaTeX $\rightarrow$ Pdf & Media & Media & Veloce* \\
+      Peso & 0 & 0** & 200MB -- 2GB \\
+      Limite & Imposto dal sito & Nessuno** & Nessuno* \\
+      \bottomrule
+    \end{tabularx}
+    \vspace{0.4cm}
+    \raggedright
+    \scriptsize{* Dipende dal vostro pc, generalmente quanto ho scritto.} \\
+    \scriptsize{** Dipende dal carico del mio server, la potenza viene divisa su tutti coloro che lo usano.}
   \end{table}
 \end{frame}
-\end{document}
+
+\begin{frame}{Overleaf: come funziona}
+  \begin{itemize}
+    \item È un tool \textbf{online} che divide lo schermo in due metà: a sinistra il codice, a destra il pdf risultante.
+    \begin{warnbox}
+    Overleaf ha un limite di \textbf{tempo di compilazione}: se il file usa molte librerie, contiene immagini o è molto lungo (come degli appunti d'esame), la compilazione può fallire.
+   \end{warnbox}
+    \item È possibile lavorare su tanti file più piccoli (es. uno per capitolo), così ognuno viene elaborato senza problemi dal sito, ma può risultare scomodo da gestire.
+    \item I file restano \textbf{online}, accessibili solo tramite internet.
+  \end{itemize}
+\end{frame}
+
+\begin{frame}{Overleaf Toolkit: la versione self-hosted}
+  \begin{itemize}
+    \item È la versione \textbf{self-hosted} di Overleaf.
+    \item Il proprietario del server può regolare e volendo rimuovere alcuni limiti.
+    \item Essendo online condivide gli altri lati negativi della versione classica.
+  \end{itemize}
+  \begin{warnbox}
+    Il piano base (anche quello self-hosted) è privo di ogni misura di sicurezza, perché Overleaf spinge verso il piano premium. Per questo è \textbf{necessario} accedervi con WireGuard.
+  \end{warnbox}
+\end{frame}
+
+\begin{frame}{Visual Studio Code}
+  \begin{itemize}
+    \item È un ambiente di sviluppo che supporta il download di varie \textbf{estensioni} per la gestione del codice.
+    \item Può sembrare eccessivo per quello che dobbiamo fare, ma è il migliore dal punto di vista delle \textbf{integrazioni} e dell'interfaccia grafica.
+    \item Di per sé è solo un ambiente di lavoro: pesa relativamente poco, qualche centinaio di megabyte.
+    \item Necessita però di avere LaTeX installato \textbf{localmente} sul proprio computer.
+  \end{itemize}
+\end{frame}
+
+\begin{frame}{LaTeX installato localmente}
+  LaTeX è scaricabile da varie distribuzioni, a seconda del sistema operativo:
+  \begin{itemize}
+    \item Windows
+    \begin{itemize}
+      \item MikTeX
+      \item TeX Live
+    \end{itemize}
+    \item Mac
+    \begin{itemize}
+      \item MacTeX \emph{[mai usata, spero sia intuitiva da scaricare]}
+    \end{itemize}
+  \end{itemize}
+\end{frame}
+
+\begin{frame}{TeX Live vs MikTeX: TeX Live}
+  \begin{itemize}
+    \item È la distribuzione usata da me, non perché sia la migliore (anzi).
+    \item Scarica tutte le librerie di LaTeX in locale, oppure solo quelle filtrate che si vogliono installare.
+    \item Il peso totale non è il vero problema: si parla di circa \textbf{1.6\,GB}.
+    \item Il vero lato negativo è la \textbf{velocità di download}, incredibilmente lenta perché distribuita da migliaia di server diversi e datati. A me ha richiesto circa \textbf{6 ore}.
+  \end{itemize}
+\end{frame}
+
+\begin{frame}{TeX Live vs MikTeX: MikTeX}
+  \begin{itemize}
+    \item Non l'ho mai usata personalmente, ma si presenta come più \textbf{nuova}, \textbf{veloce} e \textbf{leggera}.
+    \item Richiede però il download di un'altra libreria di circa \textbf{200\,MB} chiamata Perl (un linguaggio di programmazione).
+    \item Resta comunque più leggera: scarica solo le librerie effettivamente usate al momento della compilazione (quando si trasforma il \texttt{.tex} in \texttt{.pdf}).
+  \end{itemize}
+\end{frame}
+
+\begin{frame}{Una scorciatoia: la mia installazione}
+  \begin{itemize}
+    \item Un'alternativa è scaricare la copia già configurata da me installata, il che dovrebbe essere più veloce.
+    \item C'è il rischio che sia particolarmente instabile.
+  \end{itemize}
+  \begin{warnbox}
+    MikTeX è sconsigliata dagli stessi autori delle estensione di VS Code, ma nella pratica non è quasi mai un vero problema.
+  \end{warnbox}
+\end{frame}
+
+\begin{frame}{Dunque, cosa farei io?}
+  \begin{tipbox}[Il mio consiglio]
+    \begin{itemize}
+      \item Nelle prime settimane: \textbf{Overleaf}, mentre si fa un po' di pratica.
+      \item Se si vuole continuare è utile installare la versione \textbf{completa} di TeX Live, per evitare problemi futuri.
+    \end{itemize}
+  \end{tipbox}
+  Trovo infinitamente più comodo lavorare in locale, come sto scrivendo queste slide, rispetto al limitato Overleaf.
+\end{frame}
+
+\begin{frame}{Alternative a LaTeX}
+  LaTeX ha dato vita a tanti altri linguaggi:
+  \begin{itemize}
+    \item \textbf{KaTeX}, usato ad esempio dai blocchi matematici di Notion.
+    \item Le note di \textbf{Obsidian}, un'alternativa più semplice e leggera, che uso ultimamente sul telefono al posto delle note di default che per quanto mi piacciano, le trovo leggermente più lente.
+  \end{itemize}
+\end{frame}
+
+\section{Bonus}
+
+\begin{frame}{Il Tool}
+  \begin{itemize}
+    \item Vi ho già parlato di questo tool molte volte, e qualcuno del gruppo lo ha anche già usato (ma probabilmente non se lo ricorderà).
+    \item Permette la \textbf{sincronizzazione di file di testo}, generalmente codice, in repository (raccolte) online, pubbliche o private.
+  \end{itemize}
+  \begin{infobox}
+    È uno strumento essenziale nello sviluppo software, ma ho scoperto che viene utilizzato in modo più generale in qualsiasi ambiente di lavoro di gruppo per la sua comodità.
+  \end{infobox}
+\end{frame}
+
+\begin{frame}{Git}
+  \begin{itemize}
+    \item \icongit\ \textbf{Git} è il nome del tool di cui sto parlando.
+    \item Piattaforme che ne gestiscono e ospitano il servizio sono:
+    \begin{itemize}
+      \item \textbf{GitHub}: la più usata e diffusa.
+      \item \textbf{GitLab}
+      \item \textbf{Gitea}: versione self-hosted, che uso sul mio server.
+    \end{itemize}
+  \end{itemize}
+  \begin{tipbox}[GitHub Pages]
+    GitHub permette a qualsiasi utente di pubblicare automaticamente un sito web costruito a partire da una repository, purché non infranga leggi e non abbia fini commerciali. È la piattaforma preferita da programmatori e artisti per il proprio portfolio.
+  \end{tipbox}
+\end{frame}
+
+\begin{frame}{I concetti base}
+  Immaginate un repository come una cartella su un cloud:
+  \begin{itemize}
+    \item \textbf{Push} $\rightarrow$ inviamo e aggiorniamo i dati.
+    \item \textbf{Pull} $\rightarrow$ riceviamo i dati aggiornati.
+    \item È possibile tornare a \textbf{qualsiasi versione precedente} sia mai esistita.
+    \item Si possono eseguire azioni automatiche dopo l'invio o prima della ricezione dei dati: le \textbf{Actions}.
+    \item Inoltre piattaforme come GitHub non hanno un limite di spazio.
+\end{itemize}
+\end{frame}
+
+\begin{frame}{Le Actions}
+  \begin{itemize}
+    \item Generalmente sono usate per generare siti web da file di testo partendo da un semplice template.
+     \item È possibile configurare una Action in modo che, appena qualcuno invia un file \texttt{.tex}, venga caricato automaticamente anche il \textbf{pdf compilato}: dopo pochi secondi il risultato è pronto da scaricare.
+   \end{itemize}
+\end{frame}
+
+\begin{frame}{Quando conviene usarlo}
+  \begin{itemize}
+    \item È realisticamente utile quando \textbf{non} serve controllare ogni secondo cosa si sta scrivendo, ma solo generare il file finale.
+    \item Per progetti grandi è probabilmente la scelta migliore.
+  \item Inoltre permette di salvare i propri lavori in un ambiente online, condiviso o pubblico a seconda delle necessità.
+  \end{itemize}
+\end{frame}
+
+\end{document}
+