> 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/04-writing-your-own-class.md). # Oman luokan kirjoittaminen Joskus paras vaihtoehto dokumentin muokkaamiseen on kirjoittaa uusi luokka alusta alkaen. Tässä artikkelissa selitetään uuden luokan tärkein rakenne ja tarvittavat komennot. ## Johdanto Ensimmäinen asia, joka kannattaa tehdä ennen uuden luokan koodaamista, on selvittää, tarvitseeko todella uutta luokkaa vai ei. On suositeltavaa [hakea CTANista (Comprehensive TeX Archive Network)](http://www.ctan.org/ctan-portal/search/) ja katsoa, onko joku jo luonut jotakin vastaavaa tarvitsemaasi dokumenttiluokkaan. 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 luokkatiedostojen rakenne voidaan karkeasti kuvata seuraavissa neljässä osassa: * ***Tunnistus***. Tiedosto ilmoittaa itsensä luokaksi, joka on kirjoitettu LaTeX2ε-syntaksilla. * ***Alustavat määrittelyt***. Tähän tuodaan tarvittavat ulkoiset paketit ja luokat. Lisäksi tiedoston tässä osassa koodataan ilmoitettujen valitsinten edellyttämät komennot ja määrittelyt. * ***Valinnat***. Luokka ilmoittaa ja käsittelee valitsimet. * ***Lisää määrittelyjä***. Luokan pääosa. Lähes kaikki, mitä luokka tekee, määritellään täällä. Seuraavissa alaluvuissa esitetään tarkempi kuvaus rakenteesta ja toimiva esimerkki, *exampleclass.cls*, esitellään. ### Tunnistus Kaikilla luokilla täytyy olla kaksi yksinkertaista komentoa: ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesClass{exampleclass}[2014/08/16 Example LaTeX class] ``` Komento `\NeedsTeXFormat{LaTeX2e}` asettaa luokan LaTeX-version, jonka kanssa toimitaan. Lisäksi hakasulkeisiin voidaan lisätä päivämäärä, jolla määritetään vaadittu vähimmäisjulkaisupäivä. Komento `ProvidesClass{exampleclass}[...]` tunnistaa tämän luokan nimellä *exampleclass* ja hakasulkeissa on julkaisupäivä ja joitakin lisätietoja. Päivämäärän tulee olla muodossa VVVV/KK/PP [Avaa esimerkki luokan kirjoittamisesta Overleafissa](https://www.overleaf.com/project/new/template/19419?id=65524436\&templateName=An+example+of+writing+a+LaTeX+class\&latexEngine=\&texImage=texlive-full%3A2020.1\&mainFile=) ### Alustavat määrittelyt Useimmat luokat laajentavat ja muokkaavat olemassa olevia luokkia, ja ne tarvitsevat toimiakseen myös joitakin ulkoisia paketteja. Alla esimerkkiluokkaan lisätään vielä hieman koodia `exampleclass.cls`. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesClass{exampleclass}[2014/08/16 Example LaTeX class] \newcommand{\headlinecolor}{\normalcolor} \LoadClass[twocolumn]{article} \RequirePackage{xcolor} \definecolor{slcolor}{HTML}{882B21} ``` Tämän osan komennot joko alustavat joitakin parametreja, joita myöhemmin käytetään valintojen hallintaan, tai tuovat ulkoisia tiedostoja. Komento `\LoadClass[twocolumn]{article}` lataa luokan `article` lisäparametrilla `twocolumn`. Siksi kaikki vakio- `article` luokan komennot ovat automaattisesti käytettävissä **esimerkki** luokassa, paitsi että asiakirja tulostetaan kaksipalstaisessa muodossa. `\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` kun kirjoitetaan uusia luokkia tai paketteja. [Avaa esimerkki luokan kirjoittamisesta Overleafissa](https://www.overleaf.com/project/new/template/19419?id=65524436\&templateName=An+example+of+writing+a+LaTeX+class\&latexEngine=\&texImage=texlive-full%3A2020.1\&mainFile=) ### Valinnat Jotta luokkiin saadaan hieman joustavuutta, muutamat lisävalitsimet ovat erittäin hyödyllisiä. Tiedoston seuraava osa `exampleclass.cls` käsittelee document class -komentoon välitetyt parametrit. Olemme myös siirtäneet `\LoadClass` kohteeseen *jälkeen* valitsimet käsitellään, jotta .tex-tiedostossa asetetut valitsimet voidaan välittää perusluokalle. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesClass{exampleclass}[2014/08/16 Example LaTeX class] \newcommand{\headlinecolor}{\normalcolor} \RequirePackage{xcolor} \definecolor{slcolor}{HTML}{882B21} \DeclareOption{onecolumn}{\OptionNotUsed} \DeclareOption{green}{\renewcommand{\headlinecolor}{\color{green}}} \DeclareOption{red}{\renewcommand{\headlinecolor}{\color{slcolor}}} \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} \ProcessOptions\relax \LoadClass[twocolumn]{article} ``` Tässä on neljä pääkomentoa, jotka käsittelevät luokalle välitetyt valitsimet. 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` näyttää viestin kääntäjässä ja lokeissa, eikä valitsinta käytetä. Tässä tapauksessa dokumentti on asetettu kaksipalstaiseksi, ja jos käyttäjä yrittää vaihtaa sen yksipalstaiseksi, se ei toimi; valitsin jätetään huomiotta. Komento `\Declareoption*{}` käsittelee kaikki valitsimet, joita ei ole määritelty erikseen. Se ottaa vain yhden parametrin: koodin, joka suoritetaan, kun tuntematon valitsin välitetään. Tässä tapauksessa se suorittaa seuraavan komennon: `\PassOptionsToClass{}{}`. Välittää ensimmäisen aaltosulkuparin sisällä olevan valitsimen toisen aaltosulkuparin sisään asetetulle document class -komennolle. Esimerkissä kaikki tuntemattomat valitsimet välitetään **article** dokumenttiluokalle. `\CurrentOption` tallentaa käsiteltävän luokkavalitsimen nimen tiettynä hetkenä. Komento `\ProcessOptions\relax` suorittaa koodin jokaiselle valitsimelle ja se on lisättävä sen jälkeen, kun kaikki valitsinten käsittelykomennot on kirjoitettu. Tästä komennosta on tähdellinen versio, joka suorittaa valitsimet täsmälleen siinä järjestyksessä kuin kutsukomennot ne määrittävät. Esimerkissä, jos valinnat `punainen` tai `green` välitetään dokumentille otsikon ja osioiden fontti asetetaan vastaavaan väriin. Väri nimeltä `slcolor` määriteltiin [alustavissa määrittelyissä](#preliminary-declaration) sen jälkeen, kun tuotiin `xcolor` pakettiin. [Avaa esimerkki luokan kirjoittamisesta Overleafissa](https://www.overleaf.com/project/new/template/19419?id=65524436\&templateName=An+example+of+writing+a+LaTeX+class\&latexEngine=\&texImage=texlive-full%3A2020.1\&mainFile=) ### Lisää määrittelyjä Tässä osassa esiintyy suurin osa komennoista. "exampleclass.cls"-tiedostossa asetetaan sivun mitat sekä otsikon, leipätekstin ja osioiden fonttikoko. Alla voit nähdä koko luokkatiedoston. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesClass{exampleclass}[2014/08/16 Example LaTeX class] \newcommand{\headlinecolor}{\normalcolor} \RequirePackage{xcolor} \definecolor{slcolor}{HTML}{882B21} \DeclareOption{onecolumn}{\OptionNotUsed} \DeclareOption{green}{\renewcommand{\headlinecolor}{\color{green}}} \DeclareOption{red}{\renewcommand{\headlinecolor}{\color{slcolor}}} \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} \ProcessOptions\relax \LoadClass[twocolumn]{article} \renewcommand{\maketitle}{% \twocolumn[% \fontsize{50}{60}\fontfamily{phv}\fontseries{b}% \fontshape{sl}\selectfont\headlinecolor \@title \\medskip ]% } \renewcommand{\section}{% \@startsection {section}{1}{0pt}{-1.5ex plus -1ex minus -.2ex}% {1ex plus .2ex}{\large\sffamily\slshape\headlinecolor}% } \renewcommand{\normalsize}{\fontsize{9}{10}\selectfont} \setlength{\textwidth}{17.5cm} \setlength{\textheight}{22cm} \setcounter{secnumdepth}{0} ``` Jäljelle jäävien komentojen ymmärtämiseksi katso [viiteopas](#reference-guide) ja linkkejä [lisälukemisen osiossa](#further-reading). Esimerkin neljä viimeistä komentoa näyttävät neljä asiaa, jotka kaikkien luokkien on sisällettävä: * Määritelmä `normalsize`. Asettaa oletusarvoisen [fonttikoko](/latex/fi/fontit/01-font-sizes-families-and-styles.md). * oletusarvo tälle [`textwidth`](/latex/fi/muotoilu/07-page-size-and-margins.md) * oletusarvo tälle [`textheight`](/latex/fi/muotoilu/07-page-size-and-margins.md) * Määritykset [sivunumeroinnille](/latex/fi/muotoilu/03-page-numbering.md). Alla on dokumentti, joka käyttää luokkaa *exampleclass.cls*. ```latex \documentclass[red]{exampleclass} \usepackage[utf8]{inputenc} \usepackage[english]{babel} \usepackage{blindtext} \title{Example to show how classes work} \author{Team Learn ShareLaTeX} \date{August 2014} \begin{document} \maketitle \noindent Aloitetaan tästä yksinkertaisella toimivalla esimerkillä. \blindtext \section{Introduction} Monty Hall -ongelma... \section{The same thing} Monty... ``` ![WrittingClassesEx1.png](/files/cbaf145a7fc47940cca2eabcbcbf763fe6389806) Huomaa, että tässä ensimmäinen komento on ```latex \documentclass[red]{exampleclass} ``` [Avaa esimerkki luokan kirjoittamisesta Overleafissa](https://www.overleaf.com/project/new/template/19419?id=65524436\&templateName=An+example+of+writing+a+LaTeX+class\&latexEngine=\&texImage=texlive-full%3A2020.1\&mainFile=) ## Virheiden käsittely Uusia luokkia kehitettäessä 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. * `\ClassError{*class-name*}{*error-text*}{*help-text*}`. Ottaa kolme parametria, joista kukin on aaltosulkujen sisällä: luokan nimi, näytettävä virheteksti (käännösprosessi pysähtyy) ja ohjeteksti, joka tulostetaan, jos käyttäjä painaa "h", kun käännös keskeytyy virheen vuoksi. * `\ClassWarning{*class-name*}{*warning-text*}`. Tässä tapauksessa teksti näytetään, mutta käännösprosessi ei pysähdy. Se näyttää rivinumeron, jolla varoitus tapahtui. * `\ClassWarningNoLine{*class-name*}{*warning-text*}`. Toimii aivan kuten edellinen komento, mutta se ei näytä riviä, jolla varoitus tapahtui. * `\ClassInfo{*class name*}{*info-text*}`. Tässä tapauksessa toisen parametrin tieto tulostetaan vain transkriptitiedostoon, rivinumero mukaan lukien. [Avaa esimerkki luokan kirjoittamisesta Overleafissa](https://www.overleaf.com/project/new/template/19419?id=65524436\&templateName=An+example+of+writing+a+LaTeX+class\&latexEngine=\&texImage=texlive-full%3A2020.1\&mainFile=) ## Viiteopas **Luokissa ja paketeissa yleisesti käytettyjen komentojen luettelo** * `\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 sellainen kuin `\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 paketin kirjoittaminen](/latex/fi/luokkatiedostot/03-writing-your-own-package.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ε luokkien 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/04-writing-your-own-class.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.