> 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/cs/tridni-soubory/03-writing-your-own-package.md). # Psaní vlastního balíčku Někdy je nejlepším řešením pro používání vlastních příkazů a maker v dokumentu napsat nový balíček od nuly. Tento článek vysvětluje základní strukturu nového balíčku. ## Úvod První věc, kterou je třeba před napsáním nového balíčku udělat, je určit, zda nový balíček opravdu potřebujete, nebo ne. Doporučuje se [vyhledat na CTAN (Comprehensive TeX Archive Network)](http://www.ctan.org/ctan-portal/search/) a zjistit, zda už někdo nevytvořil něco podobného tomu, co potřebujete. Další důležitá věc, kterou je třeba mít na paměti, je [rozdíl mezi balíčky a třídami](/latex/cs/tridni-soubory/01-understanding-packages-and-class-files.md). Nesprávná volba může ovlivnit flexibilitu výsledného produktu. ## Obecná struktura Strukturu všech souborů balíčku lze zhruba popsat následujícími čtyřmi částmi: * ***Identifikace***. Soubor se deklaruje jako balíček napsaný syntaxí LaTeX2ε. * ***Předběžná deklarace***. Zde se importují potřebné externí balíčky. Také v této části souboru jsou zapsány příkazy a definice potřebné pro deklarované volby. * ***Volby***. Balíček deklaruje a zpracovává volby. * ***Další deklarace***. Hlavní část balíčku. Téměř vše, co balíček dělá, je definováno zde. V následujících pododdílech bude předložen podrobnější popis struktury a funkční příklad, *examplepackage.sty*, bude představen. ### Identifikace Všechny balíčky musí mít dva jednoduché příkazy: ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/24 Ukázkový balíček LaTeX] ``` Příkaz `\NeedsTeXFormat{LaTeX2e}` nastaví verzi LaTeXu, se kterou má balíček fungovat. Navíc lze do hranatých závorek přidat datum, které určí požadované minimální datum vydání. Příkaz `ProvidesPackage{examplepackage}[...]` identifikuje tento balíček jako *examplepackage* a v hranatých závorkách je uvedeno datum vydání a nějaké doplňující informace. Datum by mělo být ve formátu YYYY/MM/DD [Otevřít příklad, jak napsat balíček v Overleafu](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Předběžná deklarace Většina balíčků rozšiřuje a upravuje stávající balíčky a k fungování také potřebuje některé externí balíčky. Níže je do ukázkového balíčku „examplepackage.sty“ přidán další kód. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Ukázkový balíček] \RequirePackage{imakeidx} \RequirePackage{xstring} \RequirePackage{xcolor} \definecolor{greycolour}{HTML}{525252} \definecolor{sharelatexcolour}{HTML}{882B21} \definecolor{mybluecolour}{HTML}{394773} \newcommand{\wordcolour}{greycolour} ``` Příkazy v této části buď inicializují některé parametry, které budou později použity ke správě voleb, nebo importují externí soubory. Příkaz `\RequirePackage` je velmi podobný známému `\usepackage`, přidání volitelných parametrů v hranatých závorkách bude také fungovat. Jediný rozdíl je v tom, že `\usepackage` nelze použít před `\documentclass` příkazem. Důrazně se doporučuje používat `\RequirePackage` při psaní nových balíčků nebo tříd. [Otevřít příklad, jak napsat balíček v Overleafu](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Volby Aby balíčky byly trochu flexibilnější, několik dodatečných voleb je velmi užitečných. Další část v souboru „examplepackage.sty“ zpracovává parametry předané příkazu pro import balíčku. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Ukázkový balíček] \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}{Neznámá ‘\CurrentOption’}} \ProcessOptions\relax ``` Níže je popis hlavních příkazů, které mohou zpracovávat volby předané balíčku. Příkaz `\DeclareOption{}{}` zpracovává zadanou volbu. Bere dva parametry: prvním je název volby a druhým kód, který se má vykonat, pokud je volba předána. Příkaz `\OptionNotUsed` vypíše zprávu v překladači i v logu, volba nebude použita. Příkaz `\Declareoption*{}` zpracovává každou volbu, která není výslovně definována. Bere pouze jeden parametr, kód, který se má vykonat, když je předána neznámá volba. V tomto případě vypíše varování pomocí následujícího příkazu: `\PackageWarning{}{}`. Viz [zpracování chyb](#handling-errors) pro popis toho, co tento příkaz dělá. `\CurrentOption` ukládá název volby balíčku, která je v daném okamžiku zpracovávána. Příkaz `\ProcessOptions\relax` spouští kód pro každou volbu a musí být vložen až po tom, co byly zadány všechny příkazy pro zpracování voleb. Existuje i hvězdičkovaná verze tohoto příkazu, která provede volby v přesném pořadí určeném volajícími příkazy. V příkladu, pokud jsou volby *red* nebo *blue* předány `\usepackage` příkazu v dokumentu, příkaz `\wordcolor` je předefinován. Obě barvy i výchozí šedá barva byly definovány v [předběžných deklaracích](#preliminary-declaration) po importu *xcolor* balíček. [Otevřít příklad, jak napsat balíček v Overleafu](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Další deklarace V této části se objeví většina příkazů. V „examplepackage.sty“. Níže můžete vidět celý soubor balíčku. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Ukázkový balíček] \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}{Neznámá ‘\CurrentOption’}} \ProcessOptions\relax %%Číslované prostředí \newcounter{example}[section] \newenvironment{example}[1][]{\refstepcounter{example}\par\medskip \noindent \textbf{Moje~prostředí~\theexample. #1} \rmfamily}{\medskip} %%Důležitá slova jsou přidána do rejstříku a vytištěna jinou barvou \newcommand{\important}[1] {\IfSubStr{#1}{!} {\textcolor{\wordcolour}{\textbf{\StrBefore{#1}{!}~\StrBehind{#1}{!}}}\index{#1}} {\textcolor{\wordcolour}{\textbf{#1}}\index{#1}\kern-1pt} } ``` Tento balíček definuje nové prostředí `příklad`a nový příkaz `\important`, který vypisuje slova speciální barvou a přidává je do rejstříku. Pro úplné pochopení každého příkazu se podívejte na [referenční příručku](#reference-guide) a odkazy v [sekci další četby](#further-reading). Níže je dokument, který používá balíček *examplepackage.sty*. ```latex \documentclass{article} \usepackage[utf8]{inputenc} \usepackage[red]{examplepackage} \makeindex \title{Příklad balíčku} \author{Tým Learn ShareLaTeX} \date{ } \begin{document} \maketitle \section{Úvod} V tomto dokumentu je testován nový balíček. Tento balíček umožňuje speciální číslovaná prostředí \begin{example} Tento text je uvnitř zvláštního prostředí, nějaký text tučným písmem je vytištěn na začátku a je nastaveno nové odsazení. \end{example} Také existuje speciální příkaz pro \important{důležitá!slova}, který bude vytištěn speciální \important{barvou} v závislosti na parametru použitém v \important{balíčku} importation statement. Protože je to \important{důležité}. \printindex \end{document} ``` ![WrittingPackagesEx1.png](/files/c5bd1cfdec43394653f0eae9e059c046bdf1a68b) Všimněte si příkazu ```latex \usepackage[red]{examplepackage} ``` [Otevřít příklad, jak napsat balíček v Overleafu](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ## Zpracování chyb Při vývoji nových balíčků je důležité zpracovávat možné chyby, aby uživatel věděl, že se něco pokazilo. Pro hlášení chyb v překladači existují čtyři hlavní příkazy. * `\PackageError{*package-name*}{*error-text*}{*help-text*}`. Bere tři parametry, každý ve složených závorkách: název balíčku, chybový text, který bude zobrazen (proces kompilace bude pozastaven), a nápovědný text, který se vytiskne, pokud uživatel stiskne „h“, když se kompilace kvůli chybě zastaví. * `\PackageWarning{*package-name*}{*warning-text*}`. V tomto případě se text zobrazí, ale proces kompilace se nezastaví. Ukáže číslo řádku, kde došlo k varování. * `\PackageWarningNoLine{*package-name*}{*warning-text*}`. Funguje stejně jako předchozí příkaz, ale nezobrazí řádek, na kterém došlo k varování. * `\PackageInfo{*package-name*}{*info-text*}`. V tomto případě budou informace v druhém parametru vytištěny pouze do souboru protokolu, včetně čísla řádku. [Otevřít příklad, jak napsat balíček v Overleafu](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ## Referenční příručka **Seznam příkazů běžně používaných v balíčcích a třídách** * `\newcommand{*name*}{*definition*}`. Definuje [nový příkaz](/latex/cs/prikazy/01-commands.md#defining-a-new-command), prvním parametrem je název nového příkazu a druhým parametrem je to, co příkaz bude dělat. * `\renewcommand{}{}`. Stejné jako `\newcommand` ale přepíše stávající příkaz. * `\providecommand{}{}`. Funguje stejně jako `\newcommand` ale pokud je příkaz již definován, tento bude tiše ignorován. * `\CheckCommand{}{}`. Syntaxe je stejná jako `\newcommand`, ale místo toho zkontroluje, zda příkaz existuje a má očekávanou definici; LaTeX zobrazí varování, pokud příkaz není to, co `\CheckCommand` očekáváno. * `\setlength{}{}`. Nastaví délku prvku předaného jako první parametr na hodnotu zapsanou jako druhý parametr. * `\mbox{}`. Vytvoří rámeček, který obsahuje prvky zapsané ve složených závorkách. * `\fbox{}`. Stejné jako `\mbox`, ale kolem obsahu se skutečně vykreslí rámeček. ## Další čtení Další informace najdete v * [Porozumění balíčkům a souborům tříd](/latex/cs/tridni-soubory/01-understanding-packages-and-class-files.md) * [Vytvoření vlastní třídy](/latex/cs/tridni-soubory/04-writing-your-own-class.md) * [Příkazy](/latex/cs/prikazy/01-commands.md) a [Prostředí](/latex/cs/prikazy/02-environments.md) * [Délky v LaTeXu](/latex/cs/formatovani/01-lengths-in-latex.md) * [Používání barev v LaTeXu](/latex/cs/formatovani/13-using-colors-in-latex.md) * [Správa ve velkém projektu](/latex/cs/struktura-dokumentu/07-management-in-a-large-project.md) * [LaTeX2ε pro tvůrce balíčků a tříd](http://www.latex-project.org/guides/clsguide.pdf) * [Poznámky k programování v TeXu](http://pgfplots.sourceforge.net/TeX-programming-notes.pdf) * [Minuty za méně než hodiny: Používání zdrojů LaTeXu](https://tug.org/pracjourn/2005-4/hefferon/hefferon.pdf) * [Průvodce LaTeXem. Druhé vydání](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/cs/tridni-soubory/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.