> 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/class-files/03-writing-your-own-package.md). # Writing your own package Sometimes the best option to use your own commands and macros in a document is to write a new package from scratch. This article explains the main structure of a new package. ## Introduction The first thing to do before coding a new package is to determine whether you really need a new package or not. It's recommended to [search on CTAN (Comprehensive TeX Archive Network)](http://www.ctan.org/ctan-portal/search/) and see if someone already created something similar to what you need. Another important thing to have in mind is [the difference between packages and classes](/latex/class-files/01-understanding-packages-and-class-files.md). Making the wrong choice can affect the flexibility of the final product. ## General structure The structure of all package files can be roughly described in the next four parts: * ***Identification***. The file declares itself as a package written with the LaTeX2ε syntax. * ***Preliminary declarations***. Here the external packages needed are imported. Also, in this part of the file the commands and definitions needed by the declared options are coded. * ***Options***. The package declares and processes the options. * ***More declarations***. The main body of the package. Almost everything a package does is defined here. In the next subsections a more detailed description of the structure and a working example, *examplepackage.sty*, will be presented. ### Identification There are two simple commands that all packages must have: ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/24 Example LaTeX package] ``` The command `\NeedsTeXFormat{LaTeX2e}` sets the LaTeX version for the package to work. Additionally, a date can be added within brackets to specify the minimal release date required. The command `ProvidesPackage{examplepackage}[...]` identifies this package as *examplepackage* and, inside the brackets, the release date and some additional information is included. The date should be in the form YYYY/MM/DD [Open an example of how to write a package in Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Preliminary declarations Most of the packages extend and customize existing ones, and also need some external packages to work. Below, some more code is added to the sample package "examplepackage.sty". ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Example package] \RequirePackage{imakeidx} \RequirePackage{xstring} \RequirePackage{xcolor} \definecolor{greycolour}{HTML}{525252} \definecolor{sharelatexcolour}{HTML}{882B21} \definecolor{mybluecolour}{HTML}{394773} \newcommand{\wordcolour}{greycolour} ``` The commands in this part either initialize some parameters that latter will be used to manage the options, or import external files. The command `\RequirePackage` is very similar to the well-known `\usepackage`, adding optional parameters within brackets will also work. The only difference is that the `\usepackage` can not be used before `\documentclass` command. It's strongly recommended to use `\RequirePackage` when writing new packages or classes. [Open an example of how to write a package in Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Options To allow some flexibility in the packages a few additional options are very useful. The next part in the file "examplepackage.sty" handles the parameters passed to the package-importing statement. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Example package] \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}{Unknown ‘\CurrentOption’}} \ProcessOptions\relax ``` Below a description of the main commands that can handle the options passed to the package. The command `\DeclareOption{}{}` handles a given option. It takes two parameters, the first one is the name of the option and the second one is the code to execute if the option is passed. The command `\OptionNotUsed` will print a message in the compiler and the logs, the option won't be used. The command `\Declareoption*{}` handles every option not explicitly defined. It takes only one parameter, the code to execute when an unknown option is passed. In this case it will print a warning by means of the next command: `\PackageWarning{}{}`. See [handling errors](#handling-errors) for a description about what this command does. `\CurrentOption` stores the name of the package option being handled at a determined moment. The command `\ProcessOptions\relax` executes the code fore each option and must be inserted after all the option-handling commands were typed. There's a starred version of this command that will execute the options in the exact order specified by the calling commands. In the example, if the options *red* or *blue* are passed to the `\usepackage` command within the document, the command `\wordcolor` is redefined. Both colours and the default grey colour were defined in the [preliminary declarations](#preliminary-declaration) after importing the *xcolor* package. [Open an example of how to write a package in Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### More declarations In this part most of the commands will appear. In "examplepackage.sty". Below you can see the full package file. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Example package] \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}{Unknown ‘\CurrentOption’}} \ProcessOptions\relax %%Numbered environment \newcounter{example}[section] \newenvironment{example}[1][]{\refstepcounter{example}\par\medskip \noindent \textbf{My~environment~\theexample. #1} \rmfamily}{\medskip} %%Important words are added to the index and printed in different colour \newcommand{\important}[1] {\IfSubStr{#1}{!} {\textcolor{\wordcolour}{\textbf{\StrBefore{#1}{!}~\StrBehind{#1}{!}}}\index{#1}} {\textcolor{\wordcolour}{\textbf{#1}}\index{#1}\kern-1pt} } ``` This package defines the new environment `example`, and a new command `\important`, that prints the words in a special colour and adds them to the index. To fully understand each command see the [reference guide](#reference-guide) and the links in the [further reading section](#further-reading). Below, a document that uses the package *examplepackage.sty*. ```latex \documentclass{article} \usepackage[utf8]{inputenc} \usepackage[red]{examplepackage} \makeindex \title{Package Example} \author{Team Learn ShareLaTeX} \date{ } \begin{document} \maketitle \section{Introduction} In this document a new package is tested. This package allows special numbered environments \begin{example} This text is inside a special environment, some boldface text is printed at the beginning and a new indentation is set. \end{example} Also, there's a special command for \important{important!words} that will be printed in a special \important{colour} depending on the parameter used in the \important{package} importation statement. Because it's \important{important}. \printindex \end{document} ``` ![WrittingPackagesEx1.png](/files/4Y4vgqE1AztDQN5XMWHs) Notice the command ```latex \usepackage[red]{examplepackage} ``` [Open an example of how to write a package in Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ## Handling errors When it comes to develop new packages it's important to handle possible errors to let know the user that something went wrong. There are four main commands to report errors in the compiler. * `\PackageError{*package-name*}{*error-text*}{*help-text*}`. Takes three parameters, each one inside braces: the package name, the error text which is going to be displayed (the compilation process will be paused), and the help text that will be printed if the user press "h" when the compilation pauses because of the error. * `\PackageWarning{*package-name*}{*warning-text*}`. In this case the text is displayed but the compilation process won't stop. It will show the line number where the warning occurred. * `\PackageWarningNoLine{*package-name*}{*warning-text*}`. Works just like the previous command, but it won't show the line where the warning occurred. * `\PackageInfo{*package-name*}{*info-text*}`. In this case the information in the second parameter will only be printed in the transcript file, including the line number. [Open an example of how to write a package Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ## Reference guide **List of commands commonly used in packages and classes** * `\newcommand{*name*}{*definition*}`. Defines a [new command](/latex/commands/01-commands.md#defining-a-new-command), the first parameter is the name of the new command, the second parameter is what the command will do. * `\renewcommand{}{}`. The same as `\newcommand` but will overite an existing command. * `\providecommand{}{}`. Works just as `\newcommand` but if the command is already defined this one will be silently ignored. * `\CheckCommand{}{}`. The syntax is the same as `\newcommand`, but instead it will check whether the command exists and has the expected definition, LaTeX will show a warning if the command is now what `\CheckCommand` expected. * `\setlength{}{}`. Sets the length of the element passed as first parameter to the value written as second parameter. * `\mbox{}`. Creates a box that contains the elements written inside the braces. * `\fbox{}`. The same as `\mbox`, but a box is actually printed around the contents. ## Further reading For more information see * [Understanding packages and class files](/latex/class-files/01-understanding-packages-and-class-files.md) * [Writing your own class](/latex/class-files/04-writing-your-own-class.md) * [Commands](/latex/commands/01-commands.md) and [Environments](/latex/commands/02-environments.md) * [Lengths in LaTeX](/latex/formatting/01-lengths-in-latex.md) * [Using colours in LaTeX](/latex/formatting/13-using-colors-in-latex.md) * [Management in a large project](/latex/document-structure/07-management-in-a-large-project.md) * [LaTeX2ε for package and package writers](http://www.latex-project.org/guides/clsguide.pdf) * [Notes on programming in tex](http://pgfplots.sourceforge.net/TeX-programming-notes.pdf) * [Minutes in less than hours: Using LaTeX Resources](https://tug.org/pracjourn/2005-4/hefferon/hefferon.pdf) * [The LaTeX Companion. Second edition](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/class-files/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.