> 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/base-di-conoscenza/033-cross-referencing-with-the-xr-package-in-overleaf.md). # Riferimenti incrociati con il pacchetto xr in Overleaf ## Panoramica La [`xr` pacchetto](https://ctan.org/pkg/xr?lang=en) consente di creare riferimenti incrociati a equazioni, figure, tabelle ecc. contenute in documenti LaTeX esterni, a condizione che tali documenti siano *autonomi.* Un documento LaTeX autonomo è un documento che può essere compilato perché contiene una `\documentclass{...}` istruzione e il `\begin{document}`...`\end{document}` costrutto. ### Riepilogo dell'utilizzo 1. Scrivere `\usepackage{xr}` nel preambolo del file LaTeX che deve creare riferimenti incrociati a contenuti presenti in file LaTeX esterni. 2. Usa la `xr` comando del pacchetto `\externaldocument{filename}` per specificare i documenti esterni di cui si desidera creare riferimenti incrociati al contenuto. La `xr` Il pacchetto funziona utilizzando le etichette di riferimento incrociato contenute nei `.aux` file generati quando i documenti LaTeX esterni vengono compilati. ### Come funzionano i riferimenti incrociati (un breve riepilogo) Per creare un riferimento incrociato a un elemento in un documento LaTeX, è necessario: 1. Assegnargli un identificatore univoco, `some_string`, usando `\label` comando: ```latex \label{some_string} ``` 3. Nel punto in cui si desidera fare riferimento a quell'elemento, è necessario scrivere ```latex \ref{some_string} ``` In breve, LaTeX gestisce i riferimenti incrociati scrivendo dati in un file chiamato `filename.aux` dove `filename` è il nome del file principale `.tex` in fase di compilazione. Affinché il processo funzioni, il documento LaTeX deve essere compilato almeno due volte: la prima compilazione *genera* i dati di riferimento, scrivendoli in `filename.aux`. Durante la seconda compilazione, LaTeX *legge* `filename.aux` per risolvere i riferimenti, fornendo dati per sostituire le occorrenze di `\ref{some_string}`. * Per maggiori dettagli sui riferimenti incrociati, consulta l'articolo Overleaf [Riferimenti incrociati a sezioni, equazioni e oggetti mobili](/latex/it/struttura-del-documento/03-cross-referencing-sections-equations-and-floats.md). ## Progetti in cui il pacchetto xr non è necessario I grandi progetti LaTeX, come libri o relazioni lunghe, sono spesso suddivisi in una serie di file più piccoli `.tex` file, uno per capitolo, con il file di ciascun capitolo `.tex` aggiunto al documento LaTeX principale utilizzando `\input` o `\include`. In genere, tali capitoli non sono autonomi: non è possibile compilare singoli capitoli perché non contengono una `\documentclass{...}` istruzione né il `\begin{document}...\end{document}` costrutto. Tali capitoli sono destinati all' *inclusione* in un documento “contenitore” che *può* essere compilato. In tali circostanze, i riferimenti incrociati agli elementi del documento, all'interno di qualsiasi singolo file di capitolo, possono procedere normalmente: non è necessario utilizzare `xr` pacchetto. Per esplorare un esempio di progetto di grandi dimensioni, puoi [aprire questo esempio in Overleaf.](https://www.overleaf.com/project/new/template/20618?id=70769185\&templateName=Managing+a+large+project+on+Overleaf\&latexEngine=pdflatex\&texImage=texlive-full%3A2020.1\&mainFile=) ## Esempio di un progetto in cui è richiesto il pacchetto xr Supponiamo di avere un insieme di documenti LaTeX autonomi, come una raccolta di N articoli: `article1.tex`, `article2.tex` ... `articleN.tex`. Ciascuno di questi articoli può essere compilato separatamente ed è probabile che sia stato scritto utilizzando una varietà di classi di documento, pacchetti ecc. Ora immagina di voler usare LaTeX per scrivere una panoramica o un riepilogo di tali articoli: chiameremo il nostro file `summary.tex`. Il nostro riepilogo deve fare riferimento a sezioni, figure, tabelle, equazioni ecc. contenute in questi N singoli articoli autonomi. Come possiamo farlo? La `xr` Il pacchetto consente di farlo: permette `summary.tex` di utilizzare etichette di riferimento generate da uno qualsiasi dei file autonomi `article*.tex` i file. ### Una nota sui file .aux * Nota: qui stiamo usando un asterisco (`*`) come segnaposto per qualsiasi numero da 1 a N. La compilazione di uno qualsiasi dei file autonomi `article1.tex`, `article2.tex` ... `articleN.tex` fa sì che LaTeX generi un corrispondente `article*.aux` (\*\*`aux`file ausiliario che, tra le altre cose, contiene i dati delle etichette necessari per generare riferimenti incrociati. Se uno qualsiasi dei `article*.tex` file viene modificato, ad esempio per cambiare, aggiungere o rimuovere etichette (`\label{...}`), il corrispondente `article*.tex` file deve essere ricompilato per aggiornare l'associato `article*.aux` file del tuo progetto. Il rilevamento delle modifiche a `article*.tex`, e la loro successiva ricompilazione, può essere automatizzato su Overleaf utilizzando un appropriato `latexmkrc` . ## Come usare xr su Overleaf Useremo una versione semplificata del nostro esempio con più articoli; in particolare, mostriamo come automatizzare il processo di compilazione tramite un `latexmkrc` file modificabile [fornito a Overleaf da John Collins](#code-for-latexmkrc) ([manutentore di `latexmk`](https://ctan.org/pkg/latexmk?lang=en)). ### File utilizzati nel nostro esempio Il nostro esempio utilizza i seguenti file: * `**summary.tex**`: questo è il nostro documento di panoramica. Abbiamo bisogno che faccia riferimento a contenuti presenti in `article1.tex`, come figure e sezioni. * `summary.tex` carica il `xr` pacchetto e usa `\externaldocument{article1}` per specificare che i dati di riferimento da `article1.aux` devono essere utilizzati. * `**article1.tex**`: un singolo articolo autonomo che contiene riferimenti incrociati interni. La compilazione di `article1.tex` genera dati di riferimento incrociato contenuti nel file `article1.aux`. * Un file esterno come `article1.tex` che potrebbe essere stato scritto da qualcun altro, affinché tu lo possa usare “così com'è”, cioè senza modificarlo. * `**latexmkrc**`: contiene codice (Perl) per automatizzare la ricompilazione di `article1.tex` a seguito di eventuali modifiche apportate a esso, per creare un aggiornato `article1.aux` . * Il nostro `latexmkrc` file era [fornito a Overleaf da John Collins](#code-for-latexmkrc) ([manutentore di `latexmk`](https://ctan.org/pkg/latexmk?lang=en)). ### Informazioni sul comando \externaldocument La `xr` Il pacchetto fornisce il comando`\externaldocument` che ha la forma generale ```latex \externaldocument[prefix]{external_file} ``` * **`prefix` (facoltativo):** Questo argomento facoltativo consente di definire un prefisso che verrà aggiunto a tutte le etichette importate dal documento esterno. È utile per evitare conflitti se gli stessi nomi di etichetta vengono utilizzati in più documenti. * **`external_file` (obbligatorio):** Questo argomento obbligatorio specifica il nome del documento LaTeX esterno (senza l' `.tex` estensione) dal quale si desidera importare i riferimenti. Il `xr` pacchetto cercherà il `.aux` file corrispondente a `external_file` (ad esempio, `external_file.aux`) per recuperare le etichette. Ad esempio, se il nostro file principale `.tex` file modificabile `summary.tex` e il file esterno, `article1.tex` contengono entrambi l'etichetta `\label{eq:1}` allora abbiamo un conflitto di nomi di etichetta. Questo conflitto può essere evitato scrivendo ```latex \externaldocument[art1-]{article1} ``` nel qual caso tutte le etichette create compilando `article1.tex` sono precedute da `art1-`. Ora puoi accedere a `\label{eq:1}`, contenuto in `article1.tex`, scrivendo `\ref{art1-eq:1}` in `summary.tex`. ### I file del progetto #### article1.tex Il seguente codice può essere aperto in Overleaf utilizzando il collegamento sotto l'elenco. ```latex \documentclass{article} \title{This is \texttt{article1.tex}} \begin{document} \section{Introduzione} \label{introduction} Questo è un documento \LaTeX{} autonomo con riferimenti che vogliamo utilizzare in \texttt{summary.tex}. \subsection{Math references} \label{mathrefs} Come menzionato nella sezione \ref{introduction}, è possibile fare riferimento a elementi diversi all'interno di un documento. \subsection{Powers series} \label{powers} \begin{equation} \label{eq:1} \sum_{i=0}^{\infty} a_i x^i \end{equation} L'equazione \ref{eq:1} è una tipica serie di potenze. \end{document} ``` [Apri `article1.tex` in Overleaf](https://www.overleaf.com/docs?engine=%5B%5B%3ATemplate%3AEngine%5D%5D}\&snip_name\[]=readme.txt\&snip\[]=A+project+created+from+the+Overleaf+wiki\&snip_name\[]=article1.tex\&main_document=article1.tex\&snip\[]=%5Cdocumentclass%7Barticle%7D%0A%5Ctitle%7BThis+is+%5Ctexttt%7Barticle1.tex%7D%7D%0A%5Cbegin%7Bdocument%7D%0A%5Csection%7BIntroduction%7D%0A%5Clabel%7Bintroduction%7D%0A%0AThis+is+a+standalone+%5CLaTeX%7B%7D+document+with%0Areferences+we+want+to+use+in+%5Ctexttt%7Bsummary.tex%7D.%0A%0A%5Csubsection%7BMath+references%7D%0A%5Clabel%7Bmathrefs%7D%0AAs+mentioned+in+section+%5Cref%7Bintroduction%7D%2C+%0Adifferent+elements+can+be+referenced+within%0Aa+document.%0A%0A%5Csubsection%7BPowers+series%7D%0A%5Clabel%7Bpowers%7D%0A%0A%5Cbegin%7Bequation%7D%0A%5Clabel%7Beq%3A1%7D%0A%5Csum_%7Bi%3D0%7D%5E%7B%5Cinfty%7D+a_i+x%5Ei%0A%5Cend%7Bequation%7D%0A%0AEquation+%5Cref%7Beq%3A1%7D+is+a+typical+power+series.%0A%5Cend%7Bdocument) La compilazione di `article1.tex` produce il seguente output: ![Output prodotto compilando il file article1.tex su Overleaf](/files/d74d303fb9f7d3c9c73c3c064482c6a010040f8b) #### summary.tex Ecco il nostro iniziale `summary.tex` file modificabile *prima che* abbiamo specificato quale documento esterno desideriamo referenziare. Per semplicità, `summary.tex` non contiene alcun `\label` comando perché non esistono riferimenti incrociati interni. Tutti i `\ref` comandi fanno riferimento a etichette generate da `\label` comandi contenuti in `article1.tex`. ```latex \documentclass{article} \usepackage{xr} \title{This is \texttt{summary.tex}} \begin{document} Nel file \texttt{article1.tex}, l'introduzione è la sezione \ref{introduction}. In quel file, ci sono due sottosezioni: \ref{mathrefs} e \ref{powers}. Nella sottosezione \ref{powers}, l'equazione \ref{eq:1} mostra una serie di potenze. \end{document} ``` [Apri questo *incompleto* `summary.tex` in Overleaf](https://www.overleaf.com/docs?engine=%5B%5B%3ATemplate%3AEngine%5D%5D}\&snip_name\[]=readme.txt\&snip\[]=A+project+created+from+the+Overleaf+wiki\&snip_name\[]=summary.tex\&main_document=summary.tex\&snip\[]=%5Cdocumentclass%7Barticle%7D%0A%5Cusepackage%7Bxr%7D%0A%5Ctitle%7BThis+is+%5Ctexttt%7Bsummary.tex%7D%7D%0A%5Cbegin%7Bdocument%7D%0AIn+the+file+%5Ctexttt%7Barticle1.tex%7D%2C+the+introduction+is+section+%5Cref%7Bintroduction%7D.++In+that+file%2C+there+are+two+subsections%3A+%5Cref%7Bmathrefs%7D+and+%5Cref%7Bpowers%7D.+In+subsection+%5Cref%7Bpowers%7D%2C+equation+%5Cref%7Beq%3A1%7D+demonstrates+a+power+series.%0A%5Cend%7Bdocument%7D) Se compiliamo questa versione di `summary.tex` tenterà di leggere i dati di riferimento da `summary.aux` ma i dati necessari sono contenuti nel file esterno `article1.aux` che non è ancora accessibile. La compilazione di questo `summary.tex` file incompleto produce il seguente output, con doppi punti interrogativi che indicano riferimenti non definiti: ![Immagine che mostra riferimenti mancanti segnalati](/files/46f08046ffda0ed9d3f9e7bd78a95ea48b78786f) ### Specificare il documento esterno Il passo successivo è specificare `article1` come nome del documento esterno le cui etichette vogliamo referenziare. Aggiungi la seguente riga al preambolo di `summary.tex`: ```latex \externaldocument{article1} ``` Qui, `article1` può essere sostituito da qualsiasi file alle cui etichette desideri accedere: puoi utilizzare più `\externaldocument` comandi per accedere a file esterni aggiuntivi. ### Creazione del file latexmkrc Il passo successivo è creare un `latexmkrc` file come mostrato di seguito: * Nella finestra dell'editor del progetto, seleziona l'icona **Nuovo file** nell'angolo superiore sinistro della finestra del progetto. * Seleziona **Nuovo file** dall'interno della finestra di dialogo a comparsa **Aggiungi file** e assegna al file il nome `latexmkrc`—nota che non esiste un'estensione del file: ![Creazione di un file latexmkrc in Overleaf](/files/d2ee21b28fef46c85a26edeefe2665faab811199) * Assicurati che il `latexmkrc` file sia creato e salvato al livello superiore (radice) dell'area file del progetto. Ovvero, non all'interno di alcuna cartella nell'albero dei file. * Copia e incolla il seguente codice nel tuo `latexmkrc` . #### Codice per latexmkrc Overleaf è grata a John Collins, [manutentore di `latexmk`](https://ctan.org/pkg/latexmk?lang=en), per averci contattato e fornito il seguente `latexmkrc` file, che siamo lieti di pubblicare integralmente, inclusi i commenti in linea estremamente utili. ```perl # Questo mostra come usare il pacchetto xr con latexmk. # John Collins 2023-03-29 # # Il pacchetto xr ("un sistema per riferimenti eXterni") viene usato da un documento # per creare riferimenti a sezioni, equazioni ecc. in altri documenti # esterni. # Le definizioni in questo file consentono a latexmk di applicare latexmk per # aggiornare automaticamente un documento esterno ogni volta che il relativo file .tex cambia, # in modo che i riferimenti nel documento principale restino aggiornati. # Note: # 1. Questa versione è definita per inserire i file dalle compilazioni di # documenti esterni in una sottodirectory definita, per separare # i potenzialmente numerosi file generati dalle directory del documento # principale. # 2. Tuttavia, affinché venga utilizzato il meccanismo di dipendenze personalizzate di latexmk, come qui, # il file aux dalla compilazione di un sottodocumento deve essere generato nella # stessa directory del corrispondente file sorgente .tex. Quindi il # file .aux viene copiato. # 3. Si presume che i documenti esterni debbano essere compilati con # pdflatex. Questo può naturalmente essere cambiato modificando l'opzione '-pdf' # fornita al latexmk invocato con quella necessaria. # 4. Un'implementazione ideale garantirebbe inoltre che la ricompilazione di un # documento esterno avvenga anche ogni volta che uno qualsiasi degli altri file sorgente # cambia. Ma ciò non viene fatto nella versione attuale e # probabilmente richiederebbe l'uso di variabili interne di latexmk # o miglioramenti aggiuntivi a latexmk. # 5. Il codice usa le subroutine copy e fileparse che vengono caricate da # latexmk dai pacchetti Perl File::Copy e File::Basename. # 6. Usa inoltre alcune funzionalità non ancora documentate di latexmk: una variabile # array @file_not_found e le subroutine popd, pushd e # rdb_add_generated. #-------------------- # Scelte configurabili per la compilazione di documenti esterni # Sottodirectory per i file di output dalla compilazione di documenti esterni: $sub_doc_output = 'output-subdoc'; # Opzioni da fornire a latexmk per la compilazione di documenti esterni: @sub_doc_options = (); push @sub_doc_options, '-pdf'; # Usa pdflatex per la compilazione di documenti esterni. # Se necessario, sostituisci '-pdf' con '-pdfdvi', 'pdfxe' o 'pdflua'. #-------------------- # Aggiungi alla lista di latexmk un modello per il messaggio nel file di log di xr relativo ai file mancanti. # La variabile @file_not_found di Latexmk non è ancora documentata. # Questa riga non è necessaria per la versione 4.80 o successiva di latexmk. push @file_not_found, '^No file\\s*(.+)\s*$'; add_cus_dep( 'tex', 'aux', 0, 'makeexternaldocument' ); sub makeexternaldocument { if ( $root_filename ne $_[0] ) { my ($base_name, $path) = fileparse( $_[0] ); pushd $path; my $return = system "latexmk", @sub_doc_options, "-aux-directory=$sub_doc_output", "-output-directory=$sub_doc_output", $base_name; if ( ($sub_doc_output ne '') && ($sub_doc_output ne '.') ) { # In questo caso, il file .aux generato da pdflatex non si trova nella stessa # directory del file .tex. # Pertanto: # 1. Il file aux effettivamente generato deve essere elencato come prodotto da questa # regola, affinché latexmk gestisca correttamente le dipendenze. # (Problema da superare: se $sub_dir_output coincide con $aux_dir # per il documento principale, xr potrebbe leggere il file .aux nella # aux_dir anziché quello che latexmk presume venga prodotto dalla dipendenza personalizzata # e che si trova nella stessa directory del file sorgente .tex # per questa dipendenza personalizzata.) # Usa la subroutine latexmk non ancora documentata rdb_add_generated # per farlo: # 2. Una copia del file .aux deve trovarsi nella stessa directory del file .tex # per soddisfare la definizione di dipendenza personalizzata di latexmk. rdb_add_generated( "$sub_doc_output/$base_name.aux" ); copy "$sub_doc_output/$base_name.aux", "."; } popd; return $return; } } ``` ### Apri un progetto Overleaf che mostra xr Il seguente progetto composto da tre file può ora essere aperto in Overleaf utilizzando i collegamenti forniti sopra e sotto gli elenchi dei file. Nota che il `latexmkrc` file contiene il codice fornito da John Collins ma, per brevità, la maggior parte dei commenti è stata rimossa. [Apri questo esempio a tre file in Overleaf.](/latex/it/base-di-conoscenza/033-cross-referencing-with-the-xr-package-in-overleaf.md) **summary.tex** Questo è il nostro file di riepilogo. Da questo file vogliamo usare riferimenti incrociati creati in file esterni. Qui vogliamo usare etichette generate in `article1.tex`. ```latex \documentclass[12pt]{article} \usepackage{xr} \title{Using the xr package on Overleaf} % inserisci qui tutti i documenti esterni! \externaldocument{article1} \begin{document} Nel file \texttt{article1.tex}, l'introduzione è la sezione \ref{introduction}. In quel file, ci sono due sottosezioni: \ref{mathrefs} e \ref{powers}. Nella sottosezione \ref{powers}, l'equazione \ref{eq:1} mostra una serie di potenze. \end{document} ``` **article1.tex** Questo file è uno dei nostri articoli. Nota come contiene vari `\label` comandi per creare etichette che, grazie al `xr` pacchetto, possiamo usare nel file `summary.tex`. ```latex \documentclass{article} \title{This is \texttt{article1.tex}} \begin{document} \section{Introduzione} \label{introduction} Questo è un documento \LaTeX{} autonomo con riferimenti che vogliamo utilizzare in \texttt{summary.tex}. \subsection{Math references} \label{mathrefs} Come menzionato nella sezione \ref{introduction}, è possibile fare riferimento a elementi diversi all'interno di un documento. \subsection{Powers series} \label{powers} \begin{equation} \label{eq:1} \sum_{i=0}^{\infty} a_i x^i \end{equation} L'equazione \ref{eq:1} è una tipica serie di potenze. \end{document} ``` **latexmkrc** Questo `latexmkrc` file contiene codice per garantire che i file esterni vengano compilati. ```latex $sub_doc_output = 'output-subdoc'; @sub_doc_options = (); push @sub_doc_options, '-pdf'; # Usa pdflatex per la compilazione di documenti esterni. # Se necessario, sostituisci '-pdf' con '-pdfdvi', 'pdfxe' o 'pdflua'. push @file_not_found, '^No file\\s*(.+)\s*$'; add_cus_dep( 'tex', 'aux', 0, 'makeexternaldocument' ); sub makeexternaldocument { if ( $root_filename ne $_[0] ) { my ($base_name, $path) = fileparse( $_[0] ); pushd $path; my $return = system "latexmk", @sub_doc_options, "-aux-directory=$sub_doc_output", "-output-directory=$sub_doc_output", $base_name; if ( ($sub_doc_output ne '') && ($sub_doc_output ne '.') ) { rdb_add_generated( "$sub_doc_output/$base_name.aux" ); copy "$sub_doc_output/$base_name.aux", "."; } popd; return $return; } } ``` [Apri questo esempio a tre file in Overleaf.](/latex/it/base-di-conoscenza/033-cross-referencing-with-the-xr-package-in-overleaf.md) Il seguente grafico è una versione annotata dell'output ottenuto componendo `summary.tex`, che mostra i riferimenti incrociati e le etichette corrispondenti dal file esterno `article1.tex`. ![Visualizzazione dei riferimenti importati da un file esterno](/files/12c83f062f080839d6c7bac25cfeee534a3ea800) * Per maggiori dettagli sui riferimenti incrociati, consulta l'articolo Overleaf [Riferimenti incrociati a sezioni, equazioni e oggetti mobili](/latex/it/struttura-del-documento/03-cross-referencing-sections-equations-and-floats.md). ## Una nota sugli errori di sintassi Per il file principale del progetto, puoi usare la modalità di compilazione di Overleaf [Interrompi al primo errore](/latex/it/base-di-conoscenza/149-using-the-stop-on-first-error-compilation-mode.md) per assicurarti che la compilazione termini immediatamente al rilevamento del primo errore. Questo può aiutare a isolare e identificare gli errori nel codice, anziché consentire che gli errori si propaghino a cascata, rendendo molto più difficile individuare ed eseguire il debug dei problemi. La *external* i documenti vengono compilati automaticamente tramite il `latexmkrc` file; di conseguenza, eventuali errori di sintassi LaTeX al loro interno non verranno visualizzati nell'interfaccia di Overleaf, a meno che non li ricompili anche in Overleaf. Gli errori in tali file esterni potrebbero impedire la corretta visualizzazione dei riferimenti incrociati nel file PDF composto, pertanto consigliamo vivamente di controllare e correggere tali errori non appena si verificano. --- # 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/base-di-conoscenza/033-cross-referencing-with-the-xr-package-in-overleaf.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.