DEV DEVeloping Software Solutions n.

120 luglio-agosto 2004

Codici sorgente in documenti LaTeX

di Gianluca Pignalberi
La nostra documentazione ha bisogno di porzioni di codice sorgente, e la nostra ssazione nellusare LaTeX ci permette di farlo in maniera rapida, automatizzata, elegante e con soluzioni grache spesso vincenti.

Gianluca Pignalberi ` E laureato in Scienze dellInformazione presso ` lUniversita La Sapienza di Roma. Si occupa, per passione, di Algoritmi Genetici applicati allelaborazione delle imma` gini, ma e stato a lungo occupato, per professione, in problematiche legate allelaborazione di testi: riconoscimento della lingua, compressione, retrieval. Il tutto sempre per sistemi Unix.

pubblicato su WWW.INFOMEDIA.IT stampa digitale da Lulu Enterprises Inc. stores.lulu.com/infomedia

Infomedia
` Infomedia e limpresa editoriale che da quasi venti anni ha raccolto la voce dei programmatori, dei sistemisti, dei professionisti, degli studenti, dei ricercatori e dei professori dinformatica italiani. Sono pi` di 800 gli autori che hanno realizzato per le teu state Computer Programming, Dev, Login, Visual Basic Journal e Java Journal, molte migliaia di articoli tecnici, presentazioni di prodotti, tecnologie, protocolli, strumenti di lavoro, tecniche di sviluppo e semplici trucchi e stratagemmi. Oltre 6 milioni di copie distribuite, trentamila pagine stampate, fanno di questa impresa la pi` grande ed u inuente realt` delleditoria specializzata nel campo della a programmazione e della sistemistica. In tutti questi anni le riviste Infomedia hanno vissuto della passione di quanti vedono nella programmazione non solo la propria professione ma unattivit` vitale e un vero a divertimento. ` Nel 2009, Infomedia e cambiata radicalmente adottando ` un nuovo modello aziendale ed editoriale e si e organizzata attorno ad una idea di Impresa Sociale di Comunit` , a partecipata da programmatori e sistemisti, separando le attivit` di gestione dellinformazione gestite da un board a comunitario professionale e quelle di produzione gesti` te da una impresa strumentale. Questo assetto e in linea con le migliori esperienze internazionali e rende Infomedia ancora di pi` parte della Comunit` nazionale degli u a sviluppatori di software. ` Infomedia e media-partner di manifestazioni ed eventi in ambito informatico, collabora con molti dei pi` imporu tanti editori informatici italiani come partner editoriale e fornitore di servizi di localizzazione in italiano di testi in lingua inglese.

Limpaginazione automatica di questa rivista e realizzata al ` 100% con strumenti Open Source usando OpenOffice, Emacs, BHL, LaTeX, Gimp, Inkscape e i linguaggi Lisp, Python e BASH

For copyright information about the contents of DEV, please see the section Copyright at the end of each article if exists, otherwise ask authors. Infomedia contents is 2004 Infomedia and released as Creative Commons 2.5 BY-NC-ND. Turing Club content is 2004 Turing Club released as Creative Commons 2.5 BY-ND. Le informazioni di copyright sul contenuto di DEV sono riportate nella sezione Copyright alla ne di ciascun articolo o vanno richieste direttamente agli autori. Il contenuto Infomedia e 2004 Infomedia e rilasciato ` con Licenza Creative Commons 2.5 BY-NC-ND. Il contenuto Turing Club e 2004 Turing Club e rilasciato ` con Licenza Creative Commons 2.5 BY-ND. Si applicano tutte le norme di tutela dei marchi e dei segni distintivi. ` E in ogni caso ammessa la riproduzione parziale o totale dei testi e delle immagini per scopo didattico purch e vengano integralmente citati gli autori e la completa identicazione della testata. Manoscritti e foto originali, anche se non pubblicati, non si restituiscono. Contenuto pubblicitario inferiore al 45%. La biograa dellautore riportata nellarticolo e sul sito www.infomedia.it e di norma quella disponibi` le nella stampa dellarticolo o aggiornata a cura dellautore stesso. Per aggiornarla scrivere a info@infomedia.it o farlo in autonomia allindirizzo http://mags.programmers.net/moduli/biograa

