> 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/fi/syvalliset-artikkelit/06-an-introduction-to-kpathsea-and-how-tex-engines-search-for-files.md). # Johdanto Kpathseaan ja siihen, miten TeX-moottorit etsivät tiedostoja ## Johdanto Tämä artikkeli tarjoaa johdatuksen siihen, miten TeX-moottorit paikantavat tiedostot, joita tarvitaan asiakirjasi ladontaan—käyttäen LaTeXia tai mitä tahansa muuta makropakettia. Vaikka Overleaf vapauttaa käyttäjät TeX-asennuksen hallinnan haasteista ([TeX Live](https://www.tug.org/texlive/)) TeX-moottorien tiedostohakujen perusteista on hyötyä / ne ovat kiinnostavia, jos haluat luoda kansiorakenteen Overleaf-projektisi hallinnan helpottamiseksi. Miksi näin voisi olla? Jos säilytät joitakin Overleaf-projektisi tiedostoja kansioissa, LaTeX ei ehkä löydä näitä tiedostoja, koska oletusarvoisesti TeX-moottori (kääntäjä) ei ehkä *tiedä* että sen täytyy etsiä näistä kansioista—eikä siis löydä niiden sisältämiä tiedostoja. Tämän välttämiseksi voit luoda projektiisi asetustiedoston nimeltä [latexmkrc-tiedosto](https://mg.readthedocs.io/latexmk.html#configuration-files) jolla voidaan kertoa TeX-moottorille, että kansiosi ovat olemassa ja että sen pitäisi etsiä niistä. Jos haluat siirtyä suoraan esimerkkiin, jossa näytetään latexmkrc-tiedosto, voit lukea tämän ohjeartikkelin: [latexmkrc:n käyttäminen Overleafissä: esimerkkejä ja tekniikoita](/latex/fi/syvalliset-artikkelit/28-how-to-use-latexmkrc-with-overleaf.md). Ei ehkä ole heti ilmeistä, miten tai miksi tuo latexmkrc-tiedosto oikeastaan toimii. Jos haluat tietää miksi ja ehkä saada paremman ymmärryksen sen käyttämisestä projektisi lisäasetusten kanssa, jatka lukemista... Tämän artikkelin lopussa käymme läpi [käytännön esimerkin](#kpathsea-and-texinputs-latexmkrc-file-to-the-rescue)—käyttäen tietämystämme siitä, miten TeX etsii tiedostoja—luodaksemme latexmkrc-tiedoston, jolla hallitaan sisäkkäisiä kansioita, jotka sisältävät grafiikkatiedostosi. ## TeX ja alustariippumattomuus Kun Knuth loi TeX:n, alustariippumattomuus oli keskeinen periaate, joka ohjasi sen suunnittelua ja toteutusta, ja tuo filosofia heijastuu koko TeX:n sisäisissä toiminnoissa (esim. kokonaislukuaritmetiikka, ”kotikutoinen” merkkijononkäsittely, muistinhallinta jne.). Vielä nykyäänkin nykyaikaisten TeX-pohjaisten moottoreiden alustariippumattomuus herättää kysymyksiä ja keskustelua julkisilla foorumeilla; esimerkiksi katso tämä keskustelu tex.stackexchange-sivustolla: [Ovatko XeTeX ja LuaTeX alustariippuvaisia?](https://tex.stackexchange.com/questions/94297/are-xetex-and-luatex-platform-dependent) joka sisältää useiden tunnettujen TeX-asiantuntijoiden kommentteja ja havaintoja. Jätetään kuitenkin toistaiseksi hienommat yksityiskohdat sivuun ja todetaan, että TeX-moottoreiden täytyy silti olla erittäin siirrettäviä — niiden on kyettävä toimimaan useissa käyttöjärjestelmissä ja tuottamaan ”identtisiä” tuloksia. Siirrettävyyden keskeinen osa on tiedostojen etsiminen alustariippumattomalla tavalla. ## TeX-moottorit eivät etsi tiedostoja… oikeasti!? Ei, TeX-moottorit eivät *suoraan* etsi tiedostoja *itse*. Kun käsitellään `.tex` tiedostoa, TeX-moottori saattaa tunnistaa tarpeen avata tietty tiedosto, mutta se *delegoi* löytämistehtävän toiselle ohjelmistolle nimeltä [*Kpathsea*](https://tug.org/kpathsea/): ulkoinen ohjelmakirjasto, joka ei ole osa *ydin* TeX-moottoreiden lähdekoodia. Kpathsea tarjoaa käytännössä API:n ([sovellusohjelmointirajapinnasta](https://en.wikipedia.org/wiki/Application_programming_interface)) jota TeX-moottorit (sekä BibTeX, MetaPost ja muut sovellukset) voivat kutsua aina kun niiden täytyy avata tietty tiedosto: Kpathsea tekee varsinaisen työn tämän tiedoston paikantamiseksi. Kun Knuth kirjoitti alkuperäisen TeX-moottorin — josta kaikki muut TeX-moottorit ovat lopulta polveutuneet — tiedostojen löytämisen/avaamisen ongelma oli merkittävä haaste osittain tuon ajan hyvin hajanaisen teknologiaekosysteemin vuoksi. Itse asiassa TeX:n lähdekoodissa Knuth kutsuu tiedostojen tuloa ja lähtöä ”siirrettävyyden kiroukseksi” (katso sivu 12, kohta 25 [TeX: The Program](https://www.amazon.co.uk/Computers-Typesetting-TeX-Program-TEX/dp/0201134373)). TeX-yhteisö tunnisti tarpeen yhdenmukaistaa (standardisoida) tiedostojen etsintä TeX:ssä —*ja TeXiin liittyvässä ohjelmistossa*—ja päätti tarjota TeX:lle siihen tarvittavat työkalut. Ratkaistakseen erittäin hankalan ongelman alustariippumattomasta tavasta löytää tiedostoja Karl Berry, TeX-yhteisön johtava jäsen, kirjoitti ohjelmiston ratkaistakseen *polku*-hakemisongelman: ratkaisun, jonka hän nimesi [**Kpathsea**](http://tug.org/texinfohtml/kpathsea.html)—joka on johdettu **K**Karlin **Path** **Sea**rching (katso tämä [haastattelu Karl Berryn kanssa](http://www.tug.org/interviews/berry.html)). Voimme todeta, että sitä kutsutaan K**polku**sea eikä K**tiedostoa**sea, koska kuten [dokumentaatiota](http://tug.org/texinfohtml/kpathsea.html) huomauttaa, se on \*polkuja\* hakeva kirjasto. On tärkeää huomata, että Kpathseaa eivät käytä vain TeX-moottorit; myös monet TeXiin liittyvät ohjelmat, kuten BibTeX ja MetaPost, käyttävät Kpathseaa syötetiedostojen etsimiseen. Pääpiirteittäin, aina kun TeX/LaTeX-makrot tarvitsevat tietyn tiedoston avaamista, komennot, joista nuo makrot koostuvat, muunnetaan lopulta matalan tason TeX-käskyiksi (TeX-primitiiiveiksi), joita TeX-moottorit itse suorittavat. Jos nuo käskyt sisältävät tiedoston avaamisen tarpeen, TeX-moottori kutsuu Kpathseaa käytännössä sanoen: ”etsithän tämän tiedoston”; jos tuo Kpathsean haku onnistuu, tiedosto avataan. Jos Kpathsea ei kuitenkaan löydä tiedostoa, siitä ilmoitetaan TeX-moottorille, joka keskeyttää suorituksen ja antaa kuuluisan virheilmoituksen ``! En löydä tiedostoa `...'`` Totuus on, että Kpathsea ei löydä sitä. ### Huomioita LuaTeXistä Tarkkaan ottaen meidän pitäisi tässä kohdassa tehdä varaus ja todeta, että LuaTeX tarjoaa käyttäjälle mekanismin oman tiedostohakukoodinsa tarjoamiseen käyttämällä *takaisinkutsuja*. LuaTeX antaa käyttäjien kirjoittaa funktioita Lua-skriptauskielellä ja rekisteröidä ne LuaTeXiin, jolloin se kutsuu kyseistä käyttäjän määrittämää funktiota tietyissä vaiheissa LuaTeXin suorituksen aikana — tästä nimitys *takaisinkutsuja*. Se on erittäin tehokas tekniikka, ja aiheesta kiinnostunut lukija löytää lisätietoja kohdan 9 [LuaTeXin viiteoppaassa](http://www.pragma-ade.com/general/manuals/luatex.pdf) (kirjoitushetkellä tuo linkki koskee LuaTeX 1.09:ää). ### Kpathsea-asetustiedosto: texmf.cnf Jokainen TeX-asennus sisältää tekstitiedoston nimeltä `texmf.cnf` joka on Kpathsean käyttämä asetustiedosto: se sisältää lukuisia ”asetettavia muuttujia”, jotka määrittävät polut, joita Kpathsea käyttää etsiessään erilaisia tiedostotyyppejä, joita TeX-moottorit (tai BibTeX, MetaPost jne.) saattavat tarvita. Kuten alla näemme, nuo ”asetettavat muuttujat” määrittävät hakupolkuja, jotka on rakennettu niin sanotuista *polkuelementeistä*: käyttäen erilaisia rakenteita, muuttujia ja parametreja määrittämään kukin polkuelementti ”mallipohjaksi”, jota Kpathsea käsittelee luodakseen varsinaiset, fyysiset hakemistot. Tässä yksi konkreettinen esimerkki tällaisesta asetettavasta muuttujasta, joka määrittää OpenType-fonttien hakupolut — älä toistaiseksi huolehdi tämän polun rakenteen merkityksestä: ``` OPENTYPEFONTS = .;$TEXMF/fonts/{opentype,truetype}//;$OSFONTDIR// ``` Tärkeää on vain, että tiedosto `texmf.cnf` (Kpathsean lukema) määrittää asetettavan muuttujan nimeltä `OPENTYPEFONTS` jota käytetään määrittämään polku(t), joita Kpathsea käyttää OpenType-fonttien etsimiseen. ”=” -merkin oikea puoli ei näytä miltään polulta, jota näkisit tavallisessa laitteessa, koska se on rakennettu käyttäen erilaisia muuttujia ja parametreja, jotka määrittävät kunkin polun ”malliksi” tai ”piirustukseksi”, jota Kpathsea käyttää luodakseen todelliset hakemistot etsittäviksi. ### Kpathsean käsitys ”polusta” Ehkä keskeisin ymmärrettävä käsite on Kpathsean käsitys ”polusta”: perusrakenne, jota Kpathsea käyttää selvittääkseen, missä tietty tiedosto sijaitsee. Kuten näimme `OPENTYPEFONTS` yllä olevassa esimerkissä, Kpathsean käsitys polusta näyttää hyvin erilaiselta kuin polut, joita olemme tottuneet käyttämään työpöytä- tai kannettavissa laitteissa. Kuten Kpathsean [dokumentaatiota](http://tug.org/texinfohtml/kpathsea.html#Searching-overview): > ... *hakupolku* on kaksoispistein eroteltu luettelo *polkuelementeistä*, jotka ovat hakemistonimiä muutamin ”lisämaustein”. —mutta huomaa, että puolipistettä (`;`) käytetään myös erottamaan *polkuelementeistä*. Myöhemmin kuvaamme lyhyesti joidenkin noiden ”lisämausteiden” luonnetta. Meidän `OPENTYPEFONTS` esimerkissämme on kolme polkuelementtiä, joista kukin on erotettu puolipisteellä (`;`): ![Kuva, joka näyttää Kpathsean polkumäärityksen sisältämät polkuelementit](/files/51b73e1a3f41ebafd9aa684c34bf283d3a75b4d0) 1. `.` (tarkoittaa nykyistä hakemistoa) 2. `$TEXMF/fonts/{opentype,truetype}//` 3. `$OSFONTDIR//` Huomaa, että kaksoisviiva (`//`) polkuelementissä tarkoittaa alihakemistojen etsimistä (rekursiivisesti). Tyypillinen `texmf.cnf` tiedosto sisältää lukuisia ”asetettavia muuttujia” määrittämään hakupolut tiedostotyypeille, joita Kpathsea voi etsiä. ## Kpathsea: hyvin lyhyt yleiskatsaus Kpathsea on kehittynyt kirjasto — siinä on paljon hienovaraisia yksityiskohtia ja vivahteita — ja jo lyhytkin vilkaisu sen [dokumentaatiota](http://tug.org/texinfohtml/kpathsea.html) tekee selväksi, ettemme voi perehtyä kaikkiin yksityiskohtiin. Voimme kuitenkin yrittää antaa yleiskuvan siitä, mitä se tekee — auttaaksemme suuntaamaan ajatteluasi ja tarjotaksemme lähtökohdan lisälukemiselle. ### Kpathsean keskeinen tarkoitus Kuten dokumentaatiossa todetaan, Kpathsean perimmäinen tarkoitus on ”palauttaa tiedostonimi käyttäjän määrittämästä hakemistoluettelosta”, ja nuo hakemistot (hakupolut) määritellään käyttäen ”muutamia lisämausteita”. ### Nuo ”lisämausteet” Edellä mainitut ”muutamat lisämausteet” sisältävät erilaisia parametreja ja muuttujia, joita Kpathsea käyttää hakupolkujensa (tai ”polkumallien”) rakentamiseen, jotta se voi määrittää polkuja yleisemmällä tavalla. Kun TeX-moottori todella käy (suorittaa), Kpathea voi käyttää noiden parametrien/muuttujien nykyisiä arvoja todellisten polkujen selvittämiseen korvaamalla nuo muuttujat niiden todellisilla (ajonaikaisilla) arvoilla. Nuo muuttujat on helppo tunnistaa (polkuelementeissä), koska ne alkavat `$` merkillä. Siksi sanomme, että Kpathsea *laajentaa* polkuelementin, eli se muuntaa nuo parametrit ja muuttujat: muuttaa polun ”mallin” yhden tai useamman fyysisen hakemiston todelliseksi nimeksi/nimiksi, joista tiedostoa etsitään. Tämä tarjoaa paljon joustavuutta ja tarkoittaa, että Kpathsea saattaa muodostaa luettelon hakemistoista, jotka vastaavat yhtä polkuelementtiä — esimerkiksi jos sille käsketään etsiä alihakemistoja. ### OpenType-esimerkkimme uudelleen tarkasteltuna Kokoamme eri langat yhteen ja tarkastelemme `OPENTYPEFONTS` hieman yksityiskohtaisemmin: ``` OPENTYPEFONTS = .;$TEXMF/fonts/{opentype,truetype}//;$OSFONTDIR// ``` Tarkastellaan kahta polkuelementtiä `$TEXMF/fonts/{opentype,truetype}//` ja `$OSFONTDIR//`. Tässä Kpathsea huomaa aaltosulkeiden käytön `{...}` ja käsittelee `$TEXMF/fonts/{opentype,truetype}` siten, että ne edustavat *kahta* polkuelementtiä: 1. `$TEXMF/fonts/opentype//` 2. `$TEXMF/fonts/truetype//` ja että *alihakemistot* molemmista noista polkuelementeistä pitäisi myös etsiä (mikä ilmenee loppuun lisätystä `//`). **Huomaa**: Katso Kpathsean dokumentaatiosta [alihakemistojen laajennus](http://tug.org/texinfohtml/kpathsea.html#Subdirectory-expansion) tärkeä huomautus siitä, missä järjestyksessä alihakemistoja millä tahansa tasolla etsitään (järjestystä ei ole määritelty). Teemme muutamia huomioita `$TEXMF` alla. #### $OSFONTDIR// `$OSFONTDIR` on muuttuja, jonka arvon tulisi olla määritelty ympäristömuuttujana, joka sisältää sen sijainnin, jossa fontit on tallennettu: tarkka arvo riippuu luonnollisesti käyttöjärjestelmästä, jolla TeX:iä ajetaan. Huomaa, että tässä loppuun lisätty `//` kehottaa Kpathseaa etsimään alihakemistoja OpenType-fontteja etsittäessä. Oletusmääritelmä `OSFONTDIR` sisällä `texmf.cnf` on: ``` OSFONTDIR = /please/set/osfontdir/in/the/environment ``` Joten se on ehdottomasti jotain, joka sinun täytyy asettaa, jos haluat käyttää sitä — ympäristömuuttujasi ohittaa tämän ”paikkamerkki”-määritelmän, joka sisältyy `texmf.cnf`. Jos asetat ympäristömuuttujan `OSFONTDIR` silloin ajonaikana aina kun Kpathsea näkee `$OSFONTDIR` osana polkuelementtiä (kohdassa `texmf.cnf`) se voi korvata muuttujan `$OSFONTDIR` ympäristömuuttujaan tallennetulla todellisella arvolla `OSFONTDIR`. Muista, että käytettäessä sitä `texmf.cnf` polkuelementeissä määritämme muuttujan `$OSFONTDIR`—etuliitteellä `$`—jotta Kpathsea ymmärtää, että kyseessä on muuttuja, jonka *arvo* sen täytyy käyttää. #### Lyhyitä huomioita $TEXMF:stä `TEXMF` on toinen asetettava muuttuja, joka on määritelty `texmf.cnf`; esimerkiksi TeX Liven pääjakelussa näkisit: ``` TEXMF = {$TEXMFAUXTREES$TEXMFCONFIG,$TEXMFVAR,$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFSYSCONFIG,!!$TEXMFSYSVAR,!!$TEXMFDIST} ``` Sinun ei tarvitse huolehtia tämän määritelmän yksityiskohdista `TEXMF`—emme käy läpi kaikkia yksityiskohtia, vaan toteamme vain, että `$TEXMF` muuttujaa käytetään polkuelementeissä, koska se määrittää joukon ylimmän tason kansioita (joihin viitataan nimellä ”texmf-puut”), joista tiedostojen etsintä voidaan aloittaa. `TEXMF` on erittäin hyödyllinen, jos haluat tai joudut jakamaan TeX-asennuksen useisiin hakemistoihin (tai hakemistopuihin). Esimerkiksi sinulla voi olla TeX/LaTeX-pakettien pää- tai mestarikokoelma (esim. TeX Live) ja toinen kokoelma tiedostoja ja kansioita, joita käytetään paikallisten LaTeX-pakettien tallentamiseen — tai ehkä paikallisten asetustiedostojen tai standardipakettien muokattujen versioiden tallentamiseen. TeX-asennuksen jakaminen tällä tavalla voi helpottaa TeX/LaTeX-pakettien pääkokoelman (jakelun) päivittämistä, koska paikallinen kokoelmasi on erotettu pää­tiedostoista, jotka päivittyvät kun päivität TeX Live -jakelusi/-asennuksesi. Lisätietoja monimutkaisempien TeX-asennusten hallinnasta kiinnostunut lukija voi katsoa näistä kahdesta artikkelista: * [Managing Multiple TDS Trees](http://tug.org/TUGboat/Articles/tb22-3/tb72downes.pdf) Michael J Downesin kirjoittama; * [Juggling texmf trees](http://www.ntg.nl/maps/27/17.pdf) Siep Kroonenbergin kirjoittama. #### TeX-hakemistorakenne Jokainen, joka on hallinnoinut TeX-asennusta, tietää, että nykyaikaiset TeX-järjestelmät, kuten TeX Live, sisältävät kymmeniä tuhansia tiedostoja, jotka kattavat valtavan määrän tiedostotyyppejä. TeX Directory Structure (TDS) suunniteltiin parhaiden käytäntöjen ”malliksi” tämän laajan tiedostokokoelman järjestämiseksi toimivassa TeX-asennuksessa, ja sitä suositellaan vahvasti käytettäväksi Kpathsean kanssa. Lisätietoja varten lukija ohjataan TDS-spesifikaatioon: [TeX-tiedostojen hakemistorakenne](https://www.tug.org/tds/tds.pdf). ## Kpathsean tiedostotyypit Kpathseaa käyttävien sovellusten joukko tarvitsee pääsyn laajaan valikoimaan tiedostotyyppejä, joten Kpathsea käyttää ”asetettavaa muuttujaa” tunnistamaan polun/polut kullekin tukemalleen tiedostotyypille (tai tiedostoryhmälle). Verkko­dokumentaatiossa on täydellinen luettelo (katso myös meidän [yhteenvetotaulukkoamme alla](#table-listing-kpathsea-config-variables)) mutta tässä ovat yleisempien tiedostotyyppien ”asetettavat muuttujat”: | | | | ----------------------- | ---------------------------------------------- | | **Asetettava muuttuja** | **Tiedostotyyppien esimerkkejä** | | TEXINPUTS | TeX-lähdetiedostot ja kuva-/grafiikkatiedostot | | BIBINPUTS, BSTINPUTS | BibTeX-bibliografian lähdetiedostot | | TTFONTS | TrueType-outline-fontit | | OPENTYPEFONTS | OpenType-outline-fontit | `TEXINPUTS` on erityisen tärkeä asetettava muuttuja, koska se määrittää, mistä TeX-moottori hakee syötelähdetiedostonsa. Huomaa, että kuvatiedostoja pidetään syötetiedostoina, ja niitä voidaan myös etsiä käyttämällä polkua, jonka määrittää `TEXINPUTS`. ### Joitakin Kpathsean vivahteita Kuten todettiin, Kpathseassa on monia vivahteita, joita emme voi tässä käsitellä yksityiskohtaisesti. Tässä on kuitenkin ominaisuuksia, joita jotkut lukijat saattavat haluta tutkia: * **tiedostonimikanta:** Levyhakujen minimoimiseksi Kpathsea voi käyttää ”ulkoisesti rakennettua [ls-R-nimistä tiedostonimikantatiedostoa](http://tug.org/texinfohtml/kpathsea.html#Filename-database) joka yhdistää tiedostot hakemistoihin”. TeX Live tarjoaa sellaisen sekä työkalut sen päivittämiseen, jos uusia tiedostoja lisätään. * **ympäristömuuttujat**: Asetettavien muuttujien (kuten `OPENTYPEFONTS`) lisäksi Kpathsea käyttää myös taitavasti [ympäristömuuttujat](https://en.wikipedia.org/wiki/Environment_variable); esimerkiksi ympäristömuuttujien ajonaikaisia arvoja voidaan käyttää määrittämään polkuelementtejä `texmf.cnf` tiedostossa (mahdollisesti ohittamaan samannimiset muuttujat, jotka on määritelty `texmf.cnf`). * **ohjelman nimi:** Hienovarainen mutta olennainen osa Kpathsean käyttäytymistä on, että se voi käyttää suoritettavan ohjelman nimeä (esim. TeX-moottoria) rakentaakseen ohjelmakohtaisia hakupolkurakenteita. Tämä antaa huomattavaa joustavuutta, koska tiedostohaku voidaan kohdistaa tietylle TeX-moottorille. Esimerkiksi LuaTeX/LuaLaTeXille: ``` TEXINPUTS.lualatex = .;$TEXMF/tex/{lualatex,latex,luatex,generic,}// TEXINPUTS.luatex = .;$TEXMF/tex/{luatex,plain,generic,}// ``` * **löytäminen `texmf.cnf`**: Saatat kysyä, mistä Kpathsea tietää, missä `texmf.cnf` sitä säilytetään? Vastaus on ympäristömuuttuja nimeltä `TEXMFCNF`. Tämä täytyy asettaa (laitteessa/alustalla, jossa TeX:ää ajetaan) polkuun, jossa `texmf.cnf` se säilytetään. #### Kpathsea-ongelmien vianetsintä Overleafin käyttäjät tuskin tarvitsevat näitä toimintoja, mutta luettelemme ne täydellisyyden vuoksi: * **kpsewhich**: Erillinen ohjelma (sisältyy TeX Liveen), jota voidaan käyttää asetustesi testaamiseen: muuttujien arvojen määrittämiseen ja tiedostojen löytämiseen. Aiheesta kiinnostuneet lukijat ohjataan [verkko­dokumentaatioon](http://tug.org/texinfohtml/kpathsea.html#Invoking-kpsewhich) saadakseen lisätietoja. * **ympäristömuuttujat**: Kpathsea tukee ympäristömuuttujaa nimeltä [`KPATHSEA_DEBUG`](http://www.tug.org/texinfohtml/kpathsea.html#Debugging) auttamaan sen toiminnan virheenkorjauksessa. Voit asettaa `KPATHSEA_DEBUG` sen eri arvoihin sen mukaan, kuinka paljon virhetietoa tarvitset. Asettamalla `KPATHSEA_DEBUG=-1` se tuottaa *merkittävän* määrän dataa. ## Ja lopuksi: kansiot, kuvatiedostot ja latexmkrc Miten yllä oleva liittyy latexmkrc:hen? Jos luet tämän artikkelin [latexmkrc:n käyttäminen Overleafissä: esimerkkejä ja tekniikoita](/latex/fi/syvalliset-artikkelit/28-how-to-use-latexmkrc-with-overleaf.md) voit nähdä, että latexmkrc-esimerkin (Perl-)koodi asettaa ympäristömuuttujan arvon `TEXINPUTS`: ``` $ENV{'TEXINPUTS'}='./tex//:' . $ENV{'TEXINPUTS'}; ``` Huomaa, että tässä käytetty kaksoispiste (`./tex//**:**`) on *erittäin* on tärkeä. Jos jätät tuon kaksoispisteen pois, TeX/LaTeX ei ehkä pysty löytämään tärkeitä järjestelmätiedostoja, kuten LaTeX-paketteja! Mitä tämä latexmkrc-tiedosto käytännössä tekee, on lisätä ylimmän tason kansion polku (`./tex` yllä olevassa esimerkissä) järjestelmän määrittämään `TEXINPUTS` ympäristömuuttujaan, jotta kun Kpathsea käyttää muuttujaa `$TEXINPUTS` se tietää silloin, että kansio `/tex//` tulisi etsiä syötetiedostojen löytämiseksi. Jos katsot tarkasti, huomaat, että todellinen käytetty polku on `./tex//:` sivustolta `//` kertoo Kpathsealle, että sen tulee etsiä tex-kansiosta rekursiivisesti — eli tarkastella kaikkia alikansioita, jotka sisältyvät `tex` kansioon. Kuten todettiin, lisäsimme myös tärkeän kaksoispistemerkin. Voimme käyttää täsmälleen samaa tekniikkaa kuvatiedostoille. ### Sivuhuomio BibTeXistä Kuten todettiin, BibTeX-ohjelma käyttää myös Kpathseaa syötetiedostojensa etsimiseen; erityisesti: * sivustolta `BSTINPUTS` asetettavaa muuttujaa (hakupolkua) käytetään etsimään `.bst` tiedostoja; * ja `BIBINPUTS` asetettavaa muuttujaa (hakupolkua) käytetään etsimään `.bib` .bib-tiedostoja. Jos lisäät uusia `.bst` tai `.bib` tiedostoja Overleaf-projektiisi, voit käyttää alla olevaa tekniikkaa ohjataksesi BibTeXin löytämään nämä tiedostot — sinun täytyy korvata `TEXINPUTS` verrattuna `BSTINPUTS` ja/tai `BIBINPUTS`. ### TEXINPUTS ja sisäkkäisten kansioiden käyttäminen grafiikkatiedostoille Jos projektissasi on paljon grafiikkatiedostoja, voi olla kätevää luoda joukko kansioita niiden tallentamiseen ja hallintaan. Esimerkiksi seuraava kuvakaappaus näyttää osion Overleaf-projektista, jossa käytetään ylimmän tason kansiota nimeltä **`graphics`**: ![Kuva, jossa näkyy sisäkkäisiä kansioita Overleaf-projektissa](/files/9c664cefd2470f53f558f333287d7c6299a39efa) On useita (sisäkkäisiä) alikansioita, jotka sisältävät grafiikkaa asiakirjamme eri osiin. Oletetaan, että meillä on yllä oleva kansiorakenne ja että haluamme käyttää `graphicx` paketin (`\usepackage{graphicx}`) ja että yritämme tehdä sen näin: ```latex \documentclass{article} \usepackage{graphicx} \begin{document} \includegraphics{endlinechar}% hyvä käytäntö on olla käyttämättä tiedostopäätettä \end{document} ``` Se ei toimi, ja saat tällaisen virheen: ``` ! LaTeX-virhe: Tiedostoa `endlinechar' ei löydy. l.4 \includegraphics{endlinechar} En löytänyt tiedostoa millään näistä päätteistä: .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 ``` Tuo virhe johtuu siitä, että grafiikkatiedostomme on tallennettu sijaintiin, josta TeX/LaTeX (ja Kpathsea) eivät ole tietoisia, eivätkä siksi löydä sitä — grafiikkatiedoston polku on: ``` ./graphics/Introduction/Chapter1/Section1/Subsection3/endlinechar.png ``` **Huomaa**: On yleisesti hyväksytty paras käytäntö ***välttää välilyöntimerkkejä kansionimissä***. Vaikka kansioiden nimissä voi varmasti olla välilyöntejä ja alla käsiteltäviä tekniikoita voidaan käyttää, suosittelemme varovaisuutta tämän suhteen asiakirjan siirrettävyyden vuoksi Overleaf-alustan ulkopuolella. Kuten tässä [Overleafin ohjeartikkelissa](/latex/fi/lisaa-aiheita/27-inserting-images.md) voit toki käyttää kansioita grafiikkasi tallentamiseen, mutta sinun täytyy kertoa LaTeXille, missä ne sijaitsevat. Tässä tarkastelemme kahta ratkaisua: * Käyttämällä \graphicspath-komentoa; * Käyttämällä tietämystämme Kpathseasta ja `TEXINPUTS`. ### \graphicspathin käyttäminen Se `graphicx` paketti tarjoaa `\graphicspath` komennon, jolla voit ilmoittaa polut, joilla grafiikkasi sijaitsee; joten voisimme tehdä jotakuinkin näin: ```latex \graphicspath{{./graphics/Introduction/Chapter1/Section1/Subsection3/}} ``` ja LaTeX löytää nyt kaikki kyseiseen polkuun tallennetut grafiikat. **Huomaa**: Jos *täytyy* kansioiden nimissä on välilyöntejä, sinun täytyy ympäröidä polut lainausmerkeillä (`"..."`): ```latex \graphicspath{{"./graphics/Introduction/Chapter 1/Section 1/Subsection 3/"}} ``` **Huomaa**: Voit ilmoittaa useita polkuja näin: ```latex \graphicspath{{path1}{path2}{path3}...{pathN}} ``` jossa `...` tarkoittaa lisäksi aaltosulkeisiin suljettuja polkuja. **Huomaa**: Aloitamme polun `./graphics` eikä pelkästään `/graphics`. Piste (.) kertoo käyttöjärjestelmälle, että polku on suhteessa nykyiseen työhakemistoon. Se `\graphicspath` komento toimii hyvin, mutta jos kansioita on paljon, jokaisen polun lisääminen voi käydä varsin työlääksi; lisäksi polut, jotka on määritelty `\graphicspath` eivät enää toimisi, jos nimeäisit kansiot uudelleen tai järjestelisit ne toisin. Onko helpompaa tapaa? Kyllä, voit käyttää latexmkrc-tiedostoa! #### \graphicspath ja rekursio (alikansiot) Huomaa, että verkossa käydään keskusteluja/väittelyitä siitä, tukevatko jotkin järjestelmät/ottavatko käyttöön `\graphicspath` alihakemistojen rekursiivisen etsimisen, jos lisäät `//` polun loppuun: katso esimerkiksi nämä keskustelut tex.stackexchange-sivustolla: * [LaTeX \graphicspathin rekursiivinen haku](https://tex.stackexchange.com/questions/25443/latex-graphicspath-recursive-search); * [Graphicspath MikTeXille](https://tex.stackexchange.com/questions/3131/graphicspath-for-miktex). Parhaan yhteensopivuuden vuoksi sinun tulisi olettaa, että `\graphicspath` ei tue hakemistojen rekursiivista hakua. ### Kpathsea ja TEXINPUTS (latexmkrc-tiedosto apuun) **VAROITUS:** Huomaa, että seuraava tekniikka toimii hyvin Overleafissä ja asianmukaisesti määritetyissä paikallisissa TeX-asennuksissa; **mutta** jos käytät latexmkrc-tiedostoa, projektistasi voi tulla yhteensopimaton muiden TeX-asennusten kanssa, kuten kustantajien ja verkkolehtien käsittelyjärjestelmien käyttämien. Kolmannen osapuolen TeX-asennukset saattavat tukea tai olla tukematta latexmkrc:n käyttöä, tai ne saattavat sallia sen tai olla sallimatta. Jos sinun täytyy viedä Overleaf-projektisi käytettäväksi muualla tai haluat lähettää sen lehteen, sinun tulisi poistaa kaikki välilyöntimerkit polkunimistä ja parannetun yhteensopivuuden vuoksi lisätä `\graphicspath` komento, joka määrittää kaikki polut: ```latex \graphicspath{{path1}{path2}{path3}...{pathN}} ``` jossa `...` tarkoittaa lisäksi aaltosulkeisiin suljettuja polkuja. Alla käsiteltävä tekniikka (käyttäen `TEXINPUTS`) on testattu onnistuneesti Overleafissä pdfTeX-, XeTeX- ja LuaTeX-moottoreilla (eli Overleaf-valikon pdfLaTeX-, XeLaTeX- ja LuaLaTeX-kääntimiasetuksilla): ![Kuva, joka näyttää, miten LaTeX-kääntäjä valitaan Overleafissä](/files/e697c2d36a5d6b8c77546835ab842d09b7fd6aa8) Palataan esimerkkiimme: haluamme käyttää tätä koodia (syvästi sisäkkäisillä kansioilla), ja käytämme latexmkrc-tiedostoa sen toteuttamiseen: ```latex \documentclass{article} \usepackage{graphicx} \begin{document} \includegraphics{endlinechar}% hyvä käytäntö on olla käyttämättä tiedostopäätettä \end{document} ``` Tässä on kuvakaappaus, jossa yllä oleva koodi toimii ongelmitta: LaTeX on löytänyt grafiikkatiedostomme (`endlinechar.png`) vaikka se on syvästi sisäkkäisessä kansiorakenteessa (ilman välilyöntejä kansioiden nimissä). ![Kuva projektista, jossa sisäkkäiset kansiot käännetään Overleafissä](/files/7444374497fe7d43713172f3967709576162674f) Miten teimme tämän? Sinun tarvitsee vain: * luoda uusi tiedosto ilman tiedostopäätettä ja nimetä se latexmkrc:ksi; * lisätä seuraava rivi tuohon tiedostoon: ``` $ENV{'TEXINPUTS'}='./graphics//:'.$ENV{'TEXINPUTS'}; ``` Kpathsea tietää nyt kansioista, jotka sijaitsevat alla `**graphics**` ja koska `//` se etsii myös alikansioista. Huomaa jälleen, että kaksoispiste kohdassa `./graphics//:` on itse asiassa *erittäin* on tärkeä. Jos jätät tuon kaksoispisteen pois, TeX/LaTeX ei ehkä pysty löytämään tärkeitä järjestelmätiedostoja, kuten LaTeX-paketteja! Käyttämällä yllä olevaa yksinkertaista projekti-esimerkkiä voit nyt kääntää sen, ja kas! LaTeX löytää grafiikkatiedostosi — ja voit nimetä uudelleen tai järjestellä /graphics-kansion alihakemistot uudelleen, eikä se estä LaTeXia löytämästä niitä. ## Taulukko, jossa luetellaan Kpathsean “config variables” Seuraava taulukko on yhteenveto, joka on johdettu [Kpathsea-dokumentaatiossa luetelluista tiedoista](http://tug.org/texinfohtml/kpathsea.html#Supported-file-formats). | | | | | --------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------ | | **Kpathsea-asetusmuuttuja** | **Tiedostotyypin kuvaus** | **Tiedostopääte** | | AFMFONTS | Adobe-fonttimittatiedot | .afm | | MFBASES, TEXMFINI | Metafont-muistin dumppi | .base | | BIBINPUTS, TEXBIB | BibTeX-bibliografian lähdetiedosto | .bib | | BLTXMLINPUTS | BibLaTeXML-bibliografiatiedostot Biberille | .bltxml | | BSTINPUTS | BibTeX-tyyli | .bst | | CLUAINPUTS | dynaamiset kirjastot Lualle | .dll ja .so | | CMAPFONTS | merkkikarttatiedostot | .cmap | | TEXMFCNF | Ajoaikaiset asetustiedostot | .cnf | | CWEBINPUTS | CWEB-syötetiedostot | .w, .web, .ch | | TEXCONFIG | Dvipsin 'config.\*'-tiedostot, kuten config.ps | | | ENCFONTS | koodausvektorit | .enc | | TEXFORMATS, TEXMFINI | TeX-muistin dumppi | .fmt | | FONTCIDMAPS | CJK-kartoitus | .cid | | FONTFEATURES | ensisijaisesti OpenType-fontin ominaisuuksille | .fea | | FONTS, GFFONTS, GLYPHFONTS, TEXFONTS | yleinen fonttibitmap | .gf | | TEXPICTS, TEXINPUTS | Encapsulated PostScript -kuvat | .eps, .epsi | | TEXINDEXSTYLE, INDEXSTYLE | makeindex-tyylitiedostot | .ist | | LIGFONTS | ligatuurimääritystiedostot | .lig | | TEXMFDBS | tiedostonimitietokannat | | | TEXFONTMAPS | fonttikartat | .map | | MPMEMS, TEXMFINI | MetaPost-muistin dumppi | .mem | | MPSUPPORT | MetaPostin tukitiedostot, joita DMP käyttää | | | MFINPUTS | Metafont-lähde | .mf | | MFPOOL, TEXMFINI | Metafont-ohjelmamerkkijonot | .pool | | MFTINPUTS | MFT-tyylitiedosto | .mft | | MISCFONTS | fontteihin liittyvät tiedostot, jotka eivät sovi muihin kategorioihin | | | MLBIBINPUTS, BIBINPUTS, TEXBIB | MlBibTeX-bibliografian lähdetiedosto | .mlbib, .mlbib | | MLBSTINPUTS, BSTINPUTS | MlBibTeX-tyyli | .mlbst, .bst | | MPINPUTS | MetaPost-lähde | .mp | | MPPOOL, TEXMFINI | MetaPost-ohjelmamerkkijonot | .pool | | OCPINPUTS | Omega-käännetyt prosessitiedostot | .ocp | | OFMFONTS, TEXFONTS | Omega-fonttimittatiedot | .ofm, .tfm | | OPENTYPEFONTS | OpenType-fontit | | | OPLFONTS, TEXFONTS | Omega-ominaisuusluettelot | .opl | | OTPINPUTS | Omega-käännösprosessitiedostot | .otp | | OVFFONTS, TEXFONTS | Omega-virtuaalifontit | .ovf | | OVPFONTS, TEXFONTS | Omega-virtuaaliset ominaisuusluettelot | .ovp | | PDFTEXCONFIG | PDFTeX-kohtaiset asetustiedostot | | | PROGRAMFONTS, PKFONTS, TEXPKS, GLYPHFONTS, TEXFONTS | pakatut bittikarttafontit | .pk | | TEXPSHEADERS, PSHEADERS | ladattava PostScript | .pro | | RISINPUTS | RIS-bibliografiatiedostot, pääasiassa Bibe | .ris | | SFDFONTS | alifonttimääritystiedostot | .sfd | | TEXINPUTS | TeX-lähde | .tex | | TEXDOCS | TeX-järjestelmän dokumentaatiotiedostot | | | TEXSOURCES | TeX-järjestelmän lähdetiedostot | | | TEXMFSCRIPTS | texmf-puihin jaetut arkkitehtuurista riippumattomat suoritettavat tiedostot | | | TEXPOOL, TEXMFINI | TeX-ohjelmamerkkijonot | .pool | | TFMFONTS, TEXFONTS | TeX-fonttimittatiedot | .tfm | | TRFONTS | Troff-fontit | | | TTFONTS | TrueType-outline-fontit | .ttf, ,TTF, .ttc, .TTC, .dfont | | T1FONTS, T1INPUTS, TEXPSHEADERS, DVIPSHEADERS | Type 1 PostScript -ääriviivafontit | .pfa, .pfb | | T42FONTS | Type 42 PostScript -ääriviivafontit | | | VFFONTS, TEXFONTS | virtuaalifontteja | .vf | | WEBINPUTS | WEB-syötetiedostot | .web, .ch | | WEB2C | web2c-toteutukselle ominaiset tiedostot | | --- # 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/fi/syvalliset-artikkelit/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.