> 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/it/file-di-classe/03-writing-your-own-package.md). # Scrivere il proprio pacchetto A volte la soluzione migliore per usare i propri comandi e macro in un documento è scrivere da zero un nuovo pacchetto. Questo articolo spiega la struttura principale di un nuovo pacchetto. ## Introduzione La prima cosa da fare prima di programmare un nuovo pacchetto è stabilire se hai davvero bisogno di un nuovo pacchetto oppure no. Si consiglia di [cercare su CTAN (Comprehensive TeX Archive Network)](http://www.ctan.org/ctan-portal/search/) e vedere se qualcuno ha già creato qualcosa di simile a ciò di cui hai bisogno. Un'altra cosa importante da tenere a mente è [la differenza tra pacchetti e classi](/latex/it/file-di-classe/01-understanding-packages-and-class-files.md). Fare la scelta sbagliata può influire sulla flessibilità del prodotto finale. ## Struttura generale La struttura di tutti i file dei pacchetti può essere descritta approssimativamente nelle quattro parti seguenti: * ***Identificazione***. Il file si dichiara come un pacchetto scritto con la sintassi LaTeX2ε. * ***Dichiarazioni preliminari***. Qui vengono importati i pacchetti esterni necessari. Inoltre, in questa parte del file vengono codificati i comandi e le definizioni necessari alle opzioni dichiarate. * ***Opzioni***. Il pacchetto dichiara ed elabora le opzioni. * ***Ulteriori dichiarazioni***. Il corpo principale del pacchetto. Quasi tutto ciò che fa un pacchetto è definito qui. Nelle sottosezioni seguenti verranno presentate una descrizione più dettagliata della struttura e un esempio funzionante, *examplepackage.sty*, saranno presentati. ### Identificazione Esistono due semplici comandi che tutti i pacchetti devono avere: ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/24 Example LaTeX package] ``` Il comando `\NeedsTeXFormat{LaTeX2e}` imposta la versione di LaTeX con cui il pacchetto deve funzionare. Inoltre, è possibile aggiungere una data tra parentesi quadre per specificare la data minima di rilascio richiesta. Il comando `ProvidesPackage{examplepackage}[...]` identifica questo pacchetto come *examplepackage* e, tra parentesi quadre, sono incluse la data di rilascio e alcune informazioni aggiuntive. La data dovrebbe essere nel formato AAAA/MM/GG [Apri un esempio di come scrivere un pacchetto in Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Dichiarazioni preliminari La maggior parte dei pacchetti estende e personalizza quelli esistenti, e ha anche bisogno di alcuni pacchetti esterni per funzionare. Di seguito vengono aggiunti altri comandi di codice al pacchetto di esempio "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} ``` I comandi in questa parte inizializzano alcuni parametri che in seguito verranno usati per gestire le opzioni, oppure importano file esterni. Il comando `\RequirePackage` è molto simile al ben noto `\usepackage`, aggiungere parametri opzionali tra parentesi quadre funzionerà anche. L'unica differenza è che il `\usepackage` non può essere usato prima del `\documentclass` comando. Si consiglia vivamente di usare `\RequirePackage` quando si scrivono nuovi pacchetti o classi. [Apri un esempio di come scrivere un pacchetto in Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Opzioni Per consentire una certa flessibilità nei pacchetti, alcune opzioni aggiuntive sono molto utili. La parte successiva del file "examplepackage.sty" gestisce i parametri passati all'istruzione di importazione del pacchetto. ```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}{Opzione sconosciuta ‘\CurrentOption’}} \ProcessOptions\relax ``` Di seguito una descrizione dei principali comandi che possono gestire le opzioni passate al pacchetto. Il comando `\DeclareOption{}{}` gestisce una data opzione. Accetta due parametri: il primo è il nome dell'opzione e il secondo è il codice da eseguire se l'opzione viene passata. Il comando `\OptionNotUsed` stamperà un messaggio nel compilatore e nei log, l'opzione non verrà usata. Il comando `\Declareoption*{}` gestisce ogni opzione non definita esplicitamente. Accetta un solo parametro, il codice da eseguire quando viene passata un'opzione sconosciuta. In questo caso stamperà un avviso tramite il comando seguente: `\PackageWarning{}{}`. Vedi [gestione degli errori](#handling-errors) per una descrizione di ciò che fa questo comando. `\CurrentOption` memorizza il nome dell'opzione del pacchetto che viene gestita in un determinato momento. Il comando `\ProcessOptions\relax` esegue il codice per ogni opzione e deve essere inserito dopo che tutti i comandi di gestione delle opzioni sono stati digitati. Esiste una versione con asterisco di questo comando che eseguirà le opzioni nell'esatto ordine specificato dai comandi chiamanti. Nell'esempio, se le opzioni *red* o *blu* vengono passate al `\usepackage` comando all'interno del documento, il comando `\wordcolor` viene ridefinito. Sia i colori sia il colore grigio predefinito sono stati definiti nelle [dichiarazioni preliminari](#preliminary-declaration) dopo aver importato il *xcolor* pacchetto. [Apri un esempio di come scrivere un pacchetto in Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### Ulteriori dichiarazioni In questa parte appariranno la maggior parte dei comandi. In "examplepackage.sty". Di seguito puoi vedere il file completo del pacchetto. ```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}{Opzione sconosciuta ‘\CurrentOption’}} \ProcessOptions\relax %%Ambiente numerato \newcounter{example}[section] \newenvironment{example}[1][]{\refstepcounter{example}\par\medskip \noindent \textbf{Il mio~ambiente~\theexample. #1} \rmfamily}{\medskip} %%Le parole importanti vengono aggiunte all'indice e stampate in un colore diverso \newcommand{\important}[1] {\IfSubStr{#1}{!} {\textcolor{\wordcolour}{\textbf{\StrBefore{#1}{!}~\StrBehind{#1}{!}}}\index{#1}} {\textcolor{\wordcolour}{\textbf{#1}}\index{#1}\kern-1pt} } ``` Questo pacchetto definisce il nuovo ambiente `esempio`, e un nuovo comando `\important`, che stampa le parole in un colore speciale e le aggiunge all'indice. Per comprendere appieno ciascun comando, consulta la [guida di riferimento](#reference-guide) e i collegamenti nella [sezione ulteriori letture](#further-reading). Di seguito, un documento che utilizza il pacchetto *examplepackage.sty*. ```latex \documentclass{article} \usepackage[utf8]{inputenc} \usepackage[red]{examplepackage} \makeindex \title{Esempio di pacchetto} \author{Team Learn ShareLaTeX} \date{ } \begin{document} \maketitle \section{Introduzione} In questo documento viene testato un nuovo pacchetto. Questo pacchetto consente ambienti numerati speciali gli ambienti \begin{example} Questo testo si trova all'interno di un ambiente speciale, viene stampato del testo in grassetto all'inizio e viene impostata una nuova indentazione. \end{example} Inoltre, esiste un comando speciale per \important{parole!importanti} che verrà stampato in un \important{colore} speciale a seconda del parametro usato nella \important{pacchetto} nell'istruzione di importazione. Perché è \important{importante}. \printindex \end{document} ``` ![WrittingPackagesEx1.png](/files/5509901e6bf00b7735310c2492640b9751d6b524) Si noti il comando ```latex \usepackage[red]{examplepackage} ``` [Apri un esempio di come scrivere un pacchetto in Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ## Gestione degli errori Quando si tratta di sviluppare nuovi pacchetti è importante gestire i possibili errori per far sapere all'utente che qualcosa è andato storto. Ci sono quattro comandi principali per segnalare errori nel compilatore. * `\PackageError{*package-name*}{*error-text*}{*help-text*}`. Accetta tre parametri, ciascuno tra parentesi graffe: il nome del pacchetto, il testo dell'errore che verrà mostrato (il processo di compilazione verrà sospeso) e il testo di aiuto che verrà stampato se l'utente preme "h" quando la compilazione si interrompe a causa dell'errore. * `\PackageWarning{*package-name*}{*warning-text*}`. In questo caso il testo viene mostrato ma il processo di compilazione non si fermerà. Verrà mostrato il numero di riga in cui si è verificato l'avviso. * `\PackageWarningNoLine{*package-name*}{*warning-text*}`. Funziona come il comando precedente, ma non mostrerà la riga in cui si è verificato l'avviso. * `\PackageInfo{*package-name*}{*info-text*}`. In questo caso le informazioni nel secondo parametro verranno stampate solo nel file di transcript, incluso il numero di riga. [Apri un esempio di come scrivere un pacchetto su Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ## Guida di riferimento **Elenco dei comandi comunemente usati nei pacchetti e nelle classi** * `\newcommand{*name*}{*definition*}`. Definisce un [nuovo comando](/latex/it/comandi/01-commands.md#defining-a-new-command), il primo parametro è il nome del nuovo comando, il secondo parametro è ciò che il comando farà. * `\renewcommand{}{}`. Come `\newcommand` ma sovrascriverà un comando esistente. * `\providecommand{}{}`. Funziona proprio come `\newcommand` ma se il comando è già definito verrà ignorato silenziosamente. * `\CheckCommand{}{}`. La sintassi è la stessa di `\newcommand`, ma invece controllerà se il comando esiste e ha la definizione prevista; LaTeX mostrerà un avviso se il comando non è quello `\CheckCommand` previsto. * `\setlength{}{}`. Imposta la lunghezza dell'elemento passato come primo parametro al valore scritto come secondo parametro. * `\mbox{}`. Crea una scatola che contiene gli elementi scritti tra le parentesi graffe. * `\fbox{}`. Come `\mbox`, ma viene effettivamente stampata una scatola attorno al contenuto. ## Approfondimenti Per maggiori informazioni vedi * [Comprendere i pacchetti e i file di classe](/latex/it/file-di-classe/01-understanding-packages-and-class-files.md) * [Scrivere la propria classe](/latex/it/file-di-classe/04-writing-your-own-class.md) * [Comandi](/latex/it/comandi/01-commands.md) e [Ambienti](/latex/it/comandi/02-environments.md) * [Lunghezze in LaTeX](/latex/it/formattazione/01-lengths-in-latex.md) * [Uso dei colori in LaTeX](/latex/it/formattazione/13-using-colors-in-latex.md) * [Gestione in un grande progetto](/latex/it/struttura-del-documento/07-management-in-a-large-project.md) * [LaTeX2ε per i pacchetti e per chi li scrive](http://www.latex-project.org/guides/clsguide.pdf) * [Note sulla programmazione in tex](http://pgfplots.sourceforge.net/TeX-programming-notes.pdf) * [Minuti invece di ore: utilizzo delle risorse LaTeX](https://tug.org/pracjourn/2005-4/hefferon/hefferon.pdf) * [The LaTeX Companion. Seconda edizione](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/it/file-di-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.