> 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/es/archivos-de-clase/03-writing-your-own-package.md). # Escribir su propio paquete A veces, la mejor opción para usar tus propios comandos y macros en un documento es escribir un paquete nuevo desde cero. Este artículo explica la estructura principal de un paquete nuevo. ## Introducción Lo primero que hay que hacer antes de codificar un paquete nuevo es determinar si realmente necesitas un paquete nuevo o no. Se recomienda [buscar en CTAN (Comprehensive TeX Archive Network)](http://www.ctan.org/ctan-portal/search/) y ver si alguien ya ha creado algo similar a lo que necesitas. Otra cosa importante que tener en cuenta es [la diferencia entre paquetes y clases](/latex/es/archivos-de-clase/01-understanding-packages-and-class-files.md). Elegir mal puede afectar la flexibilidad del producto final. ## Estructura general La estructura de todos los archivos de paquete puede describirse aproximadamente en las cuatro partes siguientes: * ***Identificación***. El archivo se declara como un paquete escrito con la sintaxis LaTeX2ε. * ***Declaraciones preliminares***. Aquí se importan los paquetes externos necesarios. Además, en esta parte del archivo se codifican los comandos y definiciones necesarios para las opciones declaradas. * ***Opciones***. El paquete declara y procesa las opciones. * ***Más declaraciones***. El cuerpo principal del paquete. Casi todo lo que hace un paquete se define aquí. En las siguientes subsecciones se presentará una descripción más detallada de la estructura y un ejemplo funcional, *examplepackage.sty*, se presentarán. ### Identificación Hay dos comandos sencillos que todos los paquetes deben tener: ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/24 Paquete de LaTeX de ejemplo] ``` El comando `\NeedsTeXFormat{LaTeX2e}` establece la versión de LaTeX con la que funcionará el paquete. Además, se puede añadir una fecha entre corchetes para especificar la fecha mínima de lanzamiento requerida. El comando `ProvidesPackage{examplepackage}[...]` identifica este paquete como *examplepackage* y, dentro de los corchetes, se incluye la fecha de lanzamiento y alguna información adicional. La fecha debe estar en el formato AAAA/MM/DD [Abra un ejemplo de cómo escribir un paquete en Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Declaraciones preliminares La mayoría de los paquetes amplían y personalizan otros existentes, y también necesitan algunos paquetes externos para funcionar. A continuación, se añade más código al paquete de ejemplo "examplepackage.sty". ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Paquete de ejemplo] \RequirePackage{imakeidx} \RequirePackage{xstring} \RequirePackage{xcolor} \definecolor{greycolour}{HTML}{525252} \definecolor{sharelatexcolour}{HTML}{882B21} \definecolor{mybluecolour}{HTML}{394773} \newcommand{\wordcolour}{greycolour} ``` Los comandos de esta parte inicializan algunos parámetros que luego se usarán para gestionar las opciones, o bien importan archivos externos. El comando `\RequirePackage` es muy similar al conocido `\usepackage`, añadir parámetros opcionales entre corchetes también funcionará. La única diferencia es que el `\usepackage` no puede usarse antes del `\documentclass` comando. Se recomienda encarecidamente usar `\RequirePackage` al escribir paquetes o clases nuevos. [Abra un ejemplo de cómo escribir un paquete en Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Opciones Para permitir cierta flexibilidad en los paquetes, algunas opciones adicionales son muy útiles. La siguiente parte del archivo "examplepackage.sty" maneja los parámetros pasados a la instrucción de importación del paquete. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Paquete de ejemplo] \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}{Opción desconocida ‘\CurrentOption’}} \ProcessOptions\relax ``` A continuación se describe los comandos principales que pueden gestionar las opciones pasadas al paquete. El comando `\DeclareOption{}{}` gestiona una opción dada. Toma dos parámetros: el primero es el nombre de la opción y el segundo es el código que se ejecutará si se pasa la opción. El comando `\OptionNotUsed` mostrará un mensaje en el compilador y en los registros; la opción no se utilizará. El comando `\Declareoption*{}` gestiona toda opción no definida explícitamente. Toma solo un parámetro, el código que se ejecutará cuando se pase una opción desconocida. En este caso mostrará una advertencia mediante el siguiente comando: `\PackageWarning{}{}`. Véase [gestión de errores](#handling-errors) para una descripción de lo que hace este comando. `\CurrentOption` almacena el nombre de la opción del paquete que se está gestionando en un momento determinado. El comando `\ProcessOptions\relax` ejecuta el código para cada opción y debe insertarse después de haber escrito todos los comandos de gestión de opciones. Existe una versión con asterisco de este comando que ejecutará las opciones en el orden exacto especificado por los comandos que lo invocan. En el ejemplo, si las opciones *red* o *blue* se pasan al `\usepackage` comando dentro del documento, el comando `\wordcolor` se redefine. Ambos colores y el color gris predeterminado se definieron en las [declaraciones preliminares](#preliminary-declaration) después de importar el *xcolor* paquete. [Abra un ejemplo de cómo escribir un paquete en Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Más declaraciones En esta parte aparecerá la mayoría de los comandos. En "examplepackage.sty". A continuación puedes ver el archivo completo del paquete. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Paquete de ejemplo] \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}{Opción desconocida ‘\CurrentOption’}} \ProcessOptions\relax %%Entorno numerado \newcounter{example}[section] \newenvironment{example}[1][]{\refstepcounter{example}\par\medskip \noindent \textbf{My~environment~\theexample. #1} \rmfamily}{\medskip} %%Las palabras importantes se añaden al índice y se imprimen en un color diferente \newcommand{\important}[1] {\IfSubStr{#1}{!} {\textcolor{\wordcolour}{\textbf{\StrBefore{#1}{!}~\StrBehind{#1}{!}}}\index{#1}} {\textcolor{\wordcolour}{\textbf{#1}}\index{#1}\kern-1pt} } ``` Este paquete define el nuevo entorno `ejemplo`, y un nuevo comando `\important`, que imprime las palabras en un color especial y las añade al índice. Para comprender completamente cada comando, consulta el [guía de referencia](#reference-guide) y los enlaces en la [sección de lectura adicional](#further-reading). A continuación, un documento que utiliza el paquete *examplepackage.sty*. ```latex \documentclass{article} \usepackage[utf8]{inputenc} \usepackage[red]{examplepackage} \makeindex \title{Ejemplo de paquete} \author{Equipo Learn ShareLaTeX} \date{ } \begin{document} \maketitle \section{Introducción} En este documento se prueba un nuevo paquete. Este paquete permite entornos numerados especiales entornos \begin{example} Este texto está dentro de un entorno especial, se imprime texto en negrita al principio y se establece una nueva sangría. \end{example} Además, hay un comando especial para \important{important!words} que será impreso en un \important{color} especial según el parámetro usado en la importación de \important{paquete}. Porque es \important{importante}. \printindex \end{document} ``` ![WrittingPackagesEx1.png](/files/e5f4b95a9d6aa1baaec8e9e20be8a975e72be99c) Observe el comando ```latex \usepackage[red]{examplepackage} ``` [Abra un ejemplo de cómo escribir un paquete en Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ## Gestión de errores Cuando se trata de desarrollar nuevos paquetes, es importante gestionar los posibles errores para hacer saber al usuario que algo salió mal. Hay cuatro comandos principales para informar de errores en el compilador. * `\PackageError{*package-name*}{*error-text*}{*help-text*}`. Toma tres parámetros, cada uno entre llaves: el nombre del paquete, el texto del error que se mostrará (se pausará el proceso de compilación) y el texto de ayuda que se imprimirá si el usuario pulsa "h" cuando la compilación se detenga debido al error. * `\PackageWarning{*package-name*}{*warning-text*}`. En este caso el texto se muestra pero el proceso de compilación no se detendrá. Mostrará el número de línea donde ocurrió la advertencia. * `\PackageWarningNoLine{*package-name*}{*warning-text*}`. Funciona igual que el comando anterior, pero no mostrará la línea donde ocurrió la advertencia. * `\PackageInfo{*package-name*}{*info-text*}`. En este caso la información del segundo parámetro solo se imprimirá en el archivo de transcripción, incluido el número de línea. [Abra un ejemplo de cómo escribir un paquete en Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ## Guía de referencia **Lista de comandos comúnmente usados en paquetes y clases** * `\newcommand{*name*}{*definition*}`. Define un [nuevo comando](/latex/es/comandos/01-commands.md#defining-a-new-command), el primer parámetro es el nombre del nuevo comando y el segundo parámetro es lo que hará el comando. * `\renewcommand{}{}`. Igual que `\newcommand` pero sobrescribirá un comando existente. * `\providecommand{}{}`. Funciona igual que `\newcommand` pero si el comando ya está definido, este se ignorará sin mostrar ningún mensaje. * `\CheckCommand{}{}`. La sintaxis es la misma que `\newcommand`, pero, en su lugar, comprobará si el comando existe y tiene la definición esperada; LaTeX mostrará una advertencia si el comando no es lo que `\CheckCommand` se esperaba. * `\setlength{}{}`. Establece la longitud del elemento pasado como primer parámetro al valor escrito como segundo parámetro. * `\mbox{}`. Crea una caja que contiene los elementos escritos dentro de las llaves. * `\fbox{}`. Igual que `\mbox`, pero en realidad se imprime una caja alrededor del contenido. ## Lectura adicional Para más información, consulta * [Entender los paquetes y los archivos de clase](/latex/es/archivos-de-clase/01-understanding-packages-and-class-files.md) * [Escribir su propia clase](/latex/es/archivos-de-clase/04-writing-your-own-class.md) * [Comandos](/latex/es/comandos/01-commands.md) y [Entornos](/latex/es/comandos/02-environments.md) * [Longitudes en LaTeX](/latex/es/formato/01-lengths-in-latex.md) * [Uso de colores en LaTeX](/latex/es/formato/13-using-colors-in-latex.md) * [Gestión en un proyecto grande](/latex/es/estructura-del-documento/07-management-in-a-large-project.md) * [LaTeX2ε para paquetes y autores de paquetes](http://www.latex-project.org/guides/clsguide.pdf) * [Notas sobre programación en TeX](http://pgfplots.sourceforge.net/TeX-programming-notes.pdf) * [Minutos en menos de horas: Uso de recursos de LaTeX](https://tug.org/pracjourn/2005-4/hefferon/hefferon.pdf) * [La compañera de LaTeX. Segunda edició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/es/archivos-de-clase/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.