Codici sorgente in documenti LaTeX

di

Gianluca Pignalberi > gpignalberi@infomedia.it

La nostra documentazione ha bisogno di porzioni di codice sorgente, e la nostra fissazione nellusare LaTeX ci permette di farlo in maniera rapida, automatizzata, elegante e con soluzioni grafiche spesso vincenti

rovandoci nella necessit di dover documentare i nostri programmi, avremo verosimilmente bisogno di includere porzioni di codice sorgente nei nostri manuali, libri, relazioni. Leslie Lamport, che aveva ben presente questa necessit, pens bene di dotare il suo LaTeX [3] di un ambiente in grado di formattare un testo come un codice sorgente. Pur coprendo parte delle esigenze dellutenza, questo ambiente offre funzionalit piuttosto spartane. Per ovviare a ci, altri TeX-nici (come vengono chiamati in gergo i programmatori TeX) hanno fornito dei package in grado di espandere le capacit di siffatta funzione. In questo articolo vedremo come sfruttare al meglio questi ausili.

guire, allinterno di un paragrafo, non dovremmo faticare molto: LaTeX ci fornisce il comando \verb, e il corrispondente starred. Il loro uso molto semplice, e consiste nel far seguire al comando il testo da rendere, racchiuso da un carattere delimitatore. Ad esempio
\verb+printf(const char *format, ...);+

Lambiente verbatim
Il set base di macro offerto da LaTeX comprende lambiente verbatim per inserire dei codici sorgente allinterno di un documento. La prima modalit per comporre un codice allinterno di un documento la seguente:
\begin{verbatim} <codice sorgente> \end{verbatim}

compone il testo racchiuso entro i caratteri + come visibile in Figura 1. Questo quanto: LaTeX non in grado di fare altro per trattare i nostri sorgenti. Purtroppo a noi documentatori folli (e incontentabili) questo non basta: vorremmo, ad esempio, numerare le righe dei sorgenti per riferirci ad esse pi facilmente, o includere i sorgenti senza doverli scrivere fisicamente nel documento (un po come le direttive al precompilatore del C o il comando \input di LaTeX).

Compito: pi funzionalit. Voto: D+

Per estendere le possibilit offerte dallambiente verbatim, stato implementato il package omonimo [5]. Vediamone alcune caratteristiche. Mentre lambiente originale non permette di scrivere \end {verbatim} (con lo spazio in mezzo) e deve leggere tutto il testo compreso tra \begin{verbatim} e \end{verbatim} prima di poterlo comporre (eventualmente eccedendo i limiti di memoria di TeX), il nuovo package supera questi limiti (di minore entit il primo, pi serio il secondo). Introduce per unincompatibilit: se in LaTeX base scrivessimo del testo dopo il comando \end{verbatim} e sulla stessa riga, questo verrebbe riconosciuto come testo e composto correttamente; il package verbatim invece scarterebbe questo testo, avvertendo che ogni carattere compreso tra il comando e la fine della riga stato scartato ( il prezzo da pagare per poter inserire degli spazi tra \end e {verbatim}!). Viene anche fornito lambiente comment, che fa ignorare al compilatore il testo compreso tra linizio e la fine dellambiente.
DEV > n. 120 luglio/agosto 2004

Il codice sorgente verr composto con un carattere di tipo typewriter (quindi equispaziato), allo stesso modo di come stato scritto nel sorgente del documento; i caratteri tab saranno per sostituiti con lo spazio semplice. Come molti ambienti, anche verbatim ha una versione starred. Scrivere
\begin{verbatim*} <codice sorgente> \end{verbatim*}

equivale ad ottenere il codice sorgente formattato come appena detto, ma con gli spazi evidenziati. Un esempio delle due modalit mostrato in Figura 1. In caso volessimo scrivere dei pezzi di sorgente, o evidenziare dei comandi da ese>> 94

Intermediate

FIGURA 2 FIGURA 1
Codice sorgente inserito nel documento e allinterno di un paragrafo, sia in versione normale che starred

