> For the complete documentation index, see [llms.txt](https://ayakaleaf-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://ayakaleaf-pro.ayaka.space/latex/uk/faili-klasiv/03-writing-your-own-package.md). # Створення власного пакета Іноді найкращий варіант для використання власних команд і макросів у документі — це написати новий пакет з нуля. У цій статті пояснюється основна структура нового пакета. ## Вступ Перш ніж писати новий пакет, насамперед слід визначити, чи справді вам потрібен новий пакет. Рекомендується [пошукати на CTAN (Comprehensive TeX Archive Network)](http://www.ctan.org/ctan-portal/search/) і подивитися, чи вже хтось створив щось подібне до того, що вам потрібно. Ще одна важлива річ, про яку слід пам’ятати, — це [різниця між пакетами та класами](/latex/uk/faili-klasiv/01-understanding-packages-and-class-files.md). Неправильний вибір може вплинути на гнучкість кінцевого продукту. ## Загальна структура Структуру всіх файлів пакетів можна приблизно описати у таких чотирьох частинах: * ***Ідентифікація***. Файл оголошує себе пакетом, написаним із використанням синтаксису LaTeX2ε. * ***Попередні оголошення***. Тут імпортуються потрібні зовнішні пакети. Також у цій частині файлу записуються команди та визначення, потрібні для оголошених параметрів. * ***Параметри***. Пакет оголошує та обробляє параметри. * ***Додаткові оголошення***. Основна частина пакета. Тут визначається майже все, що робить пакет. У наступних підрозділах буде наведено докладніший опис структури та робочий приклад, *examplepackage.sty*, буде наведено. ### Ідентифікація Є дві прості команди, які мають бути в кожному пакеті: ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/24 Зразковий пакет LaTeX] ``` Команда `\NeedsTeXFormat{LaTeX2e}` встановлює версію LaTeX, з якою працюватиме пакет. Додатково в дужках можна додати дату, щоб указати мінімально необхідну дату випуску. Команда `ProvidesPackage{examplepackage}[...]` ідентифікує цей пакет як *examplepackage* а всередині дужок містяться дата випуску та деяка додаткова інформація. Дата має бути у форматі РРРР/ММ/ДД [Відкрити приклад написання пакета в Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Попередні оголошення Більшість пакетів розширюють і налаштовують наявні, а також потребують для роботи деяких зовнішніх пакетів. Нижче до зразка пакета «examplepackage.sty» додано ще трохи коду. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Зразковий пакет] \RequirePackage{imakeidx} \RequirePackage{xstring} \RequirePackage{xcolor} \definecolor{greycolour}{HTML}{525252} \definecolor{sharelatexcolour}{HTML}{882B21} \definecolor{mybluecolour}{HTML}{394773} \newcommand{\wordcolour}{greycolour} ``` Команди в цій частині або ініціалізують деякі параметри, які згодом використовуватимуться для керування параметрами, або імпортують зовнішні файли. Команда `\RequirePackage` дуже схожа на добре відому `\usepackage`, додавання необов’язкових параметрів у дужках також працюватиме. Єдина відмінність полягає в тому, що `\usepackage` не можна використовувати перед `\documentclass` командою. Настійно рекомендується використовувати `\RequirePackage` під час написання нових пакетів або класів. [Відкрити приклад написання пакета в Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Параметри Щоб забезпечити певну гнучкість у пакетах, дуже корисними є кілька додаткових параметрів. Наступна частина у файлі «examplepackage.sty» обробляє параметри, передані до оператора імпорту пакета. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Зразковий пакет] \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}{Невідомий ‘\CurrentOption’}} \ProcessOptions\relax ``` Нижче подано опис основних команд, які можуть обробляти параметри, передані пакету. Команда `\DeclareOption{}{}` обробляє вказаний параметр. Вона приймає два параметри: перший — це назва параметра, а другий — код, який слід виконати, якщо параметр передано. Команда `\OptionNotUsed` виведе повідомлення у компіляторі та журналах, а параметр не буде використано. Команда `\Declareoption*{}` обробляє кожен параметр, який не було явно визначено. Вона приймає лише один параметр — код, який слід виконати, коли передано невідомий параметр. У цьому випадку буде виведено попередження за допомогою наступної команди: `\PackageWarning{}{}`. Див. [обробка помилок](#handling-errors) щоб дізнатися, що робить ця команда. `\CurrentOption` зберігає назву параметра пакета, який обробляється в певний момент. Команда `\ProcessOptions\relax` виконує код для кожного параметра і має бути вставлена після введення всіх команд обробки параметрів. Існує зіркова версія цієї команди, яка виконуватиме параметри в точному порядку, заданому командами виклику. У прикладі, якщо параметри *red* або *blue* передано до `\usepackage` команди в документі, команда `\wordcolor` перевизначається. Обидва кольори та стандартний сірий колір були визначені в [попередніх оголошеннях](#preliminary-declaration) після імпортування *xcolor* пакет. [Відкрити приклад написання пакета в Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Додаткові оголошення У цій частині з’явиться більшість команд. У «examplepackage.sty». Нижче ви можете побачити повний файл пакета. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Зразковий пакет] \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}{Невідомий ‘\CurrentOption’}} \ProcessOptions\relax %%Нумероване середовище \newcounter{example}[section] \newenvironment{example}[1][]{\refstepcounter{example}\par\medskip \noindent \textbf{Моє~середовище~\theexample. #1} \rmfamily}{\medskip} %%Важливі слова додаються до покажчика та друкуються іншим кольором \newcommand{\important}[1] {\IfSubStr{#1}{!} {\textcolor{\wordcolour}{\textbf{\StrBefore{#1}{!}~\StrBehind{#1}{!}}}\index{#1}} {\textcolor{\wordcolour}{\textbf{#1}}\index{#1}\kern-1pt} } ``` Цей пакет визначає нове середовище `прикладу`, а також нову команду `\important`, яка друкує слова особливим кольором і додає їх до покажчика. Щоб повністю зрозуміти кожну команду, дивіться [довідковий посібник](#reference-guide) і посилання в [розділі додаткового читання](#further-reading). Нижче наведено документ, який використовує пакет *examplepackage.sty*. ```latex \documentclass{article} \usepackage[utf8]{inputenc} \usepackage[red]{examplepackage} \makeindex \title{Приклад пакета} \author{Команда Learn ShareLaTeX} \date{ } \begin{document} \maketitle \section{Вступ} У цьому документі тестується новий пакет. Цей пакет дозволяє спеціальні нумеровані середовища \begin{example} Цей текст міститься в особливому середовищі, деякий текст напівжирним шрифтом друкується на початку, а також встановлюється новий відступ. \end{example} Також є спеціальна команда для \important{важливі!слова}, яка буде надрукована особливим \important{кольором} залежно від параметра, використаного в операторі імпорту \important{пакета}. Тому що це \important{важливе}. \printindex \end{document} ``` ![WrittingPackagesEx1.png](/files/8e12d69be1bdb1eef31a0f0f07eea966136eb50a) Зверніть увагу на команду ```latex \usepackage[red]{examplepackage} ``` [Відкрити приклад написання пакета в Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ## Обробка помилок Коли йдеться про розробку нових пакетів, важливо обробляти можливі помилки, щоб повідомити користувача, що щось пішло не так. Існує чотири основні команди для повідомлення про помилки в компіляторі. * `\PackageError{*package-name*}{*error-text*}{*help-text*}`. Приймає три параметри, кожен у фігурних дужках: назву пакета, текст помилки, який буде відображено (процес компіляції буде призупинено), та довідковий текст, який буде виведено, якщо користувач натисне "h", коли компіляція зупиниться через помилку. * `\PackageWarning{*package-name*}{*warning-text*}`. У цьому випадку текст буде показано, але процес компіляції не зупиниться. Буде показано номер рядка, де виникло попередження. * `\PackageWarningNoLine{*package-name*}{*warning-text*}`. Працює так само, як попередня команда, але не покаже рядок, у якому виникло попередження. * `\PackageInfo{*package-name*}{*info-text*}`. У цьому випадку інформація у другому параметрі буде надрукована лише у файлі транскрипту, включно з номером рядка. [Відкрити приклад того, як написати пакет в Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ## Довідковий посібник **Список команд, які зазвичай використовуються в пакетах і класах** * `\newcommand{*name*}{*definition*}`. Визначає [нову команду](/latex/uk/komandi/01-commands.md#defining-a-new-command), перший параметр — це назва нової команди, а другий параметр — те, що робитиме команда. * `\renewcommand{}{}`. Те саме, що й `\newcommand` але перезаписує наявну команду. * `\providecommand{}{}`. Працює так само, як `\newcommand` але якщо команда вже визначена, цю буде мовчки проігноровано. * `\CheckCommand{}{}`. Синтаксис такий самий, як у `\newcommand`, але замість цього перевірятиме, чи існує команда і чи має очікуване визначення; LaTeX покаже попередження, якщо команда тепер не така, як `\CheckCommand` очікувалося. * `\setlength{}{}`. Встановлює довжину елемента, переданого як перший параметр, у значення, записане як другий параметр. * `\mbox{}`. Створює коробку, яка містить елементи, записані всередині фігурних дужок. * `\fbox{}`. Те саме, що й `\mbox`, але навколо вмісту фактично друкується рамка. ## Додаткове читання Для отримання додаткової інформації див. * [Розуміння пакетів і файлів класів](/latex/uk/faili-klasiv/01-understanding-packages-and-class-files.md) * [Створення власного класу](/latex/uk/faili-klasiv/04-writing-your-own-class.md) * [Команди](/latex/uk/komandi/01-commands.md) та [Середовища](/latex/uk/komandi/02-environments.md) * [Довжини в LaTeX](/latex/uk/formatuvannya/01-lengths-in-latex.md) * [Використання кольорів у LaTeX](/latex/uk/formatuvannya/13-using-colors-in-latex.md) * [Керування у великому проєкті](/latex/uk/struktura-dokumenta/07-management-in-a-large-project.md) * [LaTeX2ε для пакетів і тих, хто їх пише](http://www.latex-project.org/guides/clsguide.pdf) * [Нотатки про програмування в TeX](http://pgfplots.sourceforge.net/TeX-programming-notes.pdf) * [Хвилини замість годин: використання ресурсів LaTeX](https://tug.org/pracjourn/2005-4/hefferon/hefferon.pdf) * [The LaTeX Companion. Друге видання](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://ayakaleaf-pro.ayaka.space/latex/uk/faili-klasiv/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.