> 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/pl/artykuly-szczegolowe/06-an-introduction-to-kpathsea-and-how-tex-engines-search-for-files.md). # Wprowadzenie do Kpathsea i do tego, jak silniki TeX wyszukują pliki ## Wstęp Ten artykuł przedstawia wprowadzenie do tego, jak silniki TeX-a lokalizują pliki potrzebne do składania dokumentu — używając LaTeX-a lub dowolnego innego pakietu makr. Chociaż Overleaf zwalnia użytkowników z trudności związanych z zarządzaniem instalacją TeX-a ([TeX Live](https://www.tug.org/texlive/)), podstawy tego, jak silniki TeX-a wyszukują pliki, przydadzą się/będą interesujące, jeśli chcesz utworzyć strukturę folderów, aby ułatwić zarządzanie projektem Overleaf. Dlaczego mogłoby to być prawdą? Jeśli przechowujesz niektóre pliki projektu Overleaf w folderach, LaTeX może nie znaleźć tych plików, ponieważ domyślnie silnik TeX-a (kompilator) może nie *wiedzieć* że musi przeszukiwać te foldery — a więc nie znajdzie plików, które zawierają. Aby tego uniknąć, możesz utworzyć i dodać do projektu plik konfiguracyjny o nazwie [plik latexmkrc](https://mg.readthedocs.io/latexmk.html#configuration-files) który można wykorzystać, aby poinformować silnik TeX-a, że twoje foldery istnieją i że powinien je przeszukiwać. Jeśli chcesz przejść od razu do przykładu pokazującego plik latexmkrc, możesz przeczytać ten artykuł pomocy: [Jak używać latexmkrc z Overleaf: przykłady i techniki](/latex/pl/artykuly-szczegolowe/28-how-to-use-latexmkrc-with-overleaf.md). Może nie być od razu oczywiste, jak lub dlaczego ten plik latexmkrc rzeczywiście działa. Jeśli chcesz wiedzieć dlaczego i być może lepiej to zrozumieć pod kątem dalszych możliwości konfiguracji projektu, czytaj dalej... Na końcu tego artykułu przejdziemy przez [praktyczny przykład](#kpathsea-and-texinputs-latexmkrc-file-to-the-rescue)— wykorzystując naszą wiedzę o tym, jak TeX przeszukuje pliki — aby utworzyć plik latexmkrc do zarządzania zagnieżdżonymi folderami zawierającymi pliki graficzne. ## TeX i niezależność od platformy Kiedy Knuth tworzył TeX-a, niezależność od platformy była centralną zasadą kierującą jego projektem i implementacją, a ta filozofia jest odzwierciedlona w całym wewnętrznym działaniu TeX-a (np. używanie arytmetyki całkowitoliczbowej, „własnoręcznie” napisanej obsługi ciągów znaków, zarządzania pamięcią itd.). Nawet dziś niezależność od platformy nowoczesnych silników opartych na TeX-ie nadal budzi pytania i dyskusje na publicznych forach; na przykład zobacz tę dyskusję na tex.stackexchange: [Czy XeTeX i LuaTeX są zależne od platformy?](https://tex.stackexchange.com/questions/94297/are-xetex-and-luatex-platform-dependent) która zawiera komentarze i spostrzeżenia kilku dobrze znanych ekspertów TeX-a. Jednak na razie odłóżmy na bok drobniejsze szczegóły i zauważmy, że silniki TeX-a nadal muszą być wysoce przenośne — zdolne do działania w wielu systemach operacyjnych i do uzyskiwania „identycznych” wyników. Kluczowym aspektem przenośności jest wyszukiwanie plików w sposób niezależny od platformy. ## Silniki TeX-a nie wyszukują plików… naprawdę!? Nie, silniki TeX-a nie *bezpośrednie* wyszukują plików *same z siebie*. Podczas przetwarzania `.tex` pliku silnik TeX-a może rozpoznać potrzebę otwarcia określonego pliku, ale *przekazuje* zadanie jego odnalezienia innemu programowi o nazwie [*Kpathsea*](https://tug.org/kpathsea/): zewnętrznej bibliotece oprogramowania, która nie jest częścią *rdzenia* kodu źródłowego silników TeX-a. To, co Kpathsea zapewnia, to w praktyce API ([interfejs programowania aplikacji](https://en.wikipedia.org/wiki/Application_programming_interface)) które silniki TeX-a (wraz z BibTeX, MetaPost i innymi aplikacjami) mogą wywołać, gdy potrzebują otworzyć określony plik: Kpathsea wykonuje właściwą pracę polegającą na zlokalizowaniu tego pliku. Kiedy Knuth napisał oryginalny silnik TeX-a — od którego ostatecznie wywodzą się wszystkie inne silniki TeX-a — problem znajdowania/otwierania plików stanowił istotne wyzwanie, częściowo z powodu bardzo zróżnicowanego ekosystemu technologicznego tamtych czasów. W rzeczywistości w kodzie źródłowym TeX-a Knuth odnosi się do wejścia/wyjścia plików jako do „zmory przenośności” (zob. strona 12, sekcja 25 [TeX: The Program](https://www.amazon.co.uk/Computers-Typesetting-TeX-Program-TEX/dp/0201134373)). Społeczność TeX-a uznała potrzebę ujednolicenia (standaryzacji) wyszukiwania plików dla TeX-a —*i oprogramowania związanego z TeX-em*— i postanowiła dostarczyć TeX-owi narzędzia do tego. Aby rozwiązać bardzo trudny problem platformo-niezależnej metody znajdowania plików, Karl Berry, czołowy członek społeczności TeX-a, napisał oprogramowanie rozwiązujące problem *wyszukiwania ścieżek*: rozwiązanie, które nazwał [**Kpathsea**](http://tug.org/texinfohtml/kpathsea.html)— co wywodzi się z **K**Karl’s **Path** **Sea**rching (zob. ten [wywiad z Karlem Berrym](http://www.tug.org/interviews/berry.html)). Można zauważyć, że nazywa się to K**wyszukiwania ścieżek**sea, a nie K**pliku**sea, ponieważ — jak [dokumentację](http://tug.org/texinfohtml/kpathsea.html) wskazuje — jest to biblioteka do \*przeszukiwania ścieżek\*. Ważne jest, by zauważyć, że Kpathsea jest używana nie tylko przez silniki TeX-a; różne programy związane z TeX-em, w tym BibTeX i MetaPost, również używają Kpathsea do wyszukiwania plików wejściowych. Z grubsza rzecz biorąc, gdy makra TeX/LaTeX muszą otworzyć określony plik, polecenia, z których te makra są zbudowane, zostaną ostatecznie przekształcone w niskopoziomowe instrukcje TeX-a (prymitywy TeX-a), które silniki TeX-a rzeczywiście wykonują. Jeśli instrukcje te obejmują potrzebę otwarcia pliku, silnik TeX-a zwróci się do Kpathsea, mówiąc w istocie: „proszę znaleźć ten plik”; jeśli to wyszukiwanie Kpathsea zakończy się powodzeniem, plik zostanie otwarty. Jednak jeśli Kpathsea nie zdoła zlokalizować pliku, silnik TeX-a zostanie o tym poinformowany i zatrzyma wykonanie, aby wyświetlić osławiony błąd ``! Nie mogę znaleźć pliku `...'`` Prawda jest taka, że Kpathsea nie może go znaleźć. ### Uwagi o LuaTeX-ie Ściśle rzecz biorąc, powinniśmy zastrzec tę sekcję, zauważając, że LuaTeX rzeczywiście oferuje mechanizm umożliwiający użytkownikowi dostarczenie własnego kodu do wyszukiwania plików poprzez użycie *callbacków*. LuaTeX pozwala użytkownikom pisać funkcje w języku skryptowym Lua i rejestrować je w LuaTeX-ie, aby wywoływał tę zdefiniowaną przez użytkownika funkcję na określonych etapach podczas wykonywania LuaTeX-a — stąd termin *callbacków*callback [Podręczniku referencyjnym LuaTeX](http://www.pragma-ade.com/general/manuals/luatex.pdf) . To bardzo potężna technika, a zainteresowany czytelnik znajdzie więcej informacji w sekcji 9 (w chwili pisania ten link prowadzi do LuaTeX 1.09). ### Plik konfiguracyjny Kpathsea: texmf.cnf Każda instalacja TeX-a zawiera plik tekstowy o nazwie `texmf.cnf` który jest plikiem konfiguracyjnym używanym przez Kpathsea: zawiera liczne „zmienne konfiguracyjne”, które definiują ścieżki, których Kpathsea będzie używać do wyszukiwania różnych typów plików, których mogą potrzebować silniki TeX-a (lub BibTeX, MetaPost itd.). Jak zobaczymy poniżej, te „zmienne konfiguracyjne” definiują ścieżki wyszukiwania zbudowane z tak zwanych *elementów ścieżki*: przy użyciu różnych konstrukcji, zmiennych i parametrów, aby zdefiniować każdy element ścieżki jako „szablon”, który Kpathsea przetwarza, by wygenerować rzeczywiste, fizyczne katalogi do przeszukania. Aby podać konkretny przykład, oto jedna z takich zmiennych konfiguracyjnych, która definiuje ścieżki wyszukiwania dla czcionek OpenType — na razie nie martw się znaczeniem konstrukcji tej ścieżki: ``` OPENTYPEFONTS = .;$TEXMF/fonts/{opentype,truetype}//;$OSFONTDIR// ``` Ważne jest tutaj tylko to, że plik `texmf.cnf` (czytany przez Kpathsea) definiuje zmienną konfiguracyjną o nazwie `OPENTYPEFONTS` która służy do definiowania ścieżki/ścieżek, których Kpathsea użyje do wyszukiwania czcionek OpenType. Prawa strona znaku „=” nie wygląda jak żadna ścieżka, którą widzisz na typowym urządzeniu, ponieważ jest zbudowana przy użyciu różnych zmiennych i parametrów, aby zdefiniować każdą ścieżkę jako „szablon” lub „plan”, który Kpathsea wykorzysta do wygenerowania rzeczywistych katalogów do przeszukania. ### Pojęcie „ścieżki” w Kpathsea Być może centralnym pojęciem do zrozumienia jest pojęcie „ścieżki” w Kpathsea: podstawowa konstrukcja, której Kpathsea używa, aby ustalić, gdzie znajduje się dany plik. Jak widzieliśmy w `OPENTYPEFONTS` powyższym przykładzie, pojęcie ścieżki w Kpathsea wygląda bardzo inaczej niż ścieżki, których jesteśmy przyzwyczajeni używać na naszych komputerach stacjonarnych lub urządzeniach przenośnych. Cytując dokumentację Kpathsea [dokumentację](http://tug.org/texinfohtml/kpathsea.html#Searching-overview): > ... a *ścieżka wyszukiwania* jest listą rozdzielaną dwukropkami z *elementów ścieżki*, które są nazwami katalogów z kilkoma „dodatkowymi ozdobnikami”. —ale zauważ, że średnik (`;`) jest również używany do oddzielania *elementów ścieżki*. Później krótko wskażemy charakter niektórych z tych „dodatkowych ozdobników”. W naszym `OPENTYPEFONTS` przykładzie istnieją trzy elementy ścieżki, z których każdy jest oddzielony średnikiem (`;`): ![Obraz pokazujący elementy ścieżki zawarte w definicji ścieżki Kpathsea](/files/9eccd9f48508f45189754d8f44d48434de48b6fd) 1. `.` (co oznacza bieżący katalog) 2. `$TEXMF/fonts/{opentype,truetype}//` 3. `$OSFONTDIR//` Zauważ, że podwójny ukośnik (`//`) w elemencie ścieżki oznacza przeszukiwanie podkatalogów (rekurencyjnie). Typowy `texmf.cnf` plik będzie zawierał liczne „zmienne konfiguracyjne”, określające ścieżki wyszukiwania dla typów plików, które Kpathsea może przeszukiwać. ## Kpathsea: bardzo krótki przegląd Kpathsea jest wyrafinowaną biblioteką — z wieloma drobnymi szczegółami i niuansami — a nawet pobieżne spojrzenie na jej [dokumentację](http://tug.org/texinfohtml/kpathsea.html) dokumentację sprawia, że jasne staje się, iż nie możemy zagłębiać się we wszystkie szczegóły. Jednak możemy spróbować przedstawić ogólny przegląd tego, co robi — aby pomóc ukierunkować twoje myślenie i dać punkt wyjścia do dalszej lektury. ### Podstawowy cel Kpathsea Jak zauważono w dokumentacji, fundamentalnym celem Kpathsea jest „zwrócenie nazwy pliku z listy katalogów określonej przez użytkownika” oraz to, że te katalogi (ścieżki wyszukiwania) są określane przy użyciu „kilku dodatkowych ozdobników”. ### Te „dodatkowe ozdobniki” Te „kilka dodatkowych ozdobników” wspomniane powyżej obejmują różne parametry i zmienne, których Kpathsea używa do konstruowania swoich ścieżek wyszukiwania (lub „szablonów ścieżek”), tak aby mógł definiować ścieżki w bardziej ogólny sposób. Gdy silnik TeX-a rzeczywiście działa (wykonuje się), Kpathsea może użyć bieżących wartości tych parametrów/zmiennych, aby ustalić rzeczywiste ścieżki, zastępując te zmienne ich rzeczywistymi (w czasie wykonania) wartościami. Łatwo rozpoznasz te zmienne (wewnątrz elementów ścieżki), ponieważ zaczynają się od znaku `$` $ W ten sposób mówimy, że Kpathsea *rozwija* element ścieżki, co oznacza, że przekształca te parametry i zmienne: zamieniając „szablon” ścieżki w rzeczywistą nazwę lub nazwy jednego lub większej liczby fizycznych katalogów, w których należy szukać pliku. Daje to dużą elastyczność i oznacza, że Kpathsea może utworzyć listę katalogów odpowiadającą pojedynczemu elementowi ścieżki — na przykład, jeśli otrzyma polecenie przeszukiwania podkatalogów. ### Nasz przykład z OpenType ponownie Połączymy teraz różne wątki i przyjrzymy się `OPENTYPEFONTS` nieco bardziej szczegółowo: ``` OPENTYPEFONTS = .;$TEXMF/fonts/{opentype,truetype}//;$OSFONTDIR// ``` Rozważmy dwa elementy ścieżki `$TEXMF/fonts/{opentype,truetype}//` i `$OSFONTDIR//`. Tutaj Kpathsea zauważa użycie nawiasów klamrowych `{...}` i traktuje `$TEXMF/fonts/{opentype,truetype}` jako reprezentujące *dwa* elementy ścieżki: 1. `$TEXMF/fonts/opentype//` 2. `$TEXMF/fonts/truetype//` oraz że *podkatalogi* obu tych elementów ścieżki również powinny zostać przeszukane (co wskazuje końcowy `//`). **Uwaga**: Zobacz dokumentację Kpathsea dotyczącą [rozwijania podkatalogów](http://tug.org/texinfohtml/kpathsea.html#Subdirectory-expansion) w sprawie ważnego zastrzeżenia dotyczącego kolejności, w jakiej przeszukiwane są podkatalogi na dowolnym poziomie (jest ona nieokreślona). Zrobimy kilka uwag na temat `$TEXMF` poniżej. #### $OSFONTDIR// `$OSFONTDIR` jest zmienną, której wartość powinna być zdefiniowana jako zmienna środowiskowa zawierająca lokalizację, w której przechowywane są czcionki: dokładna wartość będzie oczywiście zależeć od systemu operacyjnego używanego do uruchamiania TeX-a. Zauważ, że tutaj końcowy `//` nakazuje Kpathsea przeszukiwanie podkatalogów podczas szukania czcionek OpenType. Domyślna definicja `OSFONTDIR` w obrębie `texmf.cnf` jest: ``` OSFONTDIR = /please/set/osfontdir/in/the/environment ``` Jest to więc coś, co z pewnością trzeba ustawić, jeśli chce się z tego korzystać — zmienna środowiskowa zastąpi tę definicję-„zastępcę” zawartą w `texmf.cnf`. Jeśli ustawisz zmienną środowiskową `OSFONTDIR` to w czasie wykonania, wszędzie tam, gdzie Kpathsea zobaczy `$OSFONTDIR` jako część elementu ścieżki (w `texmf.cnf`) może zastąpić zmienną `$OSFONTDIR` rzeczywistą wartością zapisaną w zmiennej środowiskowej `OSFONTDIR`. Pamiętaj, że używając jej wewnątrz `texmf.cnf` elementów ścieżki, określamy zmienną `$OSFONTDIR`—z poprzedzającym ją `$`$ *wartości* —aby poinformować Kpathsea, że jest to zmienna, której #### Krótkie uwagi o $TEXMF `TEXMF` jest kolejną zmienną konfiguracyjną, która jest zdefiniowana w `texmf.cnf`; na przykład w głównej dystrybucji TeX Live zobaczysz: ``` TEXMF = {$TEXMFAUXTREES$TEXMFCONFIG,$TEXMFVAR,$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFSYSCONFIG,!!$TEXMFSYSVAR,!!$TEXMFDIST} ``` Nie musisz się przejmować szczegółami tej definicji `TEXMF`— nie będziemy zgłębiać wszystkich detali, a jedynie zauważmy, że `$TEXMF` zmienna jest używana wewnątrz elementów ścieżki, ponieważ definiuje serię katalogów najwyższego poziomu (określanych jako „drzewa texmf”), od których można rozpocząć wyszukiwanie plików. `TEXMF` jest niezwykle przydatne, jeśli chcesz lub musisz podzielić instalację TeX-a na wiele katalogów (lub „drzew” katalogów). Na przykład posiadanie głównej lub nadrzędnej kolekcji pakietów TeX/LaTeX (np. TeX Live) oraz innej kolekcji plików i folderów służących do przechowywania lokalnych pakietów LaTeX — albo może do przechowywania lokalnych plików konfiguracyjnych lub dostosowanych wersji standardowych pakietów. Podzielenie instalacji TeX-a w ten sposób może ułatwić zarządzanie uaktualnianiem głównej/nadrzędnej kolekcji (dystrybucji) pakietów TeX/LaTeX, ponieważ twoja lokalna kolekcja jest oddzielona od głównych plików, które są aktualizowane podczas uaktualniania dystrybucji/instalacji TeX Live. Dalsze szczegóły dotyczące zarządzania bardziej złożonymi instalacjami TeX-a zainteresowany czytelnik znajdzie w tych dwóch artykułach: * [Zarządzanie wieloma drzewami TDS](http://tug.org/TUGboat/Articles/tb22-3/tb72downes.pdf) autorstwa Michaela J. Downesa; * [Żonglowanie drzewami texmf](http://www.ntg.nl/maps/27/17.pdf) autorstwa Siepa Kroonenberga. #### Struktura katalogów TeX Każdy, kto zarządzał instalacją TeX-a, wie, że nowoczesne systemy TeX, takie jak TeX Live, zawierają wiele dziesiątek tysięcy plików obejmujących ogromną gamę typów plików. Struktura katalogów TeX (TDS) została zaprojektowana jako najlepsza praktyka — „plan” organizacji ogromnej kolekcji plików w działającej instalacji TeX-a — i jest zdecydowanie zalecana do użycia z Kpathsea. Dalsze informacje można znaleźć w specyfikacji TDS: [Struktura katalogów dla plików TeX](https://www.tug.org/tds/tds.pdf). ## Typy plików Kpathsea Zestaw aplikacji, które używają Kpathsea, musi uzyskiwać dostęp do szerokiego zakresu typów plików, więc Kpathsea używa „zmiennej konfiguracyjnej” do identyfikowania ścieżki/ścieżek dla każdego typu pliku (lub grupy plików), który obsługuje. Dokumentacja online zawiera pełną listę (zob. także naszą [tabelę podsumowującą poniżej](#table-listing-kpathsea-config-variables)) ale tutaj są „zmienne konfiguracyjne” dla bardziej powszechnych typów plików: | | | | -------------------------- | -------------------------------------------------- | | **Zmienna konfiguracyjna** | **Przykłady typów plików** | | TEXINPUTS | pliki źródłowe TeX-a oraz pliki z figurami/grafiką | | BIBINPUTS, BSTINPUTS | pliki źródłowe bibliografii BibTeX | | TTFONTS | czcionki konturowe TrueType | | OPENTYPEFONTS | czcionki konturowe OpenType | `TEXINPUTS` jest szczególnie ważną zmienną konfiguracyjną, ponieważ określa, skąd silnik TeX-a pobiera swoje wejściowe pliki źródłowe. Zauważ, że pliki obrazów są uznawane za pliki wejściowe i można ich również szukać przy użyciu ścieżki zdefiniowanej przez `TEXINPUTS`. ### Kilka niuansów Kpathsea Jak wspomniano, Kpathsea ma wiele niuansów, których nie możemy tutaj szczegółowo omówić. Oto jednak funkcje, które niektórzy czytelnicy mogą chcieć zgłębić: * **baza danych nazw plików:** Aby zminimalizować przeszukiwanie dysku, Kpathsea może korzystać z „zewnętrznie utworzonego [pliku bazy danych nazw plików o nazwie ls-R](http://tug.org/texinfohtml/kpathsea.html#Filename-database) mapującego pliki na katalogi”. TeX Live dostarcza taki plik oraz narzędzia do jego aktualizacji, jeśli dodane zostaną nowe pliki. * **zmienne środowiskowe**: Oprócz „zmiennych konfiguracyjnych” (takich jak `OPENTYPEFONTS`) Kpathsea również sprytnie korzysta z [zmienne środowiskowe](https://en.wikipedia.org/wiki/Environment_variable); na przykład bieżąca wartość zmiennych środowiskowych może być używana do definiowania elementów ścieżki w `texmf.cnf` pliku `texmf.cnf`). * **nazwa programu:** Subtelnym, ale istotnym aspektem zachowania Kpathsea jest to, że może ono wykorzystywać nazwę programu wykonywalnego (np. silnik TeX-a) do konstruowania specyficznych dla programu konstrukcji ścieżek wyszukiwania. Daje to znaczną elastyczność, ponieważ wyszukiwanie ścieżek można kierować do plików dla konkretnego silnika TeX-a. Na przykład dla LuaTeX/LuaLaTeX: ``` TEXINPUTS.lualatex = .;$TEXMF/tex/{lualatex,latex,luatex,generic,}// TEXINPUTS.luatex = .;$TEXMF/tex/{luatex,plain,generic,}// ``` * **odnajdywanie `texmf.cnf`**: Pytanie, które możesz sobie zadawać, brzmi: skąd Kpathsea wie, gdzie `texmf.cnf` jest przechowywany? Odpowiedzią jest zmienna środowiskowa o nazwie `TEXMFCNF`. Trzeba ją ustawić (na urządzeniu/platformie uruchamiającej TeX-a) na ścieżkę, gdzie `texmf.cnf` jest przechowywany. #### Debugowanie problemów Kpathsea Użytkownicy Overleaf prawdopodobnie nie będą potrzebować tych funkcji, ale wymieniamy je dla pełności: * **kpsewhich**: Samodzielny program (dołączony do TeX Live), którego można używać do testowania ustawień: określania wartości zmiennych i znajdowania plików. Zainteresowanym czytelnikom polecamy [dokumentację online](http://tug.org/texinfohtml/kpathsea.html#Invoking-kpsewhich) w celu uzyskania dalszych informacji. * **zmienne środowiskowe**: Kpathsea obsługuje zmienną środowiskową o nazwie [`KPATHSEA_DEBUG`](http://www.tug.org/texinfohtml/kpathsea.html#Debugging) w celu ułatwienia debugowania swojego działania. Możesz ustawić `KPATHSEA_DEBUG` na różne wartości w zależności od tego, ile informacji debugowania potrzebujesz. Ustawienie `KPATHSEA_DEBUG=-1` wygeneruje *znaczną* ilość danych. ## I na koniec: foldery, pliki graficzne i latexmkrc A więc, jak to powyższe ma się do latexmkrc? Jeśli przeczytasz ten artykuł [Jak używać latexmkrc z Overleaf: przykłady i techniki](/latex/pl/artykuly-szczegolowe/28-how-to-use-latexmkrc-with-overleaf.md) możesz zobaczyć, że kod (Perl) w przykładzie latexmkrc ustawia wartość zmiennej środowiskowej `TEXINPUTS`: ``` $ENV{'TEXINPUTS'}='./tex//:' . $ENV{'TEXINPUTS'}; ``` Zauważ, że użyty tutaj dwukropek (:)`./tex//:`) to *skrajnie* jest ważny. Jeśli pominiesz ten dwukropek, TeX/LaTeX może nie być w stanie znaleźć ważnych plików systemowych, takich jak pakiety LaTeX! To, co ten plik latexmkrc robi w praktyce, to dodaje ścieżkę folderu najwyższego poziomu (`./tex` w powyższym przykładzie) do systemowo zdefiniowanej `TEXINPUTS` zmiennej środowiskowej, tak aby gdy Kpathsea używa zmiennej `$TEXINPUTS` to będzie ona wtedy świadoma, że folder `/tex//` powinien być przeszukiwany w celu znalezienia plików wejściowych. Jeśli przyjrzysz się uważnie, zobaczysz, że rzeczywista używana ścieżka to `./tex//:` stronie `//` nakazuje Kpathsea przeszukiwanie folderu tex rekurencyjnie — tzn. zaglądanie do wszelkich podfolderów zawartych w `folderze tex` . Jak zauważono, dodaliśmy również ważny znak dwukropka. Możemy użyć dokładnie tej samej techniki dla plików graficznych. ### Dygresja o BibTeX Jak zauważono, program BibTeX również używa Kpathsea do wyszukiwania plików wejściowych; w szczególności: * stronie `BSTINPUTS` zmienna konfiguracyjna (ścieżka wyszukiwania) jest używana do wyszukiwania `.bst` plików; * oraz `BIBINPUTS` zmienna konfiguracyjna (ścieżka wyszukiwania) będzie używana do wyszukiwania `.bib` pliki. Jeśli dodasz nowe `.bst` lub `.bib` pliki do swojego projektu Overleaf, możesz użyć poniższej techniki, aby poinstruować BibTeX, gdzie ma te pliki znaleźć — trzeba zastąpić `TEXINPUTS` z `BSTINPUTS` i/lub `BIBINPUTS`. ### TEXINPUTS i używanie zagnieżdżonych folderów dla plików graficznych Jeśli twój projekt ma wiele plików graficznych, wygodne może być utworzenie zestawu folderów do ich przechowywania i zarządzania nimi. Na przykład poniższy zrzut ekranu pokazuje fragment projektu Overleaf, który używa folderu najwyższego poziomu o nazwie **`graphics`**: ![Obraz pokazujący zagnieżdżone foldery w projekcie Overleaf](/files/91de04f0c71d8fc214866c1a1e1db7bb845c6d93) Istnieje wiele (zagnieżdżonych) podfolderów zawierających grafikę dla różnych sekcji naszego dokumentu. Załóżmy, że mamy powyższą strukturę folderów i chcemy użyć `graphicx` (`\usepackage{graphicx}`) i próbujemy zrobić to w ten sposób: ```latex \documentclass{article} \usepackage{graphicx} \begin{document} \includegraphics{endlinechar}% najlepszą praktyką jest nieużywanie rozszerzenia pliku \end{document} ``` To nie zadziała i otrzymasz taki błąd: ``` ! Błąd LaTeX-a: Nie znaleziono pliku `endlinechar'. l.4 \includegraphics{endlinechar} Nie mogłem odnaleźć pliku przy użyciu żadnego z tych rozszerzeń: .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 ``` Ten błąd powstaje, ponieważ nasz plik graficzny jest przechowywany w lokalizacji, której TeX/LaTeX (i Kpathsea) nie znają, a więc nie mogą go znaleźć — ścieżka do pliku graficznego to: ``` ./graphics/Introduction/Chapter1/Section1/Subsection3/endlinechar.png ``` **Uwaga**: Ogólnie przyjętą dobrą praktyką jest ***unikanie spacji w nazwach folderów***. Chociaż oczywiście można mieć spacje w nazwach folderów, stosując techniki omówione poniżej, odradzamy to z powodów przenośności dokumentu poza platformą Overleaf. Jak wyjaśniono w tym [artykule pomocy Overleaf](/latex/pl/wiecej-tematow/27-inserting-images.md) możesz oczywiście używać folderów do przechowywania grafiki, ale musisz poinformować LaTeX-a, gdzie są przechowywane. Tutaj przyjrzymy się dwóm rozwiązaniom: * Użycie polecenia \graphicspath; * Korzystając z naszej wiedzy o Kpathsea i `TEXINPUTS`. ### Używanie \graphicspath Ta `graphicx` pakiet dostarcza `\graphicspath` polecenie, którego możesz użyć do zadeklarowania ścieżek, w których znajdują się twoje grafiki; moglibyśmy więc zrobić coś takiego: ```latex \graphicspath{{./graphics/Introduction/Chapter1/Section1/Subsection3/}} ``` a LaTeX teraz znajdzie każdą grafikę przechowywaną pod tą ścieżką. **Uwaga**: Jeśli *musi* masz spacje w nazwach folderów, będziesz musiał ująć ścieżki w podwójne cudzysłowy (`"..."`): ```latex \graphicspath{{"./graphics/Introduction/Chapter 1/Section 1/Subsection 3/"}} ``` **Uwaga**: Możesz zadeklarować wiele ścieżek w ten sposób: ```latex \graphicspath{{path1}{path2}{path3}...{pathN}} ``` gdzie `...` oznacza dodatkowe ścieżki ujęte w nawiasy klamrowe. **Uwaga**: Zaczynamy ścieżkę od `./graphics` a nie po prostu `/graphics`. Kropka (.) informuje system operacyjny, że ścieżka jest względna względem bieżącego katalogu roboczego. Ta `\graphicspath` polecenie działa dobrze, ale jeśli masz wiele folderów, dodawanie każdej ścieżki może być dość żmudne; dodatkowo ścieżki zdefiniowane przez `\graphicspath` nie będą już działać, jeśli zmienisz nazwy folderów lub zmienisz ich strukturę. Czy istnieje łatwiejszy sposób? Tak, możesz użyć pliku latexmkrc! #### \graphicspath i rekurencja (podkatalogi) Zauważ, że istnieją dyskusje/debaty online na temat tego, czy niektóre systemy obsługują/włączają `\graphicspath` do rekurencyjnego przeszukiwania podkatalogów, jeśli dodasz `//` na końcu ścieżki: zobacz na przykład te dyskusje na tex.stackexchange: * [Rekurencyjne wyszukiwanie \graphicspath w LaTeX-u](https://tex.stackexchange.com/questions/25443/latex-graphicspath-recursive-search); * [\graphicspath dla MikTeX](https://tex.stackexchange.com/questions/3131/graphicspath-for-miktex). Dla największej zgodności powinieneś założyć, że `\graphicspath` nie obsługuje rekurencyjnego przeszukiwania katalogów. ### Kpathsea i TEXINPUTS (pliki latexmkrc na ratunek) **OSTRZEŻENIE:** Zauważ, że poniższa technika działa dobrze w Overleaf i odpowiednio skonfigurowanych lokalnych instalacjach TeX-a; **ale** jeśli używasz pliku latexmkrc, twój projekt może stać się niekompatybilny z innymi instalacjami TeX-a, takimi jak te używane przez wydawców i internetowe systemy zgłaszania artykułów do czasopism. Instalacje TeX-a stron trzecich mogą, ale nie muszą, obsługiwać lub pozwalać na użycie latexmkrc. Jeśli musisz wyeksportować projekt Overleaf do użycia gdzie indziej lub chcesz go przesłać do czasopisma, powinieneś usunąć wszelkie spacje z nazw ścieżek, a dla lepszej zgodności dodać `\graphicspath` polecenie, które definiuje wszystkie ścieżki: ```latex \graphicspath{{path1}{path2}{path3}...{pathN}} ``` gdzie `...` oznacza dodatkowe ścieżki ujęte w nawiasy klamrowe. Opisana poniżej technika (używająca `TEXINPUTS`) została pomyślnie przetestowana w Overleaf z silnikami pdfTeX, XeTeX i LuaTeX (tj. opcjami kompilatora pdfLaTeX, XeLaTeX i LuaLaTeX w menu Overleaf): ![Obraz pokazujący, jak wybrać kompilator LaTeX-a w Overleaf](/files/696c0a08503d2715976aae274e778fe44e95c4bd) Wracając do naszego przykładu, chcemy użyć tego kodu (z głęboko zagnieżdżonymi folderami) i użyjemy pliku latexmkrc, aby to osiągnąć: ```latex \documentclass{article} \usepackage{graphicx} \begin{document} \includegraphics{endlinechar}% najlepszą praktyką jest nieużywanie rozszerzenia pliku \end{document} ``` Oto zrzut ekranu pokazujący, że powyższy kod działa bez problemów: LaTeX znalazł nasz plik graficzny (`endlinechar.png`) mimo że znajduje się on w głęboko zagnieżdżonej strukturze folderów (bez żadnych spacji w nazwach folderów). ![Obraz pokazujący projekt z zagnieżdżonymi folderami kompilowany w Overleaf](/files/4b8b320d09cea925665862488a321b4adc3e692b) A więc, jak to zrobiliśmy? Wszystko, co musisz zrobić, to: * utworzyć nowy plik, bez rozszerzenia, i nazwać go latexmkrc; * dodać do tego pliku następującą linię: ``` $ENV{'TEXINPUTS'}='./graphics//:'.$ENV{'TEXINPUTS'}; ``` Kpathsea będzie teraz znać foldery znajdujące się w `**graphics**` a dzięki `//` będzie też zaglądać do podfolderów. Zwróć ponownie uwagę, że dwukropek w `./graphics//:` tak naprawdę jest *skrajnie* jest ważny. Jeśli pominiesz ten dwukropek, TeX/LaTeX może nie być w stanie znaleźć ważnych plików systemowych, takich jak pakiety LaTeX! Korzystając z prostego przykładu projektu powyżej, możesz go teraz skompilować i voila! LaTeX znajduje twój plik graficzny — a możesz zmienić nazwy lub uporządkować foldery w /graphics, i nie przeszkodzi to LaTeX-owi w ich odnalezieniu. ## Tabela przedstawiająca „zmienne konfiguracyjne” Kpathsea Poniższa tabela jest podsumowaniem opartym na [danych wymienionych w dokumentacji Kpathsea](http://tug.org/texinfohtml/kpathsea.html#Supported-file-formats). | | | | | --------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------ | | **zmienna konfiguracyjna Kpathsea** | **Opis typu pliku** | **Rozszerzenie pliku** | | AFMFONTS | metryki czcionek Adobe | .afm | | MFBASES, TEXMFINI | zrzut pamięci Metafont | .base | | BIBINPUTS, TEXBIB | źródło bibliografii BibTeX | .bib | | BLTXMLINPUTS | pliki bibliografii BibLaTeXML dla Biber | .bltxml | | BSTINPUTS | styl BibTeX | .bst | | CLUAINPUTS | biblioteki dynamiczne dla Lua | .dll i .so | | CMAPFONTS | pliki map znaków | .cmap | | TEXMFCNF | pliki konfiguracji uruchomieniowej | .cnf | | CWEBINPUTS | pliki wejściowe CWEB | .w, .web, .ch | | TEXCONFIG | Pliki „config.\*” Dvipsa, takie jak config.ps | | | ENCFONTS | wektory kodowania | .enc | | TEXFORMATS, TEXMFINI | zrzut pamięci TeX | .fmt | | FONTCIDMAPS | mapowanie CJK | .cid | | FONTFEATURES | głównie dla funkcji czcionek OpenType | .fea | | FONTS, GFFONTS, GLYPHFONTS, TEXFONTS | ogólna bitmapa czcionki | .gf | | TEXPICTS, TEXINPUTS | rysunki Encapsulated PostScript | .eps, .epsi | | TEXINDEXSTYLE, INDEXSTYLE | pliki stylu makeindex | .ist | | LIGFONTS | pliki definicji ligatur | .lig | | TEXMFDBS | bazy danych nazw plików | | | TEXFONTMAPS | mapy czcionek | .map | | MPMEMS, TEXMFINI | zrzut pamięci MetaPost | .mem | | MPSUPPORT | pliki pomocnicze MetaPost, używane przez DMP | | | MFINPUTS | źródło Metafont | .mf | | MFPOOL, TEXMFINI | ciągi znaków programu Metafont | .pool | | MFTINPUTS | plik stylu MFT | .mft | | MISCFONTS | pliki związane z czcionkami, które nie pasują do innych kategorii | | | MLBIBINPUTS, BIBINPUTS, TEXBIB | źródło bibliografii MlBibTeX | .mlbib, .mlbib | | MLBSTINPUTS, BSTINPUTS | styl MlBibTeX | .mlbst, .bst | | MPINPUTS | źródło MetaPost | .mp | | MPPOOL, TEXMFINI | ciągi znaków programu MetaPost | .pool | | OCPINPUTS | skompilowane pliki procesów Omega | .ocp | | OFMFONTS, TEXFONTS | metryki czcionek Omega | .ofm, .tfm | | OPENTYPEFONTS | czcionki OpenType | | | OPLFONTS, TEXFONTS | listy właściwości Omega | .opl | | OTPINPUTS | pliki procesu tłumaczenia Omega | .otp | | OVFFONTS, TEXFONTS | wirtualne czcionki Omega | .ovf | | OVPFONTS, TEXFONTS | wirtualne listy właściwości Omega | .ovp | | PDFTEXCONFIG | pliki konfiguracyjne specyficzne dla PDFTeX | | | PROGRAMFONTS, PKFONTS, TEXPKS, GLYPHFONTS, TEXFONTS | spakowane bitmapowe czcionki | .pk | | TEXPSHEADERS, PSHEADERS | pobieralny PostScript | .pro | | RISINPUTS | Pliki bibliografii RIS, głównie dla Bibe | .ris | | SFDFONTS | pliki definicji podczcionek | .sfd | | TEXINPUTS | źródło TeX | .tex | | TEXDOCS | pliki dokumentacji dla systemu TeX | | | TEXSOURCES | pliki źródłowe dla systemu TeX | | | TEXMFSCRIPTS | wykonywalne pliki niezależne od architektury dystrybuowane w drzewach texmf | | | TEXPOOL, TEXMFINI | ciągi znaków programu TeX | .pool | | TFMFONTS, TEXFONTS | metryki czcionek TeX | .tfm | | TRFONTS | czcionki Troff | | | TTFONTS | czcionki konturowe TrueType | .ttf, ,TTF, .ttc, .TTC, .dfont | | T1FONTS, T1INPUTS, TEXPSHEADERS, DVIPSHEADERS | konturowe czcionki PostScript typu 1 | .pfa, .pfb | | T42FONTS | konturowe czcionki PostScript typu 42 | | | VFFONTS, TEXFONTS | czcionki wirtualne | .vf | | WEBINPUTS | pliki wejściowe WEB | .web, .ch | | WEB2C | pliki specyficzne dla implementacji 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/pl/artykuly-szczegolowe/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.