Pezzi di codice sorgente inseriti nel documento e con le righe numerate

I due ambienti non possono essere annidati. Naturalmente, dellambiente verbatim viene fornita anche la versione starred, con la stessa caratteristica delloriginale. Pur potendo ricorrere al cut and paste, inserire dei sorgenti in un documento pu essere scomodo e tedioso. Per evitare ci c il comando \verbatiminput{<nome file>}. Questo inserisce il sorgente nel punto voluto, formattandolo propriamente. La versione starred di questo comando, come intuibile, evidenzia gli spazi. Notiamo una cosa: senza il package verbatim avremmo potuto ottenere la stessa cosa aggiungendo nel sorgente le righe di inizio e fine ambiente, usando il comando \input{<nome sorgente>}; ma a questo punto il sorgente non sarebbe pi compilabile, a meno di non averne fatto una copia. Come vediamo, anche se il nostro lavoro di documentatori stato semplificato, questo non ci basta: ad esempio, vorremmo poter contrassegnare le righe del nostro codice con dei numeri per riferirci pi velocemente ad esse, al fine di documentare determinate funzionalit. Per poter espletare questaltra funzione ricorreremo al package moreverb [1]. Questo fornisce un insieme di ambienti riconducibili a quello cosiddetto listing. Lambiente principale, per lappunto listing, si apre con la seguente sintassi:
\begin{listing}[<intervallo>]{<riga iniziale>}

mostrare in varie parti allinterno del documento, e di voler continuare la numerazione da dove lavevamo lasciata. Lambiente che per noi riprende tale numerazione listingcont. Entrambi i comandi visti hanno la versione starred (Figura 2). Purtroppo hanno il difetto di volere la hard copy del codice allinterno del documento. Per ovviare a questo inconveniente c lambiente listinginput, che non dispone della versione starred. La sintassi di inclusione :
\listinginput[<intervallo>]{<riga iniziale>}{<nome file>}

Tutti questi ambienti non sfruttano una capacit del package: non espandono i tab. Il package moreverb permette di definire la dimensione dei caratteri di tabulazione, per comporli correttamente. I due ambienti che permettono ci sono verbatimtab e verbatimtabinput. Entrambi prendono come parametro opzionale la dimensione della tabulazione; il secondo prende un ulteriore parametro, obbligatorio, che il nome del file da includere nel documento. Non dando la dimensione del tab, il package assume che sia 8 caratteri; possiamo variare in tutto il documento questo valore di default ridefinendo \verbatimtabsize come segue:
\renewcommand\verbatimtabsize{<valore>\relax}

Il parametro riga iniziale indica da quale numero si inizia a numerare le righe (numero assunto dalla prima riga), mentre il parametro opzionale intervallo indica quali righe avranno il numero scritto accanto (quelle il cui numero mod intervallo = 0). Ovviamente pu capitare di voler suddividere il sorgente da

LISTATO 1

Sorgente LaTeX che genera un documento in cui il comando di chiusura dellambiente pu essere inserito nel codice sorgente da mostrare

