> 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/artigos-aprofundados/06-an-introduction-to-kpathsea-and-how-tex-engines-search-for-files.md). # Uma introdução ao Kpathsea e à forma como os motores TeX procuram ficheiros ## Introdução Este artigo fornece uma introdução a como os motores TeX localizam os arquivos necessários para compor seu documento — usando LaTeX ou qualquer outro pacote de macros. Embora o Overleaf alivie os usuários dos desafios de gerenciar uma instalação TeX ([TeX Live](https://www.tug.org/texlive/)), o básico de como os motores TeX procuram arquivos será útil/interessante se você quiser criar uma estrutura de pastas para ajudar a gerenciar seu projeto Overleaf. Por que isso pode ser verdade? Se você armazenar alguns dos arquivos do seu projeto Overleaf dentro de pastas, o LaTeX talvez não encontre esses arquivos porque, por padrão, o motor TeX (compilador) pode não *saber* que precisa procurar nessas pastas — assim, não encontrará os arquivos que elas contêm. Para evitar isso, você pode criar e adicionar ao seu projeto um arquivo de configuração chamado [arquivo latexmkrc](https://mg.readthedocs.io/latexmk.html#configuration-files) que pode ser usado para informar a um motor TeX que suas pastas existem e que ele deve procurá-las. Se você quiser ver um exemplo mostrando um arquivo latexmkrc, pode ler este artigo de ajuda: [Como usar latexmkrc com Overleaf: exemplos e técnicas](/latex/overleaf-learn-latex-pt/artigos-aprofundados/28-how-to-use-latexmkrc-with-overleaf.md). Talvez não seja imediatamente óbvio como, ou por que, esse arquivo latexmkrc realmente funciona. Se você quiser saber por quê e, talvez, desenvolver uma melhor compreensão para uso com outras possibilidades de configuração do seu projeto, então continue lendo... No final deste artigo, vamos trabalhar em um [exemplo prático](#kpathsea-and-texinputs-latexmkrc-file-to-the-rescue)—usando nosso conhecimento de como o TeX procura arquivos—para criar um arquivo latexmkrc para gerenciar pastas aninhadas contendo seus arquivos gráficos. ## TeX e independência de plataforma Quando Knuth criou o TeX, a independência de plataforma era um princípio central que orientava seu design e implementação, e essa filosofia é refletida em todas as operações internas do TeX (por exemplo, usando aritmética inteira, manipulação de strings “caseira”, gerenciamento de memória etc.). Ainda hoje, a independência de plataforma dos motores modernos baseados em TeX continua gerando dúvidas e debate em fóruns públicos; por exemplo, veja esta discussão no tex.stackexchange: [XeTeX e LuaTeX são dependentes de plataforma?](https://tex.stackexchange.com/questions/94297/are-xetex-and-luatex-platform-dependent) que contém comentários e observações feitas por vários especialistas bem conhecidos em TeX. No entanto, por ora vamos deixar de lado os detalhes mais finos e observar que os motores TeX ainda precisam ser altamente portáveis — capazes de funcionar em vários sistemas operacionais e produzir resultados “idênticos”. Um aspecto fundamental da portabilidade é procurar arquivos de maneira independente da plataforma. ## Os motores TeX não procuram arquivos… ou será que procuram!? Não, os motores TeX não *diretamente* procuram arquivos *por conta própria*. Ao processar um `.tex` arquivo, um motor TeX pode identificar a necessidade de abrir um arquivo específico, mas ele *delega* a tarefa de encontrá-lo a outro software chamado [*Kpathsea*](https://tug.org/kpathsea/): uma biblioteca de software externa que não faz parte do código-fonte *principal* dos motores TeX. O que o Kpathsea fornece é, na prática, uma API ([Interface de Programação de Aplicações](https://en.wikipedia.org/wiki/Application_programming_interface)) que os motores TeX (além do BibTeX, MetaPost e outras aplicações) podem chamar sempre que precisarem abrir um arquivo específico: o Kpathsea faz o trabalho real de localizar esse arquivo. Quando Knuth escreveu o motor TeX original — do qual todos os outros motores TeX descendem, em última instância — o problema de encontrar/abrir arquivos era um desafio significativo devido, em parte, ao ecossistema tecnológico altamente heterogêneo daquela época. De fato, no código-fonte do TeX, Knuth se refere à entrada/saída de arquivos como o flagelo da portabilidade (veja a página 12, seção 25 de [TeX: The Program](https://www.amazon.co.uk/Computers-Typesetting-TeX-Program-TEX/dp/0201134373)). A comunidade TeX reconheceu a necessidade de harmonizar (padronizar) a busca de arquivos para TeX —*e software relacionado ao TeX*—e decidiu fornecer ao TeX as ferramentas para fazer isso. Para enfrentar o problema muito espinhoso de um método independente de plataforma para localizar arquivos, Karl Berry, membro de destaque da comunidade TeX, escreveu o software para resolver o *problema de*busca por caminhos [**Kpathsea**](http://tug.org/texinfohtml/kpathsea.html)—uma solução que ele chamou de **K**arl’s **Path** **Sea**rching (veja esta [entrevista com Karl Berry](http://www.tug.org/interviews/berry.html)). Podemos observar que se chama K**problema de**sea e não K**editável**sea porque, como a [documentação](http://tug.org/texinfohtml/kpathsea.html) observa, é uma biblioteca de busca por \*caminhos\*. É importante reconhecer que o Kpathsea não é usado apenas por motores TeX; vários programas relacionados ao TeX, incluindo BibTeX e MetaPost, também usam Kpathsea para procurar arquivos de entrada. Em resumo, sempre que as macros de TeX/LaTeX precisam abrir um arquivo específico, os comandos a partir dos quais essas macros são construídas serão, eventualmente, convertidos em instruções de baixo nível do TeX (primitivas do TeX) que os motores TeX realmente executam. Se essas instruções incluírem a necessidade de abrir um arquivo, o motor TeX chamará o Kpathsea dizendo, na prática, “por favor, encontre este arquivo”; se essa busca do Kpathsea for bem-sucedida, o arquivo será aberto. No entanto, se o Kpathsea não conseguir localizar o arquivo, o motor TeX será avisado disso e interromperá a execução para emitir o famigerado erro ``! Não consigo encontrar o arquivo `...'`` A verdade é que o Kpathsea não consegue encontrá-lo. ### Notas sobre LuaTeX Estritamente falando, deveríamos fazer uma ressalva nesta seção, observando que o LuaTeX oferece um mecanismo para o usuário fornecer seu próprio código de busca de arquivos por meio do uso de *callbacks*. O LuaTeX permite que os usuários escrevam funções na linguagem de script Lua e as registrem no LuaTeX para que ele chame essa função definida pelo usuário em certos estágios durante a execução do LuaTeX — daí o termo *callbacks*. É uma técnica muito poderosa e o leitor interessado pode encontrar mais informações na Seção 9 de [Manual de Referência do LuaTeX](http://www.pragma-ade.com/general/manuals/luatex.pdf) (na data em que este texto foi escrito, esse link é para LuaTeX 1.09). ### O arquivo de configuração do Kpathsea: texmf.cnf Toda instalação TeX contém um arquivo de texto chamado `texmf.cnf` que é um arquivo de configuração usado pelo Kpathsea: ele contém inúmeras “variáveis de configuração” que definem os caminhos que o Kpathsea usará para procurar vários tipos de arquivo de que os motores TeX (ou BibTeX, MetaPost etc.) possam precisar. Como veremos abaixo, essas “variáveis de configuração” definem caminhos de busca construídos a partir dos chamados *elementos de caminho*: usando várias construções, variáveis e parâmetros para definir cada elemento de caminho como um “modelo” que o Kpathsea processa para gerar os diretórios físicos reais a serem pesquisados. Só para dar um exemplo concreto, aqui está uma dessas variáveis de configuração que define os caminhos de busca para fontes OpenType — por enquanto, não se preocupe com o significado da construção deste caminho: ``` OPENTYPEFONTS = .;$TEXMF/fonts/{opentype,truetype}//;$OSFONTDIR// ``` Tudo o que importa aqui é que o arquivo `texmf.cnf` (lido pelo Kpathsea) define uma variável de configuração chamada `OPENTYPEFONTS` que é usada para definir o(s) caminho(s) que o Kpathsea usará para procurar fontes OpenType. O lado direito do “=” não se parece com nenhum caminho que você vê em um dispositivo típico porque é construído usando várias variáveis e parâmetros para definir cada caminho como um “modelo” ou “planta” que o Kpathsea usará para gerar os diretórios reais a pesquisar. ### O conceito de “caminho” do Kpathsea Talvez o conceito central a ser entendido seja a noção de “caminho” do Kpathsea: a construção básica que o Kpathsea usa para descobrir onde um arquivo específico está localizado. Como vimos no `OPENTYPEFONTS` exemplo acima, a noção de caminho do Kpathsea parece muito diferente dos caminhos com os quais estamos acostumados a usar em nossos dispositivos desktop ou portáteis. Para citar a documentação do Kpathsea, [documentação](http://tug.org/texinfohtml/kpathsea.html#Searching-overview): > ... um *caminho de busca* é uma lista separada por dois-pontos de *elementos de caminho*, que são nomes de diretórios com algumas “comodidades extras”. —mas observe que um ponto e vírgula (`;`) também é usado para separar *elementos de caminho*. Mais adiante, indicaremos brevemente a natureza de algumas dessas “comodidades extras”. Em nosso `OPENTYPEFONTS` exemplo, há três elementos de caminho, cada um delimitado usando ponto e vírgula (`;`): ![Imagem mostrando os elementos de caminho contidos em uma definição de caminho do Kpathsea](/files/25127ce6a82c105dabf2895bb4e5a51cf5409c74) 1. `.` (significando o diretório atual) 2. `$TEXMF/fonts/{opentype,truetype}//` 3. `$OSFONTDIR//` Observe que uma barra dupla (`//`) em um elemento de caminho significa procurar subdiretórios (recursivamente). Um típico `texmf.cnf` arquivo conterá inúmeras “variáveis de configuração” para definir caminhos de busca para os tipos de arquivo que o Kpathsea pode pesquisar. ## Kpathsea: uma visão geral muito breve O Kpathsea é uma biblioteca sofisticada — com muitos detalhes finos e nuances — e até mesmo uma rápida olhada em sua [documentação](http://tug.org/texinfohtml/kpathsea.html) documentação mostra claramente que não podemos nos aprofundar em todos os detalhes. No entanto, podemos tentar fornecer uma visão geral do que ele faz — para ajudar a orientar seu pensamento e oferecer um ponto de partida para leituras adicionais. ### Objetivo principal do Kpathsea Como observado na documentação, o propósito fundamental do Kpathsea é “retornar um nome de arquivo a partir de uma lista de diretórios especificada pelo usuário” e que esses diretórios (caminhos de busca) são especificados usando “algumas comodidades extras”. ### Essas “comodidades extras” As “poucas comodidades extras” mencionadas acima incluem vários parâmetros e variáveis que o Kpathsea usa para construir seus caminhos de busca (ou “modelos de caminho”) para que possa definir caminhos de maneira mais geral. Quando um motor TeX está realmente em execução, o Kpathsea pode usar o valor atual desses parâmetros/variáveis para descobrir os caminhos reais, substituindo essas variáveis por seus valores reais (em tempo de execução). Você pode identificar facilmente essas variáveis (dentro dos elementos de caminho) porque elas começam com um `$` símbolo. Assim, dizemos que o Kpathsea *expande* um elemento de caminho, significando que ele transforma esses parâmetros e variáveis: convertendo um “modelo” de caminho no(s) nome(s) real(is) de um ou mais diretórios físicos nos quais procurar um arquivo. Isso oferece uma grande flexibilidade e significa que o Kpathsea pode construir uma lista de diretórios correspondente a um elemento de caminho individual — por exemplo, se lhe for dito para pesquisar subdiretórios. ### Nosso exemplo de OpenType revisitado Vamos reunir os vários tópicos e explorar `OPENTYPEFONTS` com um pouco mais de detalhe: ``` OPENTYPEFONTS = .;$TEXMF/fonts/{opentype,truetype}//;$OSFONTDIR// ``` Vamos considerar os dois elementos de caminho `$TEXMF/fonts/{opentype,truetype}//` e `$OSFONTDIR//`. Aqui, o Kpathsea percebe o uso de chaves `{...}` e trata `$TEXMF/fonts/{opentype,truetype}` como representando *dois* elementos de caminho: 1. `$TEXMF/fonts/opentype//` 2. `$TEXMF/fonts/truetype//` e que os *subdiretórios* de ambos esses elementos de caminho também devem ser pesquisados (indicado pelo `//`). **Nota**Consulte a documentação do Kpathsea sobre [expansão de subdiretórios](http://tug.org/texinfohtml/kpathsea.html#Subdirectory-expansion) para uma ressalva importante sobre a ordem em que os subdiretórios, em qualquer nível, são pesquisados (ela não é especificada). Faremos algumas observações sobre `$TEXMF` abaixo. #### $OSFONTDIR// `$OSFONTDIR` é uma variável cujo valor deve ser definido como uma variável de ambiente contendo o local onde as fontes são armazenadas: o valor exato dependerá, é claro, do sistema operacional usado para executar o TeX. Observe que, aqui, o `//` instrui o Kpathsea a pesquisar subdiretórios ao procurar fontes OpenType. A definição padrão de `OSFONTDIR` dentro `texmf.cnf` é: ``` OSFONTDIR = /please/set/osfontdir/in/the/environment ``` Portanto, é certamente algo que você precisa definir se quiser usá-lo — sua variável de ambiente substituirá essa definição “placeholder” contida em `texmf.cnf`. Se você definir a variável de ambiente `OSFONTDIR` então, em tempo de execução, onde quer que o Kpathsea veja `$OSFONTDIR` como parte de um elemento de caminho (em `texmf.cnf`) ele pode substituir a variável `$OSFONTDIR` pelo valor real armazenado na variável de ambiente `OSFONTDIR`. Lembre-se de que, ao usá-lo dentro de `texmf.cnf` elementos de caminho, especificamos a variável `$OSFONTDIR`—com um `$`—para informar ao Kpathsea que esta é uma variável cujo *valor* ele precisa usar. #### Breves notas sobre $TEXMF `TEXMF` é outra variável de configuração definida em `texmf.cnf`; por exemplo, na distribuição mestre do TeX Live você veria: ``` TEXMF = {$TEXMFAUXTREES$TEXMFCONFIG,$TEXMFVAR,$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFSYSCONFIG,!!$TEXMFSYSVAR,!!$TEXMFDIST} ``` Você não precisa se preocupar com os detalhes desta definição de `TEXMF`—não exploraremos todos os detalhes, mas simplesmente observaremos que a `$TEXMF` variável é usada dentro de elementos de caminho porque define uma série de pastas de nível superior (chamadas de “árvores texmf”) a partir das quais você pode começar a busca por arquivos. `TEXMF` é extremamente útil se você quiser, ou precisar, dividir uma instalação TeX entre vários diretórios (ou “árvores” de diretórios). Por exemplo, ter uma coleção principal ou mestre de pacotes TeX/LaTeX (por exemplo, TeX Live) e outra coleção de arquivos e pastas usada para armazenar pacotes LaTeX locais — ou, talvez, usada para armazenar arquivos de configuração locais ou versões personalizadas de pacotes padrão. Dividir a instalação TeX dessa maneira pode facilitar o gerenciamento da atualização da coleção principal/mestre (distribuição) de pacotes TeX/LaTeX, porque sua coleção local fica separada dos arquivos mestres que são atualizados quando você atualiza sua distribuição/instalação TeX Live. Para mais detalhes sobre como gerenciar instalações TeX mais complexas, o leitor interessado é encaminhado a estes dois artigos: * [Gerenciando múltiplas árvores TDS](http://tug.org/TUGboat/Articles/tb22-3/tb72downes.pdf) por Michael J Downes; * [Malabarismo com árvores texmf](http://www.ntg.nl/maps/27/17.pdf) por Siep Kroonenberg. #### Estrutura de Diretórios TeX Qualquer pessoa que já tenha gerenciado uma instalação TeX sabe que os sistemas TeX modernos, como o TeX Live, contêm muitas dezenas de milhares de arquivos, abrangendo uma enorme variedade de tipos de arquivo. A Estrutura de Diretórios TeX (TDS) foi projetada como um “modelo” de melhores práticas para organizar a vasta coleção de arquivos em uma instalação TeX funcional e é fortemente recomendada para uso com o Kpathsea. Para mais informações, o leitor é direcionado para a especificação TDS: [Uma Estrutura de Diretórios para Ficheiros TeX](https://www.tug.org/tds/tds.pdf). ## Tipos de arquivo do Kpathsea O conjunto de aplicações que usam Kpathsea precisa acessar uma ampla gama de tipos de arquivo, então o Kpathsea usa uma “variável de configuração” para identificar o(s) caminho(s) de cada tipo de arquivo (ou grupo de arquivos) que ele suporta. A documentação online tem uma lista completa (veja também nosso [quadro-resumo abaixo](#table-listing-kpathsea-config-variables)) mas aqui estão as “variáveis de configuração” para os tipos de arquivo mais comuns: | | | | ---------------------------- | ------------------------------------------------- | | **Variável de configuração** | **Exemplos de tipos de arquivo** | | TEXINPUTS | Arquivos-fonte TeX e arquivos de figuras/gráficos | | BIBINPUTS, BSTINPUTS | Arquivos-fonte de bibliografia BibTeX | | TTFONTS | Fontes de contorno TrueType | | OPENTYPEFONTS | Fontes de contorno OpenType | `TEXINPUTS` é uma variável de configuração especialmente importante porque especifica onde um motor TeX obtém seus arquivos-fonte de entrada. Observe que os arquivos de imagem são considerados arquivos de entrada e também podem ser pesquisados usando o caminho definido por `TEXINPUTS`. ### Algumas nuances do Kpathsea Como observado, o Kpathsea tem muitas nuances que não podemos explorar aqui em detalhes. No entanto, aqui estão recursos que alguns leitores podem querer explorar: * **banco de dados de nomes de arquivos:** Para minimizar buscas em disco, o Kpathsea pode fazer uso de um “ [arquivo de banco de dados de nomes de arquivos chamado ls-R](http://tug.org/texinfohtml/kpathsea.html#Filename-database) que mapeia arquivos para diretórios”. O TeX Live fornece um e também as ferramentas para atualizá-lo se novos arquivos forem adicionados. * **variáveis de ambiente**: Além de “variáveis de configuração” (como `OPENTYPEFONTS`) o Kpathsea também faz uso inteligente de [variáveis de ambiente](https://en.wikipedia.org/wiki/Environment_variable); por exemplo, o valor em tempo de execução das variáveis de ambiente pode ser usado para definir elementos de caminho no `texmf.cnf` arquivo (possivelmente para substituir variáveis com o mesmo nome definidas em `texmf.cnf`). * **nome do programa:** Um aspecto sutil, mas essencial, do comportamento do Kpathsea é que ele pode usar o nome do programa executável (por exemplo, o motor TeX) para construir estruturas de caminho de busca específicas do programa. Isso oferece considerável flexibilidade porque a busca de caminhos pode ser direcionada para arquivos de um motor TeX específico. Por exemplo, para LuaTeX/LuaLaTeX: ``` TEXINPUTS.lualatex = .;$TEXMF/tex/{lualatex,latex,luatex,generic,}// TEXINPUTS.luatex = .;$TEXMF/tex/{luatex,plain,generic,}// ``` * **localizando `texmf.cnf`**: Uma pergunta que você talvez esteja fazendo é como o Kpathsea sabe onde `texmf.cnf` está armazenado? A resposta é uma variável de ambiente chamada `TEXMFCNF`. Isso precisa ser definido (no dispositivo/plataforma que executa o TeX) para o caminho onde `texmf.cnf` está armazenado. #### Depurando problemas do Kpathsea É improvável que os usuários do Overleaf precisem dessas facilidades, mas as listamos por completude: * **kpsewhich**: Um programa independente (incluído no TeX Live) que pode ser usado para testar suas configurações: determinar o valor de variáveis e localizar arquivos. Leitores interessados são encaminhados para a [documentação online](http://tug.org/texinfohtml/kpathsea.html#Invoking-kpsewhich) para mais informações. * **variáveis de ambiente**: O Kpathsea oferece suporte a uma variável de ambiente chamada [`KPATHSEA_DEBUG`](http://www.tug.org/texinfohtml/kpathsea.html#Debugging) para ajudar a depurar seu comportamento. Você pode definir `KPATHSEA_DEBUG` com valores diferentes dependendo da quantidade de informação de depuração que você precisa. Definir `KPATHSEA_DEBUG=-1` gerará uma quantidade *substancial* de dados. ## E por fim: pastas, arquivos de figuras e latexmkrc Então, como isso se relaciona com o latexmkrc? Se você ler este artigo [Como usar latexmkrc com Overleaf: exemplos e técnicas](/latex/overleaf-learn-latex-pt/artigos-aprofundados/28-how-to-use-latexmkrc-with-overleaf.md) você pode ver que o código (Perl) no exemplo de latexmkrc define o valor de uma variável de ambiente `TEXINPUTS`: ``` $ENV{'TEXINPUTS'}='./tex//:' . $ENV{'TEXINPUTS'}; ``` Observe que o dois-pontos (:) usado aqui (`./tex//**:**`) é *extremamente* importante. Se você omitir esse dois-pontos, o TeX/LaTeX pode não conseguir encontrar arquivos vitais do sistema, como pacotes LaTeX! O que esse arquivo latexmkrc faz, na prática, é adicionar um caminho de pasta de nível superior (`./tex` no exemplo acima) à variável de ambiente definida pelo sistema, de modo que, quando o Kpathsea usa a variável `TEXINPUTS` $TEXINPUTS `ele passa a saber que a pasta` /tex// `deve ser pesquisada para encontrar arquivos de entrada. Se você olhar com atenção, verá que o caminho real usado é` deve ser pesquisada para encontrar arquivos de entrada. Se você olhar com atenção, verá que o caminho real usado é `./tex//:` o `//` instrui o Kpathsea a pesquisar a pasta tex recursivamente — isto é, olhar em quaisquer subpastas contidas na `pasta tex` . Como observado, também adicionamos o importante caractere dois-pontos. Podemos usar exatamente a mesma técnica para arquivos de figuras. ### Uma observação sobre BibTeX Como observado, o programa BibTeX também usa Kpathsea para procurar seus arquivos de entrada; em particular: * o `BSTINPUTS` variável de configuração (caminho de busca) é usada para procurar `.bst` arquivos; * e `BIBINPUTS` variável de configuração (caminho de busca) será usada para procurar `.bib` ficheiros. Se você adicionar novos `.bst` ou `.bib` arquivos ao seu projeto Overleaf, você pode usar a técnica abaixo para instruir o BibTeX onde encontrar esses arquivos — você precisa substituir `TEXINPUTS` com `BSTINPUTS` e/ou `BIBINPUTS`. ### TEXINPUTS e usando pastas aninhadas para arquivos gráficos Se o seu projeto tem muitos arquivos gráficos, pode ser conveniente criar um conjunto de pastas para armazená-los e gerenciá-los. Por exemplo, a captura de tela a seguir mostra uma seção de um projeto Overleaf que usa uma pasta de nível superior chamada **`graphics`**: ![Imagem mostrando pastas aninhadas em um projeto Overleaf](/files/b66e9bdce179c3c4d2e37ad98dcdef6fb5071bac) Há vários subdiretórios (aninhados) contendo gráficos para várias seções do nosso documento. Suponha que tenhamos a estrutura de pastas acima e queiramos usar o `graphicx` pacote (`\usepackage{graphicx}`) e que tentemos fazer isso assim: ```latex \documentclass{article} \usepackage{graphicx} \begin{document} \includegraphics{endlinechar}% a melhor prática é não usar a extensão do arquivo \end{document} ``` Não vai funcionar e você receberá um erro como este: ``` ! Erro do LaTeX: arquivo `endlinechar' não encontrado. l.4 \includegraphics{endlinechar} Não consegui localizar o arquivo com nenhuma destas extensões: .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 ``` Esse erro surge porque nosso arquivo gráfico está armazenado em um local que o TeX/LaTeX (e o Kpathsea) desconhecem e, portanto, não conseguem encontrar — o caminho para o arquivo gráfico é: ``` ./graphics/Introduction/Chapter1/Section1/Subsection3/endlinechar.png ``` **Nota**: É geralmente considerada uma boa prática ***evitar caracteres de espaço nos nomes das pastas***. Embora seja certamente possível ter espaços nos nomes de pastas, usando as técnicas discutidas abaixo, recomendamos cautela ao fazê-lo por razões de portabilidade do documento fora da plataforma Overleaf. Conforme explicado neste [artigo de ajuda do Overleaf](/latex/overleaf-learn-latex-pt/mais-topicos/27-inserting-images.md) você pode, é claro, usar pastas para armazenar seus gráficos, mas precisa dizer ao LaTeX onde eles estão armazenados. Aqui, veremos duas soluções: * Usando o comando \graphicspath; * Usando nosso conhecimento de Kpathsea e `TEXINPUTS`. ### Usando \graphicspath O `graphicx` o pacote fornece o `\graphicspath` comando que você pode usar para declarar caminhos onde seus gráficos estão localizados; então poderíamos fazer algo assim: ```latex \graphicspath{{./graphics/Introduction/Chapter1/Section1/Subsection3/}} ``` e agora o LaTeX encontrará quaisquer gráficos armazenados sob esse caminho. **Nota**: Se você *deve* tiver espaços nos nomes das pastas, então será necessário colocar os caminhos entre aspas duplas (`"..."`): ```latex \graphicspath{{"./graphics/Introduction/Chapter 1/Section 1/Subsection 3/"}} ``` **Nota**: Você pode declarar vários caminhos assim: ```latex \graphicspath{{path1}{path2}{path3}...{pathN}} ``` onde `...` significa caminhos adicionais entre chaves. **Nota**: Começamos o caminho com `./graphics` e não apenas `/graphics`. O ponto (.) informa ao sistema operacional que o caminho é relativo ao diretório de trabalho atual. O `\graphicspath` comando funciona bem, mas se você tiver muitas pastas pode ficar bastante tedioso adicionar cada caminho; além disso, caminhos definidos via `\graphicspath` não funcionariam mais se você renomeasse as pastas ou as reestruturasse. Existe uma maneira mais fácil? Sim, você pode usar um arquivo latexmkrc! #### \graphicspath e recursão (subdiretórios) Observe que há discussões/debates online sobre se alguns sistemas suportam/habilitam `\graphicspath` para pesquisar recursivamente subdiretórios se você adicionar `//` no final do caminho: veja, por exemplo, estas discussões no tex.stackexchange: * [Busca recursiva de \graphicspath no LaTeX](https://tex.stackexchange.com/questions/25443/latex-graphicspath-recursive-search); * [Graphicspath para MikTeX](https://tex.stackexchange.com/questions/3131/graphicspath-for-miktex). Para maior compatibilidade, você deve assumir que `\graphicspath` não oferece suporte à pesquisa recursiva de diretórios. ### Kpathsea e TEXINPUTS (arquivo latexmkrc para salvar o dia) **AVISO:** Observe que a técnica a seguir funciona bem no Overleaf e em instalações TeX locais devidamente configuradas; **mas** se você usar um arquivo latexmkrc, seu projeto pode tornar-se incompatível com outras instalações TeX, como aquelas usadas por editoras e sistemas online de submissão de artigos. Instalações TeX de terceiros podem ou não oferecer suporte ou permitir o uso de latexmkrc. Se você precisar exportar seu projeto Overleaf para uso em outro lugar, ou quiser submetê-lo a um periódico, você deve remover quaisquer caracteres de espaço dos nomes dos caminhos e, para melhorar a compatibilidade, adicionar um `\graphicspath` comando que define todos os caminhos: ```latex \graphicspath{{path1}{path2}{path3}...{pathN}} ``` onde `...` significa caminhos adicionais entre chaves. A técnica discutida abaixo (usando `TEXINPUTS`) foi testada com sucesso no Overleaf com os motores pdfTeX, XeTeX e LuaTeX (isto é, as opções de compilador pdfLaTeX, XeLaTeX e LuaLaTeX no menu do Overleaf): ![Imagem mostrando como escolher o compilador LaTeX no Overleaf](/files/9f6950f23334d86e1c23aaa9e03d9a3f85c9aa0e) Voltando ao nosso exemplo, queremos usar este código (com pastas profundamente aninhadas) e usaremos um arquivo latexmkrc para conseguir isso: ```latex \documentclass{article} \usepackage{graphicx} \begin{document} \includegraphics{endlinechar}% a melhor prática é não usar a extensão do arquivo \end{document} ``` Aqui está uma captura de tela mostrando o código acima funcionando sem problemas: o LaTeX encontrou nosso arquivo gráfico (`endlinechar.png`) embora ele esteja em uma estrutura de pastas profundamente aninhada (sem espaços nos nomes das pastas). ![Imagem mostrando um projeto com pastas aninhadas compilando no Overleaf](/files/e7791c55004c0fdfcf5cac6112b30da0e24c45a3) Então, como fizemos isso? Tudo o que você precisa fazer é: * criar um novo arquivo, sem extensão, e chamá-lo latexmkrc; * adicionar a seguinte linha a esse arquivo: ``` $ENV{'TEXINPUTS'}='./graphics//:'.$ENV{'TEXINPUTS'}; ``` O Kpathsea agora saberá das pastas contidas em `**graphics**` e, por causa de `//` irá também procurar nas subpastas. Note, novamente, que os dois pontos em `./graphics//:` na verdade é *extremamente* importante. Se você omitir esse dois-pontos, o TeX/LaTeX pode não conseguir encontrar arquivos vitais do sistema, como pacotes LaTeX! Usando o exemplo simples de projeto acima, agora pode compilá-lo e voilà! O LaTeX encontra o seu ficheiro gráfico — e pode renomear ou reorganizar as pastas em /graphics, e isso não impedirá o LaTeX de as encontrar. ## Tabela que lista as “variáveis de configuração” do Kpathsea A tabela seguinte é um resumo derivado de [dados listados na documentação do Kpathsea](http://tug.org/texinfohtml/kpathsea.html#Supported-file-formats). | | | | | --------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------ | | **Variável de configuração do Kpathsea** | **Descrição do tipo de ficheiro** | **Sufixo do ficheiro** | | AFMFONTS | métricas de fonte Adobe | .afm | | MFBASES, TEXMFINI | dump de memória do Metafont | .base | | BIBINPUTS, TEXBIB | fonte bibliográfica do BibTeX | .bib | | BLTXMLINPUTS | ficheiros bibliográficos BibLaTeXML para Biber | .bltxml | | BSTINPUTS | estilo BibTeX | .bst | | CLUAINPUTS | bibliotecas dinâmicas para Lua | .dll and .so | | CMAPFONTS | ficheiros de mapa de caracteres | .cmap | | TEXMFCNF | ficheiros de configuração em tempo de execução | .cnf | | CWEBINPUTS | ficheiros de entrada CWEB | .w, .web, .ch | | TEXCONFIG | ficheiros 'config.\*' do Dvips, como config.ps | | | ENCFONTS | vetores de codificação | .enc | | TEXFORMATS, TEXMFINI | dump de memória do TeX | .fmt | | FONTCIDMAPS | mapeamento CJK | .cid | | FONTFEATURES | principalmente para funcionalidades de fontes OpenType | .fea | | FONTS, GFFONTS, GLYPHFONTS, TEXFONTS | bitmap genérico de fonte | .gf | | TEXPICTS, TEXINPUTS | figuras PostScript encapsuladas | .eps, .epsi | | TEXINDEXSTYLE, INDEXSTYLE | ficheiros de estilo makeindex | .ist | | LIGFONTS | ficheiros de definição de ligaduras | .lig | | TEXMFDBS | bases de dados de nomes de ficheiro | | | TEXFONTMAPS | mapas de fontes | .map | | MPMEMS, TEXMFINI | dump de memória do MetaPost | .mem | | MPSUPPORT | ficheiros de suporte do MetaPost, usados pelo DMP | | | MFINPUTS | fonte do Metafont | .mf | | MFPOOL, TEXMFINI | cadeias de programa do Metafont | .pool | | MFTINPUTS | ficheiro de estilo MFT | .mft | | MISCFONTS | ficheiros relacionados com fontes que não se enquadram nas outras categorias | | | MLBIBINPUTS, BIBINPUTS, TEXBIB | fonte bibliográfica do MlBibTeX | .mlbib, .mlbib | | MLBSTINPUTS, BSTINPUTS | estilo MlBibTeX | .mlbst, .bst | | MPINPUTS | fonte do MetaPost | .mp | | MPPOOL, TEXMFINI | cadeias de programa do MetaPost | .pool | | OCPINPUTS | ficheiros de processo compilados do Omega | .ocp | | OFMFONTS, TEXFONTS | métricas de fonte Omega | .ofm, .tfm | | OPENTYPEFONTS | fontes OpenType | | | OPLFONTS, TEXFONTS | listas de propriedades Omega | .opl | | OTPINPUTS | ficheiros de processo de tradução Omega | .otp | | OVFFONTS, TEXFONTS | fontes virtuais Omega | .ovf | | OVPFONTS, TEXFONTS | listas de propriedades virtuais Omega | .ovp | | PDFTEXCONFIG | ficheiros de configuração específicos do PDFTeX | | | PROGRAMFONTS, PKFONTS, TEXPKS, GLYPHFONTS, TEXFONTS | fontes bitmap empacotadas | .pk | | TEXPSHEADERS, PSHEADERS | PostScript descarregável | .pro | | RISINPUTS | ficheiros bibliográficos RIS, principalmente para Bibe | .ris | | SFDFONTS | ficheiros de definição de subfontes | .sfd | | TEXINPUTS | fonte TeX | .tex | | TEXDOCS | ficheiros de documentação do sistema TeX | | | TEXSOURCES | ficheiros de origem para o sistema TeX | | | TEXMFSCRIPTS | executáveis independentes da arquitetura distribuídos nas árvores texmf | | | TEXPOOL, TEXMFINI | cadeias de programa do TeX | .pool | | TFMFONTS, TEXFONTS | métricas de fonte TeX | .tfm | | TRFONTS | fontes Troff | | | TTFONTS | Fontes de contorno TrueType | .ttf, ,TTF, .ttc, .TTC, .dfont | | T1FONTS, T1INPUTS, TEXPSHEADERS, DVIPSHEADERS | fontes de contorno PostScript Type 1 | .pfa, .pfb | | T42FONTS | fontes de contorno PostScript Type 42 | | | VFFONTS, TEXFONTS | tipos de letra virtuais | .vf | | WEBINPUTS | ficheiros de entrada WEB | .web, .ch | | WEB2C | ficheiros específicos da implementação 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/overleaf-learn-latex-pt/artigos-aprofundados/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.