> 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/ru/podrobnye-stati/06-an-introduction-to-kpathsea-and-how-tex-engines-search-for-files.md). # Введение в Kpathsea и то, как движки TeX ищут файлы ## Введение Эта статья знакомит с тем, как движки TeX находят файлы, необходимые для набора вашего документа — с использованием LaTeX или любого другого макропакета. Хотя Overleaf избавляет пользователей от трудностей управления установкой TeX ([TeX Live](https://www.tug.org/texlive/)), основы того, как движки TeX ищут файлы, будут полезны/интересны, если вы хотите создать структуру папок, чтобы упростить управление вашим проектом Overleaf. Почему это может быть так? Если вы храните некоторые файлы вашего проекта Overleaf внутри папок, LaTeX может не найти эти файлы, потому что по умолчанию движок TeX (компилятор) может не *знать* что ему нужно искать в этих папках — и поэтому не найдёт содержащиеся в них файлы. Чтобы избежать этого, вы можете создать и добавить в свой проект файл конфигурации под названием [файл latexmkrc](https://mg.readthedocs.io/latexmk.html#configuration-files) который можно использовать, чтобы сообщить движку TeX, что ваши папки существуют и что ему следует искать в них. Если вы хотите сразу перейти к примеру с файлом latexmkrc, вы можете прочитать эту справочную статью: [Как использовать latexmkrc в Overleaf: примеры и приёмы](/latex/ru/podrobnye-stati/28-how-to-use-latexmkrc-with-overleaf.md). Может быть не сразу очевидно, как и почему этот файл latexmkrc на самом деле работает. Если вы хотите понять, почему, и, возможно, лучше разобраться, чтобы использовать дополнительные возможности настройки вашего проекта, тогда читайте дальше... В конце этой статьи мы разберём [практический пример](#kpathsea-and-texinputs-latexmkrc-file-to-the-rescue)—используя наши знания о том, как TeX ищет файлы, — чтобы создать файл latexmkrc для управления вложенными папками, содержащими ваши графические файлы. ## TeX и независимость от платформы Когда Кнут создавал TeX, независимость от платформы была центральным принципом, определявшим его проектирование и реализацию, и эта философия отражается во всей внутренней работе TeX (например, в использовании целочисленной арифметики, «самодельной» обработки строк, управления памятью и т. д.). Даже сегодня независимость от платформы современных движков на базе TeX всё ещё вызывает вопросы и споры на публичных форумах; например, см. это обсуждение на tex.stackexchange: [Зависимы ли XeTeX и LuaTeX от платформы?](https://tex.stackexchange.com/questions/94297/are-xetex-and-luatex-platform-dependent) в котором содержатся комментарии и наблюдения ряда известных экспертов по TeX. Однако пока оставим в стороне тонкие детали и отметим, что движки TeX по-прежнему должны быть очень переносимыми — способными работать на нескольких операционных системах и выдавать «идентичные» результаты. Важный аспект переносимости — поиск файлов независимо от платформы. ## Движки TeX не ищут файлы… правда!? Нет, движки TeX не *непосредственно* ищут файлы *сами по себе*. При обработке `.tex` файла движок TeX может определить необходимость открыть определённый файл, но он *передаёт* задачу его поиска другому программному обеспечению под названием [*Kpathsea*](https://tug.org/kpathsea/): внешняя программная библиотека, не входящая в *ядро* исходного кода движков TeX. По сути, Kpathsea предоставляет API ([интерфейсом программирования приложений](https://en.wikipedia.org/wiki/Application_programming_interface)), к которому движки TeX (а также BibTeX, MetaPost и другие приложения) могут обращаться всякий раз, когда им нужно открыть определённый файл: Kpathsea и выполняет фактическую работу по поиску этого файла. Когда Кнут писал оригинальный движок TeX, от которого в конечном счёте произошли все остальные движки TeX, проблема поиска/открытия файлов была серьёзной задачей, отчасти из-за крайне разнородной технологической среды того времени. Фактически в исходном коде TeX Кнут называет ввод/вывод файлов «проклятием переносимости» (см. страницу 12, раздел 25 [TeX: The Program](https://www.amazon.co.uk/Computers-Typesetting-TeX-Program-TEX/dp/0201134373)). Сообщество TeX осознало необходимость гармонизировать (стандартизировать) поиск файлов для TeX —*и программного обеспечения, связанного с TeX*— и решило предоставить TeX инструменты для этого. Чтобы решить очень сложную проблему платформонезависимого метода поиска файлов, Карл Берри, ведущий участник сообщества TeX, написал программное обеспечение для решения *проблемы*поиска путей: решение, которое он назвал [**Kpathsea**](http://tug.org/texinfohtml/kpathsea.html)— которое произошло от **K**Карла **Path** **Sea**рчинг (см. это [интервью с Карлом Берри](http://www.tug.org/interviews/berry.html)). Можно отметить, что это называется K**проблемы**sea, а не K**файла**sea, потому что, как [документацию](http://tug.org/texinfohtml/kpathsea.html) отмечает документация, это библиотека \*path-\*поиска. Важно понимать, что Kpathsea используется не только движками TeX; различные программы, связанные с TeX, включая BibTeX и MetaPost, также используют Kpathsea для поиска входных файлов. В общих чертах, всякий раз, когда макросам TeX/LaTeX нужно открыть определённый файл, команды, из которых эти макросы составлены, в конечном счёте преобразуются в низкоуровневые инструкции TeX (примитивы TeX), которые движки TeX и выполняют. Если эти инструкции содержат необходимость открыть файл, движок TeX обратится к Kpathsea, по сути говоря: «пожалуйста, найди этот файл»; если поиск Kpathsea успешен, файл открывается. Однако если Kpathsea не может найти файл, движок TeX будет об этом уведомлён и остановит выполнение, чтобы выдать печально известную ошибку ``! Я не могу найти файл `...'`` На самом деле Kpathsea не может его найти. ### Примечания по LuaTeX Строго говоря, в этом разделе следует сделать оговорку, отметив, что LuaTeX действительно предоставляет механизм, позволяющий пользователю задавать собственный код поиска файлов с помощью *коллбэков*. LuaTeX позволяет пользователям писать функции на скриптовом языке Lua и регистрировать их в LuaTeX, чтобы он вызывал эту пользовательскую функцию на определённых этапах выполнения LuaTeX — отсюда термин *коллбэков*. Это очень мощный приём, и заинтересованный читатель может найти больше информации в разделе 9 [Справочном руководстве LuaTeX](http://www.pragma-ade.com/general/manuals/luatex.pdf) (на момент написания эта ссылка ведёт на LuaTeX 1.09). ### Файл конфигурации Kpathsea: texmf.cnf Каждая установка TeX содержит текстовый файл под названием `texmf.cnf` который является конфигурационным файлом, используемым Kpathsea: он содержит многочисленные «конфигурационные переменные», определяющие пути, которые Kpathsea будет использовать для поиска различных типов файлов, которые могут понадобиться движкам TeX (или BibTeX, MetaPost и т. д.). Как мы увидим ниже, эти «конфигурационные переменные» определяют поисковые пути, построенные из так называемых *элементов пути*: с использованием различных конструкций, переменных и параметров, чтобы определить каждый элемент пути как «шаблон», который Kpathsea обрабатывает для создания фактических, физических каталогов для поиска. Просто чтобы привести конкретный пример, вот одна такая конфигурационная переменная, которая определяет поисковые пути для шрифтов OpenType — пока не беспокойтесь о том, что означает построение этого пути: ``` OPENTYPEFONTS = .;$TEXMF/fonts/{opentype,truetype}//;$OSFONTDIR// ``` Всё, что важно здесь, — это то, что файл `texmf.cnf` (читаемый Kpathsea) определяет конфигурационную переменную под названием `OPENTYPEFONTS` которая используется для определения пути(ей), которые Kpathsea будет использовать для поиска шрифтов OpenType. Правая часть знака «=» не похожа ни на один путь, который вы видите на обычном устройстве, потому что она построена с использованием различных переменных и параметров, чтобы определить каждый путь как «шаблон» или «чертёж», который Kpathsea будет использовать для создания реальных каталогов для поиска. ### Понятие «пути» в Kpathsea Возможно, ключевая концепция, которую нужно понять, — это представление Kpathsea о «пути»: базовая конструкция, которую Kpathsea использует, чтобы определить, где находится определённый файл. Как мы видели в `OPENTYPEFONTS` приведённом выше примере, представление Kpathsea о пути выглядит совсем не так, как пути, к которым мы привыкли на настольных или портативных устройствах. Если цитировать Kpathsea [документацию](http://tug.org/texinfohtml/kpathsea.html#Searching-overview): > ... это *поисковый путь* — это список, разделённый двоеточиями, из *элементов пути*, которые представляют собой имена каталогов с несколькими «дополнительными наворотами». —но обратите внимание, что точка с запятой (`;`) также используется для разделения *элементов пути*. Позже мы вкратце укажем, что представляют собой некоторые из этих «дополнительных наворотов». В нашем `OPENTYPEFONTS` примере есть три элемента пути, каждый из которых отделён точкой с запятой (`;`): ![Изображение, показывающее элементы пути, содержащиеся в определении пути Kpathsea](/files/ceb589b207f63f479879caa7dc391072bbe8a2d4) 1. `.` (то есть текущий каталог) 2. `$TEXMF/fonts/{opentype,truetype}//` 3. `$OSFONTDIR//` Обратите внимание, что двойной слэш (`//`) в элементе пути означает поиск подкаталогов (рекурсивно). Типичный `texmf.cnf` файл будет содержать многочисленные «конфигурационные переменные» для определения поисковых путей для типов файлов, которые может искать Kpathsea. ## Kpathsea: очень краткий обзор Kpathsea — это сложная библиотека с множеством тонких деталей и нюансов, и даже беглый взгляд на её [документацию](http://tug.org/texinfohtml/kpathsea.html) ясно показывает, что мы не можем углубиться во все детали. Однако мы можем попытаться дать обзор того, что она делает, — чтобы помочь сориентироваться и дать отправную точку для дальнейшего чтения. ### Основная цель Kpathsea Как отмечается в документации, основная цель Kpathsea — «возвращать имя файла из списка каталогов, заданных пользователем», а эти каталоги (поисковые пути) задаются с использованием «нескольких дополнительных наворотов». ### Эти «дополнительные навороты» Упомянутые выше «несколько дополнительных наворотов» включают различные параметры и переменные, которые Kpathsea использует для построения своих поисковых путей (или «шаблонов пути»), чтобы он мог определять пути более общим образом. Когда движок TeX фактически запущен (выполняется), Kpathea может использовать текущее значение этих параметров/переменных, чтобы определить реальные пути, заменяя эти переменные их фактическими значениями (во время выполнения). Эти переменные (внутри элементов пути) легко распознать, потому что они начинаются со `$` знака. Таким образом, мы говорим, что Kpathsea *разворачивает* элемент пути, то есть преобразует эти параметры и переменные: превращая «шаблон» пути в фактическое имя (имена) одного или нескольких физических каталогов, в которых нужно искать файл. Это даёт большую гибкость и означает, что Kpathsea может построить список каталогов, соответствующих отдельному элементу пути, — например, если ему указано искать подкаталоги. ### Снова обратимся к нашему примеру с OpenType Мы соберём все нити воедино и рассмотрим `OPENTYPEFONTS` чуть подробнее: ``` OPENTYPEFONTS = .;$TEXMF/fonts/{opentype,truetype}//;$OSFONTDIR// ``` Рассмотрим два элемента пути `$TEXMF/fonts/{opentype,truetype}//` и `$OSFONTDIR//`. Здесь Kpathsea замечает использование фигурных скобок `{...}` и рассматривает `$TEXMF/fonts/{opentype,truetype}` как представляющие *два* элемента пути: 1. `$TEXMF/fonts/opentype//` 2. `$TEXMF/fonts/truetype//` и что *подкаталоги* обоих этих элементов пути тоже должны быть просмотрены (об этом указывает завершающий `//`). **Примечание**: См. документацию Kpathsea по [разворачиванию подкаталогов](http://tug.org/texinfohtml/kpathsea.html#Subdirectory-expansion) относительно важной оговорки о порядке, в котором подкаталоги любого уровня просматриваются (он не определён). Мы сделаем несколько замечаний о `$TEXMF` ниже. #### $OSFONTDIR// `$OSFONTDIR` — это переменная, значение которой должно быть определено как переменная окружения, содержащая расположение, где хранятся шрифты: точное значение, разумеется, зависит от операционной системы, на которой запускается TeX. Обратите внимание, что здесь завершающий `//` указывает Kpathsea искать подкаталоги при поиске шрифтов OpenType. Значение по умолчанию для `OSFONTDIR` внутри `texmf.cnf` таков: ``` OSFONTDIR = /please/set/osfontdir/in/the/environment ``` Так что это, безусловно, то, что вам нужно задать, если вы хотите его использовать — ваша переменная окружения переопределит это «заглушечное» определение, содержащееся в `texmf.cnf`. Если вы действительно зададите переменную окружения `OSFONTDIR` тогда во время выполнения везде, где Kpathsea видит `$OSFONTDIR` как часть элемента пути (в `texmf.cnf`) он может заменить переменную `$OSFONTDIR` фактическим значением, хранящимся в переменной окружения `OSFONTDIR`. Помните, что при использовании её внутри `texmf.cnf` элементов пути мы указываем переменную `$OSFONTDIR`—с ведущим `$`—чтобы сообщить Kpathsea, что это переменная, чьё *значения* значение ему нужно использовать. #### Краткие заметки о $TEXMF `TEXMF` — это ещё одна конфигурационная переменная, определённая в `texmf.cnf`; например, в основной дистрибуции TeX Live вы увидите: ``` TEXMF = {$TEXMFAUXTREES$TEXMFCONFIG,$TEXMFVAR,$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFSYSCONFIG,!!$TEXMFSYSVAR,!!$TEXMFDIST} ``` Вам не нужно вникать в детали этого определения `TEXMF`—мы не будем рассматривать все детали, а просто отметим, что `$TEXMF` переменная используется внутри элементов пути, потому что она определяет набор папок верхнего уровня (называемых «деревьями texmf»), с которых можно начинать поиск файлов. `TEXMF` чрезвычайно полезно, если вы хотите или вам нужно разделить установку TeX по нескольким каталогам (или «деревьям» каталогов). Например, иметь основную или мастер-коллекцию пакетов TeX/LaTeX (например, TeX Live) и ещё одну коллекцию файлов и папок, используемых для хранения локальных пакетов LaTeX — или, возможно, для хранения локальных конфигурационных файлов либо изменённых версий стандартных пакетов. Разделение установки TeX таким образом может упростить управление обновлением основной/мастер-коллекции (дистрибутива) пакетов TeX/LaTeX, потому что ваша локальная коллекция отделена от мастер-файлов, которые обновляются при обновлении вашего дистрибутива/установки TeX Live. Для получения дополнительных сведений об управлении более сложными установками TeX заинтересованному читателю следует обратиться к этим двум статьям: * [Управление несколькими деревьями TDS](http://tug.org/TUGboat/Articles/tb22-3/tb72downes.pdf) Майкла Дж. Даунса; * [Жонглирование деревьями texmf](http://www.ntg.nl/maps/27/17.pdf) Сипа Круненберга. #### Структура каталогов TeX Любой, кто управлял установкой TeX, знает, что современные системы TeX, такие как TeX Live, содержат многие десятки тысяч файлов, охватывающих огромный диапазон типов файлов. TeX Directory Structure (TDS) была разработана как «чертёж» лучших практик для организации огромной коллекции файлов в рабочей установке TeX и настоятельно рекомендуется к использованию с Kpathsea. Для получения дополнительной информации читателю предлагается спецификация TDS: [Структура каталогов для файлов TeX](https://www.tug.org/tds/tds.pdf). ## Типы файлов Kpathsea Набор приложений, использующих Kpathsea, должен обращаться к широкому спектру типов файлов, поэтому Kpathsea использует «конфигурационную переменную» для определения пути(ей) для каждого типа файла (или группы файлов), который она поддерживает. В онлайн-документации есть полный список (см. также нашу [сводную таблицу ниже](#table-listing-kpathsea-config-variables)), но вот «конфигурационные переменные» для более распространённых типов файлов: | | | | ------------------------------- | ------------------------------------------- | | **Конфигурационная переменная** | **Примеры типов файлов** | | TEXINPUTS | Исходные файлы TeX и файлы рисунков/графики | | BIBINPUTS, BSTINPUTS | Исходные файлы библиографии BibTeX | | TTFONTS | Контурные шрифты TrueType | | OPENTYPEFONTS | Контурные шрифты OpenType | `TEXINPUTS` —это особенно важная конфигурационная переменная, потому что она указывает, откуда движок TeX получает свои входные исходные файлы. Обратите внимание, что файлы изображений считаются входными файлами, и их также можно искать с помощью пути, определённого `TEXINPUTS`. ### Некоторые нюансы Kpathsea Как уже отмечалось, у Kpathsea есть множество нюансов, которые мы не можем подробно рассмотреть здесь. Однако вот функции, которые некоторым читателям, возможно, захочется изучить: * **база данных имён файлов:** Чтобы минимизировать обращения к диску, Kpathsea может использовать «внешне созданную [базу данных имён файлов под названием ls-R](http://tug.org/texinfohtml/kpathsea.html#Filename-database) которая сопоставляет файлы каталогам». TeX Live предоставляет такую базу и инструменты для её обновления, если добавляются новые файлы. * **окружения**: Помимо «конфигурационных переменных» (таких как `OPENTYPEFONTS`) Kpathsea также умело использует [окружения](https://en.wikipedia.org/wiki/Environment_variable); например, текущее значение переменных окружения может использоваться для определения элементов пути в `texmf.cnf` файле (возможно, чтобы переопределить переменные с тем же именем, определённые в `texmf.cnf`). * **имя программы:** Тонкий, но важный аспект поведения Kpathsea заключается в том, что она может использовать имя исполняемой программы (например, движка TeX) для построения специфичных для программы поисковых конструкций пути. Это даёт значительную гибкость, поскольку поиск путей можно направить к файлам для конкретного движка TeX. Например, для LuaTeX/LuaLaTeX: ``` TEXINPUTS.lualatex = .;$TEXMF/tex/{lualatex,latex,luatex,generic,}// TEXINPUTS.luatex = .;$TEXMF/tex/{luatex,plain,generic,}// ``` * **поиск `texmf.cnf`**: Возможно, вы спрашиваете себя: как Kpathsea узнаёт, где `texmf.cnf` хранится? Ответ — переменная окружения под названием `TEXMFCNF`. Её нужно задать (на устройстве/платформе, где запускается TeX) как путь, по которому `texmf.cnf` она хранится. #### Отладка проблем Kpathsea Пользователям Overleaf вряд ли понадобятся эти возможности, но мы перечисляем их для полноты картины: * **kpsewhich**: Отдельная программа (входит в TeX Live), которую можно использовать для проверки ваших настроек: определения значений переменных и поиска файлов. Заинтересованным читателям предлагается обратиться к [онлайн-документации](http://tug.org/texinfohtml/kpathsea.html#Invoking-kpsewhich) для получения дополнительной информации. * **окружения**: Kpathsea поддерживает переменную окружения под названием [`KPATHSEA_DEBUG`](http://www.tug.org/texinfohtml/kpathsea.html#Debugging) для помощи в отладке её поведения. Вы можете установить `KPATHSEA_DEBUG` в разные значения в зависимости от того, сколько отладочной информации вам нужно. Установка `KPATHSEA_DEBUG=-1` сгенерирует *значительный* объём данных. ## И наконец: папки, графические файлы и latexmkrc Итак, как всё вышеперечисленное связано с latexmkrc? Если вы прочитаете эту статью [Как использовать latexmkrc в Overleaf: примеры и приёмы](/latex/ru/podrobnye-stati/28-how-to-use-latexmkrc-with-overleaf.md) вы увидите, что (Perl-)код в примере latexmkrc задаёт значение переменной окружения `TEXINPUTS`: ``` $ENV{'TEXINPUTS'}='./tex//:' . $ENV{'TEXINPUTS'}; ``` Обратите внимание, что двоеточие (:) здесь (`./tex//**:**`) представляет собой *чрезвычайно* важно. Если вы опустите это двоеточие, TeX/LaTeX может не суметь найти важные системные файлы, например пакеты LaTeX! По сути, этот файл latexmkrc добавляет путь к папке верхнего уровня (`./tex` в приведённом выше примере) к определённой системой `TEXINPUTS` переменной окружения, чтобы когда Kpathsea использует переменную `$TEXINPUTS` он будет знать, что папка `/tex//` должна быть просмотрена для поиска входных файлов. Если присмотреться, вы увидите, что фактически используется путь `./tex//:` окружения `//` указывает Kpathsea искать папку tex рекурсивно — то есть просматривать любые подпапки, содержащиеся в `tex` папке. Как уже отмечалось, мы также добавили важный символ двоеточия. Точно такой же приём можно использовать для файлов рисунков. ### Небольшое замечание о BibTeX Как уже отмечалось, программа BibTeX также использует Kpathsea для поиска своих входных файлов; в частности: * окружения `BSTINPUTS` конфигурационная переменная (поисковый путь) используется для поиска `.bst` файлов; * и `BIBINPUTS` конфигурационная переменная (поисковый путь) будет использоваться для поиска `.bib` файлов. Если вы добавите новые `.bst` или `.bib` файлы в ваш проект Overleaf, вы можете использовать описанный ниже приём, чтобы указать BibTeX, где найти эти файлы — вам нужно заменить `TEXINPUTS` с `BSTINPUTS` и/или `BIBINPUTS`. ### TEXINPUTS и использование вложенных папок для графических файлов Если в вашем проекте много графических файлов, может быть удобно создать набор папок для их хранения и управления ими. Например, следующий снимок экрана показывает раздел проекта Overleaf, который использует папку верхнего уровня под названием **`graphics`**: ![Изображение, показывающее вложенные папки в проекте Overleaf](/files/f20ad899c241b0c8a050cbcec6f38b6c1bf31eee) Существует множество (вложенных) подпапок, содержащих графику для различных разделов нашего документа. Предположим, у нас есть приведённая выше структура папок и мы хотим использовать `graphicx` (`\usepackage{graphicx}`) и попробуем сделать это так: ```latex \documentclass{article} \usepackage{graphicx} \begin{document} \includegraphics{endlinechar}% по лучшей практике не следует использовать расширение файла \end{document} ``` Это не сработает, и вы получите ошибку вроде этой: ``` ! Ошибка LaTeX: файл `endlinechar' не найден. l.4 \includegraphics{endlinechar} Не удалось найти файл ни с одним из этих расширений: .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 ``` Эта ошибка возникает потому, что наш графический файл хранится в месте, о котором TeX/LaTeX (и Kpathsea) не знают, и поэтому не могут его найти — путь к графическому файлу: ``` ./graphics/Introduction/Chapter1/Section1/Subsection3/endlinechar.png ``` **Примечание**: Обычно считается хорошей практикой ***избегать пробелов в именах папок***. Хотя, конечно, пробелы в именах папок возможны, с использованием описанных ниже приёмов, мы бы предостерегли от этого из соображений переносимости документа за пределами платформы Overleaf. Как объясняется в этой [справочной статье Overleaf](/latex/ru/drugie-temy/27-inserting-images.md) вы, конечно, можете использовать папки для хранения графики, но вам нужно сообщить LaTeX, где они хранятся. Здесь мы рассмотрим два решения: * Использование команды \graphicspath; * Используя наши знания о Kpathsea и `TEXINPUTS`. ### Использование \graphicspath Это `graphicx` пакет предоставляет `\graphicspath` команду, которую можно использовать для объявления путей, где расположена ваша графика; так что мы могли бы сделать что-то вроде этого: ```latex \graphicspath{{./graphics/Introduction/Chapter1/Section1/Subsection3/}} ``` и теперь LaTeX найдёт любую графику, хранящуюся по этому пути. **Примечание**: Если у вас *должны* есть пробелы в именах папок, вам нужно будет заключить пути в двойные кавычки (`"..."`): ```latex \graphicspath{{"./graphics/Introduction/Chapter 1/Section 1/Subsection 3/"}} ``` **Примечание**: Вы можете объявить несколько путей вот так: ```latex \graphicspath{{path1}{path2}{path3}...{pathN}} ``` где `...` означает дополнительные пути, заключённые в фигурные скобки. **Примечание**: Мы начинаем путь с `./graphics` а не просто с `/graphics`. Точка (.) сообщает операционной системе, что путь относителен к текущему рабочему каталогу. Это `\graphicspath` команда работает хорошо, но если у вас много папок, добавление каждого пути может стать довольно утомительным; кроме того, пути, определённые через `\graphicspath` больше не будут работать, если вы переименуете папки или измените их структуру. Есть ли более простой способ? Да, вы можете использовать файл latexmkrc! #### \graphicspath и рекурсия (подкаталоги) Обратите внимание, что в сети есть обсуждения/споры о том, поддерживают ли некоторые системы/включают ли `\graphicspath` рекурсивный поиск подкаталогов, если вы добавите `//` в конце пути: см., например, эти обсуждения на tex.stackexchange: * [Рекурсивный поиск \graphicspath в LaTeX](https://tex.stackexchange.com/questions/25443/latex-graphicspath-recursive-search); * [Graphicspath для MikTeX](https://tex.stackexchange.com/questions/3131/graphicspath-for-miktex). Для наибольшей совместимости следует считать, что `\graphicspath` не поддерживает рекурсивный поиск по каталогам. ### Kpathsea и TEXINPUTS (файл latexmkrc приходит на помощь) **ОГОВОРКА:** Обратите внимание, что следующий приём хорошо работает в Overleaf и в должным образом настроенных локальных установках TeX; **но** если вы используете файл latexmkrc, ваш проект может стать несовместимым с другими установками TeX, такими как те, что используются издателями и системами онлайн-подачи журналов. Сторонние установки TeX могут поддерживать или не поддерживать использование latexmkrc. Если вам нужно экспортировать ваш проект Overleaf для использования где-то ещё или вы хотите отправить его в журнал, следует убрать все пробелы из имён путей и, для лучшей совместимости, добавить `\graphicspath` команду, которая определяет все пути: ```latex \graphicspath{{path1}{path2}{path3}...{pathN}} ``` где `...` означает дополнительные пути, заключённые в фигурные скобки. Описанный ниже приём (с использованием `TEXINPUTS`) был успешно протестирован в Overleaf на движках pdfTeX, XeTeX и LuaTeX (то есть с параметрами компилятора pdfLaTeX, XeLaTeX и LuaLaTeX в меню Overleaf): ![Изображение, показывающее, как выбрать компилятор LaTeX в Overleaf](/files/62d35ccf1527b8c4957bb6835be57c4f7364c7d8) Возвращаясь к нашему примеру, мы хотим использовать этот код (с глубоко вложенными папками), и для этого мы воспользуемся файлом latexmkrc: ```latex \documentclass{article} \usepackage{graphicx} \begin{document} \includegraphics{endlinechar}% по лучшей практике не следует использовать расширение файла \end{document} ``` Вот снимок экрана, показывающий, что приведённый выше код работает без проблем: LaTeX нашёл наш графический файл (`endlinechar.png`), хотя он находится в глубоко вложенной структуре папок (без пробелов в именах папок). ![Изображение, показывающее проект с вложенными папками, компилируемый в Overleaf](/files/50730e69e0c76ee35f0c641b5a8c06d32a6537e4) Итак, как мы это сделали? Всё, что нужно сделать: * создать новый файл без расширения и назвать его latexmkrc; * добавить в этот файл следующую строку: ``` $ENV{'TEXINPUTS'}='./graphics//:'.$ENV{'TEXINPUTS'}; ``` Теперь Kpathsea будет знать о папках, находящихся внутри `**graphics**` и из-за `//` он также будет искать в подкаталогах. Заметьте снова, что двоеточие в `./graphics//:` на самом деле *чрезвычайно* важно. Если вы опустите это двоеточие, TeX/LaTeX может не суметь найти важные системные файлы, например пакеты LaTeX! Используя приведённый выше простой пример проекта, вы теперь можете его скомпилировать, и вуаля! LaTeX находит ваш графический файл — и вы можете переименовывать или переорганизовывать папки в /graphics, и это не помешает LaTeX находить их. ## Таблица со списком «конфигурационных переменных» Kpathsea Следующая таблица представляет собой сводку, составленную на основе [данных, перечисленных в документации Kpathsea](http://tug.org/texinfohtml/kpathsea.html#Supported-file-formats). | | | | | --------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------ | | **Конфигурационная переменная Kpathsea** | **Описание типа файла** | **Суффикс файла** | | AFMFONTS | метрики шрифтов Adobe | .afm | | MFBASES, TEXMFINI | дамп памяти Metafont | .base | | BIBINPUTS, TEXBIB | исходный файл библиографии BibTeX | .bib | | BLTXMLINPUTS | файлы библиографии BibLaTeXML для Biber | .bltxml | | BSTINPUTS | стиль BibTeX | .bst | | CLUAINPUTS | динамические библиотеки для Lua | .dll и .so | | CMAPFONTS | файлы карт символов | .cmap | | TEXMFCNF | файлы конфигурации времени выполнения | .cnf | | CWEBINPUTS | входные файлы CWEB | .w, .web, .ch | | TEXCONFIG | Файлы 'config.\*' для Dvips, например config.ps | | | ENCFONTS | векторы кодировок | .enc | | TEXFORMATS, TEXMFINI | дамп памяти TeX | .fmt | | FONTCIDMAPS | сопоставление CJK | .cid | | FONTFEATURES | в первую очередь для функций шрифтов OpenType | .fea | | FONTS, GFFONTS, GLYPHFONTS, TEXFONTS | универсальный растровый шрифт | .gf | | TEXPICTS, TEXINPUTS | фигуры Encapsulated PostScript | .eps, .epsi | | TEXINDEXSTYLE, INDEXSTYLE | стилевые файлы makeindex | .ist | | LIGFONTS | файлы определения лигатур | .lig | | TEXMFDBS | Базы данных имён файлов | | | TEXFONTMAPS | Карты шрифтов | .map | | MPMEMS, TEXMFINI | дамп памяти MetaPost | .mem | | MPSUPPORT | поддерживающие файлы MetaPost, используемые DMP | | | MFINPUTS | исходный код Metafont | .mf | | MFPOOL, TEXMFINI | строки программы Metafont | .pool | | MFTINPUTS | стилевой файл MFT | .mft | | MISCFONTS | файлы, связанные со шрифтами, которые не подходят под другие категории | | | MLBIBINPUTS, BIBINPUTS, TEXBIB | исходный файл библиографии MlBibTeX | .mlbib, .mlbib | | MLBSTINPUTS, BSTINPUTS | стиль MlBibTeX | .mlbst, .bst | | MPINPUTS | исходный код MetaPost | .mp | | MPPOOL, TEXMFINI | строки программы MetaPost | .pool | | OCPINPUTS | скомпилированные файлы процессов Omega | .ocp | | OFMFONTS, TEXFONTS | метрики шрифтов Omega | .ofm, .tfm | | OPENTYPEFONTS | шрифты OpenType | | | OPLFONTS, TEXFONTS | списки свойств Omega | .opl | | OTPINPUTS | файлы процесса преобразования Omega | .otp | | OVFFONTS, TEXFONTS | виртуальные шрифты Omega | .ovf | | OVPFONTS, TEXFONTS | виртуальные списки свойств Omega | .ovp | | PDFTEXCONFIG | файлы конфигурации, специфичные для PDFTeX | | | PROGRAMFONTS, PKFONTS, TEXPKS, GLYPHFONTS, TEXFONTS | упакованные растровые шрифты | .pk | | TEXPSHEADERS, PSHEADERS | загружаемый PostScript | .pro | | RISINPUTS | файлы библиографии RIS, в первую очередь для Bibe | .ris | | SFDFONTS | файлы определения подшрифтов | .sfd | | TEXINPUTS | исходный код TeX | .tex | | TEXDOCS | файлы документации для системы TeX | | | TEXSOURCES | исходные файлы для системы TeX | | | TEXMFSCRIPTS | исполняемые файлы, не зависящие от архитектуры, распространяемые в деревьях texmf | | | TEXPOOL, TEXMFINI | строки программы TeX | .pool | | TFMFONTS, TEXFONTS | метрики шрифтов TeX | .tfm | | TRFONTS | шрифты Troff | | | TTFONTS | Контурные шрифты TrueType | .ttf, ,TTF, .ttc, .TTC, .dfont | | T1FONTS, T1INPUTS, TEXPSHEADERS, DVIPSHEADERS | контурные шрифты PostScript Type 1 | .pfa, .pfb | | T42FONTS | контурные шрифты PostScript Type 42 | | | VFFONTS, TEXFONTS | виртуальные шрифты | .vf | | WEBINPUTS | входные файлы WEB | .web, .ch | | WEB2C | файлы, специфичные для реализации 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/ru/podrobnye-stati/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.