> 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/03-writing-your-own-package.md). # Pisanie własnego pakietu Czasami najlepszym sposobem na używanie własnych poleceń i makr w dokumencie jest napisanie nowego pakietu od podstaw. Ten artykuł wyjaśnia główną strukturę nowego pakietu. ## Wstęp Pierwszą rzeczą przed napisaniem nowego pakietu jest ustalenie, czy naprawdę potrzebujesz nowego pakietu. Zaleca się [wyszukać w CTAN (Comprehensive TeX Archive Network)](http://www.ctan.org/ctan-portal/search/) i sprawdzić, czy ktoś już stworzył coś podobnego do tego, czego potrzebujesz. 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 pakietów można z grubsza opisać w następujących czterech częściach: * ***Identyfikacja***. Plik deklaruje się jako pakiet napisany składnią LaTeX2ε. * ***Deklaracje wstępne***. Tutaj importowane są potrzebne pakiety zewnętrzne. Ponadto w tej części pliku kodowane są polecenia i definicje potrzebne przez zadeklarowane opcje. * ***Opcje***. Pakiet deklaruje i przetwarza opcje. * ***Dodatkowe deklaracje***. Główna część pakietu. Prawie wszystko, co robi pakiet, jest tu zdefiniowane. W kolejnych podsekcjach zostanie przedstawiony bardziej szczegółowy opis struktury oraz działający przykład, *examplepackage.sty*, zostaną przedstawione. ### Identyfikacja Istnieją dwa proste polecenia, które muszą mieć wszystkie pakiety: ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/24 Przykładowy pakiet LaTeX] ``` Polecenie `\NeedsTeXFormat{LaTeX2e}` ustawia wersję LaTeX, z którą pakiet ma działać. Dodatkowo w nawiasach można dodać datę, aby określić minimalną wymaganą datę wydania. Polecenie `ProvidesPackage{examplepackage}[...]` identyfikuje ten pakiet jako *examplepackage* a w nawiasach zawiera datę wydania oraz dodatkowe informacje. Data powinna mieć format RRRR/MM/DD [Otwórz przykład tworzenia pakietu w Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Deklaracje wstępne Większość pakietów rozszerza i dostosowuje istniejące, a do działania potrzebuje też zewnętrznych pakietów. Poniżej dodano więcej kodu do przykładowego pakietu „examplepackage.sty”. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Przykładowy pakiet] \RequirePackage{imakeidx} \RequirePackage{xstring} \RequirePackage{xcolor} \definecolor{greycolour}{HTML}{525252} \definecolor{sharelatexcolour}{HTML}{882B21} \definecolor{mybluecolour}{HTML}{394773} \newcommand{\wordcolour}{greycolour} ``` 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 `\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 tworzenia nowych pakietów lub klas. [Otwórz przykład tworzenia pakietu w Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Opcje Aby zapewnić pewną elastyczność w pakietach, kilka dodatkowych opcji jest bardzo przydatnych. Następna część pliku „examplepackage.sty” obsługuje parametry przekazywane do polecenia importującego pakiet. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Przykładowy pakiet] \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}{Nieznana ‘\CurrentOption’}} \ProcessOptions\relax ``` Poniżej opisano główne polecenia, które mogą obsługiwać opcje przekazywane do pakietu. 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, opcja nie zostanie użyta. Polecenie `\Declareoption*{}` obsługuje każdą opcję, która nie została jawnie zdefiniowana. Przyjmuje tylko jeden parametr: kod do wykonania, gdy zostanie przekazana nieznana opcja. W tym przypadku zostanie wyświetlone ostrzeżenie za pomocą następnego polecenia: `\PackageWarning{}{}`. Zobacz [obsługę błędów](#handling-errors) aby zobaczyć opis działania tego polecenia. `\CurrentOption` przechowuje nazwę opcji pakietu, która jest w danym momencie obsługiwana. Polecenie `\ProcessOptions\relax` wykonuje kod dla każdej opcji i musi zostać wstawione po wpisaniu wszystkich poleceń obsługujących opcje. Istnieje wersja gwiazdkowa tego polecenia, która wykona opcje dokładnie w kolejności określonej przez polecenia wywołujące. W przykładzie, jeśli opcje *red* lub *blue* zostaną przekazane do `\usepackage` polecenia w dokumencie, polecenie `\wordcolor` jest przedefiniowane. Oba kolory oraz domyślny szary kolor zostały zdefiniowane w [deklaracjach wstępnych](#preliminary-declaration) po zaimportowaniu *xcolor* pakiet. [Otwórz przykład tworzenia pakietu w Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Dodatkowe deklaracje W tej części pojawi się większość poleceń. W „examplepackage.sty” poniżej można zobaczyć pełny plik pakietu. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Przykładowy pakiet] \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}{Nieznana ‘\CurrentOption’}} \ProcessOptions\relax %%Numerowane środowisko \newcounter{example}[section] \newenvironment{example}[1][]{\refstepcounter{example}\par\medskip \noindent \textbf{Moje~środowisko~\theexample. #1} \rmfamily}{\medskip} %%Ważne słowa są dodawane do indeksu i drukowane w innym kolorze \newcommand{\important}[1] {\IfSubStr{#1}{!} {\textcolor{\wordcolour}{\textbf{\StrBefore{#1}{!}~\StrBehind{#1}{!}}}\index{#1}} {\textcolor{\wordcolour}{\textbf{#1}}\index{#1}\kern-1pt} } ``` Ten pakiet definiuje nowe środowisko `przykładowego`, oraz nowe polecenie `\important`, które drukuje słowa w specjalnym kolorze i dodaje je do indeksu. Aby w pełni zrozumieć każde polecenie, zobacz [przewodnik referencyjny](#reference-guide) i odnośniki w [sekcji dalszej lektury](#further-reading). Poniżej dokument korzystający z pakietu *examplepackage.sty*. ```latex \documentclass{article} \usepackage[utf8]{inputenc} \usepackage[red]{examplepackage} \makeindex \title{Przykład pakietu} \author{Zespół Learn ShareLaTeX} \date{ } \begin{document} \maketitle \section{Wprowadzenie} W tym dokumencie testowany jest nowy pakiet. Pakiet ten umożliwia specjalne numerowane środowisk \begin{example} Ten tekst znajduje się w specjalnym środowisku, na początku wyświetlany jest pewien tekst pogrubiony na początku i ustawiane jest nowe wcięcie. \end{example} Ponadto istnieje specjalne polecenie dla \important{important!words}, które będzie drukowane w specjalnym \important{kolorze} w zależności od parametru użytego w poleceniu importującym \important{pakiet}. Ponieważ jest to \important{ważne}. \printindex \end{document} ``` ![WrittingPackagesEx1.png](/files/e75c8e58dd9a7546e7585d75a40357e79c1105f4) Zwróć uwagę na polecenie ```latex \usepackage[red]{examplepackage} ``` [Otwórz przykład tworzenia pakietu w Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ## Obsługa błędów Podczas tworzenia nowych pakietów ważne jest obsługiwanie możliwych błędów, aby dać użytkownikowi znać, że coś poszło nie tak. Istnieją cztery główne polecenia do zgłaszania błędów w kompilatorze. * `\PackageError{*package-name*}{*error-text*}{*help-text*}`. Przyjmuje trzy parametry, każdy w nawiasach klamrowych: nazwę pakietu, tekst błędu, który zostanie wyświetlony (proces kompilacji zostanie wstrzymany), oraz tekst pomocy, który zostanie wyświetlony, jeśli użytkownik naciśnie „h” po zatrzymaniu kompilacji z powodu błędu. * `\PackageWarning{*package-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. * `\PackageWarningNoLine{*package-name*}{*warning-text*}`. Działa tak samo jak poprzednie polecenie, ale nie pokaże linii, w której wystąpiło ostrzeżenie. * `\PackageInfo{*package-name*}{*info-text*}`. W tym przypadku informacja z drugiego parametru zostanie wydrukowana tylko w pliku transkryptu, wraz z numerem linii. [Otwórz przykład tworzenia pakietu w Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ## Przewodnik referencyjny **Lista poleceń powszechnie używanych w pakietach i klasach** * `\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, czego `\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łasnej klasy](/latex/pl/pliki-klas/04-writing-your-own-class.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 pakietów i ich autoró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/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.