> 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/pliki-klas/04-writing-your-own-class.md). # Pisanie własnej klasy Czasami najlepszym sposobem dostosowania dokumentu jest napisanie nowej klasy od podstaw. Ten artykuł wyjaśnia główną strukturę i polecenia potrzebne w nowej klasie. ## Wstęp Pierwszą rzeczą, którą należy zrobić przed napisaniem nowej klasy, jest ustalenie, czy rzeczywiście potrzebujesz nowej klasy, czy nie. Zaleca się, aby [wyszukać w CTAN (Comprehensive TeX Archive Network)](http://www.ctan.org/ctan-portal/search/) sprawdzić, czy ktoś już stworzył coś podobnego do potrzebnej ci klasy dokumentu. Inną ważną rzeczą, o której trzeba pamiętać, jest [różnica między pakietami a klasami](/latex/pl/pliki-klas/01-understanding-packages-and-class-files.md). Wybór niewłaściwej opcji może wpłynąć na elastyczność końcowego produktu. ## Struktura ogólna Strukturę wszystkich plików klas można z grubsza opisać w następujących czterech częściach: * ***Identyfikacja***. Plik deklaruje się jako klasę napisaną składnią LaTeX2ε. * ***Deklaracje wstępne***. Tutaj importowane są potrzebne zewnętrzne pakiety i klasy. Ponadto w tej części pliku kodowane są polecenia i definicje potrzebne dla zadeklarowanych opcji. * ***Opcje***. Klasa deklaruje i przetwarza opcje. * ***Dodatkowe deklaracje***. Główna część klasy. Definiowane jest tutaj niemal wszystko, co robi klasa. W kolejnych podsekcjach zostanie przedstawiony bardziej szczegółowy opis struktury oraz działający przykład, *exampleclass.cls*, zostaną przedstawione. ### Identyfikacja Istnieją dwa proste polecenia, które muszą mieć wszystkie klasy: ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesClass{exampleclass}[2014/08/16 Example LaTeX class] ``` Polecenie `\NeedsTeXFormat{LaTeX2e}` ustawia wersję LaTeX, z którą klasa ma działać. Dodatkowo w nawiasach można dodać datę, aby określić minimalną wymaganą datę wydania. Polecenie `ProvidesClass{exampleclass}[...]` identyfikuje tę klasę jako *exampleclass* a w nawiasach zawiera datę wydania oraz dodatkowe informacje. Data powinna mieć format RRRR/MM/DD [Otwórz przykład pokazujący, jak napisać klasę w Overleaf](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=) ### Deklaracje wstępne Większość klas rozszerza i dostosowuje istniejące, a także potrzebuje do działania pewnych zewnętrznych pakietów. Poniżej do przykładowej klasy dodano trochę więcej kodu `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} ``` Polecenia w tej części albo inicjalizują pewne parametry, które później będą używane do zarządzania opcjami, albo importują pliki zewnętrzne. Polecenie `\LoadClass[twocolumn]{article}` wczytuje klasę `article` z dodatkowym parametrem `twocolumn`. Dlatego wszystkie polecenia w standardowej `article` klasie będą automatycznie dostępne w **przykładowego** klasie, z tą różnicą, że dokument będzie drukowany w układzie dwukolumnowym. `\RequirePackage` jest bardzo podobne do dobrze znanego `\usepackage`, dodawanie opcjonalnych parametrów w nawiasach również będzie działać. Jedyna różnica polega na tym, że `\usepackage` nie może być używane przed `\documentclass` poleceniem. Zdecydowanie zaleca się używanie `\RequirePackage` podczas pisania nowych klas lub pakietów. [Otwórz przykład pokazujący, jak napisać klasę w Overleaf](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=) ### Opcje Aby zapewnić pewną elastyczność w klasach, kilka dodatkowych opcji jest bardzo przydatnych. Następna część pliku `exampleclass.cls` obsługuje parametry przekazane do polecenia \documentclass. Przenieśliśmy też `\LoadClass` na *po* opcje są przetwarzane, tak aby opcje ustawione w pliku .tex mogły zostać przekazane do klasy bazowej. ```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} ``` Istnieją tutaj cztery główne polecenia obsługujące opcje przekazane do klasy. Polecenie `\DeclareOption{}{}` obsługuje daną opcję. Przyjmuje dwa parametry: pierwszy to nazwa opcji, a drugi to kod do wykonania, jeśli opcja zostanie przekazana. Polecenie `\OptionNotUsed` wyświetli komunikat w kompilatorze i w logach, a opcja nie zostanie użyta. W tym przypadku dokument jest ustawiony na układ dwukolumnowy i jeśli użytkownik spróbuje zmienić go na jednokolumnowy, nie zadziała to, a opcja zostanie zignorowana. Polecenie `\Declareoption*{}` obsługuje każdą opcję nieokreśloną jawnie. Przyjmuje tylko jeden parametr: kod do wykonania, gdy zostanie przekazana nieznana opcja. W tym przypadku uruchomi następne polecenie: `\PassOptionsToClass{}{}`. Przekazuje opcję znajdującą się w pierwszej parze nawiasów klamrowych do klasy dokumentu określonej w drugiej parze nawiasów klamrowych. W przykładzie wszystkie nieznane opcje zostaną przekazane do **article** klasy dokumentu. `\CurrentOption` przechowuje nazwę opcji klasy obsługiwanej w danym momencie. Polecenie `\ProcessOptions\relax` wykonuje kod dla każdej opcji i musi zostać wstawione po wpisaniu wszystkich poleceń obsługujących opcje. Istnieje wersja oznaczona gwiazdką tego polecenia, która wykona opcje dokładnie w kolejności określonej przez wywołujące polecenia. W przykładzie, jeśli opcje `red` lub `zielony` są przekazywane do dokumentu, a czcionka używana dla nagłówka i sekcji zostanie ustawiona na odpowiedni kolor. Kolor o nazwie `slcolor` został zdefiniowany w [deklaracjach wstępnych](#preliminary-declaration) po zaimportowaniu `xcolor` pakiet. [Otwórz przykład pokazujący, jak napisać klasę w Overleaf](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=) ### Dodatkowe deklaracje W tej części pojawi się większość poleceń. W „exampleclass.cls” ustawiane są wymiary strony oraz rozmiar czcionki dla tytułu, treści i sekcji. Poniżej można zobaczyć pełny plik klasy. ```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} ``` Aby zrozumieć pozostałe polecenia, zobacz [przewodnik referencyjny](#reference-guide) i odnośniki w [sekcji dalszej lektury](#further-reading). Ostatnie cztery polecenia w przykładzie pokazują cztery rzeczy, które muszą zawierać wszystkie klasy: * Definicja `normalsize`. Ustawia domyślny [rozmiar fontu](/latex/pl/czcionki/01-font-sizes-families-and-styles.md). * Domyślna wartość dla [`textwidth`](/latex/pl/formatowanie/07-page-size-and-margins.md) * Domyślna wartość dla [`textheight`](/latex/pl/formatowanie/07-page-size-and-margins.md) * Specyfikacje dla [numeracji stron](/latex/pl/formatowanie/03-page-numbering.md). Poniżej dokument używający klasy *exampleclass.cls*. ```latex \documentclass[red]{exampleclass} \usepackage[utf8]{inputenc} \usepackage[english]{babel} \usepackage{blindtext} \title{Przykład pokazujący, jak działają klasy} \author{Zespół Learn ShareLaTeX} \date{sierpień 2014} \begin{document} \maketitle \noindent Zacznijmy tutaj od prostego działającego przykładu. \blindtext \section{Wprowadzenie} Problem Monty Halla... \section{To samo} Monty... ``` ![WrittingClassesEx1.png](/files/9a0ab1fcbadb1a5c24d89e00b24791f7fe23601d) Zauważ, że pierwszym poleceniem tutaj jest ```latex \documentclass[red]{exampleclass} ``` [Otwórz przykład pokazujący, jak napisać klasę w Overleaf](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=) ## Obsługa błędów Przy tworzeniu nowych klas ważne jest obsługiwanie możliwych błędów, aby poinformować użytkownika, że coś poszło nie tak. Istnieją cztery główne polecenia służące do zgłaszania błędów w kompilatorze. * `\ClassError{*class-name*}{*error-text*}{*help-text*}`. Przyjmuje trzy parametry, każdy wewnątrz nawiasów klamrowych: nazwę klasy, tekst błędu, który zostanie wyświetlony (proces kompilacji zostanie wstrzymany), oraz tekst pomocy, który zostanie wypisany, jeśli użytkownik naciśnie "h", gdy kompilacja zostanie wstrzymana z powodu błędu. * `\ClassWarning{*class-name*}{*warning-text*}`. W tym przypadku tekst zostanie wyświetlony, ale proces kompilacji się nie zatrzyma. Zostanie pokazany numer linii, w której wystąpiło ostrzeżenie. * `\ClassWarningNoLine{*class-name*}{*warning-text*}`. Działa tak samo jak poprzednie polecenie, ale nie pokaże linii, w której wystąpiło ostrzeżenie. * `\ClassInfo{*class name*}{*info-text*}`. W tym przypadku informacja z drugiego parametru zostanie wydrukowana tylko w pliku transkryptu, wraz z numerem linii. [Otwórz przykład pokazujący, jak napisać klasę w Overleaf](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=) ## Przewodnik referencyjny **Lista poleceń często używanych w klasach i pakietach** * `\newcommand{*name*}{*definition*}`. Definiuje [nowe polecenie](/latex/pl/polecenia/01-commands.md#defining-a-new-command), pierwszy parametr to nazwa nowego polecenia, drugi parametr to to, co polecenie będzie robić. * `\renewcommand{}{}`. Tak samo jak `\newcommand` ale nadpisuje istniejące polecenie. * `\providecommand{}{}`. Działa tak samo jak `\newcommand` ale jeśli polecenie jest już zdefiniowane, to to zostanie po cichu zignorowane. * `\CheckCommand{}{}`. Składnia jest taka sama jak `\newcommand`, ale zamiast tego sprawdzi, czy polecenie istnieje i ma oczekiwaną definicję; LaTeX wyświetli ostrzeżenie, jeśli polecenie nie jest tym, czym `\CheckCommand` oczekiwano. * `\setlength{}{}`. Ustawia długość elementu przekazanego jako pierwszy parametr na wartość zapisaną jako drugi parametr. * `\mbox{}`. Tworzy ramkę zawierającą elementy zapisane wewnątrz nawiasów klamrowych. * `\fbox{}`. Tak samo jak `\mbox`, ale wokół zawartości rzeczywiście jest drukowana ramka. ## Dalsza lektura Więcej informacji znajdziesz w * [Zrozumienie pakietów i plików klas](/latex/pl/pliki-klas/01-understanding-packages-and-class-files.md) * [Pisanie własnego pakietu](/latex/pl/pliki-klas/03-writing-your-own-package.md) * [Polecenia](/latex/pl/polecenia/01-commands.md) i [Środowiska](/latex/pl/polecenia/02-environments.md) * [Długości w LaTeX-u](/latex/pl/formatowanie/01-lengths-in-latex.md) * [Używanie kolorów w LaTeX](/latex/pl/formatowanie/13-using-colors-in-latex.md) * [Zarządzanie w dużym projekcie](/latex/pl/struktura-dokumentu/07-management-in-a-large-project.md) * [LaTeX2ε dla autorów klas i pakietów](http://www.latex-project.org/guides/clsguide.pdf) * [Uwagi o programowaniu w TeX-u](http://pgfplots.sourceforge.net/TeX-programming-notes.pdf) * [Minuty zamiast godzin: korzystanie z zasobów LaTeX](https://tug.org/pracjourn/2005-4/hefferon/hefferon.pdf) * [The LaTeX Companion. Drugie wydanie](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/pl/pliki-klas/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.