> 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/overleaf-learn-latex-pt/ficheiros-de-classe/03-writing-your-own-package.md). # Escrever o seu próprio pacote Às vezes, a melhor opção para usar os seus próprios comandos e macros num documento é escrever um novo pacote do zero. Este artigo explica a estrutura principal de um novo pacote. ## Introdução A primeira coisa a fazer antes de programar um novo pacote é determinar se realmente precisa ou não de um novo pacote. É recomendável [pesquisar no CTAN (Comprehensive TeX Archive Network)](http://www.ctan.org/ctan-portal/search/) e ver se alguém já criou algo semelhante ao que precisa. Outra coisa importante a ter em mente é [a diferença entre pacotes e classes](/latex/overleaf-learn-latex-pt/ficheiros-de-classe/01-understanding-packages-and-class-files.md). Fazer a escolha errada pode afetar a flexibilidade do produto final. ## Estrutura geral A estrutura de todos os ficheiros de pacote pode ser descrita de forma aproximada nas quatro partes seguintes: * ***Identificação***. O ficheiro declara-se como um pacote escrito com a sintaxe LaTeX2ε. * ***Declarações preliminares***. Aqui são importados os pacotes externos necessários. Além disso, nesta parte do ficheiro são codificados os comandos e as definições necessários pelas opções declaradas. * ***Opções***. O pacote declara e processa as opções. * ***Mais declarações***. O corpo principal do pacote. Quase tudo o que um pacote faz é definido aqui. Nas próximas subseções será apresentada uma descrição mais detalhada da estrutura e um exemplo funcional, *examplepackage.sty*, serão apresentados. ### Identificação Existem dois comandos simples que todos os pacotes devem ter: ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/24 Exemplo de pacote LaTeX] ``` O comando `\NeedsTeXFormat{LaTeX2e}` define a versão do LaTeX necessária para o pacote funcionar. Além disso, pode ser adicionada uma data entre chavetas para especificar a data mínima de lançamento exigida. O comando `ProvidesPackage{examplepackage}[...]` identifica este pacote como *examplepackage* e, dentro das chavetas, inclui a data de lançamento e algumas informações adicionais. A data deve estar no formato AAAA/MM/DD [Abra um exemplo de como escrever um pacote no Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Declarações preliminares A maioria dos pacotes expande e personaliza outros já existentes e também precisa de alguns pacotes externos para funcionar. Abaixo, é adicionado mais código ao pacote de exemplo "examplepackage.sty". ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Pacote de exemplo] \RequirePackage{imakeidx} \RequirePackage{xstring} \RequirePackage{xcolor} \definecolor{greycolour}{HTML}{525252} \definecolor{sharelatexcolour}{HTML}{882B21} \definecolor{mybluecolour}{HTML}{394773} \newcommand{\wordcolour}{greycolour} ``` Os comandos nesta parte ou inicializam alguns parâmetros que mais tarde serão usados para gerir as opções, ou importam ficheiros externos. O comando `\RequirePackage` é muito semelhante ao conhecido `\usepackage`, adicionar parâmetros opcionais entre chavetas também funcionará. A única diferença é que o `\usepackage` não pode ser usado antes do comando `\documentclass` . É fortemente recomendado usar `\RequirePackage` ao escrever novos pacotes ou classes. [Abra um exemplo de como escrever um pacote no Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Opções Para permitir alguma flexibilidade nos pacotes, algumas opções adicionais são muito úteis. A próxima parte do ficheiro "examplepackage.sty" trata os parâmetros passados à instrução de importação do pacote. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Pacote de exemplo] \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}{Opção desconhecida ‘\CurrentOption’}} \ProcessOptions\relax ``` Abaixo está uma descrição dos principais comandos que podem tratar as opções passadas ao pacote. O comando `\DeclareOption{}{}` trata de uma dada opção. Aceita dois parâmetros: o primeiro é o nome da opção e o segundo é o código a executar se a opção for passada. O comando `\OptionNotUsed` irá imprimir uma mensagem no compilador e nos registos, a opção não será usada. O comando `\Declareoption*{}` trata de todas as opções não definidas explicitamente. Aceita apenas um parâmetro, o código a executar quando é passada uma opção desconhecida. Neste caso, imprimirá um aviso por meio do comando seguinte: `\PackageWarning{}{}`. Veja [tratamento de erros](#handling-errors) para uma descrição do que este comando faz. `\CurrentOption` guarda o nome da opção do pacote que está a ser tratada num determinado momento. O comando `\ProcessOptions\relax` executa o código para cada opção e deve ser inserido depois de todos os comandos de tratamento de opções terem sido escritos. Existe uma versão com estrela deste comando que executará as opções na ordem exata especificada pelos comandos de chamada. No exemplo, se as opções *vermelho* ou *azul* forem passadas ao `\usepackage` comando dentro do documento, o comando `\wordcolor` é redefinido. Ambas as cores e a cor cinzenta predefinida foram definidas nas [declarações preliminares](#preliminary-declaration) após importar o *xcolor* pacote. [Abra um exemplo de como escrever um pacote no Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Mais declarações Nesta parte aparecerá a maioria dos comandos. Em "examplepackage.sty". Abaixo pode ver o ficheiro completo do pacote. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Pacote de exemplo] \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}{Opção desconhecida ‘\CurrentOption’}} \ProcessOptions\relax %%Ambiente numerado \newcounter{example}[section] \newenvironment{example}[1][]{\refstepcounter{example}\par\medskip \noindent \textbf{My~environment~\theexample. #1} \rmfamily}{\medskip} %%Palavras importantes são adicionadas ao índice e impressas em cor diferente \newcommand{\important}[1] {\IfSubStr{#1}{!} {\textcolor{\wordcolour}{\textbf{\StrBefore{#1}{!}~\StrBehind{#1}{!}}}\index{#1}} {\textcolor{\wordcolour}{\textbf{#1}}\index{#1}\kern-1pt} } ``` Este pacote define o novo ambiente `exemplo`, e um novo comando `\important`, que imprime as palavras numa cor especial e as adiciona ao índice. Para compreender plenamente cada comando, veja o [guia de referência](#reference-guide) e os links na [secção de leitura adicional](#further-reading). Abaixo, um documento que utiliza o pacote *examplepackage.sty*. ```latex \documentclass{article} \usepackage[utf8]{inputenc} \usepackage[red]{examplepackage} \makeindex \title{Exemplo de pacote} \author{Equipa Learn ShareLaTeX} \date{ } \begin{document} \maketitle \section{Introdução} Neste documento é testado um novo pacote. Este pacote permite ambientes numerados especiais ambientes \begin{example} Este texto está dentro de um ambiente especial; algum texto em negrito é impresso no início e é definida uma nova indentação. \end{example} Além disso, existe um comando especial para \important{important!words} que será impresso numa cor especial \important{cor} dependendo do parâmetro usado na declaração de importação do \important{pacote}. Porque é \important{importante}. \printindex \end{document} ``` ![WrittingPackagesEx1.png](/files/1e6ed5cbc74d1b4ac4883fce906e3685f0f2b9e1) Repare no comando ```latex \usepackage[red]{examplepackage} ``` [Abra um exemplo de como escrever um pacote no Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ## Tratamento de erros Quando se trata de desenvolver novos pacotes, é importante tratar possíveis erros para informar o utilizador de que algo correu mal. Existem quatro comandos principais para relatar erros no compilador. * `\PackageError{*package-name*}{*error-text*}{*help-text*}`. Aceita três parâmetros, cada um dentro de chavetas: o nome do pacote, o texto do erro que será apresentado (o processo de compilação será pausado) e o texto de ajuda que será impresso se o utilizador premir "h" quando a compilação parar devido ao erro. * `\PackageWarning{*package-name*}{*warning-text*}`. Neste caso, o texto é apresentado mas o processo de compilação não irá parar. Será mostrada a linha onde o aviso ocorreu. * `\PackageWarningNoLine{*package-name*}{*warning-text*}`. Funciona exatamente como o comando anterior, mas não mostrará a linha onde o aviso ocorreu. * `\PackageInfo{*package-name*}{*info-text*}`. Neste caso, a informação no segundo parâmetro será impressa apenas no ficheiro de transcrição, incluindo o número da linha. [Abra um exemplo de como escrever um pacote no Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ## Guia de referência **Lista de comandos comumente usados em pacotes e classes** * `\newcommand{*name*}{*definition*}`. Define um [novo comando](/latex/overleaf-learn-latex-pt/comandos/01-commands.md#defining-a-new-command), o primeiro parâmetro é o nome do novo comando, o segundo parâmetro é o que o comando fará. * `\renewcommand{}{}`. O mesmo que `\newcommand` mas irá sobrescrever um comando existente. * `\providecommand{}{}`. Funciona como `\newcommand` mas, se o comando já estiver definido, este será ignorado silenciosamente. * `\CheckCommand{}{}`. A sintaxe é a mesma que `\newcommand`, mas, em vez disso, verificará se o comando existe e tem a definição esperada; o LaTeX mostrará um aviso se o comando não for o que `\CheckCommand` era esperado. * `\setlength{}{}`. Define o comprimento do elemento passado como primeiro parâmetro para o valor indicado como segundo parâmetro. * `\mbox{}`. Cria uma caixa que contém os elementos escritos dentro das chavetas. * `\fbox{}`. O mesmo que `\mbox`, mas é realmente desenhada uma caixa à volta do conteúdo. ## Leitura adicional Para mais informações, veja * [Compreender pacotes e ficheiros de classe](/latex/overleaf-learn-latex-pt/ficheiros-de-classe/01-understanding-packages-and-class-files.md) * [Escrever a sua própria classe](/latex/overleaf-learn-latex-pt/ficheiros-de-classe/04-writing-your-own-class.md) * [Comandos](/latex/overleaf-learn-latex-pt/comandos/01-commands.md) e [Ambientes](/latex/overleaf-learn-latex-pt/comandos/02-environments.md) * [Comprimentos em LaTeX](/latex/overleaf-learn-latex-pt/formatacao/01-lengths-in-latex.md) * [Utilizar cores no LaTeX](/latex/overleaf-learn-latex-pt/formatacao/13-using-colors-in-latex.md) * [Gestão num grande projeto](/latex/overleaf-learn-latex-pt/estrutura-do-documento/07-management-in-a-large-project.md) * [LaTeX2ε para pacotes e autores de pacotes](http://www.latex-project.org/guides/clsguide.pdf) * [Notas sobre programação em TeX](http://pgfplots.sourceforge.net/TeX-programming-notes.pdf) * [Minutos em vez de horas: Usando recursos do LaTeX](https://tug.org/pracjourn/2005-4/hefferon/hefferon.pdf) * [O Companheiro de LaTeX. Segunda edição](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/overleaf-learn-latex-pt/ficheiros-de-classe/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.