> 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/luokkatiedostot/03-writing-your-own-package.md). # Oman paketin kirjoittaminen Joskus paras tapa käyttää omia komentoja ja makroja asiakirjassa on kirjoittaa uusi paketti alusta alkaen. Tässä artikkelissa selitetään uuden paketin pääasiallinen rakenne. ## Johdanto Ensimmäinen asia ennen uuden paketin koodaamista on määrittää, tarvitsetko todella uuden paketin vai et. On suositeltavaa [hakea CTANista (Comprehensive TeX Archive Network)](http://www.ctan.org/ctan-portal/search/) ja katsoa, onko joku jo luonut jotakin tarpeeseesi vastaavaa. Toinen tärkeä asia pitää mielessä on [ero pakettien ja luokkien välillä](/latex/fi/luokkatiedostot/01-understanding-packages-and-class-files.md). Väärän valinnan tekeminen voi vaikuttaa lopputuotteen joustavuuteen. ## Yleinen rakenne Kaikkien pakettitiedostojen rakenne voidaan karkeasti kuvata seuraaviin neljään osaan: * ***Tunnistus***. Tiedosto ilmoittaa itsensä paketiksi, joka on kirjoitettu LaTeX2ε-syntaksilla. * ***Alustavat määrittelyt***. Tässä tuodaan tarvittavat ulkoiset paketit. Myös tässä tiedoston osassa koodataan ilmoitettujen valintojen tarvitsemat komennot ja määrittelyt. * ***Valinnat***. Paketti ilmoittaa ja käsittelee valinnat. * ***Lisää määrittelyjä***. Paketin pääosa. Melkein kaikki, mitä paketti tekee, määritellään täällä. Seuraavissa alaluvuissa esitetään tarkempi kuvaus rakenteesta ja toimiva esimerkki, *examplepackage.sty*, esitellään. ### Tunnistus Kaikilla paketeilla on oltava kaksi yksinkertaista komentoa: ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/24 Esimerkkipaketti LaTeXille] ``` Komento `\NeedsTeXFormat{LaTeX2e}` asettaa LaTeX-version, jolla paketti toimii. Lisäksi hakasulkeisiin voidaan lisätä päivämäärä, joka määrittää vaaditun vähimmäisjulkaisupäivän. Komento `ProvidesPackage{examplepackage}[...]` tunnistaa tämän paketin nimellä *examplepackage* ja hakasulkeissa on julkaisupäivä ja joitakin lisätietoja. Päivämäärän tulee olla muodossa VVVV/KK/PP [Avaa esimerkki paketin kirjoittamisesta Overleafissa](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Alustavat määrittelyt Useimmat paketit laajentavat ja mukauttavat olemassa olevia paketteja, ja ne tarvitsevat myös joitakin ulkoisia paketteja toimiakseen. Alla lisätään lisää koodia esimerkkipakettiin "examplepackage.sty". ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Esimerkkipaketti] \RequirePackage{imakeidx} \RequirePackage{xstring} \RequirePackage{xcolor} \definecolor{greycolour}{HTML}{525252} \definecolor{sharelatexcolour}{HTML}{882B21} \definecolor{mybluecolour}{HTML}{394773} \newcommand{\wordcolour}{greycolour} ``` Tämän osan komennot joko alustavat joitakin parametreja, joita myöhemmin käytetään valintojen hallintaan, tai tuovat ulkoisia tiedostoja. Komento `\RequirePackage` on hyvin samankaltainen kuin tunnettu `\usepackage`, hakasulkeisiin lisättyjen valinnaisten parametrien käyttö toimii myös. Ainoa ero on, että `\usepackage` ei voi käyttää ennen `\documentclass` komentoa. On erittäin suositeltavaa käyttää `\RequirePackage` uutta pakettia tai luokkaa kirjoitettaessa. [Avaa esimerkki paketin kirjoittamisesta Overleafissa](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Valinnat Jotta paketteihin saadaan hieman joustavuutta, muutamat lisävalinnat ovat erittäin hyödyllisiä. Tiedoston "examplepackage.sty" seuraava osa käsittelee paketin tuontilauseelle annettuja parametreja. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Esimerkkipaketti] \RequirePackage{imakeidx} \RequirePackage{xstring} \RequirePackage{xcolor} \definecolor{greycolour}{HTML}{525252} \definecolor{sharelatexcolour}{HTML}{882B21} \definecolor{mybluecolour}{HTML}{394773} \newcommand{\wordcolour}{greycolour} \DeclareOption{red}{\renewcommand{\wordcolour}{sharelatexcolour}} \DeclareOption{blue}{\renewcommand{\wordcolour}{mybluecolour}} \DeclareOption*{\PackageWarning{examplepackage}{Tuntematon ‘\CurrentOption’}} \ProcessOptions\relax ``` Alla kuvaus tärkeimmistä komennoista, jotka voivat käsitellä paketille välitetyt valinnat. Komento `\DeclareOption{}{}` käsittelee annetun valinnan. Se ottaa kaksi parametria: ensimmäinen on valinnan nimi ja toinen on suoritettava koodi, jos valinta annetaan. Komento `\OptionNotUsed` tulostaa viestin kääntäjään ja lokeihin, eikä valintaa käytetä. Komento `\Declareoption*{}` käsittelee kaikki valinnat, joita ei ole määritelty erikseen. Se ottaa vain yhden parametrin: suoritettavan koodin, kun tuntematon valinta annetaan. Tässä tapauksessa se tulostaa varoituksen seuraavan komennon avulla: `\PackageWarning{}{}`. Katso [virheiden käsittely](#handling-errors) saadaksesi kuvauksen siitä, mitä tämä komento tekee. `\CurrentOption` tallentaa sen pakettivalinnan nimen, jota käsitellään tiettynä hetkenä. Komento `\ProcessOptions\relax` suorittaa koodin jokaiselle valinnalle, ja se on lisättävä sen jälkeen, kun kaikki valintojen käsittelykomennot on kirjoitettu. Tästä komennosta on tähdellinen versio, joka suorittaa valinnat täsmälleen siinä järjestyksessä, jossa kutsukomennot ne määrittävät. Esimerkissä, jos valinnat *punainen* tai *blue* välitetään `\usepackage` komennolle asiakirjassa, komento `\wordcolor` määritellään uudelleen. Sekä värit että oletusarvoinen harmaa väri määriteltiin [alustavissa määrittelyissä](#preliminary-declaration) sen jälkeen, kun tuotiin *xcolor* pakettiin. [Avaa esimerkki paketin kirjoittamisesta Overleafissa](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Lisää määrittelyjä Tässä osassa suurin osa komennoista esiintyy. Tiedostossa "examplepackage.sty". Alla voit nähdä koko pakettitiedoston. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Esimerkkipaketti] \RequirePackage{imakeidx} \RequirePackage{xstring} \RequirePackage{xcolor} \definecolor{greycolour}{HTML}{525252} \definecolor{sharelatexcolour}{HTML}{882B21} \definecolor{mybluecolour}{HTML}{394773} \newcommand{\wordcolour}{greycolour} \DeclareOption{red}{\renewcommand{\wordcolour}{sharelatexcolour}} \DeclareOption{blue}{\renewcommand{\wordcolour}{mybluecolour}} \DeclareOption*{\PackageWarning{examplepackage}{Tuntematon ‘\CurrentOption’}} \ProcessOptions\relax %%Numeroitu ympäristö \newcounter{example}[section] \newenvironment{example}[1][]{\refstepcounter{example}\par\medskip \noindent \textbf{Oma~ympäristö~\theexample. #1} \rmfamily}{\medskip} %%Tärkeät sanat lisätään hakemistoon ja tulostetaan eri värillä \newcommand{\important}[1] {\IfSubStr{#1}{!} {\textcolor{\wordcolour}{\textbf{\StrBefore{#1}{!}~\StrBehind{#1}{!}}}\index{#1}} {\textcolor{\wordcolour}{\textbf{#1}}\index{#1}\kern-1pt} } ``` Tämä paketti määrittelee uuden ympäristön `esimerkki`, ja uuden komennon `\important`, joka tulostaa sanat erityisellä värillä ja lisää ne hakemistoon. Kunkin komennon ymmärtämiseksi täysin katso [viiteopas](#reference-guide) ja linkkejä [lisälukemisen osiossa](#further-reading). Alla on asiakirja, joka käyttää pakettia *examplepackage.sty*. ```latex \documentclass{article} \usepackage[utf8]{inputenc} \usepackage[red]{examplepackage} \makeindex \title{Paketin esimerkki} \author{Team Learn ShareLaTeX} \date{ } \begin{document} \maketitle \section{Introduction} Tässä asiakirjassa testataan uutta pakettia. Tämä paketti sallii erityiset numeroidut ympäristöjä \begin{example} Tämä teksti on erityisessä ympäristössä, ja osa tekstistä tulostetaan lihavoituna alussa, ja asetetaan uusi sisennys. \end{example} Lisäksi on erityinen komento \important{tärkeille!sanoille}, joka tulostetaan erityisellä \important{värillä} riippuen parametrista, jota käytetään \important{paketin} tuontilauseessa. Koska se on \important{tärkeää}. \printindex \end{document} ``` ![WrittingPackagesEx1.png](/files/0e40a60e72285ce24fff722ea44d1587fd7c636e) Huomaa komento ```latex \usepackage[red]{examplepackage} ``` [Avaa esimerkki paketin kirjoittamisesta Overleafissa](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ## Virheiden käsittely Kun kehitetään uusia paketteja, on tärkeää käsitellä mahdolliset virheet, jotta käyttäjälle voidaan ilmoittaa, että jokin meni pieleen. Kääntäjässä virheiden ilmoittamiseen on neljä pääkomentoa. * `\PackageError{*package-name*}{*error-text*}{*help-text*}`. Ottaa kolme parametria, kukin aaltosulkeissa: paketin nimi, virheteksti, joka näytetään (käännösprosessi keskeytetään), ja ohjeteksti, joka tulostetaan, jos käyttäjä painaa "h", kun käännös pysähtyy virheen vuoksi. * `\PackageWarning{*package-name*}{*warning-text*}`. Tässä tapauksessa teksti näytetään, mutta käännösprosessi ei pysähdy. Se näyttää rivinumeron, jolla varoitus tapahtui. * `\PackageWarningNoLine{*package-name*}{*warning-text*}`. Toimii aivan kuten edellinen komento, mutta se ei näytä riviä, jolla varoitus tapahtui. * `\PackageInfo{*package-name*}{*info-text*}`. Tässä tapauksessa toisen parametrin tieto tulostetaan vain transkriptitiedostoon, rivinumero mukaan lukien. [Avaa esimerkki siitä, miten paketti kirjoitetaan Overleafissa](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ## Viiteopas **Luettelo komennoista, joita käytetään yleisesti paketeissa ja luokissa** * `\newcommand{*name*}{*definition*}`. Määrittää [uuden komennon](/latex/fi/komennot/01-commands.md#defining-a-new-command), ensimmäinen parametri on uuden komennon nimi, toinen parametri on se, mitä komento tekee. * `\renewcommand{}{}`. Sama kuin `\newcommand` mutta korvaa olemassa olevan komennon. * `\providecommand{}{}`. Toimii aivan kuten `\newcommand` mutta jos komento on jo määritelty, tämä ohitetaan hiljaisesti. * `\CheckCommand{}{}`. Syntaksi on sama kuin `\newcommand`, mutta sen sijaan se tarkistaa, onko komento olemassa ja onko sillä odotettu määrittely. LaTeX näyttää varoituksen, jos komento ei ole sitä, mitä `\CheckCommand` odotettiin. * `\setlength{}{}`. Asettaa ensimmäisenä parametrina annetun elementin pituudeksi toisen parametrin arvon. * `\mbox{}`. Luo laatikon, joka sisältää aaltosulkeisiin kirjoitetut elementit. * `\fbox{}`. Sama kuin `\mbox`, mutta sisällön ympärille tulostetaan todellisuudessa laatikko. ## Lisälukemista Lisätietoja on kohdassa * [Pakettien ja luokkatiedostojen ymmärtäminen](/latex/fi/luokkatiedostot/01-understanding-packages-and-class-files.md) * [Oman luokan kirjoittaminen](/latex/fi/luokkatiedostot/04-writing-your-own-class.md) * [Komennot](/latex/fi/komennot/01-commands.md) ja [Ympäristöt](/latex/fi/komennot/02-environments.md) * [Pituudet LaTeXissa](/latex/fi/muotoilu/01-lengths-in-latex.md) * [Värien käyttäminen LaTeXissa](/latex/fi/muotoilu/13-using-colors-in-latex.md) * [Hallinta suuressa projektissa](/latex/fi/asiakirjan-rakenne/07-management-in-a-large-project.md) * [LaTeX2ε paketeille ja pakettien kirjoittajille](http://www.latex-project.org/guides/clsguide.pdf) * [Muistiinpanoja TeX-ohjelmoinnista](http://pgfplots.sourceforge.net/TeX-programming-notes.pdf) * [Minuutit alle tunneissa: LaTeX-resurssien käyttö](https://tug.org/pracjourn/2005-4/hefferon/hefferon.pdf) * [The LaTeX Companion. Toinen painos](http://ptgmedia.pearsoncmg.com/images/9780201362992/samplepages/0201362996.pdf) --- # 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/luokkatiedostot/03-writing-your-own-package.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.