> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/latex/it/articoli-approfonditi/06-an-introduction-to-kpathsea-and-how-tex-engines-search-for-files.md). # Un'introduzione a Kpathsea e a come i motori TeX cercano i file ## Introduzione Questo articolo offre un'introduzione a come i motori TeX individuano i file necessari per comporre il tuo documento—usando LaTeX o qualsiasi altro pacchetto di macro. Sebbene Overleaf sollevi gli utenti dalle difficoltà di gestire un'installazione TeX ([TeX Live](https://www.tug.org/texlive/)), le basi di come i motori TeX cercano i file saranno utili/interessanti se vuoi creare una struttura di cartelle per aiutarti a gestire il tuo progetto Overleaf. Perché potrebbe essere vero? Se memorizzi alcuni file del tuo progetto Overleaf all'interno di cartelle, allora LaTeX potrebbe non trovare quei file perché, per impostazione predefinita, il motore TeX (compilatore) potrebbe non *sapere* che deve cercare in quelle cartelle—e quindi non troverà i file che contengono. Per evitare ciò, puoi creare e aggiungere al tuo progetto un file di configurazione chiamato [file latexmkrc](https://mg.readthedocs.io/latexmk.html#configuration-files) che può essere usato per indicare a un motore TeX che le tue cartelle esistono e che deve cercarle. Se vuoi passare a un esempio che mostra un file latexmkrc, puoi leggere questo articolo di supporto: [Come usare latexmkrc con Overleaf: esempi e tecniche](/latex/it/articoli-approfonditi/28-how-to-use-latexmkrc-with-overleaf.md). Potrebbe non essere subito evidente come, o perché, quel file latexmkrc funzioni davvero. Se vuoi sapere perché e, magari, sviluppare una migliore comprensione per usarlo con ulteriori possibilità di configurazione per il tuo progetto, allora continua a leggere... Alla fine di questo articolo esamineremo un [esempio pratico](#kpathsea-and-texinputs-latexmkrc-file-to-the-rescue)—usando la nostra conoscenza di come TeX cerca i file—per creare un file latexmkrc per gestire cartelle nidificate contenenti i tuoi file grafici. ## TeX e indipendenza dalla piattaforma Quando Knuth creò TeX, l'indipendenza dalla piattaforma era un principio centrale che guidava la sua progettazione e implementazione e quella filosofia si riflette in tutte le operazioni interne di TeX (ad es., uso dell'aritmetica intera, gestione delle stringhe “fatta in casa”, gestione della memoria, ecc.). Ancora oggi, l'indipendenza dalla piattaforma dei moderni motori basati su TeX solleva ancora domande e dibattiti nei forum pubblici; per esempio, vedi questa discussione su tex.stackexchange: [XeTeX e LuaTeX dipendono dalla piattaforma?](https://tex.stackexchange.com/questions/94297/are-xetex-and-luatex-platform-dependent) che contiene commenti e osservazioni di diversi noti esperti TeX. Tuttavia, per il momento lasciamo da parte i dettagli più sottili e notiamo che i motori TeX devono comunque essere altamente portabili—in grado di funzionare su più sistemi operativi e produrre risultati “identici”. Un aspetto chiave della portabilità è la ricerca dei file in modo indipendente dalla piattaforma. ## I motori TeX non cercano i file… davvero!? No, i motori TeX non *direttamente* cercano i file *da soli*. Durante l'elaborazione di un `.tex` file, un motore TeX potrebbe identificare la necessità di aprire un file specifico, ma *delega* il compito di trovarlo a un altro componente software chiamato [*Kpathsea*](https://tug.org/kpathsea/): una libreria software esterna che non fa parte del *nucleo* codice sorgente dei motori TeX. Ciò che Kpathsea fornisce è, in effetti, una API ([Interfaccia di programmazione delle applicazioni](https://en.wikipedia.org/wiki/Application_programming_interface)) che i motori TeX (oltre a BibTeX, MetaPost e altre applicazioni) possono chiamare ogni volta che devono aprire un file specifico: Kpathsea svolge il lavoro effettivo di localizzare quel file. Quando Knuth scrisse il motore TeX originale—dal quale discendono, in ultima analisi, tutti gli altri motori TeX—il problema di trovare/aprire file era una sfida significativa dovuta, in parte, all'ecosistema tecnologico molto eterogeneo di quel tempo. In effetti, nel codice sorgente di TeX Knuth si riferisce all'input/output dei file come al “flagello della portabilità” (vedi pagina 12, sezione 25 di [TeX: The Program](https://www.amazon.co.uk/Computers-Typesetting-TeX-Program-TEX/dp/0201134373)). La comunità TeX ha riconosciuto la necessità di armonizzare (standardizzare) la ricerca dei file per TeX—*e il software correlato a TeX*—e ha deciso di fornire a TeX gli strumenti per farlo. Per affrontare il problema molto spinoso di un metodo indipendente dalla piattaforma per trovare i file, Karl Berry, un membro di spicco della comunità TeX, ha scritto il software per risolvere il *problema dei percorsi*di ricerca: una soluzione che ha chiamato [**Kpathsea**](http://tug.org/texinfohtml/kpathsea.html)—che deriva da **K**arl’s **Path** **Sea**rching (vedi questa [intervista con Karl Berry](http://www.tug.org/interviews/berry.html)). Possiamo notare che si chiama K**problema dei percorsi**sea e non K**file**sea perché, come [documentazione](http://tug.org/texinfohtml/kpathsea.html) nota, è una libreria di ricerca \*per percorsi\*. È importante riconoscere che Kpathsea non è usato solo dai motori TeX; vari programmi correlati a TeX, tra cui BibTeX e MetaPost, usano anch'essi Kpathsea per cercare i file di input. In sintesi, ogni volta che le macro TeX/LaTeX devono aprire un file specifico, i comandi con cui tali macro sono costruite verranno, alla fine, convertiti in istruzioni TeX di basso livello (primitivi TeX) che i motori TeX eseguono realmente. Se tali istruzioni includono la necessità di aprire un file, il motore TeX chiamerà Kpathsea dicendo, in effetti, “per favore trova questo file”; se la ricerca di Kpathsea ha esito positivo, il file viene aperto. Tuttavia, se Kpathsea non riesce a individuare il file, allora il motore TeX ne sarà informato e interromperà l'esecuzione per emettere il famigerato errore ``! Non riesco a trovare il file `...'`` La verità è che Kpathsea non riesce a trovarlo. ### Note su LuaTeX A rigor di termini dovremmo premettere una precisazione a questa sezione, notando che LuaTeX offre un meccanismo per consentire all'utente di fornire il proprio codice di ricerca dei file tramite l'uso di *callback*. LuaTeX consente agli utenti di scrivere funzioni nel linguaggio di scripting Lua e registrarle con LuaTeX affinché quest'ultimo richiami quella funzione definita dall'utente in determinate fasi durante l'esecuzione di LuaTeX—da qui il termine *callback*. È una tecnica molto potente e il lettore interessato può trovare maggiori informazioni nella Sezione 9 di [Il manuale di riferimento di LuaTeX](http://www.pragma-ade.com/general/manuals/luatex.pdf) (al momento della stesura, quel collegamento è per LuaTeX 1.09). ### Il file di configurazione di Kpathsea: texmf.cnf Ogni installazione TeX contiene un file di testo chiamato `texmf.cnf` che è un file di configurazione usato da Kpathsea: contiene numerose “variabili di configurazione” che definiscono i percorsi che Kpathsea userà per cercare vari tipi di file di cui i motori TeX (o BibTeX, MetaPost ecc.) potrebbero aver bisogno. Come vedremo qui sotto, quelle “variabili di configurazione” definiscono percorsi di ricerca costruiti a partire dai cosiddetti *elementi di percorso*: usando vari costrutti, variabili e parametri per definire ogni elemento di percorso come un “modello” che Kpathsea elabora per generare le directory reali e fisiche da cercare. Per fare un esempio concreto, ecco una di queste variabili di configurazione che definisce i percorsi di ricerca per i font OpenType—per ora, non preoccuparti del significato della costruzione di questo percorso: ``` OPENTYPEFONTS = .;$TEXMF/fonts/{opentype,truetype}//;$OSFONTDIR// ``` Tutto ciò che è importante qui è che il file `texmf.cnf` (letto da Kpathsea) definisce una variabile di configurazione chiamata `OPENTYPEFONTS` che viene usata per definire il/i percorso/i che Kpathsea userà per cercare i font OpenType. Il lato destro del “=” non assomiglia a nessun percorso che si veda su un dispositivo tipico perché è costruito usando varie variabili e parametri per definire ogni percorso come un “modello” o “schema” che Kpathsea userà per generare directory reali da cercare. ### Il concetto di “percorso” di Kpathsea Forse il concetto centrale da comprendere è la nozione di “percorso” di Kpathsea: la struttura di base che Kpathsea usa per stabilire dove si trova un file specifico. Come abbiamo visto nell' `OPENTYPEFONTS` esempio precedente, la nozione di percorso di Kpathsea appare molto diversa dai percorsi a cui siamo abituati a usare sui nostri dispositivi desktop o portatili. Per citare Kpathsea [documentazione](http://tug.org/texinfohtml/kpathsea.html#Searching-overview): > ... un *percorso di ricerca* è un elenco separato da due punti di *elementi di percorso*, che sono nomi di directory con qualche “fronzolo” in più. —ma nota che un punto e virgola (`;`) è usato anche per separare *elementi di percorso*. In seguito, indicheremo brevemente la natura di alcuni di quei “fronzoli” in più. Nel nostro `OPENTYPEFONTS` esempio ci sono tre elementi di percorso, ciascuno delimitato usando il punto e virgola (`;`): ![Immagine che mostra gli elementi di percorso contenuti in una definizione di percorso Kpathsea](/files/e0716db32a73f6aa2b3a11f95acf60a2949fb775) 1. `.` (che indica la directory corrente) 2. `$TEXMF/fonts/{opentype,truetype}//` 3. `$OSFONTDIR//` Nota che una doppia barra (`//`) in un elemento di percorso significa cercare nelle sottodirectory (ricorsivamente). Un tipico `texmf.cnf` file conterrà numerose “variabili di configurazione” per definire i percorsi di ricerca per i tipi di file che Kpathsea può cercare. ## Kpathsea: una panoramica molto breve Kpathsea è una libreria sofisticata—con molti dettagli e sfumature—e anche solo una rapida occhiata alla sua [documentazione](http://tug.org/texinfohtml/kpathsea.html) rende chiaro che non possiamo addentrarci in tutti i dettagli. Tuttavia, possiamo provare a fornire una panoramica di ciò che fa—per aiutarti a orientarti e offrire un punto di partenza per ulteriori letture. ### Lo scopo fondamentale di Kpathsea Come indicato nella documentazione, lo scopo fondamentale di Kpathsea è “restituire un nome file da un elenco di directory specificato dall'utente” e il fatto che tali directory (percorsi di ricerca) siano specificate usando “qualche fronzolo in più”. ### Quei “fronzoli in più” I “pochi fronzoli in più” menzionati sopra includono vari parametri e variabili che Kpathsea usa per costruire i suoi percorsi di ricerca (o “modelli di percorso”) in modo da poter definire i percorsi in modo più generale. Quando un motore TeX è effettivamente in esecuzione, Kpathea può usare il valore corrente di quei parametri/variabili per determinare i percorsi reali sostituendo tali variabili con i loro valori reali (a runtime). Puoi facilmente identificare quelle variabili (all'interno degli elementi di percorso) perché iniziano con un `$` simbolo. Pertanto, diciamo che Kpathsea *espande* un elemento di percorso, il che significa che trasforma quei parametri e variabili: convertendo un percorso “modello” nel/i nome/i reale/i di una o più directory fisiche in cui cercare un file. Questo offre molta flessibilità e significa che Kpathsea potrebbe costruire un elenco di directory corrispondente a un singolo elemento di percorso—per esempio, se gli viene detto di cercare nelle sottodirectory. ### Rivediamo il nostro esempio OpenType Metteremo insieme i vari fili e esamineremo `OPENTYPEFONTS` un po' più in dettaglio: ``` OPENTYPEFONTS = .;$TEXMF/fonts/{opentype,truetype}//;$OSFONTDIR// ``` Consideriamo i due elementi di percorso `$TEXMF/fonts/{opentype,truetype}//` e `$OSFONTDIR//`. Qui, Kpathsea nota l'uso delle parentesi graffe `{...}` e tratta `$TEXMF/fonts/{opentype,truetype}` come rappresentante *due* elementi di percorso: 1. `$TEXMF/fonts/opentype//` 2. `$TEXMF/fonts/truetype//` e che le *sottodirectory* di entrambi questi elementi di percorso debbano essere cercate anch'esse (indicato dalla doppia barra finale `//`). **Nota**: vedi la documentazione di Kpathsea su [espansione delle sottodirectory](http://tug.org/texinfohtml/kpathsea.html#Subdirectory-expansion) per una importante avvertenza sull'ordine in cui vengono cercate le sottodirectory, a qualsiasi livello (non è specificato). Faremo alcune osservazioni su `$TEXMF` qui sotto. #### $OSFONTDIR// `$OSFONTDIR` è una variabile il cui valore dovrebbe essere definito come una variabile d'ambiente contenente la posizione in cui sono memorizzati i font: il valore esatto dipenderà, naturalmente, dal sistema operativo usato per eseguire TeX. Nota che, qui, la doppia barra finale `//` istruisce Kpathsea a cercare nelle sottodirectory quando cerca i font OpenType. La definizione predefinita di `OSFONTDIR` all'interno di `texmf.cnf` è: ``` OSFONTDIR = /please/set/osfontdir/in/the/environment ``` Quindi è sicuramente qualcosa che devi impostare se desideri usarlo—la tua variabile d'ambiente sovrascriverà questa definizione “segnaposto” contenuta in `texmf.cnf`. Se imposti la variabile d'ambiente `OSFONTDIR` allora, a runtime, ovunque Kpathsea veda `$OSFONTDIR` come parte di un elemento di percorso (in `texmf.cnf`) può sostituire la variabile `$OSFONTDIR` con il valore effettivo memorizzato nella variabile d'ambiente `OSFONTDIR`. Ricorda che, quando lo usi all'interno di `texmf.cnf` elementi di percorso specifichiamo la variabile `$OSFONTDIR`—con un prefisso `$`—per indicare a Kpathsea che si tratta di una variabile il cui *valore* valore deve usare. #### Brevi note su $TEXMF `TEXMF` è un'altra variabile di configurazione definita in `texmf.cnf`; per esempio, nella distribuzione master di TeX Live vedresti: ``` TEXMF = {$TEXMFAUXTREES$TEXMFCONFIG,$TEXMFVAR,$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFSYSCONFIG,!!$TEXMFSYSVAR,!!$TEXMFDIST} ``` Non è necessario preoccuparsi dei dettagli di questa definizione di `TEXMF`—non esploreremo tutti i dettagli, ma notiamo semplicemente che la `$TEXMF` variabile viene usata all'interno degli elementi di percorso perché definisce una serie di cartelle di primo livello (indicate come “alberi texmf”) da cui puoi iniziare la ricerca dei file. `TEXMF` è estremamente utile se vuoi, o devi, suddividere un'installazione TeX su più directory (o “alberi” di directory). Per esempio, avere una raccolta principale o master di pacchetti TeX/LaTeX (ad es., TeX Live) e un'altra raccolta di file e cartelle usata per memorizzare pacchetti LaTeX locali—o, magari, usata per memorizzare file di configurazione locali o versioni personalizzate di pacchetti standard. Suddividere l'installazione TeX in questo modo può rendere più facile gestire l'aggiornamento della raccolta principale/master (distribuzione) di pacchetti TeX/LaTeX perché la tua raccolta locale è separata dai file master che vengono aggiornati quando aggiorni la tua distribuzione/installazione di TeX Live. Per ulteriori dettagli sulla gestione di installazioni TeX più complesse, il lettore interessato è rimandato a questi due articoli: * [Gestire più alberi TDS](http://tug.org/TUGboat/Articles/tb22-3/tb72downes.pdf) di Michael J Downes; * [Destreggiarsi tra gli alberi texmf](http://www.ntg.nl/maps/27/17.pdf) di Siep Kroonenberg. #### Struttura delle directory TeX Chiunque abbia gestito un'installazione TeX sa che i moderni sistemi TeX, come TeX Live, contengono decine di migliaia di file che comprendono un'enorme varietà di tipi di file. La TeX Directory Structure (TDS) è stata progettata come uno “schema” di best practice per organizzare l'enorme raccolta di file in un'installazione TeX funzionante ed è fortemente raccomandata per l'uso con Kpathsea. Per ulteriori informazioni, il lettore è indirizzato alla specifica TDS: [Una struttura di directory per i file TeX](https://www.tug.org/tds/tds.pdf). ## Tipi di file di Kpathsea La suite di applicazioni che usa Kpathsea deve accedere a una vasta gamma di tipi di file, quindi Kpathsea usa una “variabile di configurazione” per identificare il/i percorso/i per ciascun tipo di file (o gruppo di file) che supporta. La documentazione online ne ha un elenco completo (vedi anche la nostra [tabella riassuntiva qui sotto](#table-listing-kpathsea-config-variables)) ma ecco le “variabili di configurazione” per i tipi di file più comuni: | | | | ------------------------------- | ------------------------------------------ | | **Variabile di configurazione** | **Esempi di tipi di file** | | TEXINPUTS | File sorgente TeX e file di figure/grafica | | BIBINPUTS, BSTINPUTS | File sorgente della bibliografia BibTeX | | TTFONTS | Font outline TrueType | | OPENTYPEFONTS | Font outline OpenType | `TEXINPUTS` è una variabile di configurazione particolarmente importante perché specifica da dove un motore TeX ottiene i suoi file sorgente di input. Nota che i file immagine sono considerati file di input e possono anche essere cercati usando il percorso definito da `TEXINPUTS`. ### Alcune sfumature di Kpathsea Come notato, Kpathsea ha molte sfumature che non possiamo esplorare qui in dettaglio. Tuttavia, ecco alcune funzionalità che alcuni lettori potrebbero voler approfondire: * **database dei nomi file:** Per ridurre al minimo le ricerche su disco, Kpathsea può avvalersi di un [file di database dei nomi file costruito esternamente chiamato ls-R](http://tug.org/texinfohtml/kpathsea.html#Filename-database) che mappa i file alle directory”. TeX Live ne fornisce uno e gli strumenti per aggiornarlo se vengono aggiunti nuovi file. * **variabili d'ambiente**: oltre alle “variabili di configurazione” (come `OPENTYPEFONTS`) Kpathsea fa anche un uso intelligente di [variabili d'ambiente](https://en.wikipedia.org/wiki/Environment_variable); per esempio, il valore a runtime delle variabili d'ambiente può essere usato per definire elementi di percorso nel `texmf.cnf` file (eventualmente per sovrascrivere variabili con lo stesso nome definite in `texmf.cnf`). * **nome del programma:** Un aspetto sottile ma essenziale del comportamento di Kpathsea è che può usare il nome del programma eseguibile (ad es., il motore TeX) per costruire strutture di percorsi di ricerca specifiche per programma. Questo offre una notevole flessibilità perché la ricerca dei percorsi può essere indirizzata ai file di un particolare motore TeX. Per esempio, per LuaTeX/LuaLaTeX: ``` TEXINPUTS.lualatex = .;$TEXMF/tex/{lualatex,latex,luatex,generic,}// TEXINPUTS.luatex = .;$TEXMF/tex/{luatex,plain,generic,}// ``` * **trovare `texmf.cnf`**: Una domanda che potresti porti è: come fa Kpathsea a sapere dove `texmf.cnf` è memorizzato? La risposta è una variabile d'ambiente chiamata `TEXMFCNF`. Questa deve essere impostata (sul dispositivo/piattaforma che esegue TeX) sul percorso in cui `texmf.cnf` è memorizzato. #### Debug dei problemi di Kpathsea È improbabile che gli utenti di Overleaf abbiano bisogno di queste funzioni, ma le elenchiamo per completezza: * **kpsewhich**: un programma autonomo (incluso in TeX Live) che può essere usato per testare le tue impostazioni: determinare il valore delle variabili e trovare i file. I lettori interessati sono rimandati alla [documentazione online](http://tug.org/texinfohtml/kpathsea.html#Invoking-kpsewhich) per ulteriori informazioni. * **variabili d'ambiente**: Kpathsea supporta una variabile d'ambiente chiamata [`KPATHSEA_DEBUG`](http://www.tug.org/texinfohtml/kpathsea.html#Debugging) per aiutare a debuggare il suo comportamento. Puoi impostare `KPATHSEA_DEBUG` a valori diversi a seconda di quante informazioni di debug ti servono. Impostando `KPATHSEA_DEBUG=-1` genererà una *notevole* quantità di dati. ## E infine: cartelle, file di figure e latexmkrc Allora, in che modo quanto sopra si collega a latexmkrc? Se leggi questo articolo [Come usare latexmkrc con Overleaf: esempi e tecniche](/latex/it/articoli-approfonditi/28-how-to-use-latexmkrc-with-overleaf.md) puoi vedere che il codice (Perl) nell'esempio latexmkrc imposta il valore di una variabile d'ambiente `TEXINPUTS`: ``` $ENV{'TEXINPUTS'}='./tex//:' . $ENV{'TEXINPUTS'}; ``` Nota che i due punti (:) usati qui (`./tex//**:**`) è *estremamente* importante. Se ometti quel due punti, allora TeX/LaTeX potrebbe non essere in grado di trovare file di sistema vitali, come i pacchetti LaTeX! Ciò che questo file latexmkrc fa, in effetti, è aggiungere un percorso di cartella di primo livello (`./tex` nell'esempio sopra) alla `TEXINPUTS` variabile d'ambiente definita dal sistema in modo che, quando Kpathsea usa la variabile `$TEXINPUTS` sarà allora consapevole che la cartella `/tex//` deve essere cercata per trovare i file di input. Se guardi attentamente, vedrai che il percorso effettivamente usato è `./tex//:` le `//` dice a Kpathsea di cercare la cartella tex in modo ricorsivo—cioè di guardare in eventuali sottocartelle contenute nella `tex` cartella. Come notato, abbiamo anche aggiunto il carattere due punti, importante. Possiamo usare esattamente la stessa tecnica per i file di figure. ### Una nota a margine su BibTeX Come notato, anche il programma BibTeX usa Kpathsea per cercare i propri file di input; in particolare: * le `BSTINPUTS` la variabile di configurazione (percorso di ricerca) viene usata per cercare i `.bst` file; * e il `BIBINPUTS` la variabile di configurazione (percorso di ricerca) verrà usata per cercare i `.bib` file. Se aggiungi nuovi `.bst` o `.bib` file al tuo progetto Overleaf puoi usare la tecnica qui sotto per indicare a BibTeX dove trovare questi file—devi sostituire `TEXINPUTS` con `BSTINPUTS` e/o `BIBINPUTS`. ### TEXINPUTS e usare cartelle nidificate per i file grafici Se il tuo progetto ha molti file grafici può essere comodo creare una serie di cartelle in cui conservarli e gestirli. Per esempio, la seguente schermata mostra una sezione di un progetto Overleaf che usa una cartella di primo livello chiamata **`graphics`**: ![Immagine che mostra cartelle nidificate in un progetto Overleaf](/files/bad87d8049cafa21202743cc97234a33715a6aef) Ci sono numerose sottocartelle (nidificate) contenenti grafica per varie sezioni del nostro documento. Supponiamo di avere la struttura di cartelle sopra e di voler usare la `graphicx` (`\usepackage{graphicx}`) e di provare a farlo così: ```latex \documentclass{article} \usepackage{graphicx} \begin{document} \includegraphics{endlinechar}% la best practice è non usare l'estensione del file \end{document} ``` Non funzionerà e otterrai un errore come questo: ``` ! Errore LaTeX: file `endlinechar' non trovato. l.4 \includegraphics{endlinechar} Non ho potuto individuare il file con nessuna di queste estensioni: .pdf,.PDF,.ai,.AI,.png,.PNG,.jpg,.JPG,.jpeg,.JPEG,.jp2,.JP2,.jpf,.JPF,.bmp,.BMP, ,.ps,.PS,.eps,.EPS,.mps,.MPS,.pz,.eps.Z,.ps.Z,.ps.gz,.eps.gz ``` Questo errore si verifica perché il nostro file grafico è memorizzato in una posizione di cui TeX/LaTeX (e Kpathsea) non sono a conoscenza, e quindi non possono trovarlo—il percorso del file grafico è: ``` ./graphics/Introduction/Chapter1/Section1/Subsection3/endlinechar.png ``` **Nota**: è generalmente considerata una buona pratica ***evitare caratteri spazio nei nomi delle cartelle***. Sebbene sia certamente possibile avere spazi nei nomi delle cartelle, usando le tecniche discusse qui sotto, sconsiglieremmo di farlo per ragioni di portabilità del documento al di fuori della piattaforma Overleaf. Come spiegato in questo [articolo di supporto di Overleaf](/latex/it/altri-argomenti/27-inserting-images.md) puoi, naturalmente, usare cartelle per memorizzare la tua grafica, ma devi indicare a LaTeX dove sono archiviate. Qui esamineremo due soluzioni: * Usando il comando \graphicspath; * Usando la nostra conoscenza di Kpathsea e `TEXINPUTS`. ### Usando \graphicspath Il `graphicx` il pacchetto fornisce il `\graphicspath` comando che puoi usare per dichiarare i percorsi in cui si trovano i tuoi file grafici; quindi potremmo fare qualcosa del genere: ```latex \graphicspath{{./graphics/Introduction/Chapter1/Section1/Subsection3/}} ``` e LaTeX ora troverà qualsiasi grafica memorizzata sotto quel percorso. **Nota**: Se hai *devono* spazi nei nomi delle cartelle, allora dovrai racchiudere i percorsi tra virgolette doppie (`"..."`): ```latex \graphicspath{{"./graphics/Introduction/Chapter 1/Section 1/Subsection 3/"}} ``` **Nota**: Puoi dichiarare più percorsi così: ```latex \graphicspath{{path1}{path2}{path3}...{pathN}} ``` dove `...` significa percorsi aggiuntivi racchiusi tra parentesi graffe. **Nota**: Iniziamo il percorso con `./graphics` e non semplicemente `/graphics`. Il punto (.) indica al sistema operativo che il percorso è relativo alla directory di lavoro corrente. Il `\graphicspath` comando funziona bene ma se hai molte cartelle può diventare piuttosto tedioso aggiungere ogni percorso; inoltre, i percorsi definiti tramite `\graphicspath` non funzionerebbero più se rinominassi le cartelle o le ristrutturassi. C'è un modo più semplice? Sì, puoi usare un file latexmkrc! #### \graphicspath e ricorsione (sottodirectory) Nota che ci sono discussioni/dibattiti online sul fatto che alcuni sistemi supportino/abilitino `\graphicspath` la ricerca ricorsiva nelle sottodirectory se aggiungi `//` alla fine del percorso: vedi, per esempio, queste discussioni su tex.stackexchange: * [Ricerca ricorsiva di \graphicspath in LaTeX](https://tex.stackexchange.com/questions/25443/latex-graphicspath-recursive-search); * [Graphicspath per MikTeX](https://tex.stackexchange.com/questions/3131/graphicspath-for-miktex). Per la massima compatibilità dovresti assumere che `\graphicspath` non supporti la ricerca ricorsiva delle directory. ### Kpathsea e TEXINPUTS (il file latexmkrc in soccorso) **AVVERTENZA:** Nota che la seguente tecnica funziona bene su Overleaf e su installazioni TeX locali opportunamente configurate; **ma** se usi un file latexmkrc il tuo progetto potrebbe diventare incompatibile con altre installazioni TeX, come quelle usate da editori e sistemi online di invio di articoli. Le installazioni TeX di terze parti possono, oppure no, supportare o consentire l'uso di latexmkrc. Se devi esportare il tuo progetto Overleaf per usarlo altrove, o vuoi inviarlo a una rivista, dovresti rimuovere eventuali caratteri spazio dai nomi dei percorsi e, per una maggiore compatibilità, aggiungere un `\graphicspath` comando che definisca tutti i percorsi: ```latex \graphicspath{{path1}{path2}{path3}...{pathN}} ``` dove `...` significa percorsi aggiuntivi racchiusi tra parentesi graffe. La tecnica discussa qui sotto (usando `TEXINPUTS`) è stata testata con successo su Overleaf con i motori pdfTeX, XeTeX e LuaTeX (cioè le opzioni di compilazione pdfLaTeX, XeLaTeX e LuaLaTeX nel menu di Overleaf): ![Immagine che mostra come scegliere il compilatore LaTeX su Overleaf](/files/63385e52b9c1f539d9ba00825fbfef441b21d8c9) Tornando al nostro esempio, vogliamo usare questo codice (con cartelle profondamente annidate) e useremo un file latexmkrc per ottenerlo: ```latex \documentclass{article} \usepackage{graphicx} \begin{document} \includegraphics{endlinechar}% la best practice è non usare l'estensione del file \end{document} ``` Ecco uno screenshot che mostra il codice sopra in funzione senza problemi: LaTeX ha trovato il nostro file grafico (`endlinechar.png`) anche se si trova in una struttura di cartelle profondamente annidata (senza alcuno spazio nei nomi delle cartelle). ![Immagine che mostra un progetto con cartelle annidate in compilazione su Overleaf](/files/61b46e80d390888149b431384eade8d0cdf3f7c4) Quindi, come abbiamo fatto? Tutto ciò che devi fare è: * creare un nuovo file, senza estensione, e chiamarlo latexmkrc; * aggiungere la seguente riga a quel file: ``` $ENV{'TEXINPUTS'}='./graphics//:'.$ENV{'TEXINPUTS'}; ``` Kpathsea ora conoscerà le cartelle contenute sotto `**graphics**` e grazie al `//` cercherà anche nelle sottocartelle. Nota ancora che i due punti in `./graphics//:` è in realtà *estremamente* importante. Se ometti quel due punti, allora TeX/LaTeX potrebbe non essere in grado di trovare file di sistema vitali, come i pacchetti LaTeX! Usando il semplice esempio di progetto sopra, ora puoi compilarlo e voilà! LaTeX trova il tuo file grafico — e puoi rinominare o riorganizzare le cartelle sotto /graphics e ciò non impedirà a LaTeX di trovarle. ## Tabella che elenca le “variabili di configurazione” di Kpathsea La tabella seguente è un riassunto ricavato da [i dati elencati nella documentazione di Kpathsea](http://tug.org/texinfohtml/kpathsea.html#Supported-file-formats). | | | | | --------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------ | | **variabile di configurazione di Kpathsea** | **Descrizione del tipo di file** | **Estensione del file** | | AFMFONTS | metriche dei font Adobe | .afm | | MFBASES, TEXMFINI | dump della memoria di Metafont | .base | | BIBINPUTS, TEXBIB | sorgente bibliografica BibTeX | .bib | | BLTXMLINPUTS | file bibliografici BibLaTeXML per Biber | .bltxml | | BSTINPUTS | Stile BibTeX | .bst | | CLUAINPUTS | librerie dinamiche per Lua | .dll e .so | | CMAPFONTS | file di mappa dei caratteri | .cmap | | TEXMFCNF | File di configurazione a runtime | .cnf | | CWEBINPUTS | file di input CWEB | .w, .web, .ch | | TEXCONFIG | file 'config.\*' di Dvips, come config.ps | | | ENCFONTS | vettori di codifica | .enc | | TEXFORMATS, TEXMFINI | dump della memoria di TeX | .fmt | | FONTCIDMAPS | mappatura CJK | .cid | | FONTFEATURES | principalmente per le funzionalità dei font OpenType | .fea | | FONTS, GFFONTS, GLYPHFONTS, TEXFONTS | bitmap generico dei font | .gf | | TEXPICTS, TEXINPUTS | figure Encapsulated PostScript | .eps, .epsi | | TEXINDEXSTYLE, INDEXSTYLE | file di stile makeindex | .ist | | LIGFONTS | file di definizione delle legature | .lig | | TEXMFDBS | database dei nomi dei file | | | TEXFONTMAPS | mappe dei font | .map | | MPMEMS, TEXMFINI | dump della memoria di MetaPost | .mem | | MPSUPPORT | file di supporto per MetaPost, usati da DMP | | | MFINPUTS | sorgente Metafont | .mf | | MFPOOL, TEXMFINI | stringhe del programma Metafont | .pool | | MFTINPUTS | file di stile MFT | .mft | | MISCFONTS | file relativi ai font che non rientrano nelle altre categorie | | | MLBIBINPUTS, BIBINPUTS, TEXBIB | sorgente bibliografica MlBibTeX | .mlbib, .mlbib | | MLBSTINPUTS, BSTINPUTS | stile MlBibTeX | .mlbst, .bst | | MPINPUTS | sorgente MetaPost | .mp | | MPPOOL, TEXMFINI | stringhe del programma MetaPost | .pool | | OCPINPUTS | file di processo compilati di Omega | .ocp | | OFMFONTS, TEXFONTS | metriche dei font Omega | .ofm, .tfm | | OPENTYPEFONTS | font OpenType | | | OPLFONTS, TEXFONTS | elenchi di proprietà di Omega | .opl | | OTPINPUTS | file di processo di traduzione di Omega | .otp | | OVFFONTS, TEXFONTS | font virtuali di Omega | .ovf | | OVPFONTS, TEXFONTS | elenchi di proprietà virtuali di Omega | .ovp | | PDFTEXCONFIG | file di configurazione specifici di PDFTeX | | | PROGRAMFONTS, PKFONTS, TEXPKS, GLYPHFONTS, TEXFONTS | font bitmap impacchettati | .pk | | TEXPSHEADERS, PSHEADERS | PostScript scaricabile | .pro | | RISINPUTS | file bibliografici RIS, principalmente per Bibe | .ris | | SFDFONTS | file di definizione dei sottofont | .sfd | | TEXINPUTS | sorgente TeX | .tex | | TEXDOCS | file di documentazione per il sistema TeX | | | TEXSOURCES | file sorgente per il sistema TeX | | | TEXMFSCRIPTS | eseguibili indipendenti dall'architettura distribuiti negli alberi texmf | | | TEXPOOL, TEXMFINI | stringhe del programma TeX | .pool | | TFMFONTS, TEXFONTS | metriche dei font TeX | .tfm | | TRFONTS | font Troff | | | TTFONTS | Font outline TrueType | .ttf, ,TTF, .ttc, .TTC, .dfont | | T1FONTS, T1INPUTS, TEXPSHEADERS, DVIPSHEADERS | font outline PostScript di tipo 1 | .pfa, .pfb | | T42FONTS | font outline PostScript di tipo 42 | | | VFFONTS, TEXFONTS | font virtuali | .vf | | WEBINPUTS | file di input WEB | .web, .ch | | WEB2C | file specifici dell'implementazione web2c | | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://overleaf-pro.ayaka.space/latex/it/articoli-approfonditi/06-an-introduction-to-kpathsea-and-how-tex-engines-search-for-files.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.