\documentclass[12pt]{article} \usepackage{sverb} \usepackage{multicol} \begin{document} Prima di inserire un sorgente scriviamo un po di testo, tanto per vedere dove diavolo sar\`a schiaffato il codice\ldots \begin{listing*}{<fine-lista>} \begin{listing} #include <stdio.h> main() { printf(Hello, world!\n); } \end{listing} <fine-lista> \end{document}

A detta dellautore, il comando TeX \relax fondamentale per la corretta esecuzione della composizione. Altri due ambienti sono forniti da questo package: verbatimwrite e boxedverbatim. Il primo scrive nel file di cui abbiamo fornito il nome come parametro tutto ci che c scritto nel suo corpo; il secondo ci mostra il contenuto del suo corpo circondato da un rettangolo di dimensioni corrette, e comunque migliori di come verrebbe se volessimo farlo in modo casereccio. Un altro package di notevole aiuto alla nostra funzione di documentatori sverb [6]. Parte delle sue caratteristiche sono state ricreate in altri package, ma alcune sono molto interessanti (lautore ha creato questo package per comporre dei programmi scritti in un particolare assembly). Lambiente listing compone il codice come verbatim, ma il margine sinistro sar pi interno rispetto a quello del testo

FIGURA 3

Risultato di testo verbatim cos come composto dallambiente listing* di sverb. Questo ambiente ci permette di definire la stringa che funge da terminatore dellambiente stesso

DEV > n. 120 luglio/agosto 2004

95 <<

Intermediate

FIGURA 4

Lambiente demo mostra il testo sorgente e loutput da esso risultante uno accanto allaltro

FIGURA 5

La possibilit di abbreviare il comando per il verbatim inline ci permette una sintassi compatta

(per default 1 em, cio la larghezza approssimativa del carattere M reso nel corpo considerato). Di questo ambiente esiste la versione starred, che per non funziona come gli ambienti visti finora. Allapertura dellambiente daremo un parametro, che contiene la stringa che indica la terminazione dellambiente stesso. In questo modo possiamo includere il comando di chiusura dellambiente listing allinterno del codice da comporre. Vediamo un esempio in Figura 1, che generata dal codice mostrato nel Listato 1. Tralasciamo di vedere gli ambienti per scrivere un file su disco e per leggerlo da disco per la composizione, concentrandoci sullambiente demo. Questo permette di visualizzare, uno a fianco allaltro o uno sullaltro, il testo originale e il suo output. La sintassi la seguente:
\begin{demo}[<forma>]{<titolo>}...\end{demo}

dove la forma pu essere n (narrow) o w (wide): per default la scelta narrow, che posiziona le due sezioni affiancate. Il seguente testo:
\begin{demo}{Formula} \[n! = n \cdot (n - 1)! = \prod_{i = 1}^n i\] \end{demo}

il font con cui scrivere il testo del codice (opzione fontfamily) e la sua dimensione (opzione fontsize). Abbiamo anche la possibilit di far circondare il codice da una cornice (frame) di cui possiamo specificare la posizione, lo spessore e il colore delle linee, il colore di riempimento, la dimensione dello spazio vuoto tra cornice e testo e letichetta della cornice stessa (come fatto con lambiente demo pocanzi visto, e visibile in Figura 4). Altre possibilit offerte sono: numerazione delle righe, automaticamente o arbitrariamente; scelta delle parti di codice da includere nel documento; evidenziazione degli spazi (per cui offerto il solito ambiente starred). La sola descrizione di tutte le opzioni di fancyvrb giustificherebbe la stesura di un articolo a s stante; il lettore volenteroso potr trovare in [7] tutto ci che serve sapere. Il package fvrb-ex stato scritto per incrementare la quantit di ambienti di esempio, la maggior parte dei quali devoto allinserimento di elementi grafici. Lautore ci mette in guardia sul fatto che il suo uso non garanzia di risultato su tutti i sistemi a causa della gestione dei caratteri a 8 bit di alcune versioni di TeX. La cosa pi utile la definizione degli stili di evidenziazione di codice, da cui desumiamo dei comandi speciali per colorare il codice sia nella versione bianco e nero che a colori (opzioni baw e color).

Presentazioni ancora pi belle

In [4] abbiamo visto come creare delle presentazioni animate tramite il package pdfscreen. Tra le sue opzioni ricordiamo esserci code, che fornisce i comandi per la formattazione del codice, allo stesso modo dellambiente verbatim. Le parentesi angolari saranno trattate in maniera speciale, quando vengono trattate entro lambiente verbatim. Infatti, tutto ci che verr da esse delimitato viene trattato come se fosse unopzione di un comando, e quindi formattato in modo da evidenziare questa particolarit (lo stesso effetto che desideriamo formattando regole grammaticali, a cui riserveremo un articolo a s). Se invece vogliamo inserire dei singoli caratteri di maggiore e minore, dobbiamo aggiungere un carattere di escape (raddoppiando il carattere), pena un errore in compilazione. Inserendo il seguente codice otteniamo quanto mostrato in basso in Figura 6:

genera il testo mostrato in Figura 4.

Voglio il meglio
Per aumentare le funzionalit fin qui viste sono stati scritti altri due package: fancyvrb [7] e fvrb-ex [2], scritto intorno al primo. Il package fancyvrb aggiunge al capostipite alcune funzionalit: la prima che i comandi verbatim possono essere usati nelle note a pi di pagina, cosa impossibile originariamente. Per abilitare tale funzione ricorreremo al comando
\VerbatimFootnote

Possiamo inoltre definire unabbreviazione per il verbatim inline, in sostituzione del comando \verb. Ad esempio
\DefineShortVerb{\|}

ci permette di ottenere leffetto visibile in Figura 5, cio possiamo comporre un testo verbatim con lapposito comando o con la sua abbreviazione. Il package fancyvrb ridefinisce anche lambiente verbatim, chiamandolo Verbatim. Questo ambiente ampiamente personalizzabile; tra le varie opzioni, che qui non vedremo, ci sono la definizione di un carattere per commentare delle porzioni di testo; lopzione in questione commentchar. Ovviamente leffetto di commentare una riga di testo del codice quello di non far comporre la riga in oggetto, e quindi non farla comparire nel codice accluso al documento finale. Possiamo anche eseguire un comando prima della formattazione del testo verbatim (opzione formatcom) o scegliere
>> 96

FIGURA 6

Testo e codice formattati quando si usa il package pdfscreen

DEV > n. 120 luglio/agosto 2004

Intermediate

\begin{verbatim} \usepackage[<options>]{<package>} #include <<stdio.h>> \end{verbatim}

Bibliografia
[1] R. Fairbairns, The moreverb package, www.ctan.org, 1997. [2] D. Girou, The fvrb-ex package, www.ctan.org, 1998. [3] L. Lamport, LaTeX: A Document Preparation System, Addison Wesley, Reading, MA., 2a edizione, 1994. [4] G. Pignalberi, Presentazioni e manuali integrati con pdfLaTeX, Dev, n. 117, Gruppo Editoriale Infomedia, Apr. 2004. [5] R. Schpf, B. Raichle, and C. Rowley, A New Implementation of LaTeXs verbatim and verbatim* Environments, www.ctan.org, 2001. [6] M. Wooding, The sverb package, www.ctan.org, 1996. [7] T. Van Zandt, The fancyvrb package, www.ctan.org, 1998.

Nel package in oggetto stato definito lambiente decl, che visualizza il testo racchiudendolo in un riquadro. Siccome il testo al suo interno non trattato come un codice, dobbiamo usare alcuni accorgimenti (ad esempio circondare i comandi con |), ma potremo trattare molto facilmente i parametri di funzioni, grazie a due comandi introdotti appositamente: \arg e \oarg. Il seguente codice genera il testo visibile in alto in Figura 6:
\begin{decl} |\usepackage|\oarg{options}\arg{package} \end{decl}

Gianluca Pignalberi

Conclusioni
Le possibilit che LaTeX offre di base per inserire del codice, formattandolo come un sorgente, non sono moltissime. Lopera di scrittura di package in TeX ha fatto s che queste possibilit fossero aumentate grandemente. Nel corso del presente articolo abbiamo visto alcuni di questi package (senzaltro i pi diffusi) e buona parte delle loro capacit. I lettori interessati potranno partire da qui per rendere i propri documenti visivamente professionali e coerenti. Maggiori competenze potranno essere acquisite riferendosi sempre ai manuali di ogni package, ed eventualmente prendendo dai siti appropriati altri strumenti adatti ai propri scopi.

laureato in Scienze dellInformazione presso lUniversit La Sapienza di Roma. Si occupa, per passione, di Algoritmi Genetici applicati allelaborazione delle immagini, ma stato a lungo occupato, per professione, in problematiche legate allelaborazione di testi: riconoscimento della lingua, compressione, retrieval. Il tutto sempre per sistemi Unix.

Download del progetto

Scarica il progetto completo di questo articolo allindirizzo: ftp://ftp.infomedia.it/pub/DEV./Listati/Dev118/ls-latex.zip