> 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/04-writing-your-own-class.md). # Scrivere la propria classe A volte l'opzione migliore per personalizzare un documento è scrivere da zero una nuova classe. Questo articolo spiega la struttura principale e i comandi necessari in una nuova classe. ## Introduzione La prima cosa da fare prima di programmare una nuova classe è stabilire se ti serve davvero una nuova classe 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 alla classe di documento 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 di classe può essere descritta in modo approssimativo nelle quattro parti seguenti: * ***Identificazione***. Il file si dichiara come una classe scritta con la sintassi LaTeX2ε. * ***Dichiarazioni preliminari***. Qui vengono importati i pacchetti e le classi esterne necessari. Inoltre, in questa parte del file vengono codificati i comandi e le definizioni richiesti dalle opzioni dichiarate. * ***Opzioni***. La classe dichiara ed elabora le opzioni. * ***Ulteriori dichiarazioni***. Il corpo principale della classe. Qui è definita quasi tutto ciò che fa una classe. Nelle sottosezioni seguenti verranno presentate una descrizione più dettagliata della struttura e un esempio funzionante, *exampleclass.cls*, saranno presentati. ### Identificazione Ci sono due semplici comandi che tutte le classi devono avere: ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesClass{exampleclass}[2014/08/16 Example LaTeX class] ``` Il comando `\NeedsTeXFormat{LaTeX2e}` imposta la versione di LaTeX necessaria per il funzionamento della classe. Inoltre, è possibile aggiungere una data tra parentesi quadre per specificare la data minima di rilascio richiesta. Il comando `ProvidesClass{exampleclass}[...]` identifica questa classe come *exampleclass* 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 una classe in Overleaf](https://www.overleaf.com/project/new/template/19419?id=65524436\&templateName=An+example+of+writing+a+LaTeX+class\&latexEngine=\&texImage=texlive-full%3A2020.1\&mainFile=) ### Dichiarazioni preliminari La maggior parte delle classi estende e personalizza quelle esistenti, e inoltre ha bisogno di alcuni pacchetti esterni per funzionare. Qui sotto, viene aggiunto altro codice alla classe di esempio `exampleclass.cls`. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesClass{exampleclass}[2014/08/16 Example LaTeX class] \newcommand{\headlinecolor}{\normalcolor} \LoadClass[twocolumn]{article} \RequirePackage{xcolor} \definecolor{slcolor}{HTML}{882B21} ``` I comandi in questa parte inizializzano alcuni parametri che in seguito verranno usati per gestire le opzioni, oppure importano file esterni. Il comando `\LoadClass[twocolumn]{article}` carica la classe `article` con il parametro aggiuntivo `twocolumn`. Di conseguenza, tutti i comandi della `article` classe standard saranno automaticamente disponibili nella **esempio** classe, con l'eccezione che il documento verrà stampato in formato a due colonne. `\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 nuove classi o pacchetti. [Apri un esempio di come scrivere una classe in Overleaf](https://www.overleaf.com/project/new/template/19419?id=65524436\&templateName=An+example+of+writing+a+LaTeX+class\&latexEngine=\&texImage=texlive-full%3A2020.1\&mainFile=) ### Opzioni Per consentire una certa flessibilità nelle classi, alcune opzioni aggiuntive sono molto utili. La parte successiva del file `exampleclass.cls` gestisce i parametri passati al comando della classe di documento. Abbiamo anche spostato `\LoadClass` su *dopo* le opzioni vengono elaborate, in modo che le opzioni impostate nel file .tex possano essere passate alla classe di base. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesClass{exampleclass}[2014/08/16 Example LaTeX class] \newcommand{\headlinecolor}{\normalcolor} \RequirePackage{xcolor} \definecolor{slcolor}{HTML}{882B21} \DeclareOption{onecolumn}{\OptionNotUsed} \DeclareOption{green}{\renewcommand{\headlinecolor}{\color{green}}} \DeclareOption{red}{\renewcommand{\headlinecolor}{\color{slcolor}}} \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} \ProcessOptions\relax \LoadClass[twocolumn]{article} ``` Qui ci sono quattro comandi principali che gestiscono le opzioni passate alla classe. 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à utilizzata. In questo caso il documento è impostato su due colonne e, se l'utente prova a cambiarlo in una colonna, non funzionerà: l'opzione verrà ignorata. 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 eseguirà il comando successivo: `\PassOptionsToClass{}{}`. Passa l'opzione contenuta nel primo paio di parentesi graffe alla classe di documento specificata nel secondo paio di parentesi graffe. Nell'esempio, tutte le opzioni sconosciute verranno passate alla **article** classe di documento. `\CurrentOption` memorizza il nome dell'opzione di classe 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 `green` vengono passati al documento il carattere usato per il titolo e le sezioni saranno impostati nel colore corrispondente. Il colore chiamato `slcolor` è stato definito in [dichiarazioni preliminari](#preliminary-declaration) dopo aver importato il `xcolor` pacchetto. [Apri un esempio di come scrivere una classe in Overleaf](https://www.overleaf.com/project/new/template/19419?id=65524436\&templateName=An+example+of+writing+a+LaTeX+class\&latexEngine=\&texImage=texlive-full%3A2020.1\&mainFile=) ### Ulteriori dichiarazioni In questa parte appariranno la maggior parte dei comandi. In "exampleclass.cls" vengono impostate le dimensioni della pagina e le dimensioni del carattere per il titolo, il corpo e le sezioni. Qui sotto puoi vedere l'intero file della classe. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesClass{exampleclass}[2014/08/16 Example LaTeX class] \newcommand{\headlinecolor}{\normalcolor} \RequirePackage{xcolor} \definecolor{slcolor}{HTML}{882B21} \DeclareOption{onecolumn}{\OptionNotUsed} \DeclareOption{green}{\renewcommand{\headlinecolor}{\color{green}}} \DeclareOption{red}{\renewcommand{\headlinecolor}{\color{slcolor}}} \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} \ProcessOptions\relax \LoadClass[twocolumn]{article} \renewcommand{\maketitle}{% \twocolumn[% \fontsize{50}{60}\fontfamily{phv}\fontseries{b}% \fontshape{sl}\selectfont\headlinecolor \@title \medskip ]% } \renewcommand{\section}{% \@startsection {section}{1}{0pt}{-1.5ex plus -1ex minus -.2ex}% {1ex plus .2ex}{\large\sffamily\slshape\headlinecolor}% } \renewcommand{\normalsize}{\fontsize{9}{10}\selectfont} \setlength{\textwidth}{17.5cm} \setlength{\textheight}{22cm} \setcounter{secnumdepth}{0} ``` Per comprendere il resto dei comandi, vedi il [guida di riferimento](#reference-guide) e i collegamenti nella [sezione ulteriori letture](#further-reading). Gli ultimi quattro comandi dell'esempio mostrano le quattro cose che tutte le classi devono contenere: * La definizione di `normalsize`. Imposta il valore predefinito di [dimensione del font](/latex/it/caratteri/01-font-sizes-families-and-styles.md). * Un valore predefinito per [`textwidth`](/latex/it/formattazione/07-page-size-and-margins.md) * Un valore predefinito per [`textheight`](/latex/it/formattazione/07-page-size-and-margins.md) * Le specifiche per la [numerazione delle pagine](/latex/it/formattazione/03-page-numbering.md). Qui sotto, un documento che usa la classe *exampleclass.cls*. ```latex \documentclass[red]{exampleclass} \usepackage[utf8]{inputenc} \usepackage[english]{babel} \usepackage{blindtext} \title{Esempio per mostrare come funzionano le classi} \author{Team Learn ShareLaTeX} \date{Agosto 2014} \begin{document} \maketitle \noindent Iniziamo qui con un semplice esempio funzionante. \blindtext \section{Introduzione} Il problema di Monty Hall... \section{La stessa cosa} Il Monty... ``` ![WrittingClassesEx1.png](/files/52d90d41c4dad1011e93dc6c5425d3e0dec8b3bc) Nota che il primo comando qui è ```latex \documentclass[red]{exampleclass} ``` [Apri un esempio di come scrivere una classe in Overleaf](https://www.overleaf.com/project/new/template/19419?id=65524436\&templateName=An+example+of+writing+a+LaTeX+class\&latexEngine=\&texImage=texlive-full%3A2020.1\&mainFile=) ## Gestione degli errori Quando si tratta di sviluppare nuove classi, è importante gestire i possibili errori per far sapere all'utente che qualcosa è andato storto. Ci sono quattro comandi principali per segnalare gli errori nel compilatore. * `\ClassError{*class-name*}{*error-text*}{*help-text*}`. Accetta tre parametri, ciascuno tra parentesi graffe: il nome della classe, il testo dell'errore che verrà visualizzato (il processo di compilazione verrà messo in pausa) e il testo di aiuto che verrà stampato se l'utente preme "h" quando la compilazione si interrompe a causa dell'errore. * `\ClassWarning{*class-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. * `\ClassWarningNoLine{*class-name*}{*warning-text*}`. Funziona come il comando precedente, ma non mostrerà la riga in cui si è verificato l'avviso. * `\ClassInfo{*class 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 una classe in Overleaf](https://www.overleaf.com/project/new/template/19419?id=65524436\&templateName=An+example+of+writing+a+LaTeX+class\&latexEngine=\&texImage=texlive-full%3A2020.1\&mainFile=) ## Guida di riferimento **Elenco dei comandi comunemente usati nelle classi e nei pacchetti** * `\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 verificherà se il comando esiste e ha la definizione prevista; LaTeX mostrerà un avviso se il comando non è quello che `\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 il proprio pacchetto](/latex/it/file-di-classe/03-writing-your-own-package.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 autori di classi e pacchetti](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/04-writing-your-own-class.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.