> 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/overleaf-learn-latex-pt/base-de-conhecimento/033-cross-referencing-with-the-xr-package-in-overleaf.md). # Referência cruzada com o pacote xr no Overleaf ## Visão geral O [`xr` pacote](https://ctan.org/pkg/xr?lang=en) permite-lhe criar referências cruzadas a equações, figuras, tabelas etc. contidas em documentos LaTeX externos, desde que esses documentos sejam *independentes.* Um documento LaTeX independente é aquele que pode ser compilado porque contém uma `\documentclass{...}` instrução e o `\begin{document}`...`\end{document}` construto. ### Resumo de utilização 1. Escreva `\usepackage{xr}` no preâmbulo do ficheiro LaTeX que precisa de fazer referência cruzada ao conteúdo contido em ficheiros LaTeX externos. 2. Use a `xr` comando do pacote `\externaldocument{filename}` para especificar o(s) documento(s) externo(s) cujo conteúdo pretende referenciar cruzadamente. O `xr` O pacote funciona usando rótulos de referência cruzada contidos nos `.aux` ficheiros gerados quando os documentos LaTeX externos são compilados. ### Como funciona a referenciação cruzada (um breve resumo) Para fazer referência cruzada a um item num documento LaTeX, precisa de: 1. Dar-lhe um identificador único, `some_string`, usando o `\label` comando: ```latex \label{some_string} ``` 3. No local onde pretende referenciar esse elemento, precisa de escrever ```latex \ref{some_string} ``` Muito brevemente, o LaTeX gere a referenciação cruzada escrevendo dados para um ficheiro chamado `filename.aux` onde `filename` é o nome do principal `.tex` ficheiro que está a ser compilado. Para o processo funcionar, o documento LaTeX tem de ser compilado pelo menos duas vezes: a primeira compilação *gera* os dados de referência — escrevendo-os em `filename.aux`. Durante a segunda compilação, o LaTeX *lê* `filename.aux` para resolver as referências, fornecendo dados para substituir ocorrências de `\ref{some_string}`. * Para mais detalhes sobre referenciação cruzada, veja o artigo do Overleaf [Referenciar cruzadamente secções, equações e objetos flutuantes](/latex/overleaf-learn-latex-pt/estrutura-do-documento/03-cross-referencing-sections-equations-and-floats.md). ## Projetos em que o pacote xr não é necessário Projetos LaTeX grandes, como livros ou relatórios longos, são frequentemente divididos numa série de ficheiros menores `.tex` ficheiros, um por capítulo, com o ficheiro de cada capítulo `.tex` adicionado ao documento LaTeX principal usando `\input` ou `\include`. Normalmente, esses capítulos não são independentes: não pode compilar capítulos individuais porque não contêm uma `\documentclass{...}` instrução ou o `\begin{document}...\end{document}` construto. Esses capítulos destinam-se à *inclusão* num documento “contentor” que *pode* ser compilado. Nessas circunstâncias, a referenciação cruzada para elementos do documento — dentro de qualquer ficheiro de capítulo individual — pode prosseguir normalmente: não precisa de usar o `xr` pacote. Para explorar um exemplo de um projeto grande, pode [abrir este exemplo no 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=) ## Exemplo de um projeto em que o pacote xr é necessário Suponha que tem um conjunto de documentos LaTeX independentes, como uma coleção de N artigos: `article1.tex`, `article2.tex` ... `articleN.tex`. Cada um desses artigos pode ser compilado separadamente e é provável que tenham sido escritos usando uma variedade de classes de documento, pacotes etc. Agora imagine que quer usar o LaTeX para escrever uma visão geral ou resumo desses artigos — vamos chamar ao nosso ficheiro `summary.tex`. O nosso resumo precisa de fazer referência a secções, figuras, tabelas, equações etc. contidas nesses artigos individuais e independentes, N. Como podemos fazer isso? O `xr` o pacote permite-lhe fazer isso: ele permite `summary.tex` usar rótulos de referência gerados por qualquer um dos artigos independentes `article*.tex` ficheiros. ### Uma nota sobre os ficheiros .aux * Nota: aqui estamos a usar um asterisco (`*`) como marcador para qualquer número de 1 a N. Compilar qualquer um dos ficheiros independentes `article1.tex`, `article2.tex` ... `articleN.tex` faz com que o LaTeX gere um correspondente `article*.aux` (\*\*`aux`ficheiro \*\*auxiliar\*\*, que, entre outros elementos, contém dados de rótulos necessários para gerar referências cruzadas. Se algum dos `article*.tex` ficheiros for editado — por exemplo, para alterar, adicionar ou remover rótulos (`\label{...}`) — os correspondentes `article*.tex` ficheiro(s) têm de ser recompilados para atualizar o `article*.aux` ficheiro(s). Detetar alterações em `article*.tex`, e recompilá-los subsequentemente, pode ser automatizado no Overleaf usando um `latexmkrc` ficheiro. ## Como usar o xr no Overleaf Usaremos uma versão simplificada do nosso exemplo de vários artigos; em particular, mostramos como automatizar o processo de compilação através de um `latexmkrc` editável [fornecido ao Overleaf por John Collins](#code-for-latexmkrc) ([responsável pela manutenção de `latexmk`](https://ctan.org/pkg/latexmk?lang=en)). ### Ficheiros usados no nosso exemplo O nosso exemplo usa os seguintes ficheiros: * `**summary.tex**`: este é o nosso documento de visão geral. Precisamos que ele referencie conteúdo contido em `article1.tex`, como figuras e secções. * `summary.tex` carrega o `xr` pacote e usa `\externaldocument{article1}` para especificar que os dados de referência de `article1.aux` devem ser usados. * `**article1.tex**`: um único artigo independente que contém referências cruzadas internas. Compilar `article1.tex` gera dados de referência cruzada contidos no ficheiro `article1.aux`. * Um ficheiro externo como `article1.tex` que pode ter sido escrito por outra pessoa — para você usar “tal como fornecido”, ou seja, sem alterações. * `**latexmkrc**`: contém código (Perl) para automatizar a recompilação de `article1.tex` devido a quaisquer alterações feitas nele — para criar um `article1.aux` ficheiro. * O nosso `latexmkrc` ficheiro foi [fornecido ao Overleaf por John Collins](#code-for-latexmkrc) ([responsável pela manutenção de `latexmk`](https://ctan.org/pkg/latexmk?lang=en)). ### Sobre o comando \externaldocument O `xr` o pacote fornece o`\externaldocument` comando, que tem a forma geral ```latex \externaldocument[prefix]{external_file} ``` * **`prefixo` (opcional):** Este argumento opcional permite definir um prefixo que será adicionado a todos os rótulos importados do documento externo. Isto é útil para evitar conflitos se os mesmos nomes de rótulos forem usados em vários documentos. * **`external_file` (obrigatório):** Este argumento obrigatório especifica o nome do documento LaTeX externo (sem a `.tex` extensão) do qual pretende importar referências. O `xr` pacote procurará o `.aux` ficheiro correspondente a `external_file` (por exemplo, `external_file.aux`) para recuperar os rótulos. Por exemplo, se o nosso principal `.tex` editável `summary.tex` e o ficheiro externo, `article1.tex` contêm ambos o rótulo `\label{eq:1}` então temos um conflito de nomes de rótulos. Esse conflito pode ser evitado escrevendo ```latex \externaldocument[art1-]{article1} ``` caso em que todos os rótulos criados ao compilar `article1.tex` são precedidos pelo `art1-`. Agora pode aceder a `\label{eq:1}`, contido em `article1.tex`, escrevendo `\ref{art1-eq:1}` em `summary.tex`. ### Os ficheiros do projeto #### article1.tex O código seguinte pode ser aberto no Overleaf usando a ligação abaixo da listagem. ```latex \documentclass{article} \title{This is \texttt{article1.tex}} \begin{document} \section{Introdução} \label{introduction} Este é um documento \LaTeX{} independente com referências que queremos usar em \texttt{summary.tex}. \subsection{Math references} \label{mathrefs} Como mencionado na secção \ref{introduction}, podem ser referenciados diferentes elementos dentro de um documento. \subsection{Séries de potências} \label{powers} \begin{equation} \label{eq:1} \sum_{i=0}^{\infty} a_i x^i \end{equation} A equação \ref{eq:1} é uma série de potências típica. \end{document} ``` [Abrir `article1.tex` no 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) A compilar `article1.tex` produz a seguinte saída: ![Saída produzida pela compilação do ficheiro article1.tex no Overleaf](/files/19e987a71b8a3eb8e3168c6c1ade0e793d91e9b0) #### summary.tex Aqui está o nosso inicial `summary.tex` editável *antes de* especificámos qual documento externo queremos referenciar. Por simplicidade, `summary.tex` não contém quaisquer `\label` comandos porque não existem referências cruzadas internas. Todos `\ref` os comandos referem-se a rótulos gerados pelos `\label` comandos contidos em `article1.tex`. ```latex \documentclass{article} \usepackage{xr} \title{This is \texttt{summary.tex}} \begin{document} No ficheiro \texttt{article1.tex}, a introdução é a secção \ref{introduction}. Nesse ficheiro, existem duas subseções: \ref{mathrefs} e \ref{powers}. Na subseção \ref{powers}, a equação \ref{eq:1} demonstra uma série de potências. \end{document} ``` [Abra este *incompleto* `summary.tex` no 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 compilarmos esta versão de `summary.tex` tentará ler dados de referência de `summary.aux` mas os dados necessários estão contidos no ficheiro externo `article1.aux` ao qual ainda não se pode aceder. Compilando este `summary.tex` ficheiro incompleto, obtém-se a seguinte saída, com pontos de interrogação duplos a mostrar referências indefinidas: ![Imagem que mostra o relatório de referências em falta](/files/d9f6653a469d1a5d69a20e5969ea9d316541d80e) ### Especificar o documento externo O passo seguinte é especificar `article1` como o nome do documento externo cujos rótulos queremos referenciar. Adicione a seguinte linha ao preâmbulo de `summary.tex`: ```latex \externaldocument{article1} ``` Aqui, `article1` pode ser substituído por qualquer ficheiro cujos rótulos pretenda aceder — pode usar vários `\externaldocument` comandos para aceder a ficheiros externos adicionais. ### Criar o ficheiro latexmkrc O passo seguinte é criar um `latexmkrc` ficheiro como mostrado abaixo: * Na janela do editor do projeto, selecione o **Novo ficheiro** ícone no canto superior esquerdo da janela do projeto. * Selecione **Novo ficheiro** a partir do **Adicionar ficheiros** caixa de diálogo pop-up e dê ao ficheiro o nome `latexmkrc`— note que não existe extensão de ficheiro: ![Criar um ficheiro latexmkrc no Overleaf](/files/33d00d130c442aadfa5ffa3b5241c19fbdd1e90b) * Certifique-se de que o `latexmkrc` ficheiro é criado e guardado no nível superior (raiz) da área de ficheiros do projeto. Ou seja, não dentro de nenhuma pasta na árvore de ficheiros. * Copie e cole o código seguinte no seu `latexmkrc` ficheiro. #### Código para latexmkrc O Overleaf agradece a John Collins, [responsável pela manutenção de `latexmk`](https://ctan.org/pkg/latexmk?lang=en), por nos contactar para fornecer o seguinte `latexmkrc` ficheiro, que temos o prazer de publicar na íntegra — incluindo os comentários em linha extremamente úteis. ```perl # Isto mostra como usar o pacote xr com latexmk. # John Collins 2023-03-29 # # O pacote xr ("um sistema para referências externas") é usado por um documento # para fazer referências a secções, equações, etc. noutros # documentos. # As definições neste ficheiro permitem que o latexmk aplique o latexmk a # atualizar automaticamente um documento externo sempre que o seu ficheiro .tex seja alterado, # para que as referências no documento principal se mantenham atualizadas. # Notas: # 1. Esta versão está definida para colocar os ficheiros das compilações de # os documentos externos numa subpasta definida, para separar # potencialmente muitos ficheiros gerados do documento principal # diretórios. # 2. Mas para que o mecanismo de dependência personalizada do latexmk seja usado, como aqui, # o ficheiro aux da compilação de um subdocumento tem de ser gerado na # mesma diretoria que o ficheiro .tex de origem correspondente. Assim, o # ficheiro .aux é copiado. # 3. Assume-se que os documentos externos serão compilados por # pdflatex. Isto pode ser alterado, claro, mudando a opção '-pdf' # dada ao latexmk invocado para o que for necessário. # 4. Uma implementação ideal também garantiria que a recompilação de um # documento externo também acontecesse sempre que qualquer dos seus outros ficheiros de origem # fosse alterado. Mas isso não é feito na versão atual, e # provavelmente implicaria quer o uso de variáveis internas do latexmk # ou melhorias adicionais ao latexmk. # 5. O código usa as sub-rotinas copy e fileparse que são carregadas pelo # latexmk a partir dos pacotes Perl File::Copy e File::Basename. # 6. Também usa algumas funcionalidades ainda não documentadas do latexmk: uma matriz # variável @file_not_found e as sub-rotinas popd, pushd e # rdb_add_generated. #-------------------- # Opções configuráveis para a compilação de documentos externos # Subdiretório para ficheiros de saída da compilação de documentos externos: $sub_doc_output = 'output-subdoc'; # Opções a fornecer ao latexmk para a compilação de documentos externos: @sub_doc_options = (); push @sub_doc_options, '-pdf'; # Use o pdflatex para a compilação de documentos externos. # Substitua '-pdf' por '-pdfdvi', 'pdfxe' ou 'pdflua' se necessário. #-------------------- # Adicione um padrão para a mensagem do ficheiro de registo do xr sobre ficheiros em falta à # lista. A variável @file_not_found do Latexmk ainda não está documentada. # Esta linha não é necessária para a v. 4.80 ou posterior do 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 '.') ) { # Neste caso, o ficheiro .aux gerado pelo pdflatex não está na mesma # diretoria do ficheiro .tex. # Portanto: # 1. O ficheiro aux gerado efetivamente tem de ser listado como produzido por esta # regra, para que o latexmk trate corretamente das dependências. # (Problema a ultrapassar: se $sub_dir_output for o mesmo que $aux_dir # para o documento principal, o xr pode ler o ficheiro .aux no # aux_dir em vez daquele que a dependência personalizada (cus dep) é assumida pelo latexmk # como produzido, que está na mesma diretoria que o ficheiro-fonte .tex # para esta dependência personalizada.) # Use a sub-rotina ainda não documentada do latexmk rdb_add_generated # para fazer isso: # 2. Uma cópia do ficheiro .aux tem de estar na mesma diretoria que o ficheiro .tex # para satisfazer a definição de dependência personalizada do latexmk. rdb_add_generated( "$sub_doc_output/$base_name.aux" ); copy "$sub_doc_output/$base_name.aux", "."; } popd; return $return; } } ``` ### Abrir um projeto no Overleaf que demonstra o xr O projeto de três ficheiros seguinte pode agora ser aberto no Overleaf usando as ligações fornecidas acima e abaixo das listagens de ficheiros. Note que o `latexmkrc` ficheiro contém o código fornecido por John Collins, mas, por brevidade, a maioria dos comentários foi removida. [Abra este exemplo de três ficheiros no Overleaf.](/latex/overleaf-learn-latex-pt/base-de-conhecimento/033-cross-referencing-with-the-xr-package-in-overleaf.md) **summary.tex** Este é o nosso ficheiro de resumo. Dentro deste ficheiro, queremos usar referências cruzadas criadas em ficheiros externos. Aqui, queremos usar rótulos gerados em `article1.tex`. ```latex \documentclass[12pt]{article} \usepackage{xr} \title{Using the xr package on Overleaf} % coloque aqui todos os documentos externos! \externaldocument{article1} \begin{document} No ficheiro \texttt{article1.tex}, a introdução é a secção \ref{introduction}. Nesse ficheiro, existem duas subseções: \ref{mathrefs} e \ref{powers}. Na subseção \ref{powers}, a equação \ref{eq:1} demonstra uma série de potências. \end{document} ``` **article1.tex** Este ficheiro é um dos nossos artigos. Repare como contém vários `\label` comandos para criar rótulos que, graças ao `xr` pacote, podemos usar no ficheiro `summary.tex`. ```latex \documentclass{article} \title{This is \texttt{article1.tex}} \begin{document} \section{Introdução} \label{introduction} Este é um documento \LaTeX{} independente com referências que queremos usar em \texttt{summary.tex}. \subsection{Math references} \label{mathrefs} Como mencionado na secção \ref{introduction}, podem ser referenciados diferentes elementos dentro de um documento. \subsection{Séries de potências} \label{powers} \begin{equation} \label{eq:1} \sum_{i=0}^{\infty} a_i x^i \end{equation} A equação \ref{eq:1} é uma série de potências típica. \end{document} ``` **latexmkrc** Este `latexmkrc` ficheiro contém código para garantir que os ficheiros externos são compilados. ```latex $sub_doc_output = 'output-subdoc'; @sub_doc_options = (); push @sub_doc_options, '-pdf'; # Use o pdflatex para a compilação de documentos externos. # Substitua '-pdf' por '-pdfdvi', 'pdfxe' ou 'pdflua' se necessário. 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; } } ``` [Abra este exemplo de três ficheiros no Overleaf.](/latex/overleaf-learn-latex-pt/base-de-conhecimento/033-cross-referencing-with-the-xr-package-in-overleaf.md) O gráfico seguinte é uma versão anotada da saída da composição tipográfica de `summary.tex`, mostrando as referências cruzadas e os rótulos correspondentes do ficheiro externo `article1.tex`. ![Mostrando referências importadas de um ficheiro externo](/files/141b925b3e6a17654fa17135313976a7859afd91) * Para mais detalhes sobre referenciação cruzada, veja o artigo do Overleaf [Referenciar cruzadamente secções, equações e objetos flutuantes](/latex/overleaf-learn-latex-pt/estrutura-do-documento/03-cross-referencing-sections-equations-and-floats.md). ## Uma nota sobre erros de sintaxe Para o ficheiro principal do projeto, pode usar o [modo de compilação Stop on First Error](/latex/overleaf-learn-latex-pt/base-de-conhecimento/149-using-the-stop-on-first-error-compilation-mode.md) para garantir que a compilação termina imediatamente após a deteção do primeiro erro. Isto pode ajudar a isolar e identificar erros no seu código, em vez de permitir que os erros se propaguem, o que torna muito mais difícil encontrar e depurar problemas. O *external* os documentos são compilados automaticamente através do `latexmkrc` ficheiro; consequentemente, quaisquer erros de sintaxe LaTeX dentro deles não aparecerão na interface do Overleaf — a menos que os volte a compilar também no Overleaf. Erros nesses ficheiros externos podem impedir que as referências cruzadas apareçam corretamente no ficheiro PDF composto, por isso recomendamos fortemente verificar e corrigir quaisquer desses erros assim que ocorram. --- # 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/overleaf-learn-latex-pt/base-de-conhecimento/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.